Skip to main content
Glama

ZenTao Bugs MCP Server

by evlon
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote
3
1

ZenTao Bugs MCP Server

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

🚀 快速开始

安装

npm install -g mcp-zentao-bugs

配置与运行

方法1: 设置环境变量

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

方法2: 使用 .env 文件

# 在当前目录创建 .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: 一次性设置

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

命令行选项

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：查看可用产品（可选）

{ "keyword": "电商", "limit": 10 }

  • 🔍 产品发现：查看有哪些可用的产品

  • 📝 精确命名：获取准确的产品名称，避免模糊匹配

步骤2：获取一个BUG的完整详情

{ "productName": "电商平台", "keyword": "登录" }

  • 🎯 精准定位：通过产品名称自动找到指派给你的第一个激活BUG

  • 📋 完整详情：直接返回BUG的完整信息，无需额外调用

  • ⚡ 高效搜索：使用产品名称，更符合业务习惯

  • 🔍 精确匹配：如果找到多个产品会提示用户选择，确保准确性

步骤3：标记为已解决

{ "bugId": 123, "comment": "已修复登录页面显示问题" }

  • ✅ 快速解决：一键标记BUG为已解决状态

步骤4：继续下一个 重复步骤2，处理下一个BUG...

📊 其他工具使用场景

查看BUG列表（批量操作时）

{ "productId": 1, "limit": 20, "keyword": "界面" }

查看BUG统计

{ "productId": 1, "activeOnly": true }

📊 工作量管理

查看我的BUG统计

{ "productId": 1, "activeOnly": true }

  • 📈 工作量统计：了解当前有多少激活BUG需要处理

  • 📋 优先级排序：按严重程度自动排序

查看我的BUG列表

{ "productId": 1, "limit": 20, "keyword": "界面" }

  • 📝 批量查看：获取指派给你的BUG列表

  • 🔍 关键词搜索：快速定位特定类型的BUG

🎯 工具优势

  • 🎯 默认指派给我：所有工具默认只查询指派给你的BUG，减少干扰

  • ⚡ 默认激活状态：默认只显示激活状态的BUG，专注待处理任务

  • 🏷️ 产品名称友好：主要工具支持使用产品名称而不是ID，更符合业务习惯

  • 📋 直接返回详情：getMyBug 直接返回BUG的完整详情，减少调用步骤

  • 🔍 精确匹配验证：模糊搜索产品时，如果找到多个产品会提示用户选择，确保准确性

  • 🔒 必须指定产品：所有工具都要求指定产品，确保一段时间内专注一个产品

  • 🔄 流程优化：工具设计完全符合"获取→处理→解决→下一个"的工作流程

  • 💰 流量节省：使用生成器模式，找到即停止，避免不必要的数据传输

  • 📊 智能统计：提供准确的工作量统计，便于进度管理

图片提取功能

getBugDetail 工具现在支持自动从BUG步骤中提取图片：

{ "bug": { "id": 123, "title": "登录页面显示异常", "steps": "<p>步骤1：打开登录页面</p><p><img src=\"https://example.com/screenshot.png\" /></p>", "stepsImages": [ "https://example.com/screenshot.png" ] } }

特性：

  • 🖼️ 自动识别 - 从HTML内容中提取所有<img>标签的src属性

  • 🔗 URL过滤 - 只返回HTTP/HTTPS开头的有效图片链接

  • 📋 独立存储 - 图片URL单独存储在stepsImages数组中，便于访问 |

快速开始

1. 环境配置

复制 .env.example 为 .env 并配置禅道信息：

cp .env.example .env

编辑 .env 文件：

# 禅道配置 ZENTAO_BASE_URL=https://your-zentao.com/api.php/ ZENTAO_ACCOUNT=your-username ZENTAO_PASSWORD=your-password # 服务器端口 PORT=3000

2. 安装依赖

pnpm install

3. 启动服务器

# 方式1: 使用 npx (推荐) npx mcp-zentao-bugs # 方式2: 本地安装后运行 pnpm start # 方式3: 开发模式（文件变化自动重启） pnpm dev

服务器启动后会：

  • 自动登录禅道获取 Token

  • 在指定端口启动 HTTP Streaming 服务

  • 提供 /mcp（HTTP Streaming）和 /sse（SSE）端点

4. 健康检查

curl http://localhost:3000/health

MCP 客户端配置

Trae / Claude Code 配置

在 Trae 或 Claude Code 的 MCP 配置中添加：

{ "mcpServers": { "zentao-server": { "url": "http://localhost:3000/sse" } } }

Claude Desktop 配置

在 Claude Desktop 的 MCP 配置文件中添加：

{ "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）

脚本命令

# 安装依赖 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页），防止无限循环

  • 数据完整性：确保在到达最后一页时正确处理所有数据

实现细节：

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

发布到 npmjs

发布前准备

  1. 注册 npm 账号

    npm adduser # 或使用现有账号: npm login

  2. 检查项目状态

    # 运行发布前检查 npm run pre-release # 或手动检查 ./scripts/publish.sh patch --dry-run

发布流程

方式1: 使用发布脚本 (推荐)

# 发布补丁版本 ./scripts/publish.sh patch # 发布次要版本 ./scripts/publish.sh minor # 发布主要版本 ./scripts/publish.sh major

方式2: 使用 npm 命令

# 发布补丁版本 npm run release:patch # 发布次要版本 npm run release:minor # 发布主要版本 npm run release:major

方式3: 手动发布

# 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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/evlon/mcp-zentao-bugs'

If you have feedback or need assistance with the MCP directory API, please join our Discord server