Spud Design MCP V2

Local MCP server for evidence-bound Penpot design delivery.

Lifecycle:

Start -> Direction Commit -> Prototype Submit -> User Approval -> Implementation Submit -> User Approval -> Code Completion

Public tools

• design_session_start

• design_direction_commit

• design_stage_submit

• design_stage_approve

• design_code_complete

All writes require idempotency keys. Direction commit accepts exactly three compact, viable, materially different cards, selects one, and binds a hashed root-relative selected-design inventory under DESIGN_MCP_CAPTURE_ROOT. Every inventory item points to byte-verified evidence with declared hash, MIME type, and length before deterministic category DesignIR is stored. Full execution and DesignIR detail are on-demand resources, not default tool input. Prototype and implementation PNGs are read from DESIGN_MCP_CAPTURE_ROOT, validated from bytes, stored as immutable content-addressed SQLite blobs, rendered deterministically for review, and inspected through MCP image sampling. Both stages require a manifest path, verified server-owned Penpot journal ID, and exact selected named frame. Caller-written scores, hashes, dimensions, and review prose are not accepted.

Connected Codex host is vision provider. Server sends deterministic review rendition and rubric-only prompt through MCP sampling; selected-direction prose never enters sampling instructions. If host cannot inspect image, rejects sampling, returns malformed output, or supplies no pixel-grounded perception evidence, review status is incomplete; no axes or score are invented and approval remains blocked. Host returns eight pixel-grounded axes and at most three failed-axis findings. Server orders blocker/major findings before minor polish and assigns contiguous ranks.

Set DESIGN_MCP_LEGACY_TOOLS=1 only for one transition release to expose exact old eight tools. Default and legacy surfaces never mix.

Intended workflow uses Penpot exports for stage captures and a fixed-viewport browser screenshot for code capture. Server reads DESIGN_MCP_HOME/penpot-journal.json; caller has no default manifest-signing secret. Verified journal and export manifest bind stored review sheet to transaction, capability/revisions, session, stage, DesignIR, root PNG, and selected frame. Code completion crops that exact frame, requires matching browser artifact/frame IDs and viewport, and runs strict global/local plus exhaustive file-backed semantic parity. Server still records originAttestation: unverified: manifest integrity and pixel fidelity do not independently prove external application identity or aesthetic excellence.

Related MCP server: AI-Canvas MCP Server

Run

$env:DESIGN_MCP_CAPTURE_ROOT = 'C:\absolute\capture-root'
npm install
npm run typecheck
npm test
npm run build:runtime
npm run package:smoke
npm run benchmark:verify
npm run dev

V2 storage defaults to .design-mcp/design-mcp-v2.sqlite. Historical V1 data is separate and never pruned during startup.

Author a Penpot stage

design-mcp author-stage is packaged with server. It accepts one JSON request, verifies exact DesignIR plus byte-backed assets under capture root, then uses official Penpot MCP execute_code and export_shape boundaries. Normal stage costs at most three backend calls: snapshot, one atomic apply, one root export. Result is root PNG, penpot-export-manifest/v1, and durable verified journal entry used by design_stage_submit.

$env:DESIGN_MCP_HOME = 'C:\absolute\design-mcp-home'
$env:DESIGN_MCP_CAPTURE_ROOT = 'C:\absolute\capture-root'
$env:PENPOT_MCP_URL = 'http://127.0.0.1:4401'

# Request carries captureRoot, sessionId, stage, DesignIR, exact expected capability,
# and capture-root-relative exportPngPath/manifestPath.
design-mcp author-stage C:\absolute\capture-root\author-stage.json

Authoring fails closed on missing endpoint, capability drift, unsupported IR, path/symlink escape, asset mismatch, timeout, ambiguous mutation, or export mismatch. Current automated proof uses deterministic mocked official transports. Live Penpot stack execution remains unverified; see docs/PENPOT_AUTHORING_ARCHITECTURE.md.

Generate standalone code

design-mcp generate-code does not add an MCP tool. It reads immutable DesignIR, selected-inventory quality, and verified evidence blobs from V2 SQLite, then requires an exact expected code-manifest/v2 JSON file under DESIGN_MCP_CAPTURE_ROOT. Hash, MIME, byte length, root containment, and symlink checks fail closed. Output is created atomically under DESIGN_MCP_CODE_ROOT; existing output is never changed.

$env:DESIGN_MCP_HOME = 'C:\absolute\design-mcp-home'
$env:DESIGN_MCP_CAPTURE_ROOT = 'C:\absolute\capture-root'
$env:DESIGN_MCP_CODE_ROOT = 'C:\absolute\generated-code'

# Save expected-code-manifest resource as expected-code-manifest.json under capture root.
@{
  sessionId = 'session-id'
  codeManifestPath = 'expected-code-manifest.json'
  outputDirectory = 'product-ui'
} | ConvertTo-Json | Set-Content "$env:DESIGN_MCP_CAPTURE_ROOT\generate-code.json"

design-mcp generate-code generate-code.json
cd "$env:DESIGN_MCP_CODE_ROOT\product-ui"
npm install
npm run build
npm run smoke

Generated package pins typescript@7.0.2. Asset files are exact verified immutable bytes under assets; runtime uses only those local paths, never inventory asset.source URLs. Generated manifest binds every source and binary file by path, SHA-256, MIME type, and byte length.