禅道 MCP

这个服务把禅道 REST API 暴露为 MCP 工具，支持只读查询，以及经用户明确确认后解决 Bug。

工具

• zentao_list_bugs：分页查询 Bug。默认查询指派给当前 MCP 账号的 Bug；用户说“全部/所有 Bug”时传入 scope=all。
• zentao_search_bugs：按标题关键词搜索 Bug，默认只搜索指派给当前 MCP 账号的 Bug。
• zentao_get_bug：读取指定 Bug 的完整详情，并默认通过 REST API 下载描述中的截图，以 MCP 图片内容返回。
• zentao_list_products：读取当前账号可见的产品列表，获得产品 Bug 查询所需的 productId。
• zentao_resolve_bug：把 Bug 标记为 fixed，并自动指派回提 Bug 的人。该工具是写操作，必须传入 confirm=true。

解决 Bug 时默认使用主干 trunk 作为解决版本；如果团队按构建管理版本，请传入具体的构建 ID。工具会先读取 Bug 的创建人账号，再调用禅道 /bugs/{id}/resolve 接口，并显式把 assignedTo 设置为创建人。已达到目标状态的 Bug 不会重复写入，已关闭 Bug 会被拒绝修改。

读取 Bug 时默认返回最多 5 张截图，可通过 maxImages 调整为 1 到 10 张，或设置 includeImages=false 只读取文本详情。截图优先根据禅道的 file-read-<id> 地址或图片附件 ID 使用 /files/{id} 下载，不依赖浏览器 Cookie。单张截图限制为 5 MiB，单次调用的截图总量限制为 15 MiB；某张图片下载失败时仍会返回 Bug 详情，并在 imageSummary.failures 中说明原因。

禅道官方 v1 文档的产品 Bug 列表接口是 /products/{productId}/bugs。建议先调用 zentao_list_products，再把产品 ID 传给 zentao_list_bugs 或 zentao_search_bugs；当前实例也保留了 无产品 ID 的全局 /bugs 尝试，若该部署返回 404，工具会提示改用产品 ID。

认证方式

服务启动后的第一次查询会使用账号密码调用禅道的 POST /api.php/v1/tokens 自动认证，并只在当前进程内 缓存临时凭据；遇到 401 时会自动重新认证。密码不会写入 MCP 响应或日志。

账号和密码属于敏感凭据，不要提交到 Git、聊天记录或共享配置文件。项目组成员应使用自己的禅道账号， 并确保账号至少拥有 Bug 查看权限。

调用示例：

{"name":"zentao_list_bugs","arguments":{"scope":"all","productId":51}}
{"name":"zentao_list_bugs","arguments":{"scope":"assigned_to_me","productId":51}}

自然语言示例：

查产品 51 下我账号的 Bug
查指派给我的 Bug，关键词是“导出”
查产品 51 的全部 Bug
Bug 39766 已修复，解决版本是构建 12，备注“已修复并完成自测”，请标记已解决并指回提 Bug 的人

一键安装向导

首次安装离线包后运行：

zentao-mcp setup

交互向导支持：

• ↑ / ↓：移动选项
• 空格：勾选或取消 Codex、Claude、Cursor 等客户端
• 回车：确认并进入下一步
• Ctrl+C：安全取消，不写入后续配置

如果已经存在个人配置，setup 会先询问安装方式：

• 使用现有配置快速更新（推荐）：沿用地址、账号和密码，只检查并更新原来已配置的客户端。
• 重新运行完整配置向导：重新选择客户端，并可修改地址、账号和密码。

非交互模式检测到现有配置时默认快速更新；确实需要从环境变量重建配置时增加 --reconfigure。

普通终端不支持可靠的鼠标点击；需要鼠标操作时要另行提供桌面或网页安装器。

在本项目目录中开发时，先执行 pnpm install && pnpm build，再运行 pnpm setup。 向导会提示输入禅道地址、账号和密码，验证连接、保存个人配置，并自动写入检测到的 Codex、Claude Desktop、Claude Code 和 Cursor 配置。配置完成后完全重启对应客户端即可。

