ZenTao Bugs MCP Server

MCP开发工具

提供方 evlon · 包名 mcp-zentao-bugs

开发工具 stdio · 本地进程 Token 社区 / 第三方 Claude DesktopClaude
查看接入方式

ZenTao Bugs MCP Server 是一个基于 FastMCP 的禅道 Bug 管理服务器,提供产品搜索、Bug 查询和解决功能,适用于开发团队的 Bug 跟踪和管理。

一句话选型结论

按资料字段整理

ZenTao Bugs MCP Server 属于开发工具类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude Desktop、Claude,有可直接复制的远程端点配置。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

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

工具与能力

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

能力标签

支持客户端

适用场景

Bug管理JavaScript本地部署禅道集成开发工具项目管理自动化

安装与配置

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

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

  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

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

  3. 3
    写入客户端配置

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

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

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

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

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

不太适合

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

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
ZenTao Bugs MCP Server当前 未标注 stdio · 本地进程 支持远程部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

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

详细介绍

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

ZenTao Bugs MCP Server

基于 FastMCP 的禅道 Bug 管理 MCP 服务器,提供产品搜索、Bug 查询和解决功能。

🚀 快速开始

安装```bash

npm install -g mcp-zentao-bugs


### 配置与运行

#### 方法1: 设置环境变量```bash
export ZENTAO_BASE_URL="https://your-zentao.com"
export ZENTAO_ACCOUNT="your-username"
export ZENTAO_PASSWORD="your-password"
mcp-zentao-bugs

方法2: 使用 .env 文件```bash

在当前目录创建 .env 文件

echo "ZENTAO_BASE_URL=https://your-zentao.com" > .env
echo "ZENTAO_ACCOUNT=your-username" >> .env
echo "ZENTAO_PASSWORD=your-password" >> .env
mcp-zentao-bugs


> 💡 **提示**:全局安装后,`.env` 文件会自动被加载,无需额外配置。

#### 方法3: 一次性设置```bash
ZENTAO_BASE_URL="https://your-zentao.com" \
ZENTAO_ACCOUNT="your-username" \
ZENTAO_PASSWORD="your-password" \
mcp-zentao-bugs

命令行选项```bash

mcp-zentao-bugs --help # 显示帮助信息
mcp-zentao-bugs --version # 显示版本信息


## 功能特性

- 🔐 **自动登录** - 启动时自动登录禅道并持有 Token
- 🧠 **智能搜索** - 一步完成产品和BUG搜索:找到唯一产品时直接返回BUG列表,多个产品时提供选择
- 🐛 **Bug 管理** - 查询产品下的 Bug、获取详情、标记解决
- 🖼️ **图片提取** - 自动从BUG步骤中提取图片URL,便于查看截图
- 🎯 **精准搜索** - API层面过滤激活BUG,自动翻页确保获取足够的活跃BUG
- 📡 **SSE 流式传输** - 通过 Server-Sent Events 实时推送日志和结果
- 🔄 **串行处理** - 单进程队列处理,确保工具调用有序执行
- 🚀 **FastMCP 标准** - 兼容 MCP 协议,支持 HTTP Streaming 和 SSE
- 📉 **流量优化** - 智能合并搜索步骤,减少API调用和数据传输

## 工具列表

| 工具名 | 参数 | 描述 |
|--------|------|------|
| `searchProducts` | `keyword?: string`, `limit?: number` | **搜索产品**:查看有哪些可用的产品,帮助选择精确的产品名称。支持关键词搜索 |
| `getMyBug` | `productName: string`, `keyword?: string` | **获取我的BUG详情**:获取指定产品的一个BUG详情(指派给我的激活BUG)。**这是最常用的工具**,直接返回BUG的完整详情,而不是列表。**使用产品名称而不是ID,更符合业务习惯** |
| `getMyBugs` | `productId: number`, `keyword?: string`, `allStatuses?: boolean`, `limit?: number` | **获取我的BUG列表**:获取指派给我的BUG列表(**默认只返回激活状态**)。用于查看需要处理的BUG列表。**必须指定产品ID以保持专注** |
| `getNextBug` | `productId: number`, `keyword?: string` | **获取下一个BUG**:获取下一个需要处理的BUG(指派给我的激活BUG)。使用 **for yield 生成器模式**,高效找到第一个匹配的BUG后立即返回。**必须指定产品ID以保持专注** |
| `getBugStats` | `productId: number`, `activeOnly?: boolean` | **BUG统计**:获取指派给我的BUG统计信息(总数、激活数量等)。用于了解工作量和进度。**必须指定产品ID以保持专注** |
| `getBugDetail` | `bugId: number` | **BUG详情**:返回 Bug 全字段 + 原始 HTML 步骤 + 提取的图片URL列表 |
| `markBugResolved` | `bugId: number`, `comment?: string` | **标记已解决**:把 Bug 置为已解决(resolution=fixed) |

### 典型工作流程

#### 🔄 日常BUG处理流程

**步骤1:查看可用产品(可选)**```json
{
"keyword": "电商",
"limit": 10
}
  • 🔍 产品发现:查看有哪些可用的产品
  • 📝 精确命名:获取准确的产品名称,避免模糊匹配

