sketch-design-mcp 3.0.0

package/README.md

@@ -0,0 +1,138 @@
+# 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
+
+```bash
+npm install
+npm run build
+```
+
+## Usage with Claude Code
+
+Add to `~/.claude.json`:
+
+```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:
+
+```bash
+export SKETCH_MCP_RULESET_PROFILE=generic
+```
+
+- You can still override keyword/pattern rules without changing TypeScript code:
+
+```bash
+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:
+
+```json
+{
+  "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.