Zentao MCP (zentao-mcp-d109b1db)

MCP运维云端

提供方 aipper · 包名 @aipper/zentao-mcp-server

运维云端 stdio · 本地进程 Token 社区 / 第三方 Claude DesktopClaudeCursor
查看接入方式

一个连接禅道RESTful API v1的MCP Server,提供自动获取/缓存Token及常用bug管理工具。

一句话选型结论

按资料字段整理

Zentao MCP (zentao-mcp-d109b1db) 属于运维云端类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude Desktop、Claude、Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 9 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量9暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

禅道集成JavaScript本地部署bug管理RESTfulAPI自动化工具开发辅助

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
npx -y @aipper/zentao-mcp-server

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 9 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 9 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Zentao MCP (zentao-mcp-d109b1db)当前 9 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方aipper上游标注的维护方 aipper
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@aipper/zentao-mcp-server · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.3 KB
来自项目仓库与上游目录的原文,未做删改

zentao-mcp-server(自建)

目标

  • 提供一个可运行的 MCP Server(stdio),连接你的禅道 RESTful API v1。
  • 最小功能:自动获取/缓存 Token + 常用 bug 工具。

非目标

  • 不在仓库内存任何密钥/Token。
  • 不暴露无边界的通用 REST 写接口。
  • 不保证覆盖你禅道的全部 API;优先支持高频 bug 流程,再按你的流程补工具。

依赖

  • Node.js 18+(需要内置 fetch)

License

MIT - 详见 LICENSE 文件

配置

复制 .env.example 为 .env 并填写:
- ZENTAO_BASE_URL
- ZENTAO_ACCOUNT
- ZENTAO_PASSWORD
- (可选)ZENTAO_PRODUCT_ID:你的禅道实例若报 Need product id 时设置
- (可选)ZENTAO_PROJECT_ID:按项目查 bug 时设置(直接 /projects/{id}/bugs)
- (可选)ZENTAO_PROJECT_SET_ID:你的 bug 若在项目集视角,设置项目集 ID
- (可选)ZENTAO_DEFAULT_RESOLVED_BUILD:解决 bug 时的默认「解决版本」,默认 trunk(很多实例必填)
- (可选)ZENTAO_MY_BUGS_PATH:我的 bug 专用接口路径(如 /my/bug)
- (可选)ZENTAO_BUGS_FALLBACK_PATHS:bug 列表回退路径(逗号分隔)
- (可选)ZENTAO_PROJECT_SET_BUGS_PATHS:项目集 bug 路径模板(支持 {projectSetId})

> 注意:不同禅道版本/部署方式的 token 端点与返回结构可能不同;可通过 ZENTAO_TOKEN_PATH/ZENTAO_API_PREFIX 调整。
>
> 默认情况下不需要配置 ZENTAO_API_PREFIX(默认值是 /api.php/v1)。
>
> 安全约束:ZENTAO_API_PREFIX / ZENTAO_TOKEN_PATH 只支持相对路径;默认要求 ZENTAO_BASE_URL 使用 HTTPS。ZENTAO_BASE_URL 可为根路径或子目录部署地址(如 https://zentao.example.com/zentao)。

安装与运行```bash

npm i
cp .env.example .env
npm start


## npm 安装后的运行
发布到 npm 后,推荐用 `npx` 启动(适合 MCP 客户端配置):```bash
npx -y @aipper/zentao-mcp-server

验证(不依赖 MCP 客户端)```bash

npm i
cp .env.example .env
set -a; source .env; set +a
npm run smoke

期望结果:
- 输出一行 `token: xxxx…yyyy source: ...`
- 输出 `GET /projects status: 200`(或你的禅道实际返回码)

## Claude Desktop / Cursor 示例(stdio)
优先使用 `npx`(npm 发布版):```json
{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@aipper/zentao-mcp-server"],
      "env": {
        "ZENTAO_BASE_URL": "https://zentao.example.com",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password"
      }
    }
  }
}

本地源码调试可继续用 node src/index.js:

