jira_get_sprints
Retrieve sprints from a JIRA board with filtering by state (future, active, or closed) to track project progress and manage agile workflows.
Instructions
Get all sprints for a specific JIRA board with filtering by state
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| boardId | Yes | ||
| startAt | No | ||
| maxResults | No | ||
| state | No |
Implementation Reference
- GetSprintsHandler: Core tool handler executing validation, business logic via use case, error enhancement, and output formatting.export class GetSprintsHandler extends BaseToolHandler< GetSprintsParams, string > { private sprintListFormatter: SprintListFormatter; /** * Create a new GetSprintsHandler with use case and validator * * @param getSprintsUseCase - Use case for retrieving sprints * @param sprintValidator - Validator for sprint parameters */ constructor( private readonly getSprintsUseCase: GetSprintsUseCase, private readonly sprintValidator: SprintValidator, ) { super("JIRA", "Get Sprints"); this.sprintListFormatter = new SprintListFormatter(); } /** * Execute the handler logic * Retrieves JIRA sprints with optional filtering and formatting * * @param params - Parameters for sprint retrieval */ protected async execute(params: GetSprintsParams): Promise<string> { try { // Step 1: Validate parameters const validatedParams = this.sprintValidator.validateGetSprintsParams(params); this.logger.info( `Getting JIRA sprints for board: ${validatedParams.boardId}`, ); // Step 2: Get sprints using use case this.logger.debug("Retrieving sprints with params:", { boardId: validatedParams.boardId, hasState: !!validatedParams.state, maxResults: validatedParams.maxResults, }); const sprints = await this.getSprintsUseCase.execute(validatedParams); // Step 3: Format and return success response this.logger.info(`Successfully retrieved ${sprints.length} sprints`); return this.sprintListFormatter.format({ sprints, boardId: validatedParams.boardId, appliedFilters: { state: validatedParams.state, boardId: validatedParams.boardId, }, }); } catch (error) { this.logger.error(`Failed to get JIRA sprints: ${error}`); throw this.enhanceError(error, params); } } /** * Enhance error messages for better user guidance */ private enhanceError(error: unknown, params?: GetSprintsParams): Error { const boardContext = params?.boardId ? ` for board ${params.boardId}` : ""; if (error instanceof JiraNotFoundError) { return new Error( `❌ **No Sprints Found**\n\nNo sprints found${boardContext}.\n\n**Solutions:**\n- Verify the board ID is correct\n- Check if the board has any sprints created\n- Try removing state filters to see all sprints\n- Use \`jira_get_boards\` to find valid board IDs\n\n**Example:** \`jira_get_sprints boardId=123\``, ); } if (error instanceof JiraPermissionError) { return new Error( `❌ **Permission Denied**\n\nYou don't have permission to view sprints${boardContext}.\n\n**Solutions:**\n- Check your JIRA permissions\n- Contact your JIRA administrator\n- Verify you have access to the board\n- Use \`jira_get_boards\` to see accessible boards\n\n**Required Permissions:** Browse Projects`, ); } if (error instanceof JiraApiError) { return new Error( `❌ **JIRA API Error**\n\n${error.message}\n\n**Solutions:**\n- Verify the board ID is valid\n- Check your filter parameters\n- Try with a different board\n- Ensure the board supports sprints (Scrum boards)\n\n**Example:** \`jira_get_sprints boardId=123 state="active"\``, ); } if (error instanceof Error) { return new Error( `❌ **Sprint Retrieval Failed**\n\n${error.message}${boardContext}\n\n**Solutions:**\n- Check your parameters are valid\n- Try a simpler query first\n- Verify your JIRA connection\n\n**Example:** \`jira_get_sprints boardId=123\``, ); } return new Error( `❌ **Unknown Error**\n\nAn unknown error occurred during sprint retrieval${boardContext}.\n\nPlease check your parameters and try again.`, ); } }
- Zod schema defining the input parameters for the jira_get_sprints tool.export const getSprintsParamsSchema = z.object({ boardId: z.number().int().min(1, "Board ID must be a positive integer"), // Pagination startAt: z.number().int().min(0).optional().default(0), maxResults: z.number().int().min(1).max(50).optional().default(50), // Filtering options state: z.nativeEnum(SprintState).optional(), });
- src/features/jira/tools/factories/tool.factory.ts:191-202 (registration)Factory creating the GetSprintsHandler instance and wrapping it as the jira_get_sprints tool handler.function createSprintHandlers(dependencies: JiraDependencies) { const getSprintsHandler = new GetSprintsHandler( dependencies.getSprintsUseCase, dependencies.sprintValidator, ); return { jira_get_sprints: { handle: async (args: unknown) => getSprintsHandler.handle(args), }, }; }
- src/features/jira/tools/configs/sprint-tools.config.ts:15-26 (registration)Configuration defining tool metadata, schema reference, and handler binding for registration.export function createSprintToolsConfig(tools: { jira_get_sprints: ToolHandler; }): ToolConfig[] { return [ { name: "jira_get_sprints", description: "Get all sprints for a specific JIRA board with filtering by state", params: getSprintsParamsSchema.shape, handler: tools.jira_get_sprints.handle.bind(tools.jira_get_sprints), }, ]; }
- src/features/jira/tools/registry/tool.registry.ts:88-92 (registration)Tool registry including the sprint tools config group, leading to MCP server.tool() registration.groupName: "sprints", configs: createSprintToolsConfig({ jira_get_sprints: tools.jira_get_sprints, }), },
- Repository method performing the actual JIRA API call to retrieve sprints for a board.async getSprints( boardId: number, options?: GetSprintsOptions, ): Promise<Sprint[]> { this.logger.debug(`Getting sprints for board: ${boardId}`, { prefix: "JIRA:SprintRepository", }); const queryParams: Record<string, string | number | undefined> = {}; if (options?.startAt) { queryParams.startAt = options.startAt; } if (options?.maxResults) { queryParams.maxResults = options.maxResults; } if (options?.state) { queryParams.state = options.state; } const response = await this.httpClient.sendRequest<{ values: Sprint[] }>({ endpoint: `board/${boardId}/sprint`, method: "GET", queryParams, }); return response.values; }