🎨 Kinghost Widgetbook MCP Server

Um servidor Model Context Protocol (MCP) para consultar componentes e tokens do Design System Kinghost através do Widgetbook. Facilita o acesso a informações de componentes, propriedades, exemplos de uso e design tokens durante o desenvolvimento.

📋 Sobre

Este servidor MCP oferece ferramentas para desenvolvedores consultarem o Design System da Kinghost:

• 🧩 Listar Componentes: Visualizar todos os componentes disponíveis
• 🔍 Buscar Componente: Obter informações detalhadas de um componente específico
• ⚙️ Obter Propriedades: Consultar props e configurações de componentes
• 🎨 Buscar Tokens: Acessar tokens de design (cores, espaçamento, tipografia)
• 💡 Obter Exemplos: Ver exemplos de código e boas práticas de uso

🚀 Instalação e Uso

📦 Via NPX (Recomendado)

A forma mais fácil de usar o servidor é diretamente via npx:

# Executar diretamente (sempre a versão mais recente)
npx kinghost-widgetbook-mcp

# Ou instalar globalmente
npm install -g kinghost-widgetbook-mcp
kinghost-widgetbook-mcp

🔧 Configuração de Ambiente

O servidor pode ser configurado através de variáveis de ambiente:

# URL do Widgetbook da Kinghost
export WIDGETBOOK_URL="https://widgetbook.kinghost.com"

# Endpoint da API (se disponível)
export WIDGETBOOK_API="/api/v1"

# Executar o servidor
npx kinghost-widgetbook-mcp

🔧 Instalação Local para Desenvolvimento

Pré-requisitos

• Node.js 18+ (recomendado)
• npm ou yarn

Passos

1. Clone o projeto:

git clone <url-do-repositorio>
cd kinghost-widgetbook-mcp

2. Instale as dependências:

npm install

3. Configure as variáveis de ambiente:

cp .env.example .env
# Edite .env com as URLs corretas

4. Execute o servidor:

npm start

🛠️ Uso

Como Servidor MCP Standalone

O servidor roda via STDIO e pode ser conectado a qualquer cliente MCP compatível:

npx kinghost-widgetbook-mcp

Integração com Clientes MCP

Claude Desktop / Cursor (via NPX)

Adicione ao arquivo de configuração MCP:

{
  "mcpServers": {
    "kinghost-widgetbook": {
      "command": "npx",
      "args": ["kinghost-widgetbook-mcp"],
      "env": {
        "WIDGETBOOK_URL": "https://widgetbook.kinghost.com"
      }
    }
  }
}

Claude Desktop / Cursor (instalação local)

Para desenvolvimento local:

{
  "mcpServers": {
    "kinghost-widgetbook": {
      "command": "node",
      "args": ["/caminho/para/kinghost-widgetbook-mcp/index.js"],
      "env": {
        "WIDGETBOOK_URL": "https://widgetbook.kinghost.com"
      }
    }
  }
}

🔧 Ferramentas Disponíveis

1. listar_componentes

Descrição: Lista todos os componentes disponíveis no Design System

Parâmetros:

• categoria (opcional): Filtrar por categoria (Actions, Layout, Forms, Display, etc.)
• status (opcional): Filtrar por status (stable, beta, deprecated, all)

Exemplo:

{
  "name": "listar_componentes",
  "arguments": {
    "categoria": "Actions",
    "status": "stable"
  }
}

2. buscar_componente

Descrição: Busca informações detalhadas de um componente específico

Parâmetros:

• nome (obrigatório): Nome do componente
• incluir_exemplos (opcional): Incluir exemplos de código (padrão: true)
• incluir_props (opcional): Incluir propriedades (padrão: true)

Exemplo:

{
  "name": "buscar_componente",
  "arguments": {
    "nome": "Button",
    "incluir_exemplos": true,
    "incluir_props": true
  }
}

3. obter_props

Descrição: Obtém lista detalhada das propriedades de um componente

Parâmetros:

• componente (obrigatório): Nome do componente
• apenas_obrigatorias (opcional): Mostrar apenas props obrigatórias (padrão: false)

Exemplo:

{
  "name": "obter_props",
  "arguments": {
    "componente": "Button",
    "apenas_obrigatorias": false
  }
}

4. buscar_tokens

Descrição: Busca tokens de design (cores, espaçamento, tipografia, etc.)

Parâmetros:

• categoria (opcional): Categoria específica (colors, spacing, typography, borderRadius, all)
• busca (opcional): Termo de busca específico

