4devs-mcp-server by edum-compassuol - MCP Server

4Devs MCP Server

Um servidor MCP (Model Context Protocol) que integra com a API 4Devs para geração de documentos e dados brasileiros válidos para testes e desenvolvimento.

📋 Visão Geral

O 4Devs MCP Server fornece acesso programático à API 4Devs através do protocolo MCP, permitindo que assistentes de IA e outras ferramentas gerem dados brasileiros realistas incluindo:

Dados Pessoais Completos: Nome, idade, documentos, endereço, contatos
Documentos Brasileiros Válidos: CPF, RG, CNH, PIS, Certidões, Título de Eleitor
Dados Geográficos: Estados e cidades brasileiras com códigos válidos
Geração em Lote: Até 30 registros por requisição
Customização Avançada: Controle de gênero, idade, localização e formatação

🚀 Instalação Rápida via Packages Remotos

Você pode usar o 4Devs MCP Server diretamente no Claude Desktop sem precisar clonar o repositório, usando packages remotos via npx (GitHub Packages) ou Docker (GitHub Container Registry).

Método 1: NPX via GitHub Packages

Adicione ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "4devs": {
      "command": "npx",
      "args": ["-y", "@edum-compassuol/4devs-mcp-server"]
    }
  }
}

Nota: Este package está publicado no GitHub Package Registry. Se for um package privado, você precisará configurar autenticação npm com seu token do GitHub.

Configurar Autenticação (se necessário)

Se o package for privado, crie/edite o arquivo ~/.npmrc:

//npm.pkg.github.com/:_authToken=SEU_GITHUB_TOKEN
@edum-compassuol:registry=https://npm.pkg.github.com

Método 2: Docker via GitHub Container Registry (GHCR)

{
  "mcpServers": {
    "4devs": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/edum-compassuol/4devs-mcp-server:latest"]
    }
  }
}

Nota: Se a imagem Docker for privada, você precisará fazer login no GHCR primeiro:
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Verificação da Instalação

Após adicionar a configuração:

Reinicie o Claude Desktop
Verifique se o servidor "4devs" aparece na lista de MCP servers
Teste uma ferramenta simples como gerar_cnh para confirmar que está funcionando

✨ Ferramentas Disponíveis

1. 🧑 gerar_pessoa

Gera dados completos de pessoas brasileiras com documentos válidos.

Características:

Geração de 1 a 30 pessoas por requisição
Documentos com formatação customizável (com/sem pontuação)
Filtros por gênero, idade e localização
Dados completos: nome, CPF, RG, endereço, contatos, características físicas

Casos de Uso:

Testes de sistemas de cadastro
População de bancos de dados de desenvolvimento
Validação de formulários
Demonstrações de produtos

2. 🏙️ carregar_cidades

Lista todas as cidades de um estado brasileiro com seus códigos.

Características:

Retorna código e nome de cada cidade
Suporta todos os 27 estados brasileiros
Dados atualizados e validados

Casos de Uso:

Preenchimento de dropdowns de cidades
Validação de endereços
Integração com sistemas de logística

3. 📜 gerador_certidao

Gera números válidos de certidões brasileiras.

Tipos Suportados:

Certidão de Nascimento
Certidão de Casamento
Certidão de Casamento Religioso
Certidão de Óbito

Casos de Uso:

Testes de sistemas cartoriais
Validação de documentos
Simulação de processos legais

4. 🚗 gerar_cnh

Gera números válidos de CNH (Carteira Nacional de Habilitação).

Características:

Números com dígitos verificadores corretos
Formato padrão brasileiro

Casos de Uso:

Testes de sistemas de trânsito
Validação de habilitação
Sistemas de locação de veículos

5. 💼 gerar_pis

Gera números válidos de PIS/PASEP/NIS.

Características:

Números com dígitos verificadores corretos
Formatação customizável (com/sem pontuação)

Casos de Uso:

Testes de sistemas de RH
Validação de folha de pagamento
Sistemas previdenciários

6. 🗳️ gerar_titulo_eleitor

Gera números válidos de Título de Eleitor.

Características:

Números específicos por estado ou aleatórios
Formato padrão da Justiça Eleitoral

Casos de Uso:

Testes de sistemas eleitorais
Validação de cadastro eleitoral
Sistemas de identificação civil

🚀 Instalação

Método 1: NPM Package (Recomendado para Desenvolvimento)

Pré-requisitos

