ZenTao MCP Server (API V1.0)

ZenTao MCP Server (API V1.0)

基于 TypeScript + Node.js + @modelcontextprotocol/sdk 的禅道 MCP 服务，支持：

• 登录初始化（initZentao）
• 查看产品（getProducts）
• 查看我的 bug（getMyBugs）
• 查看 bug 详情（getBugDetail）
• 解决 bug（resolveBug）
• 激活 bug（activateBug，重新打开）

1. 环境准备

npm install
cp .env.example .env

请在 .env 中配置禅道地址与鉴权信息（推荐在运行时通过 initZentao 传入账号密码，不在文件中存明文）。

2. 从 npm / npx 运行（其它机器推荐）

npm 包名：@wudidada/zentao-mcp-server（作用域包；可执行命令 zentao-mcp-server）。

要求：Node.js >= 20。Linux/macOS 建议安装系统 curl（默认 HTTP 后端为 curl）。

2.1 命令行试跑

npx -y @wudidada/zentao-mcp-server

HTTP 模式示例：

MCP_TRANSPORT=http npx -y @wudidada/zentao-mcp-server

2.2 Cursor mcp.json（stdio + 环境变量）

在项目或用户目录下的 .cursor/mcp.json 中配置，例如：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@wudidada/zentao-mcp-server"],
      "env": {
        "ZENTAO_BASE_URL": "http://your-host/zentao/api.php/v1",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password",
        "ZENTAO_HTTP_BACKEND": "curl",
        "LOG_LEVEL": "info"
      }
    }
  }
}

修改配置后请完全重启 Cursor。也可将 args 中的包名改为固定版本，例如 @wudidada/[email protected]。

2.3 维护者：发布到 npm

npm run build
npm test
npm publish --access public

首次发布前需 npm login，并确保 package.json 中 version 未被占用。

源码仓库：https://github.com/wudidada/zentao-mcp-server

3. 启动方式

stdio（本地 IDE 首选）

npm run start:stdio

HTTP/SSE（远程接入）

npm run start:http

默认端口 3000，健康检查：

curl http://localhost:3000/healthz

4. 构建与测试

npm run build
npm test

5. MCP 工具参数说明

initZentao

• baseUrl?: string
• account: string
• password?: string
• token?: string

password 与 token 二选一。

getMyBugs

• status?: "active" | "resolved" | "closed" | "all"（默认 active）
• productId?: number

getBugDetail

• bugId: number

activateBug

• bugId: number
• assignedTo?: string（指派给，账号）
• openedBuild?: string | string[]（影响版本，文档为数组；不传则默认 ["trunk"]）
• comment?: string

resolveBug

• bugId: number
• resolution.resolution: "fixed" | "notrepro" | "duplicate" | "bydesign" | "willnotfix" | "tostory" | "external"
• resolution.resolvedBuild?: string（当解决方案为 fixed 时，服务端固定提交 trunk，忽略该字段，避免部分禅道网页端显示异常）
• resolution.duplicateBug?: number（当 resolution=duplicate 时必填）
• resolution.comment?: string

6. 安全与运维基线

• 日志默认对 password/token/authorization 做脱敏处理
• 默认请求超时 10s
• 查询接口（GET）支持指数退避重试
• HTTP 模式提供 /healthz 健康检查
• 若配置了 ZENTAO_BASE_URL + ZENTAO_ACCOUNT +（ZENTAO_PASSWORD 或 ZENTAO_TOKEN），进程启动时会自动登录，无需每次先调 initZentao
• ZENTAO_HTTP_BACKEND：axios 使用 Node 内置 HTTP；curl 调用系统 curl。在非 Windows 上默认 curl，用于规避部分禅道实例对「Node 客户端 + Token 头 + GET」长时间无响应的问题

6.1 环境变量一览

7. 项目结构

src/
  adapters/      # 禅道 API V1.0 适配层
  schemas/       # zod 参数校验
  server/        # stdio/http 双入口
  services/      # 领域服务
  tools/         # MCP 工具实现

8. 注意事项

• 当前实现按禅道 API V1.0 常见 REST 路径封装（/tokens、/bugs、/products）。
• 解决 Bug：官方 v1 接口为 POST /bugs/{id}/resolve（不是 PUT）。若误用 PUT，可能出现 HTTP 成功但禅道未真正更新状态的情况。
• 如果你的禅道实例路径或鉴权字段有差异，可在 src/adapters/zentaoApiV1.ts 适配。