jira_get_projects
Retrieve and filter JIRA projects with specific criteria such as type, category, or search query, and manage results with pagination and ordering options.
Instructions
Get all accessible JIRA projects with filtering and search capabilities
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | No | ||
| expand | No | ||
| maxResults | No | ||
| orderBy | No | ||
| properties | No | ||
| recent | No | ||
| searchQuery | No | ||
| startAt | No | ||
| typeKey | No |
Implementation Reference
- Core handler class that executes the jira_get_projects tool logic: input validation, use case execution, error handling with user-friendly messages, and output formatting.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 defining the name, description, input schema, and handler binding for registering jira_get_projects with the MCP server.{ 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), },
- Factory function creating the ToolHandler wrapper for jira_get_projects by instantiating GetProjectsHandler and binding its handle method.jira_get_projects: { handle: async (args: unknown) => getProjectsHandler.handle(args), },
- src/features/jira/tools/registry/tool.registry.ts:77-79 (registration)Inclusion of project tools config (containing jira_get_projects) in the tool registry groups for MCP server registration.configs: createProjectToolsConfig({ jira_get_projects: tools.jira_get_projects, }),