Design-Code Registry MCP

Ein deterministischer, projektunabhängiger MCP-Server, der Design-Komponenten, Tokens und Patterns ihren Code-Implementierungen zuordnet – über jedes Design-Tool und jedes Framework hinweg.

Es ist eine schlanke, git-freundliche Alternative zu Figma Code Connect, aufgebaut als generische Wissensschicht, die jeder MCP-kompatible KI-Coding-Agent (Claude Code, Cursor, Codex, OpenCode, ...) abfragen kann.

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

Warum es das gibt

KI-Coding-Agenten sind gut darin, Code zu schreiben, aber schlecht darin zu wissen: „Hat dieses Projekt bereits eine Button-Komponente – und wenn ja, wie heißt sie und wo befindet sie sich?“ Heute lebt dieses Wissen entweder in den vagen Inferenzen eines Agenten (unzuverlässig) oder ist eng an eine spezifische Design-Tool- und Framework-Kombination gekoppelt (Figma Code Connect, das nur React/Figma unterstützt).

Kernprinzip: Exakte Registry-Daten schlagen KI-Vermutungen. Wenn die Registry eine explizite Zuordnung enthält, sollte der Agent sie niemals erraten müssen. Wenn nicht, sollte dem Agenten „unresolved“ mitgeteilt werden, statt sich etwas auszudenken.

Dieses Projekt ist:

• Kein KI-Modell. Es ist eine strukturierte Wissensschicht, die über MCP-Tools bereitgestellt wird.

• Keine Vektordatenbank / RAG. Die Auflösung erfolgt ausschließlich über exakte Übereinstimmungen (id, Design-Referenz, kanonischer Name, Alias) – niemals über Embeddings oder Fuzzy-Ähnlichkeit.

• An kein Framework oder Design-Tool gebunden. React, Vue, Svelte, SwiftUI, Flutter, HTML – und Figma, Sketch, Penpot oder sonst alles – sind im Schema nur Strings und keine Sonderfälle im Code.

Architektur

Der Server (dieses npm-Paket) ist generisch und über komplett unterschiedliche Projekte hinweg wiederverwendbar. Die Registry (.design/registry/ in Ihrem Projekt) beherbergt all projektspezifisches als schlichte JSON-Dateien, die in Git lesbar, diffbar und mergebar sind.

                    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)

Registry-Konzepte

Eine einzelne Komponente kann mehrere Implementierungen haben – dasselbe Design-Konzept wird auf React, Vue, SwiftUI und Flutter gleichzeitig abgebildet, falls Ihr Projekt das benötigt:

