MCP Design System Extractor

Extrai informações de componentes, incluindo HTML, estilos e metadados, de sistemas de design do Storybook.

GitHub
69
Experimente este MCPPatrocinado

Documentação

MCP Design System Extractor

Um servidor Model Context Protocol (MCP) que extrai informações de componentes de design systems Storybook. Conecta-se a instâncias do Storybook e extrai HTML, estilos e metadados de componentes.

Demo

Instalação

Usando Claude CLI (Recomendado)

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=http://localhost:6006

Com certificado autoassinado:

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=https://my-storybook.example.com \
  --env NODE_TLS_REJECT_UNAUTHORIZED=0

Usando npm

npm install -g mcp-design-system-extractor

Em seguida, configure no seu cliente MCP (veja Variáveis de Ambiente).

A partir do código-fonte

git clone https://github.com/freema/mcp-design-system-extractor.git
cd mcp-design-system-extractor
npm install && npm run build
npm run setup  # Interactive setup for Claude Desktop

Dependências principais

  • Puppeteer: Usa Chrome headless para renderização dinâmica de componentes JavaScript
  • Chrome/Chromium: Necessário para o Puppeteer (gerenciado automaticamente no Docker)
  • Funciona com distribuições Storybook compiladas
Design System Extractor MCP server

Recursos

  • Listar Componentes: Obtenha todos os componentes disponíveis do seu Storybook com modo compacto
  • Extrair HTML: Obtenha o HTML renderizado de qualquer componente (modo assíncrono ou síncrono)
  • Buscar Componentes: Encontre componentes por nome, título, categoria ou finalidade
  • Dependências de Componentes: Analise quais componentes são usados internamente em outros componentes
  • Informações de Tema: Extraia o tema do design system (cores, espaçamento, tipografia)
  • Análise de CSS Externo: Busque e analise arquivos CSS para extrair design tokens
  • Fila de Trabalhos Assíncronos: Operações de longa duração são executadas em segundo plano com rastreamento de trabalhos

Variáveis de Ambiente

VariávelDescriçãoPadrão
STORYBOOK_URLURL da sua instância do Storybookhttp://localhost:6006
NODE_TLS_REJECT_UNAUTHORIZEDDefina como 0 para ignorar a verificação de certificado SSL (para certificados autoassinados)1

Exemplo com certificado autoassinado:

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "STORYBOOK_URL": "https://my-storybook.example.com",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Uso

Consulte DEVELOPMENT.md para instruções detalhadas de configuração.

Ferramentas Disponíveis (9 no total)

Ferramentas Principais

  1. list_components

    • Lista todos os componentes disponíveis da instância do Storybook
    • Use compact: true para saída mínima (reduz o tamanho da resposta)
    • Filtre pelo parâmetro category
    • Suporta paginação com page e pageSize (padrão: 20)

  2. get_component_html

    • Extrai HTML de uma story específica de componente
    • Assíncrono por padrão: Retorna job_id, use job_status para consultar os resultados
    • Defina async: false para modo síncrono (usa o parâmetro timeout)
    • Use variantsOnly: true para obter a lista de variantes disponíveis (síncrono, rápido)
    • includeStyles: true opcional para extração de CSS (CSS do Storybook é filtrado)
    • Formato do ID da story: "component-name--story-name" ou apenas "component-name" (resolve automaticamente para a variante padrão)

  3. search_components

    • Busca componentes por nome, título, categoria ou finalidade
    • query: Termo de busca (use "*" para todos)
    • purpose: Encontre por função ("inputs de formulário", "navegação", "feedback", "botões", etc.)
    • searchIn: "name", "title", "category" ou "all" (padrão)
    • Suporta paginação com page e pageSize

Ferramentas de Análise de Componentes

  1. get_component_dependencies
    • Analisa o HTML renderizado para encontrar quais outros componentes são usados internamente
    • Detecta componentes React, web components e padrões de classes CSS
    • Requer formato de ID de story: "component-name--story-name"

Ferramentas de Design System

  1. get_theme_info

    • Extrai o tema do design system (cores, espaçamento, tipografia, breakpoints)
    • Obtém propriedades/variáveis customizadas de CSS
    • Use includeAll: true para todas as variáveis CSS

  2. get_external_css

    • PADRÃO: Retorna apenas design tokens + estatísticas do arquivo (evita limites de tokens)
    • Extrai e categoriza tokens: cores, espaçamento, tipografia, sombras
    • Use includeFullCSS: true somente quando precisar do conteúdo CSS completo
    • Protegido por segurança: aceita apenas URLs do mesmo domínio do Storybook