示例(Claude Desktop 的 mcpServers 风格,按你的客户端实际字段为准):```json
{
"mcpServers": {
"zentao": {
"command": "node",
"args": ["src/index.js"],
"cwd": "/ABS/PATH/TO/zentao",
"env": {
"ZENTAO_BASE_URL": "https://zentao.example.com",
"ZENTAO_ACCOUNT": "your_account",
"ZENTAO_PASSWORD": "your_password"
}
}
}
}


## 常见错误(`-32000`)
`-32000` 通常是客户端侧“通用 MCP 调用失败”映射码,优先检查:
- `env` 是否完整传入(尤其是 `ZENTAO_BASE_URL`/`ZENTAO_ACCOUNT`/`ZENTAO_PASSWORD`)。
- 默认要求 HTTPS;如果你的实例只能走 HTTP,必须显式设置 `ZENTAO_ALLOW_INSECURE_HTTP=true`,且只建议临时内网调试使用。
- 若报 `Need product id`,请设置 `ZENTAO_PRODUCT_ID`,或在 `get_my_bugs` 传 `productId`。
- 若你的 bug 在“项目集/我的视角”而非产品,建议设置 `ZENTAO_PROJECT_SET_ID`,并配置 `ZENTAO_MY_BUGS_PATH=/my/bug`。
- 项目集场景下,优先直接调用 `get_my_bugs` 并传 `projectSetId`,必要时再显式传 `path="/my/bug"`;不要先依赖 `list_my_projects` 找项目。
- 有些项目集本身没有创建实际项目,但仍然存在“我的 bug”;这类数据可能不会出现在 `list_my_projects` 结果里。
- `get_my_bugs` 会按候选路径回退(包含项目集路径);即使首个路径返回空列表也会继续尝试,并会把多端点结果合并去重。
- `get_my_bugs.total` 表示最终“我的 bug”总数;若需排查底层一共扫描了多少条,可看 `raw.scannedTotal`。
- 排查时看工具返回里的 `raw.triedPaths` / `raw.paths`,可确认每条路径的返回码与命中数量。
- `ZENTAO_API_PREFIX`/`ZENTAO_TOKEN_PATH` 是否和你的禅道实例一致,且使用相对路径。
- MCP 客户端是否真的在执行 `npx -y @aipper/zentao-mcp-server`(而不是旧的本地命令)。
- 客户端日志中是否有启动报错(如找不到命令、401、超时)。

## 已实现工具
- `get_token`:获取/刷新 token(始终只回显脱敏后的 token 摘要)
- `list_my_projects`:示例:列出“我参与的项目”(字段匹配基于常见返回结构,可能需按你的实例微调;不适合作为项目集 bug 的唯一发现入口)
- `get_my_bugs`:获取“指派给我”的 bug(支持 `status`/`keyword`/`limit`/`page`/`productId`/`projectSetId`,默认路径 `/bugs`;`path` 仅允许 `/bugs`、`/my/bug`、`/my/bugs`)
- `get_bug_detail`:按 `id` 获取 bug 详情(固定读取 `/bugs/{id}`;返回安全裁剪后的 bug 摘要与同源图片链接,不直接透传外部图片地址或原始附件外链)。当 bug 被激活过时,额外返回 `activation` 摘要 `{count, lastActor, lastDate, lastComment}`,其中 `lastComment` 是最近一次激活时测试人员填写的评论(已去除 HTML)。bug 摘要现包含 `activatedCount`/`activatedDate`。
- `get_bug_actions`:按 `id` 获取 bug 的动作历史(激活/解决/关闭/评论等)。同一 `/bugs/{id}` 端点,返回 `actions:[{id, actor, action, date, comment, history:[{field, old, new}]}]`(`comment` 已去 HTML)和 `activation` 摘要。当 bug 被激活、需要拿到激活评论/字段变更明细时使用;`get_bug_detail` 的 `activation.lastComment` 已覆盖"只看最近一次激活评论"的常见场景,需完整历史再用本工具。
- `resolve_bug`:按 `id` 调用真正的解决接口 `POST /bugs/{id}/resolve`(默认 `resolution=fixed`;`resolvedBuild` 默认取 `ZENTAO_DEFAULT_RESOLVED_BUILD`/`trunk`;优先 `solutionModules`,兼容纯文本 `solution`)
- `batch_resolve_my_bugs`:批量解决“我的 bug”(同上 resolve API;默认筛选 `status=active`,支持 `productId`/`projectSetId`/`resolvedBuild`,默认遇错即停,`maxItems` 上限 100;优先共享 `solutionModules`)
- `close_bug`:按 `id` 关闭 bug
- `verify_bug`:验证结果处理(`pass`=关闭,`fail`=激活)
- `comment_bug`:按 `id` 添加备注

### 结构化解决说明 `solutionModules`(推荐)

字段:
- `rootCause`:【根因】触发条件 + 错误行为
- `fixApproach`:【修复思路】策略说明
- `logicChange`:【改动逻辑】关键分支/校验/流程变化
- `impact`:【影响范围】受影响场景 + 结果型回归点

服务端会格式化为多行文本写入禅道,例如:```text
【根因】
...

【修复思路】
...

【改动逻辑】
...

【影响范围】
...

优先级:solutionModules(任一非空字段)> 纯文本 solution > comment 兜底。

解决版本 resolvedBuild:很多禅道实例校验「解决版本不能为空」。请传工具参数 resolvedBuild,或配置 ZENTAO_DEFAULT_RESOLVED_BUILD(默认 trunk)。无版本列表时 trunk 通常可用。

