MCP Brasil

Servidor MCP (Model Context Protocol) escrito em TypeScript que expõe dados públicos brasileiros — CEP, CNPJ, CPF, bancos, feriados nacionais, municípios e DDD — como tools e resources para qualquer cliente MCP (Claude Desktop, Claude Code, ou uma integração própria).

⚠️ Licença proprietária. Este código é disponibilizado publicamente apenas para consulta/avaliação (ex.: portfólio). Cópia, uso, execução, modificação ou distribuição não são permitidos sem autorização prévia e por escrito do autor. Veja LICENSE.

Índice

• Visão geral

• Por que este projeto existe

• Tools disponíveis

• Resources disponíveis

• Transportes

• Arquitetura

• Estrutura de pastas

• Stack técnica

• Segurança e robustez

• Estratégia de testes

• Executando localmente

• Configuração (variáveis de ambiente)

• Licença

Related MCP server: brasil-data-mcp

Visão geral

LLMs não têm, nativamente, acesso a dados cadastrais e de referência do Brasil: não sabem o endereço de um CEP, se um CNPJ está ativo, quais são os feriados nacionais de um ano, ou qual estado corresponde a um DDD. Para que um agente de IA seja útil em fluxos de cadastro, cobrança, atendimento ou integração no contexto brasileiro, ele precisa de acesso confiável a esses dados — com validação de entrada, cache, tratamento de falhas e mensagens de erro que o próprio modelo consiga interpretar.

O MCP Brasil resolve isso implementando o protocolo MCP (o padrão aberto usado pelo Claude e por um número crescente de outros clientes de IA para conectar modelos a ferramentas e dados externos) sobre um conjunto de APIs públicas brasileiras: BrasilAPI, ViaCEP e o IBGE. O resultado é um binário que roda com npx mcp-brasil e se conecta a qualquer cliente MCP.

Por que este projeto existe

Este projeto nasceu como peça de portfólio técnico, para demonstrar:

• Domínio do protocolo MCP e do SDK oficial (@modelcontextprotocol/sdk), incluindo tools, resources e os dois transportes padrão (stdio e streamable HTTP).

• Engenharia de integração de verdade: múltiplos providers HTTP com fallback, cache com TTL, rate limiting por provedor, retry com backoff, timeout, e tratamento cuidadoso de erros de API (inclusive comportamentos inconsistentes entre elas — ver Segurança e robustez).

• TypeScript rigoroso, com validação de schema via Zod convertida automaticamente em JSON Schema para as tools.

• Uma suíte de testes em três camadas (unitária, integração com APIs mockadas de forma realista, e end-to-end com o binário real), com cobertura de 100% nas partes testáveis.

Tools disponíveis

Cada tool retorna, ao mesmo tempo, um bloco de texto legível (para o modelo ler diretamente) e um bloco structuredContent em JSON (para o modelo — ou o código que orquestra o agente — consumir de forma programática).

Resources disponíveis

Transportes

O servidor suporta os dois transportes definidos pela especificação MCP:

• stdio (padrão): usado por Claude Desktop e Claude Code, que gerenciam o processo filho e conversam com ele via stdin/stdout. Todo log vai para stderr — stdout é reservado exclusivamente para o canal JSON-RPC.

• HTTP (streamable): para hospedar o servidor você mesmo. Ative com MCP_TRANSPORT=http; o servidor expõe POST /mcp. Roda em modo stateless (cada requisição HTTP recebe sua própria instância de servidor/transporte MCP; os caches e o rate limiter, por serem módulos singleton, continuam compartilhados entre requisições).

Arquitetura

Cliente MCP (Claude Desktop / Code / outro)
        │  JSON-RPC (stdio | HTTP)
┌───────▼────────────────────────────────┐
│ server/   McpServer (SDK oficial)      │
│   registra tools e resources           │
├─────────────────────────────────────────┤
│ tools/    uma pasta por tool           │
│   schema (Zod) + handler + format      │
├─────────────────────────────────────────┤
│ providers/ clients HTTP tipados        │
│   BrasilAPI, ViaCEP, IBGE + fallback   │
├─────────────────────────────────────────┤
│ infra/    cache, rate-limit, http,     │
│           logger, config               │
└─────────────────────────────────────────┘

Padrões usados:

• Injeção de dependência via factory: cada handler é criado por uma função createXHandler(deps) que recebe o provider e o cache como dependências. Isso permite testar a lógica de cada tool com providers falsos, sem tocar a rede, e ainda assim conectar instâncias reais no index.ts de cada tool.

• Provider com fallback: FallbackCepProvider tenta o ViaCEP e, só em caso de falha de infraestrutura (não de "CEP não existe"), cai para a BrasilAPI. Um CEP genuinamente inexistente nunca é mascarado tentando o próximo provider.

• Cache com deduplicação de chamadas concorrentes: Cache.getOrLoad guarda a promise em andamento por chave, então duas chamadas simultâneas para o mesmo CEP disparam uma requisição de rede, não duas.

• Rate limiting por provedor: um token bucket por nome de provider (viacep, brasilapi, ibge), aplicado de forma transparente em toda chamada HTTP, para não abusar das APIs públicas gratuitas usadas pelo servidor.

Estrutura de pastas

mcp-brasil/
├── bin/mcp-brasil.js            # entry point do npx
├── src/
│   ├── index.ts                 # bootstrap + escolha de transporte
│   ├── server/
│   │   ├── create-server.ts     # instancia o McpServer e registra tools/resources
│   │   └── transports/{stdio,http}.ts
│   ├── tools/                   # uma pasta por tool: schema.ts, handler.ts, format.ts, index.ts
│   ├── providers/                # clients HTTP tipados + fallback
│   ├── resources/                 # resources MCP (uf.resource.ts)
│   ├── infra/                    # cache, rate-limit, http (retry/timeout), logger, config
│   └── domain/                   # algoritmos de CPF/CNPJ, erros de domínio
├── tests/
│   ├── unit/                    # algoritmos, cache, rate limiter, handlers com providers fake
│   ├── integration/              # providers reais contra APIs mockadas (MSW), servidor via InMemoryTransport
│   └── e2e/                      # binário real via stdio e via HTTP
└── examples/                     # configs de exemplo para Claude Desktop e Claude Code

Stack técnica

Segurança e robustez

Pontos que foram verificados e endurecidos deliberadamente, não só assumidos:

• Rate limiting real: cada chamada HTTP passa por um token bucket por provedor antes de sair. Não é apenas uma classe isolada com testes — está de fato no caminho de toda requisição (infra/http.ts).

• Validação de entrada em todas as tools: schemas Zod com limites de tamanho (.max()) em todo campo de texto, evitando payloads arbitrariamente grandes. O resource brasil://uf/{sigla} — que não passa pela validação automática do SDK, diferente das tools — tem validação de formato própria antes de montar a URL de saída.

• Limite de tamanho de corpo no transporte HTTP: requisições acima de 1 MiB são rejeitadas com 413, evitando um vetor de exaustão de memória.

• Tratamento de erro 4xx sem retry inútil: qualquer erro 4xx (não só 404) é tratado como "não encontrado", sem consumir tentativas de retry — importante porque as APIs públicas usadas aqui são inconsistentes entre si (a BrasilAPI responde 400 para um DDD malformado e 404 para um banco inexistente; o IBGE responde 200 com corpo vazio para uma UF inexistente). Cada uma dessas variações foi observada contra a API real e coberta por teste.

• Nunca expõe stack trace ao cliente: toda falha de provider vira uma mensagem de erro legível (isError: true no formato MCP), nunca um erro bruto do runtime.

• Logs sempre em stderr: nunca poluem o canal JSON-RPC do transporte stdio.

• Sem segredos: todas as APIs usadas são públicas e não exigem chave de API, token ou credencial de nenhum tipo.

• npm audit limpo em produção: npm audit --omit=dev não acusa nenhuma vulnerabilidade nas dependências que de fato vão para o pacote publicado (as únicas vulnerabilidades reportadas pelo npm audit padrão são em ferramentas de desenvolvimento — vitest/vite/esbuild — e não afetam o código em execução).

Estratégia de testes

Três camadas, sem sobreposição de responsabilidade:

• Unitários (tests/unit): algoritmos de CPF/CNPJ contra casos válidos/inválidos conhecidos; cache (incluindo expiração por TTL e deduplicação de chamadas concorrentes); rate limiter (incluindo bloqueio, liberação por refill e reset entre testes); handler de cada tool, isoladamente, com um provider fake injetado — sem tocar em rede.

• Integração (tests/integration): os providers HTTP reais (ViaCepProvider, BrasilApiClient, IbgeClient) testados contra respostas mockadas com MSW, com fixtures fiéis ao formato exato das respostas reais dessas APIs (verificadas manualmente contra produção durante o desenvolvimento); o servidor MCP completo testado via InMemoryTransport do SDK oficial, cobrindo o fluxo real de tools/list e tools/call.

• E2E (tests/e2e): o binário publicado (bin/mcp-brasil.js) executado como processo real, com handshake MCP genuíno tanto via stdio quanto via HTTP (incluindo o limite de tamanho de corpo).

Executando localmente

Pré-requisito: Node.js 20+.

npm install
npm run dev              # roda via stdio, com hot-reload via tsx
npm test                 # build + suíte completa (unit + integração + e2e)
npm run test:coverage    # com relatório de cobertura
npm run lint
npm run typecheck
npm run format:check     # verifica formatação (Prettier)
npm run build            # gera dist/ (ESM + tipos)

Para testar manualmente contra um cliente MCP local, aponte-o para node bin/mcp-brasil.js (transporte stdio) — exemplos prontos de configuração em examples/claude_desktop_config.json e examples/claude-code.md.

Configuração (variáveis de ambiente)

Licença

Este projeto não é open source. Todos os direitos são reservados ao autor — cópia, uso, execução, modificação e distribuição são proibidos sem autorização prévia e por escrito. O texto completo está em LICENSE.