🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more

mcp-server-bigboost

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

mcp-server-bigboost

Servidor MCP para integração com a API Bigboost da Bigdatacorp

1.0.9
latest
Version published
Weekly downloads
34
-60.47%
Maintainers
1
Weekly downloads
 
Created

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

ou

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/sdk@1.10.0
    
  • 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": "..."
}

FAQs

Package last updated on 04 May 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts