Storybook MCP

[!TIP] Este repositorio se ha movido a storybookjs/storybook a partir de Storybook v10.6.0. Consulta allí la documentación actualizada.

---

Storybook MCP

¡Bienvenido al monorepo del Addon Storybook MCP! Este proyecto permite a los agentes de IA trabajar de manera más eficiente con Storybook al proporcionar un servidor MCP (Model Context Protocol) que expone información de componentes de UI y flujos de trabajo de desarrollo.

📦 Paquetes

Este monorepo contiene cuatro paquetes principales:

• @storybook/mcp - Librería MCP independiente para servir conocimiento de componentes de Storybook (se puede usar de forma autónoma)
• @storybook/addon-mcp - Addon de Storybook que ejecuta un servidor MCP dentro de tu servidor de desarrollo de Storybook, e incluye la funcionalidad de @storybook/mcp desde tu Storybook local
• @storybook/claude-code-plugin - Plugin de Claude Code con habilidades de configuración de Storybook y configuración MCP
• @storybook/codex-plugin - Plugin de Codex con habilidades de configuración de Storybook y configuración MCP

Cada paquete tiene su propio README con documentación orientada al usuario. Este documento es para contribuidores que quieran desarrollar, probar o contribuir a estos paquetes.

🚀 Inicio Rápido

Probando los plugins de Claude y Codex desde GitHub

Los evaluadores externos pueden instalar el marketplace de plugins directamente desde la rama main de este repositorio. No se requiere clonar localmente.

Codex (más detalles)

codex plugin marketplace add storybookjs/mcp --ref main
codex plugin add storybook@storybook

Verifica el marketplace y el plugin:

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code (más detalles)

claude plugin marketplace add storybookjs/mcp@main --scope user
claude plugin install storybook@storybook --scope user

Verifica el plugin y el servidor MCP:

claude plugin list --json
claude mcp list

El repositorio mantiene intencionalmente los catálogos del marketplace en dos lugares. Los catálogos raíz admiten instalaciones desde GitHub desde storybookjs/mcp; los catálogos locales de cada paquete admiten los scripts de desarrollo local de los paquetes. Deben permanecer idénticos excepto por la ruta relativa del origen del plugin, y la validación de paquetes verifica que así sea.

Requisitos previos

• Node.js 24+ - El proyecto requiere Node.js 24 o superior (ver .nvmrc)
• pnpm 10.19.0+ - Requisito estricto del gestor de paquetes (aplicado en package.json)

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g pnpm@10.19.0

Instalación

# Clone the repository
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Install all dependencies (for all packages in the monorepo)
pnpm install

Flujo de Trabajo de Desarrollo

# Build all packages
pnpm build

# Start development mode (watches for changes in all packages)
pnpm dev

# Run unit tests in watch mode
pnpm test

# Run unit tests once
pnpm test:run

# Run Storybook with the addon for testing
pnpm --filter internal-storybook storybook

El comando de Storybook inicia:

• La instancia interna de prueba de Storybook en http://localhost:6006
• El addon en modo de observación, para que los cambios se reflejen automáticamente
• El servidor MCP disponible en http://localhost:6006/mcp

🛠️ Tareas Comunes

Desarrollo

El comando turbo watch build ejecuta todos los paquetes en modo de observación, reconstruyendo automáticamente cuando haces cambios:

# Start development mode for all packages
pnpm turbo watch build

# This is usually all you need - starts Storybook AND watches addon for changes
pnpm storybook

Compilación

# Build all packages
pnpm build

Pruebas

El monorepo utiliza una configuración centralizada de Vitest en el nivel raíz con proyectos configurados para cada paquete:

# Watch tests across all packages
pnpm test

# Run tests once across all packages
pnpm test:run

# Run tests with coverage and CI reporters
pnpm test:ci

Depuración de Servidores MCP

Usa el Inspector MCP para depurar y probar la funcionalidad del servidor MCP:

# Launches the MCP inspector (requires Storybook to be running)
pnpm inspect

Esto utiliza la configuración en .mcp.inspect.json para conectarse a tus servidores MCP locales.

Alternativamente, también puedes usar estos comandos curl para verificar que todo funciona:

# test that the mcp server is running
# use port 6006 to test the addon-mcp server instead
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# test a specific tool call
curl -X POST http://localhost:13316/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list-all-documentation",
      "arguments": {}
    }
  }'

Depuración con Storybook

Puedes iniciar Storybook con:

pnpm storybook

Esto compilará todo e iniciará Storybook con addon-mcp, y luego podrás conectar tu agente de codificación en http://localhost:6006/mcp (o en tu endpoint de addon configurado) y probarlo.

Trabajando con la App MCP

Para trabajar y depurar la app MCP que se renderiza como parte de la herramienta preview-stories, puedes:

1. Usar la compilación Insiders de VSCode
2. Asegurarte de que la configuración chat.mcp.apps.enabled esté habilitada
3. Iniciar el Storybook del repositorio en modo de observación ejecutando pnpm storybook en la raíz
4. Reiniciar VSCode y abrir el archivo .vscode/mcp.json y asegurarte de que Storybook MCP esté marcado como En Ejecución; de lo contrario, haz clic en Iniciar.
5. Abrir un chat en VSCode y escribir un prompt como este:

Muéstrame cómo se ven todas las historias de botones, usando Storybook MCP

6. Después de este primer prompt, cada vez que hagas cambios, Storybook se reinicia automáticamente. Espera a que esté completamente listo, y luego puedes escribir "Ejecuta la herramienta de nuevo".

También puedes usar el inspector de MCPJam para tener un control más detallado de las llamadas a herramientas.

Formato y Linting

# Format all files with Prettier
pnpm format

# Check formatting without changing files
pnpm format:check

# Lint code with oxlint
pnpm lint

# Lint with GitHub Actions format (for CI)
pnpm lint:ci

# Check package exports with publint
pnpm publint

🔍 Controles de Calidad

El monorepo incluye varios controles de calidad que se ejecutan en CI:

# Run all checks (build, test, lint, format, typecheck, publint)
pnpm check

# Run checks in watch mode (experimental)
pnpm check:watch

# Type checking (uses tsc directly, not turbo)
pnpm typecheck

# Type checking with turbo (for individual packages)
pnpm turbo:typecheck

# Testing with turbo (for individual packages)
pnpm turbo:test

📝 Convenciones de Código

TypeScript e Imports

Incluye siempre las extensiones de archivo en los imports relativos:

// ✅ Correct
import { foo } from './bar.ts';

// ❌ Wrong
import { foo } from './bar';

• Los imports JSON usan la sintaxis de atributos de import:

import pkg from '../package.json' with { type: 'json' };

🚢 Proceso de Publicación

Este proyecto usa Changesets para la gestión de versiones:

# 1. Create a changeset describing your changes
pnpm changeset

Cuando crees un PR, agrega un changeset si tus cambios deben desencadenar una publicación:

• Patch: Correcciones de errores, actualizaciones de documentación
• Minor: Nuevas funcionalidades, cambios compatibles hacia atrás
• Major: Cambios que rompen compatibilidad

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como empezar:

1. Haz un fork del repositorio y crea una rama de funcionalidad
2. Haz tus cambios siguiendo las convenciones de código anteriores
3. Prueba tus cambios usando la instancia interna de Storybook
4. Crea un changeset si tus cambios justifican una publicación
5. Envía un pull request con una descripción clara

Antes de Enviar

• El código compila sin errores (pnpm build)
• Las pruebas pasan (pnpm test:run)
• El código está formateado (pnpm format)
• El código está linted (pnpm lint)
• La verificación de tipos pasa (pnpm typecheck)
• Los cambios probados con el inspector MCP o Storybook interno
• Changeset creado si es necesario (pnpm changeset)

Obteniendo Ayuda

• Ideas y Solicitudes de Funcionalidades: Inicia una discusión
• Reportes de Errores: Abre un issue
• Preguntas: Pregunta en GitHub Discussions

📄 Licencia

MIT - Ver LICENSE para más detalles

---

Nota: Este proyecto es experimental y está en desarrollo activo. Las APIs y la arquitectura pueden cambiar mientras exploramos las mejores formas de integrar agentes de IA con Storybook.