dipanjanc-dev/reportportal-mcp-server-py

ReportPortal MCP Server (Python Implementation)

A Python implementation of the official ReportPortal MCP Server, providing AI assistants with direct access to ReportPortal test execution data through natural language queries.

Overview

This Python MCP server provides the exact same capabilities as the official Go implementation:

• Complete Launch Management: List, filter, and manage test launches with advanced filtering
• Test Item Analysis: Access detailed test item information, logs, and attachments
• Defect Classification: Update and manage test item defect types with intelligent validation
• Automated Analysis: Trigger auto-analysis, unique error analysis, and quality gates
• Structured Resources: Access launch data in structured JSON format for detailed analysis
• Natural Language Interface: Use plain English queries through Claude, Copilot, etc.

Available Tools

The following table shows all available tools that match the official Go implementation exactly:

Available Resources

Architecture & Features

🏗️ Modular Architecture

The server is built with a clean, modular architecture for better maintainability:

• 📁 tools/ - Specialized tool implementations by category
• 📁 resources/ - Rich JSON resources for programmatic access
• 📁 utils/ - Shared formatting and utility functions
• 📄 server.py - Lightweight orchestrator (88% smaller than monolithic approach)

🚀 Enhanced Launch Details

Based on real ReportPortal API responses, providing comprehensive launch information:

• 📊 Complete Statistics - Execution counts, pass rates, defect breakdowns
• 🏷️ Rich Attributes - Tags, key-value pairs, and metadata
• ⏱️ Detailed Timing - Start/end times, duration calculations, last modified
• 🔍 Defect Analysis - Product bugs, automation bugs, investigations with individual codes
• 🔄 Runtime Characteristics - Retry status, rerun detection, retention policies
• 💡 Health Assessment - HEALTHY/DEGRADED/CRITICAL status based on failure rates

🛡️ Robust Error Handling

• Smart UUID/ID Resolution - Automatic handling of both UUID and numeric IDs
• Detailed Error Messages - Helpful suggestions for common API issues
• Graceful Degradation - Fallback mechanisms for missing data
• Retry Logic - Automatic retry with exponential backoff

✅ Integration Features

• Complete Compatibility - All 11 tools from official Go implementation
• Advanced Filtering - Support for complex queries with multiple filter parameters
• AI Assistant Integration - Works with Claude Desktop, GitHub Copilot, Cursor, etc.
• Docker Support - Available as Docker container
• Custom Prompts - Load prompts from YAML files automatically
• Timestamp Parsing - Handles both Unix timestamps and ISO datetime strings

Quick Start

Prerequisites

• Python 3.8+
• A ReportPortal instance
• API token with appropriate permissions
• (Optional) Corporate proxy configuration

Installation

# Clone the repository
git clone https://github.com/reportportal/reportportal-mcp-server-python.git
cd reportportal-mcp-server-python

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install dependencies
pip install -e .

Configuration

The server uses environment variables for configuration. For corporate environments with proxy and SSL issues:

Standard Configuration:

export RP_HOST="https://your-reportportal-instance.com"
export RP_PROJECT="your-project"
export RP_TOKEN="your-api-token"

Corporate Environment with Proxy:

# Basic configuration
export RP_HOST="https://your-reportportal-instance.com"
export RP_PROJECT="your-project"
export RP_TOKEN="your-api-token"

# Proxy configuration
export HTTPS_PROXY="http://proxy.company.com:8080"
export PROXY_USER="your-username"  # if authentication required
export PROXY_PASS="your-password"  # if authentication required

# Windows SSL fixes for corporate environments
export RP_VERIFY_SSL="false"  # This gives verify=False in httpx

Running the Server

# Set required environment variables
export RP_HOST="https://your-reportportal-instance.com"
export RP_PROJECT="your-project"
export RP_TOKEN="your-api-token"

# Optional: Configure proxy if needed
export PROXY_URL="http://your-proxy-server:8080"
export PROXY_USER="proxy-username"  # if authentication required
export PROXY_PASS="proxy-password"  # if authentication required

# Optional: Windows SSL fixes for corporate environments
export RP_VERIFY_SSL="false"  # Disable SSL verification if needed
export RP_DISABLE_SSL_REVOCATION="true"  # For Windows revocation check issues

# Run the server
python -m reportportal_mcp_server

Testing the Server

Quick Configuration Test

Run the provided test script to verify your setup:

# Test configuration and basic functionality
python test_mcp_server.py

Manual Testing

1. Server Startup Test

# Start the server and verify no errors
python -m reportportal_mcp_server

Expected output:

Starting ReportPortal MCP Server on port 4389...
ReportPortal Host: https://your-reportportal-instance.com
Project: your-project

