m

mcp-zebrunner

@maksimsarychau/mcp-zebrunner
0 Stars 166 次浏览 maksimsarychau 更新于 2026-08-23
该服务暂未提供标准配置,请参考 README 手动接入

服务介绍

Zebrunner MCP Server

version

A Model Context Protocol (MCP) server that integrates with Zebrunner Test Case Management to help QA teams manage test cases, test suites, and test execution data through AI assistants like Claude.

Need help with installation? Check out our Step-by-Step Install Guide for detailed setup instructions.

Installing via npm? See our MCP NPM Installation Guide for Claude Desktop, Cursor, IntelliJ IDEA, and ChatGPT Desktop configuration.

Table of Contents

  1. What is this tool?
  2. Intelligent Rules System
  3. Prerequisites
  4. Quick Start Guide
  5. Usage Methods
  6. Available Tools
  7. Role-Specific Prompts & Workflows
  8. Output Formats
  9. Configuration Options
  10. Testing Your Setup
  11. Troubleshooting
  12. Example Workflows
  13. Advanced Features
  14. Additional Documentation
  15. Contributing
  16. License
  17. You're Ready!

What is this tool?

This tool allows you to:

  • Retrieve test cases and test suites from Zebrunner
  • Analyze test coverage and generate test code
  • Get test execution results and launch details
  • Validate test case quality with automated checks using intelligent rules
  • Generate reports and insights from your test data
  • Improve test cases with AI-powered suggestions and automated fixes

All through natural language commands in AI assistants!

Back to top

Intelligent Rules System

What Makes This Tool Special

Our MCP server includes a sophisticated 3-tier rules system that transforms how you work with test cases:

Test Case Review Rules (test_case_review_rules.md)

  • Purpose: Core quality standards and writing guidelines
  • What it does: Defines fundamental principles for writing high-quality test cases
  • Key areas: Independence, single responsibility, comprehensive preconditions, complete step coverage
  • Used by: validate_test_case and improve_test_case tools

Test Case Analysis Checkpoints (test_case_analysis_checkpoints.md)

  • Purpose: Detailed validation checklist with 100+ checkpoints
  • What it does: Provides granular validation criteria for thorough test case analysis
  • Key areas: Structure validation, automation readiness, platform considerations, quality assurance
  • Used by: validate_test_case for comprehensive scoring and issue detection

MCP Zebrunner Rules (mcp-zebrunner-rules.md)

  • Purpose: Technical configuration for test generation and coverage analysis
  • What it does: Defines framework detection patterns, code templates, and coverage thresholds
  • Key areas: Framework detection, test generation templates, coverage thresholds, quality standards
  • Used by: generate_draft_test_by_key and get_enhanced_test_coverage_with_rules tools

How the Rules Work Together

graph TD
    A[Test Case] --> B[validate_test_case]
    B --> C[test_case_review_rules.md]
    B --> D[test_case_analysis_checkpoints.md]
    B --> E[Validation Result + Issues]
    
    E --> F[improve_test_case]
    F --> G[AI-Powered Improvements]
    
    A --> H[generate_draft_test_by_key]
    H --> I[mcp-zebrunner-rules.md]
    H --> J[Generated Test Code]
    
    A --> K[get_enhanced_test_coverage_with_rules]
    K --> I
    K --> L[Coverage Analysis + Rules Validation]

Why This Matters

  1. Consistency: All team members follow the same quality standards
  2. Automation: Reduce manual review time with automated validation
  3. Learning: New team members learn best practices through AI feedback
  4. Customization: Adapt rules to your project's specific needs
  5. Continuous Improvement: AI suggests improvements based on proven patterns

Customizing Rules for Your Project

You can customize any of the three rules files:

# Copy default rules to customize
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

# Use custom rules in validation
"Validate test case PROJ-123 using custom rules from my-project-review-rules.md"

Example customizations:

  • Mobile projects: Add mobile-specific validation rules
  • API projects: Focus on API testing patterns and data validation
  • Different frameworks: Customize code generation templates
  • Company standards: Align with your organization's testing guidelines

Back to top

Prerequisites

What you need to know

  • Basic command line usage (opening terminal, running commands)
  • Your Zebrunner credentials (login and API token)
  • Basic understanding of test management (test cases, test suites)

Software requirements

  • Node.js 18 or newer - Download here
  • npm (comes with Node.js)
  • Access to a Zebrunner instance with API credentials

How to check if you have Node.js

Open your terminal/command prompt and run:

node --version
npm --version

If you see version numbers, you're ready to go!

Back to top

Quick Start Guide

Want more detailed instructions? Check out our More Detailed Step-by-step Install Guide with troubleshooting tips and platform-specific instructions.

