@kikolove/zentao-mcp-server

禅道（ZenTao）的 MCP（Model Context Protocol）Server。通过 stdio 传输 JSON-RPC 2.0，可被任何支持 MCP 的 AI 客户端（Claude Desktop、Cursor、Qoder、VS Code Copilot 等）直接集成，让 AI Agent 全面接管禅道 Bug 的全生命周期管理。

构建后为单文件分发，零运行时依赖，Node.js >= 18 即可运行。协议层基于官方 @modelcontextprotocol/sdk（esbuild 单文件 bundle），符合 MCP 2025-06-18 规范：多协议版本协商（2024-11-05 / 2025-03-26 / 2025-06-18 / 2025-11-25）、请求取消、规范 JSON-RPC 错误码与初始化状态机。

功能特性

• 协议合规：协议层基于官方 TypeScript SDK 高层 API（McpServer），多版本协商 / 请求取消 / 规范错误码 / zod 入口参数校验开箱即得，与所有官方 servers 同源实现
• 27 个工具：覆盖 Bug 全生命周期（查询/创建/批量创建/更新/批量更新/解决/激活/关闭/指派/确认/评论/贴图/附件与截图下载/关联用例/关联需求/删除）、模块树查询、测试用例（查询过滤/创建）、测试单、版本、需求、任务、执行、发布、用户、项目集等模块
• 写操作复核（verify）：所有写操作执行后自动重新拉取关键字段，有效暴露禅道"HTTP 200 但未生效"的静默失败，返回结果以 verify 为准
• 双通道架构：REST API v1 可用的操作走 REST；不可用的操作（解决/激活/关闭/批量/评论/关联等）自动切换 Web 会话通道，对调用方完全透明
• 一次配置处处共用：凭据写入用户级共享配置 ~/.zentao-mcp/config.json，任意多客户端的 MCP 条目均可零 env 接入，无需在每家 mcp.json 里重复存密码
• 一句话安装：install 子命令一行写入 Claude Desktop / Cursor / Qoder / Codex / VS Code / Claude Code / Trae 的 MCP 配置，支持 --path 覆盖任意未内置客户端，Agent 可自动执行
• 认证自动化：懒登录、并发登录复用、token 失效（401）自动重登重试，Web 会话自动处理禅道登录加密与 CSRF 校验
• AI Agent 友好：工具描述含参数说明与返回示例；错误信息带修复建议（如提示先调用哪个查询工具获取 id）；富文本字段支持图文混排 HTML 或纯文本自动转换
• 权限透明：所有操作基于集成账号自身的权限执行，无权限时返回禅道的权限拒绝信息与可读指引，不做任何权限绕过

环境要求

• Node.js >= 18
• 一台已启用 REST API v1 的禅道实例（浏览器访问 http://<zentao-host>/zentao/api.php/v1 返回 JSON 即为可用）

安装

方式一：npx 直接运行（推荐）

npx @kikolove/zentao-mcp-server

方式二：npm 全局安装

npm install -g @kikolove/zentao-mcp-server
zentao-mcp-server

方式三：从源码运行

git clone <本仓库>
cd zentao-mcp-server
npm install
npm run build
npm start

配置

配置优先级：环境变量 > 配置文件。敏感信息（地址、账号、密码）通过环境变量或配置文件传入，不在代码与命令行中硬编码。

用户级共享配置（推荐，一次配置处处共用）

npx @kikolove/zentao-mcp-server config --url http://zentao.example.com:8188/zentao --user your-account --password your-secret

写入 ~/.zentao-mcp/config.json 后，所有 MCP 客户端的 zentao 条目均可省略 env，凭据集中一份、多端共用；config --show 可按实际查找链查看当前生效配置（密码掩码）。

环境变量

| 变量 | 必填 | 说明 | |---|---|---| | ZENTAO_URL | 是 | 禅道根地址（含 /zentao 路径），如 http://zentao.example.com:8188/zentao | | ZENTAO_USER | 是 | 登录账号 | | ZENTAO_PASSWORD | 是 | 登录密码 | | ZENTAO_TIMEOUT_MS | 否 | 单次请求超时毫秒，默认 15000 | | ZENTAO_CONFIG_FILE | 否 | 指定配置文件路径 |

配置文件

复制 config.example.json 为 config.json 并填写真实值：

{
  "url": "http://zentao.example.com:8188/zentao",
  "user": "your-account",
  "password": "your-password",
  "timeoutMs": 15000
}

查找顺序：ZENTAO_CONFIG_FILE 指定路径 > 当前工作目录 config.json > 用户级共享配置 ~/.zentao-mcp/config.json（首个存在的文件生效，环境变量逐项覆盖）。

MCP 客户端集成