2. MCP Inspector Testing (Recommended)

# Install MCP Inspector (one-time)
npm install -g @modelcontextprotocol/inspector

# Test your server interactively
mcp-inspector python -m reportportal_mcp_server

What you'll see:

• 🌐 Web interface opens in browser
• 📋 List of all 13 available tools
• ✅ Interactive testing of each tool
• 🔍 Request/response debugging

Test these tools in order:

1. get_launches (no parameters) - Returns your ReportPortal launches
2. get_last_launch_by_name with launch="your-launch-name"
3. get_test_items_by_filter with launch_id from step 2
4. get_test_item_logs_by_filter with parent_id from step 3

3. Network Connectivity Verification

# Test proxy and ReportPortal connectivity
curl -k --ssl-no-revoke -x $HTTPS_PROXY \
  -H "Authorization: Bearer $RP_TOKEN" \
  "$RP_HOST/api/v1/$RP_PROJECT/launch"

AI Assistant Integration Testing

After the server tests pass, integrate with your AI assistant and test with queries like:

• "Get the last 5 launches from ReportPortal"
• "Show me failed test items from the latest launch"
• "Analyze failed tests in launch 'Demo Api Tests'"

Corporate Environment Setup

Windows Corporate Network Configuration

For Windows machines in corporate environments with proxies and SSL inspection:

# Complete corporate environment setup
export RP_HOST="https://reportportal.company.com"
export RP_PROJECT="your-project"
export RP_TOKEN="your-api-token"

# Proxy configuration (use HTTPS_PROXY for better compatibility)
export HTTPS_PROXY="http://proxy.company.com:8080"
export PROXY_USER="DOMAIN\\username"  # Note double backslash for domain
export PROXY_PASS="your-password"

# Windows SSL fixes (addresses certificate errors)
export RP_VERIFY_SSL="false"

# Optional: Increase timeout for slow corporate networks
export RP_TIMEOUT="60"

Validation Steps

1. Test Proxy Connectivity

# Test basic proxy
curl -x %HTTPS_PROXY% https://google.com

# Test with SSL fixes
curl -k --ssl-no-revoke -x %HTTPS_PROXY% https://google.com

# Test ReportPortal accessibility
curl -k --ssl-no-revoke -x %HTTPS_PROXY% \
  -H "Authorization: Bearer %RP_TOKEN%" \
  "%RP_HOST%/api/v1/%RP_PROJECT%/launch"

2. Run the Test Script

python test_mcp_server.py

3. Start the Server

python -m reportportal_mcp_server

Common Corporate Environment Issues

Proxy Configuration Examples

Basic Proxy (No Authentication)

# Using PROXY_URL
export PROXY_URL="http://proxy.company.com:8080"

# Or using standard HTTP_PROXY/HTTPS_PROXY
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

Proxy with Authentication

# Separate username/password (recommended)
export HTTPS_PROXY="http://proxy.company.com:8080"
export PROXY_USER="your-username"
export PROXY_PASS="your-password"

# For Windows corporate environments with SSL issues
export RP_VERIFY_SSL="false"
export RP_DISABLE_SSL_REVOCATION="true"

SOCKS Proxy

# SOCKS5 proxy
export PROXY_URL="socks5://proxy.company.com:1080"

# Note: SOCKS proxies typically don't require separate HTTP/HTTPS configuration

Docker Usage

# Using official Docker image
docker run -i --rm \
  -e "RP_HOST=https://your-reportportal-instance.com" \
  -e "RP_PROJECT=your-project" \
  -e "RP_TOKEN=your-api-token" \
  reportportal/mcp-server-python

Docker with Proxy

# Docker with proxy configuration
docker run -i --rm \
  -e "RP_HOST=https://your-reportportal-instance.com" \
  -e "RP_PROJECT=your-project" \
  -e "RP_TOKEN=your-api-token" \
  -e "HTTPS_PROXY=http://proxy.company.com:8080" \
  -e "PROXY_USER=username" \
  -e "PROXY_PASS=password" \
  -e "RP_VERIFY_SSL=false" \
  -e "RP_DISABLE_SSL_REVOCATION=true" \
  reportportal/mcp-server-python

Integration with AI Tools

Claude Desktop

Add to your Claude Desktop configuration:

{
  "servers": {
    "reportportal": {
      "command": "python",
      "args": ["-m", "reportportal_mcp_server"],
      "env": {
        "RP_HOST": "https://your-reportportal-instance.com",
        "RP_PROJECT": "your-project",
        "RP_TOKEN": "your-api-token",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "PROXY_USER": "username",
        "PROXY_PASS": "password",
        "RP_VERIFY_SSL": "false"
      }
    }
  }
}

