Chatwoot MCP Server

kommo mcp服务器

MCP服务器（Model Context Protocol）旨在与 Laburen.com，包括其与Kommo CRM的本地集成。该服务器公开了允许Laburen AI代理管理Lead、在管道之间移动它们、暂停代理并直接在Kommo中添加上下文注释的工具。

🎯 概述

这个MCP服务器是 Laburen.com 它充当了Laburen AI代理和Kommo CRM API之间的桥梁，利用了两个平台之间的本地集成。它为Lead的自动化管理提供了专门的工具，允许Laburen代理直接与Kommo交互以移动Lead、暂停代理并添加上下文注释。服务器在CloudFlare Workers中运行，并使用持久对象来维护MCP连接的状态。

✨ 主要特征

1. 完整的 MCP 服务器

• MCP协议（模型上下文协议）的实现
• 支持服务器发送事件（SSE）进行实时通信
• 与官方MCP SDK的集成

2. 领导管理工具

• 搬运工负责人 管道和构件之间
• 暂停代理 分配给特定的领导
• 添加注释 与Leads历史相关

3. 灵活配置

• 使用环境变量配置
• 在每个请求中由HTTP标头覆盖
• 启用工具的粒度控制

4. 多帐户

• 通过动态配置支持多个Kommo帐户
• 独立帐户身份验证

🏗️ 建筑

主要成分

• 入口点 (src/index.ts)：处理HTTP请求并路由到MCP端点
• MCP服务器 (src/mcp.ts)：定义MCP服务器并注册可用的工具
• 工具 (src/tools/leads.ts)：实现与Kommo API交互的功能
• 工具集 (src/utils/)：用于验证和配置分析的实用程序

技术

• Cloudflare员工：无服务器执行平台
• 耐用物品：维护MCP连接状态
• 模型上下文协议SDK：MCP服务器官方SDK
• API组v4：与Kommo CRM的本地集成
• Laburen.com：集成人工智能代理生态系统
• TypeScript：编程语言
• 萨德：架构验证

📋 要求

环境变量

服务器可以通过两种方式接收配置（标题优先于环境变量）：

1.环境变量 wrangler.jsonc o Cloudflare仪表板）

{
  "KOMMO_LONG_DURATION_TOKEN": "tu_token_de_kommo",
  "KOMMO_ACCOUNT_SUBDOMAIN": "tu_subdominio",
  "TOOLS_TO_USE": ["move_lead", "pause_agent", "add_note"]
}

2.HTTP标头（优先于ENV）

每个请求都可以包括覆盖配置的标头：

• KOMMO_LONG_DURATION_TOKEN：Kommo认证令牌
• KOMMO_ACCOUNT_SUBDOMAIN：Kommo帐户子域
• TOOLS_TO_USE：启用的工具列表（JSON数组或CSV格式）

格式转换器 TOOLS_TO_USE:

• JSON： ["move_lead", "pause_agent", "add_note"]
• CSV： move_lead,pause_agent,add_note

🚀 安装和部署

地方发展

# Instalar dependencias
npm install

# Ejecutar en modo desarrollo
npm run dev

# O usando wrangler directamente
wrangler dev

生产部署

# Desplegar a Cloudflare Workers
npm run deploy

# O usando wrangler directamente
wrangler deploy

可用脚本

• npm run dev：以开发模式启动服务器
• npm run deploy：Despliega a Cloudflare员工
• npm run format：使用Biome格式化代码
• npm run lint:fix：纠正链接问题
• npm run type-check：验证类型脚本
• npm run cf-typegen：生成CloudFlare Workers类型

📡 端点

MCP服务器（HTTP）

GET /mcp

用于HTTP通信的MCP服务器的主要端点。

服务器发送事件（SSE）

GET /sse
GET /sse/message

通过服务器发送事件进行通信的端点，允许与MCP客户端进行实时通信。

🛠️ 可用的工具

服务器公开了以下MCP工具来与Kommo交互：

move_lead

______________________________________________________________________

将导线移动到管道中，并在Kommo中处于不同的状态。

参数：

