MCP Zebrunner

🚀 Zebrunner MCP Server

Zebrunner MCP Server 是一個模型上下文協議 (MCP) 服務器，它與 Zebrunner 測試用例管理 集成，幫助 QA 團隊通過 Claude 等 AI 助手管理測試用例、測試套件和測試執行數據。

🚀 快速開始

💡 想要更詳細的說明？ 查看我們的 ，其中包含故障排除提示和特定平臺的說明。

步驟 1：獲取代碼

選擇以下方法之一：

選項 A：從倉庫克隆（推薦）

git clone https://github.com/maksimsarychau/mcp-zebrunner.git
cd mcp-zebrunner

選項 B：下載並解壓

下載項目文件並解壓到一個文件夾中。

步驟 2：安裝依賴項

npm install

步驟 3：配置 Zebrunner 連接

在項目文件夾中創建一個 .env 文件，並填寫你的 Zebrunner 詳細信息：

# 你的 Zebrunner 實例 URL（無尾部斜槓）
ZEBRUNNER_URL=https://your-company.zebrunner.com/api/public/v1

# 你的 Zebrunner 登錄名（通常是你的電子郵件）
ZEBRUNNER_LOGIN=your.email@company.com

# 你的 Zebrunner API 令牌（從你的 Zebrunner 個人資料中獲取）
ZEBRUNNER_TOKEN=your_api_token_here

# 可選：啟用調試日誌記錄（默認：false）
DEBUG=false

# 可選：啟用智能規則系統（如果規則文件存在則自動檢測）
ENABLE_RULES_ENGINE=true

如何獲取你的 Zebrunner API 令牌：

1. 登錄到你的 Zebrunner 實例
2. 進入你的個人資料設置
3. 找到 "API 訪問" 部分
4. 生成一個新的 API 令牌
5. 將令牌複製到你的 .env 文件中

步驟 4：構建項目

npm run build

步驟 5：測試你的連接

npm run test:health

如果你看到 "✅ 健康檢查完成"，則表示你已準備就緒！

🔄 更新到新版本

檢查當前版本

# 檢查當前版本
npm run version
# 或手動檢查 package.json
cat package.json | grep '"version"'

更新步驟

# 1. 從主分支拉取最新更改
git pull origin master

# 2. 安裝任何新的依賴項
npm install

# 3. 重新構建項目
npm run build

# 4. 測試你的連接（需要有效的.env 文件）
npm run test:health

重要提示：

• ✅ 你的 .env 文件必須正確配置，健康檢查才能正常工作
• ✅ 更新後重啟 Claude Desktop/Code 以重新加載 MCP 服務器
• ✅ 更新前查看發行說明，以瞭解是否有重大更改

如果健康檢查失敗，請驗證你的 .env 配置和 Zebrunner 憑據。

✨ 主要特性

🎯 功能概述

• 從 Zebrunner 檢索測試用例 和測試套件
• 分析測試覆蓋率 並生成測試代碼
• 獲取測試執行結果 和啟動詳細信息
• 使用智能規則通過自動檢查 驗證測試用例質量
• 從測試數據中 生成報告 和見解
• 通過 AI 建議和自動修復 改進測試用例

🧠 智能規則系統

獨特之處

MCP 服務器包含一個複雜的 三層規則系統，徹底改變了你處理測試用例的方式：

• 測試用例審查規則 (test_case_review_rules.md)：定義編寫高質量測試用例的核心質量標準和準則。
• 測試用例分析檢查點 (test_case_analysis_checkpoints.md)：提供包含 100 多個檢查點的詳細驗證清單。
• MCP Zebrunner 規則 (mcp-zebrunner-rules.md)：定義測試生成和覆蓋率分析的技術配置。

規則協同工作方式

graph TD
    A[測試用例] --> B[validate_test_case]
    B --> C[test_case_review_rules.md]
    B --> D[test_case_analysis_checkpoints.md]
    B --> E[驗證結果 + 問題]
    
    E --> F[improve_test_case]
    F --> G[AI 驅動的改進]
    
    A --> H[generate_draft_test_by_key]
    H --> I[mcp-zebrunner-rules.md]
    H --> J[生成的測試代碼]
    
    A --> K[get_enhanced_test_coverage_with_rules]
    K --> I
    K --> L[覆蓋率分析 + 規則驗證]

重要性

• 一致性：所有團隊成員遵循相同的質量標準
• 自動化：通過自動驗證減少手動審查時間
• 學習：新團隊成員通過 AI 反饋學習最佳實踐
• 定製化：根據項目的特定需求調整規則
• 持續改進：AI 根據已驗證的模式提供改進建議

為項目定製規則

你可以自定義三個規則文件中的任何一個：

