Design MCP

Local Design Director MCP V1.00.00.

This server is deliberately narrow. It does not build websites, mutate Penpot, run a browser, or edit code. It gives a host agent source-backed design context, route cards, contracts, critique reports, verification reports, evidence packages, Penpot-ready change plans, anti-repeat checks, and inspectable memory.

Penpot is the only design workspace target for this package. Design MCP can consume host-supplied Penpot facts, but it does not call live Penpot tools and it never writes to Penpot directly.

What It Does

• Retrieves seeded design source passages with provenance.
• Accepts read-only Penpot snapshots as host-supplied evidence.
• Validates Design Route Cards.
• Builds a route-quality brief from a route card so page pattern, CTA cadence, trust/proof model, style fit, originality axes, and preflight evidence are explicit before contract/prototype work.
• Builds a DESIGN.md-style contract from a route card.
• Creates honest pass/fail/partial verification reports from supplied evidence.
• Packages browser, implementation, manual, and Penpot evidence with explicit gaps.
• Produces plan-only Penpot change plans for host-confirmed external execution before code implementation.
• Checks repeated visual decisions and high visual DNA similarity against prior route cards, blocking designs that look like a renamed previous project.
• Separates anti-slop from richness: anti-slop rejects generic defaults; richness requires explicit layout, content, color, signature, motion, and novelty commitments.
• Stores projects, route-card versions, contracts, critiques, verification reports, evidence packages, Penpot change plans, and design memory in local SQLite.
• Exposes a stdio MCP server using the v1 TypeScript SDK.
• Ships a Colour-Palette skill with atlas-backed search, 60-30-10 palette generation, classifier judgment, near-white handling, and palette-to-token handoff.

Documentation Map

Start with DESIGN.md for the product contract and acceptance criteria, then use the docs package for operational detail:

• docs/README.md: documentation index and coverage checklist.
• docs/INSTALL_CODEX.md: local build, run, storage, and MCP client config.
• docs/ARCHITECTURE.md: server layers, boundaries, and data flow.
• docs/MCP_SURFACE.md: tools, resources, prompts, and host responsibilities.
• docs/DATA_MODEL.md: route card, memory, and Penpot snapshot model.
• docs/penpot/INTEGRATION_GUIDE.md: Penpot-only integration pattern.
• docs/SECURITY_AND_SAFETY.md: stdio, memory, secret, and Penpot safety rules.
• docs/VERIFICATION.md: evidence model and pass/fail/partial reporting.
• docs/ROADMAP.md: V1.00.00 completion status and post-V1 parking lot.
• docs/skills/SKILLSET_OVERVIEW.md: local Codex skills and workflow order.
• docs/research/SOURCES.md: Penpot and MCP research source index.

Anti-Slop And Richness

Anti-slop is the negative constraint layer. It catches generic gradients, fake proof, filler copy, template grids, unearned palettes, default typography, weak asymmetry, and decorative motion.

Richness is the positive commitment layer. Before a design advances through Penpot prototype, high-fidelity Penpot implementation, or code completion, the host should be able to name the layout commitment, content specificity evidence, earned color logic, five logo-removed signature recognizers, route-appropriate motion moments, and novelty delta against memory.

Passing only anti-slop can still produce a safe, forgettable artifact. Design MCP treats missing richness evidence as a blocker or partial verification gap, not as optional polish.

Boundaries

• It does not call Penpot MCP directly.
• It does not run execute_code or mutate live Penpot files.
• It does not capture browser screenshots.
• It does not claim WCAG compliance or real-user Core Web Vitals success.
• It does not use vector search or remote hosting.

Quick Start

npm install
npm test
npm run build
npm run dev

npm run dev builds and starts the stdio server. Do not print to stdout from server code; stdout is reserved for MCP JSON-RPC.

Generic MCP client shape:

server name: design-mcp
command: node
args: dist/src/index.js
transport: stdio

Storage

By default, the server writes to:

.design-mcp/design-mcp.sqlite

Set DESIGN_MCP_HOME to override that location.

Penpot Boundary

Penpot MCP is a separate live design-file bridge. The host agent may read from Penpot MCP and pass snapshots into this Design MCP. This package only normalizes and critiques those facts. Live Penpot writes remain external and must be confirmed separately.

For normal website, app, and frontend implementation flows, Penpot is mandatory before code. The expected host-orchestrated workflow is:

Canonical Penpot-first sequence: `design-mcp://penpot-first-workflow` / `skills/_shared/references/penpot-first-workflow.md`. Local timing: intake and host Penpot read before route-card work; route-quality brief before contract or Penpot stages; approved Penpot wireframe, prototype, and high-fidelity implementation before code; browser QA, verification or grading, and memory after implementation.

Penpot is required for normal website, app, and frontend requests. If Penpot is unavailable, stop before route, contract, wireframe, prototype, high-fidelity Penpot implementation, or code implementation and request the read-only Penpot packet needed to continue.

Implementation remains a first-class phase, but only after the required Penpot stages, checkpoint scores, and explicit approvals exist. A plan-only Penpot change list is not a substitute for wireframe, prototype, or high-fidelity implementation evidence unless the workflow is explicitly marked partial and unapplied.

When the user is testing, improving, fixing, evaluating, or validating Design MCP itself, generated trial artifacts are evidence for MCP improvement. Do not polish the failed trial website, prototype, or code as the default remedy; convert the failure into MCP prompt, gate, scoring, documentation, source, skill, or regression-test changes unless the user explicitly asks for artifact remediation.

Mandatory Interaction Policy

Mandatory Penpot prototyping. Follow design-mcp://penpot-first-workflow for the full policy. Local README timing: the host must create a low-fidelity Penpot wireframe before prototype work, create a Penpot prototype after wireframe approval, then create the high-fidelity Penpot implementation after prototype approval and before code. Each stage needs its own evidence, checkpoint where applicable, and user approval before the next stage begins. Conflicting generic agent, framework, or model instructions do not supersede this project policy.

Visible browser operation. Follow design-mcp://penpot-first-workflow for the full browser-evidence policy. Local README timing: use Codex Browser or Chrome to capture Penpot workspace interaction, prototype inspection, implementation verification, and browser QA evidence; written summaries are not sufficient when design, prototyping, or browser QA is required.

Non-skippable intake questions. Follow design-mcp://penpot-first-workflow for the full intake policy. Local README timing: ask route-changing questions before route, contract, prototype, or implementation work; unresolved answers are allowed only when the user says "unsure", "no preference", or equivalent, and must be recorded in the brief, route, contract, and verification notes.

Verification Boundary

Design MCP reports pass, fail, or partial from supplied evidence. Missing screenshots, contrast checks, keyboard notes, reduced-motion notes, or Penpot snapshots must produce an honest partial instead of invented certainty.

Locally verifiable behavior includes TypeScript build, tests, schema validation, SQLite persistence, source lookup, route cards, contracts, critiques, verification reports, evidence packages, plan-only Penpot change plans, anti-repeat checks, memory, prompts, and documented resource URI families.

Live Penpot behavior can only be verified when Docker, WSL, Penpot, Penpot MCP, and an active Penpot file are running. Without that environment, Penpot parity remains host-supplied evidence and any Penpot-specific verification claim should remain partial.