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:

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

Como iniciar el proyecto

Modo recomendado, para VS Code conectado por MCP HTTP:

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

Verificacion rapida:

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

Debe responder:

{"ok":true}

Modo stdio, solo si en algun momento lo necesitas:

npm run start:stdio

Configuracion en VS Code

En tu mcp.json debe quedar asi:

"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:

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 contiene la configuracion base recomendada:

{
  "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:

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

Que registra:

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

Ejemplo:

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:

$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

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