# 複製默認規則以進行自定義
cp test_case_review_rules.md my-project-review-rules.md
cp test_case_analysis_checkpoints.md my-project-checkpoints.md
cp mcp-zebrunner-rules.md my-project-technical-rules.md

# 在驗證中使用自定義規則
"Validate test case PROJ-123 using custom rules from my-project-review-rules.md"

示例自定義：

• 移動項目：添加特定於移動設備的驗證規則
• API 項目：專注於 API 測試模式和數據驗證
• 不同框架：自定義代碼生成模板
• 公司標準：與組織的測試指南保持一致

🚀 智能 URL 分析

從 v5.4.1+ 版本開始，Claude 可以自動檢測 Zebrunner URL 並使用最佳設置進行分析！只需在對話中粘貼一個 Zebrunner URL，Claude 將自動執行以下操作：

• 解析 URL 以提取項目、啟動和測試 ID
• 調用適當的分析工具
• 使用推薦的設置（啟用視頻、截圖、AI 分析）

📋 支持的 URL 模式

• 測試分析 URL：Claude 自動調用 analyze_test_failure 並提取相關信息，啟用視頻和截圖分析。
• 啟動分析 URL：Claude 自動調用 detailed_analyze_launch_failures 並提取相關信息，啟用截圖分析。

✨ 高級用法

• 覆蓋默認設置：Claude 理解自然語言覆蓋設置。
• 多 URL 分析：可以在一個請求中分析多個測試/啟動。
• 跨工作區支持：不同工作區的 URL 會顯示警告但仍嘗試分析。

🎯 使用 URL 分析的好處

• ✅ 更快：無需手動指定 ID
• ✅ 方便：直接從 Zebrunner UI 複製粘貼 URL
• ✅ 優化：自動使用推薦的設置
• ✅ 智能：Claude 檢測意圖並調整參數
• ✅ 靈活：自然語言覆蓋設置無縫工作

💡 專業提示

• 直接從 Zebrunner 獲取：在查看測試/啟動時直接從瀏覽器複製 URL
• 批量分析：粘貼多個用換行符分隔的 URL
• 自定義設置：添加自然語言指令以覆蓋默認設置
• 快速檢查：URL 非常適合快速詢問 "這裡發生了什麼？"
• 報告：結合格式請求："為 https://...url... 生成 Jira 工單"

📦 安裝指南

📋 先決條件

知識要求

• 基本命令行使用（打開終端、運行命令）
• 你的 Zebrunner 憑據（登錄名和 API 令牌）
• 對測試管理的基本理解（測試用例、測試套件）

軟件要求

• Node.js 18 或更新版本 - 在此下載
• npm（隨 Node.js 一起提供）
• 具有 API 憑據的 Zebrunner 實例訪問權限

如何檢查是否安裝了 Node.js

打開終端/命令提示符並運行：

node --version
npm --version

如果你看到版本號，則表示你已準備好開始！

💻 使用示例

方法 1：與 Claude Desktop/Code 一起使用（推薦）

將以下配置添加到你的 Claude Desktop 或 Claude Code 設置中。重要提示：你必須使用項目文件夾的完整絕對路徑。

{
  "mcpServers": {
    "mcp-zebrunner": {
      "command": "node",
      "args": ["/full/absolute/path/to/mcp-zebrunner/dist/server.js"],
      "env": {
        "ZEBRUNNER_URL": "https://your-company.zebrunner.com/api/public/v1",
        "ZEBRUNNER_LOGIN": "your.email@company.com",
        "ZEBRUNNER_TOKEN": "your_api_token_here",
        "DEBUG": "false",
        "ENABLE_RULES_ENGINE": "true",
        "DEFAULT_PAGE_SIZE": "100",
        "MAX_PAGE_SIZE": "100"
      }
    }
  }
}

示例路徑：

• Windows：C:\\Users\\YourName\\Projects\\mcp-zebrunner\\dist\\server.js
• macOS/Linux：/Users/YourName/Projects/mcp-zebrunner/dist/server.js

替代方法：命令行集成（Claude Code）

你也可以使用命令行添加服務器：

claude mcp add mcp-zebrunner \
  --env ZEBRUNNER_URL="https://your-company.zebrunner.com/api/public/v1" \
  --env ZEBRUNNER_LOGIN="your.email@company.com" \
  --env ZEBRUNNER_TOKEN="your_api_token_here" \
  --env DEBUG="false" \
  --env ENABLE_RULES_ENGINE="true" \
  -- node /full/absolute/path/to/mcp-zebrunner/dist/server.js

重要提示：將 /full/absolute/path/to/mcp-zebrunner/ 替換為你項目文件夾的實際完整路徑。

方法 2：作為獨立服務器運行

開發模式（自動重新加載）

