Mcp Zebrunner

Advanced Zebrunner MCP Server

A Model Context Protocol (MCP) server that brings advanced analytics, reporting, failure forensics, and safe TCM mutations to Zebrunner. Designed to coexist with the official Zebrunner MCP (beta) — see the "Dual-MCP setup" section below.

Tool naming: every tool on this server is registered under the canonical adv_<name> form (e.g. adv_create_test_case, adv_list_test_runs) so it never collides with the official Zebrunner MCP. The legacy names are kept as deprecated aliases so prompts/scripts that called the old names continue to work for now; aliases will be removed in the next major release.

🆕 v9.4.4 — Test-run metadata agent UX: post-mutation steering hints (discover env/config before update; import does not set badges); dual-MCP routing resource for environments vs Build/Platform; richer tool-intel for adv_manage_test_run. Builds on v9.4.3 env contract — see change-logs.md.

v9.4.3 — adv_prepare_jira_automation_plan + /jira-automation-plan prompt: Zebrunner suite → structured Jira plan; adv_manage_test_run Public API environment as { name } / { id }. See change-logs.md, TEST_PROMPTS.md §20.

v9.3.1 — TCM pagination fixes: correct get_all token walks, root_suite_id subtree scoping, honest bulk metadata. See PUBLIC_API_PAGINATION.md and change-logs.md.

v9.3.0 — Multi-PR / period test impact: change_batches[], /test-impact-period, extended /test-impact. See TEST_IMPACT_WORKFLOW.md and TEST_IMPACT_PR_PERIOD_DESIGN.md.

🆕 v9.2.7 — New adv_scaffold_test_case wizard (hybrid form/conversational) to author test cases from best practices with an automatic warn-only similar-case check, plus optional projectAliases in zebrunner-config.json so tools accept short names as well as Zebrunner project keys. See release notes.

🆕 v9.2.5 — adv_get_test_authoring_trend (TAM template 7) completes 22/22 dashboard widget MCP coverage. Hub tools, pass-rate views, period modes. See TEST_PROMPTS.md §18 and change-logs.md.

v9.2.1 — LLM-visible metrics (include_call_metrics, session breakdown), compact expansion (+19 tools), format/truncation bugfixes. See Token efficiency guide and change-logs.md.

v9.2.0 — Opt-in token/cost optimizations: format:'compact', detail:'summary', adv_batch_get_test_cases, report inline:false. Defaults unchanged. See change-logs.md.

v9.1.0 — Launch mutations: adv_rerun_launch_failures, adv_start_launch (Jenkins Build Now), plus /relaunch-regression-failures and /feature-scoped-launch prompts. See GitHub Release v9.1.0.

📖 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.

📚 Test vs Test Case vs Launch? See Terminology & Glossary — definitions, counting rules, and how metrics are calculated.

🔥 Why This Server

This is the Advanced Zebrunner MCP Server — built to go well beyond basic test case management and help QA teams work smarter and faster with AI. Compared to the official Zebrunner MCP (beta, ~70 tools spanning Public REST + Reporting/TAM/Launcher), this server provides 76 registered adv_* tools (70 inline-regression suite + 6 handler-module tools; see tools.json) and is safe to run side-by-side with the official server:

• Reporting & Analytics — dashboards, pass-rate trends, regression stability reports, runtime efficiency analysis, bug reviews, and weekly delta tracking
• Test Coverage & Analysis — coverage gaps, automation readiness scoring, and cross-suite analysis
• Intelligent Rules System — 3-tier quality rules with 100+ automated checkpoints for test case validation and improvement
• Screenshot & Video Analysis — OCR, image processing, and video analysis powered by sharp, ffmpeg, and tesseract
• MCP Resources & Prompts — @ context injection and / workflow commands for streamlined daily operations
• Multi-Transport & Multi-Auth — STDIO, Streamable HTTP, self-service OAuth, Okta SSO, and token exchange (Modes 1–5)

📑 Table of Contents

1. 🔥 Why This Server
2. 🎯 What is this tool?
3. 🧠 Intelligent Rules System

• 3.1. What Makes This Tool Special
• 3.2. How the Rules Work Together
• 3.3. Why This Matters
• 3.4. Customizing Rules for Your Project

4. 📋 Prerequisites
5. 🚀 Quick Start Guide
6. 🔧 Usage Methods

• 6.1. Method 1: Use with Claude Desktop/Code
• 6.2. Method 2: Run as standalone server
• 6.3. Method 3: Smart URL-Based Analysis 🚀

7. 🛠️ Available Tools

