# 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

```bash
npm install
npm run build
```

### Executar localmente

```bash
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)

```json
{
  "mcpServers": {
    "bunge-ds-mcp": {
      "command": "npx",
      "args": ["bunge-ds-mcp"]
    }
  }
}
```

Ou apontando para o build local:

```json
{
  "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](https://verdaccio.org/) — registry npm privado — na porta **4873** (`http://localhost:4873`). Usado para simular publicação do pacote sem enviar ao npm público.

```bash
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
```