npm run dev

生產模式

npm start

方法 3：智能 URL 分析 🚀

如前文所述，Claude 可以自動檢測 Zebrunner URL 並進行分析。

📚 詳細文檔

🛠️ 可用工具

連接後，你可以通過 AI 助手中的自然語言使用這些工具。以下是按類別組織的所有 33 多個可用工具的綜合參考：

📋 測試用例管理

工具	描述	示例用法	適用角色
get_test_case_by_key	獲取詳細的測試用例信息	"Get test case MCP-123 details"	所有角色
get_test_cases_advanced	按自動化狀態、日期進行高級過濾	"Get test cases created after 2025-01-01 with automation state 'Manual'"	QA、SDETs
get_test_cases_by_automation_state	按特定自動化狀態過濾	"Show me all 'Not Automated' test cases in project MCP"	SDETs、經理
get_test_case_by_title	按標題搜索測試用例（部分匹配）	"Find test cases with title containing 'login functionality'"	所有角色
get_test_case_by_filter	按套件、日期、優先級、自動化狀態進行高級過濾	"Get test cases from suite 491 created after 2025-01-01 with high priority"	QA、經理
get_automation_states	列出可用的自動化狀態	"What automation states are available for project MCP?"	所有角色
get_automation_priorities	列出可用的優先級及其 ID	"Show me all priority levels for project MCP"	所有角色
get_all_tcm_test_cases_by_project	獲取項目的所有測試用例（處理分頁）	"Get all test cases for project MCP"	經理、負責人
get_all_tcm_test_cases_with_root_suite_id	獲取所有帶有層次結構信息的測試用例	"Get all test cases with their root suite information"	分析師

🌳 測試套件層次結構與組織

工具	描述	示例用法	適用角色
list_test_suites	列出套件並支持分頁	"List test suites for project MCP"	所有角色
get_suite_hierarchy	顯示層次結構樹視圖	"Show me the hierarchy of test suites with depth 3"	經理、QA
get_root_suites	獲取頂級套件	"Show me all root suites for project MCP"	經理
get_all_subsuites	獲取所有子套件	"Get all subsuites from root suite 18697"	QA、分析師
get_tcm_suite_by_id	通過 ID 查找特定套件	"Get details for suite 17470"	所有角色
get_tcm_test_suites_by_project	全面列出套件信息	"Get all suites for project MCP with hierarchy"	經理
get_root_id_by_suite_id	查找任何套件的根套件	"What's the root suite for suite 12345?"	分析師

🔍 測試覆蓋率與分析

工具	描述	示例用法	適用角色
get_test_coverage_by_test_case_steps_by_key	分析實現覆蓋率	"Analyze coverage for MCP-123 against this code: [paste code]"	開發人員、SDETs
get_enhanced_test_coverage_with_rules	基於規則的覆蓋率分析	"Enhanced coverage analysis for MCP-123 with framework detection"	SDETs、負責人
analyze_test_cases_duplicates	通過步驟相似度查找並分組相似的測試用例	"Analyze suite 12345 for duplicates with 80% similarity threshold"	QA 經理、SDETs
analyze_test_cases_duplicates_semantic	使用 LLM 驅動的步驟聚類進行高級語義分析	"Semantic analysis of suite 12345 with step clustering and medoid selection"	高級 QA、測試架構師

🔗 可點擊鏈接功能：兩個重複分析工具都支持指向 Zebrunner 網頁 UI 的可點擊鏈接。

🧪 測試代碼生成與驗證

工具	描述	示例用法	適用角色
generate_draft_test_by_key	生成帶有框架檢測的測試代碼	"Generate Java/Carina test for MCP-123 based on this implementation"	SDETs、開發人員
validate_test_case	進行質量驗證並提供改進建議	"Validate test case MCP-123 and suggest improvements"	QA、經理
improve_test_case	專門用於改進測試用例的工具	"Improve test case MCP-123 with specific suggestions"	QA、SDETs

🚀 啟動與執行管理

工具	描述	示例用法	適用角色
get_launch_details	獲取全面的啟動信息	"Get launch details for launch 118685"	經理、負責人
get_launch_summary	獲取快速的啟動概述	"Show me summary for launch 118685"	經理
get_all_launches_for_project	獲取項目的所有啟動信息並支持分頁	"Get all launches for project MCP from last month"	經理、負責人
get_all_launches_with_filter	按里程碑/構建進行過濾	"Get launches for milestone 2.1.0 and build 'mcp-app-2.1.0'"	經理、負責人

📊 報告與分析

