Storybook MCP Server

oficial

Ajude agentes a escrever e testar automaticamente histórias para seus componentes de UI.

GitHub
258

Documentação

Storybook MCP - Guia do Contribuidor

Bem-vindo ao monorepo do Addon Storybook MCP! Este projeto permite que agentes de IA trabalhem de forma mais eficiente com o Storybook, fornecendo um servidor MCP (Model Context Protocol) que expõe informações de componentes de UI e fluxos de trabalho de desenvolvimento.

📦 Pacotes

Este monorepo contém quatro pacotes principais:

  • @storybook/mcp - Biblioteca MCP independente para servir conhecimento de componentes do Storybook (pode ser usada de forma independente)
  • @storybook/addon-mcp - Addon do Storybook que executa um servidor MCP dentro do seu servidor de desenvolvimento Storybook, e inclui a funcionalidade do @storybook/mcp do seu Storybook local
  • @storybook/claude-code-plugin - Plugin do Claude Code com habilidades de configuração do Storybook e configuração MCP
  • @storybook/codex-plugin - Plugin do Codex com habilidades de configuração do Storybook e configuração MCP

Cada pacote tem seu próprio README com documentação voltada para o usuário. Este documento é para contribuidores que desejam desenvolver, testar ou contribuir com esses pacotes.

🚀 Início Rápido

Testando os plugins Claude e Codex a partir do GitHub

Testadores externos podem instalar o marketplace de plugins diretamente do branch main deste repositório. Nenhum clone local é necessário.

Codex

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

Verifique o marketplace e o 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

Verifique o plugin e o servidor MCP:

claude plugin list --json
claude mcp list

O repositório mantém intencionalmente os catálogos do marketplace em dois lugares. Os catálogos na raiz suportam instalações do GitHub a partir de storybookjs/mcp; os catálogos locais do pacote suportam scripts de desenvolvimento local do pacote. Eles devem permanecer idênticos, exceto pelo caminho relativo da fonte do plugin, e a validação do pacote verifica isso.

Pré-requisitos

  • Node.js 24+ - O projeto requer Node.js 24 ou superior (veja .nvmrc)
  • pnpm 10.19.0+ - Requisito estrito de gerenciador de pacotes (aplicado em package.json)
# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g [email protected]

Instalação

# 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

Fluxo de Trabalho de Desenvolvimento

# 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

O comando Storybook inicia:

  • A instância interna de teste do Storybook em http://localhost:6006
  • O addon em modo de observação, para que as alterações sejam refletidas automaticamente
  • Servidor MCP disponível em http://localhost:6006/mcp

🛠️ Tarefas Comuns

Desenvolvimento

O comando turbo watch build executa todos os pacotes em modo de observação, reconstruindo automaticamente quando você faz alterações:

# 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

Compilação

# Build all packages
pnpm build

Testes

O monorepo usa uma configuração centralizada do Vitest no nível raiz com projetos configurados para cada pacote:

# 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

Depurando Servidores MCP

Use o MCP Inspector para depurar e testar a funcionalidade do servidor MCP:

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

Isso usa a configuração em .mcp.inspect.json para conectar-se aos seus servidores MCP locais.

Alternativamente, você também pode usar estes comandos curl para verificar se tudo 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": {}
    }
  }'

Depurando com o Storybook

Você pode iniciar o Storybook com:

pnpm storybook

Isso compilará tudo e iniciará o Storybook com o addon-mcp, e você poderá então conectar seu agente de codificação a ele em http://localhost:6006/mcp (ou no endpoint configurado do addon) e experimentá-lo.

Trabalhando com o Aplicativo MCP

Para trabalhar e depurar o aplicativo MCP que é renderizado como parte da ferramenta preview-stories, você pode:

  1. Usar a compilação Insiders do VSCode
  2. Garantir que a configuração chat.mcp.apps.enabled esteja habilitada
  3. Iniciar o Storybook do repositório em modo de observação executando pnpm storybook na raiz
  4. Reiniciar o VSCode e abrir o arquivo .vscode/mcp.json e garantir que o Storybook MCP esteja marcado como Em Execução, caso contrário, clique em Iniciar.
  5. Abrir um chat no VSCode e escrever um prompt como este:

Mostre-me como todas as histórias de botões se parecem, usando o Storybook MCP

  1. Após este primeiro prompt, sempre que você fizer alterações, o Storybook reinicia automaticamente. Aguarde até que esteja totalmente pronto, então você pode solicitar "Execute a ferramenta novamente".

Você também pode usar o inspetor do MCPJam para ter um controle de nível mais baixo das chamadas da ferramenta.

Formatação & 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

🔍 Verificações de Qualidade

O monorepo inclui várias verificações de qualidade que são executadas na 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

📝 Convenções de Código

TypeScript & Importações

Sempre inclua extensões de arquivo em importações relativas:

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

// ❌ Wrong
import { foo } from './bar';
  • Importações JSON usam a sintaxe de atributos de importação:
import pkg from '../package.json' with { type: 'json' };

🚢 Processo de Lançamento

Este projeto usa Changesets para gerenciamento de versão:

# 1. Create a changeset describing your changes
pnpm changeset

Quando você criar um PR, adicione um changeset se suas alterações devem disparar um lançamento:

  • Patch: Correções de bugs, atualizações de documentação
  • Minor: Novos recursos, alterações compatíveis com versões anteriores
  • Major: Alterações que quebram a compatibilidade

🤝 Contribuindo

Aceitamos contribuições! Veja como começar:

  1. Faça um fork do repositório e crie um branch de funcionalidade
  2. Faça suas alterações seguindo as convenções de código acima
  3. Teste suas alterações usando a instância interna do Storybook
  4. Crie um changeset se suas alterações justificarem um lançamento
  5. Envie um pull request com uma descrição clara

Antes de Enviar

  • Código compila sem erros (pnpm build)
  • Testes passam (pnpm test:run)
  • Código está formatado (pnpm format)
  • Código está lintado (pnpm lint)
  • Verificação de tipos passa (pnpm typecheck)
  • Alterações testadas com o MCP Inspector ou Storybook interno
  • Changeset criado se necessário (pnpm changeset)

Obtendo Ajuda

📄 Licença

MIT - Veja LICENSE para detalhes

Nota: Este projeto é experimental e está sob desenvolvimento ativo. APIs e arquitetura podem mudar à medida que exploramos as melhores maneiras de integrar agentes de IA com o Storybook.