98 lines
5.3 KiB
Markdown
98 lines
5.3 KiB
Markdown
# MCP Codegen Pipeline — Implementation Plan
|
||
|
||
## What's Done
|
||
|
||
Branch `feat/mcp-codegen` (off `57eaf87`).
|
||
|
||
### New Files
|
||
|
||
- `packages/core/src/tools/codegen.ts` — 3 MCP tools:
|
||
- `design_to_tokens` — extracts Figma variables as CSS/Tailwind/JSON, resolves aliases, handles multi-mode
|
||
- `design_to_component_map` — analyzes document for screens, components (variants, props, instance counts), dependency overview
|
||
- `get_codegen_prompt` — returns the codegen system prompt (lazy `await import('node:fs/promises')` to avoid Vite browser externalization error)
|
||
- `packages/core/src/tools/prompts/codegen.md` — 5-step workflow prompt (~8KB):
|
||
1. Survey (page tree, components, variables, colors, typography, spacing)
|
||
2. Decompose (clusters, describe, get_jsx → component map)
|
||
3. Extract tokens (stack-aware: Tailwind → only semantic color CSS vars; CSS → full vars)
|
||
4. Generate code (bottom-up, one file per component, interactive states)
|
||
5. Verify (re-check against design)
|
||
- `packages/core/src/tools/registry.ts` — 3 tools registered in `ALL_TOOLS` (now 91 total)
|
||
- `docs/design-to-code-overview.md` — architecture overview
|
||
|
||
### Design Decisions
|
||
|
||
- **No MCP server instructions** — prompt delivered via `get_codegen_prompt` tool only (no 8KB overhead per request)
|
||
- **Lazy fs import** — `await import('node:fs/promises')` inside function body to avoid Vite `Module "node:fs" has been externalized` crash in browser bundle
|
||
- **Tailwind token strategy** — CSS custom properties only for semantic colors; Tailwind utilities for spacing/font/radius (avoids `--font-bold`, `--text-sm` conflicts with Tailwind v4 internals)
|
||
- **No modifications to existing tools** — `get_jsx`, `describe`, `analyze_*` used as-is
|
||
|
||
### Tested
|
||
|
||
- MCP HTTP server (`http://127.0.0.1:3100/mcp`) — all 3 new tools callable
|
||
- End-to-end with `lol.fig` (Movie Card, 390×1823, Inter font, dark theme, 164 nodes):
|
||
- Full pipeline: survey → decompose → tokens → generate → verify
|
||
- Generated 10 Vue 3 + Tailwind components + semantic color tokens
|
||
- Visual test in just-bun dev server
|
||
|
||
## What's Left
|
||
|
||
### Phase 1 — Tailwind HTML Export (high value, low effort)
|
||
|
||
Add `format` parameter to `get_jsx` tool:
|
||
- `"openpencil"` (default) — current round-trip JSX
|
||
- `"tailwind"` — HTML with Tailwind v4 utility classes
|
||
|
||
The renderer already exists (`export-jsx.ts` → `collectTailwindClasses`), just not exposed through the tool params. One change in `read.ts`.
|
||
|
||
This gives the LLM ready-to-use HTML with correct Tailwind classes directly from MCP — drastically reduces hallucination in generated code.
|
||
|
||
### Phase 2 — Prompt Improvements
|
||
|
||
- [ ] **Multi-file output format** — prompt should specify how to structure output when generating multiple files (fenced blocks with filenames)
|
||
- [ ] **Framework adapters** — framework-specific sections in prompt (Vue `<script setup>` boilerplate, React hooks patterns, Svelte `$props()`)
|
||
- [ ] **Image handling** — prompt guidance on when to use `export_svg` vs `export_png`, how to reference assets in generated code
|
||
- [ ] **Responsive** — breakpoint detection from frame widths, responsive class generation
|
||
|
||
### Phase 3 — Advanced Tools
|
||
|
||
- [ ] **`design_to_html`** — full page HTML + Tailwind from a frame, using the existing tailwind renderer + semantic grouping. Essentially `get_jsx format=tailwind` but with smarter HTML tag selection (nav, header, main, section, article, button)
|
||
- [ ] **`design_to_styles`** — extract complete stylesheet (CSS custom properties for all tokens, not just Figma variables but also inferred from analyze_colors/typography)
|
||
- [ ] **`compare_design_code`** — given generated code and node ID, produce a diff of what's missing or wrong
|
||
|
||
### Phase 4 — Integration
|
||
|
||
- [ ] Pi skill for open-pencil MCP (`~/.pi/agent/skills/open-pencil/SKILL.md`) — DONE, needs testing with real workflow
|
||
- [ ] VS Code extension integration — connect open-pencil MCP to the extension's AI chat
|
||
- [ ] Batch mode — process multiple frames/pages in one go
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────┐
|
||
│ AI Agent (LLM) │
|
||
│ │
|
||
│ reads codegen.md │
|
||
│ calls MCP tools │
|
||
│ generates code │
|
||
└─────────┬───────────┘
|
||
│ MCP (HTTP SSE)
|
||
┌─────────▼───────────┐
|
||
│ MCP Server │
|
||
│ :3100/mcp │
|
||
├─────────────────────┤
|
||
│ Survey tools │ get_page_tree, get_components,
|
||
│ │ list_variables, list_collections,
|
||
│ │ analyze_colors, analyze_typography,
|
||
│ │ analyze_spacing
|
||
├─────────────────────┤
|
||
│ Decompose tools │ analyze_clusters, describe, get_jsx,
|
||
│ │ design_to_component_map
|
||
├─────────────────────┤
|
||
│ Token tools │ design_to_tokens, list_variables
|
||
├─────────────────────┤
|
||
│ Codegen tools │ get_codegen_prompt, export_svg
|
||
├─────────────────────┤
|
||
│ Core │ .fig parser, scene graph, renderers
|
||
└─────────────────────┘
|
||
```
|