Design-Code Registry MCP

任意のデザインツールとフレームワークをまたいで、デザインコンポーネント、トークン、パターンをコード実装へマッピングする、決定的（deterministic）でプロジェクトに依存しない MCP サーバー。

Figma Code Connect に代わる、軽量で git に馴染む選択肢です。MCP 互換の AI コーディングエージェント（Claude Code、Cursor、Codex、OpenCode など）がクエリできる、汎用の知識レイヤーとして構築されています。

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

なぜ存在するのか

AI コーディングエージェントはコードを書くのは得意ですが、「このプロジェクトには Button コンポーネントはすでにあるのか？ あるとしたら、それは何という名前で、どこにあるのか？」を知るのは苦手です。現在、そのような知識は、エージェントの漠然とした推論（信頼性が低い）か、特定のデザインツール＋フレームワークの組み合わせ（Figma Code Connect。React/Figma 専用）に強く結びついています。

中心となる原則：正確なレジストリデータは、AI の推論に勝る。 レジストリに明示的なマッピングがあれば、エージェントはそれを推測する必要はありません。なければ、エージェントは何か作るのではなく「unresolved」と伝えるべきです。

このプロジェクトは：

• AI モデルではありません。 MCP ツールを通じて公開される、構造化された構造化レイヤーです。

• ベクターデータベース / RAG ではありません。 解決は完全一致のみ（id、デザイン参照、正式名、エイリアス）で、埋め込みやあいまい類似度は使われません。

• 特定のフレームワークやデザインツールには縛られません。 React、Vue、Svelte、SwiftUI、Flutter、HTML、そして Figma、Sketch、Penpot、その他すべては、スキーマ上の単なる文字列であり、コード内の特殊ケースではありません。

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)

サーバー（この npm パッケージ）は汎用的で、まったく異なるプロジェクト間で再利用できます。レジストリ（プロジェクト内の .design/registry/）には、プロジェクト固有の事実がすべて格納されます。プレーンな JSON ファイルとして、git で読み取り可能、差分可能、マージ可能です。

Registry concepts

1 つのコンポーネントに複数の実装を持たせることができます。プロジェクトがそれ必要とするなら、同じデザイン概念を React、Vue、SwiftUI、Flutter に同時にマッピングできます。

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

デザイン参照も同様に汎用です。tool は組み合わせではなくオープンな文字列なので、新しいデザインツールのサポートを追加しても、スキーマのマイグレーションは一切必要ありません。

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

完全な、コメント付きスキーマ（Zod）は src/schema/ を、完全なサンプルプロジェクトは examples/fictional-project/ を参照してください。

決定的解決

registry_find_by_design_reference と基盤となるリゾルバは決して推測しません。彼らはこの固定順序で試し、一致するものが出た最初の戦略で停止します。

1. 完全一致のデザイン参照（tool + node/file/url/name）

2. 完全一致のレジストリ id

3. 完全一致の正規名（canonical name）

4. 明示的なエイリアス

5. それ以外は: unresolved

ある戦略が複数のコンポーネントに一致した場合、解決はそこで停止し、ambiguous をすべての候補とともに 报告 します。黙ってどれか選ぶことはありません。

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

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

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

MCP ツール

Read

Write

ミューテーションの安全: 存在する id を作成するのはエラーです（代わりに update を使ってください）。存在しない id を更新するのはエラーです（代わりに create を使ってください）。コンポーネントは破壊的な削除ができません。registry_deprecate_component を使用し、履歴を git に残します。

Validation

registry_validate（CLI の design-code-registry validate も同様）は、次のレジストリ全体をチェックします：

• コンポーネント/トークン/パターン/ルール内の重複する id

• 重複したデザイン参照（2 つのコンポーネントが同じ Figma ノードを主張している）

• 壊れた参照（存在しないコンポーネントを指すパターン、replacedBy なしの非推奨、どこも指さない appliesTo.id）

• 循環するパターン参照（パターン A → 関連パターン B → 関連パターン A）

• 承認されたコンポーネントでの実装欠落（エラーではなく警告です）

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

MCP ツールと同じ RegistryService を基にした、人間向けインターフェース。2 つの挙動がズレることはありません。

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

