@znmin/zentao-mcp-server

你自己维护的禅道 MCP Server，支持 npx 启动、账号密码自动换取 Token，以及完整 Bug 工作流。 基于 @aipper/zentao-mcp-server@0.1.26 的 MIT 代码维护，保留 12 个工具和已有环境变量，便于迁移。

快速接入

需要 Node.js 20 或以上。MCP 客户端配置：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@znmin/zentao-mcp-server@1.0.0"],
      "env": {
        "ZENTAO_BASE_URL": "https://zentao.example.com",
        "ZENTAO_ACCOUNT": "your-account",
        "ZENTAO_PASSWORD": "your-password"
      }
    }
  }
}

如果使用内网 HTTP，另外设置 ZENTAO_ALLOW_INSECURE_HTTP=true。 Windows 客户端无法直接找到 npx 时，使用 command: "cmd"， args: ["/d", "/c", "npx", "-y", "@znmin/zentao-mcp-server@1.0.0"]。

从上游迁移：只需将启动包名从 @aipper/zentao-mcp-server 改为本包，保留现有 ZENTAO_* 配置。 服务端和 CLI 不需要安装到禅道服务器上；MCP 运行在 Agent Runtime 所在电脑，附件路径也是该电脑上的路径。 本包使用 stdio，不是远程 HTTP MCP 服务。

Related MCP server: ZenTao MCP Server

附件修复与支持范围

Bug 查询和处理使用 REST v1（禅道 16.5+）。附件上传采用禅道 22.0+ REST v2 官方接口：

POST /api.php/v2/files
multipart/form-data:
  file       = 文件
  objectType = bug
  objectID   = Bug ID

这避免了上游 ${baseUrl}index.php 缺少斜杠的问题，也不再依赖网页上传和额外的 /bugs/{id}/files 关联接口。 支持根目录和子目录部署，例如 https://example.com/zentao；保留部署路径前缀。

上传前先读取 Bug 确认访问权限，上传后再回读 Bug 的 files 确认文件 ID 已关联。 结果包含 fileId、uploaded、linked 和 verified；只有回读确认后才返回 verified: true。 如果上传已成功但关联未确认，会返回 MCP isError: true，同时保留文件 ID 和 doNotRetryUpload: true。 请人工检查附件列表，不要盲目重传。超时也不自动重试，避免重复附件。

对于低于 22.0 的禅道版本，本包不自动尝试未经验证的网页上传方式。 如企业版或定制版调整了上传入口，可设置 ZENTAO_UPLOAD_PATH，但该接口必须接受相同的 REST v2 字段并直接关联对象。

工具

upload_attachment 参数：bugId（正整数）、filePath（运行电脑上的绝对路径），可选 fileName。 get_bug_detail / get_bug_actions 参数：id。 download_attachment 参数：fileId、savePath。

解决和备注沿用上游的结构化说明：solutionModules 包含 rootCause（根因）、fixApproach（修复思路）、 logicChange（改动逻辑）、impact（影响范围）。resolve_bug 默认解决版本为 trunk，可通过参数或环境变量覆盖。 解决 Bug 是写操作；请只在用户授权完成对应工作时执行。

环境变量

程序读取 MCP 客户端传入的环境变量，不自动加载 .env。密码、Token 不要提交到仓库。 读写能力还取决于禅道账号本身的产品、项目及操作权限；只读开关不会提升账号权限。

开发与发布

npm ci --ignore-scripts
npm run lint
npm test
npm pack --dry-run

测试覆盖真实 MCP stdio 工具调用、权限过滤、Token 缓存、根目录/子目录、 multipart 字段和文件名、文件大小、HTTP/JSON 错误、超时、拒绝重定向、上传后关联回读、下载和结构化解决说明。 所有自动测试使用本地模拟服务，不接触真实禅道，也不需要凭证。 GitHub CI 在 Windows / Ubuntu 和 Node.js 20 / 24 上运行。

发布新版本：修改版本和 CHANGELOG，测试通过后执行 npm publish --access public，再推送同版本 Git 标签。 发布包只包含运行代码、文档和许可证；测试文件、配置和登录凭证不会随包分发。

来源与许可证

MIT。上游版权保留于 LICENSE，详见 THIRD_PARTY_NOTICES.md。 官方接口：附件上传说明。