@ng-solid/mcp 22.0.0

package/GUIDE.md

@@ -0,0 +1,292 @@
+# Guía de `@ng-solid/mcp`
+
+Arquitectura, pipeline de datos y mantenimiento del servidor MCP del design
+system Arvisfy. Para instalación y uso como consumidor, ver
+[`README.md`](./README.md).
+
+> Resumen rápido: este paquete genera en build un snapshot JSON a partir del
+> **AST real** de `@ng-solid/design-system` (Compiler API de TypeScript), del
+> preset Arvisfy, del catálogo de iconos `@ng-solid/icons` y de las 6 skills
+> en `packages/mcp/skills/`. El servidor MCP sólo lee ese snapshot por
+> stdio — nunca ejecuta Angular ni analiza código en runtime.
+
+## 1. Primera librería no-Angular del workspace
+
+`@ng-solid/mcp` es la **primera** librería de `packages/*` que no es una
+librería Angular. Eso tiene consecuencias que no aplican al resto del
+workspace:
+
+- **`@nx/dependency-checks` no aplica.** El resto de `packages/*` usa
+  `@nx/eslint-plugin`'s dependency-checks rule para validar que
+  `package.json` liste exactamente lo que el código importa; `eslint.config.mjs`
+  de este paquete no extiende esa regla porque no hay un `ng-package.json`
+  que la alimente.
+- **`flat/angular` y `flat/angular-template` no aplican.** `eslint.config.mjs`
+  extiende `../../eslint.config.mjs` explícitamente sin esos presets ni
+  `@angular-eslint/component-selector` — no hay componentes ni templates
+  Angular en este paquete.
+- **El preset de Jest del workspace no aplica.** El target `test` es
+  `nx:run-commands` puro (`node --test tests/*.test.mjs` + `node
+scripts/smoke.mjs`), usando el test runner nativo de Node 24. No hay
+  `jest.config.ts` ni `ts-jest`.
+- **El build no usa `ng-packagr`.** Es `nx:run-commands` →
+  `node scripts/prebuild.mjs && tsc -p tsconfig.lib.json && node
+scripts/postbuild.mjs`. `tsc` compila `src/` a JS plano (`module`/`moduleResolution:
+NodeNext`), y `postbuild.mjs` copia los assets (`data/`, `skills/`,
+  `README.md`, `GUIDE.md`) y escribe un `package.json` saneado en
+  `dist/packages/mcp`.
+- **No hay dependencia de código hacia `design-system`/`icons`.** El
+  prebuild lee sus ficheros fuente directamente por ruta, sin importar
+  ningún paquete `@ng-solid/*` en tiempo de build. Por eso `project.json`
+  declara `implicitDependencies: ["design-system", "icons"]` — sin eso,
+  `nx affected` nunca dispararía la regeneración del snapshot cuando esos
+  paquetes cambian.
+
+## 2. Arquitectura del pipeline de datos
+
+```text
+packages/design-system/src/**            ─┐
+packages/icons/src/lib/generated/**       ├─► scripts/prebuild.mjs ─► data/design-system.json
+apps/demo/src/app/docs.registry.ts        │                          data/icons.json
+tools/scripts/check-design-system-styles.mjs                         data/skills/<name>/SKILL.md
+packages/mcp/skills/<name>/SKILL.md      ─┘
+packages/mcp/overrides/component-notes.json
+
+data/*.json ─► src/lib/data.ts (loadSnapshot/loadIcons) ─► src/lib/{tools,resources,prompts}.ts ─► server.ts ─► stdio
+```
+
+`scripts/prebuild.mjs` orquesta un único `ts.Program` (`ts-program.mjs`,
+rooteado en `packages/design-system/src/index.ts`) y ejecuta cada extractor
+de `scripts/lib/` sobre él:
+
+| Extractor                                                                                      | Lee                                                                                   | Produce                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `extract-components.mjs` (+ `extract-members.mjs`, `extract-host.mjs`, `extract-template.mjs`) | AST de cada `@Component`/`@Directive` bajo `design-system/src/lib`                    | `ComponentDoc[]` — un doc por selector, con herencia de inputs resuelta, BEM parseado y `visibility` derivada del cierre de exports público |
+| `extract-services.mjs`                                                                         | AST de servicios `@Injectable` y providers de función exportados                      | `ServiceDoc[]`, `ProviderDoc[]`                                                                                                             |
+| `extract-tokens.mjs`                                                                           | `arvisfy.preset.ts` + `theme.utils.ts` (transpilados en memoria) + SCSS de componente | `ThemeDoc` — 3 tiers, `resolved.{light,dark}` por token de componente, `drift`                                                              |
+| `extract-registry.mjs`                                                                         | `apps/demo/src/app/docs.registry.ts`                                                  | Join `slug ↔ selector` que añade `category`/`summary`/`variants`/`snippet` a los `ComponentDoc` del registro                                |
+| `extract-icons.mjs`                                                                            | `packages/icons/src/lib/generated/{catalog.json,index.ts,metadata.ts}`                | `IconDoc[]` (name ↔ symbol, sin cuerpos SVG)                                                                                                |
+| `extract-guides.mjs` (Fase 5, este paquete)                                                    | `packages/mcp/skills/<name>/SKILL.md` + el resto de extractores (para interpolar)     | `GuideDoc[]` embebido en el snapshot, y el `Map` de ficheros resueltos que `prebuild.mjs` escribe en `data/skills/`                         |
+
+`overrides/component-notes.json` inyecta `pitfalls`/`relatedComponents`
+escritos a mano por selector — lo único que ningún AST puede producir.
+
+`scripts/lib/snapshot.mjs` ensambla ambos ficheros finales
+(`buildSnapshot`/`buildIconsSnapshot`), aplica `sanitizePaths` (ninguna ruta
+absoluta del checkout sobrevive al JSON) y fija `generatedAt: "snapshot"` —
+nunca una fecha real — para que dos ejecuciones sucesivas sean
+byte-idénticas.
+
+### Regenerar el snapshot
+
+```bash
+pnpm exec nx run mcp:build-data     # escribe packages/mcp/data/*.json y data/skills/**
+```
+
+Regenera cuando cambie cualquiera de las fuentes de la tabla anterior:
+un input()/output()/model() en design-system, el preset Arvisfy, el
+catálogo de iconos, el registro de docs de la demo, el script de
+estilos, o una `SKILL.md`.
+
+### `--check` — el gate de CI
+
+```bash
+pnpm exec nx run mcp:check-data
+```
+
+Genera el mismo snapshot **en memoria** (nunca escribe a disco) y lo
+compara byte a byte contra `data/design-system.json` / `data/icons.json`.
+Si difiere, sale con código 1 y un resumen legible (selectores
+añadidos/eliminados, inputs que cambiaron, conteo de iconos) — el mismo
+contrato que `pnpm icons:check` para el catálogo de iconos del propio
+`@ng-solid/icons`. Como `guides` vive dentro de `design-system.json`, un
+cambio no regenerado en cualquier `SKILL.md` (incluida una interpolación de
+marcador desactualizada) también hace fallar `--check`, sin lógica
+adicional: no hay un `--check` separado para `data/skills/`.
+
+### Por qué se publica desde `dist/packages/mcp`
+
+`nx.json` fija `nx-release-publish.packageRoot =
+"dist/packages/{projectName}"`, y `tools/scripts/publish.mjs` hace `chdir`
+al primer `build.outputs` del proyecto antes de `npm publish`.
+`project.json` de este paquete declara
+`build.outputs: ["{workspaceRoot}/dist/packages/mcp"]` precisamente para
+encajar en ese contrato **sin modificar** `publish.mjs` — la alternativa
+(publicar desde `packages/mcp`, como hace el blueprint de BHD) exigiría un
+override del publish script y versionar `dist/` en git.
+
+## 3. El resolutor de 3 fallbacks (`data.ts`)
+
+`src/lib/data.ts#resolveSnapshotPath` no puede usar
+`new URL('../../data/…', import.meta.url)` a secas (el truco de BHD) porque
+la ruta relativa entre el módulo compilado y `data/` **cambia** según dónde
+corra el código:
+
+1. `process.env.NG_SOLID_MCP_DATA` — override explícito (tests, debugging).
+2. `../data/<fichero>` relativo al propio módulo — layout publicado:
+   `dist/packages/mcp/lib/data.js` → `dist/packages/mcp/data/<fichero>`.
+3. `../../data/<fichero>` — layout de desarrollo:
+   `packages/mcp/src/lib/data.ts` → `packages/mcp/data/<fichero>`.
+
+Gana el primer candidato para el que `existsSync` es verdadero; si ninguno
+existe, lanza un error listando las tres rutas probadas (nunca falla en
+silencio). `src/lib/install-skills.ts#resolveSkillsSourceDir` replica
+exactamente la misma cadena para `data/skills/`, y
+`GuideDoc.skillPath` (`data/skills/<name>/SKILL.md`, relativo a la raíz del
+paquete) es lo que `resources.ts`'s `ns://skill/{slug}` resuelve con la
+misma lógica de dos niveles (`../` publicado, `../../` dev) — **no** apunta
+al `SKILL.md` autoral bajo `skills/`, que puede tener marcadores sin
+resolver.
+
+## 4. El guardarraíl de `transpileModule` en `extract-tokens.mjs`
+
+`extract-tokens.mjs` no reimplementa `flattenTokens` /
+`tokenPathToCssVariable` / `validateNsPreset`: los importa **en caliente**
+desde el código de producción, transpilando `theme.utils.ts` y
+`arvisfy.preset.ts` con `ts.transpileModule(...)` y cargando el resultado
+vía `import('data:text/javascript;base64,' + …)`. Esto sólo es seguro
+porque ambos ficheros hoy únicamente tienen imports **de tipo**
+(`import type` o imports erasados por `isolatedModules`); un import de
+**valor** (por ejemplo, si `arvisfy.preset.ts` empezara a importar una
+utilidad en runtime) rompería el resultado transpilado, porque ese import
+no puede resolverse desde un data URI.
+
+El prebuild debe detectar un import de valor en esos ficheros y abortar con
+un mensaje explícito en vez de producir un snapshot silenciosamente
+incorrecto. Si eso ocurre, el fallback documentado es dejar de transpilar en
+memoria y ejecutar Node directamente sobre TypeScript con
+`node --experimental-strip-types`, aceptando que entonces sólo se admiten
+anotaciones de tipo _erasables_ (sin decoradores, sin enums no-const) en
+esos dos ficheros.
+
+## 5. Skills: fuente única, dos vehículos, un solo punto de interpolación
+
+`packages/mcp/skills/<name>/SKILL.md` es la única fuente de verdad para:
+
+1. **`guides` en el snapshot** (`list_guides`/`get_guide`, resource
+   `ns://guide/{slug}`).
+2. **Los ficheros distribuibles** que copia `install-skills` (resource
+   `ns://skill/{slug}` sirve el mismo fichero).
+
+Cada `SKILL.md` es front-matter mínimo (`name`, `description` — sin
+dependencia de YAML, parseo manual de esas dos claves en
+`extract-guides.mjs`) más un cuerpo Markdown troceado por headings `## ` en
+`sections: [{ id: slugify(title), title, content }]`.
+
+### Marcadores de datos vivos
+
+Un `SKILL.md` puede embeber `<!-- ns:<marcador> -->` en cualquier punto del
+cuerpo; `extract-guides.mjs` los reemplaza con datos derivados de los mismos
+extractores que alimentan el resto del snapshot, para que la skill nunca
+pueda desincronizarse del código real:
+
+| Marcador                     | Contenido                                                                                     |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `<!-- ns:component-list -->` | Tabla markdown de todos los componentes públicos (selector, clase, familia, categoría)        |
+| `<!-- ns:icon-count -->`     | El conteo real de `NS_ICON_COUNT` + licencia                                                  |
+| `<!-- ns:versions -->`       | Versiones publicadas de `@ng-solid/design-system` / `@ng-solid/icons` + rango peer de Angular |
+| `<!-- ns:token-count -->`    | Conteo de tokens por tier + número de grupos de componente                                    |
+| `<!-- ns:form-controls -->`  | Tabla de los controles `ControlValueAccessor` públicos bajo `form/`, con sus inputs propios   |
+
+Un marcador desconocido (typo) hace que `extract-guides.mjs` lance una
+excepción — falla el build en vez de publicar un comentario HTML literal.
+
+### Dónde se materializa la interpolación (decisión de diseño)
+
+`extract-guides.mjs` es **puro**: no escribe a disco, sólo devuelve
+`{ guides, resolvedFiles }` (`resolvedFiles` es un `Map<"<name>/SKILL.md",
+string>` con el markdown ya resuelto). `scripts/prebuild.mjs` decide qué
+hacer con eso:
+
+- `guides` se embebe directamente en `data/design-system.json` — así
+  `list_guides`/`get_guide` no tocan el filesystem en runtime, sólo leen el
+  snapshot ya cargado en memoria.
+- `resolvedFiles` se escribe, uno por skill, en
+  `data/skills/<name>/SKILL.md` — **regenerando el directorio completo en
+  cada build** (`rmSync` + recreación) para que una skill renombrada o
+  eliminada nunca deje un fichero huérfano.
+
+`install-skills` copia siempre desde `data/skills/`, nunca desde `skills/`
+directamente — así el consumidor final recibe el mismo markdown, con los
+marcadores ya resueltos, sin importar si llegó por MCP (`get_guide`,
+`ns://guide/{slug}`, `ns://skill/{slug}`) o por fichero
+(`install-skills`). El directorio autoral `skills/` (con marcadores sin
+resolver) también viaja en el tarball npm porque `postbuild.mjs` lo copia
+tal cual a `dist/packages/mcp/skills/` — eso es intencional (permite
+inspeccionar la fuente), pero ningún tool ni el comando `install-skills`
+deben leer de ahí.
+
+### Gobierno: no se duplican en `.agents/skills/` de este repo
+
+`.agents/skills/local-package-publish/` es workflow **interno** del
+workspace (cómo publicar un paquete cambiado a Verdaccio); no tiene
+relación con el design system. `packages/mcp/skills/` es **producto**: lo
+que un consumidor externo instala con `install-skills`. No mezclar ambos
+directorios ni copiar contenido de uno a otro.
+
+## 6. Superficie MCP (32 tools, 10 resources, 6 prompts)
+
+Ver el detalle completo, agrupado, en el [`README.md`](./README.md#tools-por-grupo-32).
+Convenciones que aplican a toda la superficie:
+
+- Todo output que incluya markup respeta el invariante de standalone:
+  `selector` + `importStatement` + `imports: [NsXComponent]` siempre juntos
+  (`get_component_import`, `generate_component_template`,
+  `export_component_docs`).
+- Los resources usan el namespace `ns://` (nunca `bhd://`, que era el del
+  blueprint): `component/{selector}`, `component/{selector}/markdown`,
+  `guide/{slug}`, `skill/{slug}`, `tokens/{tier}`,
+  `tokens/component/{group}`, `preset/arvisfy`, `icons/catalog`,
+  `contract/style`, `snapshot/stats`.
+- Los prompts (`build_ns_ui`, `review_ns_usage`, `choose_ns_component`,
+  `build_ns_form`, `theme_ns_app`, `migrate_to_ns`) comparten un bloque de
+  invariantes no negociables (entrypoint único, `imports` obligatorio, BEM
+  sin Tailwind en markup, valores de union cerrados, `--ns-component-*`
+  únicamente, `provideNsTheme` una sola vez) y terminan pidiendo al agente
+  que valide su propio resultado con `validate_component_usage`/
+  `validate_style_contract` antes de darlo por terminado.
+
+## 7. Cómo agregar o mejorar una guía
+
+1. Edita el `SKILL.md` correspondiente bajo `packages/mcp/skills/<name>/` —
+   nunca escribas markdown de guía a mano en TypeScript.
+2. Si necesitas un dato vivo nuevo, añade un `MARKER_BUILDERS['mi-marcador']`
+   en `extract-guides.mjs` y documenta el marcador en la tabla de la
+   sección 5 de esta guía.
+3. Regenera y valida:
+
+   ```bash
+   pnpm exec nx run mcp:build-data
+   pnpm exec nx run mcp:check-data
+   ```
+
+4. Si es una skill completamente nueva, crea el directorio
+   `packages/mcp/skills/<name>/SKILL.md` con front-matter `name`/`description`
+   (el `name` debe coincidir con el nombre del directorio — `extract-guides.mjs`
+   lo valida y falla si no coinciden) y al menos una sección `## `.
+
+## 8. Cómo agregar una tool/resource/prompt nuevos
+
+No es responsabilidad de esta guía duplicar las convenciones de
+`src/lib/tools*.ts`/`resources.ts`/`prompts.ts` (ver esos ficheros
+directamente), pero en resumen:
+
+- Reusa `loadSnapshot()`/`loadIcons()` de `data.ts`; no leas `data/*.json`
+  por tu cuenta.
+- Da errores accionables con sugerencias (ver `resolveComponent`/
+  `resolveGuide` en `tools.components.ts`/`tools.guides.ts`) en vez de un
+  simple "not found".
+- No dupliques snapshot completo en una respuesta si un subconjunto basta.
+- Mantén los nombres de tools/resources/prompts estables una vez publicados
+  — un cliente MCP puede tenerlos cacheados.
+
+## 9. Publicación — configurada, no ejecutada en esta tanda
+
+```bash
+pnpm exec nx run mcp:publish:local     # build + bump patch + publish a Verdaccio (localhost:4873)
+pnpm view @ng-solid/mcp version --registry=http://localhost:4873
+```
+
+Antes del primer publish real, `pnpm pack --dry-run` desde
+`dist/packages/mcp` confirma que `data/**` y `skills/**` viajan en el
+tarball (ambos están en `files` de `package.json`).

package/README.md

@@ -0,0 +1,159 @@
+# @ng-solid/mcp
+
+Servidor [MCP](https://modelcontextprotocol.io) que expone por stdio un snapshot
+generado en build del design system Arvisfy (`@ng-solid/design-system` +
+`@ng-solid/icons`): componentes (props/eventos/modelos, con herencia
+resuelta), tokens de tema con resolución de contraste `light`/`dark`,
+servicios, providers, el catálogo de 1790 iconos Lucide, el contrato de
+estilos y 6 guías de uso. Pensado para que un agente de IA que consuma
+`@ng-solid/design-system` en un proyecto externo trabaje con la API real en
+vez de inventarla — ver la arquitectura completa y el pipeline de datos en
+[`GUIDE.md`](./GUIDE.md).
+
+> **Estado de publicación**: este paquete todavía no se publica a npm público
+> ni a Verdaccio (ver `GUIDE.md` § publicación). Los bloques de configuración
+> de abajo describen el consumo objetivo una vez publicado
+> (`npx -y @ng-solid/mcp`); mientras tanto, usa el build local — ver
+> "Desarrollo local" más abajo, o el `.mcp.json` en la raíz de este
+> monorepo, que ya apunta a `dist/packages/mcp/index.js` para dogfooding.
+
+## Instalación por cliente MCP
+
+### Claude Code
+
+```bash
+claude mcp add ng-solid -- npx -y @ng-solid/mcp
+```
+
+O en `.mcp.json` (raíz del proyecto consumidor):
+
+```json
+{
+  "mcpServers": {
+    "ng-solid": {
+      "command": "npx",
+      "args": ["-y", "@ng-solid/mcp"]
+    }
+  }
+}
+```
+
+### OpenAI Codex
+
+```bash
+codex mcp add ng-solid -- npx -y @ng-solid/mcp
+```
+
+O en `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ng-solid]
+command = "npx"
+args = ["-y", "@ng-solid/mcp"]
+```
+
+### Cursor
+
+Crea o edita `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ng-solid": {
+      "command": "npx",
+      "args": ["-y", "@ng-solid/mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+1. Paleta de comandos (`Cmd+Shift+P` / `Ctrl+Shift+P`) → `MCP: Add Server`.
+2. Selecciona `Command (stdio)`.
+3. Comando: `npx`. Argumentos: `-y @ng-solid/mcp`.
+4. Nombre del servidor: `ng-solid`.
+
+O edita `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "ng-solid": {
+      "command": "npx",
+      "args": ["-y", "@ng-solid/mcp"]
+    }
+  }
+}
+```
+
+## `install-skills` — distribuir las guías como ficheros
+
+El mismo binario copia las 6 guías (`packages/mcp/skills/*/SKILL.md`,
+ya resueltas — sin marcadores `<!-- ns:… -->` pendientes) a un directorio de
+skills local, útil para agentes que leen ficheros `SKILL.md` en vez de
+consultar el MCP por stdio:
+
+```bash
+npx -y @ng-solid/mcp install-skills              # copia a ./.agents/skills/
+npx -y @ng-solid/mcp install-skills --list        # lista las skills sin copiar
+npx -y @ng-solid/mcp install-skills --dir ./docs/skills --force
+```
+
+- `--dir <ruta>` — directorio destino (default `./.agents/skills`).
+- `--list` — enumera las skills disponibles sin copiar nada.
+- `--force` — sobreescribe skills ya presentes en el destino; sin ella, una
+  skill existente se salta con un aviso.
+
+## Tools por grupo (32)
+
+**Descubrimiento** — `list_components`, `get_component`,
+`search_components`, `search_all`, `suggest_component`,
+`get_related_components`, `get_categories`.
+
+**API de componentes** — `get_component_api`, `get_component_import`,
+`generate_component_template`, `get_usage_example`, `export_component_docs`.
+
+**Formularios** — `get_form_control_contract`, `list_form_controls`.
+
+**Servicios y providers** — `list_services`, `get_service`, `get_provider`.
+
+**Tokens/tema** — `get_component_tokens`, `list_theme_tokens`,
+`resolve_token`, `get_token_scope`, `validate_theme_preset`,
+`get_token_drift`.
+
+**Contrato de estilos** — `get_style_contract`, `validate_style_contract`,
+`validate_component_usage`.
+
+**Iconos** — `search_icons`, `get_icon`, `get_icons_setup`.
+
+**Guías/meta** — `list_guides`, `get_guide`, `get_version_info`.
+
+## Resources y prompts
+
+Ver el detalle de URIs `ns://…` y de los prompts (`build_ns_ui`,
+`review_ns_usage`, `choose_ns_component`, `build_ns_form`, `theme_ns_app`,
+`migrate_to_ns`) en [`GUIDE.md`](./GUIDE.md).
+
+## Desarrollo local
+
+Desde la raíz del monorepo:
+
+```bash
+pnpm exec nx run mcp:build          # prebuild + tsc + postbuild -> dist/packages/mcp
+node dist/packages/mcp/index.js     # servidor por stdio
+```
+
+Regenerar sólo el snapshot de datos:
+
+```bash
+pnpm exec nx run mcp:build-data     # escribe packages/mcp/data/*.json y data/skills/
+pnpm exec nx run mcp:check-data     # falla si el snapshot en disco quedó desactualizado
+```
+
+Inspector MCP contra el build compilado:
+
+```bash
+cd packages/mcp
+pnpm run inspect
+```