Skip to main content
Glama

mcp-ferramentas-dev

CI

Servidor MCP em TypeScript com ferramentas úteis para quem desenvolve para o Brasil: CPF/CNPJ, Pix (BR Code), boleto, parcelas e faixas salariais.

O que é MCP

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como aplicações de IA conversam com ferramentas e fontes de dados externas. Um servidor MCP expõe ferramentas (funções com entrada e saída tipadas), recursos (dados para leitura) e prompts (modelos de pedido). Um cliente MCP se conecta ao servidor, descobre o que ele oferece e chama as ferramentas quando necessário.

Related MCP server: mcp-latam-validate

Instalação

Requer Node.js 18 ou superior.

git clone https://github.com/Guilherme-Jardim/mcp-ferramentas-dev.git
cd mcp-ferramentas-dev
npm install
npm run build

O servidor usa o transporte stdio: node dist/index.js.

Registrar em um cliente MCP

A maioria dos clientes aceita uma configuração JSON neste formato (o nome do arquivo e do campo raiz variam de cliente para cliente):

{
  "mcpServers": {
    "ferramentas-dev": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-ferramentas-dev/dist/index.js"],
      "env": {
        "MCP_FAIXAS_PATH": "/caminho/opcional/para/minhas-faixas.json"
      }
    }
  }
}

MCP_FAIXAS_PATH é opcional. Sem ele, a ferramenta de salário usa config/faixas-salariais.json.

Ferramentas

Todas validam a entrada com Zod, descrevem o schema de saída e devolvem structuredContent além de um resumo em texto. Erros de execução voltam com isError: true e uma mensagem clara.

validar_documento

Valida CPF (11 dígitos) ou CNPJ (14 dígitos numéricos) e formata.

{ "documento": "52998224725" }
{ "valido": true, "tipo": "cpf", "somenteDigitos": "52998224725", "formatado": "529.982.247-25" }

gerar_pix

Gera o Pix copia e cola estático com CRC16. Campos: chave, nome, cidade, e opcionais valor, txid, descricao.

{ "chave": "12345678909", "nome": "Loja Exemplo", "cidade": "Curitiba", "valor": 49.9, "txid": "PEDIDO1" }
{
  "payload": "00020101021226330014br.gov.bcb.pix011112345678909520400005303986540549.905802BR5912Loja Exemplo6008Curitiba62110507PEDIDO16304C74D",
  "tamanho": 125,
  "crc": "C74D"
}

validar_pix

Confere o CRC16, os campos obrigatórios e extrai chave, nome, cidade, valor e txid.

{ "payload": "0002010102122633...6304C74D" }
{ "valido": true, "erros": [], "crcInformado": "C74D", "crcCalculado": "C74D", "chave": "12345678909", "valor": 49.9, "tipo": "uso_unico" }

O campo tipo reflete o ponto de iniciação do BR Code: reutilizavel (11) ou uso_unico (12, usado quando há valor).

validar_boleto

Confere os dígitos verificadores da linha digitável de 47 dígitos (bancário) ou 48 dígitos (arrecadação).

{ "linhaDigitavel": "23790.00115 ..." }
{ "valido": true, "tipo": "bancario", "erros": [], "banco": "237", "moeda": "9", "fatorVencimento": 9500, "valor": 150, "codigoDeBarras": "..." }

calcular_parcelas

Tabela Price (parcelas fixas, juros compostos). A taxa é em % ao mês.

{ "valor": 10000, "taxaMensal": 1, "parcelas": 12 }
{
  "valorParcela": 888.49,
  "totalPago": 10661.86,
  "totalJuros": 661.86,
  "taxaMensal": 1,
  "tabela": [{ "numero": 1, "parcela": 888.49, "juros": 100, "amortizacao": 788.49, "saldoDevedor": 9211.51 }]
}

(a tabela completa traz as 12 linhas; a última parcela é ajustada para o saldo fechar em zero)

comparar_salario

Diz em qual faixa um salário cai, segundo um JSON configurável. Mínimo é inclusivo, máximo é exclusivo, e só a última faixa pode ter maximo: null.

{ "salario": 7000 }
{
  "salario": 7000,
  "faixa": { "nome": "Pleno", "minimo": 6000, "maximo": 10000 },
  "indice": 2,
  "abaixoDaPrimeira": false,
  "proximaFaixa": { "nome": "Sênior", "minimo": 10000, "maximo": 16000 },
  "faltaParaProxima": 3000,
  "arquivo": ".../config/faixas-salariais.json"
}

Formato do arquivo de faixas:

{
  "faixas": [
    { "nome": "Júnior", "minimo": 3000, "maximo": 6000 },
    { "nome": "Pleno", "minimo": 6000, "maximo": null }
  ]
}

Recurso e prompt

  • Recurso ferramentas://catalogo: JSON com a lista das ferramentas e suas descrições.

  • Prompt conferir_cobranca (argumentos documento e pix): pede ao cliente que confira o CPF/CNPJ e o Pix de uma cobrança usando as ferramentas acima.

Desenvolvimento

npm run lint    # ESLint
npm run build   # compila para dist/
npm test        # compila e roda os testes (unitários + integração por stdio)

A lógica pura fica em src/core (sem dependência do MCP) e o servidor em src/servidor.ts.

