jira_get_projects

Instructions

Implementation Reference

• src/features/jira/projects/handlers/get-projects.handler.ts:23-123 (handler)

  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(", ")})` : "";
    }
  }

• src/features/jira/projects/validators/project-params.validator.ts:14-47 (schema)

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

• src/features/jira/tools/configs/project-tools.config.ts:20-24 (registration)

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