• lead_id （数字）：Kommo中Lead的唯一ID
• pipeline_id （编号）：管道目的地ID
• status_id （数字）：管道内的状态ID

使用示例：

{
  "lead_id": 12345,
  "pipeline_id": 1,
  "status_id": 2
}

答案：

• ✅ Éxito：“Lead已成功移动到指定的管道和状态。”
• ❌ 潜在客户不存在：“移动潜在客户失败：指定的潜在客户在Kommo中不存在。”
• ❌ API错误：“移动潜在客户失败：Kommo不接受更新请求。”

pause_agent

通过更新Kommo中的自定义字段来暂停分配给特定Lead的代理。

参数：

• lead_id （数字）：Kommo中Lead的唯一ID

使用示例：

{
  "lead_id": 12345
}

答案：

• ✅ Éxito：“代理已成功暂停指定潜在客户。”
• ❌ 潜在客户不存在：“暂停代理失败：指定的潜在客户在Kommo中不存在。”

add_note

在Kommo的Lead历史记录中添加上下文注释。

参数：

• lead_id （数字）：Kommo中Lead的唯一ID
• note （字符串）：要添加到Lead历史记录的注释

使用示例：

{
  "lead_id": 12345,
  "note": "Cliente interesado en producto premium. Seguimiento programado para mañana."
}

答案：

• ✅ Éxito：“注释添加成功。”
• ❌ 错误：“添加注释时出错。”

🔧 配置工具

可以使用变量启用或禁用工具 TOOLS_TO_USE。MCP服务器上只有列出的工具可用。

示例-仅启用 move_lead y add_note:

{
  "TOOLS_TO_USE": ["move_lead", "add_note"]
}

示例-禁用所有工具：

{
  "TOOLS_TO_USE": []
}

🔗 与Laburen.com的整合

这个MCP服务器是专门为在 Laburen.com。Laburen的AI代理可以使用此MCP服务器通过两个平台之间的本地集成与Kommo CRM进行交互。

集成流程

1. Laburen代理连接到MCP服务器
2. MCP服务器公开了Kommo的专用工具
3. 代理商使用这些工具来管理Kommo的Lead
4. 这些操作直接在配置的Kommo帐户上执行

🔐 Kommo认证

服务器使用Kommo的长期令牌进行身份验证。要获得令牌：

1. 访问您的Kommo帐户设置
2. 转到集成→API
3. 生成长期令牌
4. 在环境变量或标题中配置它

注： 令牌必须具有以下作用域：

• crm：访问CRM
• files：访问文件（如有必要）
• notifications：通知（如有必要）

📊 项目结构

kommo-mcp-server/
├── src/
│   ├── index.ts              # Punto de entrada del worker
│   ├── mcp.ts                # Servidor MCP y definición de herramientas
│   ├── types.ts              # Tipos TypeScript
│   ├── tools/
│   │   └── leads.ts          # Funciones para interactuar con API de Kommo
│   └── utils/
│       ├── canUseTools.ts    # Validación de herramientas habilitadas
│       └── parseTools.ts     # Parsing de configuración de herramientas
├── wrangler.jsonc            # Configuración de Cloudflare Workers
├── tsconfig.json             # Configuración de TypeScript
├── biome.json                # Configuración de Biome (linter/formatter)
└── package.json              # Dependencias del proyecto

🔍 监测和观察

服务器在CloudFlare Workers中启用了可观察性：

• 日志：执行和错误日志
• Metricas：性能和资源使用
• 可追溯性：跟踪所使用的请求和工具

日志包括：

• 带有前缀的工具错误 💥
• 带有前缀的API错误 ❌
• 调试信息

🧪 发展

类型验证

npm run type-check

代码格式

npm run format

代码检查

npm run lint:fix

📝 技术说明

• 服务器使用 耐用物品 维护MCP连接的状态
• 工具在暴露之前被动态验证
• 所有工具都在执行操作之前验证Lead的存在
• 错误得到一致处理，并返回描述性消息

🤝 贡献

这是一个私人项目。如需更改或改进，请联系开发团队。

📄 许可证

私人-保留所有权利。