Skip to main content
Glama
br-docs-mcp

br-docs-mcp

br-docs-mcp

Servidor MCP (Model Context Protocol) para validação e geração de documentos brasileiros: CPF, CNPJ e boleto bancário.

O que é

Uma implementação de servidor MCP que expõe 6 ferramentas para validar e gerar documentos brasileiros. Implementa os algoritmos de validação (módulo 11 para CPF e CNPJ, módulo 10 e 11 para boleto) e permite que clientes MCP (Claude, Cursor, etc.) utilizem essas funcionalidades via chamadas de ferramentas.

Related MCP server: mcp-server-brasil

Funcionalidades e Tecnologias

Funcionalidade

Descrição

Tecnologia

Validação de CPF

Valida CPF com algoritmo mod11, aceita formatado e bruto

TypeScript

Geração de CPF

Gera CPF válido e aleatório

Pure logic

Validação de CNPJ

Valida CNPJ com pesos mod11 específicos

TypeScript

Geração de CNPJ

Gera CNPJ válido e aleatório

Pure logic

Validação de Boleto

Valida linha digitável (47 dígitos, layout FEBRABAN): mod10 nos 3 campos + DV geral mod11 na posição 33

TypeScript

Parse de Boleto

Extrai banco, valor e vencimento via fator de vencimento (com rollover de 22/02/2025)

Pure logic

MCP Tools

Expõe 6 ferramentas via Model Context Protocol

@modelcontextprotocol/sdk

MCP Resource

docs://validation-rules com a documentação dos algoritmos

Markdown

MCP Prompt

audit_customer_record para auditar cadastros usando as tools

Template

Testes

40 testes, incluindo E2E MCP real (Client ↔ Server via InMemoryTransport)

Vitest

Clean Architecture

Lógica pura separada da camada MCP

src/domain

Arquitetura

graph TB
    subgraph Client["Cliente MCP (Claude, Cursor)"]
        A["Chamada de Tool<br/>ou Leitura de Resource"]
    end
    
    subgraph Transport["Transporte"]
        B["Stdio Transport<br/>JSON-RPC 2.0"]
    end
    
    subgraph Server["br-docs-mcp Server"]
        C1["Tool: validate_cpf"]
        C2["Tool: generate_cpf"]
        C3["Tool: validate_cnpj"]
        C4["Tool: generate_cnpj"]
        C5["Tool: validate_boleto"]
        C6["Tool: parse_boleto"]
        C7["Resource: docs://validation-rules"]
        C8["Prompt: audit_customer_record"]
    end
    
    subgraph Domain["Lógica Pura"]
        D1["src/domain/cpf.ts"]
        D2["src/domain/cnpj.ts"]
        D3["src/domain/boleto.ts"]
    end
    
    A --> B --> C1
    C1 --> D1
    C2 --> D1
    C3 --> D2
    C4 --> D2
    C5 --> D3
    C6 --> D3
    
    style Domain fill:#e1f5ff
    style Server fill:#f3e5f5
    style Transport fill:#fff3e0

Como rodar

Pré-requisitos

  • Node.js >= 22.12

Instalação

npm install

Desenvolvimento

npm run dev

Build

npm run build

Saída em dist/index.js com shebang, pronto para uso via npx br-docs-mcp.

Como testar

Rodar testes

npm test

Modo watch

npm run test:watch

Type check

npm run type-check

Todos os 40 testes rodam 100% offline e cobrem:

  • Validação de CPF/CNPJ formatado e bruto

  • Rejeição de dígito verificador errado, comprimento inválido, dígitos repetidos

  • Roundtrip gerar → validar (20 iterações para CPF e CNPJ)

  • Boleto: linha válida construída nos testes (com mod10/mod11 independentes), campos corrompidos, DV geral errado

  • Parse de boleto: banco, valor e vencimento — incluindo o rollover do fator (1000 = 22/02/2025) e fator 0000 (sem vencimento)

  • E2E MCP real: Client e McpServer conectados por InMemoryTransport.createLinkedPair(), listando as 6 tools, chamando validate_cpf, lendo o resource e obtendo o prompt

Uso com clientes MCP

Configuração no Claude Desktop / Cursor

Adicione a entrada no mcp.json:

{
  "mcpServers": {
    "br-docs-mcp": {
      "command": "npx",
      "args": ["br-docs-mcp"]
    }
  }
}

Exemplo de chamada

{
  "name": "validate_cpf",
  "arguments": {
    "cpf": "529.982.247-25"
  }
}

Resposta:

{
  "valid": true
}