• 7.1. 📋 Test Case Management
• 7.2. 🌳 Test Suite Hierarchy & Organization
• 7.3. 🔧 Mutation Tools
• 7.4. 🔍 Test Coverage & Analysis
• 7.5. 🧪 Test Code Generation & Validation
• 7.6. 🚀 Launch & Execution Management
• 7.7. 📊 Reporting & Analytics
• 7.8. 🏃 Test Run Management
• 7.9. 🎯 Management-Focused Quick Commands

8. 📎 MCP Resources & Prompts (NEW)

• 8.1. Resources — @ Context Injection
• 8.2. Prompts — / Workflow Commands

9. 🎭 Role-Specific Prompts & Workflows

• 9.1. 👩‍💻 Manual QA Engineers
  • Daily Test Case Review
  • Test Case Creation & Improvement
  • Test Suite Organization
  • Coverage Analysis
• 9.2. 🤖 Test Automation Engineers & SDETs
  • Automation Readiness Assessment
  • Test Code Generation
  • Coverage Analysis & Validation
  • Framework Integration
  • Batch Automation Analysis
• 9.3. 👨‍💻 Developers
  • Test Case Understanding
  • Implementation Validation
  • Code Generation for Testing
  • Bug Analysis
• 9.4. 👔 Test Managers & Team Leads
  • Team Quality Metrics
  • Test Suite Analysis
  • Team Performance & Planning
  • Process Improvement
  • Reporting & Stakeholder Communication
• 9.5. 🏢 Project Owners & Product Managers
  • Project Health Overview
  • Feature Testing Status
  • Quality Assurance Metrics
  • Risk Assessment
  • Planning & Resource Allocation

10. 📖 Output Formats
11. ⚙️ Configuration Options
12. 🧪 Testing Your Setup
13. 🔍 Troubleshooting
14. 🎯 Example Workflows
15. 🔧 Advanced Features
16. 📚 Additional Documentation
17. 🤝 Contributing
18. 📄 License
19. 🎉 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: adv_validate_test_case and adv_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: adv_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: adv_generate_draft_test_by_key and adv_get_enhanced_test_coverage_with_rules tools

How the Rules Work Together

