Design-Code Registry MCP

Детерминированный, не зависящий от проекта MCP сервер, который сопоставляет дизайн-компоненты, токены и паттерны с их реализациями в коде — для любого инструмента дизайна и любого фреймворка.

Это лёгкая, дружелюбная к git альтернатива Figma Code Connect, построенная как универсальный слой знаний, к которому может обращаться любой MCP-совместимый ИИ-агент для написания кода (Claude Code, Cursor, Codex, OpenCode, ...).

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

Зачем это существует

ИИ-агенты для написания кода хорошо пишут код, но плохо знают: «есть ли в этом проекте уже компонент Button, и если да, как он называется и где находится?» Сегодня эти знания либо живут в размытых выводах агента (ненадёжно), либо жёстко привязаны к конкретной связке инструмента дизайна и фреймворка (Figma Code Connect, который работает только с React/Figma).

Основной принцип: точные данные реестра лучше, чем выводы ИИ. Если в реестре есть явное сопоставление, агент никогда не должен его угадывать. Если его нет, агенту следует сообщить «unresolved», а не выдумывать.

Этот проект:

• Не ИИ-модель. Это структурированный слой знаний, доступный через MCP-инструменты.

• Не векторная база данных / RAG. Разрешение выполняется только по точному совпадению (id, ссылка на дизайн, каноническое имя, алиас) — никаких эмбеддингов или нечёткого сходства.

• Не привязан к какому-либо фреймворку или инструменту дизайна. React, Vue, Svelte, SwiftUI, Flutter, HTML — и Figma, Sketch, Penpot или что угодно ещё — это просто строки в схеме, а не особые случаи в коде.

Архитектура

                    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-файлов, которые читаемы, поддаются diff и merge в git.

Концепции реестра

Один компонент может иметь несколько реализаций — одна и та же дизайн-концепция, сопоставленная с 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" }

См. src/schema/ для полной, документированной схемы (Zod), и examples/fictional-project/ для полного рабочего примера.

Детерминированное разрешение

registry_find_by_design_reference и лежащий в основе резолвер никогда не угадывают. Они пробуют в следующем фиксированном порядке и останавливаются на первой стратегии, которая даёт совпадение:

1. Точная ссылка на дизайн (tool + node/file/url/name)

2. Точный id реестра

3. Точное каноническое имя

4. Явный алиас

5. В противном случае: unresolved

Если стратегия соответствует более чем одному компоненту, разрешение останавливается и сообщает ambiguous со всеми кандидатами — оно никогда не выбирает молча:

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

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

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

MCP-инструменты

Чтение

Запись

Безопасность мутаций: создание id, который уже существует, — ошибка (используйте update); обновление id, которого не существует, — ошибка (используйте create); деструктивного удаления компонентов нет — используйте registry_deprecate_component, чтобы история сохранялась в git.

Валидация

registry_validate (и design-code-registry validate в CLI) проверяет весь реестр на:

• Дубликаты id внутри компонентов/токенов/паттернов/правил

• Дубликаты ссылок на дизайн (два компонента, претендующих на один и тот же узел 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

Интерфейс для человека поверх того же RegistryService, который используют MCP-инструменты — поведение никогда не расходится между ними.

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

Добавьте сервер в конфигурацию MCP Claude Code (.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"]
    }
  }
}

Сервер работает с любым MCP-совместимым клиентом через stdio — Claude Code — один из нескольких клиентов, а не зависимость самого сервера.

Интеграция с Figma MCP

Этот сервер не общается с Figma API и не просматривает файлы Figma — это задача собственного MCP-сервера Figma. Они спроектированы как дополняющие друг друга:

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/ содержит полный, проверенный пример реестра (Button, Input, Card, Modal, два паттерна, семь токенов, пять правил) для вымышленной «Aurora Design System». Скопируйте .design/registry/ оттуда как отправную точку или запустите:

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

Контракт использования для ИИ-агентов

Агенты, подключённые к этому серверу, должны:

1. Запрашивать реестр до создания любого переиспользуемого UI-компонента.

2. Сначала разрешать точные сопоставления — никогда не угадывать сопоставление, если оно может существовать.

3. Переиспользовать существующие зарегистрированные реализации, а не дублировать их.

4. Читать соответствующие токены и паттерны перед генерацией стилей/макета.

5. Честно сообщать unresolved, а не выдумывать сопоставление.

6. Никогда не создавать новый канонический компонент, когда registry_find_component / registry_find_by_design_reference показывает, что эквивалентный уже существует.

7. Предлагать новый компонент только тогда, когда нет подходящего существующего.

8. Считать все мутации реестра явными, обдуманными действиями, а не побочными эффектами.

9. Считать реестр авторитетным источником для специфичных для проекта фактов «Дизайн ↔ Код».

В то же время реестр не заменяет здравый инженерный смысл: когда он неполон или явно доступен более поддерживаемый подход, агент должен об этом сказать — различая проверенные факты реестра, выводы и рекомендации — а не механически подчиняться неполному реестру.

Разработка

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

См. CONTRIBUTING.md с принципами дизайна проекта перед открытием PR.

Ограничения и будущие улучшения

• Сегодня поставляется только локальный, файловый провайдер реестра. Слой RegistryService не зависит от провайдера, поэтому удалённый/API-провайдер возможен без изменения логики MCP-инструментов — просто пока не реализован.

• Пока нет опционального HTTP/SSE-транспорта (только stdio), согласно принципу «не переусложняйте первую версию».

• registry_find_component — это детерминированный поиск подстроки, а не ранжированный/нечёткий поиск — намеренно, но это означает, что очень свободные запросы могут не вернуть ничего там, где человек ожидал бы близкое совпадение.

• Нет встроенного клиента Figma/Sketch/Penpot API — этот сервер намеренно остаётся ниже по потоку от таких инструментов, как Figma MCP, а не дублирует их работу.

Лицензия

MIT