步骤2:获取一个BUG的完整详情```json
{
"productName": "电商平台",
"keyword": "登录"
}

- 🎯 **精准定位**:通过产品名称自动找到指派给你的第一个激活BUG
- 📋 **完整详情**:直接返回BUG的完整信息,无需额外调用
- ⚡ **高效搜索**:使用产品名称,更符合业务习惯
- 🔍 **精确匹配**:如果找到多个产品会提示用户选择,确保准确性

**步骤3:标记为已解决**```json
{
"bugId": 123,
"comment": "已修复登录页面显示问题"
}
  • ✅ 快速解决:一键标记BUG为已解决状态

步骤4:继续下一个
重复步骤2,处理下一个BUG...

📊 其他工具使用场景

查看BUG列表(批量操作时)```json
{
"productId": 1,
"limit": 20,
"keyword": "界面"
}


**查看BUG统计**```json
{
"productId": 1,
"activeOnly": true
}

📊 工作量管理

查看我的BUG统计```json
{
"productId": 1,
"activeOnly": true
}

- 📈 **工作量统计**:了解当前有多少激活BUG需要处理
- 📋 **优先级排序**:按严重程度自动排序

**查看我的BUG列表**```json
{
"productId": 1,
"limit": 20,
"keyword": "界面"
}
  • 📝 批量查看:获取指派给你的BUG列表
  • 🔍 关键词搜索:快速定位特定类型的BUG

🎯 工具优势

  • 🎯 默认指派给我:所有工具默认只查询指派给你的BUG,减少干扰
  • ⚡ 默认激活状态:默认只显示激活状态的BUG,专注待处理任务
  • 🏷️ 产品名称友好:主要工具支持使用产品名称而不是ID,更符合业务习惯
  • 📋 直接返回详情:getMyBug 直接返回BUG的完整详情,减少调用步骤
  • 🔍 精确匹配验证:模糊搜索产品时,如果找到多个产品会提示用户选择,确保准确性
  • 🔒 必须指定产品:所有工具都要求指定产品,确保一段时间内专注一个产品
  • 🔄 流程优化:工具设计完全符合"获取→处理→解决→下一个"的工作流程
  • 💰 流量节省:使用生成器模式,找到即停止,避免不必要的数据传输
  • 📊 智能统计:提供准确的工作量统计,便于进度管理

图片提取功能

getBugDetail 工具现在支持自动从BUG步骤中提取图片:```json
{
"bug": {
"id": 123,
"title": "登录页面显示异常",
"steps": "

步骤1:打开登录页面

",
"stepsImages": [
"https://example.com/screenshot.png"
]
}
}


**特性**:
- 🖼️ **自动识别** - 从HTML内容中提取所有``标签的`src`属性
- 🔗 **URL过滤** - 只返回HTTP/HTTPS开头的有效图片链接
- 📋 **独立存储** - 图片URL单独存储在`stepsImages`数组中,便于访问 |

## 快速开始

### 1. 环境配置

复制 `.env.example` 为 `.env` 并配置禅道信息:```bash
cp .env.example .env

编辑 .env 文件:```env

禅道配置

ZENTAO_BASE_URL=https://your-zentao.com/api.php/
ZENTAO_ACCOUNT=your-username
ZENTAO_PASSWORD=your-password

服务器端口

PORT=3000


### 2. 安装依赖```bash
pnpm install

3. 启动服务器```bash

方式1: 使用 npx (推荐)

npx mcp-zentao-bugs

方式2: 本地安装后运行

pnpm start

方式3: 开发模式(文件变化自动重启)

pnpm dev


服务器启动后会:
- 自动登录禅道获取 Token
- 在指定端口启动 HTTP Streaming 服务
- 提供 `/mcp`(HTTP Streaming)和 `/sse`(SSE)端点

### 4. 健康检查```bash
curl http://localhost:3000/health

MCP 客户端配置

Trae / Claude Code 配置

在 Trae 或 Claude Code 的 MCP 配置中添加:```json
{
"mcpServers": {
"zentao-server": {
"url": "http://localhost:3000/sse"
}
}
}


### Claude Desktop 配置

在 Claude Desktop 的 MCP 配置文件中添加:```json
{
"mcpServers": {
"zentao-server": {
"command": "node",
"args": ["src/mcp-server.mjs"],
"env": {
"ZENTAO_BASE_URL": "https://your-zentao.com/api.php/",
"ZENTAO_ACCOUNT": "your-username",
"ZENTAO_PASSWORD": "your-password",
"PORT": "3000"
}
}
}
}

开发

