# Zephyr Scale MCP Server

Model Context Protocol (MCP) server that integrates with Zephyr Scale test management tool for Jira. This server allows Claude Desktop and other MCP clients to fetch and update test case information directly from Zephyr Scale.

**→ [Quick Start Guide](QUICK_START.md)** - Get up and running in 5 minutes

## Features

- **Read Operations:**
  - Fetch test case information with steps, labels, details, priority, and status
  - Get complete raw test case object from API
- **Write Operations:**
  - Update test case labels
  - Update any test case field (objective, precondition, priority, etc.)
  - Automatic handling of mandatory fields
- **Developer Friendly:**
  - Support for both WSL2 and Windows environments
  - Easy integration with Claude Desktop
  - Natural language interactions in chat

## Prerequisites

- Node.js (v16 or higher)
- npm or yarn
- Zephyr Scale API token
- TypeScript (included as dev dependency)
- For WSL2 users: WSL2 with Ubuntu or similar distro

## Installation

1. Clone or navigate to the project directory:

```bash
cd /path/to/mcp-zephyr
```

2. Install dependencies:

```bash
npm install
```

3. Build the TypeScript code:

```bash
npm run build
```

## Configuration

### 1. Get Your Zephyr Scale API Token

1. Log in to your Jira/Zephyr Scale account
2. Navigate to API token settings
3. Generate a new API token
4. Copy the token for the next step

### 2. Configure Claude Desktop

**For detailed step-by-step instructions, see the [Quick Start Guide](QUICK_START.md)**