GitHub Copilot

1. Open VS Code
2. Press Ctrl+Shift+P and search for "MCP"
3. Select "MCP: Open User Configuration"
4. Add the server configuration similar to Claude Desktop

Cursor

1. Open Cursor Settings
2. Navigate to "Tools & Integrations"
3. Click "New MCP Server"
4. Add the configuration

Usage Examples

Once connected, you can ask your AI assistant natural language questions:

🚀 Launch Management

• "Get the last 10 launches for project ABC"
• "Show me launches that failed in the last week"
• "Force finish the running launch with ID 456"
• "Delete launch 789"

🔍 Test Analysis

• "Get test items for launch 123 that failed"
• "Show me logs for test item 456 with ERROR level"
• "Get attachments for test item 789"

🏷️ Defect Classification

• "Classify test item 412 as a product bug with comment 'Login button not working'"
• "Update defect classification for test item 456 to automation bug"
• "Bulk classify failed tests: items 412,413,414 as product bugs"
• "Mark test item 789 as 'no defect' since it's expected behavior"

📊 Automated Analysis

• "Run auto analysis on launch 123"
• "Analyze unique errors in launch 456"
• "Run quality gate check on launch 789"

📈 Advanced Filtering

• "Get launches owned by john.doe that started yesterday"
• "Show test items with 'API' in the name for launch 123"
• "Get logs containing 'timeout' for test item 456"

Comparison with Official Go Implementation

Development

Project Structure

src/reportportal_mcp_server/
├── __init__.py              # Package initialization
├── __main__.py              # Module entry point  
├── main.py                  # CLI entry point
├── server.py                # Main orchestrator (lightweight, 4KB)
├── client.py                # ReportPortal API client with enhanced models
├── config.py                # Configuration management
├── tools/                   # Tool implementations (modular)
│   ├── __init__.py
│   ├── launch_tools.py      # Launch operations (get_launches, get_last_launch_by_name, etc.)
│   ├── test_item_tools.py   # Test item operations (get_test_items_by_filter, logs, attachments)
│   └── analysis_tools.py    # Analysis operations (auto_analysis, unique_error_analysis, quality_gate)
├── resources/               # Resource implementations
│   ├── __init__.py
│   └── launch_resources.py  # Launch analysis resource with comprehensive JSON output
└── utils/                   # Shared utilities
    ├── __init__.py
    └── formatters.py        # Formatting utilities (timestamps, durations, launch details)

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=reportportal_mcp_server

Code Quality

# Format code
black src/

# Sort imports
isort src/

# Type checking
mypy src/

# Linting
ruff check src/

Troubleshooting

Common Issues

1. Connection Errors

   • Verify RP_HOST is accessible
   • Check API token permissions
   • Ensure project name is correct
   • If behind proxy, verify proxy configuration

2. Proxy Connection Issues

   • Verify proxy URL format: http://proxy.company.com:8080
   • Check proxy authentication credentials
   • Test proxy connectivity: curl -x $PROXY_URL https://google.com
   • For corporate proxies, ensure ReportPortal host is allowed

3. Windows SSL/TLS Issues (schannel errors)

   • Set RP_VERIFY_SSL=false to disable SSL verification
   • Set RP_DISABLE_SSL_REVOCATION=true for Windows certificate revocation issues
   • For "unable to get local issuer certificate": Set RP_VERIFY_SSL=false
   • Update Windows certificate store: certlm.msc
   • Reset network stack: netsh winsock reset (run as Administrator)
   • Test with curl: curl -k --ssl-no-revoke -x proxy:port https://your-host.com

4. SSL Certificate Issues

   • Set RP_VERIFY_SSL=false to disable SSL verification (not recommended for production)
   • For corporate environments, ensure CA certificates are properly configured
   • Check if proxy is performing SSL inspection

5. Timestamp Parsing Errors

   • ✅ Fixed in v0.2.0 - automatic handling of both Unix timestamps and ISO datetime strings

6. Tool Not Found

   • Restart your AI assistant
   • Check MCP server configuration
   • Verify environment variables

7. Logs API Sorting Error (Fixed in v0.2.1)

   • ✅ Fixed HTTP 400 error when calling get_test_item_logs_by_filter
   • ✅ Root cause: Invalid default sorting parameter time,DESC
   • ✅ Solution: Removed default sorting, made it optional
   • ✅ Valid sort options: logTime,DESC, level,ASC, message,ASC, id,DESC

Getting Help

• Official Documentation
• GitHub Issues
• ReportPortal Slack

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is licensed under the Apache 2.0 License - see the file for details.

Changelog

