JIRA Zephyr MCP Server

# Zephyr MCP Implementation Plan ## Overview This document outlines the implementation plan for a Model Context Protocol (MCP) server that integrates with JIRA's Zephyr test management system. The MCP server will provide tools for managing test plans, test cycles, and accessing JIRA issue information. ## Architecture ### Core Components - **MCP Server**: Main server handling MCP protocol communication - **JIRA Client**: HTTP client for JIRA REST API interactions - **Zephyr Client**: HTTP client for Zephyr API interactions - **Tool Handlers**: Individual functions implementing each MCP tool - **Configuration Manager**: Handles authentication and API endpoints ## Project Structure ``` jira-zephyr-mcp/ ├── src/ │ ├── index.ts # Main MCP server entry point │ ├── clients/ │ │ ├── jira-client.ts # JIRA API client │ │ └── zephyr-client.ts # Zephyr API client │ ├── tools/ │ │ ├── test-plans.ts # Test plan management tools │ │ ├── test-cycles.ts # Test cycle management tools │ │ ├── jira-issues.ts # JIRA issue reading tools │ │ └── test-execution.ts # Test execution tools │ ├── types/ │ │ ├── jira-types.ts # JIRA API response types │ │ └── zephyr-types.ts # Zephyr API response types │ └── utils/ │ ├── config.ts # Configuration utilities │ └── validation.ts # Input validation utilities ├── package.json ├── tsconfig.json ├── README.md └── .env.example ``` ## MCP Tools Implementation ### Primary Tools (Required) #### 1. create_test_plan - **Purpose**: Create new test plans in Zephyr - **Inputs**: - name: string (required) - description: string (optional) - projectKey: string (required) - startDate: string (optional) - endDate: string (optional) - **Output**: Created test plan details #### 2. create_test_cycle - **Purpose**: Create test execution cycles - **Inputs**: - name: string (required) - description: string (optional) - projectKey: string (required) - versionId: string (required) - environment: string (optional) - startDate: string (optional) - endDate: string (optional) - **Output**: Created test cycle details #### 3. read_jira_issue - **Purpose**: Retrieve JIRA issue information - **Inputs**: - issueKey: string (required) - fields: string[] (optional) - specific fields to retrieve - **Output**: JIRA issue details including custom fields ### Additional Useful Tools #### 4. list_test_plans - **Purpose**: Browse existing test plans - **Inputs**: - projectKey: string (required) - limit: number (optional, default: 50) - offset: number (optional, default: 0) - **Output**: List of test plans with basic details #### 5. list_test_cycles - **Purpose**: View test cycles and their status - **Inputs**: - projectKey: string (required) - versionId: string (optional) - limit: number (optional, default: 50) - **Output**: List of test cycles with execution status #### 6. execute_test - **Purpose**: Update test execution results - **Inputs**: - executionId: string (required) - status: string (required) - PASS, FAIL, WIP, BLOCKED - comment: string (optional) - defects: string[] (optional) - linked defect keys - **Output**: Updated execution details #### 7. get_test_execution_status - **Purpose**: Check test execution progress - **Inputs**: - cycleId: string (required) - **Output**: Execution statistics and progress #### 8. link_tests_to_issues - **Purpose**: Associate test cases with JIRA issues - **Inputs**: - testCaseId: string (required) - issueKeys: string[] (required) - **Output**: Link confirmation #### 9. generate_test_report - **Purpose**: Create test execution reports - **Inputs**: - cycleId: string (required) - format: string (optional) - JSON, HTML - **Output**: Test execution report data ## Technical Implementation Details ### Dependencies - `@modelcontextprotocol/sdk`: MCP SDK for server implementation - `axios`: HTTP client for API requests - `dotenv`: Environment variable management - `zod`: Schema validation for inputs and outputs ### Authentication - Basic Auth for JIRA API - API tokens for Zephyr Scale/Squad - Environment variables for credentials: - `JIRA_BASE_URL` - `JIRA_USERNAME` - `JIRA_API_TOKEN` - `ZEPHYR_API_TOKEN` ### Error Handling - Structured error responses with MCP error codes - API rate limiting considerations - Network timeout handling - Input validation using Zod schemas ### Type Safety - Complete TypeScript types for all API responses - Zod schemas for runtime validation - Generic error handling types ## Configuration ### Environment Variables ```bash JIRA_BASE_URL=https://your-domain.atlassian.net JIRA_USERNAME=your-email@company.com JIRA_API_TOKEN=your-jira-api-token ZEPHYR_API_TOKEN=your-zephyr-api-token ``` ### MCP Server Configuration ```json { "name": "jira-zephyr-mcp", "version": "1.0.0", "tools": [ "create_test_plan", "create_test_cycle", "read_jira_issue", "list_test_plans", "list_test_cycles", "execute_test", "get_test_execution_status", "link_tests_to_issues", "generate_test_report" ] } ``` ## Implementation Phases ### Phase 1: Core Setup 1. Initialize Node.js/TypeScript project 2. Set up MCP server framework 3. Create basic JIRA client 4. Implement read_jira_issue tool ### Phase 2: Test Management 1. Implement Zephyr client 2. Create test plan management tools 3. Create test cycle management tools 4. Add input validation ### Phase 3: Advanced Features 1. Implement test execution tools 2. Add reporting capabilities 3. Create linking functionality 4. Add comprehensive error handling ### Phase 4: Documentation & Polish 1. Complete README documentation 2. Add usage examples 3. Create configuration templates 4. Add logging and monitoring ## Testing Strategy - Unit tests for each tool function - Integration tests with JIRA/Zephyr APIs - Mock API responses for development - End-to-end testing with real JIRA instance ## Deployment Options - Local development server - Docker containerization - Claude Desktop integration - CI/CD pipeline setup ## Security Considerations - Secure credential storage - API token rotation - Input sanitization - Rate limiting compliance - Audit logging for sensitive operations