@atlassian-dc-mcp/bitbucket 0.24.0 → 0.25.1

package/src/__tests__/bitbucket-service.test.ts

@@ -16,6 +16,7 @@ jest.mock('../bitbucket-client/index.js', () => ({
   PullRequestsService: {
     streamRawDiff2: jest.fn(),
     createComment2: jest.fn(),
+    updateComment2: jest.fn(),
     streamChanges1: jest.fn(),
     create: jest.fn(),
     update: jest.fn(),
@@ -860,10 +861,8 @@ describe('BitbucketService', () => {
           line: 15,
           lineType: 'ADDED',
           fileType: 'TO',
-          multilineAnchor: true,
-          multilineStartLine: 10,
-          multilineStartLineType: 'ADDED',
-          multilineDestinationRange: { minimum: 10, maximum: 15 }
+          multilineMarker: { startLine: 10, startLineType: 'ADDED' },
+          multilineSpan: { dstSpanStart: 10, dstSpanEnd: 15 }
         }
       };
       (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue(mockComment);
@@ -905,10 +904,8 @@ describe('BitbucketService', () => {
             line: 15,
             lineType: 'ADDED',
             fileType: 'TO',
-            multilineAnchor: true,
-            multilineStartLine: 10,
-            multilineStartLineType: 'ADDED',
-            multilineDestinationRange: { minimum: 10, maximum: 15 }
+            multilineMarker: { startLine: 10, startLineType: 'ADDED' },
+            multilineSpan: { dstSpanStart: 10, dstSpanEnd: 15 }
           }
         }
       );
@@ -925,10 +922,8 @@ describe('BitbucketService', () => {
           line: 8,
           lineType: 'ADDED',
           fileType: 'TO',
-          multilineAnchor: true,
-          multilineStartLine: 5,
-          multilineStartLineType: 'CONTEXT',
-          multilineDestinationRange: { minimum: 5, maximum: 8 }
+          multilineMarker: { startLine: 5, startLineType: 'CONTEXT' },
+          multilineSpan: { dstSpanStart: 5, dstSpanEnd: 8 }
         }
       };
       (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue(mockComment);
@@ -958,15 +953,133 @@ describe('BitbucketService', () => {
             line: 8,
             lineType: 'ADDED',
             fileType: 'TO',
-            multilineAnchor: true,
-            multilineStartLine: 5,
-            multilineStartLineType: 'CONTEXT',
-            multilineDestinationRange: { minimum: 5, maximum: 8 }
+            multilineMarker: { startLine: 5, startLineType: 'CONTEXT' },
+            multilineSpan: { dstSpanStart: 5, dstSpanEnd: 8 }
           }
         }
       );
     });
 
+    it('should normalize a reversed multiline range (startLine > line)', async () => {
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue({ id: 1, anchor: { path: 'src/test.js' } });
+
+      await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        'Reversed range',
+        undefined,      // parentId
+        'src/test.js',  // filePath
+        15,             // startLine (greater than line)
+        'ADDED',        // startLineType
+        10,             // line (end line, smaller)
+        'ADDED'         // lineType
+      );
+
+      expect(PullRequestsService.createComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        mockPullRequestId,
+        mockRepositorySlug,
+        {
+          text: 'Reversed range',
+          anchor: {
+            path: 'src/test.js',
+            diffType: 'EFFECTIVE',
+            line: 15,
+            lineType: 'ADDED',
+            fileType: 'TO',
+            multilineMarker: { startLine: 10, startLineType: 'ADDED' },
+            multilineSpan: { dstSpanStart: 10, dstSpanEnd: 15 }
+          }
+        }
+      );
+    });
+
+    it('should anchor a REMOVED multiline range to the source file', async () => {
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue({ id: 1, anchor: { path: 'src/test.js' } });
+
+      await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        'Removed range',
+        undefined,      // parentId
+        'src/test.js',  // filePath
+        2,              // startLine
+        'REMOVED',      // startLineType
+        5,              // line (end line)
+        'REMOVED'       // lineType
+      );
+
+      expect(PullRequestsService.createComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        mockPullRequestId,
+        mockRepositorySlug,
+        {
+          text: 'Removed range',
+          anchor: {
+            path: 'src/test.js',
+            diffType: 'EFFECTIVE',
+            line: 5,
+            lineType: 'REMOVED',
+            fileType: 'FROM',
+            multilineMarker: { startLine: 2, startLineType: 'REMOVED' },
+            multilineSpan: { srcSpanStart: 2, srcSpanEnd: 5 }
+          }
+        }
+      );
+    });
+
+    it('should warn when a multi-line suggestion is anchored to a single line', async () => {
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue({
+        id: 99,
+        anchor: { path: 'src/test.js', line: 5, lineType: 'ADDED' }
+      });
+
+      const result = await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        '```suggestion\nconst a = 1;\nconst b = 2;\n```',
+        undefined,      // parentId
+        'src/test.js',  // filePath
+        undefined,      // startLine (single-line anchor — the bug shape)
+        undefined,      // startLineType
+        5,              // line
+        'ADDED'         // lineType
+      );
+
+      expect(result.success).toBe(true);
+      expect((result.data as any).warning).toMatch(/multi-line ```suggestion/);
+      // single-line anchor: no multiline fields sent
+      const sentAnchor = (PullRequestsService.createComment2 as jest.Mock).mock.calls[0][3].anchor;
+      expect(sentAnchor.multilineMarker).toBeUndefined();
+      expect(sentAnchor.multilineSpan).toBeUndefined();
+    });
+
+    it('should not warn when a multi-line suggestion has a proper multiline range', async () => {
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue({
+        id: 100,
+        anchor: { path: 'src/test.js', line: 5, lineType: 'ADDED', multilineMarker: { startLine: 4, startLineType: 'ADDED' } }
+      });
+
+      const result = await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        '```suggestion\nconst a = 1;\nconst b = 2;\n```',
+        undefined,      // parentId
+        'src/test.js',  // filePath
+        4,              // startLine
+        'ADDED',        // startLineType
+        5,              // line
+        'ADDED'         // lineType
+      );
+
+      expect(result.success).toBe(true);
+      expect((result.data as any).warning).toBeUndefined();
+    });
+
     it('should handle API errors gracefully', async () => {
       const mockError = new Error('API Error');
       (PullRequestsService.createComment2 as jest.Mock).mockRejectedValue(mockError);
@@ -2002,6 +2115,181 @@ describe('BitbucketService', () => {
     });
   });
 
+  describe('updatePullRequestComment', () => {
+    it('should resolve a task by sending state RESOLVED with the version', async () => {
+      const mockComment = { id: 500, version: 2, state: 'RESOLVED', text: 'Task body' };
+      (PullRequestsService.updateComment2 as jest.Mock).mockResolvedValue(mockComment);
+
+      const result = await bitbucketService.updatePullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        '500',      // commentId
+        1,          // version
+        undefined,  // text
+        'RESOLVED'  // state
+      );
+
+      expect(result.success).toBe(true);
+      expect(PullRequestsService.updateComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        '500',
+        mockPullRequestId,
+        mockRepositorySlug,
+        { version: 1, state: 'RESOLVED' }
+      );
+    });
+
+    it('should edit the comment text without changing state or severity', async () => {
+      const mockComment = { id: 501, version: 3, text: 'Edited text' };
+      (PullRequestsService.updateComment2 as jest.Mock).mockResolvedValue(mockComment);
+
+      await bitbucketService.updatePullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        '501',
+        2,
+        'Edited text'
+      );
+
+      expect(PullRequestsService.updateComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        '501',
+        mockPullRequestId,
+        mockRepositorySlug,
+        { version: 2, text: 'Edited text' }
+      );
+    });
+
+    it('should support combining text, state, and severity in a single update', async () => {
+      const mockComment = { id: 502, version: 4, text: 'New body', state: 'RESOLVED', severity: 'BLOCKER' };
+      (PullRequestsService.updateComment2 as jest.Mock).mockResolvedValue(mockComment);
+
+      await bitbucketService.updatePullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        '502',
+        3,
+        'New body',
+        'RESOLVED',
+        'BLOCKER'
+      );
+
+      expect(PullRequestsService.updateComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        '502',
+        mockPullRequestId,
+        mockRepositorySlug,
+        { version: 3, text: 'New body', state: 'RESOLVED', severity: 'BLOCKER' }
+      );
+    });
+
+    it('should propagate API errors', async () => {
+      (PullRequestsService.updateComment2 as jest.Mock).mockRejectedValue(new Error('Conflict'));
+
+      const result = await bitbucketService.updatePullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        '503',
+        1,
+        undefined,
+        'RESOLVED'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Conflict');
+    });
+  });
+
+  describe('postPullRequestComment - severity flag', () => {
+    it('should include severity: BLOCKER in the request body when severity is BLOCKER', async () => {
+      const mockComment = { id: 200, text: 'Task comment', author: { displayName: 'Test User' } };
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue(mockComment);
+
+      const result = await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        'Task comment',
+        undefined,  // parentId
+        undefined,  // filePath
+        undefined,  // startLine
+        undefined,  // startLineType
+        undefined,  // line
+        undefined,  // lineType
+        undefined,  // pending
+        'BLOCKER'   // severity
+      );
+
+      expect(result.success).toBe(true);
+      expect(PullRequestsService.createComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        mockPullRequestId,
+        mockRepositorySlug,
+        { text: 'Task comment', severity: 'BLOCKER' }
+      );
+    });
+
+    it('should NOT include severity in the request body when severity is omitted', async () => {
+      const mockComment = { id: 201, text: 'Normal comment', author: { displayName: 'Test User' } };
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue(mockComment);
+
+      await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        'Normal comment'
+      );
+
+      expect(PullRequestsService.createComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        mockPullRequestId,
+        mockRepositorySlug,
+        { text: 'Normal comment' } // no severity field
+      );
+    });
+
+    it('should support severity BLOCKER combined with a file/line anchor', async () => {
+      const mockComment = { id: 202, text: 'Inline task', author: { displayName: 'Test User' } };
+      (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue(mockComment);
+
+      await bitbucketService.postPullRequestComment(
+        mockProjectKey,
+        mockRepositorySlug,
+        mockPullRequestId,
+        'Inline task',
+        undefined,      // parentId
+        'src/index.ts', // filePath
+        undefined,      // startLine
+        undefined,      // startLineType
+        10,             // line
+        'ADDED',        // lineType
+        undefined,      // pending
+        'BLOCKER'       // severity
+      );
+
+      expect(PullRequestsService.createComment2).toHaveBeenCalledWith(
+        mockProjectKey,
+        mockPullRequestId,
+        mockRepositorySlug,
+        {
+          text: 'Inline task',
+          severity: 'BLOCKER',
+          anchor: {
+            path: 'src/index.ts',
+            diffType: 'EFFECTIVE',
+            line: 10,
+            lineType: 'ADDED',
+            fileType: 'TO'
+          }
+        }
+      );
+    });
+  });
+
   describe('postPullRequestComment - pending flag', () => {
     it('should include state: PENDING in the request body when pending is true', async () => {
       const mockComment = { id: 99, text: 'Draft comment', author: { displayName: 'Test User' } };

package/src/__tests__/bitbucket-token-optimization.test.ts

@@ -390,7 +390,7 @@ describe('BitbucketService token optimization paths', () => {
       };
       (PullRequestsService.createComment2 as jest.Mock).mockResolvedValue(mockComment);
 
-      const result = await service.postPullRequestComment('TEST', 'repo', '123', 'Raw comment', undefined, undefined, undefined, undefined, undefined, undefined, undefined, 'full');
+      const result = await service.postPullRequestComment('TEST', 'repo', '123', 'Raw comment', undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, 'full');
 
       expect(result.success).toBe(true);
       expect(result.data).toBe(mockComment);

package/src/bitbucket-response-mapper.ts

@@ -113,10 +113,10 @@ export function shapePullRequestCommentAck(comment: any): Record<string, any> {
             path: comment.anchor.path,
             ...(comment.anchor.line !== undefined ? { line: comment.anchor.line } : {}),
             ...(typeof comment.anchor.lineType === 'string' ? { lineType: comment.anchor.lineType } : {}),
-            ...(comment.anchor.multilineAnchor
+            ...(comment.anchor.multilineMarker
               ? {
-                  startLine: comment.anchor.multilineStartLine,
-                  startLineType: comment.anchor.multilineStartLineType,
+                  startLine: comment.anchor.multilineMarker.startLine,
+                  startLineType: comment.anchor.multilineMarker.startLineType,
                 }
               : {}),
           },

package/src/bitbucket-service.ts

@@ -23,6 +23,84 @@ function resolveToken(token: string | (() => string | undefined), missingTokenMe
   };
 }
 
+type DiffLineType = 'ADDED' | 'REMOVED' | 'CONTEXT';
+
+/**
+ * Build a Bitbucket DC inline comment anchor.
+ *
+ * For a multiline range, Bitbucket DC (>= 9.3.0) requires `multilineMarker` + `multilineSpan`.
+ * The legacy `multilineStartLine`/`multilineStartLineType`/`multilineAnchor`/`multilineDestinationRange`
+ * fields are silently ignored by the server, which then stores a single-line anchor — so a multiline
+ * `​```suggestion` only replaces its first line on Apply. Field names verified against BB DC 9.3.2.
+ */
+function buildCommentAnchor(params: {
+  filePath: string;
+  line?: number;
+  lineType?: DiffLineType;
+  startLine?: number;
+  startLineType?: DiffLineType;
+}): Record<string, any> {
+  const { filePath, line, lineType } = params;
+  const anchor: Record<string, any> = { path: filePath, diffType: 'EFFECTIVE' };
+  if (line === undefined || !lineType) {
+    return anchor;
+  }
+
+  if (params.startLine === undefined) {
+    anchor.line = line;
+    anchor.lineType = lineType;
+    anchor.fileType = lineType === 'REMOVED' ? 'FROM' : 'TO';
+    return anchor;
+  }
+
+  // Normalize so the marker sits on the lower line and `line` on the upper line.
+  let startLine = params.startLine;
+  let startLineType: DiffLineType = params.startLineType ?? lineType;
+  let endLine = line;
+  let endLineType: DiffLineType = lineType;
+  if (startLine > endLine) {
+    [startLine, endLine] = [endLine, startLine];
+    [startLineType, endLineType] = [endLineType, startLineType];
+  }
+
+  const fileType = endLineType === 'REMOVED' ? 'FROM' : 'TO';
+  anchor.line = endLine;
+  anchor.lineType = endLineType;
+  anchor.fileType = fileType;
+  anchor.multilineMarker = { startLine, startLineType };
+  anchor.multilineSpan =
+    fileType === 'FROM'
+      ? { srcSpanStart: startLine, srcSpanEnd: endLine }
+      : { dstSpanStart: startLine, dstSpanEnd: endLine };
+  return anchor;
+}
+
+const SUGGESTION_BLOCK_RE = /```suggestion\b[^\n]*\n([\s\S]*?)```/;
+
+/**
+ * Warn when a multi-line `​```suggestion` block is anchored to a single line: Bitbucket only replaces
+ * the anchored line on Apply, leaving the rest (duplicated code). Returns undefined when there is no
+ * concern. Heuristic — a 1-line anchor with a multi-line suggestion is the common failure shape.
+ */
+function multilineSuggestionWarning(text: string, startLine?: number): string | undefined {
+  if (startLine !== undefined) {
+    return undefined;
+  }
+  const match = SUGGESTION_BLOCK_RE.exec(text);
+  if (!match) {
+    return undefined;
+  }
+  const suggestionLineCount = match[1].replace(/\n$/, '').split('\n').length;
+  if (suggestionLineCount <= 1) {
+    return undefined;
+  }
+  return (
+    'The comment contains a multi-line ```suggestion block but is anchored to a single line. ' +
+    'On Apply, Bitbucket replaces only that one line and leaves the rest. To replace multiple lines, ' +
+    'set startLine (first replaced line) and line (last replaced line) to span the whole range.'
+  );
+}
+
 export class BitbucketService {
   private readonly getPageSize: () => number;
 
@@ -301,13 +379,14 @@ export class BitbucketService {
    * @param text The comment text
    * @param parentId Optional parent comment ID for replies
    * @param filePath Optional file path for file-specific comments
-   * @param line Optional end line number for line/multiline comments
-   * @param lineType Optional line type ('ADDED', 'REMOVED', 'CONTEXT') for the end line
    * @param startLine Optional start line for multiline comments; when provided together with line, creates a range comment
    * @param startLineType Optional line type for the start line; defaults to lineType if omitted
+   * @param line Optional end line number for line/multiline comments
+   * @param lineType Optional line type ('ADDED', 'REMOVED', 'CONTEXT') for the end line
    * @param pending Optional flag to create a pending (draft) comment, not visible to others until a review is submitted.
    *   Only works when filePath is provided (file-level or inline comments).
    *   Top-level PR comments (no filePath) are always posted live regardless of this flag.
+   * @param severity Optional severity for the comment. 'BLOCKER' posts the comment as a task that must be resolved before the PR can be merged. Defaults to 'NORMAL' (regular comment) when omitted.
    * @returns Promise with created comment data
    */
   async postPullRequestComment(
@@ -322,6 +401,7 @@ export class BitbucketService {
     line?: number,
     lineType?: 'ADDED' | 'REMOVED' | 'CONTEXT',
     pending?: boolean,
+    severity?: 'NORMAL' | 'BLOCKER',
     output: BitbucketMutationOutputMode = 'ack'
   ) {
     projectKey = projectKey.toUpperCase();
@@ -330,6 +410,10 @@ export class BitbucketService {
       text
     };
 
+    if (severity) {
+      comment.severity = severity;
+    }
+
     // Mark comment as pending (draft) — not visible to others until review is submitted
     // Note: Bitbucket DC uses state:'PENDING' not pending:true
     if (pending) {
@@ -343,27 +427,11 @@ export class BitbucketService {
 
     // Add anchor for file/line comments
     if (filePath) {
-      comment.anchor = {
-        path: filePath,
-        diffType: 'EFFECTIVE'
-      };
-
-      // Add line-specific anchor properties
-      if (line !== undefined && lineType) {
-        comment.anchor.line = line;
-        comment.anchor.lineType = lineType;
-        comment.anchor.fileType = 'TO'; // Default to destination file
-
-        if (startLine !== undefined) {
-          const resolvedStartLineType = startLineType ?? lineType;
-          comment.anchor.multilineAnchor = true;
-          comment.anchor.multilineStartLine = startLine;
-          comment.anchor.multilineStartLineType = resolvedStartLineType;
-          comment.anchor.multilineDestinationRange = { minimum: startLine, maximum: line };
-        }
-      }
+      comment.anchor = buildCommentAnchor({ filePath, line, lineType, startLine, startLineType });
     }
 
+    const suggestionWarning = filePath ? multilineSuggestionWarning(text, startLine) : undefined;
+
     const result = await handleApiOperation(
       () => PullRequestsService.createComment2(
         projectKey,
@@ -374,6 +442,76 @@ export class BitbucketService {
       'Error posting pull request comment'
     );
 
+    if (result.success && result.data && output !== 'full') {
+      return {
+        ...result,
+        data: {
+          ...shapePullRequestCommentAck(result.data),
+          ...(suggestionWarning ? { warning: suggestionWarning } : {}),
+        },
+      };
+    }
+
+    if (result.success && suggestionWarning) {
+      return { ...result, warning: suggestionWarning };
+    }
+
+    return result;
+  }
+
+  /**
+   * Update an existing pull request comment. Use this to edit text, change severity, or change state.
+   * On a BLOCKER (task) comment, setting state to 'RESOLVED' ticks the task. Note: this is NOT the same
+   * as the thread-level "Resolve" button on regular comment threads — that operates on CommentThread.resolved
+   * and is a separate concept not exposed by this endpoint.
+   * @param projectKey The project key
+   * @param repositorySlug The repository slug
+   * @param pullRequestId The pull request ID
+   * @param commentId The comment ID to update
+   * @param version The current version of the comment (required for optimistic locking)
+   * @param text Optional new comment text
+   * @param state Optional new state. On a BLOCKER comment, 'RESOLVED' ticks the task and 'OPEN' un-ticks it.
+   * @param severity Optional new severity. 'BLOCKER' converts a comment into a task, 'NORMAL' converts a task back to a regular comment.
+   * @returns Promise with updated comment data
+   */
+  async updatePullRequestComment(
+    projectKey: string,
+    repositorySlug: string,
+    pullRequestId: string,
+    commentId: string,
+    version: number,
+    text?: string,
+    state?: 'OPEN' | 'RESOLVED',
+    severity?: 'NORMAL' | 'BLOCKER',
+    output: BitbucketMutationOutputMode = 'ack'
+  ) {
+    projectKey = projectKey.toUpperCase();
+    repositorySlug = repositorySlug.toLowerCase();
+    const comment: any = { version };
+
+    if (text !== undefined) {
+      comment.text = text;
+    }
+
+    if (state) {
+      comment.state = state;
+    }
+
+    if (severity) {
+      comment.severity = severity;
+    }
+
+    const result = await handleApiOperation(
+      () => PullRequestsService.updateComment2(
+        projectKey,
+        commentId,
+        pullRequestId,
+        repositorySlug,
+        comment
+      ),
+      'Error updating pull request comment'
+    );
+
     if (result.success && result.data && output !== 'full') {
       return {
         ...result,
@@ -842,11 +980,23 @@ export const bitbucketToolSchemas = {
     text: z.string().describe("The comment text"),
     parentId: z.number().optional().describe("Parent comment ID for replies"),
     filePath: z.string().optional().describe("File path for file-specific comments"),
-    startLine: z.number().optional().describe("Start line of a multiline comment range. When provided together with 'line' (end line), creates a multiline comment spanning from startLine to line."),
-    startLineType: z.enum(['ADDED', 'REMOVED', 'CONTEXT']).optional().describe("Line type for the start line of a multiline comment. Defaults to the same value as lineType if omitted."),
-    line: z.number().optional().describe("Line number for single-line comments, or end line for multiline comments"),
-    lineType: z.enum(['ADDED', 'REMOVED', 'CONTEXT']).optional().describe("Line type for the end line (or the only line for single-line comments)"),
+    startLine: z.number().optional().describe("First line of a multiline range. Provide together with 'line' (the last line) to span multiple lines. REQUIRED for a multi-line ```suggestion: the anchored range (startLine..line) is exactly what 'Apply suggestion' replaces — omit it and only the single 'line' is replaced, leaving the rest. Requires Bitbucket DC >= 9.3.0 for multiline suggestions."),
+    startLineType: z.enum(['ADDED', 'REMOVED', 'CONTEXT']).optional().describe("Line type for the start line of a multiline range. Defaults to the same value as lineType if omitted."),
+    line: z.number().optional().describe("Single-line comments: the line. Multiline: the LAST line of the range (use startLine for the first). For a ```suggestion this is the last replaced line."),
+    lineType: z.enum(['ADDED', 'REMOVED', 'CONTEXT']).optional().describe("Line type for 'line' (the end line, or the only line for single-line comments). Use 'ADDED'/'CONTEXT' for the new/target file, 'REMOVED' for the original/source file."),
     pending: z.boolean().optional().describe("If true, creates a pending (draft) comment not visible to others until the review is submitted via bitbucket_submitPullRequestReview. Only works when filePath is provided — top-level PR comments (no filePath) are always posted live."),
+    severity: z.enum(['NORMAL', 'BLOCKER']).optional().describe("Comment severity. Use 'BLOCKER' to post the comment as a task that must be resolved before the PR can be merged. Defaults to 'NORMAL' (regular comment)."),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
+  },
+  updatePullRequestComment: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    pullRequestId: z.string().describe("The pull request ID"),
+    commentId: z.string().describe("The ID of the comment to update"),
+    version: z.number().describe("The current version of the comment, required for optimistic locking. Get it from bitbucket_getPR_CommentsAndAction or from the response of the original post/update."),
+    text: z.string().optional().describe("New comment text. Omit to leave unchanged."),
+    state: z.enum(['OPEN', 'RESOLVED']).optional().describe("New state. On a BLOCKER (task) comment, 'RESOLVED' ticks the task and 'OPEN' un-ticks it. This is NOT the thread-level 'Resolve' button on regular comment threads — that is a separate concept (CommentThread.resolved) and is not exposed by this endpoint."),
+    severity: z.enum(['NORMAL', 'BLOCKER']).optional().describe("New severity. Use 'BLOCKER' to convert a comment into a task, 'NORMAL' to convert it back."),
     output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
   getUser: {

package/src/index.ts

@@ -129,10 +129,20 @@ server.tool(
 
 server.tool(
   "bitbucket_postPullRequestComment",
-  "Post a comment to a Bitbucket pull request. Use pending: true to create a draft comment that is only visible to you until you call bitbucket_submitPullRequestReview. NOTE: pending only works when filePath is provided (file-level or inline comments). True top-level PR comments (no filePath) are always posted live and cannot be drafted.",
+  "Post a comment to a Bitbucket pull request. Use pending: true to create a draft comment that is only visible to you until you call bitbucket_submitPullRequestReview. NOTE: pending only works when filePath is provided (file-level or inline comments). True top-level PR comments (no filePath) are always posted live and cannot be drafted. Use severity: 'BLOCKER' to post the comment as a task — tasks must be resolved before the PR can be merged.",
   bitbucketToolSchemas.postPullRequestComment,
-  async ({ projectKey, repositorySlug, pullRequestId, text, parentId, filePath, startLine, startLineType, line, lineType, pending, output }) => {
-    const result = await bitbucketService.postPullRequestComment(projectKey, repositorySlug, pullRequestId, text, parentId, filePath, startLine, startLineType, line, lineType, pending, output);
+  async ({ projectKey, repositorySlug, pullRequestId, text, parentId, filePath, startLine, startLineType, line, lineType, pending, severity, output }) => {
+    const result = await bitbucketService.postPullRequestComment(projectKey, repositorySlug, pullRequestId, text, parentId, filePath, startLine, startLineType, line, lineType, pending, severity, output);
+    return formatToolResponse(result);
+  }
+);
+
+server.tool(
+  "bitbucket_updatePullRequestComment",
+  "Update an existing pull request comment. Use to edit text, change severity, or change state. On a BLOCKER (task) comment, state: 'RESOLVED' ticks the task. NOTE: this is the task-tick, not the thread-level 'Resolve' button on regular comment threads — that is a separate concept (CommentThread.resolved) and is not exposed by this endpoint. Requires the current 'version' from optimistic locking; fetch it via bitbucket_getPR_CommentsAndAction or use the version returned when the comment was created.",
+  bitbucketToolSchemas.updatePullRequestComment,
+  async ({ projectKey, repositorySlug, pullRequestId, commentId, version, text, state, severity, output }) => {
+    const result = await bitbucketService.updatePullRequestComment(projectKey, repositorySlug, pullRequestId, commentId, version, text, state, severity, output);
     return formatToolResponse(result);
   }
 );