Design-Code Registry MCP

Un servidor MCP determinista y agnóstico al proyecto que mapea componentes de diseño, tokens y patrones a sus implementaciones de código, en cualquier herramienta de diseño y cualquier framework.

Es una alternativa ligera y amigable con git a Figma Code Connect, construida como una capa de conocimiento genérica que cualquier agente de IA de codificación compatible con MCP (Claude Code, Cursor, Codex, OpenCode, ...) puede consultar.

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

Por qué existe esto

Los agentes de IA de codificación son buenos escribiendo código, pero malos sabiendo "¿este proyecto ya tiene un componente Button y, si es así, cómo se llama y dónde vive?". Hoy ese conocimiento o bien vive en la inferencia difusa del agente (poco fiable) o está fuertemente acoplado a un par específico de herramienta de diseño + framework (Figma Code Connect, que es solo React/Figma).

Principio fundamental: los datos exactos del registro superan a la inferencia de la IA. Si el registro tiene un mapeo explícito, el agente nunca debería necesitar adivinarlo. Si no lo tiene, se le debe decir "unresolved" en lugar de inventarse algo.

Este proyecto es:

• No es un modelo de IA. Es una capa de conocimiento estructurado expuesta a través de herramientas MCP.

• No es una base de datos vectorial / RAG. La resolución es solo de coincidencia exacta (id, referencia de diseño, nombre canónico, alias), nunca embeddings ni similitud difusa.

• No está ligado a ningún framework ni herramienta de diseño. React, Vue, Svelte, SwiftUI, Flutter, HTML — y Figma, Sketch, Penpot o cualquier otra cosa — son solo cadenas en el esquema, no casos especiales en el código.

Arquitectura

                    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)

El servidor (este paquete npm) es genérico y reutilizable en proyectos completamente distintos. El registro (.design/registry/ en tu proyecto) es donde viven todos los hechos específicos del proyecto, como archivos JSON planos que se pueden leer, comparar y fusionar en git.

Conceptos del registro

Un solo componente puede tener múltiples implementaciones: el mismo concepto de diseño mapeado a React, Vue, SwiftUI y Flutter simultáneamente, si tu proyecto lo necesita:

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

Las referencias de diseño también son genéricas: tool es una cadena abierta, no una enumeración, por lo que añadir soporte para una nueva herramienta de diseño nunca requiere una migración de esquema:

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

Consulta src/schema/ para ver el esquema completo comentado (Zod), y examples/fictional-project/ para un ejemplo completo y funcional.

Resolución determinista

registry_find_by_design_reference y el resolvedor subyacente nunca adivinan. Intentan, en este orden fijo, y se detienen en la primera estrategia que produce una coincidencia:

1. Referencia de diseño exacta (herramienta + nodo/archivo/url/nombre)

2. Id de registro exacto

3. Nombre canónico exacto

4. Alias explícito

5. De lo contrario: unresolved

Si una estrategia coincide con más de un componente, la resolución se detiene ahí e informa ambiguous con todos los candidatos; nunca elige uno en silencio:

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

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

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

Herramientas MCP

Lectura

Escritura

Seguridad de mutación: crear un id que ya existe es un error (usa update); actualizar un id que no existe es un error (usa create); no hay borrado destructivo para componentes: usa registry_deprecate_component para que el historial sobreviva en git.

Validación

registry_validate (y design-code-registry validate en la CLI) comprueba todo el registro en busca de:

• Ids duplicados dentro de componentes/tokens/patrones/reglas

• Referencias de diseño duplicadas (dos componentes reclamando el mismo nodo de Figma)

• Referencias rotas (un patrón que apunta a un componente inexistente, un replacedBy de deprecación que no apunta a nada, un appliesTo.id de una regla que no apunta a nada)

• Referencias circulares de patrones (patrón A → patrón relacionado B → patrón relacionado A)