Step 1: Get the code

Choose one of these methods:

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

Option B: Download and extract

Download the project files and extract them to a folder.

Step 2: Install dependencies

npm install

Step 3: Configure your Zebrunner connection

Create a .env file in the project folder with your Zebrunner details:

# Your Zebrunner instance URL (without trailing slash)
ZEBRUNNER_URL=https://your-company.zebrunner.com/api/public/v1

# Your Zebrunner login (usually your email)
ZEBRUNNER_LOGIN=your.email@company.com

# Your Zebrunner API token (get this from your Zebrunner profile)
ZEBRUNNER_TOKEN=your_api_token_here

# Optional: Enable debug logging (default: false)
DEBUG=false

# Optional: Enable intelligent rules system (auto-detected if rules file exists)
ENABLE_RULES_ENGINE=true

How to get your Zebrunner API token:

  1. Log into your Zebrunner instance
  2. Go to your profile settings
  3. Find the "API Access" section
  4. Generate a new API token
  5. Copy the token to your .env file

Step 4: Build the project

npm run build

Step 5: Test your connection

npm run test:health

If you see " Health check completed", you're ready to go!

Updating to New Version

Check current version

# Check your current version
npm run version
# or manually check package.json
cat package.json | grep '"version"'

Update steps

# 1. Pull latest changes from master branch
git pull origin master

# 2. Install any new dependencies
npm install

# 3. Rebuild the project
npm run build

# 4. Test your connection (requires valid .env file)
npm run test:health

Important Notes:

  • Your .env file must be properly configured for the health check to work
  • Restart Claude Desktop/Code after updating to reload the MCP server
  • Check release notes for any breaking changes before updating

If the health check fails, verify your .env configuration and Zebrunner credentials.

Back to top

Usage Methods

Add this configuration to your Claude Desktop or Claude Code settings. Important: You must use the full absolute path to your project folder.

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

Example paths:

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

Alternative: Command Line Integration (Claude Code)

You can also add the server using the command line:

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

Important: Replace /full/absolute/path/to/mcp-zebrunner/ with the actual full path to your project folder.

Method 2: Run as standalone server

Development mode (with auto-reload)

npm run dev

Production mode

npm start

Method 3: Smart URL-Based Analysis

NEW in v5.4.1+: Claude can automatically detect Zebrunner URLs and analyze them with optimal settings!

Just paste a Zebrunner URL in your conversation, and Claude will automatically:

  • Parse the URL to extract project, launch, and test IDs
  • Call the appropriate analysis tool
  • Use recommended settings (videos, screenshots, AI analysis enabled)

Supported URL Patterns

1. Test Analysis URLs

https://your-workspace.zebrunner.com/projects/PROJECT/automation-launches/LAUNCH_ID/tests/TEST_ID

What happens:

  • Claude automatically calls analyze_test_failure
  • Extracts: projectKey, testRunId (launch ID), testId
  • Enables: includeVideo: true, analyzeScreenshotsWithAI: true, all diagnostics

Example:

User: "Analyze https://your-workspace.zebrunner.com/projects/MCP/automation-launches/120911/tests/5455386"

Claude automatically calls:
{
  projectKey: "MCP",
  testRunId: 120911,
  testId: 5455386,
  includeVideo: true,
  analyzeScreenshotsWithAI: true,
  includeLogs: true,
  includeScreenshots: true,
  analyzeSimilarFailures: true,
  screenshotAnalysisType: "detailed",
  format: "detailed"
}

2. Launch Analysis URLs

https://your-workspace.zebrunner.com/projects/PROJECT/automation-launches/LAUNCH_ID

What happens:

  • Claude automatically calls detailed_analyze_launch_failures
  • Extracts: projectKey, testRunId (launch ID)
  • Enables: includeScreenshotAnalysis: true, comprehensive analysis

Example:

User: "Analyze https://your-workspace.zebrunner.com/projects/MCP/automation-launches/120911"

Claude automatically calls:
{
  projectKey: "MCP",
  testRunId: 120911,
  filterType: "without_issues",
  includeScreenshotAnalysis: true,
  screenshotAnalysisType: "detailed",
  format: "summary",
  executionMode: "sequential"
}

Advanced Usage

Override Default Settings

Claude understands natural language overrides:

User: "Analyze https://...url... but without screenshots"
 Claude sets: analyzeScreenshotsWithAI: false

User: "Analyze https://...url... in jira format"
 Claude sets: format: "jira"

User: "Quick analysis of https://...url..."
 Claude sets: format: "summary", screenshotAnalysisType: "basic"

Multiple URLs

