Storybook MCP Server

oficial

Ayuda a los agentes a escribir y probar automáticamente historias para tus componentes de interfaz de usuario.

GitHub
259

Documentación

Storybook MCP - Guía para colaboradores

¡Bienvenido al monorepositorio del Addon Storybook MCP! Este proyecto permite que los agentes de IA trabajen de manera más eficiente con Storybook al proporcionar un servidor MCP (Protocolo de Contexto de Modelo) que expone información de componentes de UI y flujos de trabajo de desarrollo.

📦 Paquetes

Este monorepositorio contiene cuatro paquetes principales:

  • @storybook/mcp - Biblioteca MCP independiente para servir conocimiento de componentes de Storybook (se puede usar de forma independiente)
  • @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 colaboradores que buscan desarrollar, probar o contribuir a estos paquetes.

🚀 Inicio rápido

Probar los plugins de Claude y Codex desde GitHub

Los probadores externos pueden instalar el mercado de plugins directamente desde la rama main de este repositorio. No se requiere clonación local.

Codex

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

Verifica el mercado y el plugin:

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code

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 mercado en dos lugares. Los catálogos raíz soportan instalaciones desde GitHub desde storybookjs/mcp; los catálogos locales del paquete soportan scripts de desarrollo local del paquete. Deben permanecer idénticos excepto por la ruta relativa de origen del plugin, y la validación del paquete comprueba que así sea.

Prerrequisitos

  • Node.js 24+ - El proyecto requiere Node.js 24 o superior (ver .nvmrc)
  • pnpm 10.19.0+ - Requisito estricto de 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 [email protected]

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 Storybook de prueba en http://localhost:6006
  • El addon en modo vigilancia, 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 vigilancia, reconstruyendo automáticamente cuando realizas 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

Construcción

# Build all packages
pnpm build

Pruebas

El monorepositorio utiliza una configuración centralizada de Vitest a 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 construirá todo e iniciará Storybook con addon-mcp, y luego puedes conectar tu agente de codificación a él en http://localhost:6006/mcp (o tu endpoint de addon configurado) y probarlo.

Trabajar con la aplicación MCP

Para trabajar y depurar la aplicación MCP que se renderiza como parte de la herramienta de historias de vista previa, 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 vigilancia ejecutando pnpm storybook en la raíz
  4. Reiniciar VSCode y abrir el archivo .vscode/mcp.json y asegurarte de que el Storybook MCP esté marcado como En ejecución, de lo contrario haz clic en Iniciar.
  5. Abrir un chat en VSCode y escribir un mensaje como este:

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

  1. Después de este primer mensaje, cada vez que hagas cambios, Storybook se reinicia automáticamente. Espera a que esté completamente listo, luego puedes pedir "Ejecutar la herramienta de nuevo".

También puedes usar el inspector de MCPJam para tener un control de más bajo nivel de las llamadas a la herramienta.

Formateo 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 monorepositorio 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 importaciones

Incluye siempre las extensiones de archivo en las importaciones relativas:

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

// ❌ Wrong
import { foo } from './bar';
  • Las importaciones JSON usan la sintaxis de atributos de importación:
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, añade un changeset si tus cambios deben desencadenar una publicación:

  • Parche: Correcciones de errores, actualizaciones de documentación
  • Menor: Nuevas funcionalidades, cambios compatibles con versiones anteriores
  • Mayor: Cambios que rompen la compatibilidad

🤝 Contribuir

¡Agradecemos las contribuciones! Aquí te mostramos cómo empezar:

  1. Bifurca el repositorio y crea una rama de funcionalidad
  2. Realiza 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 una solicitud de extracción con una descripción clara

Antes de enviar

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

Obtener ayuda

📄 Licencia

MIT - Consulta LICENSE para más detalles

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