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.
¿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:
- Instala el addon:
npx storybook add @storybook/addon-mcp. Mientras corre el servidor de desarrollo, el endpoint queda enhttp://localhost:6006/mcp, aunque el puerto puede cambiar en tu proyecto. - Activa el manifiesto de componentes en
.storybook/main.tsconfeatures: { componentsManifest: true }. - Registra el servidor en tu agente. Storybook documenta la configuración para Claude Code, Gemini CLI, OpenAI Codex y VS Code Copilot.
- Actualiza
AGENTS.mdoCLAUDE.mdpara 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
!manifestpuedes 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.
¿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.