MCP Zephyr

# MCP Zephyr A Model Context Protocol (MCP) server for Zephyr Scale Cloud test management. This MCP server provides tools to manage test cases, test executions, test cycles, and test plans in Zephyr Scale Cloud. ## Features - **Test Case Management**: Create, read, update, delete, and search test cases - **Test Execution**: Execute tests and track results with detailed step-by-step outcomes - **Test Cycle Management**: Organize test cases into cycles and manage execution progress - **Test Plan Management**: Create and manage comprehensive test plans - **Bulk Operations**: Efficiently handle multiple test executions at once - **Search and Filtering**: Use JQL (Jira Query Language) for advanced test case searching ## Prerequisites - Node.js 18+ - Zephyr Scale Cloud account with API access - Valid Zephyr API token ## Installation 1. Clone this repository: ```bash git clone <repository-url> cd mcp-zephyr ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ## Configuration Create a `.env` file based on `.env.example`: ```bash cp .env.example .env ``` Edit `.env` with your Zephyr Scale Cloud credentials: ```env # Required: Your Zephyr API token ZEPHYR_API_TOKEN=your_api_token_here # Optional: Base URL (defaults to official Zephyr Scale Cloud API) ZEPHYR_BASE_URL=https://api.zephyrscale.smartbear.com/v2 # Optional: Default project key ZEPHYR_PROJECT_KEY=your_project_key_here ``` ### Getting Your API Token 1. Log into your Zephyr Scale Cloud instance 2. Navigate to **Settings** > **API Tokens** 3. Generate a new API token with appropriate permissions 4. Copy the token and add it to your `.env` file ## Usage ### Start the MCP Server ```bash npm start ``` Or for development: ```bash npm run dev ``` ### Integration with Claude Desktop Add this server to your Claude Desktop configuration: ```json { "mcpServers": { "zephyr": { "command": "node", "args": ["/path/to/mcp-zephyr/dist/index.js"], "env": { "ZEPHYR_API_TOKEN": "your_api_token_here", "ZEPHYR_BASE_URL": "https://api.zephyrscale.smartbear.com/v2", "ZEPHYR_PROJECT_KEY": "your_project_key_here" } } } } ``` ## Available Tools ### Test Case Management #### `zephyr_list_test_cases` List test cases in a project. - **Parameters**: `projectKey`, `maxResults`, `startAt` #### `zephyr_get_test_case` Get a specific test case by key. - **Parameters**: `testCaseKey` #### `zephyr_create_test_case` Create a new test case. - **Parameters**: `projectKey`, `name`, `objective`, `precondition`, `status`, `priority`, `component`, `estimatedTime`, `labels`, `steps` #### `zephyr_update_test_case` Update an existing test case. - **Parameters**: `testCaseKey`, plus any fields to update #### `zephyr_delete_test_case` Delete a test case. - **Parameters**: `testCaseKey` #### `zephyr_search_test_cases` Search test cases using JQL. - **Parameters**: `jql`, `maxResults` ### Test Execution Management #### `zephyr_list_test_executions` List executions for a test cycle. - **Parameters**: `testCycleKey`, `maxResults` #### `zephyr_get_test_execution` Get a specific test execution. - **Parameters**: `executionKey` #### `zephyr_create_test_execution` Create a new test execution. - **Parameters**: `testCaseKey`, `testCycleKey`, `status`, `executedBy`, `actualTime`, `comment`, `defects`, `stepResults` #### `zephyr_update_test_execution` Update an existing test execution. - **Parameters**: `executionKey`, plus any fields to update #### `zephyr_bulk_create_test_executions` Create multiple test executions at once. - **Parameters**: `executions` (array) #### `zephyr_get_test_case_executions` Get all executions for a test case. - **Parameters**: `testCaseKey`, `maxResults` #### `zephyr_get_test_results` Get test results for a test cycle. - **Parameters**: `testCycleKey`, `maxResults` ### Test Cycle Management #### `zephyr_list_test_cycles` List test cycles in a project. - **Parameters**: `projectKey`, `maxResults` #### `zephyr_get_test_cycle` Get a specific test cycle. - **Parameters**: `testCycleKey` #### `zephyr_create_test_cycle` Create a new test cycle. - **Parameters**: `projectKey`, `name`, `description`, `status`, `environment`, `startDate`, `endDate` #### `zephyr_update_test_cycle` Update an existing test cycle. - **Parameters**: `testCycleKey`, plus any fields to update #### `zephyr_add_test_cases_to_cycle` Add test cases to a test cycle. - **Parameters**: `testCycleKey`, `testCaseKeys` (array) #### `zephyr_remove_test_cases_from_cycle` Remove test cases from a test cycle. - **Parameters**: `testCycleKey`, `testCaseKeys` (array) ### Test Plan Management #### `zephyr_list_test_plans` List test plans in a project. - **Parameters**: `projectKey`, `maxResults` #### `zephyr_get_test_plan` Get a specific test plan. - **Parameters**: `testPlanKey` #### `zephyr_create_test_plan` Create a new test plan. - **Parameters**: `projectKey`, `name`, `description`, `status`, `startDate`, `endDate` #### `zephyr_update_test_plan` Update an existing test plan. - **Parameters**: `testPlanKey`, plus any fields to update ## Examples ### Creating a Test Case ```javascript await zephyr_create_test_case({ projectKey: "PROJ", name: "User Login Test", objective: "Verify users can successfully log in with valid credentials", precondition: "User must have valid account", status: "Draft", priority: "High", steps: [ { action: "Navigate to login page", expected: "Login page is displayed", stepIndex: 1 }, { action: "Enter valid username and password", expected: "Fields accept input", stepIndex: 2 }, { action: "Click login button", expected: "User is redirected to dashboard", stepIndex: 3 } ] }); ``` ### Creating a Test Execution ```javascript await zephyr_create_test_execution({ testCaseKey: "PROJ-T1", testCycleKey: "PROJ-C1", status: "Pass", executedBy: "test.user@company.com", actualTime: 5, comment: "All steps executed successfully", stepResults: [ { stepIndex: 0, status: "Pass", actual: "Login page loaded correctly" }, { stepIndex: 1, status: "Pass", actual: "Credentials accepted" }, { stepIndex: 2, status: "Pass", actual: "Successfully redirected to dashboard" } ] }); ``` ### Searching Test Cases ```javascript await zephyr_search_test_cases({ jql: "project = PROJ AND status = 'Draft' AND priority = High", maxResults: 25 }); ``` ## Error Handling The server provides detailed error messages for common issues: - **Authentication errors**: Invalid API token - **Authorization errors**: Insufficient permissions - **Validation errors**: Invalid input data - **Network errors**: Connection issues - **API limits**: Rate limiting exceeded ## Development ### Project Structure ``` src/ ├── index.ts # Main MCP server entry point ├── zephyr-client.ts # Zephyr API client ├── types.ts # TypeScript type definitions └── tools/ # MCP tool implementations ├── test-case-tools.ts ├── test-execution-tools.ts ├── test-cycle-tools.ts └── test-plan-tools.ts ``` ### Building ```bash npm run build ``` ### Testing ```bash npm run dev ``` ### Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Support For issues related to: - **This MCP server**: Create an issue in this repository - **Zephyr Scale Cloud**: Contact SmartBear support - **MCP protocol**: See [Model Context Protocol documentation](https://modelcontextprotocol.io/) ## Changelog ### v1.0.0 - Initial release - Full test case management - Test execution tracking - Test cycle and plan management - Bulk operations support - JQL search functionality