@higinio/design-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Higinio Sosa. Todos los derechos reservados.
+
+Este software y los sistemas de diseño que contiene ("Celeste Clásica" y
+"Nocturna Eléctrica"), incluyendo sus tokens, componentes, documentación y
+activos, son propiedad de Higinio Sosa y están destinados exclusivamente a
+uso en sus propios productos.
+
+No se concede ninguna licencia, expresa o implícita, para usar, copiar,
+modificar, fusionar, publicar, distribuir, sublicenciar o vender copias de
+este software ni de su definición de marca, en su totalidad o en parte, sin
+autorización previa y por escrito de Higinio Sosa.
+
+EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O
+IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD
+PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO EL AUTOR SERÁ
+RESPONSABLE DE NINGUNA RECLAMACIÓN, DAÑO U OTRA RESPONSABILIDAD DERIVADA DEL
+USO DEL SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @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`
+
+```json
+{ "mcpServers": { "design": { "command": "node", "args": ["ABS/RUTA/mcp/dist/index.js"] } } }
+```
+
+### Cursor — `.cursor/mcp.json`
+
+Mismo formato (`mcpServers`):
+
+```json
+{ "mcpServers": { "design": { "command": "node", "args": ["ABS/RUTA/mcp/dist/index.js"] } } }
+```
+
+### VS Code — `.vscode/mcp.json`
+
+VS Code usa la clave `servers`, no `mcpServers`:
+
+```json
+{ "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:** una vez publicado el paquete en npm, la config se simplifica y deja de depender de una ruta local:
+
+```json
+{ "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`](../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` (compilado en `dist/cli.js`):
+
+```
+design-lint --system celeste|nocturna [--lang css|html|js] [--json] <archivos o globs...>
+
+# ejemplos
+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:
+
+```sh
+#!/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.