JIRA MCP Server

Instructions

Implementation Reference

• src/features/jira/sprints/handlers/get-sprints.handler.ts:24-118 (handler)

  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.`,
      );
    }
  }

• src/features/jira/sprints/validators/sprint.validator.ts:18-27 (schema)

  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,
    }),
  },

• src/features/jira/sprints/repositories/sprint.repository.ts:25-54 (helper)

  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;
  }