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

Clone or download this repository
Install dependencies:
```
npm install
```

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

Log in to your Jira Cloud instance
Click on your profile picture in the bottom left
Select "Zephyr API keys"
Generate a new API token
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

"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
"Invalid testCaseKey format"
- Test case keys must match pattern [A-Z]+-T[0-9]+
- Examples: PROJ-T1, PROJECT123-T456
"Request timeout"
- Check your internet connection
- Try reducing maxResults parameter for large requests
"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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

🆘 Support

Zephyr Documentation: Zephyr Scale Cloud API Docs
MCP Specification: Model Context Protocol
Issues: Report bugs via GitHub Issues