Edit your Claude Desktop configuration file:
- Windows: `C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**WSL2 Configuration Example:**
```json
{
  "mcpServers": {
    "zephyr-steps-server": {
      "command": "wsl",
      "args": [
        "bash",
        "-c",
        "cd /home/username/mcpServers/mcp-zephyr && ZEPHYR_API_KEY='your_token' /path/to/node dist/index.js"
      ]
    }
  }
}
```

**Windows Configuration Example:**
```json
{
  "mcpServers": {
    "zephyr-steps-server": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\mcp-zephyr\\dist\\index.js"],
      "env": {
        "ZEPHYR_API_KEY": "your_zephyr_api_token_here"
      }
    }
  }
}
```

See [QUICK_START.md](QUICK_START.md) for complete configuration examples and troubleshooting.

## Usage

### With Claude Desktop

Once configured in Claude Desktop, restart the application. The tools will be available for use in your chat.

#### Fetching Test Case Information

Ask Claude naturally:
```
Get the test steps for RADAR-T1
```
```
Show me test case RDR-T23 with all details
```
```
What are the labels on RADAR-T5?
```

**Returns:**
- Test case name and key
- All labels
- Objective/description
- Preconditions
- Priority and status
- Complete test steps with instructions and expected results

#### Updating Test Case Labels

Ask Claude to update labels:
```
Update labels for RADAR-T1 to: smoke-test, regression, automated
```
```
Set labels for RDR-T23 to: critical, P1
```
```
Remove all labels from RADAR-T5
```

**Note:** When updating labels, Claude will first fetch the current test case information to understand the context, then update the labels.

#### Updating Other Test Case Fields

For advanced updates (objective, precondition, priority, etc.):
```
Update the objective for RADAR-T1 to "Verify login functionality with valid credentials"
```
```
Change the priority of RDR-T23 to High
```

Claude will:
1. Fetch the complete test case details
2. Modify the requested fields
3. Update the test case with all mandatory fields intact

### Available Tools

**get_zephyr_steps**

Fetches complete test case information including labels, details, and test steps from Zephyr Scale.

**Input:**
- `testCaseKey` (string): The test case ID (e.g., "RADAR-T1")

**Output:**
- JSON object containing:
  - `testCaseKey`: Test case ID
  - `name`: Test case name
  - `labels`: Array of labels assigned to the test case
  - `objective`: Test objective/description from Details
  - `precondition`: Prerequisites for the test
  - `priority`: Priority level
  - `status`: Current test case status
  - `steps`: Array of test steps with:
    - `index`: Step number
    - `instruction`: Step description
    - `expectedResult`: Expected outcome
    - `testData`: Test data (if applicable)

**update_test_case_labels**

Updates the labels for a specific test case in Zephyr Scale.

**Input:**
- `testCaseKey` (string): The test case ID (e.g., "RADAR-T1")
- `labels` (array of strings): List of labels to set for the test case

**Output:**
- Success message confirming the labels were updated

**Important Notes:**
- This tool **REPLACES** all existing labels with the new list provided
- To add a label, you must include all existing labels plus the new one
- To remove a label, provide the list without it
- To remove all labels, provide an empty array `[]`

**Example Usage:**
- "Update RADAR-T1 labels to: smoke-test, regression, high-priority"
- "Set labels for RADAR-T5 to: critical, P1"
- "Remove all labels from RADAR-T10"

**get_test_case_details**

Fetches the complete raw test case object from Zephyr Scale API.

**Input:**
- `testCaseKey` (string): The test case ID (e.g., "RADAR-T1")

**Output:**
- Complete JSON object with all test case fields as returned by Zephyr API

**Use Case:**
- Get the full test case structure including all mandatory fields
- Useful before making updates to ensure all required fields are present
- Returns raw API response for maximum flexibility

**update_test_case**

Updates a test case with a complete payload to satisfy mandatory field requirements.

**Input:**
- `testCaseKey` (string): The test case ID (e.g., "RADAR-T1")
- `payload` (object): The complete test case object with modified fields

**Output:**
- Success message confirming the update

**Workflow:**
1. Use `get_test_case_details` to fetch the current test case
2. Modify the desired fields in the returned object
3. Use `update_test_case` with the modified object

**Important Notes:**
- Zephyr API requires all mandatory fields to be present in PUT requests
- This tool accepts the complete payload to avoid "missing mandatory field" errors
- Best practice: Always fetch details first, then update

**Example Usage:**
- "Update the objective for RADAR-T1 to 'Test login functionality'"
- "Change priority of RDR-T23 to High"
- "Update precondition for RADAR-T5"

## Development

### Build

Compile TypeScript to JavaScript:
```bash
npm run build
```

### Watch Mode

Automatically recompile on changes:
```bash
npm run watch
```

### Project Structure

```
mcp-zephyr/
├── dist/                # Compiled JavaScript (generated, gitignored)
│   ├── index.js         # Main MCP server (compiled)
│   └── index.d.ts       # TypeScript definitions
├── node_modules/        # Dependencies (gitignored)
├── index.ts             # Source code - MCP Server implementation
├── package.json         # Node.js dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── .gitignore           # Git ignore rules
├── QUICK_START.md       # Quick start guide (5-minute setup)
├── README.md            # Complete documentation (this file)
└── CLAUDE.md            # Claude Code project instructions
```

## API Integration

- **Base URL**: `https://api.zephyrscale.smartbear.com/v2`
- **Endpoints**:
  - `GET /testcases/{testCaseKey}` - Fetch test case details, labels, and metadata
  - `GET /testcases/{testCaseKey}/teststeps` - Fetch test steps
  - `PUT /testcases/{testCaseKey}` - Update test case details (including labels)
- **Authentication**: Bearer token via Authorization header

## Troubleshooting

**For common issues and solutions, see the [Quick Start Guide - Troubleshooting section](QUICK_START.md#troubleshooting)**

### "ZEPHYR_API_KEY environment variable is not set"

Make sure you have set the `ZEPHYR_API_KEY` correctly in your Claude Desktop configuration.

**WSL2:** Set it in the bash command: `ZEPHYR_API_KEY='your_token'`
**Windows:** Set it in the `env` section of the config

### "Server disconnected" or "Cannot attach to MCP server"

**Check the logs:**
```
C:\Users\YourUsername\AppData\Roaming\Claude\logs\mcp-server-zephyr-steps-server.log
```

**Common causes:**
- Incorrect Node.js path (WSL2 users: use full path like `/home/user/.nvm/versions/node/v22.17.1/bin/node`)
- Missing `dist/index.js` file (run `npm run build`)
- Invalid API token

### "Cannot find module" errors

Run `npm install` to ensure all dependencies are installed, then rebuild:
```bash
npm install
npm run build
```

### "node: command not found" (WSL2 only)

When using WSL2, don't use just `node` - use the full path to your Node.js binary:
```bash
# Find your node path
which node
# Use that full path in claude_desktop_config.json
```

## License

ISC

## Support

For issues or questions, refer to the MCP SDK documentation or Zephyr Scale API documentation.