Analyze multiple tests/launches in one request:

User: "Compare these failures:
https://your-workspace.zebrunner.com/projects/MCP/automation-launches/120911/tests/5455386
https://your-workspace.zebrunner.com/projects/MCP/automation-launches/120911/tests/5455390"

 Claude analyzes both sequentially and compares results

Cross-Workspace Support

URLs from different workspaces will show a warning but still attempt analysis:

User: "Analyze https://other-workspace.zebrunner.com/..."
 Claude warns: "URL is from 'other-workspace.zebrunner.com' but configured workspace is 'your-workspace.zebrunner.com'"
 Proceeds with analysis using available credentials

URL Pattern Reference

Component Example Extracted As Used In Tool
Workspace your-workspace.zebrunner.com Validation only N/A
Project Key MCP projectKey All tools
Launch ID 120911 testRunId All tools
Test ID 5455386 testId analyze_test_failure only

Why Use URL-Based Analysis?

Faster: No need to manually specify IDs
Convenient: Copy-paste URLs directly from Zebrunner UI
Optimized: Automatic use of recommended settings
Smart: Claude detects intent and adjusts parameters
Flexible: Natural language overrides work seamlessly

Pro Tips

  1. Direct from Zebrunner: Copy URL directly from your browser while viewing a test/launch
  2. Batch Analysis: Paste multiple URLs separated by newlines
  3. Custom Settings: Add natural language instructions to override defaults
  4. Quick Checks: URLs work great for quick "what happened here?" questions
  5. Reports: Combine with format requests: "Generate JIRA ticket for https://...url..."

Back to top

Available Tools

Once connected, you can use these tools through natural language in your AI assistant. Here's a comprehensive reference of all 33+ available tools organized by category:

Test Case Management

Core Test Case Tools

Tool Description Example Usage Best For
get_test_case_by_key Get detailed test case information "Get test case MCP-123 details" All roles
get_test_cases_advanced Advanced filtering with automation states, dates "Get test cases created after 2024-01-01 with automation state 'Manual'" QA, SDETs
get_test_cases_by_automation_state Filter by specific automation states "Show me all 'Not Automated' test cases in project MCP" SDETs, Managers
get_test_case_by_title Search test cases by title (partial match) "Find test cases with title containing 'login functionality'" All roles
get_test_case_by_filter Advanced filtering by suite, dates, priority, automation state "Get test cases from suite 491 created after 2024-01-01 with high priority" QA, Managers
get_automation_states List available automation states "What automation states are available for project MCP?" All roles
get_automation_priorities List available priorities with IDs "Show me all priority levels for project MCP" All roles

Batch Test Case Operations

Tool Description Example Usage Best For
get_all_tcm_test_cases_by_project Get ALL test cases (handles pagination) "Get all test cases for project MCP" Managers, Leads
get_all_tcm_test_cases_with_root_suite_id All test cases with hierarchy info "Get all test cases with their root suite information" Analysts

Test Suite Hierarchy & Organization

Suite Management

Tool Description Example Usage Best For
list_test_suites List suites with pagination "List test suites for project MCP" All roles
get_suite_hierarchy Hierarchical tree view "Show me the hierarchy of test suites with depth 3" Managers, QA
get_root_suites Get top-level suites "Show me all root suites for project MCP" Managers
get_all_subsuites Get all child suites "Get all subsuites from root suite 18697" QA, Analysts

Suite Analysis Tools

Tool Description Example Usage Best For
get_tcm_suite_by_id Find specific suite by ID "Get details for suite 17470" All roles
get_tcm_test_suites_by_project Comprehensive suite listing "Get all suites for project MCP with hierarchy" Managers
get_root_id_by_suite_id Find root suite for any suite "What's the root suite for suite 12345?" Analysts

Test Coverage & Analysis

Coverage Analysis

Tool Description Example Usage Best For
get_test_coverage_by_test_case_steps_by_key Analyze implementation coverage "Analyze coverage for MCP-123 against this code: [paste code]" Developers, SDETs
get_enhanced_test_coverage_with_rules Rules-based coverage analysis "Enhanced coverage analysis for MCP-123 with framework detection" SDETs, Leads

Duplicate Analysis

Tool Description Example Usage Best For
analyze_test_cases_duplicates Find and group similar test cases by step similarity "Analyze suite 12345 for duplicates with 80% similarity threshold" QA Managers, SDETs
analyze_test_cases_duplicates_semantic Advanced semantic analysis with LLM-powered step clustering "Semantic analysis of suite 12345 with step clustering and medoid selection" Senior QA, Test Architects

** Clickable Links Feature**: Both duplicate analysis tools support clickable links to Zebrunner web UI:

  • Add include_clickable_links: true to make test case keys clickable in markdown output
  • JSON/DTO formats automatically include webUrl fields when enabled
  • Links are generated from your ZEBRUNNER_URL environment variable
  • Example: "Analyze suite 17585 for duplicates with clickable links enabled"

Test Code Generation & Validation

AI-Powered Tools

Tool Description Example Usage Best For
generate_draft_test_by_key Generate test code with framework detection "Generate Java/Carina test for MCP-123 based on this implementation" SDETs, Developers
validate_test_case Quality validation with improvement "Validate test case MCP-123 and suggest improvements" QA, Managers
improve_test_case Dedicated improvement tool "Improve test case MCP-123 with specific suggestions" QA, SDETs

Launch & Execution Management

Launch Operations Essential for Managers

Tool Description Example Usage Best For
get_launch_details Comprehensive launch information "Get launch details for launch 118685" Managers, Leads
get_launch_summary Quick launch overview "Show me summary for launch 118685" Managers
get_all_launches_for_project All launches with pagination "Get all launches for project MCP from last month" Managers, Leads
get_all_launches_with_filter Filter by milestone/build "Get launches for milestone 2.1.0 and build 'mcp-app-2.1.0'" Managers, Leads

Reporting & Analytics

Test Failure Analysis Game Changer

Tool Description Example Usage Best For
analyze_test_failure Deep forensic analysis of failed tests with logs, screenshots, error classification, and recommendations. NEW in v5.11.0: Compare with last passed execution! Shows what changed (logs, duration, environment). Also: format: 'jira' generates ready-to-paste Jira tickets with auto-priority, labels, and clickable video links! "Analyze test failure 5451420 in launch 120806 and compare with last passed execution" QA Engineers, SDETs, Managers
get_test_execution_history NEW in v5.11.0! Track test execution trends across launches. View pass/fail history, find last passed execution, calculate pass rate. Critical Detection: Highlights when test failed in all recent runs! "Show execution history for test 5478492" or "Has test 5478492 been failing consistently?" QA Engineers, SDETs, Managers
detailed_analyze_launch_failures Enhanced v4.12.1 Analyze failures WITHOUT linked issues with Claude-level intelligence + Jira format support. Auto-deep-dive with executive summary, timeline, patterns, priorities. NEW: Generate Jira-ready tickets for entire launches! "Analyze failures in launch 120806" or with format: 'jira' QA Managers, SDETs, Team Leads

FIXED in v5.2.4! Improved Reliability & Video Links

  • ** Video URLs fixed**: Now uses test-sessions API (/api/reporting/v1/launches/{id}/test-sessions) for reliable video artifact extraction
  • ** Comprehensive error handling**: Gracefully handles missing screenshots/logs (returns empty arrays instead of throwing)
  • ** No more "no result received" errors**: All API calls have proper try-catch blocks with fallbacks
  • ** Better debugging**: Enhanced logging when debug: true is enabled in config
  • ** Schema updates**: Supports both old and new API structures for backward compatibility

NEW in v4.12.1! Jira-Ready Ticket Format

  • Use format: 'jira' to generate ready-to-paste Jira tickets
  • Auto-calculated priority based on stability and impact
  • Smart labels: test-automation, locator-issue, flaky-test, etc.
  • Complete Jira markup: Tables, panels, code blocks, clickable links
  • ** Prominent video links**: Beautiful panels + links section
  • Copy-paste ready: No manual formatting needed
  • Saves 5-10 minutes per ticket with consistent quality

Enhanced in v4.11.1! detailed_analyze_launch_failures provides automatic deep synthesis like Claude would manually provide:

  • ** Executive Summary**: Key findings, patterns, and stability indicators
  • ** Timeline Analysis**: When failures first appeared, progression tracking
  • ** Pattern Analysis**: Groups by root cause with affected tests and stability %
  • ** Priority-Based Recommendations**: HIGH / MEDIUM / LOW with impact analysis
  • ** Enhanced Test Details**: Full error messages, stack traces, timestamps
  • ** Smart Follow-up Questions**: Guides next investigation steps
  • Smart filtering: Analyzes only tests WITHOUT linked issues by default
  • Optional AI screenshot analysis for all tests
  • No manual follow-up needed - get complete picture in one call!

NEW in v5.11.0! Test Execution History & Comparison

  • ** Track execution trends**: View pass/fail history across launches with get_test_execution_history
  • ** Compare with last passed**: New compareWithLastPassed parameter in analyze_test_failure
    • Compare logs (new errors detection)
    • Compare duration (performance regression)
    • Compare environment (device/platform changes)
    • Compare screenshots (visual differences)
  • ** Critical detection**: Automatically highlights when test failed in all recent executions
  • ** Regression analysis**: See exactly what changed between passed and failed runs
  • ** Pass rate metrics**: Calculate test stability over time
  • See TOOLS_CATALOG.md for example prompts!

Screenshot Analysis & Visual Forensics Enhanced in v4.11.0

Tool Description Example Usage Best For
download_test_screenshot Download protected screenshots from Zebrunner with authentication "Download screenshot from https://your-workspace.zebrunner.com/files/abc123 for test 5451420" QA Engineers, Automation Engineers
analyze_screenshot Visual analysis with OCR, UI detection, and Claude Vision "Analyze screenshot https://your-workspace.zebrunner.com/files/abc123 with OCR and detailed analysis" QA Engineers, SDETs, Developers

Enhanced! Screenshot analysis now integrated directly into analyze_test_failure and analyze_launch_failures - no need to call separately! See Screenshot Analysis Guide for details.

Platform & Results Analysis Critical for Management

Tool Description Example Usage Best For
get_platform_results_by_period Test results by platform/period "Get iOS test results for the last 7 days" Managers, Leads
get_top_bugs Most frequent defects "Show me top 10 bugs from last week" Managers, Developers
get_bug_review Detailed bug review with failure analysis, priority breakdown, and automatic detail fetching "Get bug review with full failure details for top 10 bugs" Managers, QA, Developers
get_bug_failure_info Comprehensive failure info by hashcode (alternative to auto-fetch) "Get failure info for hashcode 1051677506" Developers, SDETs
get_project_milestones Available milestones "Get all milestones for project MCP" Managers, PMs

Project Discovery

Tool Description Example Usage Best For
get_available_projects Discover all accessible projects "What projects can I access?" All roles
test_reporting_connection Test API connectivity "Test my connection to Zebrunner" All roles

Test Run Management

Public API Test Runs Powerful for Analysis

Tool Description Example Usage Best For
list_test_runs Advanced test run filtering "Get test runs from last 30 days with status 'FAILED'" Managers, SDETs
get_test_run_by_id Detailed test run information "Get details for test run 12345" Managers, QA
list_test_run_test_cases Test cases in a specific run "Show me all test cases in test run 12345" QA, Analysts

Configuration Management

Tool Description Example Usage Best For
get_test_run_result_statuses Available result statuses "What result statuses are configured for project MCP?" QA, SDETs
get_test_run_configuration_groups Configuration options "Show me configuration groups for project MCP" SDETs, Leads

Management-Focused Quick Commands

** Daily Standup Reports**

# Get yesterday's results
"Get platform results for last 7 days for project MCP"

# Check recent failures  
"Show me top 5 bugs from last week"

# Review recent launches
"Get all launches for project MCP from last 3 days"

** Test Suite Optimization**

# Basic duplicate analysis
"Analyze suite 12345 for duplicates with 80% similarity threshold"

# Advanced semantic analysis with step clustering
"Semantic analysis of suite 12345 with 85% step clustering and medoid selection"

# Analyze specific test cases for duplicates
"Analyze test cases MCP-123, MCP-124, MCP-125 for duplicates"

# Project-wide duplicate analysis (use with caution - large datasets)
"Analyze project MCP for test case duplicates with 85% similarity"

# Get detailed similarity matrix with pattern types
"Analyze suite 12345 for duplicates with similarity matrix included"

# Two-phase clustering with semantic insights
"Semantic duplicate analysis with step clustering threshold 90% and insights enabled"

# Enable clickable links for easy navigation
"Analyze suite 17585 for duplicates with clickable links enabled"

** Weekly Management Reports**

# Comprehensive project health
"Get all launches for project MCP with milestone filter"

# Platform performance analysis
"Get iOS and Android test results for the last month"

# Quality metrics
"Get all test cases by automation state for project MCP"

** Milestone & Release Planning**

# Milestone tracking
"Get project milestones for MCP with completion status"

# Build-specific results
"Get launches for build 'mcp-app-2.1.0-release' and milestone '2.1.0'"

# Release readiness
"Get automation readiness for all test cases in project MCP"

** Issue Analysis & Troubleshooting**

# Bug analysis
"Show me top 10 most frequent bugs with issue links"

# Failure investigation
"Get test run 12345 details with all test cases"

# Platform-specific issues
"Get Android test results for last 7 days with failure analysis"

Back to top

Role-Specific Prompts & Workflows

Manual QA Engineers

Daily Test Case Review

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

Test Case Creation & Improvement

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

Test Suite Organization

"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 con

相关 MCP 服务