@zentao-hub/mcp

English | 简体中文

面向 禅道 20.x 开源版 的 Model Context Protocol 服务器，覆盖禅道 v1 REST API 的常用实体（产品 / 项目 / 计划 / 迭代 / 需求 / 任务 / Bug / 测试用例 / 构建 / 发布 / 代码库 / 用户 / 文档），加一个通用的 zentao_request 逃生口兜底未包装的端点。

想要 hub 目录、slash command、commit-msg hook 这些自动化协作工件，看姐妹包 @zentao-hub/cli。本包只做 MCP server 本身。

工具总览（129 个）

| 实体 | 工具 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 用户/部门 | whoami · list_users · get_user · list_departments · list_department_users | | 产品 | list_products · get_product · create_product · update_product · delete_product · list_product_branches · list_product_modules · list_product_plans · list_product_executions | | 项目 | list_projects · get_project · create_project · update_project · delete_project · list_project_executions · list_project_products | | 项目集 | list_programs · get_program · create_program · delete_program | | 执行/迭代 | list_executions · get_execution · create_execution · update_execution · delete_execution · start_execution · close_execution · list_execution_tasks · list_execution_stories · list_execution_team | | 需求 | list_product_stories · get_story · create_story · update_story · delete_story · change_story · review_story · close_story · activate_story · assign_story | | 任务 | get_task · list_my_tasks · create_task · update_task · delete_task · start_task · finish_task · pause_task · activate_task · close_task · cancel_task · assign_task | | Bug | list_my_bugs · list_product_bugs · list_execution_bugs · get_bug · create_bug · update_bug · delete_bug · resolve_bug · close_bug · confirm_bug · activate_bug · assign_bug · get_bug_history · download_bug_attachments | | 测试用例 | list_product_cases · get_case · create_case · update_case · delete_case · create_case_result · list_case_results · list_product_testsuites · list_product_testtasks | | 测试报告 | list_product_testreports · get_testreport · create_testreport · delete_testreport | | 构建 | list_product_builds · list_execution_builds · get_build · create_build · delete_build | | 发布 | list_product_releases · get_release · create_release · delete_release | | 代码库 | list_repos · get_repo · list_repo_branches · list_repo_commits | | 文档 | list_doclibs · list_doclib_docs · get_doc · create_doc · update_doc · delete_doc | | 工时(effort) | log_effort · list_efforts · update_effort · delete_effort | | 待办 | list_todos · get_todo · create_todo · update_todo · finish_todo · delete_todo | | 问题 | list_project_issues · get_issue · create_issue · update_issue · resolve_issue · close_issue · delete_issue | | 风险 | list_project_risks · get_risk · create_risk · update_risk · delete_risk | | 逃生口 | zentao_request — 任意 GET / POST / PUT / DELETE 到 /api.php/v1/...，覆盖没显式包装的端点 |

关于 product 作用域：禅道 v1 REST API 大多 bug / story / case / build / release 接口都按产品作用域。第一步通常先 list_products 拿 productId。

环境要求

• Node.js ≥ 18
• 一台开启了 v1 REST API 的禅道 20.x 实例，并能从本机访问
• 一个开发者账号（账号 / 密码），或一个已签发的 token

安装

一般用法不需要安装 —— MCP 客户端通过 npx -y @zentao-hub/mcp 启动， 首次运行会下载并缓存包。

若想启动更快或经常离线，可全局安装：

npm install -g @zentao-hub/mcp
# 或在 monorepo 内：从根目录 `pnpm install && pnpm run build`

全局安装会暴露 zentao-hub-mcp 可执行文件。

配置

推荐做法：通过姊妹 CLI @zentao-hub/cli 登录一次，MCP 服务自动读取：

npm install -g @zentao-hub/cli            # MCP server 本身用 npx 跑，不必装
zentao-hub profile login                         # 默认 profile
zentao-hub profile login --profile personal      # 多个禅道实例时再加一个
zentao-hub profile list                          # 列出 profile
zentao-hub profile use personal                  # 切换默认 profile

