bunge-ds-mcp
Servidor MCP (Model Context Protocol) que expõe o catálogo de componentes do Design System @bunge/ds-components. Permite que assistentes de IA listem, busquem e obtenham detalhes completos dos componentes — incluindo inputs, outputs, exemplos de uso e instruções de import.
O servidor se comunica via stdio (não expõe porta HTTP). A comunicação acontece pelo próprio processo, integrado diretamente ao cliente MCP (ex: VS Code Copilot).
Tools
| Tool | Descrição |
|---|---|
list-components | Lista todos os componentes disponíveis, com filtro opcional por categoria (form, layout, navigation, feedback, data-display, overlay) |
get-component | Retorna detalhes completos de um componente por ID (inputs, outputs, uso, import) |
search-components | Busca componentes por nome, descrição ou tags |
get-component-usage | Retorna exemplos de uso e instruções de import de um componente |
Como iniciar
Pré-requisitos
- Node.js 18+
- npm 9+
Instalação e build
npm install
npm run build
Executar localmente
npm start
O servidor inicia via stdio — não há porta HTTP. Ele é consumido por clientes MCP que se conectam ao processo diretamente.
Configuração no cliente MCP (ex: VS Code)
{
"mcpServers": {
"bunge-ds-mcp": {
"command": "npx",
"args": ["bunge-ds-mcp"]
}
}
}
Ou apontando para o build local:
{
"mcpServers": {
"bunge-ds-mcp": {
"command": "node",
"args": ["dist/index.js"]
}
}
}
Scripts do package.json
| Script | Comando | Descrição |
|---|---|---|
build | tsc | Compila o TypeScript para JavaScript na pasta dist/ |
start | node dist/index.js | Inicia o servidor MCP (requer build prévio) |
dev | tsc --watch | Compila em modo watch — recompila automaticamente a cada alteração |
dev:inspect | tsc && npx @modelcontextprotocol/inspector node dist/index.js | Compila e abre o MCP Inspector para testar as tools interativamente |
test | vitest run | Executa os testes unitários uma vez |
test:watch | vitest | Executa os testes em modo watch |
docker:infra:up | docker compose up -d --wait | Sobe o Verdaccio (registry npm privado) na porta 4873 |
docker:infra:down | docker compose down | Para e remove o container do Verdaccio |
registry:login:private | npm login --registry http://localhost:4873 | Faz login no registry privado local (Verdaccio) |
release:private | npm version patch && npm publish --registry http://localhost:4873 | Incrementa a versão (patch) e publica no registry privado local |
Infraestrutura local (Docker)
O docker-compose.yaml sobe um Verdaccio — registry npm privado — na porta 4873 (http://localhost:4873). Usado para simular publicação do pacote sem enviar ao npm público.
npm run docker:infra:up # sobe o Verdaccio
npm run registry:login:private # autentica no registry local
npm run release:private # publica o pacote localmente
Estrutura do projeto
src/
├── index.ts # Entrada: cria o McpServer e conecta ao transport
├── tools/ # Registro das tools (uma por arquivo)
│ ├── index.ts # Barrel — registra todas as tools
│ ├── list-components.ts
│ ├── get-component.ts
│ ├── search-components.ts
│ └── get-component-usage.ts
├── data/
│ └── components.ts # Catálogo de componentes do DS
├── models/
│ └── mcp-server.model.ts # Interfaces e tipos
└── tests/
├── data.spec.ts
└── tools.spec.ts