不要用 HTTP 编辑冒充解决:PUT /bugs/{id} 或网页表单“编辑”只可能改字段/状态,不会走 resolve 动作,也不会把 MCP 的 solutionModules 模板写进解决说明。必须用 resolve_bug / batch_resolve_my_bugs。

示例参数:
- resolve_bug(推荐):```json
{
"id": 123,
"resolution": "fixed",
"resolvedBuild": "trunk",
"solutionModules": {
"rootCause": "分页参数为空时仍进入查询构造,导致列表请求异常。",
"fixApproach": "为空参数补默认值,并在构造前做兜底校验。",
"logicChange": "page/size 为空时回落默认值;非法值改为明确错误提示,避免前端重复提交。",
"impact": "列表查询与分页切换;重点回归空参进入与异常提示是否收敛。"
}
}

- `resolve_bug`(兼容纯文本):`{"id":123,"resolution":"fixed","resolvedBuild":"trunk","solution":"补齐分页参数为空时的默认值分支,避免空值继续进入查询构造;同时收敛异常提示,防止前端重复触发提交"}`
- `batch_resolve_my_bugs`(推荐共享模块):```json
{
  "status": "active",
  "maxItems": 20,
  "resolvedBuild": "trunk",
  "solutionModules": {
    "rootCause": "状态切换时旧数据判空顺序错误,触发空指针。",
    "fixApproach": "统一状态切换的判空与分支顺序。",
    "logicChange": "保存前增加兜底校验;异常改为明确提示而非静默失败。",
    "impact": "状态流转相关保存与切换场景。"
  }
}
  • get_my_bugs(项目集):{"status":"active","projectSetId":1001,"limit":50}
  • get_my_bugs(我的):{"status":"active","path":"/my/bug","limit":50}
  • get_my_bugs(项目集 + 我的):{"status":"active","projectSetId":1001,"path":"/my/bug","limit":50}
  • get_my_bugs(按产品):{"status":"active","productId":1,"limit":50}
  • close_bug:{"id":123,"comment":"验证通过,关闭"}
  • verify_bug:{"id":123,"result":"pass","comment":"验证通过"}
  • comment_bug:{"id":123,"comment":"已复现,正在定位根因"}

solutionModules / solution / comment 不要写 Evidence:、Verify:、文件路径、编译命令或“已修复并自测”这类无法说明改动内容的表述。

使用建议:如果用户提到“项目集”“我的 bug”“项目列表里找不到但禅道里能看到 bug”,优先走项目集视角的 get_my_bugs,不要先让用户证明项目已创建。

安全建议

  • 默认要求使用 HTTPS:HTTP 会明文传输账号密码和数据,存在安全风险;如确需兼容老旧实例,需显式设置 ZENTAO_ALLOW_INSECURE_HTTP=true。
  • 使用最小权限账号(仅需要的项目权限),避免使用管理员账号。
  • get_token 不再支持回显完整 token。
  • 调试日志会自动脱敏 query、body、comment、solution 等敏感字段,但仍建议仅在排查问题时临时开启。

调试

如需查看详细日志,可设置环境变量:```bash
ZENTAO_DEBUG=true npx -y @aipper/zentao-mcp-server

日志会输出到 stderr,不影响 MCP 协议通信。

## 发布到 npm
脚本:`scripts/release-npm.sh`(参考 `aiws` 的发布流程,默认 dry-run)。

常用命令:```bash
# dry-run:只检查 + npm pack --dry-run,不会发布
npm run release:npm

# 自动递增版本(patch/minor/major)+ commit + tag(不发布)
npm run release:npm -- --bump patch

# 发布(会二次确认;默认自动 patch 递增)
npm run release:npm -- --publish

# 版本对齐 + commit + tag(不发布)
npm run release:npm -- --release v0.1.0

注意:
- 若 package.json 为 private: true,发布前请改成 false 并确认包名可用。
- 可加 --require-tag 要求 HEAD 上有匹配版本的 tag。
- 若发布时报 403,通常是包名归属问题;建议改为 scoped 包名(如 @yourname/zentao-mcp-server)。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Zentao MCP (zentao-mcp-d109b1db) 怎么安装?

在客户端按下面的安装命令接入:npx -y @aipper/zentao-mcp-server。对应的包名是 @aipper/zentao-mcp-server。装完在客户端配置里引用同一个包或端点。

Zentao MCP (zentao-mcp-d109b1db) 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Zentao MCP (zentao-mcp-d109b1db) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Zentao MCP (zentao-mcp-d109b1db) 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Zentao MCP (zentao-mcp-d109b1db) 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Zentao MCP (zentao-mcp-d109b1db) 能提供哪些能力?

资料显示约 9 个工具;能力标签包括 开发工具、JavaScript、Claude、API集成。具体工具清单以官方文档为准。

Zentao MCP (zentao-mcp-d109b1db) 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

Zentao MCP (zentao-mcp-d109b1db) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。