@kemosoft/mcp-heymax-crm

MCP server em TypeScript para a API de atendimento do HeyMax CRM hospedada em ms-crm-az.kemosoft.com.br.

Estado atual

Esta primeira versão expõe apenas ferramentas read-only. Foi uma decisão deliberada.

Revisão adversarial:

• A OpenAPI da API está incompleta para operações de escrita.

• Publicar tools destrutivas agora aumentaria risco operacional sem garantia de contrato estável.

• O servidor já é útil para consulta, mas ainda não é um conector "completo" de CRM.

Related MCP server: pipedrive-pj

Fluxo

Cliente MCP
  -> Servidor (valida input com Zod)
  -> HeyMax CRM API (envia request com api-key)
  <- JSON ou erro HTTP
  -> Servidor (normaliza resposta/erro)
  -> Cliente (structuredContent + texto)

Para quem isso é utilizável

Hoje o servidor é utilizável por qualquer pessoa que tenha:

• Node.js >= 22

• acesso a um cliente MCP compatível com stdio

• uma credencial válida em HEYMAX_CRM_API_KEY

Revisão adversarial:

• Sem credencial válida, o pacote instala mas não entrega valor real.

• Portanto o produto ainda não é "aberto para qualquer pessoa" no sentido de acesso irrestrito à API.

Requisitos

• Node.js >= 22

• npm

• Credencial válida em HEYMAX_CRM_API_KEY

Variáveis de ambiente

Copie .env.example para .env ou exporte as variáveis no shell:

• HEYMAX_CRM_API_KEY: obrigatório

• HEYMAX_CRM_API_SOURCE: opcional nesta versão; será usado nas futuras operações de escrita

O timeout de request nao e configuravel pelo usuario. Ele e fixo em 30s. O host da API tambem nao e configuravel. O servidor so fala com https://ms-crm-az.kemosoft.com.br.

Guardrails de seguranca

• respostas de erro upstream sao sanitizadas

• payloads retornados ao modelo passam por redacao de campos sensiveis

• conteudos potencialmente binarios ou base64 sao removidos do output

• o markdown nao inclui mais dumps brutos de JSON

Instalação

Via npm local:

npm install
npm run build

Via npx depois da publicação no npm:

npx -y @kemosoft/mcp-heymax-crm

Execução

Modo local via stdio:

npm start

Desenvolvimento:

npm run dev

Pipeline de publicação

O release agora é automatizado pelo GitHub Actions depois que o CI passa em main.

• fix: gera patch

• feat: gera minor

• feat!: ou BREAKING CHANGE gera major

• commits que não alteram versão não disparam release

O fluxo faz:

• o CI valida build, testes e smoke

• semantic-release calcula a próxima versão

• gera CHANGELOG.md

• publica no npm como @kemosoft/mcp-heymax-crm

• cria release no GitHub

• commita os arquivos de release com [skip ci] para evitar loop

Secrets necessários no repositório:

• NPM_TOKEN: token granular com permissão de publish no scope @kemosoft

• GITHUB_TOKEN: o GitHub Actions fornece automaticamente

Para validar localmente antes de subir:

npm run prepack

Se você quiser publicar manualmente fora do pipeline, use o fluxo do semantic-release em vez de npm publish direto.

Tools disponíveis

• heymax_crm_list_active_pipelines

• heymax_crm_list_lost_reasons

• heymax_crm_list_events

• heymax_crm_list_tags

• heymax_crm_validate_phone

• heymax_crm_search_address_by_cep

• heymax_crm_find_services_by_phone

• heymax_crm_get_pipeline_flow

• heymax_crm_get_service_status_by_id

• heymax_crm_get_service_status_by_funnel_and_cpf

Exemplo de configuração em cliente MCP

Exemplo genérico de comando:

{
  "command": "node",
  "args": ["C:/caminho/para/mcp-heymax-crm/dist/index.js"],
  "env": {
    "HEYMAX_CRM_API_KEY": "sua-chave"
  }
}

Claude Desktop

{
  "mcpServers": {
    "heymax-crm": {
      "command": "npx",
      "args": ["-y", "@kemosoft/mcp-heymax-crm"],
      "env": {
        "HEYMAX_CRM_API_KEY": "sua-chave"
      }
    }
  }
}

Codex

{
  "mcpServers": {
    "heymax-crm": {
      "command": "npx",
      "args": ["-y", "@kemosoft/mcp-heymax-crm"],
      "env": {
        "HEYMAX_CRM_API_KEY": "sua-chave"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "heymax-crm": {
      "command": "node",
      "args": ["/caminho/para/mcp-heymax-crm/dist/index.js"],
      "env": {
        "HEYMAX_CRM_API_KEY": "sua-chave"
      }
    }
  }
}

Estrutura do projeto

src/
  api-client.ts
  config.ts
  constants.ts
  format.ts
  index.ts
  schemas.ts
  tools.ts
  types.ts

Verificação

npm run build
npm run typecheck
npm run smoke

Limitações atuais

• Sem tools de escrita

• Sem transporte HTTP

• Sem paginação real no backend; o limite atual corta o array retornado pela API

• Alguns endpoints da API não possuem schema de resposta confiável na documentação

• A utilidade prática ainda depende de distribuição controlada de HEYMAX_CRM_API_KEY