# Ai Canvas

> AI-Native Design Tool - TypeScript monorepo with MCP integration for AI assistants

- **Type:** MCP server
- **Install:** `agentstack add mcp-laoluojuhai-ai-canvas`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [laoluojuhai](https://agentstack.voostack.com/s/laoluojuhai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [laoluojuhai](https://github.com/laoluojuhai)
- **Source:** https://github.com/laoluojuhai/ai-canvas

## Install

```sh
agentstack add mcp-laoluojuhai-ai-canvas
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AI-Canvas

[](https://github.com/laoluojuhai/ai-canvas/actions/workflows/ci.yml)
[](https://github.com/laoluojuhai/ai-canvas/actions/workflows/docker-publish.yml)
[](./LICENSE)

AI-native design system and UI tooling for semantic, type-safe, reversible design documents.

AI-Canvas combines a document model, renderer, code generators, and an MCP server so AI assistants can inspect, modify, export, and validate design work inside one TypeScript monorepo.

## Quick Start

```bash
# Enable pnpm from Corepack if pnpm is not already on your PATH
corepack enable

# Install dependencies
corepack pnpm install

# Start development
corepack pnpm dev

# Run tests
corepack pnpm test

# Build all packages
corepack pnpm build

# Type check
corepack pnpm typecheck
```

## Documentation

- [CONTRIBUTING.md](./CONTRIBUTING.md) - contribution workflow and PR expectations
- [CHANGELOG.md](./CHANGELOG.md) - notable unreleased and released changes
- [CLAUDE.md](./CLAUDE.md) - detailed development workflow and architecture notes
- [Gemini.md](./Gemini.md) - Gemini-oriented development guide aligned with CLAUDE.md
- [TASKS.md](./TASKS.md) - roadmap, milestones, and status tracking
- [docs/product-design-strategy.md](./docs/product-design-strategy.md) - product strategy and expansion plan
- [packages/core/README.md](./packages/core/README.md) - core engine package guide
- [packages/renderer/README.md](./packages/renderer/README.md) - renderer package guide
- [packages/mcp-server/README.md](./packages/mcp-server/README.md) - MCP server package guide
- [packages/codegen/README.md](./packages/codegen/README.md) - code generation package guide
- [packages/vscode-extension/README.md](./packages/vscode-extension/README.md) - VSCode editor package guide

## Architecture

```text
packages/
├── core/              # @ai-canvas/core - Document model, operations, history, tokens (PenDocument dual mode)
├── mcp-server/        # @ai-canvas/mcp-server - 47 MCP tools (stdio + SSE transport)
├── renderer/          # @ai-canvas/renderer - IRenderBackend abstraction (Canvas2D + CanvasKit)
├── codegen/           # @ai-canvas/codegen - React/Vue/HTML/Tailwind generation
├── web-app/           # @ai-canvas/web-app - Standalone web app (React + multi-AI proxy)
└── vscode-extension/  # @ai-canvas/vscode-extension - Visual editor in VSCode
```

## Core Concepts

### Document Model

```text
Document > Pages > Nodes
```

- **Document**: Metadata, design tokens, reusable components, pages, history
- **Page**: Root canvas surface containing the node tree
- **Node**: A typed design element categorized by `primitive` and optionally `semantic`

### Node Primitives

AI-Canvas currently supports 13 primitive node types:

| Primitive | Description |
|-----------|-------------|
| `frame` | Container with layout capabilities |
| `rectangle` | Basic rectangular shape |
| `ellipse` | Circle or ellipse shape |
| `line` | Straight line segment |
| `polygon` | Regular polygon shape |
| `path` | Arbitrary vector path |
| `text` | Text content |
| `image` | Bitmap or image asset |
| `star` | Star shape |
| `arrow` | Arrow shape with direction |
| `connector` | Connection line between nodes |
| `video` | Video or media element |
| `group` | Grouping container without layout |

### Operations

Atomic, reversible operations for document modification:

- `insert` - add a node
- `update` - modify node properties
- `delete` - remove a node
- `move` - change parent or index
- `replace` - replace a node entirely
- `duplicate` - copy an existing node
- `set` - smart insert or update based on target existence

### Feature Highlights

- Immutable document updates with rollback, inverse operations, undo/redo, and checkpoints
- Semantic node search plus component discovery for AI-driven editing workflows
- Layout engines for auto-layout and CSS grid-style composition via `GridLayout`
- Rendering and interaction support for screenshots, hit testing, snapping, transforms, and viewport control
- Presentation export via `PPTXExporter`
- Motion primitives through `AnimationEngine` and `TransitionManager`
- Brand and design-system generation including `DesignPipeline` and `BrandCollateralGenerator`

## Development

### Prerequisites

- Node.js >= 20.0.0
- pnpm >= 9.15.0 via Corepack

### Scripts

| Command | Description |
|---------|-------------|
| `corepack pnpm dev` | Start all packages in dev mode |
| `corepack pnpm build` | Build all packages |
| `corepack pnpm test` | Run workspace tests |
| `corepack pnpm typecheck` | Run workspace TypeScript checks |
| `corepack pnpm lint` | Run workspace ESLint checks |
| `corepack pnpm clean` | Clean build artifacts and workspace dependencies |

### Testing

Tests use [Vitest](https://vitest.dev/). Current test suites live under package-local `src/__tests__` directories.

```bash
# Run all tests
corepack pnpm test

# Run a specific package
corepack pnpm --filter @ai-canvas/core test

# Watch mode
corepack pnpm --filter @ai-canvas/core test:watch

# Coverage
corepack pnpm --filter @ai-canvas/core test:coverage
```

### VSCode Extension Development

```bash
# Build the extension
corepack pnpm --filter @ai-canvas/vscode-extension build

# Debug from VSCode
# Open the repository in VSCode and press F5
```

## 开发经验

以下经验已同步到 `README.md`、`CLAUDE.md`、`Gemini.md`，后续调整时应同时更新这三份文档。

- 命令写法统一使用 `corepack pnpm ...`；包级验证统一使用 `corepack pnpm --filter  ...`
- 包级 `typecheck` / `test` 如果依赖其他包生成的 `dist/*.d.ts`，先构建依赖包，再验证目标包
- 文档中的数量、能力清单和工具列表必须以代码为准，避免手填数字长期漂移
- 调整 CI 质量门禁前，先本地跑受影响包的 `lint`、`typecheck`、`test`，确认当前基线
- 多 Registry 发布流程必须显式覆盖所有目标仓库，且登录失败不能静默跳过
- 测试修复优先通过类型收窄和真实接口对齐解决，避免扩散 `as any`
- 功能、命令、流程、工具数量有变化时，同时同步 `README.md`、`CLAUDE.md`、`Gemini.md`
- 每次问题修复成功后，都要把可复用的经验补充到开发文档，至少同步 `CLAUDE.md` 和 `Gemini.md`

### 推荐验证顺序

```bash
# 1. 安装依赖
corepack pnpm install --frozen-lockfile

# 2. 如目标包依赖其他包的声明产物，先构建依赖包
corepack pnpm --filter @ai-canvas/renderer build

# 3. 再验证目标包
corepack pnpm --filter @ai-canvas/mcp-server typecheck
corepack pnpm --filter @ai-canvas/mcp-server test

# 4. 最后执行仓库级验证
corepack pnpm build
corepack pnpm test
```

## MCP Server

The MCP server exposes the design document, rendering, codegen, brand, print, mockup, collateral, and export workflows to AI assistants.

`open_document` and `save_document` support both native `.canvas` documents and Pencil-compatible `.pen` files.

```bash
# Build and start the server
corepack pnpm --filter @ai-canvas/mcp-server build
corepack pnpm --filter @ai-canvas/mcp-server start
```

### Tool Coverage

The current server ships **47 MCP tools** grouped by workflow:

| Group | Count | Examples |
|-------|-------|----------|
| Document | 2 | `open_document`, `save_document` |
| Query and rendering | 5 | `get_document`, `query_nodes`, `get_layout`, `get_screenshot` |
| Mutation | 1 | `apply_operations` |
| History | 6 | `undo`, `redo`, `create_checkpoint` |
| Tokens and codegen | 4 | `get_tokens`, `set_tokens`, `generate_react`, `generate_tailwind_config` |
| Brand | 7 | `get_brand`, `generate_brand_tokens`, `generate_brand_book` |
| Design system | 10 | `get_design_patterns`, `create_seed_component`, `generate_style_guide` |
| Print and mockups | 6 | `get_print_presets`, `create_mockup`, `create_poster_template` |
| Pipeline and collateral | 5 | `run_design_pipeline`, `generate_collateral_kit`, `export_pptx` |

See [packages/mcp-server/README.md](./packages/mcp-server/README.md) for the package-level workflow overview.

## Deployment

### MCP Server — Docker (Recommended)

The MCP server ships as a multi-stage Docker image targeting `linux/amd64` and `linux/arm64`.

#### Pull from GitHub Container Registry

```bash
docker pull ghcr.io/laoluojuhai/ai-canvas-mcp:latest
```

#### Run

```bash
# stdio mode (used by Claude Desktop / Cursor)
docker run -i --rm \
  -v $(pwd)/documents:/data \
  ghcr.io/laoluojuhai/ai-canvas-mcp:latest

# Pass a specific document directory
docker run -i --rm \
  -v /absolute/path/to/designs:/data \
  ghcr.io/laoluojuhai/ai-canvas-mcp:latest
```

#### Build locally

```bash
docker build -t ai-canvas-mcp -f Dockerfile.mcp .
docker run -i --rm -v $(pwd)/documents:/data ai-canvas-mcp
```

---

### MCP Server — Connect to Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "ai-canvas": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/absolute/path/to/designs:/data",
        "ghcr.io/laoluojuhai/ai-canvas-mcp:latest"
      ]
    }
  }
}
```

Or run from source (requires the repo cloned and built):

```json
{
  "mcpServers": {
    "ai-canvas": {
      "command": "node",
      "args": ["/absolute/path/to/ai-canvas/packages/mcp-server/dist/cli.js"]
    }
  }
}
```

After saving, restart Claude Desktop. The 47 design tools will appear in the tool panel.

---

### MCP Server — Connect to Cursor

Open **Cursor Settings → MCP → Add Server**:

```json
{
  "name": "ai-canvas",
  "command": "docker run -i --rm -v /absolute/path/to/designs:/data ghcr.io/laoluojuhai/ai-canvas-mcp:latest"
}
```

---

### MCP Server — SSE Transport (HTTP)

The server also supports HTTP + Server-Sent Events for web-based clients:

```bash
# Build and start with SSE enabled
corepack pnpm --filter @ai-canvas/mcp-server build
MCP_TRANSPORT=sse MCP_PORT=3001 corepack pnpm --filter @ai-canvas/mcp-server start
```

Connect from any MCP-compatible client at `http://localhost:3001/sse`.

---

### Web App — Static Hosting

The web app builds to a static bundle and can be deployed to any CDN.

```bash
# Build
corepack pnpm --filter @ai-canvas/web-app build
# Output: packages/web-app/dist/

# Preview locally
corepack pnpm --filter @ai-canvas/web-app preview
```

#### Vercel

```bash
# Install Vercel CLI
npm i -g vercel

# Deploy from packages/web-app
cd packages/web-app && vercel --prod
```

Or add a `vercel.json` at the repo root:

```json
{
  "buildCommand": "corepack pnpm --filter @ai-canvas/web-app build",
  "outputDirectory": "packages/web-app/dist",
  "installCommand": "corepack pnpm install --frozen-lockfile"
}
```

#### Docker (web app)

```bash
docker build -t ai-canvas-web -f packages/web-app/Dockerfile .
docker run -p 3000:3000 ai-canvas-web
```

---

### VSCode Extension

#### Install from VSIX (manual)

```bash
# Build the extension package
corepack pnpm --filter @ai-canvas/vscode-extension build
cd packages/vscode-extension
npx vsce package          # produces ai-canvas-*.vsix

# Install into VSCode
code --install-extension ai-canvas-*.vsix
```

#### Development / Debug

1. Open the repo root in VSCode
2. Press **F5** — launches an Extension Development Host with the extension loaded
3. Open any `.canvas` or `.pen` file to activate the visual editor

---

### CI / CD

| Workflow              | Trigger                   | What it does                                        |
|-----------------------|---------------------------|-----------------------------------------------------|
| `ci.yml`              | Push / PR to `main`       | Install -> typecheck -> test -> build               |
| `docker-publish.yml`  | GitHub Release published  | Build multi-arch image -> push to GHCR + Docker Hub |

#### Required repository secrets

| Secret            | Purpose                                          |
|-------------------|--------------------------------------------------|
| `DOCKER_USERNAME` | Docker Hub login (optional, GHCR works without it) |
| `DOCKER_PASSWORD` | Docker Hub token                                 |

#### Create a release

```bash
# Tag a version and push — GitHub Actions handles the rest
git tag v1.0.0
git push origin v1.0.0

# Then create a GitHub Release from the tag to trigger docker-publish.yml
gh release create v1.0.0 --generate-notes
```

---

## Troubleshooting

### `pnpm: command not found`

Run `corepack enable` and retry with `corepack pnpm ...`.

### Workspace commands fail after pulling changes

Reinstall dependencies from the repository root:

```bash
rm -rf node_modules
corepack pnpm install --frozen-lockfile
```

### Clean rebuild

```bash
corepack pnpm clean
corepack pnpm install
corepack pnpm build
```

## License

Released under the MIT License. See [LICENSE](./LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [laoluojuhai](https://github.com/laoluojuhai)
- **Source:** [laoluojuhai/ai-canvas](https://github.com/laoluojuhai/ai-canvas)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-laoluojuhai-ai-canvas
- Seller: https://agentstack.voostack.com/s/laoluojuhai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.