CLI 把 URL + 用户名 + token 存到 ~/zentao-hub/credentials.json（权限 0600）， 密码缓存在系统 keychain（macOS Keychain / Linux libsecret / Windows Credential Manager）。MCP server 在环境变量未设置时自动读取，token 过期时 用缓存密码静默续期。

环境变量

环境变量优先级高于凭据文件，CI/CD 场景仍可显式注入。

| 环境变量 | 何时使用 | 说明 | | ----------------------- | ------------------------------------- | -------------------------------------------------------------------- | | ZENTAO_PROFILE | 配置了多个 profile | 选用哪个 profile。默认使用文件中的 default，若只有 1 个 profile 直接用它。 | | ZENTAO_URL | 不使用凭据文件时 | 禅道地址，例如 https://zentao.example.com（结尾不要 /）。 | | ZENTAO_TOKEN | 与（用户名+密码）二选一 | 已签发的 token。此模式下自动续期关闭。 | | ZENTAO_USERNAME | 与密码同时提供 | 账号；启动时换取 token，401 时自动重新登录。 | | ZENTAO_PASSWORD | 与账号同时提供 | 密码。 | | ZENTAO_TIMEOUT_MS | 可选 | 单次请求超时，毫秒，默认 15000。 | | ZENTAO_HUB_CREDENTIALS| 可选 | 覆盖凭据文件路径（默认 ~/zentao-hub/credentials.json；老版本的 ~/.zentao-hub/credentials.json 会被自动识别）。 |

接入 MCP 客户端

@zentao-hub/mcp 是一个标准的 stdio MCP server，可接入任何 MCP-capable client。 姊妹 CLI 内置了主流 agent 的配置格式与位置，可一条命令注册：

npm install -g @zentao-hub/cli
zentao-hub profile login                  # 凭据缓存一次，所有 agent 共用
zentao-hub setup install --agent claude-code --no-workflows --no-instructions --no-hooks

| --agent | 对应工具 | 写入文件 | | ----------------- | --------------------- | ------------------------------------------------------------ | | claude-desktop | Claude Desktop | claude_desktop_config.json | | claude-code | Claude Code CLI | ~/.claude.json（user）或 <repo>/.mcp.json（workspace） | | codex-desktop | Codex Desktop | ~/.codex/config.toml（user）或 <repo>/.codex/config.toml | | codex-cli | Codex CLI | ~/.codex/config.toml（user）或 <repo>/.codex/config.toml | | copilot-local | GitHub Copilot Local | User/mcp.json（user）或 <repo>/.vscode/mcp.json | | copilot-cli | GitHub Copilot CLI | ~/.copilot/mcp-config.json（user）或 <repo>/.mcp.json |

其他 client（Cline、Continue、自研客户端等）手工编辑 config 即可——形如 command: "npx" + args: ["-y", "@zentao-hub/mcp"]。若已全局安装 @zentao-hub/mcp， 可改成 command: "zentao-hub-mcp" + args: []。

Claude Code / Claude Desktop — 使用 zentao-hub profile login

zentao-hub profile login 完成后 env 块完全可省略：

{
  "mcpServers": {
    "zentao-hub": {
      "command": "npx",
      "args": ["-y", "@zentao-hub/mcp"]
    }
  }
}

配置了多个 profile 时，给每个 MCP server 条目指定一个：

{
  "mcpServers": {
    "zentao-hub":          { "command": "npx", "args": ["-y", "@zentao-hub/mcp"] },
    "zentao-hub-personal": { "command": "npx", "args": ["-y", "@zentao-hub/mcp"], "env": { "ZENTAO_PROFILE": "personal" } }
  }
}

Claude Code / Claude Desktop — 纯环境变量（不依赖 CLI，例如 CI）

{
  "mcpServers": {
    "zentao-hub": {
      "command": "npx",
      "args": ["-y", "@zentao-hub/mcp"],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_USERNAME": "你的账号",
        "ZENTAO_PASSWORD": "你的密码"
      }
    }
  }
}

Claude Code CLI（纯环境变量示例）：