{
  "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-Referenzen sind ebenso generisch – tool ist ein offener String, kein Enum, sodass die Unterstützung für einen neuen Design-Tools keine Schema-Migration erfordert:

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

Das vollständige, auskommentierte Schema (Zod) finden Sie unter src/schema/ und ein vollständiges durchgearbeitetes Beispiel unter examples/fictional-project/.

Deterministische Auflösung

registry_find_by_design_reference und der zugrunde liegende Resolver raten nie. Sie versuchen es in dieser festen Reihenfolge und stoppen bei der ersten Strategie, die einen Treffer liefert:

1. Exakte Design-Referenz (tool + node/file/url/name)

2. Exakte Registry id

3. Exakter kanonischer Name

4. Expliziter Alias

5. Andernfalls: kanschiedlich unresolved

Wenn eine Strategie mehr als eine Komponente trifft, stoppt die Auflösung dort und meldet ambiguous mit allen Ehren Kandidaten – sie wählt nie stillschweigen einen aus:

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

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

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

MCP-Tools

Lesen

Schreiben

Sicherheit bei Mutationen: Das Erstellen einer id, die bereits existiert, ist ein Fehler (nutzen Sie stattdessen Update); das Aktualisieren einer id, die nicht existiert, ist ebenfalls ein Fehler (nutzen Sie stattdessen Create). Es gibt kein destruktives Löschen für Komponenten – verwenden Sie registry_deprecate_component, damit die Historie in Git erhalten bleibt.

Validierung

registry_validate (und design-code-registry validate in der CLI) prüft die gesamte Registry auf:

• Doppelte ids innerhalb von Komponenten/Tokens/Patterns/Rules

• Doppelte Design-Referenzen (zwei Komponenten beanspruchenleichen Figma-Node)

• Kaputte Referenzen (ein Pattern, das auf eine nicht vorhandene Komponente zeigt, eine von replacedBy ausgehende Deprecation, die ins Leere zeigt, eine appliesTo.id einer Regel, die ins Leerehe dieses Mal zeigt)

• Zirkuläre Pattern-Verweise (Pattern A → verwandtes Pattern B → verwandtes Pattern A)

• Fehlende Implementierungen bei zugelassenen Komponenten (Warnung, kein Fehler)

{
  "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

Eine menschlich zugängliche Oberfläche auf demselben RegistryService, den auch die MCP-Tools verwenden – das Verhalten driftet nie zwischen beiden.

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

Jeder Befehl akzeptiert -p, --path <path>, um auf eine bestimmte Registry zu zeigen, oder liest DESIGN_REGISTRY_PATH.

Installation

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

Einrichtung mit Claude Code

Fügen Sie den Server zur MCP-Konfiguration von Claude Code hinzu (.mcp.json im Projektstamm oder über claude mcp add):

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

Oder mit einem expliziten Registry-Pfad (nützlich in einem Monorepo):

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

Der Server funktioniert mit jedem MCP-kompatiblen Client über stdio – Claude Code ist einer von mehreren Clients und keene Abhängigkeit des Servers selbst.

Figma-MCP-Integration

Dieser Server spricht nicht mit der Figma-API und prüft keine Figma-Dateien – das ist der Job des eigenen Figma-MCP-Servers. Die beiden sind dafür ausgelegt, sich zu ergänzen:

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

Ein typischer Agenten-Workflow:

1. Der Agent fragt den Figma MCP nach fileKey/nodeId des ausgewählten Knotens.

2. Der Agent ruft auf diesem Server registry_find_by_design_reference mit diesen Identifikatoren auf.

3. Bei resolved fungiert eine Verwendung der zurückgegebenen Implementierung. Bei unresolved darf der Agent eine neue Komponente vorschlagen (gemäß der Regeln Iregebnisses) und diese über registry_create_component registrieren.

Multi-Framework-Beispiel

Ein einzelnes Registry kann Implementierungen über völlig unterschiedliche Codebasen hinweg beschreiben:

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

Am Server selbst ändert sich nichts davon, welches dieser Frameworks Ihr Projekt verwendet – das Schema behandelt language und unmeldung als offene Strings.

Beispielprojekt

examples/fictional-project/ enthält eine vollständige, validierte Beispiel-Registry (Button, Input, Card, Modal, zwei Patterns, sieben Tokens, fünf-5 Regeln) für ein fiktionales „Aurora Design System“. Kopieren Sie .design/registry/ von dort als Ausgangspunkt oder führen Sie aus:

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

Nutzungsvertrag für KI-Agenten

Mit diesem Server verbundene Agents sollten:

1. Die Registry abfragen, bevor sie eine wiederverwendbare UI-Komponente erstellen.

2. Exakte Zuordnungen zuerst auflösen – niemals eine Zuordnung raten, wenn eine existieren könnte.

3. Vorhandene registrierte Implementierungen wiederverwenden, statt sie zu duplizieren.

4. Relevante Tokens und Patterns lesen, bevor Stile/Layouts erzeugt werden.

5. unresolved ehrlich melden, statt eine Zuordnung zu erfinden.

6. Niemals eine neue kanonische Komponente erzeugen, wenn registry_find_component / registry_find_by_design_reference zeigt, dass eine äquivalente bereits existiert.

7. Nur dann eine neue Komponente vorschlagen, wenn keine passende vorhandene existiert.

8. Alle Mutationen der Registry als explizite, bewusste Handlungen betrachten – nicht als beiläufige Nebeneffekte.

9. Die Registry als maßgeblich für projektsprezifische Design-↔-Code-Fakten betrachten.

Gleichzeitig ist die Registry kein Ersatz für gutes Engineering-Webels? Wenn sie unvollständig ist oder ein besser wartbarer Ansatz offensichtlich verfügbar ist, sollte ein Agent das ausdrücklich sagen – er sollte belegte Registry-Fakten von erschlossenen Informationen und Empfehlungen unterscheiden –, statt sich einer unvollständigen Registry mechanisch unterzuwerfen.

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

Siehe CONTRIBUTING.md für die Design-Prinzipien des Projekts, bevor Sie einen PR eröffnen.

Einschränkungen & zukünftige Verbesserungen

• Heute ist nur ein lokaler, dateibasierter Registry-Provider enthalten. Der RegistryService-Layer ist Provider-unabhängig, sodass ein Remote-/API-basierter Provider möglich ist, ohne die MCP-Tool-Logik zu verändern – derzeit nur noch nicht umgesetzt.

• Es gibt noch kein optionales HTTP/SSE-Transport (nur stdio), wie das Prinzip „die erste Version nicht überengagieren“.

• registry_find_component ist eine deterministische Teilstrings-Sache, keine Rang- oder Fuzzy-Suche – das ist beabsichtigt, bedeutet aber, dass sehr vage Anfragen leer ausgehen können, wo man als Mensch einen Treffer mit Näherungswert, annäherndes Ergebnis erwart; and.

• Kein eingebauter Figma-/Sketch-/Penpot-API-Client – dieser Server bleibt bewusst downstream von Werkzeugen wie Figma MCP und dupliziert deren Arbeit nicht.

Lizenz

MIT