mcp-server-bigboost

Servidor MCP (Model Context Protocol) para integração com a API Bigboost da Bigdatacorp. Este servidor permite que modelos de linguagem como o Claude possam acessar dados da Bigboost API de forma padronizada, permitindo consultas de dados de pessoas físicas e empresas através de diferentes parâmetros de busca.

O servidor segue os padrões SOLID e SDR, com variáveis, classes e métodos em inglês usando camelCase, e índices no elasticsearch em inglês usando snake_case.

Requisitos

• Node.js 18 ou superior
• npm ou yarn
• Credenciais de acesso à API Bigboost (AccessToken e TokenId)

Estrutura do Projeto

mcp-server-bigboost/
├── src/
│   ├── config/                    # Configurações
│   ├── constants/                 # Constantes
│   ├── services/                  # Serviços
│   ├── tools/                     # Ferramentas MCP
│   ├── types/                     # Definições de tipos
│   ├── utils/                     # Utilitários
│   ├── server.ts                  # Configuração do servidor
│   └── index.ts                   # Ponto de entrada
├── tests/                         # Testes
├── .env.example                   # Exemplo de variáveis de ambiente
└── README.md                      # Documentação

Configuração

1. Clone o repositório
2. Instale as dependências:

   npm install

3. Copie o arquivo .env.example para .env e configure suas credenciais:

   cp .env.example .env

   BIGBOOST_ACCESS_TOKEN=seu-access-token
   BIGBOOST_TOKEN_ID=seu-token-id

Execução

O servidor MCP funciona exclusivamente no modo stdio, usado para integração direta com modelos de linguagem como o Claude:

npm start

Ferramentas Disponíveis

1. Consultas de Pessoas Físicas

1.1. consultaPessoa

Consulta dados básicos de uma pessoa física a partir do CPF.

Parâmetros:

• cpf: Número do CPF (com ou sem pontuação)

Exemplo de uso:

// No Claude Desktop
const resultado = await mcp.consultaPessoa({ cpf: "${CPF_EXEMPLO}" });

// Em outros clientes MCP
const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "consultaPessoa",
    parameters: { cpf: "${CPF_EXEMPLO}" }
  })
});
const resultado = await response.json();

1.2. consultaPessoaTelefone

Consulta dados básicos de uma pessoa física a partir do número de telefone.

Parâmetros:

• telefone: Número de telefone (com ou sem pontuação)

Exemplo de uso:

// No Claude Desktop
const resultado = await mcp.consultaPessoaTelefone({ telefone: "${TELEFONE_EXEMPLO}" });

// Em outros clientes MCP
const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "consultaPessoaTelefone",
    parameters: { telefone: "${TELEFONE_EXEMPLO}" }
  })
});
const resultado = await response.json();

1.3. consultaPessoaEmail

Consulta dados básicos de uma pessoa física a partir do endereço de email.

Parâmetros:

• email: Endereço de email válido

Exemplo de uso:

// No Claude Desktop
const resultado = await mcp.consultaPessoaEmail({ email: "${EMAIL_EXEMPLO}" });

// Em outros clientes MCP
const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "consultaPessoaEmail",
    parameters: { email: "${EMAIL_EXEMPLO}" }
  })
});
const resultado = await response.json();

2. Consultas de Empresas

2.1. consultaEmpresa

Consulta dados básicos de uma empresa a partir do CNPJ.

Parâmetros:

• cnpj: Número do CNPJ (com ou sem pontuação)

Exemplo de uso:

// No Claude Desktop
const resultado = await mcp.consultaEmpresa({ cnpj: "${CNPJ_EXEMPLO}" });

// Em outros clientes MCP
const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "consultaEmpresa",
    parameters: { cnpj: "${CNPJ_EXEMPLO}" }
  })
});
const resultado = await response.json();

2.2. consultaQsa

Consulta o Quadro Societário e Administrativo (QSA) de uma empresa a partir do CNPJ.

Parâmetros:

• cnpj: Número do CNPJ (com ou sem pontuação)

Exemplo de uso:

// No Claude Desktop
const resultado = await mcp.consultaQsa({ cnpj: "${CNPJ_EXEMPLO}" });

// Em outros clientes MCP
const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "consultaQsa",
    parameters: { cnpj: "${CNPJ_EXEMPLO}" }
  })
});
const resultado = await response.json();

2.3. consultaRegistroEmpresa

Consulta dados completos de registro de uma empresa a partir do CNPJ, incluindo endereços e contatos.

Parâmetros:

• cnpj: Número do CNPJ (com ou sem pontuação)

Exemplo de uso:

// No Claude Desktop
const resultado = await mcp.consultaRegistroEmpresa({ cnpj: "${CNPJ_EXEMPLO}" });

// Em outros clientes MCP
const response = await fetch("http://localhost:3000/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "consultaRegistroEmpresa",
    parameters: { cnpj: "${CNPJ_EXEMPLO}" }
  })
});
const resultado = await response.json();

Limitações

• Limite de 5000 requisições a cada 5 minutos por IP
• As requisições devem ser distribuídas homogeneamente
• Timeout de 30 segundos para cada requisição
• Datasets restritos podem retornar a mensagem "DATASET UNAVAILABLE"
• Alguns parâmetros podem ser obrigatórios, semi-obrigatórios ou opcionais

Desenvolvimento

Compilação

npm run build

Execução em modo de desenvolvimento

npm run dev

Solução de problemas

Erro com o pacote @modelcontextprotocol/sdk

Se você encontrar erros relacionados ao pacote @modelcontextprotocol/sdk, como:

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in node_modules/@modelcontextprotocol/sdk/package.json

ou

Cannot find module '@modelcontextprotocol/sdk' or its corresponding type declarations

Tente as seguintes soluções:

1. Usar uma versão específica do Node.js (recomendado: v18.x):

   nvm use 18

2. Reinstalar o pacote MCP SDK:

   npm uninstall @modelcontextprotocol/sdk
   npm install @modelcontextprotocol/[email protected]

3. Limpar o cache do npm:

   npm cache clean --force
   rm -rf node_modules
   npm install

Testes

npm test

Lint

npm run lint

Características Técnicas

• Implementação seguindo os princípios SOLID e SDR
• Tratamento adequado para os códigos de status da API:
  • Códigos -100 a -999: relacionados aos dados de entrada
  • Códigos -1000 a -1199: relacionados a problemas de login
  • Códigos -1200 a -1999: relacionados a problemas internos nas APIs ou datasets
  • Códigos -2000 a -2999: relacionados às consultas on-demand
  • Códigos -3000 em diante: relacionados a problemas na API de Monitoramento ou Chamadas Assíncronas
• Controle de limite de requisições
• Suporte a tags de chamada (limitado a 10 tags por requisição)
• Tratamento para datasets restritos
• Validação de parâmetros de consulta
• Retorno dos dados brutos da API, sem transformações adicionais

Integração com Clientes

Integração com o Windsurf

Para utilizar este servidor com o Windsurf (Claude Desktop), você precisa configurá-lo no arquivo mcp_config.json:

1. Instale o pacote do servidor:

   npm install -g mcp-server-bigboost

2. Adicione a configuração ao arquivo ~/.codeium/windsurf/mcp_config.json:

   {
     "mcpServers": {
       "bigboost-mcp-server": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-server-bigboost"
         ],
         "env": {
           "BIGBOOST_ACCESS_TOKEN": "seu-access-token",
           "BIGBOOST_TOKEN_ID": "seu-token-id"
         }
       }
     }
   }

3. Reinicie o Windsurf para que as alterações sejam aplicadas.

4. Utilize as ferramentas diretamente no prompt do Claude:

   Por favor, consulte o CPF ${CPF_EXEMPLO} usando a ferramenta consultaPessoa.

Integração com Claude e outros modelos de linguagem

Para utilizar este servidor com o Claude ou outros modelos de linguagem:

1. Inicie o servidor:

   npm start

2. Configure o Claude para usar o servidor como uma ferramenta externa via MCP:

   • No Claude Desktop, adicione o servidor como uma ferramenta externa
   • No Claude Web, configure a integração com o servidor MCP

Exemplo de uso direto no Claude

Usuário: Consulte o CPF ${CPF_EXEMPLO} para mim.

Claude: Vou consultar esse CPF para você usando a ferramenta consultaPessoa.

[Claude usa a ferramenta consultaPessoa com o parâmetro CPF]

Aqui estão os resultados da consulta para o CPF ${CPF_EXEMPLO}:

Nome: João da Silva
Data de Nascimento: 15/05/1980
Situação do CPF: Regular
...

Códigos de Status e Tratamento de Erros

O servidor MCP retorna os códigos de status da API Bigboost no campo status da resposta. Verifique sempre este campo para garantir que a consulta foi bem-sucedida.

Exemplo de resposta com sucesso:

{
  "result": [...],
  "status": {
    "doc_finder": [
      {
        "Code": 0,
        "Message": "OK"
      }
    ],
    "basic_data": [
      {
        "Code": 0,
        "Message": "OK"
      }
    ]
  },
  "queryId": "...",
  "elapsedMilliseconds": 123,
  "queryDate": "..."
}