zentao-mcp-v1

禅道 MCP Server，专门适配禅道开源版 18.x REST API v1。

在 Kiro / Cursor / Claude Desktop 等支持 MCP 的 AI IDE 中直接管理禅道的 Bug、任务、需求、评论等，无需切换浏览器。

为什么需要这个包？

市面上已有的禅道 MCP 包大多基于禅道专业版/旗舰版 API 或假定特定部署路径（如 /zentao 前缀），在开源版 18.x 上会遇到：

• 评论/操作历史接口 404（开源版没有独立的 /actions 端点）
• Token 获取失败（MD5 密码 vs 明文密码问题）
• 路径前缀不匹配

本包通过 REST API v1 + pathinfo 格式混合调用，解决了上述所有问题。

功能（22 个工具）

| 类别 | 工具 | 说明 | |---|---|---| | 通用 | call | 调用任意禅道 REST API | | Bug | get_my_bugs | 获取我的 Bug 列表 | | | get_bug_detail | Bug 详情 | | | resolve_bug | 解决 Bug | | | close_bug | 关闭 Bug | | | activate_bug | 重新激活 Bug | | 任务 | getMyTasks | 获取我的任务列表 | | | getTaskDetail | 任务详情 | | | updateTask | 更新任务 | | | finishTask | 完成任务 | | | createTask | 创建任务 | | | deleteTask | 删除任务 | | 需求 | getStoryDetail | 需求详情 | | | getProductStories | 产品需求列表 | | 评论 | getActions | 获取操作历史和评论 ✅ | | | addComment | 添加评论 ✅ | | 项目 | getProjects / getProjectDetail | 项目列表/详情 | | | getProjectExecutions / getProjectReleases | 执行列表/发布列表 | | 执行 | getExecutionDetail / getExecutionTasks / getExecutionBuilds | 迭代详情/任务/版本 | | 产品 | getProducts / getProductBugs / getProductPlans | 产品列表/Bug/计划 | | 其他 | getUsers / getTodos | 用户列表/待办 |

快速开始

1. 安装

npm install -g zentao-mcp-v1

2. 配置 MCP

Kiro (~/.kiro/settings/mcp.json)：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "zentao-mcp-v1"],
      "env": {
        "ZENTAO_URL": "http://你的禅道地址:端口",
        "ZENTAO_ACCOUNT": "你的账号",
        "ZENTAO_PASSWORD": "你的密码"
      }
    }
  }
}

Cursor (.cursor/mcp.json)：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "zentao-mcp-v1"],
      "env": {
        "ZENTAO_URL": "http://你的禅道地址:端口",
        "ZENTAO_ACCOUNT": "你的账号",
        "ZENTAO_PASSWORD": "你的密码"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "zentao-mcp-v1"],
      "env": {
        "ZENTAO_URL": "http://你的禅道地址:端口",
        "ZENTAO_ACCOUNT": "你的账号",
        "ZENTAO_PASSWORD": "你的密码"
      }
    }
  }
}

3. 重启 IDE / 重连 MCP

配置完成后重启 IDE 或在 MCP 面板中重连服务。

使用示例

在 AI 对话中直接说：

• "看看我有哪些 Bug"
• "查看任务 #616 的详情"
• "把 Bug #123 标记为已修复"
• "给任务 #456 添加一条备注"
• "获取任务 #616 的操作历史和评论"

环境变量

| 变量 | 说明 | 必填 | |---|---|---| | ZENTAO_URL | 禅道服务地址，如 http://192.168.1.100:8080 | ✅ | | ZENTAO_ACCOUNT | 登录账号 | ✅ | | ZENTAO_PASSWORD | 登录密码（明文） | ✅ |

适配说明

• 禅道版本：开源版 18.x（REST API v1）
• 部署方式：支持根路径部署（无 /zentao 前缀）和子目录部署
• 认证方式：明文密码，Token 自动缓存和刷新
• Node.js：>= 18（需要原生 fetch 支持）

技术细节

为什么用 pathinfo 混合调用？

禅道开源版 18.x 的 REST API v1 有以下限制：

1. 无独立的 actions/comments 端点：/bugs/{id}/actions 返回 404
2. 部分列表接口需要通过父级获取：如 /projects/{id}/builds 返回 403，需用 /executions/{id}/builds
3. pathinfo 格式（如 /bug-view-{id}.json）响应中包含 actions 字段

本包采用策略：

• 列表查询、创建、更新、删除 → REST API v1
• 详情 + 操作历史 + 评论 → pathinfo 格式
• Token 获取 → REST API /api.php/v1/tokens

pathinfo 响应格式

{"status":"success","data":"{\"title\":\"...\",\"actions\":[...]}","md5":"..."}

data 是转义后的 JSON 字符串，需要二次 JSON.parse()。

License

MIT