Ferramentas disponíveis

  • validate_cpf - Valida CPF → { "valid": true } ou { "valid": false, "reason": "check digit mismatch" }

  • generate_cpf - Gera CPF válido → { "cpf": "..." }

  • validate_cnpj - Valida CNPJ

  • generate_cnpj - Gera CNPJ válido

  • validate_boleto - Valida linha digitável de boleto

  • parse_boleto - Extrai dados do boleto → { "bankCode": "001", "amount": 1500, "dueDate": "2025-02-22" }

Resource disponível

  • docs://validation-rules - Documentação dos algoritmos

Prompt disponível

  • audit_customer_record - Audita registros de clientes usando as tools

Estrutura do projeto

.
├── src/
│   ├── domain/
│   │   ├── cpf.ts          # Lógica pura de CPF
│   │   ├── cnpj.ts         # Lógica pura de CNPJ
│   │   └── boleto.ts       # Lógica pura de boleto (layout FEBRABAN)
│   ├── server.ts           # Servidor MCP (tools, resource, prompt)
│   ├── validation-rules.ts # Markdown servido pelo resource
│   └── index.ts            # Entrypoint stdio (#!/usr/bin/env node)
├── tests/
│   ├── domain/
│   │   ├── cpf.test.ts
│   │   ├── cnpj.test.ts
│   │   └── boleto.test.ts
│   └── e2e/
│       └── server.test.ts
├── package.json            # bin: br-docs-mcp → dist/index.js
├── tsconfig.json
├── vitest.config.ts
├── README.md               # Este arquivo
├── LICENSE                 # MIT
└── .gitignore

Publicação no npm

Build e teste

npm run type-check
npm test
npm run build

Publicar

npm publish

O script prepublishOnly garante que testes e build passam antes de publicar.

Origem

Inspirado em conceitos do curso de pós-graduação em Engenharia de Software com IA Aplicada — implementação própria do zero, usando TypeScript e clean architecture para demonstrar:

  • Design domain-driven

  • Separação de responsabilidades (domain vs. transport)

  • Algoritmos de validação (mod11, mod10)

  • Model Context Protocol (MCP)

  • Test-driven development com Vitest

  • Empacotamento npm com tipos

Licença

MIT - Copyright (c) 2026 Vicente Moura

Available Tools

6 tools
generate_cnpjA

Gera um CNPJ válido aleatório. Use formatted=true para "XX.XXX.XXX/XXXX-XX".

Inputs: formatted.

generate_cpfA

Gera um CPF válido aleatório. Use formatted=true para "XXX.XXX.XXX-XX".

Inputs: formatted.

parse_boletoA

Extrai código do banco, valor (R$) e data de vencimento da linha digitável de um boleto. Falha com mensagem clara se a linha for inválida.

Inputs: linha_digitavel (required).

validate_boletoA

Valida a linha digitável de um boleto bancário (47 dígitos, aceita pontuação). Confere o mod 10 dos 3 campos e o DV geral mod 11. Retorna { valid } e { reason } quando inválido.

Inputs: linha_digitavel (required).

validate_cnpjA

Valida um CNPJ brasileiro (aceita formatado "11.222.333/0001-81" ou cru). Retorna { valid } e, quando inválido, { reason }.

Inputs: cnpj (required).

validate_cpfA

Valida um CPF brasileiro (aceita formatado "529.982.247-25" ou cru "52998224725"). Retorna { valid } e, quando inválido, { reason }.

Inputs: cpf (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct document type and action. CPF, CNPJ, and boleto are clearly different domains, and validate vs. generate vs. parse have well-defined boundaries. Even the two boleto tools are unambiguous: one checks validity, the other extracts data.

    Naming Consistency5/5

    All tool names follow a strict verb_noun pattern in lowercase snake_case: validate_cpf, generate_cpf, validate_cnpj, generate_cnpj, validate_boleto, parse_boleto. The verb (validate/generate/parse) and noun (cpf/cnpj/boleto) are consistent and predictable.

    Tool Count5/5

    Six tools is well within the ideal 3-15 range and each tool provides a distinct function for Brazilian documents. The count feels neither sparse nor bloated, covering validation, generation, and parsing for three common document types.

    Completeness5/5

    The surface covers the core lifecycle for each document type: CPF and CNPJ have both generation and validation (with formatted output options), and boleto has validation and parsing. There are no obvious dead ends or missing operations for the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server with tools for Brazilian data like CPF, CNPJ, CEP validation and generation, and currency quotes.
      7
      50 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server for generating and validating Brazilian documents (CPF, CNPJ, CNH, RG, PIS/PASEP, RENAVAM), encoding/decoding data (Base64, MD5, SHA1, URL), and performing text utilities like removing accents, reversing, and analyzing text.
      -