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

Clone o repositório
Instale as dependências:
```
npm install
```

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

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

Tente as seguintes soluções:

Usar uma versão específica do Node.js (recomendado: v18.x):
```
nvm use 18
```

Reinstalar o pacote MCP SDK:

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

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:

Instale o pacote do servidor:
```
npm install -g mcp-server-bigboost
```

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

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

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:

Inicie o servidor:
```
npm start
```
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": "..."
}