• Implementaciones faltantes en componentes aprobados (advertencia, no 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

Interfaz humana sobre el mismo RegistryService que usan las herramientas MCP: el comportamiento nunca se desvía entre ambos.

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

Cada comando acepta -p, --path <ruta> para apuntar a un registro específico, o lee DESIGN_REGISTRY_PATH.

Instalación

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

Configuración de Claude Code

Añade el servidor a tu configuración MCP de Claude Code (.mcp.json en la raíz de tu proyecto, o mediante claude mcp add):

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

O, con una ruta de registro explícita (útil en un monorepo):

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

El servidor funciona con cualquier cliente compatible con MCP a través de stdio: Claude Code es un cliente entre varios, no una dependencia del propio servidor.

Integración con Figma MCP

Este servidor no habla con la API de Figma ni inspecciona archivos de Figma; eso es trabajo del propio servidor MCP de Figma. Ambos están diseñados para ser complementarios:

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

Un flujo de trabajo típico de agente:

1. El agente pide al Figma MCP el fileKey/nodeId del nodo seleccionado.

2. El agente llama a registry_find_by_design_reference en este servidor con esos identificadores.

3. Si se resuelve, el agente reutiliza la implementación devuelta. Si no se resuelve, el agente puede proponer un nuevo componente (según las reglas de tu proyecto) y registrarlo con registry_create_component.

Ejemplo multi-framework

Un solo registro puede describir implementaciones en bases de código totalmente diferentes:

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

Nada del servidor cambia según cuál de estos use tu proyecto: el esquema trata language y framework como cadenas abiertas.

Proyecto de ejemplo

examples/fictional-project/ contiene un registro de ejemplo completo y validado (Button, Input, Card, Modal, dos patrones, siete tokens, cinco reglas) para un ficticio "Aurora Design System". Copia .design/registry/ desde allí como punto de partida, o ejecuta:

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

Contrato de uso para agentes de IA

Los agentes conectados a este servidor deben:

1. Consultar el registro antes de crear cualquier componente de interfaz reutilizable.

2. Resolver primero los mapeos exactos: nunca adivinar un mapeo cuando podría existir.

3. Reutilizar las implementaciones registradas existentes en lugar de duplicarlas.

4. Leer los tokens y patrones relevantes antes de generar estilos/diseño.

5. Informar unresolved con honestidad en lugar de inventar un mapeo.

6. Nunca crear un nuevo componente canónico cuando registry_find_component / registry_find_by_design_reference muestre que ya existe uno equivalente.

7. Solo proponer un nuevo componente cuando no exista ninguno apropiado.

8. Tratar todas las mutaciones del registro como acciones explícitas y deliberadas, no como efectos secundarios incidentales.

9. Tratar el registro como autoritativo para los hechos de Diseño ↔ Código específicos del proyecto.

Al mismo tiempo, el registro no posee buen criterio de ingeniería: cuando esté incompleto o exista claramente un enfoque más mantenible, un agente debería decirlo, distinguiendo hechos verificados del registro de información inferida y recomendaciones, en lugar de obedecer mecánicamente un registro incompleto.

Desarrollo

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

Consulta CONTRIBUTING.md para conocer los principios de diseño del proyecto antes de abrir un PR.

Limitaciones y mejoras futuras

• Hoy solo se distribuye un proveedor de registro local basado en archivos. La capa RegistryService es agnóstica al proveedor, por lo que es posible un proveedor remoto/API sin tocar la lógica de las herramientas MCP, pero aún no está implementado.

• Aún no hay transporte HTTP/SSE opcional (solo stdio), según el principio de "no sobre-ingeniería en la primera versión".

• registry_find_component es una búsqueda determinista de subcadenas, no una búsqueda clasificada/difusa; por diseño, pero significa que consultas muy vagas pueden no devolver nada donde un humano esperaría una coincidencia aproximada.

• No hay cliente de API integrado para Figma/Sketch/Penpot: este servidor se mantiene intencionalmente aguas abajo de herramientas como Figma MCP en lugar de duplicar su trabajo.

Licencia

MIT