Limites

  • A validação de CPF/CNPJ é só matemática (dígitos verificadores). Não consulta a Receita Federal, então não diz se o documento existe ou está regular. CNPJ alfanumérico (novo formato) não é suportado.

  • O Pix gerado é estático, sem consulta ao PSP. Não valida se a chave existe nem cria cobrança dinâmica (campo url). Nome e cidade perdem acentos e são truncados, como pede o BR Code.

  • O boleto é verificado apenas pelos dígitos. Não consulta banco ou câmara, então não informa pagamento, vencimento real ou valor atualizado. O fator de vencimento é devolvido cru: ele reinicia a cada 9000 dias (houve reinício em 22/02/2025), então a data exata fica ambígua sem contexto. A conferência de arrecadação cobre os DVs dos quatro blocos, e não a validação do convênio.

  • Price assume taxa nominal mensal constante, sem IOF, tarifas, seguros, CET nem carência. Arredondamento em centavos, com ajuste na última parcela. Use como estimativa, não como proposta financeira.

  • As faixas salariais são só as que você configurar; o arquivo de exemplo é ilustrativo e não representa nenhuma tabela oficial ou de mercado.

  • Pensado para uso local por stdio. Não há autenticação nem transporte HTTP.

Licença

MIT. Veja LICENSE.

Available Tools

6 tools
calcular_parcelasCalcular parcelas (Price)A

Calcula parcelas fixas pela tabela Price com juros compostos. A taxa é percentual ao mês (ex.: 1.99). Não inclui IOF, tarifas nem seguros.

Inputs: valor (required), parcelas (required), taxaMensal (required). Returns: tabela, totalPago, taxaMensal, totalJuros, +1 more

comparar_salarioComparar salário com faixasA

Diz em qual faixa um salário se encaixa, segundo um arquivo JSON de faixas configurável (variável MCP_FAIXAS_PATH ou parâmetro caminhoConfig).

Inputs: salario (required), caminhoConfig. Returns: faixa, indice, arquivo, salario, +3 more

gerar_pixGerar Pix copia e colaA

Gera o payload Pix estático (BR Code, padrão EMV) com CRC16. Sem valor, o pagador informa o valor. Nome e cidade são normalizados para ASCII e truncados em 25 e 15 caracteres.

Inputs: nome (required), chave (required), cidade (required), txid, +2 more. Returns: crc, payload, tamanho

validar_boletoValidar linha digitável de boletoA

Confere os dígitos verificadores da linha digitável: 47 dígitos (boleto bancário) ou 48 dígitos (arrecadação/convênio). Não consulta o banco, então não diz se o boleto está pago ou vencido.

Inputs: linhaDigitavel (required). Returns: tipo, banco, erros, moeda, +4 more

validar_documentoValidar CPF ou CNPJA

Valida CPF (11 dígitos) ou CNPJ (14 dígitos numéricos) pelos dígitos verificadores e devolve o número formatado. Aceita com ou sem pontuação.

Inputs: documento (required). Returns: tipo, motivo, valido, formatado, +1 more

validar_pixValidar Pix copia e colaA

Confere o CRC16 e os campos obrigatórios de um payload Pix e extrai chave, nome, cidade e valor.

Inputs: payload (required). Returns: nome, tipo, txid, chave, +6 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct artifact: salary bands, CPF/CNPJ, Pix payload generation, Pix validation, boleto validation, and loan installments. The only mild friction is the 'validar_*' trio — an agent handed an arbitrary numeric/EMV string could initially hesitate between validar_documento, validar_boleto and validar_pix — but descriptions make the input shapes clear enough.

    Naming Consistency5/5

    All six names follow the same snake_case verb_noun convention in Portuguese (comparar_, validar_, gerar_, calcular_), with singular nouns. No mixed casing or stylistic outliers.

    Tool Count4/5

    Six tools sit comfortably in the reasonable range and each covers a separate utility. The set is a grab-bag of Brazilian finance helpers rather than a deep domain, so six is defensible but feels slightly thin for the broad 'ferramentas-dev' framing.

    Completeness3/5

    There is a clear asymmetry: Pix has both gerar_pix and validar_pix, but boleto only has validar_boleto with no generation counterpart, and parcelas has no reverse calculation (rate/term inference) or formatting helper for currency. Document validation is also limited to CPF/CNPJ, so agents will hit dead ends for adjacent tasks.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Latin American business compliance suite — 28 tools for tax ID validation (CPF, CNPJ, RFC, RUT, CUIT, NIT), banking (PIX, CLABE, CBU), VAT rules, e-invoicing (NF-e, CFDI, DTE), holidays, and labor calendar across Brazil, Mexico, Chile, Argentina, and Colombia.
      28
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Validates LatAm banking and tax IDs (Mexican CLABE, Brazilian CNPJ/CPF checksums) and performs BrasilAPI company, CEP, and bank lookups, enabling AI agents to verify financial and tax information in Latin America.
      72 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Exposes Brazilian public data — postal codes (CEP), company registrations (CNPJ), CPF/CNPJ validation, banks, national holidays, municipalities, and DDD area codes — as MCP tools and resources, backed by BrasilAPI, ViaCEP, and IBGE with caching, fallback, and rate limiting. Any MCP client such as Claude Desktop or Claude Code can query and validate this reference and registration data through natural language or programmatic calls.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and business systems to query and validate Brazilian fiscal data and documents, including CNPJ/CPF, Simples Nacional/MEI, NF-e/NFS-e, SPED, eSocial, and supplier compliance, without mandatory API keys. It also supports offline reference tables, tax-regime comparison, due-diligence scoring, and 2026 IBS/CBS reform analysis through composable tools.
      MIT