MCP Zentao Bugs

🚀 禪道 Bug 管理 MCP 服務器

基於 FastMCP 的禪道 Bug 管理 MCP 服務器，提供產品搜索、Bug 查詢和解決功能，助力高效的 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調用和數據傳輸

📦 安裝指南

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

💻 使用示例

基礎用法

日常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

圖片提取功能

getBugDetail 工具現在支持自動從BUG步驟中提取圖片：

{
  "bug": {
    "id": 123,
    "title": "登錄頁面顯示異常",
    "steps": "<p>步驟1：打開登錄頁面</p><p></p>",
    "stepsImages": [
      "https://example.com/screenshot.png"
    ]
  }
}

特性：

• 🖼️ 自動識別 - 從HTML內容中提取所有<img>標籤的src屬性
• 🔗 URL過濾 - 只返回HTTP/HTTPS開頭的有效圖片鏈接
• 📋 獨立存儲 - 圖片URL單獨存儲在stepsImages數組中，便於訪問

📚 詳細文檔

工具列表

工具優勢

• 🎯 默認指派給我：所有工具默認只查詢指派給你的BUG，減少干擾
• ⚡ 默認激活狀態：默認只顯示激活狀態的BUG，專注待處理任務
• 🏷️ 產品名稱友好：主要工具支持使用產品名稱而不是ID，更符合業務習慣
• 📋 直接返回詳情：getMyBug 直接返回BUG的完整詳情，減少調用步驟
• 🔍 精確匹配驗證：模糊搜索產品時，如果找到多個產品會提示用戶選擇，確保準確性
• 🔒 必須指定產品：所有工具都要求指定產品，確保一段時間內專注一個產品
• 🔄 流程優化：工具設計完全符合"獲取→處理→解決→下一個"的工作流程
• 💰 流量節省：使用生成器模式，找到即停止，避免不必要的數據傳輸
• 📊 智能統計：提供準確的工作量統計，便於進度管理

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

環境變量

腳本命令

# 安裝依賴
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