# 禅道 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 查看权限。

调用示例：

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

自然语言示例：

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

## 一键安装向导

首次安装离线包后运行：

```bash
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 风险。

### 给项目组分发

维护者生成离线安装包：

```bash
pnpm install
pnpm test
pnpm pack
```

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

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

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

```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` 条目。

查看当前安装版本：

```bash
zentao-mcp -v
```

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

也可以直接使用 CLI：

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

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

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

```bash
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
地址缺少该参数会直接停止，且不会写入个人凭据或客户端配置。

如果只想跳过网络验证：

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

在独立项目目录中执行：

```bash
pnpm install
pnpm build
pnpm setup
```

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

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

```text
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`；需要回退时，用输出中列出的备份覆盖对应配置文件。

## 验证

```bash
pnpm test
pnpm type-check
```

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