在客户端的 MCP 配置（如 Claude Desktop 的 claude_desktop_config.json、Cursor / Qoder 的 mcp.json）中加入：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@kikolove/zentao-mcp-server"],
      "env": {
        "ZENTAO_URL": "http://zentao.example.com:8188/zentao",
        "ZENTAO_USER": "your-account",
        "ZENTAO_PASSWORD": "your-password"
      }
    }
  }
}

通用接入流程（推荐，两行命令 + 最简配置）

# 1. 一次全局安装
npm install -g @kikolove/zentao-mcp-server

# 2. 凭据写入用户级共享配置（所有客户端共用，mcp.json 零 env）
npx @kikolove/zentao-mcp-server config --url <禅道地址> --user <账号> --password <密码>

# 3. 各客户端一行接入
npx @kikolove/zentao-mcp-server install --client <claude|cursor|qoder|codex|vscode|claude-code|trae>

安装后 mcp.json 中只需最简零 env 条目（凭据来自共享配置）：

"zentao": { "command": "cmd", "args": ["/c", "zentao-mcp-server"] }

Windows 下 install 生成 cmd /c zentao-mcp-server（用系统 cmd.exe 包装全局 bin shim，规避宿主非交互 spawn 无法解析 .cmd 的问题）；macOS / Linux 直接生成 "command": "zentao-mcp-server"（全局 bin 为带 shebang 的 symlink，spawn 直接可用，业界最简形态）。两者均零硬编码路径，任何装了 Node.js 的机器拷贝即用。

客户端默认配置路径：claude（claude_desktop_config.json）、cursor（~/.cursor/mcp.json）、qoder（~/.qoder/mcp.json）、codex（~/.codex/config.toml）、vscode（用户级 Code/User/mcp.json，servers 根键）、claude-code（~/.claude.json）、trae（~/.trae/mcp.json）；未内置的客户端用 --path <配置文件> 直接指定（JSON，根键 mcpServers）。

工具列表

Bug 查询

| 工具 | 说明 | |---|---| | zentao_list_products | 产品列表（查询 Bug / 用例前先用它确认 product id） | | zentao_list_projects | 项目列表 | | zentao_list_modules | 产品模块树（Bug / 用例的 module 取值唯一查询入口） | | zentao_list_bugs | Bug 列表，支持 status/severity/pri/type/assignedTo/module/keywords 过滤；带过滤时自动翻页聚合全部匹配一次性返回（scannedTotal 实际扫描数、scanTruncated 截断标记），自动剔除已删除记录（deletedInPage 本页剔除数） | | zentao_get_bug | Bug 详情（含 steps 复现步骤、处理历史、fileRefs 附件与内嵌图片引用清单） |

Bug 生命周期写操作（均内置 verify 复核）

| 工具 | 说明 | |---|---| | zentao_create_bug | 创建 Bug；steps 支持图文混排富文本（HTML 或纯文本自动转换） | | zentao_batch_create_bugs | 批量创建（bugs 数组，单次上限 10 条，创建后按标题复核） | | zentao_update_bug | 更新编辑类字段：title/steps/severity/pri/type/assignedTo/keywords/module/deadline | | zentao_batch_update_bugs | 批量更新（items 数组，单次上限 20 条，逐条独立复核，返回逐条成功/失败） | | zentao_resolve_bug | 解决 Bug（active → resolved），resolution 支持 fixed / bydesign / duplicate 等 | | zentao_activate_bug | 激活（重开）Bug（resolved/closed → active），用于验证不通过或问题复现 | | zentao_close_bug | 关闭 Bug（→ closed） | | zentao_delete_bug | 删除 Bug（软删除，进入回收站可由管理员恢复，请谨慎使用） |

协作与关联

| 工具 | 说明 | |---|---| | zentao_assign_bug | 指派 Bug 给处理人（复核 assignedTo） | | zentao_confirm_bug | 确认 Bug（标记已确认有效；受限权限操作，无权限时返回可读指引） | | zentao_add_comment | 追加评论（支持图文混排富文本，复核处理历史中的 commented 记录） | | zentao_upload_file | 上传本地图片为 Bug 附件并内嵌 steps 渲染（自动清理旧引用保证唯一；直接传 <img> 会被服务端编码成破图，贴图请一律用本工具；下载见 zentao_download_file） | | zentao_link_case | 关联来源用例（传 "0" 取消关联；自动回填全部字段防止编辑重置） | | zentao_link_story | 关联来源需求（传 "0" 取消关联；同上防重置） |

附件与截图

| 工具 | 说明 | |---|---| | zentao_download_file | 下载 Bug / 用例的附件与内嵌截图：fileId 取自详情返回的 fileRefs；默认落盘到系统临时目录（savePath 可指定），inline=true 直接以图片内容返回（多模态客户端可直接查看）。禅道 file-read 地址需登录态，浏览器匿名打开会跳登录页，查看截图请一律走本工具 |

