JIRA Zephyr MCP Server

Instructions

Implementation Reference

• src/tools/test-cases.ts:70-108 (handler)

  Main handler function that parses input using schema, calls Zephyr client to search test cases, maps and returns formatted results or error.

  export const searchTestCases = async (input: SearchTestCasesInput) => {
    const validatedInput = searchTestCasesSchema.parse(input);
    
    try {
      const result = await getZephyrClient().searchTestCases(
        validatedInput.projectKey,
        validatedInput.query,
        validatedInput.limit
      );
      
      return {
        success: true,
        data: {
          testCases: result.testCases.map(testCase => ({
            id: testCase.id,
            key: testCase.key,
            name: testCase.name,
            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,
            linkedIssues: testCase.links?.issues?.length || 0,
          })),
          total: result.total,
          projectKey: validatedInput.projectKey,
        },
      };
    } catch (error: any) {
      return {
        success: false,
        error: error.response?.data?.message || error.message,
      };
    }

• src/utils/validation.ts:83-87 (schema)

  Zod schema defining input validation for the search_test_cases tool: requires projectKey, optional query and limit.

  export const searchTestCasesSchema = z.object({
    projectKey: z.string().min(1, 'Project key is required'),
    query: z.string().optional(),
    limit: z.number().min(1).max(100).default(50),
  });

• src/index.ts:228-239 (registration)

  Tool registration in the TOOLS array, defining name, description, and inputSchema for MCP server.

    name: 'search_test_cases',
    description: 'Search for test cases in a project',
    inputSchema: {
      type: 'object',
      properties: {
        projectKey: { type: 'string', description: 'JIRA project key' },
        query: { type: 'string', description: 'Search query (optional)' },
        limit: { type: 'number', description: 'Maximum number of results (default: 50)' },
      },
      required: ['projectKey'],
    },
  },

• src/index.ts:449-458 (registration)

  Dispatch handler in the MCP server's CallToolRequest switch statement that validates args and calls the searchTestCases function.

  case 'search_test_cases': {
    const validatedArgs = validateInput<SearchTestCasesInput>(searchTestCasesSchema, args, 'search_test_cases');
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(await searchTestCases(validatedArgs), null, 2),
        },
      ],
    };