项目结构```

├── src/
│ ├── mcp-server.mjs # FastMCP 服务器主文件
│ ├── zentao-api.mjs # 禅道 API 封装模块
│ └── server.mjs # 原始 SSE 服务器(备用)
├── scripts/ # 发布和工具脚本
│ ├── publish.sh # Linux/macOS 发布脚本
│ ├── publish.bat # Windows 发布脚本
│ └── pre-publish.js # 发布前检查脚本
├── api-docs/ # API 文档
├── .env # 环境变量配置
├── .env.example # 环境变量模板
├── package.json
└── README.md


### 环境变量

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `ZENTAO_BASE_URL` | ✅ | 禅道 API 基础地址 |
| `ZENTAO_ACCOUNT` | ✅ | 禅道登录账号 |
| `ZENTAO_PASSWORD` | ✅ | 禅道登录密码 |
| `PORT` | ❌ | 服务器端口(默认:3000) |

### 脚本命令```bash
# 安装依赖
pnpm install

# 启动服务器
pnpm start

# 开发模式(监听文件变化)
pnpm dev

API 端点

  • HTTP Streaming: http://localhost:3000/mcp
  • SSE: http://localhost:3000/sse
  • 健康检查: http://localhost:3000/health

技术栈

  • FastMCP - MCP 服务器框架
  • Node.js 20+ - 运行时环境
  • Zod - 参数验证
  • dotenv - 环境变量管理
  • 模块化架构 - 禅道API独立封装,便于维护和测试

故障排除

登录失败

  1. 检查 .env 文件中的禅道配置是否正确
  2. 确认网络可以访问禅道服务器
  3. 验证账号密码是否有权限访问 API

连接问题

  1. 确认服务器已启动:curl http://localhost:3000/health
  2. 检查防火墙设置,确保端口可访问
  3. 查看服务器日志获取详细错误信息

工具调用失败

  1. 检查禅道 Token 是否有效(Token 过期需要重启服务器)
  2. 确认传入的参数格式正确
  3. 查看服务器日志中的错误信息

API 分页问题

问题描述:禅道API的分页机制存在特殊行为,当请求的页码超出最大页数时,API不会返回空数据,而是返回第一页的数据,但返回的页码字段与请求的页码不一致。

解决方案:
- 分页有效性检查:通过比较 data.page 与请求的 page 参数来判断是否超出最大页数
- 智能分页:逐页获取数据,当检测到页码不一致时停止分页
- 性能优化:设置合理的最大页数限制(50页),防止无限循环
- 数据完整性:确保在到达最后一页时正确处理所有数据

实现细节:```javascript
// 检查分页是否有效:如果返回的页码与请求的页码不一致,说明已超出最大页数
if (data.page && data.page !== page) {
break; // 已到达最后一页
}


## 发布到 npmjs

### 发布前准备

1. **注册 npm 账号**```bash
npm adduser
# 或使用现有账号: npm login
  1. 检查项目状态```bash

运行发布前检查

npm run pre-release

或手动检查

./scripts/publish.sh patch --dry-run


### 发布流程

#### 方式1: 使用发布脚本 (推荐)```bash
# 发布补丁版本
./scripts/publish.sh patch

# 发布次要版本
./scripts/publish.sh minor

# 发布主要版本
./scripts/publish.sh major

方式2: 使用 npm 命令```bash

发布补丁版本

npm run release:patch

发布次要版本

npm run release:minor

发布主要版本

npm run release:major


#### 方式3: 手动发布```bash
# 1. 更新版本
npm version patch

# 2. 发布
npm publish

# 3. 推送标签
git push && git push --tags

发布脚本功能

  • 自动检查: 检查项目状态、依赖、文件完整性
  • 版本管理: 自动更新版本号并创建 git tag
  • 安全发布: 检查 npm 登录状态和包名可用性
  • 跨平台支持: 提供 bash 和 Windows batch 脚本

版本管理策略

  • patch: 修复 bug,向后兼容 (1.0.0 → 1.0.1)
  • minor: 新增功能,向后兼容 (1.0.0 → 1.1.0)
  • major: 重大变更,可能不兼容 (1.0.0 → 2.0.0)

发布检查清单

  • [ ] 测试通过 (npm test)
  • [ ] README.md 更新完整
  • [ ] 版本号已更新
  • [ ] 所有更改已提交
  • [ ] npm 账号已登录
  • [ ] 包名可用性检查

许可证

ISC License

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
ZenTao Bugs MCP Server 怎么安装?

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

ZenTao Bugs MCP Server 怎么在 Claude Desktop、Claude 里配置?

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

ZenTao Bugs MCP Server 收费吗?

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

ZenTao Bugs MCP Server 需要 API Key 吗?

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

ZenTao Bugs MCP Server 支持哪些客户端?

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

ZenTao Bugs MCP Server 能提供哪些能力?

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

ZenTao Bugs MCP Server 需要什么运行环境?

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

ZenTao Bugs MCP Server 是本地还是远程?

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

热门专题

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

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