@higinio/design-mcp

Servidor MCP (Model Context Protocol) que expone los sistemas de diseño de Higinio —tokens, componentes, reglas y validación— como herramientas, recursos y prompts consumibles desde cualquier IDE o cliente compatible con MCP. Funciona en dos modos: stdio (local, el IDE lanza el proceso) y HTTP (servicio remoto, p. ej. en Dokploy).

Puesta en marcha (local)

Requiere Node.js >= 20.

cd mcp
npm install
npm run sync-assets
npm run build

• npm install dispara automáticamente el script prepare (sync-assets && build), así que en un git clone limpio con solo npm install ya queda todo listo.
• sync-assets copia los tokens y la documentación de cada sistema (celeste/, nocturna/) a mcp/assets/ (carpeta gitignored, se regenera siempre desde la fuente).
• build compila src/ a dist/ con tsc. Los binarios ejecutables son dist/index.js (server MCP, bin design-mcp) y dist/cli.js (linter, bin design-lint; ver CLI / pre-commit), ambos con shebang #!/usr/bin/env node.

Para desarrollo sin compilar: npm run dev (ejecuta src/index.ts con tsx). Para correr los tests: npm test.

Conectarlo a un IDE

El servidor habla MCP por stdio. Cualquier cliente que soporte servidores MCP locales puede lanzarlo con node apuntando al binario compilado.

Claude Code / Claude Desktop — .mcp.json

{ "mcpServers": { "design": { "command": "node", "args": ["ABS/RUTA/mcp/dist/index.js"] } } }

Cursor — .cursor/mcp.json

Mismo formato (mcpServers):

{ "mcpServers": { "design": { "command": "node", "args": ["ABS/RUTA/mcp/dist/index.js"] } } }

VS Code — .vscode/mcp.json

VS Code usa la clave servers, no mcpServers:

{ "servers": { "design": { "command": "node", "args": ["ABS/RUTA/mcp/dist/index.js"] } } }

En los tres casos, reemplaza ABS/RUTA/mcp/dist/index.js por la ruta absoluta real al archivo compilado (por ejemplo C:/Users/higinio/Documents/Proyectos/Diseño/mcp/dist/index.js), usando / en vez de \ para evitar problemas de escape en JSON.

Nota: el paquete ya está publicado en npm como @higinio/design-mcp, así que la config puede usar npx directamente y deja de depender de una ruta local:

{ "command": "npx", "args": ["-y", "@higinio/design-mcp"] }

Modo servidor (HTTP / producción)

Además de stdio, el servidor corre como servicio HTTP (transporte streamable, stateless) para consumirlo en remoto —por ejemplo desplegado en Dokploy—. Se activa con variables de entorno:

| Variable | Efecto | |---|---| | MCP_TRANSPORT=http (o definir PORT) | Arranca en modo HTTP en vez de stdio | | PORT | Puerto (por defecto 3000) | | MCP_AUTH_TOKEN | Requerido en HTTP: exige Authorization: Bearer <token> en POST /mcp. Sin él el server no arranca (salvo MCP_ALLOW_NO_AUTH=1) | | MCP_BIND | Interfaz de escucha; por defecto 127.0.0.1 (solo local). En contenedor se usa 0.0.0.0 | | MCP_ALLOWED_HOSTS | Lista (separada por comas) de Host permitidos; protege contra DNS rebinding. Ej.: design-mcp.tudominio.com | | MCP_ALLOWED_ORIGINS | Lista de Origin permitidos (opcional) |

Endpoints: POST /mcp (protocolo MCP) y GET /health (health check). Ejemplo local:

cd mcp && npm run build
MCP_TRANSPORT=http PORT=3000 MCP_AUTH_TOKEN=un-secreto node dist/index.js
# -> [design-mcp] HTTP escuchando en 127.0.0.1:3000 (POST /mcp · auth: bearer)

Para desplegarlo en Dokploy y conectarlo desde Claude Code (local o remoto), ver ../docs/despliegue-dokploy.md.

Herramientas

Tools:

• list_design_systems — lista los sistemas disponibles con su metadata (filosofía, paleta, fuentes).
• get_token — resuelve un alias semántico (p. ej. --accent) o un token DTCG por path (p. ej. color.primary.500) a su valor.
• search_tokens — busca tokens por substring en su path o valor.
• list_components — lista los componentes documentados del sistema.
• get_component_spec — devuelve la especificación (estados, medidas, variantes) de un componente del DESIGN.md.
• get_rules — reglas duras del sistema y referencia rápida (paleta, fuentes, filosofía).
• validate_code — valida CSS o HTML contra las reglas duras del sistema (hex directos, primary-300 como texto, doble primario, contraste AA, outline-none sin reemplazo, div clicable sin semántica, puntos suspensivos como tres puntos, deriva de border-radius y de font-size fuera de las escalas del sistema, letter-spacing ≤ −0.04em).
• validate_motion — audita CSS/HTML/JS contra las reglas de motion del sistema (transition:all, ease-in en entradas, animar propiedades de layout, blur, duración > el techo del sistema (--duration-page), scale(0), rebote en utilitarios, overshoot excesivo, blur/hover-scale/stagger repetidos, pulsing, hover con transform sin gating @media (hover: hover)). Ver §11.6 del DESIGN.md.
• check_slop — detecta clichés de diseño generado por IA en CSS/HTML (gradientes, glassmorphism, fuentes genéricas, tipografía descuidada, copy de marketing, cadencia aforística, eyebrow-spam, presupuesto de glow en dark, borde de acento lateral), adaptado a las reglas de la marca.
• checklist_preflight — checklist estático de pre-producción sobre HTML/CSS (lang, title, meta, canonical, un h1, theme-color, noindex, skip link, saltos de heading, img alt/dimensiones/src, botón-icono sin label, zoom, autocomplete, paste bloqueado, enlaces genéricos, SRI, font-display). Los umbrales de runtime (Core Web Vitals, Lighthouse) se miden con Lighthouse/PageSpeed, no aquí.
• generate_snippet — genera un snippet de un componente usando solo aliases semánticos (CSS, Tailwind o React).

Prompts:

• build_ui — instrucciones para construir UI respetando el sistema de diseño elegido.
• audit_ui — instrucciones para auditar código o una pantalla contra el sistema de diseño elegido.
• audit_diseno — instrucciones para auditar una interfaz con la rúbrica de 14 dimensiones, Nielsen /40, carga cognitiva y las 5 personas, con salida por fases.
• recomendar_direccion — dado un brief de producto, recomienda el sistema (Celeste vs Nocturna), los valores de dial (variación/motion/densidad acotados) y una dirección de diseño sobria.
• recomendar_grafica — dada una descripción de datos, recomienda el tipo de gráfica, la paleta (categórica/secuencial/divergente/estado) y el fallback de accesibilidad.

Resources:

• design://systems — índice de sistemas disponibles y su metadata.
• design://<sistema>/<archivo> — archivo crudo de un sistema (tokens.json, tokens.css, tailwind.css, framework.css, design-doc.md, styleguide.html), con <sistema> = celeste o nocturna.

CLI / pre-commit

Los cuatro validadores puros (validate_code, validate_motion, check_slop, checklist_preflight) también se pueden correr sobre archivos locales sin pasar por MCP, con el binario design-lint. Como el paquete está publicado en npm, en otro proyecto lo ejecutas con npx sin instalar nada; dentro de este repo apuntas a dist/cli.js:

design-lint --system celeste|nocturna [--lang css|html|js] [--json] <archivos o globs...>

# desde cualquier proyecto (paquete publicado)
npx @higinio/design-mcp design-lint --system celeste "src/**/*.css"

# dentro de este repo (binario compilado)
node dist/cli.js --system celeste src/styles/*.css
node dist/cli.js --system nocturna --json "src/**/*.html"
node dist/cli.js --system celeste --lang css tokens.txt   # fuerza el lenguaje

