jira_get_boards

Instructions

Implementation Reference

• src/features/jira/boards/handlers/get-boards.handler.ts:23-128 (handler)

  GetBoardsHandler class: core implementation of the jira_get_boards tool logic, including parameter validation, use case execution, response formatting, and comprehensive error handling.

  export class GetBoardsHandler extends BaseToolHandler<GetBoardsParams, string> {
    private boardListFormatter: BoardListFormatter;
  
    /**
     * Create a new GetBoardsHandler with use case and validator
     *
     * @param getBoardsUseCase - Use case for retrieving boards
     * @param boardValidator - Validator for board parameters
     */
    constructor(
      private readonly getBoardsUseCase: GetBoardsUseCase,
      private readonly boardValidator: BoardValidator,
    ) {
      super("JIRA", "Get Boards");
      this.boardListFormatter = new BoardListFormatter();
    }
  
    /**
     * Execute the handler logic
     * Retrieves JIRA boards with optional filtering and formatting
     *
     * @param params - Parameters for board retrieval
     */
    protected async execute(params: GetBoardsParams): Promise<string> {
      try {
        // Step 1: Validate parameters
        const validatedParams =
          this.boardValidator.validateGetBoardsParams(params);
        this.logger.info("Getting JIRA boards");
  
        // Step 2: Get boards using use case
        this.logger.debug("Retrieving boards with params:", {
          hasType: !!validatedParams.type,
          hasProject: !!validatedParams.projectKeyOrId,
          hasName: !!validatedParams.name,
          maxResults: validatedParams.maxResults,
        });
  
        const boards = await this.getBoardsUseCase.execute(validatedParams);
  
        // Step 3: Format and return success response
        this.logger.info(`Successfully retrieved ${boards.length} boards`);
        return this.boardListFormatter.format({
          boards,
          appliedFilters: {
            type: validatedParams.type,
            projectKeyOrId: validatedParams.projectKeyOrId,
            name: validatedParams.name,
          },
        });
      } catch (error) {
        this.logger.error(`Failed to get JIRA boards: ${error}`);
        throw this.enhanceError(error, params);
      }
    }
  
    /**
     * Enhance error messages for better user guidance
     */
    private enhanceError(error: unknown, params?: GetBoardsParams): Error {
      const filterContext = this.getFilterContext(params);
  
      if (error instanceof JiraNotFoundError) {
        return new Error(
          `❌ **No Boards Found**\n\nNo boards found${filterContext}.\n\n**Solutions:**\n- Check your search criteria are correct\n- Try removing filters to see all boards\n- Verify you have permission to view boards\n\n**Example:** \`jira_get_boards type="scrum"\``,
        );
      }
  
      if (error instanceof JiraPermissionError) {
        return new Error(
          `❌ **Permission Denied**\n\nYou don't have permission to view boards${filterContext}.\n\n**Solutions:**\n- Check your JIRA permissions\n- Contact your JIRA administrator\n- Verify you're logged in with the correct account\n\n**Required Permissions:** Browse Projects`,
        );
      }
  
      if (error instanceof JiraApiError) {
        return new Error(
          `❌ **JIRA API Error**\n\n${error.message}\n\n**Solutions:**\n- Check your filter parameters are valid\n- Try removing filters to see all boards\n- Verify your project key is correct\n- Check board type is valid (scrum, kanban, simple)\n\n**Example:** \`jira_get_boards projectKeyOrId="PROJ" type="scrum"\``,
        );
      }
  
      if (error instanceof Error) {
        return new Error(
          `❌ **Board Retrieval Failed**\n\n${error.message}${filterContext}\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_boards maxResults=10\``,
        );
      }
  
      return new Error(
        `❌ **Unknown Error**\n\nAn unknown error occurred during board retrieval${filterContext}.\n\nPlease check your parameters and try again.`,
      );
    }
  
    /**
     * Get filter context for error messages
     */
    private getFilterContext(params?: GetBoardsParams): string {
      if (!params) return "";
  
      const filters = [];
      if (params.type) filters.push(`type: ${params.type}`);
      if (params.projectKeyOrId)
        filters.push(`project: ${params.projectKeyOrId}`);
      if (params.name) filters.push(`name: "${params.name}"`);
  
      return filters.length > 0 ? ` with filters (${filters.join(", ")})` : "";
    }
  }

• src/features/jira/boards/validators/board.validator.ts:14-36 (schema)

  Zod schema defining the input parameters for the jira_get_boards tool, including pagination, filtering by type/project/name, and other options.

  export const getBoardsParamsSchema = z.object({
    // Pagination
    startAt: z.number().int().min(0).optional().default(0),
    maxResults: z.number().int().min(1).max(50).optional().default(50),
  
    // Filtering options
    type: z.enum(["scrum", "kanban", "simple"]).optional(),
    name: z.string().min(1).optional(),
    projectKeyOrId: z.string().min(1).optional(),
  
    // Location filtering
    accountIdLocation: z.string().min(1).optional(),
    projectLocation: z.string().min(1).optional(),
    includePrivate: z.boolean().optional(),
    negateLocationFiltering: z.boolean().optional(),
  
    // Ordering and expansion
    orderBy: z.enum(["name", "type"]).optional(),
    expand: z.enum(["admins", "permissions"]).optional(),
  
    // Filter by saved filter
    filterId: z.string().min(1).optional(),
  });

• src/features/jira/tools/configs/board-tools.config.ts:19-25 (registration)

  Tool configuration defining the name, description, schema, and handler for jira_get_boards.

    {
      name: "jira_get_boards",
      description: "Get all accessible JIRA boards with filtering by type, project, and name",
      params: getBoardsParamsSchema.shape,
      handler: tools.jira_get_boards.handle.bind(tools.jira_get_boards),
    },
  ];

• src/features/jira/tools/factories/tool.factory.ts:181-185 (handler)

  Factory creating the jira_get_boards tool handler wrapper that delegates to GetBoardsHandler instance.

  return {
    jira_get_boards: {
      handle: async (args: unknown) => getBoardsHandler.handle(args),
    },
  };

• src/features/jira/tools/registry/tool.registry.ts:82-86 (registration)

  Tool registry configuration group that includes the board tools config for MCP server registration.

    groupName: "boards",
    configs: createBoardToolsConfig({
      jira_get_boards: tools.jira_get_boards,
    }),
  },