{"_id":"@cyberweb/kinghost-widgetbook-mcp","_rev":"3-906d6f94886051b7e9392e6db1a392af","name":"@cyberweb/kinghost-widgetbook-mcp","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@cyberweb/kinghost-widgetbook-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","kinghost","widgetbook","design-system","components","ui","design-tokens","claude","ai"],"author":{"name":"Squad DevCanais - Kinghost","email":"produtos-canais@kinghost.com.br"},"license":"MIT","_id":"@cyberweb/kinghost-widgetbook-mcp@1.0.0","maintainers":[{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},{"name":"security-kinghost","email":"security@kinghost.com.br"}],"contributors":[{"url":"https://kinghost.com","name":"Squad DevCanais","email":"produtos-canais@kinghost.com.br"}],"homepage":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app","bugs":{"url":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app/-/issues"},"bin":{"kinghost-widgetbook-mcp":"index.js"},"dist":{"shasum":"650457a29897e99321b53fa03384772bf69980f2","tarball":"https://registry.npmjs.org/@cyberweb/kinghost-widgetbook-mcp/-/kinghost-widgetbook-mcp-1.0.0.tgz","fileCount":4,"integrity":"sha512-2HigXJFLZc6kBSPln/kPWXXXC+qespX6pXnw1wRzwO91hNil7MEUKCVixcDcG1Ny/f+sts5I1WmCskYTan+RbA==","signatures":[{"sig":"MEUCIBzE+DrICQ1cSbdkiiGv0+rIzeNC23tzq+bo2/uPSaC5AiEA9LpEddCEgF81YEqYiw72yGFLcTHO/VatC6XXYPkYoRY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30585},"main":"index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"f651cfb9701f5270fa48418c9104e355dfc4d319","scripts":{"dev":"node --watch index.js","start":"node index.js","prepublishOnly":"echo '🚀 Publicando @cyberweb/kinghost-widgetbook-mcp...'"},"_npmUser":{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},"repository":{"url":"git@gitlab-administrativo.kinghost.net:DevCanais/design-system-app/mcp-app.git","type":"git"},"_npmVersion":"10.9.2","description":"🎨 Servidor MCP para consultar componentes e tokens do Design System Kinghost via Widgetbook - Desenvolvido pela Squad DevCanais","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.22.0","cheerio":"^1.0.0-rc.12","node-fetch":"^3.3.2","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kinghost-widgetbook-mcp_1.0.0_1753403754827_0.7110572928955659","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cyberweb/kinghost-widgetbook-mcp","version":"1.0.1","keywords":["mcp","model-context-protocol","kinghost","widgetbook","design-system","components","ui","design-tokens","claude","ai"],"author":{"name":"Squad DevCanais - Kinghost","email":"produtos-canais@kinghost.com.br"},"license":"MIT","_id":"@cyberweb/kinghost-widgetbook-mcp@1.0.1","maintainers":[{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},{"name":"security-kinghost","email":"security@kinghost.com.br"}],"contributors":[{"url":"https://kinghost.com","name":"Squad DevCanais","email":"produtos-canais@kinghost.com.br"}],"homepage":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app","bugs":{"url":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app/-/issues"},"bin":{"kinghost-widgetbook-mcp":"index.js"},"dist":{"shasum":"07235bbe982ddf56e284f5c10abe1602c75cc387","tarball":"https://registry.npmjs.org/@cyberweb/kinghost-widgetbook-mcp/-/kinghost-widgetbook-mcp-1.0.1.tgz","fileCount":4,"integrity":"sha512-WTWwGTBcKn64OwPnq+re5NoFabdxP5/bBBx1AtwvOJq+v770Iy1Cn5Sqt0QaId0FhEcv5W/XrOYZb7SdkFiuuQ==","signatures":[{"sig":"MEUCIQCdCnei71UUnQq2WcCDZs358ywnkXctE8sYKYTiWrWGjwIgJ9qF9Bdh0UsMTPNyWvJGz+/R+Uzl05kE4mQfgTGi67U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30585},"main":"index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"3a3a8e2ade0a8ff300006b8ce111286d99640dff","scripts":{"dev":"node --watch index.js","start":"node index.js","prepublishOnly":"echo '🚀 Publicando @cyberweb/kinghost-widgetbook-mcp...'"},"_npmUser":{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},"repository":{"url":"git@gitlab-administrativo.kinghost.net:DevCanais/design-system-app/mcp-app.git","type":"git"},"_npmVersion":"10.9.2","description":"🎨 Servidor MCP para consultar componentes e tokens do Design System Kinghost via Widgetbook - Desenvolvido pela Squad DevCanais","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.22.0","cheerio":"^1.0.0-rc.12","node-fetch":"^3.3.2","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kinghost-widgetbook-mcp_1.0.1_1753404298654_0.01371337502696135","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@cyberweb/kinghost-widgetbook-mcp","version":"1.0.2","description":"🎨 Servidor MCP para consultar componentes e tokens do Design System Kinghost via Widgetbook - Desenvolvido pela Squad DevCanais","type":"module","main":"index.js","bin":{"kinghost-widgetbook-mcp":"index.js"},"scripts":{"start":"node index.js","dev":"node --watch index.js","prepublishOnly":"echo '🚀 Publicando @cyberweb/kinghost-widgetbook-mcp...'"},"keywords":["mcp","model-context-protocol","kinghost","widgetbook","design-system","components","ui","design-tokens","claude","ai"],"author":{"name":"Squad DevCanais - Kinghost","email":"produtos-canais@kinghost.com.br"},"contributors":[{"name":"Squad DevCanais","email":"produtos-canais@kinghost.com.br","url":"https://kinghost.com"}],"license":"MIT","homepage":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app","repository":{"type":"git","url":"git@gitlab-administrativo.kinghost.net:DevCanais/design-system-app/mcp-app.git"},"bugs":{"url":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app/-/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.22.0"},"engines":{"node":">=18.0.0"},"_id":"@cyberweb/kinghost-widgetbook-mcp@1.0.2","gitHead":"ed32e8f891b3441f4ee0f35cf0552f98c81b2589","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-lmpdOC1XTH7yF8y3iZTGyCnV0QxSwiXhXoQQrXcTBFtCPPIMGzCXL8L03enyoLv+S881JC7zzpefvPsDF5bOAQ==","shasum":"b90db9b325cdac48bfd0b03448cf57576e926ec4","tarball":"https://registry.npmjs.org/@cyberweb/kinghost-widgetbook-mcp/-/kinghost-widgetbook-mcp-1.0.2.tgz","fileCount":4,"unpackedSize":18804,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCpZx6Hk5rggfWvc/+H7pN2WrblZXChBixF5smrJ1UdvgIhAKFyLNaq23u5HmZAFGgqsx7PdlnqUEGCFlALGzFEtnW3"}]},"_npmUser":{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},"directories":{},"maintainers":[{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},{"name":"security-kinghost","email":"security@kinghost.com.br"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kinghost-widgetbook-mcp_1.0.2_1753407048096_0.6700401581642488"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-25T00:35:54.826Z","modified":"2025-07-25T01:30:48.523Z","1.0.0":"2025-07-25T00:35:55.074Z","1.0.1":"2025-07-25T00:44:58.836Z","1.0.2":"2025-07-25T01:30:48.275Z"},"bugs":{"url":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app/-/issues"},"author":{"name":"Squad DevCanais - Kinghost","email":"produtos-canais@kinghost.com.br"},"license":"MIT","homepage":"https://gitlab-administrativo.kinghost.net/DevCanais/design-system-app/mcp-app","keywords":["mcp","model-context-protocol","kinghost","widgetbook","design-system","components","ui","design-tokens","claude","ai"],"repository":{"type":"git","url":"git@gitlab-administrativo.kinghost.net:DevCanais/design-system-app/mcp-app.git"},"description":"🎨 Servidor MCP para consultar componentes e tokens do Design System Kinghost via Widgetbook - Desenvolvido pela Squad DevCanais","contributors":[{"name":"Squad DevCanais","email":"produtos-canais@kinghost.com.br","url":"https://kinghost.com"}],"maintainers":[{"name":"botmarvin","email":"produtos-canais@kinghost.com.br"},{"name":"security-kinghost","email":"security@kinghost.com.br"}],"readme":"# 🎨 Kinghost Widgetbook MCP Server\n\nUm 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.\n\n## 📋 Sobre\n\nEste servidor MCP oferece ferramentas para desenvolvedores consultarem o Design System da Kinghost:\n\n- 🧩 **Listar Componentes**: Visualizar todos os componentes disponíveis\n- 🔍 **Buscar Componente**: Obter informações detalhadas de um componente específico\n- ⚙️ **Obter Propriedades**: Consultar props e configurações de componentes\n- 🎨 **Buscar Tokens**: Acessar tokens de design (cores, espaçamento, tipografia)\n- 💡 **Obter Exemplos**: Ver exemplos de código e boas práticas de uso\n\n## 🚀 Instalação e Uso\n\n### 📦 Via NPX (Recomendado)\n\nA forma mais fácil de usar o servidor é diretamente via npx:\n\n```bash\n# Executar diretamente (sempre a versão mais recente)\nnpx kinghost-widgetbook-mcp\n\n# Ou instalar globalmente\nnpm install -g kinghost-widgetbook-mcp\nkinghost-widgetbook-mcp\n```\n\n### 🔧 Configuração de Ambiente\n\nO servidor pode ser configurado através de variáveis de ambiente:\n\n```bash\n# URL do Widgetbook da Kinghost\nexport WIDGETBOOK_URL=\"https://widgetbook.kinghost.com\"\n\n# Endpoint da API (se disponível)\nexport WIDGETBOOK_API=\"/api/v1\"\n\n# Executar o servidor\nnpx kinghost-widgetbook-mcp\n```\n\n### 🔧 Instalação Local para Desenvolvimento\n\n#### Pré-requisitos\n- Node.js 18+ (recomendado)\n- npm ou yarn\n\n#### Passos\n\n1. **Clone o projeto:**\n```bash\ngit clone <url-do-repositorio>\ncd kinghost-widgetbook-mcp\n```\n\n2. **Instale as dependências:**\n```bash\nnpm install\n```\n\n3. **Configure as variáveis de ambiente:**\n```bash\ncp .env.example .env\n# Edite .env com as URLs corretas\n```\n\n4. **Execute o servidor:**\n```bash\nnpm start\n```\n\n## 🛠️ Uso\n\n### Como Servidor MCP Standalone\n\nO servidor roda via STDIO e pode ser conectado a qualquer cliente MCP compatível:\n\n```bash\nnpx kinghost-widgetbook-mcp\n```\n\n### Integração com Clientes MCP\n\n#### Claude Desktop / Cursor (via NPX)\nAdicione ao arquivo de configuração MCP:\n\n```json\n{\n  \"mcpServers\": {\n    \"kinghost-widgetbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"kinghost-widgetbook-mcp\"],\n      \"env\": {\n        \"WIDGETBOOK_URL\": \"https://widgetbook.kinghost.com\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Desktop / Cursor (instalação local)\nPara desenvolvimento local:\n\n```json\n{\n  \"mcpServers\": {\n    \"kinghost-widgetbook\": {\n      \"command\": \"node\",\n      \"args\": [\"/caminho/para/kinghost-widgetbook-mcp/index.js\"],\n      \"env\": {\n        \"WIDGETBOOK_URL\": \"https://widgetbook.kinghost.com\"\n      }\n    }\n  }\n}\n```\n\n## 🔧 Ferramentas Disponíveis\n\n### 1. `listar_componentes`\n\n**Descrição:** Lista todos os componentes disponíveis no Design System\n\n**Parâmetros:**\n- `categoria` (opcional): Filtrar por categoria (Actions, Layout, Forms, Display, etc.)\n- `status` (opcional): Filtrar por status (stable, beta, deprecated, all)\n\n**Exemplo:**\n```json\n{\n  \"name\": \"listar_componentes\",\n  \"arguments\": {\n    \"categoria\": \"Actions\",\n    \"status\": \"stable\"\n  }\n}\n```\n\n### 2. `buscar_componente`\n\n**Descrição:** Busca informações detalhadas de um componente específico\n\n**Parâmetros:**\n- `nome` (obrigatório): Nome do componente\n- `incluir_exemplos` (opcional): Incluir exemplos de código (padrão: true)\n- `incluir_props` (opcional): Incluir propriedades (padrão: true)\n\n**Exemplo:**\n```json\n{\n  \"name\": \"buscar_componente\",\n  \"arguments\": {\n    \"nome\": \"Button\",\n    \"incluir_exemplos\": true,\n    \"incluir_props\": true\n  }\n}\n```\n\n### 3. `obter_props`\n\n**Descrição:** Obtém lista detalhada das propriedades de um componente\n\n**Parâmetros:**\n- `componente` (obrigatório): Nome do componente\n- `apenas_obrigatorias` (opcional): Mostrar apenas props obrigatórias (padrão: false)\n\n**Exemplo:**\n```json\n{\n  \"name\": \"obter_props\",\n  \"arguments\": {\n    \"componente\": \"Button\",\n    \"apenas_obrigatorias\": false\n  }\n}\n```\n\n### 4. `buscar_tokens`\n\n**Descrição:** Busca tokens de design (cores, espaçamento, tipografia, etc.)\n\n**Parâmetros:**\n- `categoria` (opcional): Categoria específica (colors, spacing, typography, borderRadius, all)\n- `busca` (opcional): Termo de busca específico\n\n**Exemplo:**\n```json\n{\n  \"name\": \"buscar_tokens\",\n  \"arguments\": {\n    \"categoria\": \"colors\",\n    \"busca\": \"primary\"\n  }\n}\n```\n\n### 5. `obter_exemplos`\n\n**Descrição:** Obtém exemplos de código e uso de um componente\n\n**Parâmetros:**\n- `componente` (obrigatório): Nome do componente\n- `formato` (opcional): Formato dos exemplos (jsx, html, all)\n\n**Exemplo:**\n```json\n{\n  \"name\": \"obter_exemplos\",\n  \"arguments\": {\n    \"componente\": \"Button\",\n    \"formato\": \"jsx\"\n  }\n}\n```\n\n## 🏗️ Arquitetura\n\n### Estrutura do Projeto\n```\nkinghost-widgetbook-mcp/\n├── index.js              # Servidor MCP principal\n├── package.json           # Dependências e scripts\n├── .npmrc.example        # Exemplo de configuração npm\n├── .gitignore            # Arquivos ignorados pelo Git\n├── .npmignore            # Arquivos ignorados pelo npm\n└── README.md             # Esta documentação\n```\n\n### Dependências\n- `@modelcontextprotocol/sdk` - SDK oficial do MCP\n- `zod` - Validação de schemas TypeScript-first\n- `node-fetch` - Cliente HTTP para consultar APIs\n- `cheerio` - Parser HTML para fallback de scraping\n\n### Fluxo de Funcionamento\n\n1. **Inicialização:** Servidor MCP iniciado via STDIO\n2. **Configuração:** Lê variáveis de ambiente para URLs do Widgetbook\n3. **Descoberta:** Cliente lista ferramentas disponíveis (`tools/list`)\n4. **Execução:** Cliente chama ferramentas específicas (`tools/call`)\n5. **Consulta:** \n   - Tenta acessar API do Widgetbook\n   - Fallback para parsing HTML se necessário\n   - Retorna dados mock em caso de erro (desenvolvimento)\n6. **Resposta:** Retorna informações formatadas em Markdown\n\n### Estratégias de Acesso aos Dados\n\nO servidor implementa múltiplas estratégias para acessar os dados do Widgetbook:\n\n1. **API REST** (preferencial): Consulta endpoints JSON estruturados\n2. **Parsing HTML** (fallback): Extrai dados diretamente do HTML\n3. **Dados Mock** (desenvolvimento): Fornece exemplos durante desenvolvimento\n\n## 🔧 Configuração\n\n### Variáveis de Ambiente\n\n| Variável | Descrição | Padrão |\n|----------|-----------|---------|\n| `WIDGETBOOK_URL` | URL base do Widgetbook | `https://widgetbook.kinghost.com` |\n| `WIDGETBOOK_API` | Endpoint da API | `/api/v1` |\n\n### Configuração para Diferentes Ambientes\n\n```bash\n# Desenvolvimento\nexport WIDGETBOOK_URL=\"http://localhost:3000\"\n\n# Staging\nexport WIDGETBOOK_URL=\"https://staging-widgetbook.kinghost.com\"\n\n# Produção\nexport WIDGETBOOK_URL=\"https://widgetbook.kinghost.com\"\n```\n\n## 🧪 Teste e Desenvolvimento\n\n### Teste Local\n\n```bash\n# Instalar dependências\nnpm install\n\n# Executar em modo desenvolvimento\nnpm run dev\n\n# Testar com dados mock\nnode index.js\n```\n\n### Teste com Cliente MCP\n\n```javascript\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst transport = new StdioClientTransport({\n  command: \"npx\",\n  args: [\"kinghost-widgetbook-mcp\"]\n});\n\n// Listar componentes\nconst result = await client.callTool(\"listar_componentes\", {\n  categoria: \"Actions\"\n});\n```\n\n## 🚨 Solução de Problemas\n\n### Erro: \"Cannot fetch Widgetbook data\"\n**Causa:** URL do Widgetbook não configurada ou inacessível\n**Solução:** \n- Verifique a variável `WIDGETBOOK_URL`\n- Teste o acesso manual à URL\n- Verifique conectividade de rede\n\n### Erro: \"Component not found\"\n**Causa:** Nome do componente incorreto ou não existe\n**Solução:** Use `listar_componentes` para ver nomes disponíveis\n\n### Dados Mock sendo retornados\n**Causa:** Servidor não consegue acessar o Widgetbook real\n**Solução:** \n- Configure `WIDGETBOOK_URL` corretamente\n- Verifique se o Widgetbook está online\n- Em desenvolvimento, isso é normal\n\n### Timeout errors\n**Causa:** Widgetbook demora para responder\n**Solução:** O timeout padrão é 30s, verifique a conectividade\n\n## 📝 Scripts Disponíveis\n\n```bash\nnpm start       # Inicia o servidor\nnpm run dev     # Inicia com auto-reload (Node 18+)\n```\n\n## 📦 Publicação no NPM\n\nPara publicar atualizações do servidor:\n\n### 1. Preparação\n```bash\nnpm whoami  # Verificar login npm\n```\n\n### 2. Atualizar versão\n```bash\nnpm version patch  # 1.0.0 -> 1.0.1\nnpm version minor  # 1.0.0 -> 1.1.0\nnpm version major  # 1.0.0 -> 2.0.0\n```\n\n### 3. Publicar\n```bash\nnpm publish\n```\n\n### 4. Verificar\n```bash\nnpx kinghost-widgetbook-mcp\n```\n\n## 🤝 Contribuindo\n\n1. Fork do projeto\n2. Crie uma branch para sua feature (`git checkout -b feature/nova-funcionalidade`)\n3. Commit suas mudanças (`git commit -am 'Adiciona nova funcionalidade'`)\n4. Push para a branch (`git push origin feature/nova-funcionalidade`)\n5. Abra um Pull Request\n\n## 📄 Licença\n\nEste projeto está licenciado sob a MIT License - veja o arquivo [LICENSE](LICENSE) para detalhes.\n\n## 🔗 Links Úteis\n\n- [Model Context Protocol Specification](https://modelcontextprotocol.io/)\n- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)\n- [Claude MCP Integration](https://docs.anthropic.com/claude/docs/mcp)\n- [Kinghost Design System](https://kinghost.com)\n\n---\n\n**Desenvolvido com ❤️ para a comunidade Kinghost** 🚀 ","readmeFilename":"README.md"}