jira_get_projects
Retrieve JIRA projects with filtering by type, category, or search terms to manage and organize work across teams.
Instructions
Get all accessible JIRA projects with filtering and search capabilities
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| expand | No | ||
| recent | No | ||
| properties | No | ||
| maxResults | No | ||
| startAt | No | ||
| typeKey | No | ||
| categoryId | No | ||
| searchQuery | No | ||
| orderBy | No |
Implementation Reference
- GetProjectsHandler class implementing the core tool logic: validates input parameters, executes the use case to fetch projects from JIRA, formats the results, and provides enhanced error messages with guidance.export class GetProjectsHandler extends BaseToolHandler< GetProjectsParams, string > { private readonly formatter: ProjectListFormatter; /** * Create a new GetProjectsHandler with use case and validator * * @param getProjectsUseCase - Use case for retrieving projects * @param projectParamsValidator - Validator for project parameters */ constructor( private readonly getProjectsUseCase: GetProjectsUseCase, private readonly projectParamsValidator: ProjectParamsValidator, ) { super("JIRA", "Get Projects"); this.formatter = new ProjectListFormatter(); } /** * Execute the handler logic * Retrieves JIRA projects with optional filtering and formatting * * @param params - Parameters for project retrieval */ protected async execute(params: GetProjectsParams): Promise<string> { try { // Step 1: Validate parameters const validatedParams = this.projectParamsValidator.validateGetProjectsParams(params); this.logger.info("Getting JIRA projects"); // Step 2: Get projects using use case this.logger.debug("Retrieving projects with params:", { hasSearch: !!validatedParams.searchQuery, hasTypeFilter: !!validatedParams.typeKey, maxResults: validatedParams.maxResults, }); const projects = await this.getProjectsUseCase.execute(validatedParams); // Step 3: Format and return success response this.logger.info(`Successfully retrieved ${projects.length} projects`); return this.formatter.format(projects); } catch (error) { this.logger.error(`Failed to get JIRA projects: ${error}`); throw this.enhanceError(error, params); } } /** * Enhance error messages for better user guidance */ private enhanceError(error: unknown, params?: GetProjectsParams): Error { const filterContext = this.getFilterContext(params); if (error instanceof JiraNotFoundError) { return new Error( `❌ **No Projects Found**\n\nNo projects found${filterContext}.\n\n**Solutions:**\n- Check your search query is correct\n- Try removing filters to see all projects\n- Verify you have permission to view projects\n\n**Example:** \`jira_get_projects searchQuery="web"\``, ); } if (error instanceof JiraPermissionError) { return new Error( `❌ **Permission Denied**\n\nYou don't have permission to view projects${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 projects\n- Verify your search query syntax\n- Check project type keys are correct\n\n**Example:** \`jira_get_projects searchQuery="web" typeKey="software"\``, ); } if (error instanceof Error) { return new Error( `❌ **Project 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_projects maxResults=10\``, ); } return new Error( "❌ **Unknown Error**\n\nAn unknown error occurred during project retrieval.\n\nPlease check your parameters and try again.", ); } /** * Get filter context for error messages */ private getFilterContext(params?: GetProjectsParams): string { if (!params) return ""; const filters = []; if (params.searchQuery) filters.push(`search: "${params.searchQuery}"`); if (params.typeKey) filters.push(`type: ${params.typeKey}`); if (params.categoryId) filters.push(`category: ${params.categoryId}`); if (params.recent) filters.push(`recent: ${params.recent}`); return filters.length > 0 ? ` with filters (${filters.join(", ")})` : ""; } }
- Zod schema defining the input parameters for the jira_get_projects tool, including search, filtering, pagination, and expansion options.export const getProjectsParamsSchema = z.object({ // Expansion options expand: z .array( z.enum([ "description", "lead", "issueTypes", "url", "projectKeys", "permissions", "insight", ]), ) .optional(), // Filtering options recent: z.number().int().min(1).max(20).optional(), properties: z.array(z.string().min(1)).optional(), // Pagination maxResults: z.number().int().min(1).max(50).optional().default(50), startAt: z.number().int().min(0).optional().default(0), // Project type filtering typeKey: z.enum(["software", "service_desk", "business"]).optional(), categoryId: z.number().int().min(1).optional(), // Search and ordering searchQuery: z.string().min(1).optional(), orderBy: z .enum(["category", "key", "name", "owner", "issueCount"]) .optional(), });
- Tool configuration registration defining the name, description, input schema, and handler for jira_get_projects.name: "jira_get_projects", description: "Get all accessible JIRA projects with filtering and search capabilities", params: getProjectsParamsSchema.shape, handler: tools.jira_get_projects.handle.bind(tools.jira_get_projects), },
- src/features/jira/tools/factories/tool.factory.ts:166-168 (registration)Creation of the ToolHandler object for jira_get_projects, wrapping the GetProjectsHandler.handle method.jira_get_projects: { handle: async (args: unknown) => getProjectsHandler.handle(args), },
- src/features/jira/tools/registry/tool.registry.ts:77-79 (registration)Registration of project tools config in the tool registry, passing the jira_get_projects handler.configs: createProjectToolsConfig({ jira_get_projects: tools.jira_get_projects, }),