JIRA Zephyr MCP Server

Instructions

Implementation Reference

• src/tools/test-cases.ts:20-68 (handler)

  Main handler function that validates the input schema, calls the Zephyr client to create the test case, formats the response, and handles errors.
  export const createTestCase = async (input: CreateTestCaseInput) => { const validatedInput = createTestCaseSchema.parse(input); try { const testCase = await getZephyrClient().createTestCase({ projectKey: validatedInput.projectKey, name: validatedInput.name, objective: validatedInput.objective, precondition: validatedInput.precondition, estimatedTime: validatedInput.estimatedTime, priority: validatedInput.priority, status: validatedInput.status, folderId: validatedInput.folderId, labels: validatedInput.labels, componentId: validatedInput.componentId, customFields: validatedInput.customFields, testScript: validatedInput.testScript, }); return { success: true, data: { id: testCase.id, key: testCase.key, name: testCase.name, projectKey: testCase.project?.id, objective: testCase.objective, precondition: testCase.precondition, estimatedTime: testCase.estimatedTime, priority: testCase.priority?.id, status: testCase.status?.id, folder: testCase.folder?.id, labels: testCase.labels || [], component: testCase.component?.id, owner: testCase.owner?.accountId, createdOn: testCase.createdOn, links: { self: `https://api.zephyrscale.smartbear.com/v2/testcases/${testCase.key}`, issues: testCase.links?.issues?.length || 0, }, }, }; } catch (error: any) { return { success: false, error: error.response?.data?.message || error.message, }; } };
• src/utils/validation.ts:59-81 (schema)

  Zod schema defining the input structure and validation rules for create_test_case tool, used for parsing and type inference.
  export const createTestCaseSchema = z.object({ projectKey: z.string().min(1, 'Project key is required'), name: z.string().min(1, 'Name is required'), objective: z.string().optional(), precondition: z.string().optional(), estimatedTime: z.number().min(0).optional(), priority: z.string().optional(), status: z.string().optional(), folderId: z.string().optional(), labels: z.array(z.string()).optional(), componentId: z.string().optional(), customFields: z.record(z.any()).optional(), testScript: z.object({ type: z.enum(['STEP_BY_STEP', 'PLAIN_TEXT']), steps: z.array(z.object({ index: z.number().min(1), description: z.string().min(1), testData: z.string().optional(), expectedResult: z.string().min(1), })).optional(), text: z.string().optional(), }).optional(), });
• src/index.ts:184-226 (registration)

  Tool registration in the TOOLS array, defining name, description, and input schema for listTools endpoint.
  name: 'create_test_case', description: 'Create a new test case in Zephyr', inputSchema: { type: 'object', properties: { projectKey: { type: 'string', description: 'JIRA project key' }, name: { type: 'string', description: 'Test case name' }, objective: { type: 'string', description: 'Test case objective/description (optional)' }, precondition: { type: 'string', description: 'Test preconditions (optional)' }, estimatedTime: { type: 'number', description: 'Estimated execution time in minutes (optional)' }, priority: { type: 'string', description: 'Test case priority (optional)' }, status: { type: 'string', description: 'Test case status (optional)' }, folderId: { type: 'string', description: 'Folder ID to organize test case (optional)' }, labels: { type: 'array', items: { type: 'string' }, description: 'Test case labels (optional)' }, componentId: { type: 'string', description: 'Component ID (optional)' }, customFields: { type: 'object', description: 'Custom fields as key-value pairs (optional)' }, testScript: { type: 'object', description: 'Test script with steps (optional)', properties: { type: { type: 'string', enum: ['STEP_BY_STEP', 'PLAIN_TEXT'], description: 'Script type' }, steps: { type: 'array', items: { type: 'object', properties: { index: { type: 'number', description: 'Step number' }, description: { type: 'string', description: 'Step description' }, testData: { type: 'string', description: 'Test data (optional)' }, expectedResult: { type: 'string', description: 'Expected result' }, }, required: ['index', 'description', 'expectedResult'], }, description: 'Test steps (for STEP_BY_STEP type)', }, text: { type: 'string', description: 'Plain text script (for PLAIN_TEXT type)' }, }, required: ['type'], }, }, required: ['projectKey', 'name'], }, },
• src/index.ts:437-447 (registration)

  Dispatch handler in the CallToolRequest switch statement that validates arguments and invokes the createTestCase handler.
  case 'create_test_case': { const validatedArgs = validateInput<CreateTestCaseInput>(createTestCaseSchema, args, 'create_test_case'); return { content: [ { type: 'text', text: JSON.stringify(await createTestCase(validatedArgs), null, 2), }, ], }; }
• src/clients/zephyr-client.ts:201-262 (helper)

  ZephyrClient method that performs the actual API call to create the test case via POST /testcases.
  async createTestCase(data: { projectKey: string; name: string; objective?: string; precondition?: string; estimatedTime?: number; priority?: string; status?: string; folderId?: string; labels?: string[]; componentId?: string; customFields?: Record<string, any>; testScript?: { type: 'STEP_BY_STEP' | 'PLAIN_TEXT'; steps?: Array<{ index: number; description: string; testData?: string; expectedResult: string; }>; text?: string; }; }): Promise<ZephyrTestCase> { const payload: any = { projectKey: data.projectKey, name: data.name, objective: data.objective, precondition: data.precondition, estimatedTime: data.estimatedTime, }; if (data.priority) { payload.priority = data.priority; } if (data.status) { payload.status = data.status; } if (data.folderId) { payload.folderId = data.folderId; } if (data.labels && data.labels.length > 0) { payload.labels = data.labels; } if (data.componentId) { payload.componentId = data.componentId; } if (data.customFields) { payload.customFields = data.customFields; } if (data.testScript) { payload.testScript = data.testScript; } const response = await this.client.post('/testcases', payload); return response.data; }