jira_get_boards
Retrieve accessible JIRA boards with filters for type, project, and name to streamline project management and task organization directly within your workflow.
Instructions
Get all accessible JIRA boards with filtering by type, project, and name
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountIdLocation | No | ||
| expand | No | ||
| filterId | No | ||
| includePrivate | No | ||
| maxResults | No | ||
| name | No | ||
| negateLocationFiltering | No | ||
| orderBy | No | ||
| projectKeyOrId | No | ||
| projectLocation | No | ||
| startAt | No | ||
| type | No |
Implementation Reference
- GetBoardsHandler class implements the core execution logic for the jira_get_boards tool. It validates parameters, executes the use case to fetch boards, formats the response, and handles errors with user-friendly messages.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(", ")})` : ""; } }
- Zod schema defining input parameters for jira_get_boards tool, including pagination, filtering by type/project/name, location filters, ordering, and expansion 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:15-25 (registration)Tool configuration for registering jira_get_boards, specifying name, description, input schema, and handler binding.export function createBoardToolsConfig(tools: { jira_get_boards: ToolHandler; }): ToolConfig[] { return [ { 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:175-186 (registration)Factory function creating the jira_get_boards tool handler instance by instantiating GetBoardsHandler with dependencies and wrapping its handle method.function createBoardHandlers(dependencies: JiraDependencies) { const getBoardsHandler = new GetBoardsHandler( dependencies.getBoardsUseCase, dependencies.boardValidator, ); 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 for boards, invoking the board tools config with the jira_get_boards handler.groupName: "boards", configs: createBoardToolsConfig({ jira_get_boards: tools.jira_get_boards, }), },