zentao-84-mcp

适配禅道专业版 8.x（老版 session 鉴权 + path-info JSON 接口）的 MCP server。

针对禅道 17.x+ 写的 @orange29233/zentao-mcp 和 easysoft/zentao-cli 在 8.4 这种老版本上跑不通：

• 老版本没有 /api.php/v1/tokens v1 OAuth 接口
• 没有 RESTful API v2.0
• 登录需要 md5(md5(password) + rand) 加盐加密
• 所有 .json 端点的 content-type 都是 text/html

工具

只读工具

| 工具 | 说明 | 对应端点 | | --- | --- | --- | | list_my_bugs | 指派给当前用户的 Bug（跨产品） | /pro/my-bug.json | | get_bug | Bug 详情 | /pro/bug-view-{id}.json | | list_my_projects | 我参与的项目 | /pro/my-project.json | | list_my_tasks | 指派给我的任务 | /pro/my-task.json | | list_bugs | 按产品/模块 + 预设视图浏览 Bug，支持客户端二次过滤 | /pro/bug-browse-{pid}-0-{view}.json |

写入工具（⚠️ 改变禅道状态）

| 工具 | 说明 | 前置检查 | 对应端点 | | --- | --- | --- | --- | | resolve_bug | 解决 Bug | 状态 ≠ resolved/closed | POST /pro/bug-resolve-{id}.json | | confirm_bug | 确认 Bug（开发接手）| confirmed === 0 | POST /pro/bug-confirmBug-{id}.json | | assign_bug | 重新指派 | 目标 ≠ 当前 assignedTo | POST /pro/bug-assignTo-{id}.json | | close_bug | 关闭 Bug | 状态 === resolved | POST /pro/bug-close-{id}.json |

所有写工具都先 GET 拿 before 快照，POST 后再 GET 拿 after 快照，返回 diff 表格 + ✅/⚠️ 验证标记。响应是禅道的 JS 重定向 HTML（不是 JSON），代码里通过抓 alert('xxx') 检测错误。

Comment 字段：禅道 8.4 这台环境 action.comment 和 bug.update 权限被禁，独立 comment 工具走不通；comment 作为参数嵌进 resolve/confirm/assign/close 四个工具，所有操作都会在 bug action 历史里追加一条记录。

list_bugs 视图常量

unclosed(默认) unResolved assignToMe resolvedByMe toClosed longLifeBugs unconfirmed postponedBugs overdueBugs all

list_bugs 客户端过滤参数

severity(1-4) status(active/resolved/closed) assignedTo openedBy since(YYYY-MM-DD) until(YYYY-MM-DD) limit

限制

• 8.4 服务端忽略分页参数（pageID/recPerPage），单次请求最多 20 条，但 recTotal 准确反映总数
• productId 未指定时禅道会选默认产品（通常非用户期望），工具会输出警告并显示当前所选产品名

环境变量

| 变量 | 必填 | 说明 | | --- | --- | --- | | ZENTAO_URL | ✓ | 禅道根 URL（不含 /pro/），如 http://10.200.5.57 | | ZENTAO_USERNAME | ✓ | 账号（也可叫 ZENTAO_ACCOUNT） | | ZENTAO_PASSWORD | ✓ | 明文密码，代码内部会做 md5+rand 加密 | | ZENTAO_BASE_PATH | ✗ | URL 基础路径，默认 /pro（专业版）；开源版可改为空串 |

把上面 4 个变量 export 进 ~/.zshrc：

# Zentao MCP credentials
export ZENTAO_URL="http://你的禅道地址"
export ZENTAO_USERNAME="你的账号"
export ZENTAO_PASSWORD="你的密码"

然后 source ~/.zshrc。

安装

假设你已经把仓库克隆/解压到 $HOME/zentao-84-mcp：

cd ~/zentao-84-mcp
npm install
# 验证启动
node test-stdio.mjs list

接入 Claude Code

claude mcp add zentao -s user \
  -e 'ZENTAO_URL=${ZENTAO_URL}' \
  -e 'ZENTAO_USERNAME=${ZENTAO_USERNAME}' \
  -e 'ZENTAO_PASSWORD=${ZENTAO_PASSWORD}' \
  -- node "$HOME/zentao-84-mcp/src/index.mjs"

${ZENTAO_URL} 这种占位 Claude Code 会在启动 MCP 子进程时延迟替换；前提是启动 claude 的那个 shell 已经 source 过 .zshrc。验证：claude mcp list | grep zentao，看到 ✓ Connected 即成功。

接入 Codex CLI

codex mcp add zentao \
  --env "ZENTAO_URL=$ZENTAO_URL" \
  --env "ZENTAO_USERNAME=$ZENTAO_USERNAME" \
  --env "ZENTAO_PASSWORD=$ZENTAO_PASSWORD" \
  -- node "$HOME/zentao-84-mcp/src/index.mjs"

注意 Codex 用 --env（不是 -e），且这里用双引号让 shell 立刻展开变量写入 ~/.codex/config.toml（Codex 不支持 ${VAR} 延迟替换）。验证：codex mcp list。

分发给同事

代码本身不含任何禅道 URL/账号/密码，可放心分发。

最快：npm pack 生成 tgz 发给同事；同事 mkdir ~/zentao-84-mcp && tar -xzf zentao-84-mcp-*.tgz -C ~/zentao-84-mcp --strip-components=1 && cd ~/zentao-84-mcp && npm install，然后按上面"接入"步骤走。

团队级：推到公司内部 Git，同事 git clone + npm install。

本地调试

node test-stdio.mjs list                       # 列工具
node test-stdio.mjs list_my_bugs               # 跑工具
node test-stdio.mjs get_bug '{"bugId":240252}'
node test-stdio.mjs list_bugs '{"view":"unclosed","productId":70,"severity":2}'