# Zephyr Scale MCP Server

A Model Context Protocol (MCP) server for Zephyr Scale Test Management. This server provides comprehensive tools for interacting with Zephyr Scale through any LLM that supports MCP.

## Features

- **Test Case Management**: Search, view, and manage test cases
- **Test Run Operations**: Create, clone, and manage test runs
- **Folder Management**: Organize test runs in folders with automated workflows
- **Assignment Tools**: Bulk assign test results to team members
- **Complete Workflows**: Automated folder creation and test run cloning

## Prerequisites

- Python 3.10+
- Jira instance with Zephyr Scale installed
- Jira API token (generate from your Atlassian account settings)

## Installation

```bash
# Clone the repository
git clone https://github.com/ivinitus/zephyr-scale-mcp.git
cd zephyr-scale-mcp

# Install the package
pip install -e .

# Or install dependencies manually
pip install -r requirements.txt
```

## Configuration

Set the following environment variables:

```bash
export ZEPHYR_BASE_URL="https://your-domain.atlassian.net"
export ZEPHYR_USERNAME="your-email@example.com"
export ZEPHYR_API_TOKEN="your-api-token"
```

### Getting Your API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a label and copy the token
4. Use your email as username and the token as password

## Usage with MCP Clients

### Amazon Q Developer

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "zephyr-scale": {
      "command": "python",
      "args": ["-m", "zephyr_scale_mcp"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-domain.atlassian.net",
        "ZEPHYR_USERNAME": "your-email@example.com",
        "ZEPHYR_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zephyr-scale": {
      "command": "python",
      "args": ["-m", "zephyr_scale_mcp"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-domain.atlassian.net",
        "ZEPHYR_USERNAME": "your-email@example.com",
        "ZEPHYR_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Available Tools

### Test Case Tools
- `get_testcase_detail` - Get detailed information about a test case
- `search_testcases` - Search for test cases with filters
- `get_testcase_attachments` - Get attachments for a test case
- `get_testcase_latest_result` - Get the latest test result

### Test Run Tools
- `get_testrun_details` - Get test run information
- `get_testrun_results` - Get all results for a test run
- `search_testruns` - Search for test runs
- `get_testrun_items` - Get test run items with details

### Assignment Tools
- `update_test_assignee` - Assign a test result to a user
- `bulk_update_test_assignees` - Bulk assign multiple test results

### Folder Management Tools
- `get_folder_tree` - Get folder structure
- `find_folder_by_name` - Find a folder by name
- `get_test_runs_in_folder` - Get all test runs in a folder
- `create_test_folder` - Create a new folder
- `generate_folder_name` - Generate folder name with date
- `check_folder_exists` - Check if folder exists

### Test Run Management Tools
- `bulk_clone_test_runs` - Clone multiple test runs
- `bulk_move_test_runs` - Move test runs to a folder
- `bulk_rename_test_runs` - Rename test runs (remove cloned suffix)
- `get_recently_created_test_runs` - Get recently created test runs

### Workflow Tools
- `create_folder_and_clone_runs` - Complete workflow to create folder and clone test runs

## Example Prompts

Once configured, you can ask your LLM:

- "Show me test case PROJECT-T123"
- "Search for test cases in project ABC with status 'Draft'"
- "Create a new folder called 'Sprint 24 Testing' in project 12345"
- "Clone all test runs from folder 'Sprint 23' to a new folder 'Sprint 24'"
- "Assign test results 123, 456, 789 to John Doe"

## Project Structure

```
zephyr-scale-mcp/
├── client.py          # Zephyr Scale API client
├── server.py          # MCP server with tool definitions
├── __init__.py        # Package initialization
├── README.md          # This file
├── requirements.txt   # Python dependencies
└── .env.example       # Example environment variables
```

## Development

### Running Tests

```bash
python -m pytest tests/
```

### Adding New Tools

1. Add the method to `ZephyrClient` in `client.py`
2. Create a tool function in `server.py` with the `@handle_api_errors` decorator
3. Register the tool in the `register_tools()` function
4. Export it in `__init__.py`

## Security Notes

- Never commit your API token to version control
- Use environment variables or secure secret management
- API tokens have the same permissions as your user account
- Consider creating a dedicated service account for automation

## Troubleshooting

### Authentication Errors
- Verify your API token is correct and not expired
- Check that your username is your email address
- Ensure your user has access to the Jira project

### Connection Errors
- Verify the base URL is correct (no trailing slash)
- Check your network connection and firewall settings
- Ensure Zephyr Scale is installed on your Jira instance

### Tool Errors
- Check that project IDs are numeric strings
- Verify test case/run keys follow the format "PROJECT-T123"
- Ensure you have permissions for the operations you're attempting

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT License - feel free to use this in your projects!

## Acknowledgments

Built for the MCP ecosystem to enable AI-powered test management workflows.