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"

智能规则系统将帮助确保你的测试用例符合质量标准，并为手动执行和自动化做好准备。祝你测试愉快！ 🚀