测试管理

| 工具 | 说明 | |---|---| | zentao_list_testcases | 测试用例列表，支持 module/type/keywords/lastRunResult（含 unrun 未执行）过滤；带过滤时自动聚合全部匹配 | | zentao_get_testcase | 用例详情（接受 "276" 或 "case_276" 形式） | | zentao_create_case | 创建测试用例（steps 为 [{desc, expect}] 数组；需用例创建权限，无权限返回可读指引） | | zentao_create_testtask | 创建测试单（build 需传版本的数字 id） | | zentao_create_build | 创建版本 / Build |

通用查询

| 工具 | 说明 | |---|---| | zentao_list | 通用列表：users / programs / executions / productplans / stories / builds / tasks / testtasks / releases / testsuites | | zentao_get | 通用详情：同上模块；users 支持 id 或账号名 |

返回格式约定

所有列表工具统一返回分页结构，total > limit 时用 page 翻页；带过滤参数调用时自动翻页聚合全部匹配一次性返回（最多扫描 1000 条，返回 scannedTotal 为实际扫描数）：

{
  "page": 1,
  "total": 42,
  "limit": 20,
  "items": [
    { "id": 101, "title": "示例 Bug 标题", "severity": 3, "pri": 3, "status": "active", "assignedTo": { "account": "zhangsan" } }
  ]
}

所有写操作返回 { "verify": { ... } } 复核快照，AI Agent 应以 verify 字段判断操作是否真实生效。

AI Agent 自动安装（一句话安装）

方式一：install 子命令（推荐，通用）

两步完成所有客户端接入：先 config 写一次共享凭据，再逐客户端一行 install（无需再传凭据，条目零 env）：

# 1. 一次全局安装（install 写入的条目通过全局 bin 启动，此步必须先行）
npm install -g @kikolove/zentao-mcp-server

# 2. 凭据写入用户级共享配置（一次即可，所有客户端共用）
npx @kikolove/zentao-mcp-server config \
  --url http://zentao.example.com:8188/zentao \
  --user your-account \
  --password your-secret

# 3. 逐客户端一行接入（无需再传凭据，条目零 env）
npx @kikolove/zentao-mcp-server install --client claude
npx @kikolove/zentao-mcp-server install --client cursor

也可一步到位（凭据内联写入条目 env，不依赖共享配置）：

npx @kikolove/zentao-mcp-server install \
  --client claude \
  --url http://zentao.example.com:8188/zentao \
  --user your-account \
  --password your-secret

--client 可选值：claude（Claude Desktop）/ cursor / qoder / codex / vscode / claude-code / trae；--name（默认 zentao）可省略；未内置客户端用 --path <配置文件> 通用覆盖。Claude Code 用户也可直接用官方 CLI：

claude mcp add zentao -e ZENTAO_URL=<地址> -e ZENTAO_USER=<账号> -e ZENTAO_PASSWORD=<密码> -- npx -y @kikolove/zentao-mcp-server

方式二：让 Agent 自动装（可粘贴提示词）

将下面一句发给任意支持执行命令的 AI Agent，它会自动完成安装与验证：

请帮我安装禅道 MCP：先运行 npm install -g @kikolove/zentao-mcp-server 完成全局安装，
再运行 npx @kikolove/zentao-mcp-server config --url <禅道地址> --user <账号> --password <密码> 写入共享配置，
然后运行 npx @kikolove/zentao-mcp-server install --client <claude|cursor|qoder|codex|vscode|claude-code|trae>，
最后重载 MCP 并调用 zentao_list_products 验证连通性。凭证不要回显到对话或日志中。

方式三：手动配置

不想跑命令时，将以下片段加入客户端 MCP 配置的 mcpServers（详见上方「MCP 客户端集成」）：

"zentao": { "command": "npx", "args": ["-y", "@kikolove/zentao-mcp-server"], "env": { "ZENTAO_URL": "<地址>", "ZENTAO_USER": "<账号>", "ZENTAO_PASSWORD": "<密码>" } }

安装验证与排障

# 连通性验证
调用 zentao_list_products 列出全部产品；再对第一个产品查询未解决 bug 数量并汇总给我

# 报错排障（MCP 调用失败时发给 Agent）
禅道 MCP 调用报错：<粘贴错误信息>。请按 README「已知限制」章节排查：
ZENTAO_URL 是否包含 /zentao 路径、账号密码是否正确、
禅道是否已启用 REST API v1（浏览器访问 <ZENTAO_URL>/api.php/v1 应返回 JSON）