Ferramentas de Gerenciamento de Trabalhos

  1. job_status

    • Verifica o status de um trabalho assíncrono
    • Retorna: status, result (quando concluído), error (quando falhou)
    • Consulte após chamar get_component_html no modo assíncrono

  2. job_cancel

    • Cancela um trabalho na fila ou em execução
    • Retorna se o cancelamento foi bem-sucedido

  3. job_list

    • Lista todos os trabalhos com seus status
    • Filtre por status: "all" (padrão), "active" (na fila/em execução), "completed"
    • Retorna lista de trabalhos + estatísticas da fila

Exemplo de Uso

// List all components (compact mode recommended)
await list_components({ compact: true });

// Search for components
await search_components({ query: "button", searchIn: "name" });

// Find components by purpose
await search_components({ purpose: "form inputs" });

// Get variants for a component
await get_component_html({
  componentId: "button",
  variantsOnly: true
});
// Returns: { variants: ["primary", "secondary", "disabled"] }

// Get HTML (async mode - default)
await get_component_html({ componentId: "button--primary" });
// Returns: { job_id: "job_xxx", status: "queued" }

// Poll for result
await job_status({ job_id: "job_xxx" });
// Returns: { status: "completed", result: { html: "...", classes: [...] } }

// Get HTML (sync mode)
await get_component_html({
  componentId: "button--primary",
  async: false,
  timeout: 30000
});
// Returns: { html: "...", classes: [...] }

// Get HTML with styles
await get_component_html({
  componentId: "button--primary",
  async: false,
  includeStyles: true
});

// Check all running jobs
await job_list({ status: "active" });

// Extract theme info
await get_theme_info({ includeAll: false });

// Get design tokens from CSS
await get_external_css({
  cssUrl: "https://my-storybook.com/assets/main.css"
});

Dicas de Uso para Assistentes de IA

  1. Comece pela descoberta: Use list_components com compact: true
  2. Obtenha as variantes primeiro: Use get_component_html com variantsOnly: true
  3. Use assíncrono para HTML: O modo assíncrono padrão evita timeouts em componentes grandes
  4. Consulte job_status: Verifique a conclusão do trabalho antes de ler os resultados
  5. Busque por finalidade: Use search_components com o parâmetro purpose

Exemplos de Prompts

Após a conexão, você pode usar prompts em linguagem natural com o Claude:

MCP Servers Connected

Descoberta de Componentes:

Show me all available button components in the design system

Construindo Novos Recursos:

I need to create a user profile card. Find relevant components
from the design system and show me their HTML structure.

Análise do Design System:

Extract the color palette and typography tokens from the design system.
I want to ensure my new component matches the existing styles.

Migração de Componentes:

Get the HTML and styles for the "alert" component. I need to
recreate it in a different framework while keeping the same look.

Fluxo de Trabalho com Múltiplas Ferramentas:

First list all form-related components, then get the HTML for
the input and select components. I'm building a registration form.

Como Funciona

Conecta-se ao Storybook via endpoints /index.json e /iframe.html. Usa Puppeteer com Chrome headless para renderização dinâmica de JavaScript. Operações de longa duração usam uma fila de trabalhos em memória com no máximo 2 trabalhos simultâneos e TTL de 1 hora para trabalhos concluídos.

Solução de Problemas

  • Certifique-se de que o Storybook está em execução e que STORYBOOK_URL está correto
  • Use list_components primeiro para ver os componentes disponíveis
  • Para componentes grandes, use o modo assíncrono (padrão) e consulte job_status
  • Verifique o endpoint /index.json diretamente no navegador
  • Erros de certificado SSL: Defina NODE_TLS_REJECT_UNAUTHORIZED=0 para certificados autoassinados
  • Consulte DEVELOPMENT.md para solução de problemas detalhada

Requisitos

  • Node.js 20+
  • Chrome/Chromium (para Puppeteer)
  • Instância do Storybook em execução (veja abaixo as versões suportadas)

Versões suportadas do Storybook

Storybook 7, 8, 9 e 10. O servidor lê o índice de stories de /index.json, com fallback para /stories.json, e renderiza as stories através de /iframe.html?id=<storyId> — endpoints que permaneceram estáveis nas quatro versões principais.

Storybook 6 e versões anteriores não são suportados: eles são anteriores ao /index.json e usam um esquema de ID de story diferente.

Tanto um servidor de desenvolvimento (npm run storybook) quanto um Storybook estático compilado servido via HTTP funcionarão.

Desenvolvimento

Consulte DEVELOPMENT.md para instruções detalhadas de desenvolvimento.

Autor

Criado por Tomáš Grasl

Licença

MIT