ZenTao Bugfix MCP stdio / 禅道 Bug 修复 MCP stdio

中文 | English

中文

zentao-bugfix-mcp 是面向 AI 辅助禅道 Bug 修复流程的本地 stdio MCP 包。它适用于 Codex、Cursor、Claude Code，以及所有能够启动子进程并通过 stdio 进行 MCP JSON-RPC 通信的 MCP 客户端。

当 AI 编码 Agent 需要读取禅道 Bug、查询从源码生成的 REST v1 API 元数据、下载附件，或执行受控 REST v1 调用时，使用这个包。实际的代码定位、文件修改、验证和提交仍然由调用方 Agent 在目标业务仓库中完成。

English

zentao-bugfix-mcp is the local stdio MCP package for AI-assisted ZenTao Bug fixing workflows. It is designed for local AI clients such as Codex, Cursor, Claude Code, and any MCP client that can start a subprocess and talk MCP JSON-RPC over stdio.

Use this package when an AI coding agent needs to read ZenTao Bugs, inspect source-derived REST v1 API metadata, download attachments, and perform controlled REST v1 calls while the actual code changes, verification, and commits happen in the target business repository.

能力概览

• stdio Server 当前注册 9 个 MCP tools。
• 从禅道 22.1 源码 catalog 出 142 条 REST v1 route。
• 其中 135 条已实现 REST v1 route 可通过 zentao_call_api 调用。
• 7 条 route 明确标记为缺 entry，调用时返回 API_ROUTE_NOT_IMPLEMENTED。
• catalog 中包含 221 个 HTTP method entry：101 个 GET、74 个 POST、22 个 PUT、24 个 DELETE。
• 已确认 REST 基路径为 ${ZENTAO_BASE_URL}/api.php/v1。
• API catalog 来源于禅道源码，不依赖页面演示文档或手写示例。

已注册工具

| Tool | 用途 | 写操作行为 | | --- | --- | --- | | zentao_health_check | 检查配置、catalog 状态、认证能力和写操作开关。 | 只读 | | zentao_get_workflow_guide | 读取内置工作流指南模块，包括 Bug 修复、API catalog 使用、附件和写操作规则。 | 只读 | | zentao_search_api | 查询本地 REST v1 catalog，不访问禅道服务。 | 只读 | | zentao_call_api | 调用 catalog 中已登记的禅道 REST v1 API，支持 path params、query、body 和 dry-run。 | 非 GET 真实调用需要 ZENTAO_ALLOW_ALL_REST_WRITE=true | | zentao_list_bugs | 按产品、项目或执行维度读取 Bug 列表，返回归一化摘要和原始响应。 | 只读 | | zentao_list_my_work | 读取当前登录用户的禅道“我的工作”列表，默认返回指派给当前用户的 Bug。 | 只读 | | zentao_get_bug | 读取单个 Bug 详情，返回归一化摘要和原始响应。 | 只读 | | zentao_download_file | 下载禅道附件到 ZENTAO_ATTACHMENT_DIR。 | 文件写入限制在附件目录 | | zentao_add_bug_comment | 准备 Bug 评论回写。当前 REST v1 catalog 中没有 /comments entry，因此保持 dry-run。 | 默认 dry-run |

架构设计

stdio 包刻意保持轻量，只负责本地进程入口和 MCP 传输；工具注册和禅道访问行为由 workspace 内共享包承载：

AI MCP client
  -> zentao-bugfix-mcp binary
  -> apps/mcp-stdio/src/main.ts
  -> @modelcontextprotocol/sdk StdioServerTransport
  -> @zentao-bugfix/mcp-tools
       createMcpServer()
       registerTools()
  -> @zentao-bugfix/zentao-core
       ReloadableZentaoRuntime
       ZentaoService
       ZentaoClient
       local REST v1 catalog
       workflow guide data
  -> ZenTao REST v1: ${ZENTAO_BASE_URL}/api.php/v1

包边界：

| 模块 | 位置 | 职责 | | --- | --- | --- | | stdio MCP 包 | apps/mcp-stdio | 发布到 npm 的包、CLI binary、stdio transport、smoke test | | MCP 工具注册 | packages/mcp-tools | MCP server 创建、工具 schema、安全结果信封、工具调用观察钩子 | | 禅道核心运行时 | packages/zentao-core | 配置加载、认证、REST v1 client、catalog 查询、归一化、附件处理、workflow guide 查询 | | REST v1 catalog 数据 | packages/zentao-core/data/zentao-api-v1-catalog.json | 从禅道 22.1 源码生成的 route 元数据 | | HTTP MCP Server | apps/mcp-http | 独立的 Streamable HTTP MCP 部署目标 | | Debug 和 Web UI | apps/debug-api、apps/web、apps/admin-web | 本地 REST explorer、开发调试 UI、在线后台管理 |

stdio Server 不直接实现业务代码修复。它向调用方 Agent 提供禅道上下文和受控 API 访问能力；调用方 Agent 负责在目标仓库中定位代码、修改文件、运行测试并提交变更。

安装与运行

使用 npx：

npx zentao-bugfix-mcp

全局安装：

npm install -g zentao-bugfix-mcp
zentao-bugfix-mcp

在当前 workspace 中开发运行：