工具	描述	示例用法	適用角色
analyze_test_failure	對失敗的測試進行深入的取證分析，包括日誌、截圖、錯誤分類和建議。v5.11.0 新增功能：與上次通過的執行進行比較，顯示更改內容（日誌、持續時間、環境）。還支持 format: 'jira' 生成可直接粘貼的 Jira 工單。	"Analyze test failure 5451420 in launch 120806 and compare with last passed execution"	QA 工程師、SDETs、經理
get_test_execution_history	v5.11.0 新增功能：跟蹤測試執行趨勢，查看通過/失敗歷史，查找上次通過的執行，計算通過率。突出顯示測試在最近所有運行中均失敗的情況！	"Show execution history for test 5478492" 或 "Has test 5478492 been failing consistently?"	QA 工程師、SDETs、經理
detailed_analyze_launch_failures	v4.12.1 增強功能：使用 Claude 級別的智能分析未關聯問題的失敗情況，並支持 Jira 格式。自動深入分析，提供執行摘要、時間線、模式、優先級。新增功能：為整個啟動生成 Jira 就緒工單！	"Analyze failures in launch 120806" 或使用 format: 'jira'	QA 經理、SDETs、團隊負責人
download_test_screenshot	從 Zebrunner 下載受保護的截圖並進行身份驗證	"Download screenshot from https://your-workspace.zebrunner.com/files/abc123 for test 5451420"	QA 工程師、自動化工程師
analyze_screenshot	使用 OCR、UI 檢測和 Claude Vision 進行視覺分析	"Analyze screenshot https://your-workspace.zebrunner.com/files/abc123 with OCR and detailed analysis"	QA 工程師、SDETs、開發人員
get_platform_results_by_period	按平臺/時間段獲取測試結果	"Get iOS test results for the last 7 days"	經理、負責人
get_top_bugs	獲取最常見的缺陷	"Show me top 10 bugs from last week"	經理、開發人員
get_bug_review	詳細的缺陷審查，包括失敗分析、優先級細分和自動獲取詳細信息	"Get bug review with full failure details for top 10 bugs"	經理、QA、開發人員
get_bug_failure_info	通過哈希碼獲取全面的失敗信息（自動獲取的替代方法）	"Get failure info for hashcode 1051677506"	開發人員、SDETs
get_project_milestones	獲取可用的里程碑	"Get all milestones for project MCP"	經理、產品經理
get_available_projects	發現所有可訪問的項目	"What projects can I access?"	所有角色
test_reporting_connection	測試 API 連接性	"Test my connection to Zebrunner"	所有角色

🏃 測試運行管理

工具	描述	示例用法	適用角色
list_test_runs	進行高級測試運行過濾	"Get test runs from last 30 days with status 'FAILED'"	經理、SDETs
get_test_run_by_id	獲取詳細的測試運行信息	"Get details for test run 12345"	經理、QA
list_test_run_test_cases	獲取特定測試運行中的測試用例	"Show me all test cases in test run 12345"	QA、分析師
get_test_run_result_statuses	列出可用的結果狀態	"What result statuses are configured for project MCP?"	QA、SDETs
get_test_run_configuration_groups	獲取配置選項	"Show me configuration groups for project MCP"	SDETs、負責人

🎯 管理聚焦的快速命令

📈 每日站會報告

# 獲取昨天的結果
"Get platform results for last 7 days for project MCP"

# 檢查最近的失敗情況
"Show me top 5 bugs from last week"

# 審查最近的啟動
"Get all launches for project MCP from last 3 days"

🔍 測試套件優化

# 基本重複分析
"Analyze suite 12345 for duplicates with 80% similarity threshold"

# 帶步驟聚類的高級語義分析
"Semantic analysis of suite 12345 with 85% step clustering and medoid selection"

# 分析特定測試用例的重複情況
"Analyze test cases MCP-123, MCP-124, MCP-125 for duplicates"

# 項目範圍的重複分析（謹慎使用 - 大數據集）
"Analyze project MCP for test case duplicates with 85% similarity"

# 獲取帶有模式類型的詳細相似度矩陣
"Analyze suite 12345 for duplicates with similarity matrix included"

# 帶語義洞察的兩階段聚類
"Semantic duplicate analysis with step clustering threshold 90% and insights enabled"

# 啟用可點擊鏈接以便於導航
"Analyze suite 17585 for duplicates with clickable links enabled"

📊 每週管理報告

# 全面的項目健康狀況
"Get all launches for project MCP with milestone filter"

# 平臺性能分析
"Get iOS and Android test results for the last month"

# 質量指標
"Get all test cases by automation state for project MCP"

🎯 里程碑與發佈計劃

# 里程碑跟蹤
"Get project milestones for MCP with completion status"

# 特定構建的結果
"Get launches for build 'mcp-app-2.1.0-release' and milestone '2.1.0'"

# 發佈準備情況
"Get automation readiness for all test cases in project MCP"

🐞 問題分析與故障排除

# 缺陷分析
"Show me top 10 most frequent bugs with issue links"

# 失敗調查
"Get test run 12345 details with all test cases"

# 特定平臺的問題
"Get Android test results for last 7 days with failure analysis"

🎭 特定角色的提示與工作流程

👩‍💻 手動 QA 工程師

每日測試用例審查

"Get test case MCP-45 details and validate its quality"
"Show me all test cases in suite 18708 that need improvement"
"Validate test case MCP-67 and suggest specific improvements"
"Find test cases with title containing 'login' to review authentication tests"
"Get test cases from suite 491 with high priority for today's testing"

測試用例創建與改進

"I'm writing a test case for login functionality. What should I include based on our quality standards?"
"Improve test case MCP-89 - it's missing some preconditions"
"Check if test case MCP-12 is ready for manual execution"

測試套件組織

"Show me the hierarchy of test suites for project MYAPP to understand the structure"
"Get all subsuites from Authentication suite to review test coverage"
"List test cases in suite 18708 and identify which ones need validation"
"Find test cases with title containing 'payment' to organize payment testing"
"Get all high priority test cases from suite 491 for release testing"

覆蓋率分析

"I executed test case MCP-34 manually. Here's what I did: [paste your execution notes]. Analyze coverage against the documented steps."
"Compare test case MCP-56 with this manual testing session: [paste session details]"

🤖 測試自動化工程師與 SDETs

自動化就緒評估

"Validate test case MCP-78 for automation readiness"
"Get all test cases in suite 18708 and identify which ones are ready for automation"
"Check test case MCP-23 - does it have clear, unambiguous steps for automation?"
"Find test cases with title containing 'API' to prioritize API automation"
"Get automation priorities to understand which test cases to automate first"
"Get test cases from suite 491 with 'Not Automated' state for automation planning"

測試代碼生成

"Generate Java/Carina test code for MCP-45 based on this existing framework: [paste framework code]"
"Create JavaScript/Jest test for MCP-67 using this test structure: [paste test example]"
"Generate Python/Pytest code for MCP-89 with these page objects: [paste page object code]"

覆蓋率分析與驗證

"Analyze test coverage for MCP-34 against this automated test: [paste test code]"
"Enhanced coverage analysis for MCP-56 with rules validation - here's my implementation: [paste code]"
"Compare test case MCP-78 steps with this Selenium test: [paste selenium code]"

框架集成

"Generate test code for MCP-45 using our Carina framework with these page objects: [paste existing code]"
"Create test automation for MCP-67 that integrates with this CI/CD pipeline: [paste pipeline config]"
"Generate API test for MCP-89 using this RestAssured setup: [paste API test framework]"

批量自動化分析

"Validate all test cases in Authentication suite for automation readiness"
"Generate coverage report for all test cases in project MYAPP"
"Identify test cases in suite 18708 that have automation blockers"
"Find test cases with title containing 'regression' for automation sprint planning"
"Get test cases from suite 491 created after 2025-01-01 with high priority for next automation cycle"
"Get automation priorities and states to create automation roadmap"

👨‍💻 開發人員

測試用例理解

"Get test case MCP-45 details to understand what I need to implement"
"Show me test cases related to login functionality in project MYAPP"
"Explain test case MCP-67 requirements in developer-friendly format"
"Find test cases with title containing 'authentication' for my feature development"
"Get high priority test cases from suite 491 that I need to implement"

實現驗證

"I implemented this feature: [paste code]. Analyze coverage against test case MCP-34"
"Here's my API implementation: [paste code]. Check coverage against test case MCP-56"
"Validate my UI implementation against test case MCP-78: [paste component code]"

測試代碼生成

"Generate unit tests for test case MCP-45 using Jest framework"
"Create integration tests for MCP-67 based on this API: [paste API code]"
"Generate test data setup for MCP-89 using this database schema: [paste schema]"

缺陷分析

"Get test execution results for launch 118685 to understand recent failures"
"Show me top bugs from last week related to my feature area"
"Get detailed bug review for Android project from last 14 days"
"Show me comprehensive failure information for hashcode 1051677506"
"What are the top 50 bugs affecting our project this month?"
"Give me a summary of bug failures with reproduction dates from last 7 days"
"Analyze test case MCP-34 - why might it be failing in automation?"

👔 測試經理與團隊負責人

團隊質量指標

"Get quality metrics for all test cases in project MYAPP"
"Show me test cases that need improvement in suite 18708"
"Generate quality report for test cases created this month"
"Find test cases with title containing 'critical' to assess critical path quality"
"Get automation priorities to align team efforts with business priorities"
"Get test cases from suite 491 with high priority that need quality improvements"

測試套件分析