当前公司的禅道地址使用 HTTP。HTTP 无法加密账号密码：交互向导会显示风险，并要求输入 y 后按回车继续。 优先建议为禅道启用 HTTPS；只有确认当前网络环境可信时才接受 HTTP 风险。

给项目组分发

维护者生成离线安装包：

pnpm install
pnpm test
pnpm pack

把生成的 tianjin-library-zentao-mcp-<版本>.tgz 放到 GitLab Release 或项目组共享目录。成员安装并运行向导：

npm install -g ./tianjin-library-zentao-mcp-0.4.0.tgz && zentao-mcp setup

这是一条连续命令：安装成功后立即进入向导，同时避免使用容易卡住 CI/IDE 安装的 npm postinstall。 Windows PowerShell 使用：

npm install -g .\tianjin-library-zentao-mcp-0.4.0.tgz
if ($LASTEXITCODE -eq 0) { zentao-mcp setup }

成员更新时安装新的 .tgz 后重新运行 zentao-mcp setup，选择默认的“使用现有配置快速更新”即可，不会再次 询问禅道地址、账号或密码。安装器会保留其他 MCP、备份发生变化的客户端配置并幂等更新 zentao 条目。

查看当前安装版本：

zentao-mcp -v

同时支持 zentao-mcp --version、zentao-mcp -version 和 zentao-mcp version。

也可以直接使用 CLI：

node dist/cli.js setup
node dist/cli.js doctor --allow-insecure-http

上述 doctor 示例针对当前 HTTP 禅道；HTTPS 地址无需风险参数。安装向导生成的客户端配置会根据地址自动附加 所需参数。直接用环境变量运行 doctor 或 serve 时，HTTP 地址同样必须显式传入 --allow-insecure-http。

非交互安装（账号密码从当前环境变量读取）：

ZENTAO_BASE_URL=http://106.75.28.240:31080/zentao \
ZENTAO_ACCOUNT=你的账号 ZENTAO_PASSWORD=你的密码 \
  zentao-mcp setup --non-interactive --allow-insecure-http \
  --clients codex,claude-desktop

--allow-insecure-http 只表示明确接受 HTTP 明文传输风险；HTTPS 地址不需要该参数。非交互模式下，HTTP 地址缺少该参数会直接停止，且不会写入个人凭据或客户端配置。

如果只想跳过网络验证：

node dist/cli.js setup --skip-check --clients codex

在独立项目目录中执行：

pnpm install
pnpm build
pnpm setup

测试只使用 TypeScript 编译器和 Node.js 内置测试运行器，不需要额外的运行时转译器。

安装向导保存的个人配置默认位于：

macOS/Linux: ~/.config/zentao-mcp/profile.json
Windows:     %APPDATA%\\zentao-mcp\\profile.json

配置文件包含账号密码，安装向导会将其权限设置为仅当前用户可读。不要提交到 Git 或发送给其他人。

• macOS/Linux：新建的配置目录使用 0700，配置文件使用 0600；已有目录权限保持不变。
• Windows：配置保存在当前用户的 %APPDATA%，权限继承该用户目录的 ACL；请勿放入共享目录。

仅在源码开发场景下，可以复制 .env.example 为 .env.local。HTTPS 地址可通过 pnpm start:local 启动； HTTP 地址使用 pnpm start:local -- --allow-insecure-http。 安装向导不会读取 .env.local；它使用交互输入，或在 --non-interactive 模式下读取当前进程环境变量。

接入 MCP 客户端

通常无需手工配置。确有需要时，可复制 mcp-config.example.json，把 Node、CLI 和个人配置路径改为本机 绝对路径，再添加到客户端 MCP 配置。客户端配置只引用个人配置文件，绝不能直接包含账号密码。

安装器会保留其他 MCP，并在修改已有客户端配置前生成带时间戳的 .zentao-mcp.<时间>.bak 备份。若多客户端 配置中途失败，修正报错后可直接重跑 zentao-mcp setup；需要回退时，用输出中列出的备份覆盖对应配置文件。

验证

pnpm test
pnpm type-check

服务使用 Node.js 20 自带的 fetch，不依赖浏览器登录会话。禅道 API 错误只返回状态和通用提示，避免把 账号、密码或临时认证凭据泄露给模型。