# Storybook con IA: documentar componentes para que los use un agente

> Storybook MCP expone tu catálogo de componentes a un agente de IA para consultarlo, escribir historias y correr pruebas. Qué habilita, cómo activarlo y límites.

*Tags: ia, storybook, componentes, pruebas*

---


> [!info] Definición Rápida
> **Storybook MCP** es un servidor del Model Context Protocol que Storybook expone en tu entorno de desarrollo, para que un agente de IA consulte tus componentes documentados, escriba historias y corra pruebas sobre lo que construye. Sirve para que la IA use tu sistema de componentes en lugar de improvisar uno nuevo.


## ¿Qué es Storybook y por qué un agente lo necesita?

Storybook es una herramienta para desarrollar y documentar componentes de interfaz de forma aislada. Cada componente tiene historias, que son ejemplos con props específicas, y una documentación que muestra cómo se usa. Para un diseñador, Storybook es el lugar donde el componente real se ve en sus estados. Ya tiene lo que un agente necesita: nombres, props, variantes y ejemplos.

El problema es que, sin un canal estructurado, el agente tiene que leer el código fuente y deducir el uso. Storybook MCP cambia esa forma de acceso: le da herramientas para preguntar qué existe y cómo se usa.

## ¿Qué herramientas expone?

Según la documentación oficial, el servidor agrupa sus herramientas en tres bloques:

| Bloque | Herramienta | Qué hace |
|---|---|---|
| Documentación | `docs-list` | Devuelve el índice de componentes y de documentación suelta |
| Documentación | `docs-show` | Devuelve las props de un componente, sus tres primeras historias, un índice del resto y la documentación adicional |
| Documentación | `docs-show-story` | Devuelve una historia completa con su documentación |
| Desarrollo | `get-storybook-story-instructions` | Da guías para escribir historias útiles, con props y pruebas de interacción |
| Desarrollo | `stories-preview` | Muestra la vista previa de la historia en el chat del agente, o enlaza a ella |
| Desarrollo | `stories-find-by-component` | Relaciona el archivo de un componente con las historias que lo muestran |
| Desarrollo | `stories-changed` | Lista las historias afectadas por cambios locales (requiere detección de cambios) |
| Pruebas | `test-run` | Corre las pruebas de historias concretas e informa problemas de accesibilidad si están configurados (requiere Storybook Test) |

La documentación también menciona `review-create`, que envía una revisión de los cambios actuales y requiere la función de revisión de Storybook.

## ¿Cómo se activa?

Según la documentación oficial, son cuatro pasos:

1. Instala el addon: `npx storybook add @storybook/addon-mcp`. Mientras corre el servidor de desarrollo, el endpoint queda en `http://localhost:6006/mcp`, aunque el puerto puede cambiar en tu proyecto.
2. Activa el manifiesto de componentes en `.storybook/main.ts` con `features: { componentsManifest: true }`.
3. Registra el servidor en tu agente. Storybook documenta la configuración para Claude Code, Gemini CLI, OpenAI Codex y VS Code Copilot.
4. Actualiza `AGENTS.md` o `CLAUDE.md` para indicarle al agente que use las herramientas MCP.

Para verificar, pide al agente que liste los componentes documentados. Si llama a `docs-list`, la conexión funciona.

El paso que más se olvida es el segundo: el manifiesto viene desactivado por defecto y, sin él, la parte de documentación no está disponible. Si algo falla, el depurador de manifiestos (`/manifests/components.html`) muestra el contenido y los errores de generación.

## ¿Cómo se escribe un catálogo que un agente use bien?

La guía de buenas prácticas de Storybook da pautas concretas, y casi todas son trabajo de diseño:

- **Una historia, un concepto.** Una historia que muestra todos los tamaños y variantes a la vez es el antipatrón; sepárala.
- **Explica el porqué.** Describe cuándo usar cada historia, no solo qué muestra. Ejemplo de la propia guía: los botones primarios resuelven la acción principal de una vista y debería haber uno solo.
- **Describe el componente.** Un comentario JSDoc sobre el componente que diga para qué sirve y cuándo usarlo, con enlace al componente alternativo (el botón no navega; para navegar, el enlace).
- **Agrega `@summary`.** Si no hay resumen, el agente recibe solo los primeros 60 caracteres de la descripción de la historia, así que las primeras palabras importan.
- **Cura el contexto.** Poca información perjudica al agente, y la irrelevante también. Con la etiqueta `!manifest` puedes excluir una historia que sea un antipatrón o una página pensada solo para humanos.
- **Escribe la información dentro del MDX.** El manifiesto se genera por análisis estático, así que los valores importados desde otros archivos, como los tokens de color, no aparecen.

## ¿Por qué le importa a un diseñador?

Porque Storybook es donde tu sistema de componentes queda visible y verificable. Si documentas la intención de uso de un componente en Storybook, esa documentación llega al agente. Si no la documentas, el agente sigue inventando. Lo mismo aplica a las historias de estados de error, vacío y deshabilitado: si no existen, el agente no tiene ejemplos de cómo deben verse.

Además, `test-run` te da un lugar concreto donde revisar accesibilidad. No reemplaza tu revisión, pero evita que una interacción rota llegue a una pantalla sin que nadie lo note. Para el panorama completo de cómo los agentes usan tu sistema, mira [[componentes-y-agentes|componentes y agentes]].

## ¿Se puede compartir con el equipo?

Sí, con límites. Según la documentación, si publicas tu Storybook con Chromatic, también se publica el servidor MCP: privado si tu Storybook es privado, accesible solo para miembros invitados. La alternativa es alojarlo tú con la librería `@storybook/mcp`, que requiere Node.js 20 o superior y te obliga a mantener el servidor. En ambos casos se comparte solo la parte de documentación; las herramientas de desarrollo y de pruebas funcionan únicamente con tu Storybook local.

## ¿Cuándo NO conviene?

- Cuando tu proyecto no usa un framework soportado por el manifiesto. Revisa primero la matriz de soporte; las herramientas de desarrollo y pruebas sí funcionan igual.
- Cuando el equipo no mantiene las historias. Un catálogo desactualizado es peor que no tenerlo, porque el agente lo usará como fuente.
- Cuando la función se usa en producción sin revisar. Storybook indica que las capacidades de IA están en vista previa y la API puede cambiar.
- Cuando el componente todavía no está estabilizado. Documentar algo que va a cambiar obliga a actualizar dos veces.

## Ejemplo

Ejemplo ilustrativo: un equipo tiene un componente `Toast` con las variantes `info`, `success` y `error`. En Storybook escribe una historia por variante y una frase de uso en el JSDoc: "Úsalo para confirmar una acción que ya ocurrió. No lo uses para errores que bloquean la pantalla." Luego pide a un agente: "Muestra un aviso cuando se guarde el borrador." El agente consulta `docs-show` para `Toast`, elige la variante `success` y usa el componente existente. Después pide `test-run` sobre su historia nueva y revisa el resultado de accesibilidad.

Lo que queda para ti: confirmar que el aviso se muestra en el lugar correcto del flujo, algo que ninguna herramienta puede decidir por ti.

## Errores comunes

- Instalar el addon sin activar el manifiesto de componentes o sin escribir historias. El catálogo queda vacío y el agente no tiene qué consultar.
- Escribir solo la historia feliz y omitir errores, vacío y carga.
- Meter todas las variantes en una sola historia, que el agente no puede aprovechar.
- Creer que el soporte es igual en todos los frameworks.
- Dejar que el agente publique cambios en historias sin revisarlos.
- Confiar en que pasar las pruebas de accesibilidad significa que la pantalla es accesible. Las pruebas detectan problemas técnicos, no la experiencia de uso.

## Fuentes

- [Storybook: visión general de MCP para agentes](https://storybook.js.org/docs/ai/mcp/overview)
- [Storybook: buenas prácticas para IA](https://storybook.js.org/docs/ai/best-practices)
- [Storybook: manifiestos](https://storybook.js.org/docs/ai/manifests)
- [Storybook: compartir tu servidor MCP](https://storybook.js.org/docs/ai/mcp/sharing)


---

Source: https://www.fernandoux.com/es/wiki/ia/storybook-con-ia/