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