sketch-design-mcp

MCP server for high-fidelity implementation from Sketch spec pages (无敌Sketch标注插件导出), optimized for Claude Code.

Version 3 Direction

v3 is the only supported pipeline and focuses on implementation fidelity:

1. get_artboard_manifest: choose the right entry artboard
2. get_scene_graph: reconstruct hierarchy + constraints from flat layers
3. get_blueprint: generate implementation contract (layout/tokens/components/interactions)
4. get_interaction_graph: build trigger -> condition -> action graph with target binding
5. validate_implementation: compare expected contract vs actual implementation snapshot

This enables a practical loop: extract -> code -> screenshot/json snapshot -> validate -> fix.

Architecture

src/
├── index.ts         # MCP protocol entry (official SDK, stdio transport)
├── engine.ts        # Engine export facade
├── engine/          # Engine internals (core/output/v3-tools)
├── v3/              # v3 modules: scene / blueprint / interaction / validate / manifest
├── rules.ts         # Configurable recognition rules (supports external JSON override)
├── aggregator.ts    # Shared low-level layer helpers used by v3
├── aggregator/      # Shared low-level layer helpers
└── types.ts         # Type definitions

Tools

| Tool | Purpose | |------|---------| | get_artboard_manifest | Artboard list + complexity score + recommended pages (supports paging) | | get_scene_graph | Hierarchical nodes, constraints, sections, styles (supports paging) | | get_blueprint | Code-generation contract for Claude Code (supports component paging) | | get_interaction_graph | Structured interaction edges with target binding (supports paging) | | validate_implementation | Scoring + findings for layout/style/interaction |

Setup

npm install
npm run build

Usage with Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "sketch-design": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sketch-design-mcp/dist/index.js"]
    }
  }
}

Recommended Claude Workflow

1. Call get_artboard_manifest and choose a recommended=true artboard.
2. Call get_blueprint for the target Y range.
3. Generate front-end code from blueprint.
4. Call get_interaction_graph to complete behavior logic.
5. Feed expected/actual JSON into validate_implementation.
6. Iterate until score reaches your target.

Large Payload Behavior

• v3 tools no longer silently truncate large responses.
• If payload exceeds limit, tool returns an explicit error with guidance.
• Use offset/limit/cursor to fetch in pages.
• Cursor format is offset:N (example: offset:300).
• For very large blueprints, set include_interactions=false and fetch interactions via get_interaction_graph.

Configurable Rules

• Default recognition rules are built in src/rules.ts.
• Built-in profiles:
  • shadow_zh: optimized for current Chinese intranet Sketch annotation style.
  • generic: broader language/label matching for mixed teams.
• MCP now auto-detects profile from the selected artboard layers.
• You can force profile selection:

export SKETCH_MCP_RULESET_PROFILE=generic

• You can still override keyword/pattern rules without changing TypeScript code:

export SKETCH_MCP_RULESET_PATH=/absolute/path/to/ruleset.json

• Example rules file: docs/ruleset.example.json.
• Supported override keys include:
  • annotationNamePrefixes, annotationFontIncludes, anchorNamePrefixes
  • specFontIncludes, marginNumberedItemPattern, marginSpecPatterns
  • interactionStepPatterns.trigger/condition/action
• Every tool output now includes runtime rule metadata in meta:
  • ruleProfile
  • ruleConfidence
  • ruleSource (auto / forced_env / default)

AI Interaction Understanding

• get_interaction_graph supports model-driven semantic understanding for interaction blocks via Anthropic Messages API.
• Configuration via 4 environment variables:
  • SKETCH_MCP_INTERACTION_PROVIDER — anthropic (default) or fallback to disable AI
  • SKETCH_MCP_INTERACTION_MODEL — model name (e.g. glm-5.1)
  • SKETCH_MCP_AUTH_TOKEN — API key for the provider
  • SKETCH_MCP_BASE_URL — API base URL (e.g. https://open.bigmodel.cn/api/anthropic)
• When SKETCH_MCP_AUTH_TOKEN is empty or provider is fallback, falls back to rule-based analysis.
• AI output also feeds visualHints into get_blueprint, so interaction-derived visual states can be carried into implementation.

Example MCP server config:

{
  "env": {
    "SKETCH_MCP_INTERACTION_PROVIDER": "anthropic",
    "SKETCH_MCP_INTERACTION_MODEL": "glm-5.1",
    "SKETCH_MCP_AUTH_TOKEN": "your-api-key",
    "SKETCH_MCP_BASE_URL": "https://open.bigmodel.cn/api/anthropic"
  }
}

Notes

• Pure TypeScript runtime, no Python dependency.
• Internal-network cache: /tmp/sketch_design_cache.
• NODE_TLS_REJECT_UNAUTHORIZED=0 is enabled for intranet HTTPS edge cases.