brazilian-dev-mcp

Brazilian Dev MCP

Servidor MCP (Model Context Protocol) com ferramentas utilitárias para desenvolvedores que trabalham com dados brasileiros — CPF, CNPJ, CEP, telefones, moeda, validações, dados fake e mais.

Instalação

git clone https://github.com/dan94k/brazilian-dev-mcp.git
cd brazilian-dev-mcp
npm install

Uso

Com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "brazilian-dev": {
      "command": "npx",
      "args": ["tsx", "caminho/para/brazilian-dev-mcp/src/index.js"]
    }
  }
}

Com opencode

Adicione ao seu opencode.json (no diretório do projeto ou em ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "brazilian-dev": {
      "type": "local",
      "command": ["npx", "tsx", "caminho/para/brazilian-dev-mcp/src/index.js"],
      "enabled": true
    }
  }
}

Após salvar, reinicie o opencode para que as mudanças tenham efeito.

Com MCP Inspector (desenvolvimento)

npm run dev

Tools

| Tool | Descrição | Status | |------|-----------|--------| | validar_cpf | Valida se um CPF é válido e retorna o motivo da invalidez | ✅ | | gerar_cpf | Gera um CPF válido aleatório (módulo 11) | ✅ | | validar_cnpj | Valida CNPJ (formato numérico e alfanumérico) | ✅ | | gerar_cnpj | Gera um CNPJ válido aleatório (módulo 11) | ✅ | | consultar_cep | Consulta endereço pelo CEP na API ViaCEP | ✅ | | validar_cep | Valida CEP com regex /^\d{5}-?\d{3}$/ | ✅ | | consultar_cotacao | Consulta cotação de moedas (BRL, USD, EUR) via API AwesomeAPI | ✅ | | validar_email | Valida e-mail com regex | ⬜ | | validar_url | Valida URL usando construtor nativo URL | ⬜ | | validar_ipv4 | Valida IPv4 (4 octetos de 0-255) | ⬜ | | validar_ipv6 | Valida IPv6 (8 grupos de 4 hex) | ⬜ | | gerar_lorem | Gera Lorem Ipsum com X palavras | ⬜ | | eh_feriado | Verifica se uma data é feriado nacional | ⬜ | | eh_dia_util | Verifica se uma data é dia útil | ⬜ |

Arquitetura

src/
  index.js              → Entrypoint: cria McpServer, conecta StdioServerTransport
  registerTools.js      → Registra todas as tools no servidor
  handlers/             → Um arquivo por tool handler
    validateCPF.js
    generateCPF.js
    validateCNPJ.js
    generateCNPJ.js
    validateCEP.js
    searchCEP.js
    getCurrencyQuote.js

Design: Tools independentes

Cada tool é autocontida. Os handlers não dependem de outros arquivos do projeto — cada um contém toda a lógica necessária para funcionar. Isso significa que alguns códigos podem estar duplicados entre handlers, e isso é intencional. O objetivo é:

• Zero acoplamento: cada tool pode ser entendida, testada e modificada isoladamente
• Facilidade de contribuição: basta criar um handler novo em src/handlers/ e registrar em registerTools.js

Convenção de idioma

• pt-BR (português brasileiro): tudo que o usuário final vê ou interage — nomes de tools, parâmetros, descrições, mensagens de retorno, propriedades do JSON de resposta.
• Inglês: código interno — variáveis, funções, imports, lógica, nomes de arquivos

Exemplo: a tool se chama validar_cpf, mas a função interna é validateCPF.

Contribuindo

Contribuições são muito bem-vindas! Sinta-se livre para:

• Implementar novas tools da lista de planejadas acima
• Reportar bugs via Issues
• Sugerir novas funcionalidades que não estão na lista
• Melhorar documentação ou testes

Padrões para novas tools

• Handler exporta uma função nomeada (em inglês)
• Input schema usa z.object() do zod
• Handler retorna { content: [{ type: "text", text: JSON.stringify(result) }] }
• Nomes de tools, parâmetros e descrições em pt-BR
• Código interno em inglês
• Cada handler é independente — não importe outros handlers

Stack

• Runtime: Node.js (ESM)
• Execução: tsx
• Schema: zod
• MCP SDK: @modelcontextprotocol/sdk
• Testes: vitest

Licença

MIT