Ai Canvas

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

# 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

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

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. Current test suites live under package-local src/__tests__ directories.

# 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

# 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

推荐验证顺序

# 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.

# 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

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

Run

# 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

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):

{
  "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):

{
  "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:

{
  "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:

# 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.

# 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

# 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:

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

Docker (web app)

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)

# 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

# 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:

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

Clean rebuild

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
• Source: laoluojuhai/ai-canvas
• License: MIT

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