pnpm install
pnpm build:stdio
node apps/mcp-stdio/bin/zentao-bugfix-mcp.js

只运行当前包：

pnpm --filter zentao-bugfix-mcp build
pnpm --filter zentao-bugfix-mcp start

MCP 客户端配置

全局安装后直接调用 bin：

{
  "mcpServers": {
    "zentao-bugfix": {
      "command": "zentao-bugfix-mcp",
      "env": {
        "ZENTAO_BASE_URL": "http://<zentao-host>",
        "ZENTAO_ACCOUNT": "<zentao-account>",
        "ZENTAO_PASSWORD": "<zentao-password>",
        "ZENTAO_TOKEN": "",
        "ZENTAO_ALLOW_ALL_REST_WRITE": "false"
      }
    }
  }
}

部分客户端（如 ccs）需要显式声明 type: "stdio"，并通过 npx 启动：

{
  "mcpServers": {
    "zentao-bugfix": {
      "type": "stdio",
      "command": "npx",
      "args": ["zentao-bugfix-mcp"],
      "env": {
        "ZENTAO_BASE_URL": "http://<zentao-host>",
        "ZENTAO_ACCOUNT": "<zentao-account>",
        "ZENTAO_PASSWORD": "<zentao-password>",
        "ZENTAO_TOKEN": "",
        "ZENTAO_ALLOW_ALL_REST_WRITE": "false"
      }
    }
  }
}

上面的示例面向当前内网开发测试环境。除非明确允许客户端执行真实非 GET REST 调用，否则不要在可信测试环境之外开启 ZENTAO_ALLOW_ALL_REST_WRITE。

本地源码开发时，先完成构建，再让客户端直接指向仓库内 binary：

{
  "mcpServers": {
    "zentao-bugfix": {
      "command": "node",
      "args": ["/Users/zoujunkun/study/zentao-bugfix-mcp/apps/mcp-stdio/bin/zentao-bugfix-mcp.js"],
      "env": {
        "ZENTAO_BASE_URL": "http://<zentao-host>",
        "ZENTAO_ACCOUNT": "<zentao-account>",
        "ZENTAO_PASSWORD": "<zentao-password>",
        "ZENTAO_TOKEN": "",
        "ZENTAO_ALLOW_ALL_REST_WRITE": "false"
      }
    }
  }
}

环境变量

| 变量 | 是否必需 | 用途 | | --- | --- | --- | | ZENTAO_BASE_URL | 是 | 禅道站点根路径。Server 会拼接 /api.php/v1。 | | ZENTAO_TOKEN | 否 | 已有禅道 REST token，优先使用。 | | ZENTAO_ACCOUNT | 否 | ZENTAO_TOKEN 为空时，用于换取 token 的账号。 | | ZENTAO_PASSWORD | 否 | 配合 ZENTAO_ACCOUNT 使用的密码。 | | ZENTAO_ALLOWED_PRODUCTS | 否 | 可选的产品维度读取白名单，逗号分隔。 | | ZENTAO_ALLOWED_PROJECTS | 否 | 可选的项目维度读取白名单，逗号分隔。 | | ZENTAO_ALLOWED_EXECUTIONS | 否 | 可选的执行维度读取白名单，逗号分隔。 | | ZENTAO_ALLOW_ALL_REST_WRITE | 否 | 允许 zentao_call_api 执行真实非 GET 调用。 | | ZENTAO_ATTACHMENT_DIR | 否 | 附件下载目录，默认 /tmp/zentao-bugfix-mcp。 |

认证顺序：

1. 如果提供了 ZENTAO_TOKEN，优先使用 token。
2. 否则使用 ZENTAO_ACCOUNT 和 ZENTAO_PASSWORD 调用 POST /api.php/v1/tokens 换取 token。

示例中的测试账号密码仅适用于当前内网开发测试环境。生产、个人或其他环境凭证不得写入已提交文档、日志或验收记录。

安全模型

默认设计是优先只读，并且所有通用 API 调用都受 catalog 约束：

• zentao_call_api 只能调用生成的 REST v1 catalog 中存在的 route。
• 默认允许 GET 调用。
• 认证用 POST /tokens 默认允许。
• 其他 POST、PUT、PATCH、DELETE 需要 ZENTAO_ALLOW_ALL_REST_WRITE=true。
• dryRun=true 只返回准备好的请求，不执行写入。
• 缺 entry 的 catalog route 返回 API_ROUTE_NOT_IMPLEMENTED，Server 不会静默退回 legacy endpoint。
• 附件下载限制在 ZENTAO_ATTACHMENT_DIR。
• Server 不默认解决 Bug、不默认关闭 Bug、不默认指派 Bug。

开发

在 workspace 根目录常用命令：

pnpm typecheck
pnpm build:stdio
pnpm smoke:mcp
pnpm pack:stdio

在当前包目录常用命令：

pnpm build
pnpm typecheck
pnpm smoke

smoke test 会启动构建后的 stdio Server，并通过 MCP 列出当前暴露的 tools。

相关文档

• Workspace README：../../README.md
• 部署说明：../../docs/DEPLOYMENT.md
• 开发规范：../../docs/DEVELOPMENT.md
• 工具契约：../../docs/TOOL_CONTRACT.md
• 自动生成的 REST v1 catalog 文档：../../docs/ZENTAO_API_V1.md