Design-Code Registry MCP

A deterministic, project-agnostic MCP server that maps design components, tokens, and patterns to their code implementations — across any design tool and any framework.

It's a lightweight, git-friendly alternative to Figma Code Connect, built as a generic knowledge layer that any MCP-compatible AI coding agent (Claude Code, Cursor, Codex, OpenCode, ...) can query.

Figma Design  ↕  Design Component / Token / Pattern  ↕  Code Implementation

Why this exists

AI coding agents are good at writing code but bad at knowing "does this project already have a Button component, and if so, what's it called and where does it live?" Today that knowledge either lives in an agent's fuzzy inference (unreliable) or is coupled tightly to one specific design tool + framework pairing (Figma Code Connect, which is React/Figma-only).

Core principle: exact registry data beats AI inference. If the registry has an explicit mapping, the agent should never need to guess it. If it doesn't, the agent should be told "unresolved" rather than making something up.

This project is:

• Not an AI model. It's a structured knowledge layer exposed through MCP tools.

• Not a vector database / RAG. Resolution is exact-match only (id, design reference, canonical name, alias) — never embeddings or fuzzy similarity.

• Not tied to any framework or design tool. React, Vue, Svelte, SwiftUI, Flutter, HTML — and Figma, Sketch, Penpot, or anything else — are all just strings in the schema, not special cases in the code.

Architecture

                    AI Agent (Claude Code, Cursor, ...)
                             │
                             ↓
                       MCP Protocol (stdio)
                             │
                             ↓
                Design-Code Registry MCP  (this package — the generic engine)
                             │
                     FileRegistryProvider
                             │
              ┌──────────────┼──────────────┬─────────────┐
              ↓              ↓              ↓             ↓
         components.json  tokens.json  patterns.json  rules.json
                             │
                    .design/registry/   (your project — the data)

The server (this npm package) is generic and reusable across completely different projects. The registry (.design/registry/ in your project) is where all project-specific facts live, as plain JSON files that are readable, diffable, and mergeable in git.

Registry concepts

A single component can have multiple implementations — the same design concept mapped to React, Vue, SwiftUI, and Flutter simultaneously, if your project needs that:

{
  "id": "button",
  "name": "Button",
  "implementations": [
    { "language": "typescript", "framework": "react", "component": "Button", "sourcePath": "src/components/Button.tsx" },
    { "language": "dart", "framework": "flutter", "component": "AppButton", "sourcePath": "lib/widgets/app_button.dart" }
  ]
}

Design references are generic too — tool is an open string, not an enum, so adding support for a new design tool never requires a schema migration:

{ "tool": "figma", "fileId": "abc123", "nodeId": "12:340", "url": "https://figma.com/file/abc123?node-id=12-340" }

See src/schema/ for the full, commented schema (Zod), and examples/fictional-project/ for a complete worked example.

Deterministic resolution

registry_find_by_design_reference and the underlying resolver never guess. They try, in this fixed order, and stop at the first strategy that produces a match:

1. Exact design reference (tool + node/file/url/name)

2. Exact registry id

3. Exact canonical name

4. Explicit alias

5. Otherwise: unresolved

If a strategy matches more than one component, resolution stops there and reports ambiguous with every candidate — it never silently picks one:

// unresolved
{ "status": "unresolved" }

// ambiguous
{ "status": "ambiguous", "strategy": "alias", "candidates": [ /* ... */ ] }

// resolved
{ "status": "resolved", "strategy": "design-reference", "component": { "id": "button", /* ... */ } }

MCP tools

Read

Write

Mutation safety: creating an id that already exists is an error (use update instead); updating an id that doesn't exist is an error (use create instead); there is no destructive delete for components — use registry_deprecate_component so history survives in git.

Validation

registry_validate (and design-code-registry validate in the CLI) checks the whole registry for:

• Duplicate ids within components/tokens/patterns/rules

• Duplicate design references (two components claiming the same Figma node)

• Broken references (a pattern pointing at a component that doesn't exist, a deprecation replacedBy pointing nowhere, a rule's appliesTo.id pointing nowhere)

• Circular pattern references (pattern A → related pattern B → related pattern A)

• Missing implementations on approved components (warning, not an error)

{
  "valid": false,
  "errorCount": 1,
  "warningCount": 0,
  "issues": [
    { "severity": "error", "code": "BROKEN_REFERENCE", "message": "Pattern \"empty-state\" references component \"buton\", which does not exist.", "location": "pattern:empty-state" }
  ]
}

