ds-components-mcp

Servidor MCP (Model Context Protocol) que expõe o catálogo de componentes do Design System @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": {
    "ds-components-mcp": {
      "command": "npx",
      "args": ["ds-components-mcp"]
    }
  }
}

Ou apontando para o build local:

{
  "mcpServers": {
    "ds-components-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