文章首发于: https://feinterview.poetries.top/blog/ai-agent-zentao-bug-mcp-integration
用一份自建
MCP Server把禅道 bug 流程接入Claude/Cursor/Codex，文章配套完整的分步落地方案：5 分钟跑通最小版本、关键模块代码、Token缓存、多形态 bug 列表回退、截图落档与归档SKILL，照着做就能把团队的禅道 bug 流程接到 AI Agent 上。
在本篇文章中，我们将从浅入深，和大家一起学习以下知识：
- 为什么不要让 AI Agent 直接「裸调」禅道 REST API
- 用
Node.js 18+实现一份纯stdio的MCP Server的完整步骤 - Token 缓存、HTTPS 强约束、相对路径白名单等安全护栏
- 「我的 bug / 产品 bug / 项目集 bug」三种视角的回退策略
- bug 详情里 HTML 描述、内嵌截图、动态时间线的解析与脱敏裁剪
- 配套
SKILL把 bug 上下文按日期 + 经办人沉淀到本地工作目录 - 生产环境上线前的安全 checklist
# 痛点与解决方案
在一些以禅道（ZenTao）为唯一 bug 平台的团队里，常见的协作节奏是：测试在禅道里提 bug → 开发翻邮件或 IM 提醒 → 进禅道复制描述、下载截图、看历史动态 → 拉本地分支修 → 回禅道点「解决」并写说明。这个流程的核心矛盾不在禅道本身，而在「bug 上下文是网页里的活数据，AI Agent 看不见」：你让 Cursor / Claude 帮你定位代码，它最多看到你贴过来的一段标题，没法读到内嵌截图、字段编辑历史、上一次评审意见。
解决方法是把禅道 RESTful API 包成一份只暴露最小工具集的 MCP Server，加一份配套 SKILL 让 Agent 主动把 bug 落到本地工作底稿。下面会给出一份从 0 到 1 的完整落地步骤，你照着走就能让团队的 AI Agent 接入禅道。
# 一、整体架构
整套系统是「Agent ↔ MCP Server ↔ 禅道 REST API」三段式：
┌─────────────┐ stdio ┌──────────────────┐ HTTPS ┌────────────────┐
│ Claude / │ ◄────────► │ zentao-mcp- │ ◄────────► │ 禅道实例 │
│ Cursor / │ JSON-RPC │ server (Node) │ Token │ /api.php/v1 │
│ Codex │ │ (10 个工具) │ │ │
└─────────────┘ └──────────────────┘ └────────────────┘
│ │ │
│ ▼ │
│ ┌───────────────┐ │
└────────────────► │ bugfix/<date> │ ◄──── 落档 SKILL │
│ /bug-N-... │ 按日期 + 经办人归档 │
└───────────────┘ │
@前端进阶之旅: 代码已经复制到剪贴板
三处选型说明：
- 要求
Node.js 18+：直接用内置fetch+AbortController，省掉node-fetch这类依赖，发布包体积小、攻击面小。 stdio而非HTTP：MCP 客户端把进程 stdin/stdout 接到协议层，Server 不监听端口，省掉鉴权、CORS、TLS 这些自找的麻烦。- 不在仓库里存密钥：所有凭证只从环境变量读，配套
.env.example；连默认日志都做了字段脱敏。
# 二、五分钟跑通最小可用版本
下面是一份照抄就能跑的最小路径，先把链路打通，再做下一步优化。
# Step 1 准备禅道实例信息
向运维 / DBA 拿到三样东西并验证：
# 1. 禅道访问入口（必须 HTTPS）
ZENTAO_BASE_URL="https://zentao.example.com"
# 2. 一个最小权限的服务账号（强烈不要用管理员账号）
ZENTAO_ACCOUNT="bot_account"
ZENTAO_PASSWORD="<from-vault>"
# 3. 验证 token 接口是否通