graph TD
    A[Test Case] --> B[adv_validate_test_case]
    B --> C[test_case_review_rules.md]
    B --> D[test_case_analysis_checkpoints.md]
    B --> E[Validation Result + Issues]
    
    E --> F[adv_improve_test_case]
    F --> G[AI-Powered Improvements]
    
    A --> H[adv_generate_draft_test_by_key]
    H --> I[mcp-zebrunner-rules.md]
    H --> J[Generated Test Code]
    
    A --> K[adv_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:

Option A: Clone from repository (recommended)

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

Method 1: Use with Claude Desktop/Code (Recommended)

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

🤝 Dual-MCP setup (official zebrunner + Advanced)

Zebrunner now offers an official hosted MCP (beta) at https://{workspace}.zebrunner.com/api/mcp. It is safe to run both servers in the same Cursor / Claude session: every tool on this server is exposed under the adv_<name> prefix, so it never collides with the official tools.

Example .cursor/mcp.json:

{
  "mcpServers": {
    "zebrunner": {
      "url": "https://your-workspace.zebrunner.com/api/mcp",
      "headers": {
        "X-Zebrunner-Username": "your.name@company.com",
        "X-Zebrunner-Api-Token": "<your-zebrunner-api-token>"
      }
    },
    "mcp-zebrunner": {
      "command": "npx",
      "args": ["-y", "mcp-zebrunner"],
      "env": {
        "ZEBRUNNER_URL": "https://your-workspace.zebrunner.com/api/public/v1",
        "ZEBRUNNER_LOGIN": "your.name@company.com",
        "ZEBRUNNER_TOKEN": "<your-zebrunner-api-token>"
      }
    }
  }
}

Rule of thumb when both are connected:

Use zebrunner (official) for	Use mcp-zebrunner (Advanced) for
list_projects, shared steps, test run replace/close, custom field create	Failure forensics, runtime + flakiness analytics
Server-side filter DSL; file upload + screenshot content in triage	Reporting, dashboards, regression analyzers
Bulk launch/test comments, issue linking, launcher/preset CRUD, launch_tests	Preview/confirm TCM mutations; Jenkins Build Now / rerun failures

Inside chat, ask adv_about_mcp_tools with mode: "routing" or open the zebrunner://mcp-routing resource for the full live-generated diff and routing table.

🛠️ Available Tools

Once connected, you can use these tools through natural language in your AI assistant. This section highlights all 76 adv_* tools (see tools.json) organized by category. For the complete catalog with natural-language examples for every tool, see TOOLS_CATALOG.md.

Dashboard widgets: All 22 Zebrunner dashboard templates have MCP coverage (v9.2.5). See docs/TEST_PROMPTS.md §18 for example prompts and npm run test:api verification.

Token-efficient reads

Large TCM exports can consume significant context. Use these opt-in parameters (defaults stay backward-compatible). Full guide: docs/TOKEN_EFFICIENCY.md.

Technique	Example	When to use
format: 'compact'	adv_get_all_tcm_test_cases_by_project with format:'compact'	Minified JSON (~22% smaller than pretty json)
detail: 'summary'	adv_get_test_cases_by_suite_smart with detail:'summary'	After filtering — returns id, key, title, priority, automationState, webUrl only
adv_batch_get_test_cases	{ case_keys: ["MCP-1","MCP-2"], detail:"summary", format:"compact" }	Fetch a shortlist without N round-trips
adv_generate_report inline: false	Writes HTML/PNG to disk, returns paths	Huge dashboards in chat clients
count_only: true	Any bulk TCM/suite read	Metrics without payload
Env flags (off)	MCP_COMPACT_DEFAULTS=true, MCP_SUMMARY_DEFAULTS=true	Server-wide default flips after eval passes

Workflow: list/filter with detail:'summary' + format:'compact' → adv_get_test_case_by_key for full body (steps, preconditions) before create/update.

Example prompts for your assistant:

• "List test cases in project MCP with summary detail and compact JSON."
• "Fetch MCP-1 and MCP-2 in one batch call with summary and compact format."
• "Generate a quality dashboard for MCP with inline false — save to disk."

Tool naming: All tools are exposed as adv_<name> (e.g. adv_get_test_case_by_key). Use these names in prompts, scripts, and when both the official and Advanced MCP are connected. Legacy short names (get_test_case_by_key, etc.) are deprecated and only registered when ZEBRUNNER_REGISTER_LEGACY_ALIASES=true.

📋 Test Case Management

Core Test Case Tools

Tool	Description	Example Usage	Best For
adv_get_test_case_by_key	Get detailed test case information	"Get test case MCP-123 details"	All roles
adv_batch_get_test_cases	Fetch multiple cases by key (partial success)	"Get MCP-1 and MCP-2 with summary detail"	All roles
adv_get_test_cases_advanced	Advanced filtering with automation states, dates	"Get test cases created after 2025-01-01 with automation state 'Manual'"	QA, SDETs
adv_get_test_cases_by_automation_state	Filter by specific automation states	"Show me all 'Not Automated' test cases in project MCP"	SDETs, Managers
adv_get_test_case_by_title	Search test cases by title (partial match)	"Find test cases with title containing 'login functionality'"	All roles
adv_get_test_case_by_filter	Advanced filtering by suite, dates, priority, automation state	"Get test cases from suite 491 created after 2025-01-01 with high priority"	QA, Managers
adv_get_automation_states	List available automation states	"What automation states are available for project MCP?"	All roles
adv_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
adv_get_all_tcm_test_cases_by_project	Get ALL test cases (handles pagination)	"Get all test cases for project MCP"	Managers, Leads
adv_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
adv_get_test_cases_by_suite_smart	Smart suite test case retrieval with root/child auto-detection	"Get test cases from suite 18824 in project MCP using smart mode"	QA, Analysts

Test Case Change History

Most test case tools support optional change history enrichment — fetching the audit log of modifications for each test case. This is useful for understanding when steps were changed, when automation state transitioned, or when a test case was deprecated.

Parameter	Type	Default	Description
include_history	boolean	false	Attach a history array of parsed change entries to each test case
history_filter	steps_only	events_only	all
history_limit	number (1–100)	20	Max history entries per test case

Supported on: adv_get_test_case_by_key, adv_get_test_cases_advanced, adv_get_test_cases_by_automation_state, adv_get_test_case_by_title, adv_get_test_case_by_filter, adv_get_all_tcm_test_cases_by_project, adv_get_test_cases_by_suite_smart

Example prompts:

• "Get test case MCP-29 with change history" → sets include_history=true
• "Show me MCP-29 history, events only" → sets include_history=true, history_filter='events_only'
• "Get all automated test cases with their last 5 changes" → sets include_history=true, history_limit=5

Detected events: became_automated, became_manual, became_deprecated, became_undeprecated, steps_changed, preconditions_changed, postconditions_changed, and dynamically generated became_<state_name> for any project-specific automation state.

🌳 Test Suite Hierarchy & Organization

Suite Management

Tool	Description	Example Usage	Best For
adv_list_test_suites	List suites with pagination	"List test suites for project MCP"	All roles
adv_get_suite_hierarchy	Hierarchical tree view	"Show me the hierarchy of test suites with depth 3"	Managers, QA
adv_get_root_suites	Get top-level suites	"Show me all root suites for project MCP"	Managers
adv_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
adv_get_tcm_suite_by_id	Get suite by ID (simple: fast direct API, full: hierarchy-enriched)	"Show me suite 20421 in project MCP"	All roles
adv_get_tcm_test_suites_by_project	Comprehensive suite listing	"Get all suites for project MCP with hierarchy"	Managers
adv_get_all_tcm_test_case_suites_by_project	Get all TCM test case suites with pagination	"Get all TCM test case suites for project MCP"	Managers, Analysts
adv_get_root_id_by_suite_id	Find root suite for any suite	"What's the root suite for suite 12345?"	Analysts

🔧 Mutation Tools

Safety Model: Every mutation tool follows a two-call confirmation gate. The first call returns a preview; only after user approval should confirm: true be passed to execute the mutation. All mutations are audit-logged to ~/.mcp-zebrunner-audit.jsonl. Use dry_run: true for raw payload inspection.

Next-step steering (v7.2.2): After every successful mutation, the server appends a Tip: block guiding the LLM to the most useful next action (e.g., "validate quality", "publish the draft", "populate the test run"). Hints are conditional -- they are suppressed when redundant. For example, the quality-check hint is omitted if review: true was already used. Created test cases are always forced to draft=true, and the hint always reminds the LLM to publish via adv_update_test_case. This approach is inspired by the Strands Agents steering pattern and delivers just-in-time guidance without bloating system prompts.

Suite Mutations

Tool	Description	Example Usage	Best For
adv_create_test_suite	Create a new Test Suite	"Create root suite 'Payments' in project MCP"	QA, Managers
adv_update_test_suite	Update an existing Test Suite (full PUT)	"Rename suite 18697 to 'Login & Registration'"	QA, Managers

Test Case Mutations

Tool	Description	Example Usage	Best For
adv_create_test_case	Create a new Test Case with runtime validation of priorities, automation states, and custom fields. Accepts {file_path} in attachments. Optional source_case_key to pre-populate from an existing test case.	"Create test case 'Verify login' in suite 17470 for project MCP"	QA, SDETs
adv_update_test_case	Partially update a Test Case by ID or key (PATCH). Accepts {file_path} in attachments for local file upload.	"Attach /Users/me/screenshot.png to test case MCP-42"	QA, SDETs

🔍 Test Coverage & Analysis

Test Impact (PR / code changes) (v9.2.8)

Tool	Description	Example Usage	Best For
adv_analyze_test_impact	Rank Zebrunner cases affected by code changes from compact semantic context	"Analyze test impact for diary edit + serving size changes on PROJ2"	Developers, SDETs

Use the /test-impact MCP prompt (optional pr_url) for guided workflow. See TEST_IMPACT_WORKFLOW.md. Configure repositoryProjectMap via .env.example.

Coverage Analysis

Tool	Description	Example Usage	Best For
adv_get_test_coverage_by_test_case_steps_by_key	Analyze implementation coverage	"Analyze coverage for MCP-123 against this code: [paste code]"	Developers, SDETs
adv_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
adv_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
adv_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
adv_generate_draft_test_by_key	Generate test code with framework detection	"Generate Java/Carina test for MCP-123 based on this implementation"	SDETs, Developers
adv_validate_test_case	Quality validation with improvement	"Validate test case MCP-123 and suggest improvements"	QA, Managers
adv_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
adv_get_launch_details	Comprehensive launch information; optional includeJobParameters for Jenkins Build Now discovery	"Get launch details for launch 118685 with job parameters"	Managers, Leads, SDETs
adv_rerun_launch_failures	🆕 v9.1.0 Rerun failed/aborted tests for one or many launches (preview/confirm)	"Rerun failures for launch 132522 in project android"	Managers, SDETs
adv_start_launch	🆕 v9.1.0 Trigger Jenkins Build Now (not Launch Launchers); preview/confirm	"Build now regression for android milestone 26.19.0 build 50977"	Managers, SDETs
adv_get_launch_summary	Quick launch overview	"Show me summary for launch 118685"	Managers
adv_get_all_launches_for_project	List individual launch executions with pagination	"List launches for project MCP from last month"	Managers, Leads
adv_get_all_launches_with_filter	Search launches by milestone/build/name	"Find launches for milestone 2.1.0 and build 'mcp-app-2.1.0'"	Managers, Leads
adv_generate_weekly_regression_stability_report	Weekly regression stability report with WoW delta, linked issues, and strict Jira-ready output. Supports launch list or build-based auto-discovery (version-segment build lookup with launch.build validation when needed).	"Weekly stability report for MCP: (120906 vs 120814), (120901 vs 120809)" or "Weekly stability report for builds 9117 vs 48886"	Managers, Leads
adv_analyze_regression_runtime	Regression Runtime Efficiency — per-launch elapsed time, attempt/re-run breakdown, configurable duration classification (Short/Medium/Long), dual metrics for both Tests and Test Cases (Average Runtime, WRI), duration distribution with test case counts, and baseline comparison with delta tracking.	"Analyze regression runtime for the iOS project on the latest milestone. Show WRI and WRI per test case." or "Compare runtime for latest vs previous milestone"	Managers, Leads, SDETs

adv_analyze_regression_runtime — Usage Examples:

• "Analyze regression runtime for the iOS project on the latest milestone. Show both average runtime per test and per test case, plus WRI and WRI per test case."
• "Run regression runtime analysis for all three projects on their latest milestones. Compare how many test cases fall into Short vs Medium vs Long buckets per team."
• "Analyze regression runtime for the Android project, latest vs previous milestone. Show WRI and WRI per test case for both. Has efficiency improved or degraded?"
• "Analyze regression runtime with medium_threshold_seconds: 120 and long_threshold_seconds: 300. Show which tests fall into each bucket."
• "What is the average time cost per test case in each duration bucket? Are long-running tests covering proportionally more test cases?"

📊 Reporting & Analytics

Test Failure Analysis 🆕 Game Changer

Tool	Description	Example Usage	Best For
adv_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
adv_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
adv_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! adv_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 adv_get_test_execution_history
• 🔄 Compare with last passed: New compareWithLastPassed parameter in adv_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
adv_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
adv_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 adv_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
adv_get_platform_results_by_period	Aggregated test results, pass rate, and statistics for a project over a time period	"Get results for MCP during last 7 days" or "Show pass rate for MCP"	Managers, Leads
adv_get_top_bugs	Most frequent defects	"Show me top 10 bugs from last week"	Managers, Developers
adv_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
adv_get_bug_failure_info	Comprehensive failure info by hashcode (alternative to auto-fetch)	"Get failure info for hashcode 1051677506"	Developers, SDETs
adv_get_project_milestones	Available milestones	"Get all milestones for project MCP"	Managers, PMs

Period behavior for reporting widgets: period is passed to Zebrunner widgets as-is (for example Today, Month, Last 30 Days). If a selected widget does not support a specific period label, the API will return an error.

Project Discovery

Tool	Description	Example Usage	Best For
adv_get_available_projects	Discover all accessible projects	"What projects can I access?"	All roles
adv_test_reporting_connection	Test API connectivity	"Test my connection to Zebrunner"	All roles
adv_about_mcp_tools	Summarize tools, prompts, resources, or show session metrics. Modes: summary, tool, prompts, resources, metrics	"Using Zebrunner MCP make a summary of all tools with examples" or "Show me tool usage metrics for this session"	All roles

🏃 Test Run Management

Public API Test Runs ⭐ Powerful for Analysis

Tool	Description	Example Usage	Best For
adv_list_test_runs	Advanced test run filtering	"Get test runs from last 30 days with status 'FAILED'"	Managers, SDETs
adv_get_test_run_by_id	Detailed test run information	"Get details for test run 12345"	Managers, QA
adv_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
adv_get_test_run_result_statuses	Available result statuses	"What result statuses are configured for project MCP?"	QA, SDETs
adv_get_test_run_configuration_groups	Configuration options	"Show me configuration groups for project MCP"	SDETs, Leads

📎 MCP Resources & Prompts (NEW)

Full guide: docs/RESOURCES_AND_PROMPTS.md — detailed usage, examples, reference tables, and contributor guide.

In addition to tools, the server provides 15 resources and 22 MCP prompts (/pass-rate, /jira-automation-plan, etc.) that improve discoverability and automate complex workflows.

Resources — @ Context Injection

Resources are read-only reference data you attach to your conversation via the @ menu. They help the AI use exact parameter values instead of guessing.

---

View the full README on GitHub