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

npm run dev

Production Mode

npm start

With MCP Client

# Start the server
npm start

# In another terminal, use with your MCP client
# Configuration will be automatically discovered

🧰 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

node test-tools.js --list

Test a Tool

# Simple tool without arguments
node test-tools.js list_projects

# Tool with arguments (pass JSON)
node test-tools.js list_projects '{"maxResults": 10}'

# Get specific project
node test-tools.js get_project '{"projectId": "PROJ1"}'

# Create a test case
node test-tools.js create_test_case '{"name": "Login Test", "projectKey": "PROJ"}'

# List test cases with filtering
node test-tools.js list_test_cases '{"projectKey": "PROJ", "maxResults": 5}'

# Get reference data
node test-tools.js get_reference_data

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

📝 Usage Examples

Basic Project Operations

// List all projects
{
  "tool": "list_projects",
  "arguments": {
    "maxResults": 50
  }
}

// Get specific project
{
  "tool": "get_project",
  "arguments": {
    "projectId": "PROJ"
  }
}

Folder Management

// Create a folder
{
  "tool": "create_folder",
  "arguments": {
    "name": "Smoke Tests",
    "projectKey": "PROJ",
    "parentFolderId": "123"
  }
}

Test Case Creation

// Create a comprehensive test case
{
  "tool": "create_test_case",
  "arguments": {
    "name": "User Login Test",
    "projectKey": "PROJ",
    "description": "Verify user can log in with valid credentials",
    "priorityName": "High",
    "statusName": "Ready",
    "folderId": "123",
    "component": "Authentication",
    "labels": ["smoke", "regression"],
    "objective": "Verify login functionality",
    "precondition": "User exists in system",
    "estimatedTime": 5
  }
}

Test Steps Management

// Append test steps
{
  "tool": "append_test_steps",
  "arguments": {
    "testCaseKey": "PROJ-T1",
    "steps": [
      {
        "description": "Navigate to login page",
        "expectedResult": "Login page is displayed"
      },
      {
        "description": "Enter valid username and password",
        "expectedResult": "Credentials are accepted"
      },
      {
        "description": "Click login button",
        "expectedResult": "User is logged in and redirected to dashboard"
      }
    ]
  }
}

BDD Test Script Creation

// Create BDD script with helper
{
  "tool": "create_bdd_test_script",
  "arguments": {
    "testCaseKey": "PROJ-T2",
    "feature": "User Authentication",
    "scenario": "Successful login with valid credentials",
    "steps": [
      "Given I am on the login page",
      "And I have valid user credentials",
      "When I enter my username and password",
      "And I click the login button",
      "Then I should be redirected to the dashboard",
      "And I should see my username displayed"
    ]
  }
}

Get Reference Data

// Get all statuses and priorities
{
  "tool": "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

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

🔍 Code Quality

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

🏗️ Project Structure

mcp-zephyr/
├── src/
│   ├── config.js              # Configuration management
│   ├── zephyr-client.js       # API client with error handling
│   ├── index.js               # Main MCP server entry point
│   └── tools/                 # MCP tool implementations
│       ├── project-tools.js
│       ├── folder-tools.js
│       ├── test-case-tools.js
│       ├── test-steps-tools.js
│       ├── test-script-tools.js
│       └── reference-data-tools.js
├── tests/                     # Unit tests
│   ├── setup.js
│   ├── config.test.js
│   ├── zephyr-client.test.js
│   └── tools/
│       └── project-tools.test.js
├── .env.example               # Environment template
├── package.json               # Dependencies and scripts
├── eslint.config.js           # ESLint configuration
├── jest.config.js             # Jest test configuration
└── README.md                  # This file

🔌 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:

DEBUG=* npm start

📄 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