mcp-server-bigboost

mcp-server-bigboost

0
research_and_data

The mcp-server-bigboost provides a standardized interface for querying data from Bigboost API using the Model Context Protocol. It facilitates access to personal and company data through integration with language models like Claude. The server follows SOLID design principles and supports high-volume requests with specific limitations.

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/sdk@1.10.0

  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": "..."
}