DevTools BR

API REST e servidor MCP com geradores, validadores, encoders e utilitários de texto inspirados no 4Devs.

O código de produção não chama o 4Devs. O projeto implementa os algoritmos localmente e usa o 4Devs apenas em testes de compatibilidade via browser, quando o oracle é ativado de forma explícita.

O que o projeto entrega

• Geração e validação de documentos brasileiros: CPF, CNPJ, CNH, RG, PIS/PASEP e RENAVAM.

• Encoders e decoders: Base64, MD5, SHA1 e URL encode/decode.

• Ferramentas de texto: remover acentos, inverter texto e analisar contagens.

• API REST v1 para uso por aplicações HTTP.

• Servidor MCP v1 para uso por clientes compatíveis com Model Context Protocol.

• Testes locais determinísticos e testes oracle opcionais contra o 4Devs via Playwright.

Related MCP server: mcp-nfe-br

Requisitos

• Node.js 20 ou superior.

• npm.

• Docker e Docker Compose, se quiser rodar em containers.

Instalação

npm install

REST

Inicie a API REST em desenvolvimento:

npm run dev:rest

Por padrão, a API escuta em http://127.0.0.1:3000.

Exemplo:

curl -s http://127.0.0.1:3000/api/generators/cpf \
  -H 'content-type: application/json' \
  -d '{"formatted":true,"state":"SP","seed":"demo"}'

Resposta:

{
  "cpf": "12345678909",
  "formatted": "123.456.789-09",
  "valid": true
}

seed torna a geração determinística. Use esse campo em testes para obter sempre o mesmo resultado.

Endpoints REST

Todos os endpoints usam POST e recebem JSON.

No v1, format: "alphanumeric" para CNPJ é rejeitado. A implementação atual gera CNPJ numérico.

Erros REST

Erros retornam um envelope estável:

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid request",
    "field": "state"
  }
}

Códigos comuns:

• invalid_parameter: payload inválido ou parâmetro fora do domínio aceito.

• invalid_input: entrada malformada, como Base64 inválido.

• internal_error: falha inesperada.

MCP

O projeto expõe as mesmas operações via MCP.

Para rodar via stdio:

npm run dev:mcp:stdio

Para rodar via Streamable HTTP:

npm run dev:mcp:http

Por padrão, o endpoint HTTP escuta em:

http://127.0.0.1:3001/mcp

Ferramentas MCP disponíveis:

• generate_cpf, validate_cpf

• generate_cnpj, validate_cnpj

• generate_cnh, validate_cnh

• generate_rg, validate_rg

• generate_pis_pasep, validate_pis_pasep

• generate_renavam, validate_renavam

• encode_base64, decode_base64

• encode_md5, encode_sha1

• encode_url, decode_url

• remove_text_accents, reverse_text, analyze_text

Recursos MCP disponíveis:

• devs-clone://catalog/tools

• devs-clone://schemas/rest-v1

• devs-clone://schemas/mcp-v1

• devs-clone://reference/states

• devs-clone://reference/algorithms

Docker

Suba a API REST e o MCP HTTP com Docker Compose:

docker compose up --build

O Compose publica:

• REST: http://127.0.0.1:3000

• MCP HTTP: http://127.0.0.1:3001/mcp

Serviços:

• rest: executa npm run start:rest.

• mcp-http: executa npm run start:mcp:http.

Build de produção

Compile o TypeScript:

npm run build

Depois rode os entrypoints compilados:

npm run start:rest
npm run start:mcp:http

Variáveis úteis:

• HOST: host da API REST. Padrão: 127.0.0.1.

• PORT: porta da API REST. Padrão: 3000.

• MCP_HTTP_HOST: host do MCP HTTP. Padrão: HOST ou 127.0.0.1.

• MCP_HTTP_PORT: porta do MCP HTTP. Padrão: 3001.

Testes

Rode a suíte local:

npm run typecheck
npm run test

Rode grupos específicos:

npm run test:unit
npm run test:rest
npm run test:mcp

Os testes oracle via browser ficam desativados por padrão:

npm run test:oracle

Para comparar fluxos reais com o 4Devs, ative o oracle:

RUN_4DEVS_ORACLE=1 npm run test:oracle

Esses testes dependem da rede e da interface atual do 4Devs. Use-os como referência de compatibilidade, não como dependência de produção.

Estrutura

src/domain      Algoritmos e regras de domínio
src/schemas     Schemas de entrada e saída
src/services    Casos de uso v1
src/rest        Servidor REST
src/mcp         Servidor MCP
tests/domain    Testes unitários de domínio
tests/rest      Testes da API REST
tests/mcp       Testes do MCP
tests/oracle    Testes opcionais contra o 4Devs via browser

Escopo atual

O v1 cobre uma parte selecionada do 4Devs: documentos brasileiros, encoders e ferramentas de texto. O objetivo é expandir esse contrato aos poucos, mantendo entradas, saídas e testes claros antes de adicionar novas ferramentas.