claude mcp add zentao-hub \
  --env ZENTAO_URL=https://zentao.example.com \
  --env ZENTAO_USERNAME=你的账号 \
  --env ZENTAO_PASSWORD=你的密码 \
  -- npx -y @zentao-hub/mcp

已经 npm install -g @zentao-hub/mcp？把上面例子里的 command: "npx" + args: ["-y", "@zentao-hub/mcp"] 换成 command: "zentao-hub-mcp"（或 -- zentao-hub-mcp），启动更快。 用 CLI 自动写：zentao-hub setup install --agent claude-code --command zentao-hub-mcp --no-workflows --no-instructions --no-hooks。

用法约定

• 列表工具默认 limit=20，最大 200。page 1-based。
• list_my_bugs / list_my_tasks 在服务端按 assignedTo.account == <当前账号> 过滤，绕开禅道 v1 不可靠的查询参数；扫描上限由 maxScan（默认 1000）控制，结果中 truncated 标记是否截断。
• 状态转移用专用动作工具（resolve_bug、finish_task、close_story …），而不是 update_* —— 禅道靠 /{entity}/{id}/{action} 端点驱动状态机和历史记录。update_* 只改字段，不触发状态变更。
• zentao_request 是逃生口：任何没典型 wrapper 的端点（自定义工作流、第三方扩展、新版本里新增端点）都可以直接调，例如：

  {"method": "GET", "path": "/products/27/testreports", "query": {"limit": 10}}

行为细节

• Token 自动刷新：任何工具收到 401 都会清掉缓存 token、重登一次、重试。仅 ZENTAO_TOKEN 模式（没账号密码可刷新）下 401 会原样抛回。
• 列表结构兼容：list 工具自动适配 {bugs:[...]} / {products:[...]} / {data:[...]} / {list:[...]} / 裸数组等多种禅道返回包装，并尽量提取 total。
• summary 字段裁剪：list 工具默认只回常用字段（id / title / status / assignedTo / openedDate …）。要全字段就用对应的 get_*。
• download_bug_attachments 还会解析 bug.steps 里的 <img src> 把内联截图也下载到 destDir/inline/，单个失败不中断。

开发

# 在 monorepo 根目录（使用 pnpm）
corepack enable
pnpm install
pnpm run build         # 全部构建
pnpm run dev           # 全部 watch

# 仅本包
pnpm --filter @zentao-hub/mcp run build

冒烟测试（不需要真实禅道实例）：

ZENTAO_URL=http://example.invalid ZENTAO_TOKEN=fake \
  node dist/index.js
# 通过 stdin 发 JSON-RPC `initialize` + `tools/list` 验证。

源码组织

src/
├── index.ts                    入口 + stdio transport + 工具注册
├── zentao-client.ts            HTTP 客户端：登录、token 刷新、超时、下载
└── tools/
    ├── index.ts                聚合 buildTools(client)
    ├── helpers.ts              共用 schema 片段、summary key 集合、JSON 提取
    ├── request.ts              zentao_request 逃生口
    ├── users.ts                whoami / users / departments
    ├── products.ts             products / branches / modules / plans
    ├── projects.ts             projects / project executions / project products
    ├── programs.ts             programs
    ├── executions.ts           executions + execution tasks/stories/team
    ├── stories.ts              stories CRUD + change/review/close/activate/assign/comment
    ├── tasks.ts                tasks CRUD + start/finish/pause/activate/close/cancel/assign/comment
    ├── bugs.ts                 bugs CRUD + resolve/close/confirm/activate/assign/comment/history/attachments
    ├── cases.ts                cases / test results / testsuites / testtasks
    ├── testreports.ts          test reports
    ├── builds.ts               product/execution builds
    ├── releases.ts             product releases
    ├── repos.ts                code repos + branches + commits
    ├── docs.ts                 doclibs / docs
    ├── efforts.ts              effort (work-hour) logs
    ├── todos.ts                personal todos
    ├── issues.ts               project issues
    └── risks.ts                project risks

加新工具：在对应实体模块里加一个 defineTool({ description, schema, handler })，然后会被 tools/index.ts 的 build*Tools(ctx) 自动带进来。

License

MIT © Deven Liu