# MCP Zephyr Scale Cloud Server
A Model Context Protocol (MCP) server for Zephyr Scale Cloud, enabling AI assistants to interact with test management capabilities.
## Features
### ✅ **Currently Implemented:**
- 🩺 **API Health Monitoring** - Check connectivity and authentication status
- ⭐ **Priority Management** - Create, read, update priorities across projects
- 📊 **Status Management** - Manage test execution statuses with type filtering
- 📁 **Folder Management** - Organize test artifacts with hierarchical folder structure
- 🧪 **Test Case Management** - Full CRUD operations for test cases with metadata
- 📝 **Test Steps & Scripts** - Manage test step definitions and scripts (plain/BDD)
- 🔗 **Test Case Links** - Link test cases to Jira issues and web resources
- 📋 **Test Case Retrieval** - Advanced pagination and filtering capabilities
- 📚 **Version Management** - Test case version history and retrieval
- 🔧 **Production Ready** - Server lifespan management and structured logging
- 🧪 **Comprehensive Testing** - Unit tests, integration tests, and CI/CD pipeline
- 📝 **Type Safety** - Pydantic schema validation for all API operations
### 🚧 **Planned Features:**
Based on the Zephyr Scale Cloud API documentation, the following major categories are planned for implementation:
- 🔄 **Test Cycle Management** - Create, read, update test cycles with metadata
- 📈 **Test Execution Management** - Create, read, update test executions and results
- 📋 **Test Plan Management** - Test plan operations and organization
- 🌍 **Environment Management** - Test environment configuration and management
- 👥 **Project Management** - Project information and configuration
- 🔗 **Advanced Link Management** - Delete links and enhanced link operations
- 🤖 **Automation Integration** - Custom, Cucumber, and JUnit test execution automation
- 📊 **Issue Link Coverage** - Comprehensive Jira issue link coverage tracking
## Installation
### Option 1: Install from PyPI (Recommended)
Install directly from the Python Package Index:
```bash
pip install mcp-zephyr-scale-cloud
```
### Option 2: Install from GitHub Releases
Download and install the latest release directly from GitHub:
```bash
# Download the latest wheel file from GitHub releases
pip install https://github.com/basterboy/mcp-zephyr-scale-cloud/releases/download/v0.1.5/mcp_zephyr_scale_cloud-0.1.5-py3-none-any.whl
```
Or install from the source distribution:
```bash
pip install https://github.com/basterboy/mcp-zephyr-scale-cloud/releases/download/v0.1.5/mcp_zephyr_scale_cloud-0.1.5.tar.gz
```
### Option 3: Install from Source
For development or latest features:
```bash
git clone https://github.com/basterboy/mcp-zephyr-scale-cloud.git
cd mcp-zephyr-scale-cloud
pip install .
```
### Verify Installation
After installation, verify it works:
```bash
python -c "import mcp_zephyr_scale_cloud; print('✅ Successfully installed!')"
```
## Integration with Cursor
After installing the package, add the following to your Cursor configuration:
```json
{
"mcpServers": {
"zephyr-scale-cloud": {
"command": "mcp-zephyr-scale-cloud",
"env": {
"ZEPHYR_SCALE_API_TOKEN": "your-zephyr-api-token",
"ZEPHYR_SCALE_BASE_URL": "https://api.zephyrscale.smartbear.com/v2",
"ZEPHYR_SCALE_DEFAULT_PROJECT_KEY": "YOURPROJ"
}
}
}
}
```
### Configuration Options:
- **ZEPHYR_SCALE_API_TOKEN**: Your Zephyr Scale API token (required)
- **ZEPHYR_SCALE_BASE_URL**: API base URL (optional, defaults to `https://api.zephyrscale.smartbear.com/v2`)
- **ZEPHYR_SCALE_DEFAULT_PROJECT_KEY**: Default project key for tools that support it (optional)
#### Environment Variable Fallback
Many tools now support automatic project key resolution. If you have access to multiple projects, you can set `ZEPHYR_SCALE_DEFAULT_PROJECT_KEY` to avoid specifying the project key in every tool call. Tools like `get_test_cases`, `get_folders`, and others will automatically use this default when no explicit project key is provided.
### Getting Zephyr API Token:
1. In JIRA, go to **Apps** → **Zephyr Scale** → **API Access Tokens**
2. Click **Create access token**
3. Copy the generated token and use it as your `ZEPHYR_SCALE_API_TOKEN`
For detailed instructions, see: [API Access Tokens Management](https://support.smartbear.com/zephyr/docs/en/rest-api/api-access-tokens-management.html)
### About Zephyr Scale Cloud API
This package interfaces with the Zephyr Scale Cloud REST API, which provides comprehensive test management capabilities within Jira. The API allows you to:
- **Import and manage test data** from any framework or tool
- **Store test execution results** from automated testing
- **Integrate with CI/CD pipelines** for seamless test reporting
- **Access test cases, cycles, plans, and execution data**
**Key API Information:**
- **Base URL**: `https://api.zephyrscale.smartbear.com/v2/`
- **Authentication**: JWT Bearer token
- **Protocol**: HTTP-based REST API
- **Supported operations**: GET, POST, PUT requests for data retrieval and submission
The MCP Zephyr Scale Cloud package provides 25 tools that wrap these API endpoints, making them easily accessible through AI assistants and automation workflows.
**API Resources:**
- [REST API Overview](https://support.smartbear.com/zephyr/docs/en/rest-api/rest-api--overview-.html)
- [Complete API Documentation](https://support.smartbear.com/zephyr-scale-cloud/api-docs/)
## Development
1. Clone the repository:
```bash
git clone https://github.com/basterboy/mcp-zephyr-scale-cloud.git
cd mcp-zephyr-scale-cloud
```
2. Install dependencies:
```bash
poetry install --with dev
```
3. Run tests:
```bash
# Run all tests
make test
# Or specific test types
make test-unit # Unit tests only
make test-integration # Integration tests only
make test-fast # Fast tests (no coverage)
make test-coverage # Tests with detailed coverage
# Or use Poetry directly
poetry run pytest
```
4. Run code quality checks:
```bash
# Run all quality checks
make lint
# Or individual tools
poetry run black . # Code formatting
poetry run isort . # Import sorting
poetry run ruff check . # Linting
poetry run mypy src/ # Type checking
```
5. Auto-fix code issues:
```bash
make format # Fix formatting and imports
```
## Recent Improvements
### 🚀 **Major Updates:**
- **Test Case Management**: Full CRUD operations for test cases with advanced metadata support
- **Performance Optimization**: Added comprehensive pagination guidance with max_results=1000 recommendations
- **Link Management**: Test case linking to Jira issues and web resources
- **Version Control**: Test case version history and retrieval capabilities
- **Environment Integration**: Automatic project key resolution from environment variables
- **Enhanced Error Handling**: Improved validation and user-friendly error messages
### 🔧 **Technical Improvements:**
- **Schema Simplification**: Streamlined update operations using Pydantic model_dump()
- **Validation Enhancement**: Comprehensive input validation with helpful error guidance
- **Code Quality**: Extensive refactoring for maintainability and performance
- **Test Coverage**: Expanded test suite covering all new functionality
## Architecture
This project implements an **MCP Server** that connects AI assistants to Zephyr Scale Cloud:
```
AI Assistant (Claude)
↓ (MCP Protocol)
MCP Server (server.py)
↓ (HTTP Requests)
Zephyr Scale Cloud API
```
### Project Structure
```
src/mcp_zephyr_scale_cloud/
├── server.py # MCP Server - exposes tools to AI assistants
├── config.py # Configuration management
├── schemas/ # Pydantic schemas for data validation
│ ├── __init__.py
│ ├── base.py # Base schemas and common types
│ ├── common.py # Shared entity schemas
│ ├── priority.py # Priority-specific schemas
│ ├── status.py # Status-specific schemas
│ ├── folder.py # Folder-specific schemas
│ ├── test_case.py # Test case schemas with pagination support
│ ├── test_script.py # Test script schemas
│ ├── test_step.py # Test step schemas
│ └── version.py # Version-specific schemas
├── utils/ # Utility functions
│ ├── __init__.py
│ └── validation.py # Input validation utilities
└── clients/
├── __init__.py
└── zephyr_client.py # Schema-based HTTP Client
```
### Key Concepts
- **MCP Server** (`server.py`): Handles the Model Context Protocol, exposes tools/resources to AI assistants with advanced lifespan management
- **HTTP Client** (`clients/zephyr_client.py`): Schema-based client making type-safe REST API calls to Zephyr Scale Cloud
- **Pydantic Schemas** (`schemas/`): Data validation and serialization using Pydantic models
- **Validation Utils** (`utils/validation.py`): Input validation with comprehensive error handling
- **Configuration** (`config.py`): Manages API tokens and settings
- **Server Lifespan**: Startup validation, API connectivity testing, and graceful shutdown management
## Advanced Features
### 🚀 Server Lifespan Management
This MCP server implements advanced [server lifespan management](https://github.com/modelcontextprotocol/python-sdk?tab=readme-ov-file#low-level-server) for robust production deployment:
- **Startup Validation**: Validates configuration and tests API connectivity before accepting requests
- **Fast Failure**: Reports configuration errors immediately on startup
- **Health Monitoring**: Automatically tests Zephyr Scale API accessibility during initialization
- **Graceful Shutdown**: Properly cleans up resources when the server stops
- **Structured Logging**: Uses Python's logging module with proper log levels for production environments
**Benefits:**
- 🔧 **Better Developer Experience**: Clear error messages if API token is missing
- 🚨 **Production Ready**: Fails fast instead of silently accepting broken configurations
- 📊 **Monitoring**: Easy to detect configuration and connectivity issues
- 🧹 **Resource Management**: Proper cleanup prevents resource leaks
## Testing
This project includes comprehensive testing to ensure reliability:
### 🧪 Test Structure
```
tests/
├── test_basic.py # Basic functionality tests
├── unit/ # Unit tests for individual components
│ ├── test_config.py # Configuration tests
│ ├── test_schemas.py # Pydantic schema tests
│ ├── test_validation.py # Validation utility tests
│ └── test_zephyr_client.py # HTTP client tests
├── integration/ # Integration tests
│ └── test_mcp_server.py # MCP server integration tests
└── conftest.py # Shared test fixtures
```
### 🚀 Running Tests
```bash
# Quick test run
make test-fast
# Full test suite with coverage
make test
# Continuous testing during development
poetry run pytest tests/ --tb=short -x
# Test specific functionality
poetry run pytest tests/test_basic.py -v
```
### 📊 Test Coverage
- **Unit Tests**: Test individual components in isolation
- **Integration Tests**: Test MCP server functionality end-to-end
- **Schema Tests**: Validate Pydantic models and API contracts
- **Validation Tests**: Ensure input validation works correctly
### 🔧 CI/CD
Tests run automatically on:
- **GitHub Actions**: On push/PR to main branch
- **Multiple Python versions**: 3.10, 3.11, 3.12
- **Code quality checks**: Formatting, linting, type checking
## MCP Tools
This server provides **25 MCP tools** for Zephyr Scale Cloud integration:
| **Category** | **Tools** | **Description** |
|--------------|-----------|-----------------|
| **Health** | 1 tool | API connectivity and authentication |
| **Priorities** | 4 tools | Full CRUD operations for priority management |
| **Statuses** | 4 tools | Full CRUD operations for status management |
| **Folders** | 3 tools | Folder management and organization |
| **Test Steps** | 2 tools | Test step retrieval and creation |
| **Test Scripts** | 2 tools | Test script retrieval and creation |
| **Test Cases** | 7 tools | Complete test case management suite |
| **Test Case Links** | 2 tools | Link management for test cases |
| **Total** | **25 tools** | **Production-ready MCP server** |
### Currently Available:
#### **🩺 Health & Connectivity**
- `healthcheck` - Check Zephyr Scale Cloud API connectivity and authentication status
#### **⭐ Priority Management**
- `get_priorities` - Get all priorities with optional project filtering
- `get_priority` - Get details of a specific priority by ID
- `create_priority` - Create a new priority in a project
- `update_priority` - Update an existing priority
#### **📊 Status Management**
- `get_statuses` - Get all statuses with optional project and type filtering
- `get_status` - Get details of a specific status by ID
- `create_status` - Create a new status in a project
- `update_status` - Update an existing status
#### **📁 Folder Management**
- `get_folders` - Get all folders with optional project and type filtering
- `get_folder` - Get details of a specific folder by ID
- `create_folder` - Create a new folder in a project
#### **📝 Test Step Management**
- `get_test_steps` - Retrieve test steps for a specific test case with pagination support
- `create_test_steps` - Create test steps for a test case with APPEND/OVERWRITE modes
#### **📄 Test Script Management**
- `get_test_script` - Retrieve test script for a specific test case
- `create_test_script` - Create or update test script with plain text or BDD format
#### **📋 Test Case Management**
- `get_test_case` - Get detailed test case information including metadata, status, priority, and content
- `get_test_cases` - Retrieve test cases with advanced offset-based pagination and filtering
- `create_test_case` - Create new test cases with comprehensive metadata support
- `update_test_case` - Update existing test cases with validation and error handling
- `get_test_case_versions` - Retrieve version history for test cases
- `get_test_case_version` - Get specific version of a test case
- `get_links` - Get all links (issues + web links) associated with a test case
#### **🔗 Test Case Links**
- `create_issue_link` - Link test cases to Jira issues for traceability
- `create_web_link` - Add web links to test cases for documentation
## 📊 Status Operations Guide
Status operations allow you to manage test execution statuses in Zephyr Scale Cloud. Each status can be associated with different entity types:
### **Status Types:**
- `TEST_CASE` - For test case statuses
- `TEST_PLAN` - For test plan statuses
- `TEST_CYCLE` - For test cycle statuses
- `TEST_EXECUTION` - For test execution statuses
### **Example Usage:**
```python
# Get all statuses for a specific project and type
statuses = await get_statuses(
project_key="MYPROJ",
status_type="TEST_EXECUTION",
max_results=100
)
# Create a new test execution status
new_status = await create_status(
project_key="MYPROJ",
name="In Review",
status_type="TEST_EXECUTION",
description="Test is under review",
color="#FFA500"
)
# Update an existing status
updated = await update_status(
status_id=123,
project_id=456,
name="Reviewed",
index=5,
description="Test has been reviewed and approved"
)
```
### **Status Properties:**
- **Name**: Human-readable status name (max 255 chars)
- **Type**: One of the four status types listed above
- **Description**: Optional detailed description (max 255 chars)
- **Color**: Optional hex color code (e.g., '#FF0000')
- **Index**: Position/order in status lists
- **Default**: Whether this is the default status for the type
- **Archived**: Whether the status is archived
## 📁 Folder Operations Guide
Folder operations allow you to organize and manage test artifacts in Zephyr Scale Cloud. Folders provide hierarchical structure for test cases, test plans, and test cycles.
### **Folder Types:**
- `TEST_CASE` - For organizing test cases
- `TEST_PLAN` - For organizing test plans
- `TEST_CYCLE` - For organizing test cycles
### **Example Usage:**
```python
# Get all folders for a specific project and type
folders = await get_folders(
project_key="MYPROJ",
folder_type="TEST_CASE",
max_results=100
)
# Create a new root folder
root_folder = await create_folder(
name="Smoke Tests",
project_key="MYPROJ",
folder_type="TEST_CASE"
# parent_id is None for root folders
)
# Create a child folder
child_folder = await create_folder(
name="Login Tests",
project_key="MYPROJ",
folder_type="TEST_CASE",
parent_id=123 # ID of the parent folder
)
# Get details of a specific folder
folder_details = await get_folder(folder_id=456)
```
### **Folder Properties:**
- **Name**: Human-readable folder name (1-255 chars)
- **Type**: One of the three folder types listed above
- **Project Key**: Jira project key where the folder belongs
- **Parent ID**: ID of parent folder (null for root folders)
- **Index**: Position/order within the parent folder
- **ID**: Unique identifier assigned by Zephyr Scale
### **Folder Hierarchy:**
- Folders can be nested to create hierarchical organization
- Root folders have `parent_id = null`
- Child folders reference their parent via `parent_id`
- Each folder type maintains its own hierarchy within a project
## 🔧 Test Case Management Guide
The test case management tools provide comprehensive CRUD operations for managing test cases in Zephyr Scale Cloud.
### **Key Features:**
- **Full CRUD Operations**: Create, read, update, and retrieve test cases
- **Advanced Pagination**: Efficient offset-based pagination with performance optimizations
- **Version Management**: Access to test case version history
- **Link Management**: Connect test cases to Jira issues and web resources
- **Rich Metadata**: Support for priorities, statuses, folders, components, and custom fields
- **Environment Integration**: Automatic project key resolution from environment variables
### **Pagination Performance Tips:**
- Use `max_results=1000` for fastest bulk data retrieval
- Follow offset-based pagination: `start_at = current_start_at + max_results`
- Ensure `start_at` is a multiple of `max_results` (API requirement)
- Check `len(values) < max_results` to detect the last page
### **Example Usage:**
```python
# Get test cases with maximum performance
test_cases = await get_test_cases(
project_key="MYPROJ",
max_results=1000, # Maximum for best performance
start_at=0
)
# Create a comprehensive test case
new_test_case = await create_test_case(
name="Login functionality test",
project_key="MYPROJ",
objective="Verify user can log in successfully",
priority_name="High",
status_name="Draft",
folder_id=123,
labels=["smoke", "authentication"]
)
# Update test case with validation
updated = await update_test_case(
test_case_key="MYPROJ-T123",
name="Updated login test",
priority_id=456,
status_id=789
)
# Link to Jira issue for traceability
link_result = await create_issue_link(
test_case_key="MYPROJ-T123",
issue_id=456789
)
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-zephyr-scale-cloud",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, zephyr, scale, testing, jira",
"author": "Yevhen Burlaka",
"author_email": "yevhen.burlaka@example.com",
"download_url": "https://files.pythonhosted.org/packages/ca/4c/e07439fe0a8ef91276f2478f8b383d78ea63e4630700a9c64fe2c17a4a9d/mcp_zephyr_scale_cloud-0.1.5.tar.gz",
"platform": null,
"description": "# MCP Zephyr Scale Cloud Server\n\nA Model Context Protocol (MCP) server for Zephyr Scale Cloud, enabling AI assistants to interact with test management capabilities.\n\n## Features\n\n### \u2705 **Currently Implemented:**\n- \ud83e\ude7a **API Health Monitoring** - Check connectivity and authentication status\n- \u2b50 **Priority Management** - Create, read, update priorities across projects\n- \ud83d\udcca **Status Management** - Manage test execution statuses with type filtering\n- \ud83d\udcc1 **Folder Management** - Organize test artifacts with hierarchical folder structure\n- \ud83e\uddea **Test Case Management** - Full CRUD operations for test cases with metadata\n- \ud83d\udcdd **Test Steps & Scripts** - Manage test step definitions and scripts (plain/BDD)\n- \ud83d\udd17 **Test Case Links** - Link test cases to Jira issues and web resources\n- \ud83d\udccb **Test Case Retrieval** - Advanced pagination and filtering capabilities\n- \ud83d\udcda **Version Management** - Test case version history and retrieval\n- \ud83d\udd27 **Production Ready** - Server lifespan management and structured logging\n- \ud83e\uddea **Comprehensive Testing** - Unit tests, integration tests, and CI/CD pipeline\n- \ud83d\udcdd **Type Safety** - Pydantic schema validation for all API operations\n\n### \ud83d\udea7 **Planned Features:**\n\nBased on the Zephyr Scale Cloud API documentation, the following major categories are planned for implementation:\n\n- \ud83d\udd04 **Test Cycle Management** - Create, read, update test cycles with metadata\n- \ud83d\udcc8 **Test Execution Management** - Create, read, update test executions and results\n- \ud83d\udccb **Test Plan Management** - Test plan operations and organization \n- \ud83c\udf0d **Environment Management** - Test environment configuration and management\n- \ud83d\udc65 **Project Management** - Project information and configuration\n- \ud83d\udd17 **Advanced Link Management** - Delete links and enhanced link operations\n- \ud83e\udd16 **Automation Integration** - Custom, Cucumber, and JUnit test execution automation\n- \ud83d\udcca **Issue Link Coverage** - Comprehensive Jira issue link coverage tracking\n\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\nInstall directly from the Python Package Index:\n\n```bash\npip install mcp-zephyr-scale-cloud\n```\n\n### Option 2: Install from GitHub Releases\n\nDownload and install the latest release directly from GitHub:\n\n```bash\n# Download the latest wheel file from GitHub releases\npip install https://github.com/basterboy/mcp-zephyr-scale-cloud/releases/download/v0.1.5/mcp_zephyr_scale_cloud-0.1.5-py3-none-any.whl\n```\n\nOr install from the source distribution:\n\n```bash\npip install https://github.com/basterboy/mcp-zephyr-scale-cloud/releases/download/v0.1.5/mcp_zephyr_scale_cloud-0.1.5.tar.gz\n```\n\n### Option 3: Install from Source\n\nFor development or latest features:\n\n```bash\ngit clone https://github.com/basterboy/mcp-zephyr-scale-cloud.git\ncd mcp-zephyr-scale-cloud\npip install .\n```\n\n### Verify Installation\n\nAfter installation, verify it works:\n\n```bash\npython -c \"import mcp_zephyr_scale_cloud; print('\u2705 Successfully installed!')\"\n```\n\n## Integration with Cursor\n\nAfter installing the package, add the following to your Cursor configuration:\n\n```json\n{\n \"mcpServers\": {\n \"zephyr-scale-cloud\": {\n \"command\": \"mcp-zephyr-scale-cloud\",\n \"env\": {\n \"ZEPHYR_SCALE_API_TOKEN\": \"your-zephyr-api-token\",\n \"ZEPHYR_SCALE_BASE_URL\": \"https://api.zephyrscale.smartbear.com/v2\",\n \"ZEPHYR_SCALE_DEFAULT_PROJECT_KEY\": \"YOURPROJ\"\n }\n }\n }\n}\n```\n\n### Configuration Options:\n\n- **ZEPHYR_SCALE_API_TOKEN**: Your Zephyr Scale API token (required)\n- **ZEPHYR_SCALE_BASE_URL**: API base URL (optional, defaults to `https://api.zephyrscale.smartbear.com/v2`) \n- **ZEPHYR_SCALE_DEFAULT_PROJECT_KEY**: Default project key for tools that support it (optional)\n\n#### Environment Variable Fallback\n\nMany tools now support automatic project key resolution. If you have access to multiple projects, you can set `ZEPHYR_SCALE_DEFAULT_PROJECT_KEY` to avoid specifying the project key in every tool call. Tools like `get_test_cases`, `get_folders`, and others will automatically use this default when no explicit project key is provided.\n\n### Getting Zephyr API Token:\n\n1. In JIRA, go to **Apps** \u2192 **Zephyr Scale** \u2192 **API Access Tokens**\n2. Click **Create access token**\n3. Copy the generated token and use it as your `ZEPHYR_SCALE_API_TOKEN`\n\nFor detailed instructions, see: [API Access Tokens Management](https://support.smartbear.com/zephyr/docs/en/rest-api/api-access-tokens-management.html)\n\n### About Zephyr Scale Cloud API\n\nThis package interfaces with the Zephyr Scale Cloud REST API, which provides comprehensive test management capabilities within Jira. The API allows you to:\n\n- **Import and manage test data** from any framework or tool\n- **Store test execution results** from automated testing\n- **Integrate with CI/CD pipelines** for seamless test reporting\n- **Access test cases, cycles, plans, and execution data**\n\n**Key API Information:**\n- **Base URL**: `https://api.zephyrscale.smartbear.com/v2/`\n- **Authentication**: JWT Bearer token\n- **Protocol**: HTTP-based REST API\n- **Supported operations**: GET, POST, PUT requests for data retrieval and submission\n\nThe MCP Zephyr Scale Cloud package provides 25 tools that wrap these API endpoints, making them easily accessible through AI assistants and automation workflows.\n\n**API Resources:**\n- [REST API Overview](https://support.smartbear.com/zephyr/docs/en/rest-api/rest-api--overview-.html)\n- [Complete API Documentation](https://support.smartbear.com/zephyr-scale-cloud/api-docs/)\n\n## Development\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/basterboy/mcp-zephyr-scale-cloud.git\ncd mcp-zephyr-scale-cloud\n```\n\n2. Install dependencies:\n```bash\npoetry install --with dev\n```\n\n3. Run tests:\n```bash\n# Run all tests\nmake test\n\n# Or specific test types\nmake test-unit # Unit tests only\nmake test-integration # Integration tests only \nmake test-fast # Fast tests (no coverage)\nmake test-coverage # Tests with detailed coverage\n\n# Or use Poetry directly\npoetry run pytest\n```\n\n4. Run code quality checks:\n```bash\n# Run all quality checks\nmake lint\n\n# Or individual tools\npoetry run black . # Code formatting\npoetry run isort . # Import sorting\npoetry run ruff check . # Linting\npoetry run mypy src/ # Type checking\n```\n\n5. Auto-fix code issues:\n```bash\nmake format # Fix formatting and imports\n```\n\n## Recent Improvements\n\n### \ud83d\ude80 **Major Updates:**\n- **Test Case Management**: Full CRUD operations for test cases with advanced metadata support\n- **Performance Optimization**: Added comprehensive pagination guidance with max_results=1000 recommendations \n- **Link Management**: Test case linking to Jira issues and web resources\n- **Version Control**: Test case version history and retrieval capabilities\n- **Environment Integration**: Automatic project key resolution from environment variables\n- **Enhanced Error Handling**: Improved validation and user-friendly error messages\n\n### \ud83d\udd27 **Technical Improvements:**\n- **Schema Simplification**: Streamlined update operations using Pydantic model_dump()\n- **Validation Enhancement**: Comprehensive input validation with helpful error guidance\n- **Code Quality**: Extensive refactoring for maintainability and performance\n- **Test Coverage**: Expanded test suite covering all new functionality\n\n## Architecture\n\nThis project implements an **MCP Server** that connects AI assistants to Zephyr Scale Cloud:\n\n```\nAI Assistant (Claude) \n \u2193 (MCP Protocol)\nMCP Server (server.py) \n \u2193 (HTTP Requests)\nZephyr Scale Cloud API\n```\n\n### Project Structure\n\n```\nsrc/mcp_zephyr_scale_cloud/\n\u251c\u2500\u2500 server.py # MCP Server - exposes tools to AI assistants\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 schemas/ # Pydantic schemas for data validation\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 base.py # Base schemas and common types\n\u2502 \u251c\u2500\u2500 common.py # Shared entity schemas\n\u2502 \u251c\u2500\u2500 priority.py # Priority-specific schemas\n\u2502 \u251c\u2500\u2500 status.py # Status-specific schemas\n\u2502 \u251c\u2500\u2500 folder.py # Folder-specific schemas\n\u2502 \u251c\u2500\u2500 test_case.py # Test case schemas with pagination support\n\u2502 \u251c\u2500\u2500 test_script.py # Test script schemas\n\u2502 \u251c\u2500\u2500 test_step.py # Test step schemas\n\u2502 \u2514\u2500\u2500 version.py # Version-specific schemas\n\u251c\u2500\u2500 utils/ # Utility functions\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 validation.py # Input validation utilities\n\u2514\u2500\u2500 clients/\n \u251c\u2500\u2500 __init__.py\n \u2514\u2500\u2500 zephyr_client.py # Schema-based HTTP Client\n```\n\n### Key Concepts\n\n- **MCP Server** (`server.py`): Handles the Model Context Protocol, exposes tools/resources to AI assistants with advanced lifespan management\n- **HTTP Client** (`clients/zephyr_client.py`): Schema-based client making type-safe REST API calls to Zephyr Scale Cloud\n- **Pydantic Schemas** (`schemas/`): Data validation and serialization using Pydantic models\n- **Validation Utils** (`utils/validation.py`): Input validation with comprehensive error handling\n- **Configuration** (`config.py`): Manages API tokens and settings\n- **Server Lifespan**: Startup validation, API connectivity testing, and graceful shutdown management\n\n## Advanced Features\n\n### \ud83d\ude80 Server Lifespan Management\n\nThis MCP server implements advanced [server lifespan management](https://github.com/modelcontextprotocol/python-sdk?tab=readme-ov-file#low-level-server) for robust production deployment:\n\n- **Startup Validation**: Validates configuration and tests API connectivity before accepting requests\n- **Fast Failure**: Reports configuration errors immediately on startup\n- **Health Monitoring**: Automatically tests Zephyr Scale API accessibility during initialization \n- **Graceful Shutdown**: Properly cleans up resources when the server stops\n- **Structured Logging**: Uses Python's logging module with proper log levels for production environments\n\n**Benefits:**\n- \ud83d\udd27 **Better Developer Experience**: Clear error messages if API token is missing\n- \ud83d\udea8 **Production Ready**: Fails fast instead of silently accepting broken configurations\n- \ud83d\udcca **Monitoring**: Easy to detect configuration and connectivity issues\n- \ud83e\uddf9 **Resource Management**: Proper cleanup prevents resource leaks\n\n## Testing\n\nThis project includes comprehensive testing to ensure reliability:\n\n### \ud83e\uddea Test Structure\n```\ntests/\n\u251c\u2500\u2500 test_basic.py # Basic functionality tests\n\u251c\u2500\u2500 unit/ # Unit tests for individual components\n\u2502 \u251c\u2500\u2500 test_config.py # Configuration tests\n\u2502 \u251c\u2500\u2500 test_schemas.py # Pydantic schema tests\n\u2502 \u251c\u2500\u2500 test_validation.py # Validation utility tests\n\u2502 \u2514\u2500\u2500 test_zephyr_client.py # HTTP client tests\n\u251c\u2500\u2500 integration/ # Integration tests\n\u2502 \u2514\u2500\u2500 test_mcp_server.py # MCP server integration tests\n\u2514\u2500\u2500 conftest.py # Shared test fixtures\n```\n\n### \ud83d\ude80 Running Tests\n```bash\n# Quick test run\nmake test-fast\n\n# Full test suite with coverage\nmake test\n\n# Continuous testing during development\npoetry run pytest tests/ --tb=short -x\n\n# Test specific functionality\npoetry run pytest tests/test_basic.py -v\n```\n\n### \ud83d\udcca Test Coverage\n- **Unit Tests**: Test individual components in isolation\n- **Integration Tests**: Test MCP server functionality end-to-end\n- **Schema Tests**: Validate Pydantic models and API contracts\n- **Validation Tests**: Ensure input validation works correctly\n\n### \ud83d\udd27 CI/CD\nTests run automatically on:\n- **GitHub Actions**: On push/PR to main branch\n- **Multiple Python versions**: 3.10, 3.11, 3.12\n- **Code quality checks**: Formatting, linting, type checking\n\n## MCP Tools\n\nThis server provides **25 MCP tools** for Zephyr Scale Cloud integration:\n\n| **Category** | **Tools** | **Description** |\n|--------------|-----------|-----------------|\n| **Health** | 1 tool | API connectivity and authentication |\n| **Priorities** | 4 tools | Full CRUD operations for priority management |\n| **Statuses** | 4 tools | Full CRUD operations for status management |\n| **Folders** | 3 tools | Folder management and organization |\n| **Test Steps** | 2 tools | Test step retrieval and creation |\n| **Test Scripts** | 2 tools | Test script retrieval and creation |\n| **Test Cases** | 7 tools | Complete test case management suite |\n| **Test Case Links** | 2 tools | Link management for test cases |\n| **Total** | **25 tools** | **Production-ready MCP server** |\n\n### Currently Available:\n\n#### **\ud83e\ude7a Health & Connectivity**\n- `healthcheck` - Check Zephyr Scale Cloud API connectivity and authentication status\n\n#### **\u2b50 Priority Management**\n- `get_priorities` - Get all priorities with optional project filtering\n- `get_priority` - Get details of a specific priority by ID\n- `create_priority` - Create a new priority in a project\n- `update_priority` - Update an existing priority\n\n#### **\ud83d\udcca Status Management**\n- `get_statuses` - Get all statuses with optional project and type filtering\n- `get_status` - Get details of a specific status by ID\n- `create_status` - Create a new status in a project\n- `update_status` - Update an existing status\n\n#### **\ud83d\udcc1 Folder Management**\n- `get_folders` - Get all folders with optional project and type filtering\n- `get_folder` - Get details of a specific folder by ID\n- `create_folder` - Create a new folder in a project\n\n#### **\ud83d\udcdd Test Step Management**\n- `get_test_steps` - Retrieve test steps for a specific test case with pagination support\n- `create_test_steps` - Create test steps for a test case with APPEND/OVERWRITE modes\n\n#### **\ud83d\udcc4 Test Script Management**\n- `get_test_script` - Retrieve test script for a specific test case\n- `create_test_script` - Create or update test script with plain text or BDD format\n\n#### **\ud83d\udccb Test Case Management**\n- `get_test_case` - Get detailed test case information including metadata, status, priority, and content\n- `get_test_cases` - Retrieve test cases with advanced offset-based pagination and filtering\n- `create_test_case` - Create new test cases with comprehensive metadata support\n- `update_test_case` - Update existing test cases with validation and error handling\n- `get_test_case_versions` - Retrieve version history for test cases\n- `get_test_case_version` - Get specific version of a test case\n- `get_links` - Get all links (issues + web links) associated with a test case\n\n#### **\ud83d\udd17 Test Case Links**\n- `create_issue_link` - Link test cases to Jira issues for traceability\n- `create_web_link` - Add web links to test cases for documentation\n\n## \ud83d\udcca Status Operations Guide\n\nStatus operations allow you to manage test execution statuses in Zephyr Scale Cloud. Each status can be associated with different entity types:\n\n### **Status Types:**\n- `TEST_CASE` - For test case statuses\n- `TEST_PLAN` - For test plan statuses \n- `TEST_CYCLE` - For test cycle statuses\n- `TEST_EXECUTION` - For test execution statuses\n\n### **Example Usage:**\n\n```python\n# Get all statuses for a specific project and type\nstatuses = await get_statuses(\n project_key=\"MYPROJ\",\n status_type=\"TEST_EXECUTION\",\n max_results=100\n)\n\n# Create a new test execution status\nnew_status = await create_status(\n project_key=\"MYPROJ\",\n name=\"In Review\",\n status_type=\"TEST_EXECUTION\",\n description=\"Test is under review\",\n color=\"#FFA500\"\n)\n\n# Update an existing status\nupdated = await update_status(\n status_id=123,\n project_id=456,\n name=\"Reviewed\",\n index=5,\n description=\"Test has been reviewed and approved\"\n)\n```\n\n### **Status Properties:**\n- **Name**: Human-readable status name (max 255 chars)\n- **Type**: One of the four status types listed above\n- **Description**: Optional detailed description (max 255 chars)\n- **Color**: Optional hex color code (e.g., '#FF0000')\n- **Index**: Position/order in status lists\n- **Default**: Whether this is the default status for the type\n- **Archived**: Whether the status is archived\n\n## \ud83d\udcc1 Folder Operations Guide\n\nFolder operations allow you to organize and manage test artifacts in Zephyr Scale Cloud. Folders provide hierarchical structure for test cases, test plans, and test cycles.\n\n### **Folder Types:**\n- `TEST_CASE` - For organizing test cases\n- `TEST_PLAN` - For organizing test plans \n- `TEST_CYCLE` - For organizing test cycles\n\n### **Example Usage:**\n\n```python\n# Get all folders for a specific project and type\nfolders = await get_folders(\n project_key=\"MYPROJ\",\n folder_type=\"TEST_CASE\",\n max_results=100\n)\n\n# Create a new root folder\nroot_folder = await create_folder(\n name=\"Smoke Tests\",\n project_key=\"MYPROJ\",\n folder_type=\"TEST_CASE\"\n # parent_id is None for root folders\n)\n\n# Create a child folder\nchild_folder = await create_folder(\n name=\"Login Tests\",\n project_key=\"MYPROJ\", \n folder_type=\"TEST_CASE\",\n parent_id=123 # ID of the parent folder\n)\n\n# Get details of a specific folder\nfolder_details = await get_folder(folder_id=456)\n```\n\n### **Folder Properties:**\n- **Name**: Human-readable folder name (1-255 chars)\n- **Type**: One of the three folder types listed above\n- **Project Key**: Jira project key where the folder belongs\n- **Parent ID**: ID of parent folder (null for root folders)\n- **Index**: Position/order within the parent folder\n- **ID**: Unique identifier assigned by Zephyr Scale\n\n### **Folder Hierarchy:**\n- Folders can be nested to create hierarchical organization\n- Root folders have `parent_id = null`\n- Child folders reference their parent via `parent_id`\n- Each folder type maintains its own hierarchy within a project\n\n## \ud83d\udd27 Test Case Management Guide\n\nThe test case management tools provide comprehensive CRUD operations for managing test cases in Zephyr Scale Cloud.\n\n### **Key Features:**\n- **Full CRUD Operations**: Create, read, update, and retrieve test cases\n- **Advanced Pagination**: Efficient offset-based pagination with performance optimizations\n- **Version Management**: Access to test case version history\n- **Link Management**: Connect test cases to Jira issues and web resources\n- **Rich Metadata**: Support for priorities, statuses, folders, components, and custom fields\n- **Environment Integration**: Automatic project key resolution from environment variables\n\n### **Pagination Performance Tips:**\n- Use `max_results=1000` for fastest bulk data retrieval\n- Follow offset-based pagination: `start_at = current_start_at + max_results`\n- Ensure `start_at` is a multiple of `max_results` (API requirement)\n- Check `len(values) < max_results` to detect the last page\n\n### **Example Usage:**\n\n```python\n# Get test cases with maximum performance\ntest_cases = await get_test_cases(\n project_key=\"MYPROJ\",\n max_results=1000, # Maximum for best performance\n start_at=0\n)\n\n# Create a comprehensive test case\nnew_test_case = await create_test_case(\n name=\"Login functionality test\",\n project_key=\"MYPROJ\",\n objective=\"Verify user can log in successfully\",\n priority_name=\"High\",\n status_name=\"Draft\",\n folder_id=123,\n labels=[\"smoke\", \"authentication\"]\n)\n\n# Update test case with validation\nupdated = await update_test_case(\n test_case_key=\"MYPROJ-T123\",\n name=\"Updated login test\",\n priority_id=456,\n status_id=789\n)\n\n# Link to Jira issue for traceability\nlink_result = await create_issue_link(\n test_case_key=\"MYPROJ-T123\",\n issue_id=456789\n)\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Model Context Protocol server for Zephyr Scale Cloud",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/basterboy/mcp-zephyr-scale-cloud",
"Issues": "https://github.com/basterboy/mcp-zephyr-scale-cloud/issues",
"Repository": "https://github.com/basterboy/mcp-zephyr-scale-cloud"
},
"split_keywords": [
"mcp",
" zephyr",
" scale",
" testing",
" jira"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "759c5a2148426aa141b0fdead5b68a811b40394061e2b335227f50c30954ddc2",
"md5": "47db496eac9bdf9028719a4661eb1bbc",
"sha256": "fa4d32527cd786853405c5c3f142050474aeb567a4563cce638a381a3062bbe6"
},
"downloads": -1,
"filename": "mcp_zephyr_scale_cloud-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47db496eac9bdf9028719a4661eb1bbc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 38968,
"upload_time": "2025-09-05T17:47:10",
"upload_time_iso_8601": "2025-09-05T17:47:10.052299Z",
"url": "https://files.pythonhosted.org/packages/75/9c/5a2148426aa141b0fdead5b68a811b40394061e2b335227f50c30954ddc2/mcp_zephyr_scale_cloud-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ca4ce07439fe0a8ef91276f2478f8b383d78ea63e4630700a9c64fe2c17a4a9d",
"md5": "9cb834a8bcdef096cbbf6249d0fc4556",
"sha256": "272ba518af87754785e3d637a4fe9c8d14dcfe265172845bb12e8fb7bb19e362"
},
"downloads": -1,
"filename": "mcp_zephyr_scale_cloud-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "9cb834a8bcdef096cbbf6249d0fc4556",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 36970,
"upload_time": "2025-09-05T17:47:11",
"upload_time_iso_8601": "2025-09-05T17:47:11.245514Z",
"url": "https://files.pythonhosted.org/packages/ca/4c/e07439fe0a8ef91276f2478f8b383d78ea63e4630700a9c64fe2c17a4a9d/mcp_zephyr_scale_cloud-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 17:47:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "basterboy",
"github_project": "mcp-zephyr-scale-cloud",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-zephyr-scale-cloud"
}
JSON
