Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/pull-request-handlers.ts:435-575 (handler)

  Main execution logic for the add_comment tool: argument validation, line resolution from code snippets, suggestion formatting, API request construction for Bitbucket Server/Cloud, and posting the comment with response formatting.

  async handleAddComment(args: any) {
    if (!isAddCommentArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for add_comment'
      );
    }
  
    let { 
      workspace, 
      repository, 
      pull_request_id, 
      comment_text, 
      parent_comment_id, 
      file_path, 
      line_number, 
      line_type,
      suggestion,
      suggestion_end_line,
      code_snippet,
      search_context,
      match_strategy = 'strict'
    } = args;
  
    let sequentialPosition: number | undefined;
    if (code_snippet && !line_number && file_path) {
      try {
        const resolved = await this.resolveLineFromCode(
          workspace,
          repository,
          pull_request_id,
          file_path,
          code_snippet,
          search_context,
          match_strategy
        );
        
        line_number = resolved.line_number;
        line_type = resolved.line_type;
        sequentialPosition = resolved.sequential_position;
      } catch (error) {
        throw error;
      }
    }
  
    if (suggestion && (!file_path || !line_number)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Suggestions require file_path and line_number to be specified'
      );
    }
  
    const isInlineComment = file_path !== undefined && line_number !== undefined;
  
    let finalCommentText = comment_text;
    if (suggestion) {
      finalCommentText = formatSuggestionComment(
        comment_text,
        suggestion,
        line_number,
        suggestion_end_line || line_number
      );
    }
  
    try {
      let apiPath: string;
      let requestBody: any;
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API
        apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}/comments`;
        requestBody = {
          text: finalCommentText
        };
        
        if (parent_comment_id !== undefined) {
          requestBody.parent = { id: parent_comment_id };
        }
        
        if (isInlineComment) {
          requestBody.anchor = {
            line: line_number,
            lineType: line_type || 'CONTEXT', 
            fileType: line_type === 'REMOVED' ? 'FROM' : 'TO',
            path: file_path,
            diffType: 'EFFECTIVE'
          };
          
        }
      } else {
        // Bitbucket Cloud API
        apiPath = `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}/comments`;
        requestBody = {
          content: {
            raw: finalCommentText
          }
        };
        
        if (parent_comment_id !== undefined) {
          requestBody.parent = { id: parent_comment_id };
        }
        
        if (isInlineComment) {
          requestBody.inline = {
            to: line_number,
            path: file_path
          };
        }
      }
  
      const comment = await this.apiClient.makeRequest<any>('post', apiPath, requestBody);
  
      const responseMessage = suggestion 
        ? 'Comment with code suggestion added successfully'
        : (isInlineComment ? 'Inline comment added successfully' : 'Comment added successfully');
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              message: responseMessage,
              comment: {
                id: comment.id,
                text: this.apiClient.getIsServer() ? comment.text : comment.content.raw,
                author: this.apiClient.getIsServer() ? comment.author.displayName : comment.user.display_name,
                created_on: this.apiClient.getIsServer() ? new Date(comment.createdDate).toLocaleString() : comment.created_on,
                file_path: isInlineComment ? file_path : undefined,
                line_number: isInlineComment ? line_number : undefined,
                line_type: isInlineComment ? (line_type || 'CONTEXT') : undefined,
                has_suggestion: !!suggestion,
                suggestion_lines: suggestion ? (suggestion_end_line ? `${line_number}-${suggestion_end_line}` : `${line_number}`) : undefined
              }
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `adding ${isInlineComment ? 'inline ' : ''}comment to pull request ${pull_request_id} in ${workspace}/${repository}`);
    }
  }

• src/tools/definitions.ts:142-216 (schema)

  JSON Schema definition for the add_comment tool input parameters, including descriptions and validation rules for all fields like workspace, comment_text, file_path, line_number, suggestion, code_snippet, etc.

    name: 'add_comment',
    description: 'Add a comment to a pull request. Supports: 1) General PR comments, 2) Replies to existing comments, 3) Inline comments on specific code lines (using line_number OR code_snippet), 4) Code suggestions for single or multi-line replacements. For inline comments, you can either provide exact line_number or use code_snippet to auto-detect the line.',
    inputSchema: {
      type: 'object',
      properties: {
        workspace: {
          type: 'string',
          description: 'Bitbucket workspace/project key (e.g., "PROJ")',
        },
        repository: {
          type: 'string',
          description: 'Repository slug (e.g., "my-repo")',
        },
        pull_request_id: {
          type: 'number',
          description: 'Pull request ID',
        },
        comment_text: {
          type: 'string',
          description: 'The main comment text. For suggestions, this is the explanation before the code suggestion.',
        },
        parent_comment_id: {
          type: 'number',
          description: 'ID of comment to reply to. Use this to create threaded conversations (optional)',
        },
        file_path: {
          type: 'string',
          description: 'File path for inline comment. Required for inline comments. Example: "src/components/Button.js" (optional)',
        },
        line_number: {
          type: 'number',
          description: 'Exact line number in the file. Use this OR code_snippet, not both. Required with file_path unless using code_snippet (optional)',
        },
        line_type: {
          type: 'string',
          description: 'Type of line: ADDED (green/new lines), REMOVED (red/deleted lines), or CONTEXT (unchanged lines). Default: CONTEXT',
          enum: ['ADDED', 'REMOVED', 'CONTEXT'],
        },
        suggestion: {
          type: 'string',
          description: 'Replacement code for a suggestion. Creates a suggestion block that can be applied in Bitbucket UI. Requires file_path and line_number. For multi-line, include newlines in the string (optional)',
        },
        suggestion_end_line: {
          type: 'number',
          description: 'For multi-line suggestions: the last line number to replace. If not provided, only replaces the single line at line_number (optional)',
        },
        code_snippet: {
          type: 'string',
          description: 'Exact code text from the diff to find and comment on. Use this instead of line_number for auto-detection. Must match exactly including whitespace (optional)',
        },
        search_context: {
          type: 'object',
          properties: {
            before: {
              type: 'array',
              items: { type: 'string' },
              description: 'Array of code lines that appear BEFORE the target line. Helps disambiguate when code_snippet appears multiple times',
            },
            after: {
              type: 'array',
              items: { type: 'string' },
              description: 'Array of code lines that appear AFTER the target line. Helps disambiguate when code_snippet appears multiple times',
            },
          },
          description: 'Additional context lines to help locate the exact position when using code_snippet. Useful when the same code appears multiple times (optional)',
        },
        match_strategy: {
          type: 'string',
          enum: ['strict', 'best'],
          description: 'How to handle multiple matches when using code_snippet. "strict": fail with detailed error showing all matches. "best": automatically pick the highest confidence match. Default: "strict"',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id', 'comment_text'],
    },
  },

• src/index.ts:104-105 (registration)

  Tool registration and dispatch: routes 'add_comment' calls to the PullRequestHandlers.handleAddComment method.

  case 'add_comment':
    return this.pullRequestHandlers.handleAddComment(request.params.arguments);

• src/types/guards.ts:74-112 (schema)

  Type guard function isAddCommentArgs used in the handler for runtime input validation matching the tool schema.

  export const isAddCommentArgs = (
    args: any
  ): args is {
    workspace: string;
    repository: string;
    pull_request_id: number;
    comment_text: string;
    parent_comment_id?: number;
    file_path?: string;
    line_number?: number;
    line_type?: 'ADDED' | 'REMOVED' | 'CONTEXT';
    suggestion?: string;
    suggestion_end_line?: number;
    code_snippet?: string;
    search_context?: {
      before?: string[];
      after?: string[];
    };
    match_strategy?: 'strict' | 'best';
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.repository === 'string' &&
    typeof args.pull_request_id === 'number' &&
    typeof args.comment_text === 'string' &&
    (args.parent_comment_id === undefined || typeof args.parent_comment_id === 'number') &&
    (args.file_path === undefined || typeof args.file_path === 'string') &&
    (args.line_number === undefined || typeof args.line_number === 'number') &&
    (args.line_type === undefined || ['ADDED', 'REMOVED', 'CONTEXT'].includes(args.line_type)) &&
    (args.suggestion === undefined || typeof args.suggestion === 'string') &&
    (args.suggestion_end_line === undefined || typeof args.suggestion_end_line === 'number') &&
    (args.code_snippet === undefined || typeof args.code_snippet === 'string') &&
    (args.search_context === undefined || (
      typeof args.search_context === 'object' &&
      (args.search_context.before === undefined || Array.isArray(args.search_context.before)) &&
      (args.search_context.after === undefined || Array.isArray(args.search_context.after))
    )) &&
    (args.match_strategy === undefined || ['strict', 'best'].includes(args.match_strategy));