Node.js 18 ou superior
npm ou yarn

Passos de Instalação

# Clone o repositório
git clone https://github.com/seu-usuario/4devs-mcp-server.git
cd 4devs-mcp-server

# Instale as dependências
npm install

# Compile o projeto
npm run build

Configuração no Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "4devs": {
      "command": "node",
      "args": ["/caminho/completo/para/4devs-mcp-server/build/index.js"]
    }
  }
}

Método 2: Docker (Recomendado para Produção)

Pré-requisitos

Docker 20.10 ou superior
Docker Compose (opcional)

Build da Imagem Docker

# Clone o repositório
git clone https://github.com/seu-usuario/4devs-mcp-server.git
cd 4devs-mcp-server

# Build da imagem
docker build -t 4devs-mcp-server .

Executar com Docker

# Executar o container
docker run -i --rm 4devs-mcp-server

Configuração no Claude Desktop (Docker)

{
  "mcpServers": {
    "4devs": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "4devs-mcp-server"]
    }
  }
}

Docker Compose (Opcional)

Crie um arquivo docker-compose.yml:

version: '3.8'

services:
  4devs-mcp-server:
    build: .
    image: 4devs-mcp-server
    stdin_open: true
    tty: true

Execute com:

docker-compose up

Método 3: NPX (Execução Direta)

# Executar diretamente sem instalação
npx 4devs-mcp-server

Configuração no Claude Desktop (NPX):

{
  "mcpServers": {
    "4devs": {
      "command": "npx",
      "args": ["4devs-mcp-server"]
    }
  }
}

⚙️ Configuração Avançada

Variáveis de Ambiente

O servidor suporta as seguintes variáveis de ambiente:

# Nível de log (opcional)
LOG_LEVEL=info  # debug, info, warn, error

# Timeout de requisições (opcional, em ms)
REQUEST_TIMEOUT=30000

Configuração com Variáveis de Ambiente

NPM/Node.js:

{
  "mcpServers": {
    "4devs": {
      "command": "node",
      "args": ["/caminho/para/build/index.js"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Docker:

{
  "mcpServers": {
    "4devs": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "LOG_LEVEL=debug", "4devs-mcp-server"]
    }
  }
}

📖 Guia de Uso Detalhado

1. Gerar Pessoa

Gera dados completos de uma ou mais pessoas brasileiras.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Valores	Descrição
`sexo`	string	Sim	"H", "M", "I"	H=Homem, M=Mulher, I=Indiferente
`txt_qtde`	number	Sim	1-30	Quantidade de pessoas
`pontuacao`	string	Não	"S", "N"	Incluir pontuação nos documentos
`idade`	number	Não	0-120	Idade específica (0=aleatória)
`cep_estado`	string	Não	UF	Sigla do estado (ex: "SP")
`cep_cidade`	number	Não	código	Código da cidade (via carregar_cidades)

Exemplo Básico:

{
  "name": "gerar_pessoa",
  "arguments": {
    "sexo": "I",
    "txt_qtde": 1
  }
}

Exemplo Avançado (Pessoa de Florianópolis, SC, 25 anos):

{
  "name": "gerar_pessoa",
  "arguments": {
    "sexo": "M",
    "txt_qtde": 1,
    "pontuacao": "S",
    "idade": 25,
    "cep_estado": "SC",
    "cep_cidade": 8349
  }
}

Resposta:

[
  {
    "nome": "Maria Silva Santos",
    "idade": 25,
    "cpf": "123.456.789-00",
    "rg": "12.345.678-9",
    "data_nasc": "15/03/1999",
    "sexo": "Feminino",
    "signo": "Peixes",
    "mae": "Ana Silva",
    "pai": "José Santos",
    "email": "maria.silva@example.com",
    "senha": "abc123XYZ",
    "cep": "88000-000",
    "endereco": "Rua das Flores 123",
    "numero": 456,
    "bairro": "Centro",
    "cidade": "Florianópolis",
    "estado": "SC",
    "telefone_fixo": "(48) 3234-5678",
    "celular": "(48) 98765-4321",
    "altura": "1,65",
    "peso": 60,
    "tipo_sanguineo": "A+",
    "cor": "azul"
  }
]

2. Carregar Cidades

Lista todas as cidades de um estado brasileiro.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Valores	Descrição
`cep_estado`	string	Sim	UF	Sigla do estado

Estados Suportados: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MS, MT, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO

Exemplo:

{
  "name": "carregar_cidades",
  "arguments": {
    "cep_estado": "SC"
  }
}

Resposta:

{
  "estado": "SC",
  "total_cidades": 295,
  "cidades": [
    {
      "code": 8319,
      "name": "Abdon Batista"
    },
    {
      "code": 8349,
      "name": "Florianópolis"
    },
    {
      "code": 8542,
      "name": "São José"
    }
  ]
}

3. Gerador de Certidão

Gera números de certidões brasileiras.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Valores	Descrição
`pontuacao`	string	Não	"S", "N"	Incluir pontuação
`tipo_certidao`	string	Não	Ver abaixo	Tipo da certidão

Tipos de Certidão:

nascimento - Certidão de Nascimento
casamento - Certidão de Casamento
casamento_religioso - Certidão de Casamento Religioso
obito - Certidão de Óbito
Indiferente - Tipo aleatório (padrão)

Exemplo:

{
  "name": "gerador_certidao",
  "arguments": {
    "tipo_certidao": "nascimento",
    "pontuacao": "S"
  }
}

Resposta:

{
  "tipo_certidao": "nascimento",
  "numero": "123456 01 55 2020 1 12345 678 1234567-89"
}

4. Gerar CNH

Gera números de CNH (Carteira Nacional de Habilitação).

Parâmetros: Nenhum

Exemplo:

{
  "name": "gerar_cnh",
  "arguments": {}
}

Resposta:

{
  "cnh": "12345678901"
}

5. Gerar PIS

Gera números de PIS (Programa de Integração Social).

Parâmetros:

Parâmetro	Tipo	Obrigatório	Valores	Descrição
`pontuacao`	string	Não	"S", "N"	Incluir pontuação

Exemplo:

{
  "name": "gerar_pis",
  "arguments": {
    "pontuacao": "S"
  }
}

Resposta:

{
  "pis": "123.45678.90-1"
}

6. Gerar Título de Eleitor

Gera números de Título de Eleitor.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Valores	Descrição
`estado`	string	Não	UF	Sigla do estado

Exemplo:

{
  "name": "gerar_titulo_eleitor",
  "arguments": {
    "estado": "SP"
  }
}

Resposta:

{
  "estado": "SP",
  "titulo_eleitor": "123456789012"
}

🎯 Exemplos de Uso Prático

Exemplo 1: Gerar 5 Pessoas de Florianópolis

// 1. Primeiro, obter o código de Florianópolis
{
  "name": "carregar_cidades",
  "arguments": {
    "cep_estado": "SC"
  }
}
// Resultado: Florianópolis tem código 8349

// 2. Gerar 5 pessoas de Florianópolis com idade entre 20-30
{
  "name": "gerar_pessoa",
  "arguments": {
    "sexo": "I",
    "txt_qtde": 5,
    "pontuacao": "S",
    "idade": 25,
    "cep_estado": "SC",
    "cep_cidade": 8349
  }
}

Exemplo 2: Gerar Documentos Completos para uma Pessoa

// 1. Gerar dados da pessoa
{
  "name": "gerar_pessoa",
  "arguments": {
    "sexo": "M",
    "txt_qtde": 1,
    "pontuacao": "S"
  }
}

// 2. Gerar CNH
{
  "name": "gerar_cnh",
  "arguments": {}
}

// 3. Gerar Certidão de Nascimento
{
  "name": "gerador_certidao",
  "arguments": {
    "tipo_certidao": "nascimento",
    "pontuacao": "S"
  }
}

// 4. Gerar PIS
{
  "name": "gerar_pis",
  "arguments": {
    "pontuacao": "S"
  }
}

// 5. Gerar Título de Eleitor
{
  "name": "gerar_titulo_eleitor",
  "arguments": {
    "estado": "SP"
  }
}

Exemplo 3: Popular Banco de Dados de Teste

// Gerar 30 pessoas (máximo por requisição)
{
  "name": "gerar_pessoa",
  "arguments": {
    "sexo": "I",
    "txt_qtde": 30,
    "pontuacao": "N"
  }
}

🧪 Testes

Testar Localmente

# Compilar o projeto
npm run build

# Executar script de teste customizado
node test-tools.js

Testar com MCP Inspector

O MCP Inspector é uma ferramenta oficial para testar servidores MCP interativamente.

# Instalar e executar o Inspector
npm run inspector

O Inspector abrirá uma interface web em http://localhost:6274 onde você pode:

Listar todas as ferramentas disponíveis
Testar cada ferramenta com parâmetros customizados
Ver respostas em tempo real
Debugar problemas de integração

Testar com Docker

# Build da imagem
docker build -t 4devs-mcp-server .

# Testar a imagem
docker run -i --rm 4devs-mcp-server

🏗️ Estrutura do Projeto

4devs-mcp-server/
├── src/
│   ├── api/
│   │   ├── client.ts              # Cliente HTTP para API 4Devs
│   │   └── types.ts               # Tipos TypeScript
│   ├── resources/
│   │   └── readme-resource.ts     # Resource MCP com documentação
│   ├── schemas/
│   │   └── tool-schemas.ts        # Schemas Zod para validação
│   ├── tools/
│   │   ├── gerar-pessoa.ts        # Tool: Gerar Pessoa
│   │   ├── carregar-cidades.ts    # Tool: Carregar Cidades
│   │   ├── gerador-certidao.ts    # Tool: Gerador Certidão
│   │   ├── gerar-cnh.ts           # Tool: Gerar CNH
│   │   ├── gerar-pis.ts           # Tool: Gerar PIS
│   │   └── gerar-titulo-eleitor.ts # Tool: Gerar Título Eleitor
│   ├── server.ts                  # Implementação do servidor MCP
│   └── index.ts                   # Ponto de entrada
├── build/                         # Código compilado (gerado)
├── node_modules/                  # Dependências (gerado)
├── test-tools.js                  # Script de testes
├── Dockerfile                     # Configuração Docker
├── .dockerignore                  # Arquivos ignorados no Docker
├── package.json                   # Configuração npm
├── tsconfig.json                  # Configuração TypeScript
└── README.md                      # Esta documentação

🔧 Desenvolvimento

Scripts Disponíveis

# Compilar o projeto
npm run build

# Iniciar o servidor (após compilar)
npm start

# Modo desenvolvimento com watch
npm run dev

# Abrir MCP Inspector
npm run inspector

# Limpar arquivos compilados
npm run clean

Adicionar Nova Ferramenta

Criar arquivo da ferramenta em src/tools/:

import { FourDevsClient } from '../api/client.js';
import { z } from 'zod';

export const minhaNovaFerramenta = {
  name: 'minha_nova_ferramenta',
  description: 'Descrição da ferramenta',
  inputSchema: {
    type: 'object',
    properties: {
      parametro: {
        type: 'string',
        description: 'Descrição do parâmetro'
      }
    },
    required: ['parametro']
  },
  
  async execute(client: FourDevsClient, args: any) {
    // Implementação
    const result = await client.request({
      acao: 'minha_acao',
      ...args
    });
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  }
};

Adicionar schema Zod em src/schemas/tool-schemas.ts:

export const minhaNovaFerramentaSchema = z.object({
  parametro: z.string()
});

Registrar no servidor em src/server.ts:

import { minhaNovaFerramenta } from './tools/minha-nova-ferramenta.js';

// No método setupHandlers(), adicionar:
case minhaNovaFerramenta.name:
  return await minhaNovaFerramenta.execute(this.client, request.params.arguments);

Contribuir com o Projeto

Fork o repositório
Crie uma branch para sua feature (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'Adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

📚 Referências

Model Context Protocol
4Devs API
MCP TypeScript SDK
GitHub MCP Server - Referência de implementação

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

Faça um fork do projeto
Crie uma branch para sua feature (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'Adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

⚠️ Avisos

Este servidor é destinado apenas para fins de teste e desenvolvimento
Os dados gerados são fictícios mas seguem formatos válidos brasileiros
Não use dados gerados para fins fraudulentos ou ilegais
A API 4Devs é um serviço de terceiros e pode ter limitações de uso

🐛 Problemas Conhecidos

A API 4Devs pode retornar tipos de resposta variados (string ou objeto) para alguns endpoints
Certifique-se de usar responseType: 'text' para endpoints de documentos para evitar conversão para notação científica

📞 Suporte

Para problemas ou dúvidas:

Abra uma issue no GitHub
Consulte a documentação do MCP
Verifique a documentação da API 4Devs

🎉 Agradecimentos

4Devs pela API pública de geração de dados brasileiros
Anthropic pelo Model Context Protocol
Comunidade open source por ferramentas e bibliotecas utilizadas