CLI

Human-facing interface over the same RegistryService the MCP tools use — behavior never drifts between the two.

npx design-code-registry-mcp init --name "My Project" --design-tool figma

design-code-registry validate
design-code-registry list components --status approved
design-code-registry list tokens --category color
design-code-registry list patterns

design-code-registry add component --id button --name Button
design-code-registry add token --id color-primary --name "Primary" --category color --value "#3B5BFF"
design-code-registry add pattern --id empty-state --name "Empty State" --components button

Every command accepts -p, --path <path> to point at a specific registry, or reads DESIGN_REGISTRY_PATH.

Installation

npm install -g design-code-registry-mcp
# or, without installing:
npx design-code-registry-mcp init

Claude Code setup

Add the server to your Claude Code MCP configuration (.mcp.json at your project root, or via claude mcp add):

{
  "mcpServers": {
    "design-code-registry": {
      "command": "npx",
      "args": ["-y", "design-code-registry-mcp"]
    }
  }
}

Or, with an explicit registry path (useful in a monorepo):

{
  "mcpServers": {
    "design-code-registry": {
      "command": "npx",
      "args": ["-y", "design-code-registry-mcp", "--registry-path=./packages/design-system/.design/registry"]
    }
  }
}

The server works with any MCP-compatible client over stdio — Claude Code is one client among several, not a dependency of the server itself.

Figma MCP integration

This server does not talk to the Figma API or inspect Figma files — that's Figma's own MCP server's job. The two are designed to be complementary:

Figma MCP  →  design context (fileKey, nodeId, ...)  →  Design-Code Registry MCP  →  explicit mapping  →  AI agent  →  code

A typical agent workflow:

1. Agent asks Figma MCP for the selected node's fileKey/nodeId.

2. Agent calls registry_find_by_design_reference on this server with those identifiers.

3. If resolved, the agent reuses the returned implementation. If unresolved, the agent may propose a new component (per your project's rules) and register it with registry_create_component.

Multi-framework example

A single registry can describe implementations across totally different codebases:

Button (design concept)
 ├── React        → src/components/Button.tsx
 ├── Vue          → src/components/Button.vue
 ├── SwiftUI      → Sources/Button.swift
 └── Flutter      → lib/widgets/app_button.dart

Nothing about the server changes based on which of these your project uses — the schema treats language and framework as open strings.

Example project

examples/fictional-project/ contains a complete, validated example registry (Button, Input, Card, Modal, two patterns, seven tokens, five rules) for a fictional "Aurora Design System." Copy .design/registry/ from there as a starting point, or run:

cp -r examples/fictional-project/.design .

AI agent usage contract

Agents connected to this server should:

1. Query the registry before creating any reusable UI component.

2. Resolve exact mappings first — never guess a mapping when one might exist.

3. Reuse existing registered implementations rather than duplicating them.

4. Read relevant tokens and patterns before generating styles/layout.

5. Report unresolved honestly rather than inventing a mapping.

6. Never create a new canonical component when registry_find_component / registry_find_by_design_reference shows an equivalent one already exists.

7. Only propose a new component when no appropriate existing one exists.

8. Treat all registry mutations as explicit, deliberate actions — not incidental side effects.

9. Treat the registry as authoritative for project-specific Design ↔ Code facts.

At the same time, the registry doesn't own good engineering judgment: when it's incomplete or a more maintainable approach is clearly available, an agent should say so — distinguishing verified registry facts from inferred information and recommendations — rather than mechanically obeying an incomplete registry.

Development

npm install
npm run build      # compile TypeScript → dist/
npm test           # build + run the full vitest suite (56 tests, including a real stdio subprocess e2e test)
npm run lint
npm run typecheck

See CONTRIBUTING.md for the project's design principles before opening a PR.

Limitations & future improvements

• Only a local, file-based registry provider ships today. The RegistryService layer is provider-agnostic, so a remote/API-backed provider is possible without touching MCP tool logic — just not implemented yet.

• No optional HTTP/SSE transport yet (stdio only), per the "don't over-engineer the first version" principle.

• registry_find_component is a deterministic substring search, not a ranked/fuzzy search — by design, but it means very loose queries may return nothing where a human would expect a near-match.

• No built-in Figma/Sketch/Penpot API client — this server intentionally stays downstream of tools like Figma MCP rather than duplicating their job.

License

MIT