{"_id":"@cqjjb/zentao-mcp-server","_rev":"2-0dcac69d08f95051d135d02f2d72d73a","name":"@cqjjb/zentao-mcp-server","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@cqjjb/zentao-mcp-server","version":"1.0.0","keywords":["mcp","zentao","禅道","bug","zentaosid","mcp-server"],"license":"MIT","_id":"@cqjjb/zentao-mcp-server@1.0.0","maintainers":[{"name":"cqjjb","email":"995934055@qq.com"}],"bin":{"zentao-mcp-server":"dist/index.js"},"dist":{"shasum":"a9635e4c110dacf489ecf56f25236f3ce0447e60","tarball":"https://registry.npmjs.org/@cqjjb/zentao-mcp-server/-/zentao-mcp-server-1.0.0.tgz","fileCount":6,"integrity":"sha512-dBOAGKXXfRv/nKJfbPLlx1LPzeGRHZqVezzx/5GtVRGmk4W5TlAyX8h1CV0q6HrdiT20cQvL9iDQQe2Ejt4ghg==","signatures":[{"sig":"MEUCIQCgzdFveY3u9gq2uYggtYzCy1KpDh0L2DHAmcDNRMmeqQIgQW71Elka3dySYsIej0YAclj/VZfy3Kl+GpD8g3pDBbg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":54460},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"d648d74196b9052ce21f428efa954188619ef383","scripts":{"dev":"tsx src/index.ts","test":"node scripts/e2e.mjs","build":"tsc -p tsconfig.json","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"cqjjb","email":"995934055@qq.com"},"repository":{"url":"git+http://192.168.1.242:10985/jjb/ai-agent/mcp/zentao-mcp-server.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for ZenTao 12.x: auto-login (zentaosid session + form submission) and full bug lifecycle (list/detail/edit/assign/resolve/close/activate/comment) + attachments","directories":{},"_nodeVersion":"22.19.0","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/zentao-mcp-server_1.0.0_1788510893820_0.6878908061151625","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@cqjjb/zentao-mcp-server","version":"2.0.0","description":"MCP server for ZenTao 12.x: auto-login (zentaosid session + form submission) and full bug lifecycle (list/detail/edit/assign/resolve/close/activate/comment) + attachments","type":"module","bin":{"zentao-mcp-server":"dist/index.js"},"main":"dist/index.js","scripts":{"build":"tsc -p tsconfig.json","dev":"tsx src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit","test":"node scripts/e2e.mjs"},"engines":{"node":">=18"},"keywords":["mcp","zentao","禅道","bug","zentaosid","mcp-server"],"license":"MIT","repository":{"type":"git","url":"git+http://192.168.1.242:10985/jjb/ai-agent/mcp/zentao-mcp-server.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.0","tsx":"^4.19.0","typescript":"^5.7.0"},"_id":"@cqjjb/zentao-mcp-server@2.0.0","gitHead":"9e59425ac3905641a39dbf3206266c4c6d94e2dd","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-uzuPTlSw8vTpvcAeM2X4SI447toft1+V0F3ylftuizTKL6PNt5PRzun3A7LSNdsW29SndkNZQ90P3ThezrTRUA==","shasum":"497eaf93edc863818d1c51fc27b0297cef6c7276","tarball":"https://registry.npmjs.org/@cqjjb/zentao-mcp-server/-/zentao-mcp-server-2.0.0.tgz","fileCount":6,"unpackedSize":60762,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIECe+xF2IR7GejmUL0Mphxji+e6h2Hd0LN8sixwodPDxAiEA0W4iLirzfD0CU65M5tRymha/tHV9KkrNsz8zTALxyrw="}]},"_npmUser":{"name":"cqjjb","email":"995934055@qq.com"},"directories":{},"maintainers":[{"name":"cqjjb","email":"995934055@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zentao-mcp-server_2.0.0_1788745208908_0.28489605973662036"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-04T08:34:53.657Z","modified":"2026-09-07T01:40:09.273Z","1.0.0":"2026-09-04T08:34:53.992Z","2.0.0":"2026-09-07T01:40:09.110Z"},"license":"MIT","keywords":["mcp","zentao","禅道","bug","zentaosid","mcp-server"],"repository":{"type":"git","url":"git+http://192.168.1.242:10985/jjb/ai-agent/mcp/zentao-mcp-server.git"},"description":"MCP server for ZenTao 12.x: auto-login (zentaosid session + form submission) and full bug lifecycle (list/detail/edit/assign/resolve/close/activate/comment) + attachments","maintainers":[{"name":"cqjjb","email":"995934055@qq.com"}],"readme":"# 禅道 MCP Server\n\n让 AI（Claude / Cursor / Codex 等）**自动管理禅道 Bug**：读取列表与详情、创建、编辑、指派、解决、关闭、激活、评论——全流程自动化，无需人工操作浏览器。\n\n> 本项目针对 **禅道 12.x（开源版 12.3.1）** 真机开发与验证。\n> 禅道 16.0+ 才提供 RESTful token 接口；本实现采用禅道官方推荐的 **`zentaosid` 会话 + 表单提交** 方式，12.x 全兼容。\n\n---\n\n## ✨ 功能特性\n\n- **自动登录**：`zentaosid 会话 + md5(md5(密码)+盐) 加密`，与浏览器登录完全一致，无需验证码交互\n- **会话自管理**：内存缓存会话，掉线/过期自动重登并重试，AI 全程无感\n- **12 个工具**：覆盖 Bug 全生命周期\n- **写操作安全校验**：指派/解决后自动回读校验状态，防止\"假成功\"\n- **人员解析**：支持中文姓名 ↔ 禅道账号自动互转，指派对象必须在用户列表中校验存在\n- **自检工具**：`zentao_self_test` 一键验证连接与权限\n\n## 📦 安装与构建\n\n```bash\nnpm install\nnpm run build        # 编译到 dist/\nnpm run dev          # tsx 直接运行（开发）\n```\n\n## 🔧 配置（环境变量）\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `ZENTAO_BASE_URL` | `http://192.168.1.252/zentao` | 禅道地址（注意带 `/zentao` 前缀） |\n| `ZENTAO_ACCOUNT` | 无 | 禅道账号（必填） |\n| `ZENTAO_PASSWORD` | 无 | 禅道密码（必填） |\n| `ZENTAO_TIMEOUT_MS` | `15000` | 请求超时毫秒 |\n\n```bash\n# .env（或直接 export / 客户端配置 env）\nZENTAO_BASE_URL=http://192.168.1.252/zentao\nZENTAO_ACCOUNT=你的账号\nZENTAO_PASSWORD=你的密码\n```\n\n## 🚀 接入 MCP 客户端\n\n**Claude Desktop**（`claude_desktop_config.json`）:\n\n```json\n{\n  \"mcpServers\": {\n    \"zentao\": {\n      \"command\": \"node\",\n      \"args\": [\"D:\\\\workspace\\\\mcp\\\\zentao-mcp-server\\\\dist\\\\index.js\"],\n      \"env\": {\n        \"ZENTAO_BASE_URL\": \"http://192.168.1.252/zentao\",\n        \"ZENTAO_ACCOUNT\": \"这里填账号\",\n        \"ZENTAO_PASSWORD\": \"这里填密码\"\n      }\n    }\n  }\n}\n```\n\n**Cursor**（`.cursor/mcp.json`）:\n\n```json\n{\n  \"mcpServers\": {\n    \"zentao\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/zentao-mcp-server/dist/index.js\"],\n      \"env\": { \"ZENTAO_BASE_URL\": \"http://192.168.1.252/zentao\", \"ZENTAO_ACCOUNT\": \"...\", \"ZENTAO_PASSWORD\": \"...\" }\n    }\n  }\n}\n```\n\n## 🔨 工具清单（暴露给 AI）\n\n| 工具 | 作用 |\n|---|---|\n| `zentao_self_test` | 连接自检（登录、产品、bug 列表） |\n| `zentao_list_products` | 产品列表 |\n| `zentao_list_users` | 可指派人员列表（账号+姓名） |\n| `zentao_my_bugs` | 「我的地盘」bug 列表（默认指派给我，可切我创建/解决/关闭；跨产品，与 my-bug.html 一致） |\n| `zentao_product_bugs` | 按产品查 bug（必填 productId；支持标题关键字检索，产品内全量翻页） |\n| `zentao_get_bug` | Bug 详情（含历史记录 + 附件清单与可读性标注） |\n| `zentao_list_attachments` | 列出 Bug 全部附件（步骤/评论内嵌图 + 附件区正式附件），逐条标注类型与可读性 |\n| `zentao_download_attachment` | 下载附件到本地（白名单见下；白名单外明确拒绝并告知 AI 处理建议） |\n| `zentao_update_bug` | 编辑 Bug |\n| `zentao_assign_bug` | 指派 Bug |\n| `zentao_resolve_bug` | 解决 Bug |\n| `zentao_close_bug` | 关闭 Bug |\n| `zentao_activate_bug` | 激活（重新打开）Bug |\n| `zentao_add_comment` | 添加评论 |\n\n## 📎 附件读取边界（重要）\n\nMCP 只能**读取**以下类型的附件，其余类型会**显式告知 AI 不可读取并拒绝下载**（不会静默失败）：\n\n| 类型 | 扩展名 | 读取方式 |\n|---|---|---|\n| 🖼️ 图片 | `png / jpg / jpeg / gif / webp / bmp` | `zentao_download_attachment` 下载 → `read_image` 查看 |\n| 📄 文本 | `md / txt / csv / log / json / xml / svg` | `zentao_download_attachment` 下载 → `read` 查看 |\n| 🚫 其他 | `docx / xlsx / pdf / zip / rar / 音视频…` | **不可读取**：清单标注\"🚫 不可读取+原因+建议\"，下载工具直接拒绝 |\n\n- 附件提取来源：复现步骤内嵌图、历史/评论富文本内嵌图、附件区正式附件（`file-read-{id}.{ext}` / `file-download-{id}` 全量扫描）\n- 单文件 > 10MB 拒绝下载\n- 遇白名单外附件，AI 应**告知用户**（\"该附件类型不支持读取，请人工查看或转成图片/文本后重新上传\"），而不是猜测内容\n\n## ⚠️ 安全规则（重要）\n\n1. **指派必须询问用户**：AI 调用 `zentao_assign_bug` 前，必须先用 `zentao_list_users` 获取候选，并**向用户明确询问指派给谁**；用户未明确指定时禁止执行。\n2. 解决 Bug 默认把 bug 指派给当前指派人；如需改派必须先经用户确认。\n3. 所有写操作后自动回读校验，失败即报错，不静默。\n4. **无创建/删除功能**：创建与删除 Bug 由人工在禅道页面上完成，MCP 不暴露（避免 AI 误建/误删）。\n\n## 🔄 完整工作流示例\n\n```\n用户：「把我创建的未关闭 bug 都列出来」\n  → zentao_my_bugs(browseType=openedbyme)\n用户：「查一下产品 81 全员培训里标题带『题库』的 bug」\n  → zentao_product_bugs(productId=81, keywords=题库)\n用户：「#37813 解决掉，指派给陈春位」\n  → AI 调用 zentao_list_users(37813) 确认候选 → 向用户确认「确认指派给陈春位？」→ 用户确认\n  → zentao_resolve_bug(37813, resolution=fixed, assignedTo=陈春位, comment=...)\n```\n\n## 🧪 真机验证（本项目已对 192.168.1.252 完成验证）\n\n```bash\n# 只读链路\nZENTAO_ACCOUNT=xxx ZENTAO_PASSWORD=xxx node scripts/e2e.mjs\n# 写操作链路（会在测试 bug 上真实执行）\nZENTAO_ACCOUNT=xxx ZENTAO_PASSWORD=xxx TEST_BUG_ID=37813 node scripts/e2e-write.mjs\n```\n\n## 📝 已知限制（禅道 12.3.1）\n\n- 无 RESTful API，采用会话+表单方式（已稳定验证）\n- `action-comment` 独立评论接口受账号权限控制；被拒时自动降级为「无改动编辑 + 备注」方式记录评论（同样进入历史记录）\n- 部分账号（如本测试账号）无用户管理权限，人员列表从指派表单动态获取\n\n## 📁 项目结构\n\n```\nsrc/\n├── index.ts              # MCP Server 入口\n├── config.ts             # 环境变量配置\n├── zentao-client.ts      # 核心客户端（登录/会话/请求/重登）\n└── tools/bug-tools.ts    # 12 个工具实现\nscripts/\n├── e2e.mjs               # 读链路端到端测试\n└── e2e-write.mjs         # 写链路端到端测试\n```\n","readmeFilename":"README.md"}