"Show me the complete test suite hierarchy for project MYAPP"
"Analyze test coverage across all suites in project MYAPP"
"Get automation readiness status for all test cases in Authentication suite"

團隊績效與規劃

"Get test execution results by platform for the last 30 days"
"Show me top 10 most frequent bugs to prioritize fixes"
"Analyze test case quality trends in project MYAPP"
"Get all launches for project MYAPP from last 30 days with milestone tracking"
"Show me platform results for last 7 days to track team performance"
"Get test runs with status 'FAILED' from last week for team retrospective"

流程改進

"Validate all test cases in suite 18708 to identify common quality issues"
"Generate improvement recommendations for test cases created by junior team members"
"Analyze which test cases are consistently failing automation"
"Get top 10 bugs from last month to identify process improvements"
"Show me test runs with detailed failure analysis for process optimization"
"Get automation readiness metrics across all test cases"
"Find test cases with title containing 'flaky' to address test stability"
"Get test cases from suite 491 with medium priority that could be automated"
"Get automation priorities to optimize team resource allocation"

報告與利益相關者溝通

"Generate comprehensive test coverage report for project MYAPP in markdown format"
"Get test execution summary for launch 118685 for stakeholder presentation"
"Show me test quality metrics and improvement suggestions for quarterly review"
"Get platform results by period for executive dashboard"
"Create milestone progress report with test execution data"
"Generate weekly team performance report with launch and bug metrics"

日常管理任務

"Get all launches for project MYAPP from yesterday"
"Show me top 5 bugs from last 7 days with issue links"
"Get platform results for iOS and Android from last week"
"Check automation readiness for upcoming release milestone"
"Get test run details for failed runs from last 24 hours"
"Show me project milestones and their completion status"

🏢 項目所有者與產品經理

項目健康概述

"Get overall test coverage status for project MYAPP"
"Show me test execution results by platform for the last quarter"
"Generate project testing health report in markdown format"
"Get all launches for project MYAPP with milestone and build tracking"
"Show me platform results summary for executive review"
"Get project milestones with completion status and testing metrics"

功能測試狀態

"Get test cases related to [feature name] in project MYAPP"
"Show me test execution results for [feature name] functionality"
"Analyze test coverage for [epic/story] requirements"
"Get launches filtered by milestone for feature release tracking"
"Show me test runs for specific build versions"

質量保證指標

"Get quality metrics for all test cases in project MYAPP"
"Show me test case validation results and improvement areas"
"Generate testing quality report for stakeholder presentation"
"Get top bugs analysis for quality trend assessment"
"Show me automation vs manual testing ratio across the project"
"Find test cases with title containing 'smoke' to assess smoke test coverage"
"Get automation priorities to communicate testing strategy to stakeholders"
"Get test cases from suite 491 with critical priority for risk assessment"

風險評估

"Show me top 10 most frequent bugs in project MYAPP"
"Get test cases that are not ready for automation and assess risk"
"Analyze test execution trends to identify potential quality risks"
"Get platform-specific failure rates for the last month"
"Show me test runs with high failure rates for risk mitigation"
"Get milestone-based testing progress for release risk assessment"

規劃與資源分配

"Get automation readiness assessment for all test cases in project MYAPP"
"Show me test cases that need quality improvement and estimate effort"
"Analyze test suite structure to identify optimization opportunities"
"Get testing resource utilization by platform and time period"
"Show me milestone testing progress for sprint planning"
"Get comprehensive launch analysis for capacity planning"
"Find test cases with title containing 'performance' to plan performance testing"
"Get automation priorities to allocate automation resources effectively"
"Get test cases from suite 491 created in last month to plan review sessions"

高管報告

"Generate executive dashboard with platform results and bug trends"
"Get quarterly testing metrics with milestone progress"
"Show me ROI analysis of automation vs manual testing efforts"
"Create board-ready testing status report with key metrics"
"Get testing velocity trends for project timeline assessment"

📖 輸出格式

所有工具都支持多種輸出格式：

• json - 結構化數據（默認）
• markdown - 帶有章節和表格的豐富格式化輸出
• string - 人類可讀的文本摘要
• dto - 原始數據對象

示例：

"Get test case PROJ-123 in markdown format"
"Show me test suites as JSON"

⚙️ 配置選項

環境變量

# 必需
ZEBRUNNER_URL=https://your-instance.zebrunner.com/api/public/v1
ZEBRUNNER_LOGIN=your.email@company.com
ZEBRUNNER_TOKEN=your_api_token

# 可選 - 基本設置
DEBUG=false                        # 啟用詳細日誌記錄（默認：false）
DEFAULT_PAGE_SIZE=100             # 每頁默認項數（可選）
MAX_PAGE_SIZE=100                 # 每頁最大項數（可選）

