JIRA MCP Server

Instructions

Implementation Reference

• src/features/jira/issues/handlers/get-issue-comments.handler.ts:26-124 (handler)

  The GetIssueCommentsHandler class implements the core execution logic: validates parameters, fetches comments via use case, formats output using CommentsFormatter, and provides enhanced error messages.

  export class GetIssueCommentsHandler extends BaseToolHandler<
    GetIssueCommentsParams,
    string
  > {
    private formatter: CommentsFormatter;
  
    /**
     * Create a new GetIssueCommentsHandler with use case and validator
     *
     * @param getIssueCommentsUseCase - Use case for issue comment operations
     * @param issueCommentValidator - Validator for issue comment parameters
     */
    constructor(
      private readonly getIssueCommentsUseCase: GetIssueCommentsUseCase,
      private readonly issueCommentValidator: IssueCommentValidator,
    ) {
      super("JIRA", "Get Issue Comments");
      this.formatter = new CommentsFormatter();
    }
  
    /**
     * Execute the handler logic
     * Retrieves comments for a JIRA issue and formats them using the formatter
     *
     * @param params - Parameters for comment retrieval with progressive disclosure options
     */
    protected async execute(params: GetIssueCommentsParams): Promise<string> {
      try {
        // Step 1: Validate parameters
        const validatedParams =
          this.issueCommentValidator.validateGetCommentsParams(params);
        this.logger.info(
          `Getting comments for JIRA issue: ${validatedParams.issueKey}`,
        );
  
        // Step 2: Get comments using use case
        this.logger.debug("Retrieving comments with params:", {
          issueKey: validatedParams.issueKey,
          hasAuthorFilter: !!validatedParams.authorFilter,
          hasDateRange: !!validatedParams.dateRange,
          includeInternal: validatedParams.includeInternal,
          maxComments: validatedParams.maxComments,
        });
  
        const comments =
          await this.getIssueCommentsUseCase.execute(validatedParams);
  
        // Step 3: Create formatting context
        const context: CommentsContext = {
          issueKey: validatedParams.issueKey,
          totalComments: comments.length,
          maxDisplayed: comments.length,
        };
  
        // Step 4: Format the comments using the formatter
        return this.formatter.format({ comments, context });
      } catch (error) {
        this.logger.error(`Failed to get comments: ${error}`);
        throw this.enhanceError(error, params);
      }
    }
  
    /**
     * Enhance error messages for better user guidance
     */
    private enhanceError(error: unknown, params?: GetIssueCommentsParams): Error {
      const issueContext = params?.issueKey
        ? ` for issue ${params.issueKey}`
        : "";
  
      if (error instanceof JiraNotFoundError) {
        return new Error(
          `❌ **No Comments Found**\n\nNo comments found${issueContext}.\n\n**Solutions:**\n- Verify the issue key is correct\n- Check if the issue has any comments\n- Try including internal comments\n- Use \`jira_get_issue\` to verify the issue exists\n\n**Example:** \`jira_get_issue_comments issueKey="PROJ-123"\``,
        );
      }
  
      if (error instanceof JiraPermissionError) {
        return new Error(
          `❌ **Permission Denied**\n\nYou don't have permission to view comments${issueContext}.\n\n**Solutions:**\n- Check your JIRA permissions\n- Contact your JIRA administrator\n- Verify you have access to the issue\n- Use \`jira_get_issue\` to see accessible issues\n\n**Required Permissions:** Browse Projects`,
        );
      }
  
      if (error instanceof JiraApiError) {
        return new Error(
          `❌ **JIRA API Error**\n\n${error.message}\n\n**Solutions:**\n- Verify the issue key is valid\n- Check your filter parameters\n- Try with different filters\n\n**Example:** \`jira_get_issue_comments issueKey="PROJ-123" maxComments=5\``,
        );
      }
  
      if (error instanceof Error) {
        return new Error(
          `❌ **Comments Retrieval Failed**\n\n${error.message}${issueContext}\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_issue_comments issueKey="PROJ-123"\``,
        );
      }
  
      return new Error(
        `❌ **Unknown Error**\n\nAn unknown error occurred during comment retrieval${issueContext}.\n\nPlease check your parameters and try again.`,
      );
    }
  }

• src/features/jira/issues/validators/issue-comment.validator.ts:16-33 (schema)

  Zod schema defining input parameters for the tool, including required issueKey and optional filters like maxComments, author, date range.

  export const getIssueCommentsSchema = z.object({
    // Core parameters (required/essential)
    issueKey: issueKeySchema,
  
    // Basic options (most common use cases)
    maxComments: z.number().int().min(1).max(100).optional().default(10),
  
    // Advanced options (power user features)
    includeInternal: z.boolean().optional().default(false),
    orderBy: z.enum(["created", "updated"]).optional().default("created"),
    authorFilter: z.string().min(1).optional(),
    dateRange: z
      .object({
        from: z.string().datetime().optional(),
        to: z.string().datetime().optional(),
      })
      .optional(),
  });

• src/features/jira/tools/configs/issue-tools.config.ts:37-41 (registration)

  Tool configuration object defining the name, description, input schema, and handler binding for registration.

    name: "jira_get_issue_comments",
    description: "Retrieves comments for a specific JIRA issue with configurable quantity and filtering options",
    params: getIssueCommentsSchema.shape,
    handler: tools.jira_get_issue_comments.handle.bind(tools.jira_get_issue_comments),
  },

• src/features/jira/tools/factories/tool.factory.ts:73-100 (helper)

  Factory function creates and wraps the GetIssueCommentsHandler instance into the ToolHandler interface expected by the registry.

  const getIssueCommentsHandler = new GetIssueCommentsHandler(
    dependencies.getIssueCommentsUseCase,
    dependencies.issueCommentValidator,
  );
  
  const getAssignedIssuesHandler = new GetAssignedIssuesHandler(
    dependencies.getAssignedIssuesUseCase,
  );
  
  const createIssueHandler = new CreateIssueHandler(
    dependencies.createIssueUseCase,
  );
  
  const updateIssueHandler = new UpdateIssueHandler(
    dependencies.updateIssueUseCase,
  );
  
  const searchIssuesHandler = new SearchIssuesHandler(
    dependencies.searchIssuesUseCase,
  );
  
  return {
    jira_get_issue: {
      handle: async (args: unknown) => getIssueHandler.handle(args),
    },
    jira_get_issue_comments: {
      handle: async (args: unknown) => getIssueCommentsHandler.handle(args),
    },

• src/features/jira/tools/registry/tool.registry.ts:146-152 (registration)

  Generic registration code that calls MCP server.tool() with the configuration from issue-tools.config.ts for all tools including jira_get_issue_comments.

  server.tool(
    toolName,
    config.description,
    config.params,
    adaptHandler(config.handler),
  );