v0.3.3 (Latest - Defect Classification)

• 🔍 Defect Classification Tools - Complete defect categorization system based on real API structure
• 🏷️ Smart Type Mapping - User-friendly names (system_issue, product_bug) mapped to API codes (si001, pb001)
• ✅ Comprehensive Validation - Input validation with helpful error messages and correction suggestions
• 📊 Bulk Operations - Efficient batch processing for multiple test item classifications
• 💬 Rich Response formatting - Detailed success confirmations with next steps guidance
• 🎯 Contextual Guidance - Specific actionable recommendations based on defect type
• 🛠️ Enhanced Error Handling - HTTP status code handling with meaningful user guidance
• 🔄 API Structure Compliance - Exact match with sample-putitem.txt API format
• 🤖 AI-Friendly Design - Enables intelligent test failure categorization and automated triaging
• 📈 Quality Intelligence - Support for defect trending and process improvement analysis

v0.3.2 (Test Item Enhancement)

• 🔍 Enhanced Test Item Retrieval - Comprehensive item analysis based on real API response structure
• 📊 Rich Item Summaries - Status distribution, item types breakdown, and issue analysis
• 🏗️ Hierarchical Context - Full launch → suite → test path visibility
• 🔍 Issue Analysis Integration - Defect types, auto-analysis status, and external system tracking
• 🏷️ Complete Test Metadata - Code references, test case IDs, unique identifiers, and hash codes
• ⏱️ Precise Duration Calculations - Execution timing analysis with multiple timestamp format support
• 📎 Comprehensive Attributes - Smart handling of key-value pairs and tags with truncation
• 📊 Statistics Integration - Per-item execution counts and defect summaries
• 🛠️ Enhanced Data Model - Complete TestItemModel with all API response fields
• 🚀 Performance Optimization - Increased default page size to 50 items

v0.3.1 (Log Enhancement)

• 🔍 Enhanced Log Retrieval - Comprehensive log display based on real API response structure
• 📊 Rich Log Summaries - Page information, log level distribution, and total counts
• 📝 Smart Message Formatting - Intelligent handling of stack traces and multi-line messages
• 📎 Binary Content Support - Full attachment details with content type indicators
• 🏷️ Complete Log Metadata - Log ID, UUID, timestamps, and item references
• 📈 Enhanced Pagination - Increased default page size from 20 to 50 logs
• 🔧 Professional Formatting - Clear headers, separators, and structured layout
• 🔗 Attachment Context - Links attachments to their originating log entries
• ⚡ Better Performance - Efficient content analysis and memory-conscious truncation
• 🛠️ Improved Error Handling - Support for both 'time' and 'logTime' timestamp fields

v0.3.0 (Architecture Refactor)

• 🏗️ Modular Architecture - Refactored monolithic server into clean, modular structure
• 📊 Enhanced Launch Details - Comprehensive launch information based on real API responses
• 📈 88% Size Reduction - Main server file reduced from 33KB to 4KB
• 🛠️ Better Maintainability - Separated concerns with dedicated tool, resource, and utility modules
• 📊 Rich Statistics - Complete execution statistics, defect breakdowns, and health assessments
• 🕰️ Enhanced Timing - Duration calculations, last modified timestamps, approximate durations
• 🏷️ Comprehensive Attributes - Full support for tags, key-value pairs, and metadata
• 🔄 Runtime Insights - Retry detection, rerun identification, retention policies
• 💡 Health Assessment - Automatic HEALTHY/DEGRADED/CRITICAL classification
• 🔧 Developer Experience - Easier testing, cleaner code reviews, faster development

v0.2.1 (Bug Fix)

• 🐛 Fixed logs API sorting error - Resolved HTTP 400 "Sorting parameter time is not defined"
• ✅ Enhanced error handling - Better error messages with suggested valid sort parameters
• ✅ Improved timestamp handling - Support for both 'logTime' and 'time' field formats
• ✅ Optional sorting - Sorting now optional, API uses default when not specified

v0.2.0

• ✅ Added all 11 tools from official Go implementation
• ✅ Enhanced filtering for all tools with advanced parameter support
• ✅ Added missing tools: get_test_item_logs_by_filter, get_test_item_attachments, run_quality_gate
• ✅ Improved timestamp handling for both Unix and ISO formats
• ✅ Enhanced error handling with detailed error messages
• ✅ Complete API parity with official Go implementation

v0.1.0

• ✅ Initial release with 9 core tools
• ✅ Fixed timestamp parsing issues
• ✅ Basic MCP server functionality

Acknowledgments

• Official ReportPortal MCP Server (Go)
• Model Context Protocol
• ReportPortal Community
• FastMCP Python SDK