要求 Node.js >= 18 且 npx 可用。若 npx 首次下载超时，先 npm install -g @kikolove/zentao-mcp-server。方式一/二的 install 子命令依赖全局 bin：Windows 生成 cmd /c zentao-mcp-server（系统 cmd.exe 包装 .cmd shim，规避宿主非交互 spawn 限制），macOS / Linux 生成裸 bin 名（带 shebang 的 symlink，直接可用）。

实际场景提示词

安装后可直接复制的简短提示词，按工作流分组：

日常查询

| 提示词 | 触发工具 | |--------|----------| | 看下禅道现在有哪些未解决的 bug，按严重度排个序 | list_bugs(status=active) | | #102 这个 bug 的复现步骤和处理历史是什么 | get_bug | | 产品 1 里严重度 1-2 的 bug 都有哪些？ | list_bugs(severity) | | 禅道上还有哪些 bug 没人处理（未指派）？ | list_bugs 过滤 |

Bug 处理

| 提示词 | 触发工具 | |--------|----------| | 把 #102 指派给 zhangsan，备注“请今天看下” | assign_bug | | 解决 #102：已修复，解决版本 trunk | resolve_bug | | #102 验证不通过，重开并附原因 | activate_bug | | 关闭 #105 | close_bug | | 给 #102 补个评论：已在新版本验证通过 | add_comment | | 为 #102 关联用例 276 | link_case | | 删掉我误建的测试 bug #108 | delete_bug（软删除，可恢复） |

批量与报告

| 提示词 | 触发工具 | |--------|----------| | 把这份清单批量录入禅道 bug：<粘贴多行文本> | batch_create_bugs | | 这 5 个 bug 严重度统一改成 3，指派给 zhangsan | batch_update_bugs | | 汇总当前所有 active bug，生成一份带优先级的处理建议清单 | list_bugs + 分析 | | 新建一个 bug：标题 xxx，步骤是……，严重度 2，指派给 zhangsan | create_bug |

测试管理

| 提示词 | 触发工具 | |--------|----------| | 为产品 1 建版本 V1.2.0，再建测试单“xx 功能回归” | create_build → create_testtask | | 产品 1 的测试用例有多少条？列一下标题 | list_testcases | | #102 关联了哪个用例？把用例详情给我 | get_bug → get_testcase | | 最近的版本发布记录有哪些 | zentao_list?module=releases |

写操作提示词（指派/解决/关闭/删除等）执行前 Agent 会与你确认，禅道数据变更不可轻率。

已知限制（基于 ZenTao 20.4 实测）

• 双通道架构：部分 REST v1 端点在某些禅道部署上静默不执行或状态不生效，本工具对解决/激活/关闭/批量/评论/关联等操作自动走 Web 会话通道，对调用方透明
• Web 通道要求：禅道 20.4 的 zin 框架校验 Origin/Referer 头；登录需携带密码强度字段，否则触发强制改密拦截。本工具已内置处理，第三方无需关心
• confirm 为受限权限：Bug 确认操作在部分账号权限组下被拒（禅道返回 user-deny），工具会返回可读错误指引授权
• Windows：npx 形式若连接超时，改用 install 子命令安装（自动全局安装 + node 直连，一条命令完成）
• 列表 total 可能虚高：服务端 total 统计含已删除记录，以 items 实际条数为准；无过滤分页附 deletedInPage（本页剔除的删除条数），过滤聚合附 scannedTotal 与 scanTruncated（命中扫描上限为 true，结果可能不完整）
• 附件/截图需经工具下载：file-read-{id}.{ext} 需登录态（浏览器匿名访问会 302 跳登录页），查看截图请使用 zentao_download_file（图片可 inline 直读）
• 不支持的模块：epics、requirements、testreports（404）、feedbacks（空响应）、tickets（403，视部署而定）

开发

npm install
npm run typecheck   # tsc 严格类型检查
npm run test        # node:test 单元测试（附件引用解析 / 分页终止判据等纯函数规则）
npm run build       # esbuild 打包单文件到 dist/server.js
npm run dev         # 直接以 type stripping 运行 src/server.ts（需 Node >= 23.6）

# 端到端验证：以 MCP stdio 协议连接 dist/server.js，对真实禅道服务器校验工具行为（需项目根目录 config.json）
node scripts/verify-e2e.ts

源码结构：

src/
├── server.ts         # MCP 协议（stdio JSON-RPC 2.0）+ 27 个工具定义
├── zentao-client.ts  # 禅道 REST v1 客户端 + Web 会话通道
└── zentao-utils.ts   # 附件引用解析 / 分页终止判据等纯函数（单测覆盖）
test/                 # node:test 单元测试
scripts/              # 开发脚本（verify-e2e.ts 端到端验证，不随 npm 包发布）

欢迎通过 Issue 与 Pull Request 参与贡献。

License

MIT