# MCP Storybook Render

MCP server en NestJS para consultar el design system Doggie UI y renderizar paginas JS-heavy con Puppeteer.

Este proyecto reemplaza el enfoque anterior basado en Node plano y usa:
- NestJS
- arquitectura modular con separacion por dominio/aplicacion/infrastructure
- MCP moderno por `Streamable HTTP`
- logs de auditoria en archivo `.log`

## Que hace este MCP

Expone tools MCP para:
- renderizar una URL y devolver HTML, texto y screenshot
- hacer preguntas sobre la documentacion renderizada
- buscar stories/componentes en Storybook
- listar el catalogo de stories por seccion

Caso de uso principal:
- consultar desde VS Code informacion de componentes, tokens y documentacion del design system Doggie UI sin pegar JSON manual cada vez

## Estado actual

- Nombre del servidor MCP: `storybook-renderer`
- Transporte recomendado: `HTTP`
- Endpoint MCP: `http://127.0.0.1:3333/mcp`
- Healthcheck: `http://127.0.0.1:3333/health`
- Node validado en este proyecto: `22.19.0`

Importante:
- este proyecto ya no usa `SSE` legado como transporte principal
- la conexion correcta en VS Code es `type: "http"`
- no depende de `mcp-cli.ts`

## Estructura general

- `src/main.ts`: arranque en modo `http` o `stdio`
- `src/modules/mcp`: servidor MCP, definicion de tools y logging
- `src/modules/renderer`: render de paginas con Puppeteer
- `src/modules/storybook`: catalogo, busqueda, smart routing y ranking de fragmentos
- `logs/storybook-renderer.log`: auditoria de consultas MCP

## Instalacion

Desde esta carpeta:

```powershell
Set-Location "C:\satrack\mcp-storybook-render"
npm install
```

## Como iniciar el proyecto

Modo recomendado, para VS Code conectado por MCP HTTP:

```powershell
Set-Location "C:\satrack\mcp-storybook-render"
npm run start:http
```

Verificacion rapida:

```powershell
Invoke-WebRequest http://127.0.0.1:3333/health | Select-Object -ExpandProperty Content
```

Debe responder:

```json
{"ok":true}
```

Modo `stdio`, solo si en algun momento lo necesitas:

```powershell
npm run start:stdio
```

## Configuracion en VS Code

En tu [`mcp.json`](C:\Users\andres_gomez\AppData\Roaming\Code\User\mcp.json) debe quedar asi:

```json
"storybook-renderer": {
  "type": "http",
  "url": "http://127.0.0.1:3333/mcp",
  "alwaysAllow": ["*"]
}
```

Importante:
- no uses `transport: "sse"` para este proyecto nuevo
- no uses `http://127.0.0.1:3333/sse`
- si VS Code sigue intentando `/sse`, recarga la ventana con `Developer: Reload Window`

## Tool disponible

### `storybook_execute`

El MCP ahora publica una sola tool. Todas las capacidades se invocan con el parametro obligatorio `action`.

Acciones disponibles:
- `get_user_info`: valida autenticacion o un token puntual
- `query_url`: consulta contenido de un componente o documentacion
- `render_url`: renderiza una URL y puede devolver html, texto o screenshot
- `storybook_search`: busca stories o componentes por termino
- `list_stories`: lista el catalogo completo o por seccion
- `report_validation`: persiste un unico reporte final con la pregunta exacta y la respuesta final del chat

Parametros comunes mas usados:
- `action` obligatorio
- `url`
- `question`
- `query`
- `section`
- `source`: `auto`, `page`, `previewFrame`
- `waitUntil`
- `timeoutMs`
- `waitForMs`
- `topK`
- `maxChars`

Regla practica:
- para responder una pregunta sobre un componente, usa `storybook_execute` con `action: "query_url"`
- si no sabes que story corresponde, usa `storybook_execute` con `action: "storybook_search"` o `action: "list_stories"`
- antes de cualquier accion autenticada, usa `storybook_execute` con `action: "get_user_info"`
- al final de la conversacion, usa una sola vez `storybook_execute` con `action: "report_validation"`, `project`, `question` y `answer`
- en `answer` debes enviar exactamente el texto final mostrado en el chat, incluyendo Markdown cuando aplique

## Flujo recomendado de uso

1. Inicia el servidor con `npm run start:http`.
2. Verifica `/health`.
3. Asegura que VS Code tenga el bloque `type: "http"` apuntando a `/mcp`.
4. En un chat nuevo, pega el prompt inicial.
5. Luego pregunta en lenguaje natural.

Regla practica:
- si ya sabes la story o quieres respuesta directa, usa `storybook_execute` con `action: "query_url"`
- si no sabes que story corresponde, usa primero `storybook_execute` con `action: "storybook_search"` o `action: "list_stories"`

## Prompt inicial recomendado

Usa este prompt al comenzar un chat nuevo:

```text
Usa estas reglas:
- MCP a usar: `storybook-renderer`
- Transporte ya configurado en VS Code: HTTP
- No me pidas JSON manual ni llamadas MCP en bruto; ejecuta tu la tool.
- Usa siempre la tool `storybook_execute`.
- Si la consulta es sobre contenido o descripcion de un componente, usa `action: "query_url"`.
- Cuando ya tengas la respuesta final para el usuario, llama exactamente una vez `action: "report_validation"`.
- En esa llamada final envia solo:
  - `project`: nombre del workspace
  - `question`: la pregunta exacta escrita por el usuario en el chat
  - `answer`: la respuesta final exacta mostrada en el chat
- No infieras la pregunta desde `query`, `summary` o busquedas intermedias.
- No reportes resultados de `storybook_search`, `list_stories` o `query_url` como si fueran la respuesta final.
- Si la respuesta final tiene Markdown, listas o bloques de codigo, envialos tal cual en `answer`.
- URL base por defecto:
  `https://stoportaltest.blob.core.windows.net/doggie-ui-sb/index.html`
- Parametros por defecto para `action: "query_url"`:
  - `source: "auto"`
  - `storybookSmartRouting: true`
  - `waitUntil: "networkidle2"`
  - `timeoutMs: 60000`
  - `waitForMs: 2500`
  - `topK: 8`
  - `maxChars: 250000`
- Si no esta claro que componente corresponde a mi pregunta, usa primero `action: "storybook_search"` o `action: "list_stories"`.
- Si encuentras la story correcta, luego usa `action: "query_url"`.
- Responde en espanol.
- Dame respuestas concretas, claras y resumidas.

A partir de ahora, cuando pregunte cosas como:
- "que dice tooltip"
- "como se usa buddytip"
- "buscame el token de elevacion"
- "que componentes hay en atomos"

asume que debes consultar ese MCP.
```

## Ejemplo de consulta base

El archivo [`exampleSearch.json`](C:\satrack\mcp-storybook-render\exampleSearch.json) contiene la configuracion base recomendada:

```json
{
  "name": "storybook_execute",
  "arguments": {
    "action": "query_url",
    "url": "https://stoportaltest.blob.core.windows.net/doggie-ui-sb/index.html",
    "question": "ESCRIBE_AQUI_TU_PREGUNTA",
    "source": "auto",
    "storybookSmartRouting": true,
    "waitUntil": "networkidle2",
    "timeoutMs": 60000,
    "waitForMs": 2500,
    "topK": 8,
    "maxChars": 250000
  }
}
```

## Ejemplo de reporte final

Cuando ya hayas respondido al usuario en el chat, reporta una sola vez asi:

```json
{
  "name": "storybook_execute",
  "arguments": {
    "action": "report_validation",
    "project": "mcp-storybook-render",
    "question": "¿Como implementar el componente Buddytip?",
    "answer": "Respuesta final exacta mostrada en el chat, incluyendo Markdown si aplica."
  }
}
```

## Logs y auditoria

Cada llamada MCP deja traza en consola y en archivo.

Ruta por defecto:
- [`logs/storybook-renderer.log`](C:\satrack\mcp-storybook-render\logs\storybook-renderer.log)

Que registra:
- timestamp legible
- tipo de evento: `REQUEST`, `SUCCESS`, `ERROR`
- `requestId`
- nombre de la tool
- `url`
- `question`, `query` o `section` cuando aplique
- `durationMs`

Ejemplo:

```text
2026-03-15 17:09:13.569 [REQUEST] requestId=req-1773612553569-1 name=storybook_execute action=storybook_search url=https://stoportaltest.blob.core.windows.net/doggie-ui-sb/index.html query="chip"
2026-03-15 17:09:14.643 [SUCCESS] requestId=req-1773612553569-1 durationMs=1074 name=storybook_execute action=storybook_search url=https://stoportaltest.blob.core.windows.net/doggie-ui-sb/index.html query="chip"
```

Si quieres cambiar la ruta del log:

```powershell
$env:MCP_LOG_FILE="C:\ruta\personalizada\storybook-renderer.log"
npm run start:http
```

## Troubleshooting rapido

### VS Code no conecta

Revisa:
- que el servidor este arriba con `npm run start:http`
- que `/health` responda `{"ok":true}`
- que en `mcp.json` uses `type: "http"` y `/mcp`

### VS Code sigue intentando `/sse`

Eso significa que todavia tiene configuracion o estado viejo.

Haz esto:
- corrige `mcp.json`
- reinicia el servidor MCP
- ejecuta `Developer: Reload Window` en VS Code

### No aparecen logs

Revisa:
- que el servidor realmente este atendiendo consultas
- que exista la carpeta `logs`
- que no hayas sobrescrito `MCP_LOG_FILE` con una ruta invalida

### El chat no usa el MCP automaticamente

Normalmente pasa por falta de contexto en la conversacion.

Solucion:
- pega el prompt inicial
- luego pregunta en lenguaje natural

## Comandos utiles

```powershell
npm run start:http
npm run start:http:dev
npm run start:stdio
npm run build
npm test -- --runInBand
```

## Notas finales

- este proyecto vive en `C:\satrack\mcp-storybook-render`
- si aun tienes una version anterior del renderer en otra carpeta, pueden convivir mientras terminas la migracion
- si vas a usar solo esta version Nest, evita levantar al mismo tiempo otro renderer en el mismo puerto para no mezclar endpoints y diagnostico