list_test_cycles

Instructions

Implementation Reference

• src/tools/test-cycles.ts:57-106 (handler)

  The core handler function that validates input using listTestCyclesSchema, fetches test cycles from ZephyrClient, maps and formats the response including execution summary with pass rate, and handles errors.

  export const listTestCycles = async (input: ListTestCyclesInput) => {
    const validatedInput = listTestCyclesSchema.parse(input);
    
    try {
      const result = await getZephyrClient().getTestCycles(
        validatedInput.projectKey,
        validatedInput.versionId,
        validatedInput.limit
      );
      
      return {
        success: true,
        data: {
          total: result.total,
          testCycles: result.testCycles.map(cycle => ({
            id: cycle.id,
            key: cycle.key,
            name: cycle.name,
            description: cycle.description,
            projectId: cycle.projectId,
            versionId: cycle.versionId,
            environment: cycle.environment,
            status: cycle.status,
            plannedStartDate: cycle.plannedStartDate,
            plannedEndDate: cycle.plannedEndDate,
            actualStartDate: cycle.actualStartDate,
            actualEndDate: cycle.actualEndDate,
            createdOn: cycle.createdOn,
            updatedOn: cycle.updatedOn,
            executionSummary: {
              total: cycle.executionSummary.total,
              passed: cycle.executionSummary.passed,
              failed: cycle.executionSummary.failed,
              blocked: cycle.executionSummary.blocked,
              inProgress: cycle.executionSummary.inProgress,
              notExecuted: cycle.executionSummary.notExecuted,
              passRate: cycle.executionSummary.total > 0 
                ? Math.round((cycle.executionSummary.passed / cycle.executionSummary.total) * 100)
                : 0,
            },
          })),
        },
      };
    } catch (error: any) {
      return {
        success: false,
        error: error.response?.data?.message || error.message,
      };
    }
  };

• src/utils/validation.ts:32-36 (schema)

  Zod schema defining the input structure for list_test_cycles tool: projectKey (required), versionId (optional), limit (default 50, max 100).

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

• src/index.ts:121-133 (registration)

  MCP tool registration in the TOOLS array, specifying name, description, and inputSchema matching the Zod schema.

  {
    name: 'list_test_cycles',
    description: 'List existing test cycles with execution status',
    inputSchema: {
      type: 'object',
      properties: {
        projectKey: { type: 'string', description: 'JIRA project key' },
        versionId: { type: 'string', description: 'JIRA version ID (optional)' },
        limit: { type: 'number', description: 'Maximum number of results (default: 50)' },
      },
      required: ['projectKey'],
    },
  },

• src/index.ts:377-387 (registration)

  Switch case dispatcher in CallToolRequest handler that validates args with listTestCyclesSchema and calls the listTestCycles handler function.

  case 'list_test_cycles': {
    const validatedArgs = validateInput<ListTestCyclesInput>(listTestCyclesSchema, args, 'list_test_cycles');
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(await listTestCycles(validatedArgs), null, 2),
        },
      ],
    };
  }

• src/tools/test-cycles.ts:11-16 (helper)

  Helper function to lazily initialize and return the shared ZephyrClient instance used by listTestCycles.

  const getZephyrClient = (): ZephyrClient => {
    if (!zephyrClient) {
      zephyrClient = new ZephyrClient();
    }
    return zephyrClient;
  };