• Lenguaje: se infiere por extensión (.css → css · .html/.htm → html · .js/.mjs/.cjs/.ts/.jsx/.tsx → js) salvo que se pase --lang. Archivos con extensión no soportada se omiten en silencio. Para js solo corre validate_motion (los otros tres validadores son de CSS/HTML).
• Globs: soporta * y ** (resueltos por el propio CLI, relativos al directorio actual; ignora node_modules y .git). Entre comillas para que no los expanda el shell.
• Salida: hallazgos agrupados por archivo con línea, severidad, regla, tool de origen y fix; --json para salida machine-readable (la misma estructura LintSummary).
• Exit codes: 0 = sin hallazgos de severidad alta · 1 = hay al menos un hallazgo de severidad alta · 2 = error de uso (argumentos inválidos, ningún archivo coincide). El mapeo de severidad es directo sobre el level de cada violación: alta = error (rompe el build) · media = warn · baja = info (warn/info se reportan pero no cambian el exit code).
• Excepciones (design-lint-ignore): un comentario /* design-lint-ignore: <regla>[, <regla>...] */ (CSS/JS) o <!-- design-lint-ignore: <regla> --> (HTML) suprime los hallazgos de esas reglas en la línea inmediatamente siguiente (también vale en la misma línea de la infracción). La coincidencia es por número de línea aproximado: los hallazgos a nivel de bloque o de archivo (reportados como línea 0, p. ej. contraste-aa, un-solo-primario, falta-reduced-motion) no son suprimibles con este mecanismo — se arreglan o se aceptan.

Hook de pre-commit

Ejemplo de .git/hooks/pre-commit (dale permisos de ejecución) que lintea solo lo staged:

#!/bin/sh
files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(css|html?|m?js|tsx?|jsx)$')
[ -z "$files" ] && exit 0
node mcp/dist/cli.js --system celeste $files

Con exit code 1 (hallazgos de severidad alta) el commit se bloquea; los warn/info se muestran pero dejan pasar.

El concepto de CLI de detección (globs, --json, exit codes por severidad) está adaptado del detect.mjs de Impeccable — pbakaus/impeccable (Apache-2.0); la implementación aquí corre los validadores propios del sistema.

Presupuesto de contexto

Registrar este server no es gratis: el cliente inyecta en cada conversación los nombres, descripciones y schemas de las 11 tools (y, según el cliente, los 5 prompts y los resources). Medido sobre src/server.ts: las descripciones y títulos suman ~2 800 caracteres (~1 900 solo las tools; checklist_preflight, check_slop y validate_motion son las más largas con ~320-570 c/u). Sumando nombres, claves y enums de los input schemas serializados, el tools/list completo queda en el orden de ~4 500 caracteres ≈ 1 100-1 400 tokens; con prompts listados, ~1 500 tokens en total. Es un costo fijo por conversación, no por llamada.

Recomendación por caso:

• stdio (IDE local, un solo usuario): la opción por defecto; sin red ni auth, y el costo de contexto es el mismo que en HTTP.
• HTTP (Dokploy, equipo, o varios clientes contra una sola instancia): paga el mismo contexto por conversación pero evita duplicar proceso y assets por IDE, y permite consumirlo desde máquinas sin el repo.
• Si el presupuesto aprieta en un cliente concreto, registra el server solo en los proyectos donde se usa (config por proyecto, no global) — y al editar descripciones de tools, mantenlas cortas: cada carácter se paga en todas las conversaciones.

Actualizar tras cambiar un sistema

Los tokens y la documentación que sirve el MCP son una copia sincronizada (mcp/assets/), no la fuente de verdad. Si editas los tokens o el DESIGN.md de un sistema, hay que volver a sincronizar y recompilar:

npm run sync-assets && npm run build

Si el IDE mantiene el proceso del servidor corriendo, reinícialo después para que recargue los assets actualizados.

Relación con las skills

Las skills de Claude (celeste-clasica-design, nocturna-electrica-design) son la "voz experta": encapsulan criterio, ejemplos y guía narrativa para construir UI con estos sistemas dentro de Claude. Este MCP es la fuente de datos portátil de esos mismos sistemas —tokens, specs de componentes, reglas y validación— accesible desde cualquier IDE o cliente MCP, no solo Claude. Ambos se complementan: la skill explica el criterio, el MCP expone los datos exactos y permite validarlos programáticamente en cualquier entorno.