Servidor MCP de Storybook

Node CI npm license

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para interactuar con la documentación y la información de los componentes de Storybook.

Características

getComponentList: Obtiene una lista de todos los componentes de un Storybook configurado
getComponentsProps: Obtiene información detallada de las propiedades (props) de múltiples componentes utilizando automatización de navegador headless
Herramientas personalizadas: Crea herramientas personalizadas que pueden extraer cualquier información de tus páginas de Storybook usando JavaScript

Related MCP server: MCP Server

Instalación y configuración

Configuración de MCP

Añade la siguiente configuración a los ajustes de MCP:

{
  "mcpServers": {
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "<your_storybook_url>/index.json"
      }
    }
  }
}

storybook-mcp se inicia inmediatamente e instala Chromium en segundo plano la primera vez que se ejecuta. Si deseas preinstalar el navegador con antelación, ejecuta npx -y storybook-mcp@latest install-browser. Hasta que esa descarga finalice, la primera llamada a una herramienta basada en navegador puede tardar más tiempo.

Variables de entorno

STORYBOOK_URL (obligatorio): La URL a tu archivo index.json de Storybook
CUSTOM_TOOLS (opcional): Array JSON de definiciones de herramientas personalizadas para extraer información específica de tu Storybook

Uso

El servidor proporciona herramientas integradas y admite herramientas personalizadas:

Herramientas integradas

1. getComponentList

Recupera una lista de todos los componentes disponibles del Storybook configurado.

Ejemplo:

Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

Obtiene información detallada de las propiedades para múltiples componentes, incluyendo:

Nombres de las propiedades
Tipos
Valores predeterminados
Descripciones
Estado de requerido/opcional

Parámetros:

componentNames (array de strings): Array de nombres de componentes para los cuales obtener información de propiedades

Ejemplo de uso:

Tool: getComponentsProps
Parameters: { "componentNames": ["Button", "Input", "Avatar"] }

Herramientas personalizadas

Puedes definir herramientas personalizadas para extraer información específica de tus páginas de Storybook. Cada herramienta personalizada puede:

Navegar a cualquier página de tu Storybook
Ejecutar JavaScript personalizado para extraer datos
Devolver datos estructurados al asistente de IA

Estructura de herramienta personalizada:

interface CustomTool {
  name: string; // Unique tool name
  description: string; // Tool description for the AI
  parameters: object; // Input parameters schema (optional)
  page: string; // URL to navigate to
  handler: string; // JavaScript code to execute on the page
}

Ejemplo de herramientas personalizadas:

[
  {
    "name": "getIconList",
    "description": "Get All Icons from the Icon page",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "Extract color palette from design tokens",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/design-tokens--colors",
    "handler": "Array.from(document.querySelectorAll('.color-swatch')).map(el => ({ name: el.getAttribute('data-color-name'), value: el.style.backgroundColor }))"
  }
]

Para más ejemplos y documentación detallada, consulta examples/custom-tools-example.md.

Ejemplo

Configura Spectrum en la configuración de storybook-mcp con las variables de entorno STORYBOOK_URL y CUSTOM_TOOLS.

{
  "mcpServers": {
    "storybook-mcp": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "https://opensource.adobe.com/spectrum-web-components/storybook/index.json",
        "CUSTOM_TOOLS": "[{\"name\":\"getIconList\",\"description\":\"Get All Icons from the Icon page\",\"parameters\":{},\"page\":\"https://opensource.adobe.com/spectrum-web-components/storybook/iframe.html?viewMode=docs&id=icons--docs&globals=\",\"handler\":\"Array.from(document.querySelector('icons-demo').shadowRoot.querySelectorAll('.icon')).map(i => i.textContent)\"}]"
      }
    }
  }
}

Cómo funciona

Lista de componentes: El servidor obtiene el archivo index.json (v3 es stories.json) del Storybook y extrae todos los componentes marcados como tipo "docs"
Información de propiedades: Para las propiedades de los componentes, el servidor:
- Encuentra el ID de documentación del componente desde el index.json
- Construye la URL del iframe para la página de documentación del componente
- Utiliza Playwright para cargar la página en un navegador headless
- Extrae el HTML de la tabla de propiedades de la documentación

URLs de Storybook compatibles

El servidor funciona con cualquier Storybook que exponga un archivo index.json (v3 es stories.json). Patrones comunes:

https://your-storybook-domain.com/index.json
https://your-storybook-domain.com/storybook/index.json

Desarrollo

Desarrollo local

Clona el repositorio
Instala las dependencias: yarn install
Instala los navegadores de Playwright: yarn install:browser
Establece la variable de entorno: export STORYBOOK_URL="your-storybook-url"
Ejecuta en modo desarrollo: yarn dev

Nota: También puedes usar npx @modelcontextprotocol/inspector tsx src/index.ts en lugar de yarn dev si lo prefieres.

Construcción

yarn build

Pruebas

yarn test

Requisitos

Node.js 18.0.0 o superior
Navegador Chromium instalado por Playwright

Manejo de errores

El servidor incluye un manejo integral de errores para:

URLs de Storybook faltantes o inválidas
Problemas de conectividad de red
Escenarios donde no se encuentra el componente
Fallos en la automatización del navegador Playwright

Licencia

Storybook MCP tiene licencia MIT.

storybook-mcp