Construindo um Servidor MCP de Dados de Teste Brasileiros

O Model Context Protocol (MCP) é uma especificação aberta criada pela Anthropic que padroniza a forma como modelos de Inteligência Artificial interagem com fontes de dados e ferramentas locais ou em nuvem. Em vez de escrever integrações proprietárias para cada IDE ou cliente de chat, você constrói um servidor MCP que expõe capacidades que qualquer LLM compatível pode consumir nativamente.

Para desenvolvedores brasileiros que utilizam assistentes de IA (como Claude Desktop, Cursor ou windsurf) no dia a dia, ter um servidor MCP que gera dados de teste locais e válidos (como CPF, CNPJ e CEP) é um enorme ganho de produtividade.

Neste tutorial passo a passo, vamos construir um servidor MCP em TypeScript/Node.js para gerar massas de dados de teste brasileiras.

Arquitetura do Model Context Protocol

A arquitetura do MCP é baseada em uma relação cliente-servidor muito simples:

• MCP Client: O aplicativo que hospeda a IA (ex: Claude Desktop, sua IDE ou seu agente customizado). Ele controla o ciclo de vida do servidor.
• MCP Server: Um processo leve executado localmente ou exposto via rede que responde a requisições de descoberta e execução de ferramentas através de canais como Entrada/Saída Padrão (stdio) ou Server-Sent Events (SSE).

No nosso tutorial, usaremos a comunicação via stdio, que é a mais simples e recomendada para ferramentas locais.

Passo 1: Setup do Projeto TypeScript

Primeiro, vamos inicializar um novo projeto Node.js e instalar as dependências necessárias, incluindo a SDK oficial do MCP:

# Cria a pasta do projeto
mkdir mcp-brasil-generator
cd mcp-brasil-generator

# Inicializa o npm e instala as dependências
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node tsx
npx tsc --init

Passo 2: Criando os Geradores de Dados

Crie um arquivo chamado generators.ts para conter as funções puras de geração de documentos e dados válidos para testes:

// generators.ts
export function gerarCPF() {
  const numAleatorio = () => Math.floor(Math.random() * 9);
  const d = Array.from({ length: 9 }, numAleatorio);
  
  let d1 = d.reduce((s, v, i) => s + v * (10 - i), 0);
  d1 = 11 - (d1 % 11);
  if (d1 >= 10) d1 = 0;
  
  d.push(d1);
  let d2 = d.reduce((s, v, i) => s + v * (11 - i), 0);
  d2 = 11 - (d2 % 11);
  if (d2 >= 10) d2 = 0;
  
  d.push(d2);
  return d.join('').replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4");
}

Passo 3: Construindo o Servidor MCP

Agora, vamos estruturar o servidor MCP no arquivo index.ts. Usaremos o Server da SDK oficial e declararemos nossa ferramenta de geração para a IA:

// index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { gerarCPF } from "./generators.js";

// Instancia o servidor MCP
const server = new Server(
  {
    name: "mcp-brasil-generator",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 1. Declara as ferramentas disponíveis para o cliente
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "gerar_cpf",
        description: "Gera um número de CPF brasileiro fictício matematicamente válido para uso em testes.",
        inputSchema: {
          type: "object",
          properties: {},
        },
      },
    ],
  };
});

// 2. Trata a execução das ferramentas chamadas pela IA
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name } = request.params;

  if (name === "gerar_cpf") {
    const cpf = gerarCPF();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ cpf }),
        },
      ],
    };
  }

  throw new Error(`Ferramenta não encontrada: ${name}`);
});

// Inicializa o servidor usando comunicação via stdio
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Servidor MCP Brasil rodando em stdio!");
}

main().catch((error) => {
  console.error("Erro ao rodar servidor MCP:", error);
  process.exit(1);
});

Passo 4: Configurando no Claude Desktop

Para expor essa ferramenta localmente para o app oficial do Claude Desktop, você precisa adicionar a configuração do servidor ao seu arquivo claude_desktop_config.json:

No Windows, esse arquivo fica em: %APPDATA%/Claude/claude_desktop_config.json
No macOS, em: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-brasil-generator": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "C:/caminho/para/seu/projeto/index.ts"
      ]
    }
  }
}

Ao reiniciar o Claude Desktop, você verá o ícone de tomada indicando que o servidor foi conectado. A partir desse momento, a IA poderá criar e preencher dados brasileiros de teste sob demanda em seus prompts de codificação.

Com essa mesma estrutura de código, você pode expandir o servidor MCP para gerar CNPJ, gerar endereços simulados ou até consultar chaves da Tabela FIPE.

Se você precisa de uma interface visual amigável ou de geradores prontos na web para criar amostras estruturadas rapidamente, acesse as nossas ferramentas:

• Gere CPFs válidos sob demanda no Gerador de CPF.
• Gere dados de empresas no Gerador de CNPJ.
• Configure massas robustas e estruturadas no nosso Mock Data Generator.