すべてのコマンドは -p, --path <path> で特定のレジストリを指定できます。または DESIGN_REGISTRY_PATH を読み取ります。

インストール

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

Claude Code セットアップ

Claude Code の MCP 設定（プロジェクトルートの .mcp.json、または claude mcp add コマンド）にサーバーを追加します：

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

あるいは、明示的なレジストリパスを指定する場合（モノレポで便利）：

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

このサーバーは、stdio 経由でどの MCP 互換クライアントとも連携できます。Claude Code はそのうちの 1 つにすぎず、サーバー自体の依存ではありません。

Figma MCP 連携

このサーバーは、Figma API と通信したり、Figma ファイルを調べたりするものではありません。それは、Figma 独自の MCP server の役目です。この 2.2 つは補完し合うように設計されています。

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

典型的なエージェントのワークフロー：

1. エージェントは Figma MCP に選択ノードの fileKey / nodeId を問い合わせます。

2. エージェントは、このサーバーに対して registry_find_by_design_reference を呼び出し、これらの識別子を渡します。

3. resolved の場合、エージェントは返された実装を再利用します。unresolved の場合、エージェントはプロジェクトのルールに従って新しいコンポーネントを提案し、registry_create_component で登録することができます。

マルチフレームワークの例

単一のレジストリで、まったく異なるコードベースにまたがる実装を記述できます：

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

このうちどれをプロジェクトが使うかによって、サーバーの動作が変わることはありません。スキーマでは language と framework が単なる開かれた文字列として扱われるからです。

サンプルプロジェクト

examples/fictional-project/ には、架空の「Aurora Design System」用の、検証済みの完全な例（Button、Input、Card、Modal、2 つのパターン、7 つのトークン、5 つのルール）が含まれています。その中の .design/registry/ を出発点としてコピーするか、次を実行してください：

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

AI エージェント利用契約

このサーバーに接続されたエージェントは、以下を行ってください。

1. 再利用可能な UI コンポーネントを作成する前にレジストリを照会する。

2. まず正確なマッピングを解決する。マッピングが存在そうなら決して推測しない。

3. 既存の登録済み実装を複製ではなく再利用する。

4. スタイルやレイアウトを生成する前に、関連するトークンとパターンを読む。

5. マッピングをでっち上げず、正直に unresolved を報告する。

6. registry_find_component・registry_find_by_design_reference が同等の既存コンポーネントを示しているなら、新しい正式（canonical）コンポーネントを絶対に作成しない。

7. 適切な既存コンポーネントがない場合のみ、新しいコンポーネントを提案する。

8. レジストリへのすべての変更を、単なる偶発的な副作用ではなく、明示的で意図的な操作として扱う。

9. プロジェクト固有の Design ↔ Code 事項について、レジストリを正当なもの（authoritative）として扱う。

同じ一方で、レジストリは優れたエンジニアリング判断までを持つものではありません。不十分だったり、より保守しやすい方法が明らかにある場合は、エージェントはそれを言うべきです。つまり 検証済みのレジストリ事実、推測される情報、推奨事項 を区別し、不完全なレジストリに機械的に従うのではなく、その旨を伝えてください。

開発

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

PR を開く前に、プロジェクトの設計原則について CONTRIBUTING.md を読んでください。

制限事項と将来の改善

• 現在出荷されているのはローカルのファイルベース レジストリプロバイダーだけです。RegistryService レイヤーはプロバイダ非依存のため、MCP ツールのロジックを変えずにリモート/API バックエンドのプロバイダーも可能です。ただし、まだ実装されていません。

• HTTP/SSE トランスポートはまだありません（stdio のみ）。「最初のバージョンは過剰設計しない」という原則に従っています。

• registry_find_component は決定的な部分文字列検索であり ランキング/ あいまい検索ではありません。意図的ですが、人間が近似一致を期待するような大雑把なクエリでは、何も返らないことがあります。

• Figma / Sketch / Penpot の API クライアントは組み込みません。このサーバーは、Figma MCP のようなツールの役割を複製するのではなく、意図的にそれらの後段に留まります。

ライセンス

MIT