io.github.dan94k/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