Exemplo:

{
  "name": "buscar_tokens",
  "arguments": {
    "categoria": "colors",
    "busca": "primary"
  }
}

5. obter_exemplos

Descrição: Obtém exemplos de código e uso de um componente

Parâmetros:

• componente (obrigatório): Nome do componente
• formato (opcional): Formato dos exemplos (jsx, html, all)

Exemplo:

{
  "name": "obter_exemplos",
  "arguments": {
    "componente": "Button",
    "formato": "jsx"
  }
}

🏗️ Arquitetura

Estrutura do Projeto

kinghost-widgetbook-mcp/
├── index.js              # Servidor MCP principal
├── package.json           # Dependências e scripts
├── .npmrc.example        # Exemplo de configuração npm
├── .gitignore            # Arquivos ignorados pelo Git
├── .npmignore            # Arquivos ignorados pelo npm
└── README.md             # Esta documentação

Dependências

• @modelcontextprotocol/sdk - SDK oficial do MCP
• zod - Validação de schemas TypeScript-first
• node-fetch - Cliente HTTP para consultar APIs
• cheerio - Parser HTML para fallback de scraping

Fluxo de Funcionamento

1. Inicialização: Servidor MCP iniciado via STDIO
2. Configuração: Lê variáveis de ambiente para URLs do Widgetbook
3. Descoberta: Cliente lista ferramentas disponíveis (tools/list)
4. Execução: Cliente chama ferramentas específicas (tools/call)
5. Consulta:
   • Tenta acessar API do Widgetbook
   • Fallback para parsing HTML se necessário
   • Retorna dados mock em caso de erro (desenvolvimento)
6. Resposta: Retorna informações formatadas em Markdown

Estratégias de Acesso aos Dados

O servidor implementa múltiplas estratégias para acessar os dados do Widgetbook:

1. API REST (preferencial): Consulta endpoints JSON estruturados
2. Parsing HTML (fallback): Extrai dados diretamente do HTML
3. Dados Mock (desenvolvimento): Fornece exemplos durante desenvolvimento

🔧 Configuração

Variáveis de Ambiente

| Variável | Descrição | Padrão | |----------|-----------|---------| | WIDGETBOOK_URL | URL base do Widgetbook | https://widgetbook.kinghost.com | | WIDGETBOOK_API | Endpoint da API | /api/v1 |

Configuração para Diferentes Ambientes

# Desenvolvimento
export WIDGETBOOK_URL="http://localhost:3000"

# Staging
export WIDGETBOOK_URL="https://staging-widgetbook.kinghost.com"

# Produção
export WIDGETBOOK_URL="https://widgetbook.kinghost.com"

🧪 Teste e Desenvolvimento

Teste Local

# Instalar dependências
npm install

# Executar em modo desenvolvimento
npm run dev

# Testar com dados mock
node index.js

Teste com Cliente MCP

import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["kinghost-widgetbook-mcp"]
});

// Listar componentes
const result = await client.callTool("listar_componentes", {
  categoria: "Actions"
});

🚨 Solução de Problemas

Erro: "Cannot fetch Widgetbook data"

Causa: URL do Widgetbook não configurada ou inacessível Solução:

• Verifique a variável WIDGETBOOK_URL
• Teste o acesso manual à URL
• Verifique conectividade de rede

Erro: "Component not found"

Causa: Nome do componente incorreto ou não existe Solução: Use listar_componentes para ver nomes disponíveis

Dados Mock sendo retornados

Causa: Servidor não consegue acessar o Widgetbook real Solução:

• Configure WIDGETBOOK_URL corretamente
• Verifique se o Widgetbook está online
• Em desenvolvimento, isso é normal

Timeout errors

Causa: Widgetbook demora para responder Solução: O timeout padrão é 30s, verifique a conectividade

📝 Scripts Disponíveis

npm start       # Inicia o servidor
npm run dev     # Inicia com auto-reload (Node 18+)

📦 Publicação no NPM

Para publicar atualizações do servidor:

1. Preparação

npm whoami  # Verificar login npm

2. Atualizar versão

npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

3. Publicar

npm publish

4. Verificar

npx kinghost-widgetbook-mcp

🤝 Contribuindo

1. Fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🔗 Links Úteis

• Model Context Protocol Specification
• MCP SDK Documentation
• Claude MCP Integration
• Kinghost Design System

Desenvolvido com ❤️ para a comunidade Kinghost 🚀