MCP Zephyr Server

A comprehensive Model Context Protocol (MCP) server for Zephyr Scale Cloud API that enables seamless integration with your test management workflows.

🚀 Features

Core Capabilities

• Project Management: List and retrieve project details

• Folder Organization: Create and manage hierarchical folder structures

• Test Case Management: Create, read, and update operations for test cases

• Test Steps Management: Get and append test steps (note: no individual step update/delete)

• Test Script Management: Create and manage BDD/Gherkin test scripts (mutually exclusive with steps)

• Reference Data: Access statuses and priorities for test case configuration

🛠️ Available Tools

Project Tools

• list_projects - Get all Zephyr-integrated Jira projects

• get_project - Retrieve detailed project information

Folder Tools

• list_folders - List folders with project/folder filtering

• get_folder - Get detailed folder information

• create_folder - Create new folders with optional parent hierarchy

Test Case Tools

• list_test_cases - List test cases with filtering (project, folder)

• get_test_case - Retrieve detailed test case information

• create_test_case - Create new test cases with full configuration

• update_test_case - Update existing test cases

Test Steps Tools

• get_test_steps - Get test steps (paged, 100 items max)

• get_all_test_steps - Get all test steps (auto-pagination)

• append_test_steps - Add new steps to existing sequence (max 100 per request)

Test Script Tools

• get_test_script - Get BDD/Gherkin test script

• create_test_script - Create/update test script (removes existing steps)

• create_bdd_test_script - Helper for BDD script creation with validation

Reference Data Tools

• list_statuses - Get all available statuses (Draft, Ready, Approved, etc.)

• list_priorities - Get all available priorities (High, Medium, Low, etc.)

• get_reference_data - Get both statuses and priorities in one call

📋 Prerequisites

• Node.js 18.0.0 or higher

• Zephyr Scale Cloud account with API access

• Jira project with Zephyr integration enabled

🔧 Installation

1. Clone or download this repository

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env

   Edit .env and add your Zephyr API token:

   ZEPHYR_API_TOKEN=your_bearer_token_here ZEPHYR_REGION=us

🔑 Getting Your API Token

1. Log in to your Jira Cloud instance

2. Click on your profile picture in the bottom left

3. Select "Zephyr API keys"

4. Generate a new API token

5. Copy the token to your .env file

🚀 Running the Server

Development Mode

Production Mode

With MCP Client

🧰 Testing Individual Tools

For development and debugging, you can test individual tools without running the full MCP server using the test-tools.js script:

List Available Tools

Test a Tool

Note: Make sure your .env file is configured with ZEPHYR_API_TOKEN before running test tools.

📝 Usage Examples

Basic Project Operations

Folder Management

Test Case Creation

Test Steps Management

BDD Test Script Creation

Get Reference Data

⚠️ Important Notes

Test Steps vs Test Scripts

• Mutually Exclusive: A test case can have either test steps OR a test script, not both

• Script Creation Warning: Creating a test script automatically removes existing test steps

• Step Limitations: Individual test steps cannot be updated or deleted, only appended in batches

API Constraints

• Pagination: Most endpoints support pagination (max 1000 items per request)

• Step Limits: Maximum 100 test steps can be added per request

• Rate Limits: Respect Zephyr Cloud API rate limits

• Region Support: US and EU regions supported via configuration

Data Format

• Test Case Keys: Format [A-Z]+-T[0-9]+ (e.g., PROJ-T1)

• Project Keys: Format [A-Z][A-Z_0-9]+ (e.g., PROJ, PROJ123)

• Folder IDs: Numeric strings (e.g., "123")

• Test Scripts: Gherkin format for BDD, plain text for simple scripts

🧪 Testing

🔍 Code Quality

🏗️ Project Structure

🔌 MCP Integration

This server implements the Model Context Protocol specification:

• Tool Discovery: Automatic tool listing via ListToolsRequestSchema

• Tool Execution: Standardized tool calling via CallToolRequestSchema

• Error Handling: Consistent error responses for all operations

• JSON Schema: Input validation for all tool parameters

🐛 Troubleshooting

Common Issues

1. "ZEPHYR_API_TOKEN environment variable is required"

   • Ensure you've created .env file with a valid API token

   • Check that the token is not expired

2. "Invalid testCaseKey format"

   • Test case keys must match pattern [A-Z]+-T[0-9]+

   • Examples: PROJ-T1, PROJECT123-T456

3. "Request timeout"

   • Check your internet connection

   • Try reducing maxResults parameter for large requests

4. "Test case not found"

   • Verify the test case key exists in your Zephyr instance

   • Ensure you have proper project permissions

Debug Mode

Enable debug logging by setting the environment variable:

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run the test suite

6. Submit a pull request

🆘 Support

• Zephyr Documentation: Zephyr Scale Cloud API Docs

• MCP Specification: Model Context Protocol

• Issues: Report bugs via GitHub Issues