Kayako MCP Server

我能得到MCP服务器吗

Kayako Classic REST API的模型上下文协议（MCP）服务器，使人工智能代理能够高效地搜索、过滤和分析支持票证。

特性

🔍 搜索和筛选功能

• 高级搜索：按内容、主题、员工备注、用户电子邮件或姓名搜索门票
• 灵活过滤：按部门、状态、分配的员工或客户筛选
• 智能分页：使用偏移/限制控件处理大型结果集
• 多种格式：Markdown（人类可读）或JSON（机器可读）输出

🎯 核心工具

1. kayako_search_tickets -在多个字段中搜索门票
2. kayako_get_ticket -通过可选的对话历史记录获取完整的门票详细信息
3. kayako_list_tickets -使用高级过滤和排序功能列出门票
4. kayako_get_ticket_posts -检索完整的对话历史记录
5. kayako_get_departments -列出所有部门（筛选助手）
6. kayako_get_ticket_statuses -列出所有工单状态（帮助过滤）

💡 分析友好

• 针对AI分析优化的干净、结构化数据
• 按时间顺序排列的对话历史
• 时间戳格式，便于人类阅读
• 内容截断，并为大型响应提供指导
• 字符限制处理（25000个字符）和有用消息

______________________________________________________________________

安装

先决条件

• Python 3.10或更高版本
• 紫外线 包管理器（推荐）或pip
• 启用REST API的Kayako经典实例
• Kayako API证书（API密钥和密钥）

步骤1：安装依赖项

使用 uv （推荐）：

cd kayako-mcp
uv sync

使用 pip:

cd kayako-mcp
pip install -e .

步骤2：配置API凭据

1. 复制示例环境文件：

cp .env.example .env

1. 编辑 .env 并添加您的Kayako凭据：

KAYAKO_API_URL=https://yourcompany.kayako.com/api/index.php
KAYAKO_API_KEY=your-api-key-here
KAYAKO_SECRET_KEY=your-secret-key-here

查找您的Kayako API证书：

1. 登录Kayako管理控制面板
2. 首选 REST API 章节
3. 找到你的 API密钥 和 密钥 在...之下 api信息
4. 复制基本API URL（通常 https://yourcompany.kayako.com/api/index.php)

步骤3：测试服务器

# Show help information
uv run kayako_mcp.py --help
python kayako_mcp.py --help

# Test API credentials (recommended)
uv run kayako_mcp.py --test-credentials
python kayako_mcp.py -t

这 --test-credentials 标志验证您的API连接：

• ✅ 成功：显示连接详细信息和找到的部门数量
• ❌ 失败：显示带有诊断信息的特定错误（401、403、404、超时）

成功测试示例：

🔍 Testing Kayako API credentials...

✅ SUCCESS: API credentials are valid and working

📊 Connection Details:
  • Api Url: https://yourcompany.kayako.com/api/index.php
  • Api Key: abc1234567...
  • Departments Found: 5

______________________________________________________________________

使用Claude代码

添加到克劳德代码

claude mcp add --transport stdio kayako \
  -- uv run /Users/moroz/Projects/test-skills/kayako-mcp/kayako_mcp.py

或手动添加到 ~/.claude.json:

{
  "mcpServers": {
    "kayako": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "/Users/moroz/Projects/test-skills/kayako-mcp/kayako_mcp.py"
      ],
      "env": {
        "KAYAKO_API_URL": "https://yourcompany.kayako.com/api/index.php",
        "KAYAKO_API_KEY": "your-api-key",
        "KAYAKO_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

查询示例

一旦与Claude Code集成，您可以问：

搜索查询：

• “搜索有关密码重置问题的所有票证”
• “从用户处查找门票john@example.com"
• “显示上周包含‘账单错误’的门票”

筛选查询：

• “列出支持部门中所有未处理的工单”
• “给我看分配给5号工作人员的票”
• “按上次活动对所有已解决的工单进行排序”

分析查询：

• “分析12345号工单的对话历史记录”
• “开放式门票最常见的问题是什么？”
• “显示ABC-123-456票的全部详细信息以及所有回复”

帮助查询：

• “有哪些部门可用？”
• “列出所有票证状态及其ID”

______________________________________________________________________

工具参考

1. kayako_search_tickets

按内容、主题、用户或其他条件搜索门票。

参数：

• query （字符串，必填）：搜索查询文本
• search_contents （boolean）：在票体中搜索（默认值：true）
• search_subject （布尔值）：在主题行中搜索（默认值：true）
• search_notes （boolean）：在员工备注中搜索（默认值：false）
• search_user_email （boolean）：按用户电子邮件搜索（默认值：false）
• search_user_name （boolean）：按用户名搜索（默认值：false）
• limit （整数）：最大结果1-100（默认值：20）
• offset （整数）：分页偏移量（默认值：0）
• response_format （string）：markdown或json（默认：markdown）

例子：

Search tickets with query="password reset", search_contents=true, limit=10

2. kayako_get_ticket

获取特定票证的完整详细信息。

参数：

• ticket_id （字符串，必填）：票证ID（显示ID或内部ID）
• include_posts （布尔值）：包括对话历史记录（默认值：false）
• response_format （string）：markdown或json（默认：markdown）

例子：

Get ticket with ticket_id="12345", include_posts=true

3. kayako_list_tickets

使用高级过滤功能列出门票。

参数：

• department_id （整数，可选）：按部门筛选
• status_id （整数，可选）：按状态筛选
• owner_staff_id （整数，可选）：按指定人员筛选
• user_id （整数，可选）：按客户筛选
• limit （整数）：最大结果1-100（默认值：20）
• offset （整数）：分页偏移量（默认值：0）
• sort_field （string）：排序字段（默认：“lastactivity”）
• sort_order （字符串）：“ASC”或“DESC”（默认值：“DESC“）
• response_format （string）：“markdown”或“json”

例子：

List tickets with status_id=1, department_id=2, limit=20, sort_order="DESC"

4. kayako_get_ticket_posts

获取票务对话中的所有帖子/回复。

参数：

• ticket_id （字符串，必填）：票证ID
• response_format （string）：“markdown”或“json”

例子：

Get posts for ticket_id="12345"

5. kayako_get_departments

列出所有部门（筛选助手）。

参数：

• response_format （string）：“markdown”或“json”

例子：

Get departments in markdown format

6. kayako_get_ticket_statuses

列出所有工单状态（筛选助手）。

参数：

• response_format （string）：“markdown”或“json”

例子：

Get ticket statuses in JSON format

______________________________________________________________________

建筑

认证

使用Kayako Classic基于HMAC的签名身份验证：

1. 为每个请求生成随机盐（32个十六进制字符）
2. 创建签名： Base64(HMAC-SHA256(key=secret_key, message=salt))
3. 发送 apikey, salt，以及 signature 每次请求

注： Kayako Classic需要HMAC-SHA256，而不是普通的SHA256。HMAC（基于哈希的消息认证码）是一种加密算法，它使用哈希函数将密钥与消息组合在一起。

XML解析

• Kayako Classic对所有响应使用XML
• 自动转换为Python字典
• 数字、布尔值和字符串的类型推断
• 处理嵌套元素和属性

响应格式

• 标记语言：人类可读的标题、列表、时间戳
• JSON：用于程序化处理的完整结构化数据
• 字符限制强制（25000个字符）
• 带引导的智能截断

错误处理

清晰、可操作的错误消息，用于：

• 身份验证失败（401）
• 未发现错误（404）
• 速率限制（429）
• 服务器错误（500+）
• 网络超时
• 数据格式无效

______________________________________________________________________

发展

项目结构

kayako-mcp/
├── kayako_mcp.py       # Main MCP server (single file)
├── pyproject.toml      # Dependencies
├── README.md           # This file
├── .env.example        # Example environment variables
└── .env                # Your actual credentials (gitignored)

运行测试

基本验证：

# Check Python syntax
python -m py_compile kayako_mcp.py

# Test configuration
uv run kayako_mcp.py --help

代码质量特征

• ✅ 全程键入提示
• ✅ Pydantic v2用于输入验证
• ✅ 全面的文档字符串
• ✅ DRY原则-无代码重复
• ✅ 异步/等待所有I/O
• ✅ MCP最佳实践合规性
• ✅ 所有操作的工具注释

______________________________________________________________________

故障排除

“身份验证失败”错误

• 第一步： 跑 uv run kayako_mcp.py --test-credentials 诊断问题
• 验证 KAYAKO_API_KEY 和 KAYAKO_SECRET_KEY 是正确的
• 检查Kayako Admin CP中是否启用了API访问
• 确保您的API密钥具有必要的权限
• 重要提示： 删除尾随 ? 或 / 从 KAYAKO_API_URL （例如，使用 https://company.kayako.com/api/index.php 不 https://company.kayako.com/api/index.php?)
• 注： 此服务器仅适用于Kayako Classic（v3/v4），不适用于使用OAuth令牌的Kayako v5+

“请求超时”错误

• Kayako服务器可能运行缓慢或遇到问题
• 请稍后再试
• 检查您的网络连接

“未找到有效查询的票”

• 验证搜索查询是否与票证内容匹配
• 尝试更广泛的搜索词
• 检查Kayako系统中是否存在门票
• 尝试不同的搜索区域（内容、主题等）

“超出速率限制”错误

• 请等待几分钟，然后再提出更多请求
• 降低API调用频率
• 如果进行重复查询，请考虑缓存结果

XML分析错误

• 如果这种情况持续存在，请联系Kayako支持
• 可能表示API兼容性问题
• 检查Kayako版本（此服务器适用于Classic/v4）

______________________________________________________________________

局限性

• 仅限Kayako经典：专为Kayako Classic（v3/v4）设计，而不是Kayako v5+
• 只读的：所有工具都是只读的（尚未创建/修改工单）
• 无附件：MVP不支持附件下载
• XML性能：XML解析比JSON慢（Kayako Classic固有）
• 速率限制：受Kayako API费率限制

______________________________________________________________________

未来的增强功能

未来版本的潜在添加：

• 写入操作（创建工单、添加回复、更新状态）
• 附件支持（上传/下载）
• 自定义字段访问
• 高级分析和报告工具
• 批量操作
• 时间跟踪数据
• SLA信息
• 实时通知

______________________________________________________________________

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 提交带有描述的拉取请求

______________________________________________________________________

支持

对于问题或疑问：

• 在GitHub上打开一个问题
• 查看Kayako Classic API文档：https://classichelp.kayako.com/article/45383-kayako-rest-api
• 审查MCP协议文件：https://modelcontextprotocol.io

______________________________________________________________________

内置：

• 模型上下文协议（MCP）
• FastMCP Python SDK
• Pydantic v2
• httpx
• lxml 文件

创建： 2025年10月 版本： 0.1.0（MVP）