Kommo MCP Server

Servidor MCP (Model Context Protocol) para integração com o CRM Kommo via Fastify + Node.js.

🎯 Características

• Multi-tenant: Suporta múltiplas contas Kommo via token Bearer

• MCP over HTTP: Protocolo JSON-RPC 2.0 (Streamable)

• Sistema de Aprovação: Pede confirmação antes de operações em múltiplos registros (via sampling)

• Cache inteligente: Pipelines e campos customizados cacheados

• Validação de entrada: Schemas Zod para validação robusta de parâmetros

• Type-safe: TypeScript com strict mode e tipagens completas

• Error handling: Tratamento de erros estruturado com códigos JSON-RPC

• Logging: Sistema de logs integrado com Fastify

• Segurança: Validação de tokens, variáveis de ambiente obrigatórias

📦 Instalação

npm install
npm run build

⚙️ Configuração

Crie um arquivo .env na raiz (copie de .env.example):

PORT=3000
HOST=0.0.0.0
MCP_PASSWORD=SuaSenhaSegura123

⚠️ IMPORTANTE:

• MCP_PASSWORD é OBRIGATÓRIO - o servidor não inicia sem ele

• Nunca use senhas fracas ou padrão em produção

• Nunca commite o arquivo .env com credenciais reais

🚀 Executar localmente

# Desenvolvimento (inicia servidor + MCP Inspector)
npm run dev

# Apenas o servidor
npm start

# Build + Servidor (sem inspector)
npm run build && npm start

# Watch mode (recompila automaticamente)
npm run dev:watch

# Apenas MCP Inspector
npm run inspector

Quick start:

# Instalar dependências
npm install

# Desenvolvimento (servidor + inspector)
npm run dev

# Produção
npm run build
npm start

🔐 Autenticação

Formato do token Bearer:

MCP_PASSWORD|subdomain|kommoAccessToken

Exemplo:

curl -H "Authorization: Bearer Admin123|mpcamotestecom|eyJ0eXAi..." \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:3000/mcp

📡 Endpoints

🔧 Ferramentas Disponíveis

Cache

• Pipelines: 10 minutos

• Estágios: 10 minutos

• Campos customizados: 1 hora

🔄 Uso com n8n

1. kommo_start_session  → Inicia atendimento com lead
2. kommo_update_lead    → Modifica dados
3. kommo_add_notes      → Registra observações
4. kommo_add_tasks      → Cria follow-ups
5. kommo_end_session    → Encerra atendimento

⚠️ Boas Práticas e Segurança

Segurança

• ✅ Senha obrigatória via variável de ambiente

• ✅ Validação de entrada com Zod schemas

• ✅ Tokens multi-parte com validação

• ✅ Error handling estruturado

• ✅ Logs de erros com Fastify

Desenvolvimento

• ✅ TypeScript com strict mode

• ✅ Tipagens completas (FastifyRequest, FastifyReply)

• ✅ Constantes centralizadas em arquivo separado

• ✅ Schemas de validação reutilizáveis

• ✅ Cache configurável por TTL

Código Limpo

• ✅ Separação de responsabilidades (types, schemas, constants)

• ✅ Error codes padronizados (JSON-RPC 2.0)

• ✅ Mensagens de erro descritivas

• ✅ Validação early-return

Documentação

• 📄 README.md - Visão geral e setup

• 📄 USAGE.md - Exemplos práticos de uso com curl

• 📄 APPROVAL-SYSTEM.md - Sistema de aprovação para operações em múltiplos registros

• 📄 src/constants.ts - Constantes e configurações

• 📄 src/schemas.ts - Schemas de validação

🔐 Sistema de Aprovação

O servidor implementa um sistema de aprovação via MCP sampling para operações que afetam múltiplos registros. Quando você executa comandos como "adicione nota em lucas cardoso" e existem 2 ou mais leads com esse nome, o agente pedirá aprovação antes de executar.

Consulte APPROVAL-SYSTEM.md para detalhes completos.

🛠️ Desenvolvimento

# Build
npm run build

# Dev mode
npm run dev

# Watch mode
npm run dev:watch