@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.

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