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.

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.

Endpoint	Entrada	Saída
/api/generators/cpf	formatted, state, seed	cpf, formatted, valid
/api/validators/cpf	value	cpf, formatted, valid, message
/api/generators/cnpj	formatted, format, seed	cnpj, formatted, format, valid
/api/validators/cnpj	value	cnpj, formatted, format, valid, message
/api/generators/cnh	seed	cnh, valid
/api/validators/cnh	value	cnh, valid, message
/api/generators/rg	formatted, seed	rg, formatted, valid
/api/validators/rg	value	rg, formatted, valid, message
/api/generators/pis-pasep	formatted, seed	pisPasep, formatted, valid
/api/validators/pis-pasep	value	pisPasep, formatted, valid, message
/api/generators/renavam	seed	renavam, valid
/api/validators/renavam	value	renavam, valid, message
/api/encoders/base64/encode	text	encoded
/api/encoders/base64/decode	base64	decoded
/api/encoders/md5	text	md5
/api/encoders/sha1	text	sha1
/api/encoders/url/encode	text	encoded
/api/encoders/url/decode	url	decoded
/api/text/remove-accents	text	text
/api/text/reverse	text	text
/api/text/analyze	text	characters, charactersWithoutSpaces, words, spaces, lines, vowels, consonants

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.