# 可選 - 智能規則系統
ENABLE_RULES_ENGINE=true          # 啟用智能規則（如果規則文件存在則自動檢測）
MCP_RULES_FILE=custom-rules.md    # 自定義技術規則文件（可選）
MIN_COVERAGE_THRESHOLD=70         # 最小覆蓋率百分比（可選）
REQUIRE_UI_VALIDATION=true        # 要求在測試中進行 UI 驗證（可選）
REQUIRE_API_VALIDATION=true       # 要求在測試中進行 API 驗證（可選）

規則系統配置

規則系統會自動檢測並使用項目根目錄中的規則文件。

• 自動檢測：如果項目根目錄中有 mcp-zebrunner-rules.md 文件，規則引擎將自動啟用。
• 自定義規則文件：你可以自定義三種類型的規則：
  • 測試用例審查規則 (test_case_review_rules.md)

  # 自定義測試用例審查規則
  
  ## 規則 1: 標題質量
  - 標題必須具有描述性和特異性
  - 最小長度: 10 個字符
  - 不應包含模糊術語，如 "test"、"check"
  
  ## 規則 2: 測試步驟
  - 每個步驟必須有明確的操作和預期結果
  - 步驟應編號並按順序排列
  - 避免在一個步驟中組合多個操作
  

  • 分析檢查點 (test_case_analysis_checkpoints.md)

  # 自定義分析檢查點
  
  ## 獨立性評估
  - [ ] 此測試用例能否獨立運行？
  - [ ] 所有前置條件是否明確說明？
  - [ ] 是否不依賴其他測試用例？
  
  ## 自動化就緒性
  - [ ] 所有步驟是否明確無誤？
  - [ ] 技術可行性是否得到確認？
  - [ ] 是否有穩定的選擇器？
  

  • 技術規則 (mcp-zebrunner-rules.md)

  # 技術配置
  
  ## 覆蓋率閾值
  - 總體覆蓋率: 80%
  - 關鍵步驟: 95%
  - UI 驗證步驟: 85%
  
  ## 框架檢測
  **Java/TestNG**:
  - 關鍵字: @Test, TestNG, WebDriver
  - 文件模式: *Test.java, *Tests.java
  

🧪 測試你的設置

運行健康檢查

npm run test:health

測試 API 連接

npm run smoke

運行完整測試套件

npm test

運行特定類型的測試

npm run test:unit           # 快速單元測試
npm run test:integration    # API 集成測試
npm run test:e2e           # 端到端測試

🔍 故障排除

常見問題

• "Authentication failed" 或 401 錯誤：
  • ✅ 檢查你的 ZEBRUNNER_LOGIN 和 ZEBRUNNER_TOKEN
  • ✅ 驗證你的 API 令牌是否仍然有效
  • ✅ 確保你的用戶在 Zebrunner 中有適當的權限
• "Project not found" 或 404 錯誤：
  • ✅ 檢查項目密鑰的拼寫（例如，"MYAPP"，而不是 "myapp"）
  • ✅ 驗證你是否有權限訪問 Zebrunner 中的項目
  • ✅ 某些端點可能在所有 Zebrunner 實例上都不可用
• "Connection timeout" 錯誤：
  • ✅ 檢查你的 ZEBRUNNER_URL 是否正確
  • ✅ 確保你的網絡可以訪問 Zebrunner 實例
  • ✅ 嘗試在配置中增加超時時間
• MCP 集成不起作用：
  • ✅ 驗證 dist/server.js 的路徑是否正確
  • ✅ 檢查項目是否成功構建 (npm run build)
  • ✅ 確保環境變量已在 MCP 配置中設置
  • ✅ 查看 Claude Desktop/Code 日誌以獲取錯誤消息
• 規則引擎不起作用：
  • ✅ 檢查你的 .env 文件中 ENABLE_RULES_ENGINE=true
  • ✅ 驗證規則文件是否存在且內容有意義
  • ✅ 更改規則文件後重啟 MCP 服務器
  • ✅ 檢查調試日誌以獲取規則解析錯誤

調試模式

啟用詳細日誌記錄以解決問題：

DEBUG=true

這將顯示：

• API 請求和響應
• 錯誤詳細信息和堆棧跟蹤
• 性能指標
• 功能可用性
• 規則解析和驗證詳細信息

獲取幫助

1. 檢查日誌 - 啟用調試模式並查找錯誤消息
2. 測試你的連接 - 運行 npm run test:health
3. 驗證你的配置 - 仔細檢查你的 .env 文件
4. 檢查 Zebrunner 權限 - 確保你的用戶有適當的訪問權限
5. 驗證規則文件 - 確保規則文件內容有意義

🎯 示例工作流程

工作流程 1: 測試用例審查（手動 QA）

1. "Get test case PROJ-123 details"
2. "Validate test case PROJ-123"
3. "Improve test case PROJ-123 with specific suggestions"
4. "Check if test case PROJ-123 is ready for manual execution"

工作流程 2: 測試自動化（SDET）

1. "Validate test case PROJ-456 for automation readiness"
2. "Generate Java/Carina test code for PROJ-456"
3. "Analyze coverage between test case and my implementation"
4. "Get automation readiness assessment"

工作流程 3: 實現驗證（開發人員）

1. "Get test case PROJ-789 details to understand requirements"
2. "Analyze coverage for PROJ-789 against my implementation"
3. "Generate unit tests based on test case requirements"
4. "Validate implementation completeness"

工作流程 4: 質量管理（團隊負責人）

1. "Get quality metrics for all test cases in project MYAPP"
2. "Show me test cases that need improvement"
3. "Generate team quality report"
4. "Identify automation readiness across the project"

工作流程 5: 項目健康（產品經理）

1. "Get overall test coverage status for project MYAPP"
2. "Show me test execution results by platform"
3. "Generate project testing health report"
4. "Identify quality risks and improvement opportunities"

🔧 高級功能

批量操作

一次處理多個測試用例：

"Validate all test cases in suite 18708"
"Generate coverage report for all test cases in project MYAPP"
"Improve all test cases that have quality issues"

自定義輸出格式

以你需要的格式獲取數據：

"Get test cases as JSON for API integration"
"Show test suite hierarchy in markdown for documentation"
"Generate quality report in markdown for stakeholder presentation"

過濾和搜索

找到你確切需要的內容：

"Get test cases created after 2025-01-01"
"Find test cases with automation state 'Manual'"
"Show me test cases that are not ready for automation"

基於規則的分析

利用智能驗證：

"Validate test case PROJ-123 using custom rules from my-project-rules.md"
"Enhanced coverage analysis with framework-specific rules"
"Generate improvement suggestions based on team quality standards"

📚 附加文檔

📖 工具參考

• TOOLS_CATALOG.md - 🆕 所有 40 多個工具的完整目錄，包含自然語言示例
• INSTALL-GUIDE.md - 📥 分步安裝和設置指南

🧠 智能規則系統

• docs/INTELLIGENT_RULES_SYSTEM.md - 🧠 三層智能規則系統的完整指南
• docs/RULES_QUICK_REFERENCE.md - ⚡ 規則系統命令和配置的快速參考

📋 規則文件（可定製）

• test_case_review_rules.md - 🎯 核心質量標準和編寫指南
• test_case_analysis_checkpoints.md - ✅ 100 多個詳細的驗證檢查點
• mcp-zebrunner-rules.md - ⚙️ 測試生成和覆蓋率分析的技術配置

🔍 專業指南

• docs/SCREENSHOT_ANALYSIS.md - 📸 截圖下載和視覺分析指南
• change-logs.md - 📝 版本歷史和功能更新

🛠️ 功能文檔

• docs/NEW_LAUNCHER_TOOL.md - 啟動和報告工具的詳細信息
• docs/SUITE_HIERARCHY.md - 套件層次結構功能的完整指南
• docs/TEST_CASE_VALIDATION_IMPLEMENTATION.md - 測試用例驗證系統詳細信息
• docs/ENHANCED_VALIDATION_FEATURES.md - 高級驗證和改進功能
• docs/SCREENSHOT_ANALYSIS.md - 📸 截圖分析和視覺取證指南 🆕

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支
3. 進行更改並添加適當的測試
4. 確保所有測試通過：npm test
5. 提交拉取請求

📄 許可證

本項目採用 AGPL - 3.0 許可證，以確保對 MCP 服務器的所有改進都保持開源，特別是當軟件作為網絡服務部署時。

如果你修改並以用戶通過網絡與服務器交互的方式運行服務器（例如，Claude Desktop / Cursor 客戶端），你必須向這些用戶提供完整的修改後源代碼。

允許商業使用。對於閉源修改或企業許可，請聯繫作者。 詳情請參閱 LICENSE.md 文件。

🎉 你已準備就緒！

完成設置後：

1. 使用 npm run test:health 測試你的連接
2. 使用 MCP 服務器 配置你的 AI 助手
3. 開始詢問關於你的測試用例的問題！

示例初始命令：

• "List test suites for project [YOUR_PROJECT_KEY]"
• "Get test case [YOUR_TEST_CASE_KEY] details"
• "Validate test case [YOUR_TEST_CASE_KEY]"
• "Show me the test suite hierarchy"

智能規則系統將幫助確保你的測試用例符合質量標準，併為手動執行和自動化做好準備。祝你測試愉快！ 🚀