Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/review-handlers.ts:16-127 (handler)

  Main handler function that fetches the pull request diff from Bitbucket API (Cloud or Server), optionally filters by file patterns or specific file using DiffParser, and returns formatted JSON response with metadata.

  async handleGetPullRequestDiff(args: any) {
    if (!isGetPullRequestDiffArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for get_pull_request_diff'
      );
    }
  
    const { 
      workspace, 
      repository, 
      pull_request_id, 
      context_lines = 3,
      include_patterns,
      exclude_patterns,
      file_path
    } = args;
  
    try {
      let apiPath: string;
      let config: any = {};
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API
        apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}/diff`;
        config.params = { contextLines: context_lines };
      } else {
        // Bitbucket Cloud API
        apiPath = `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}/diff`;
        config.params = { context: context_lines };
      }
  
      // For diff, we want the raw text response
      config.headers = { 'Accept': 'text/plain' };
      
      const rawDiff = await this.apiClient.makeRequest<string>('get', apiPath, undefined, config);
  
      // Check if filtering is needed
      const needsFiltering = file_path || include_patterns || exclude_patterns;
      
      if (!needsFiltering) {
        // Return raw diff without filtering
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                message: 'Pull request diff retrieved successfully',
                pull_request_id,
                diff: rawDiff
              }, null, 2),
            },
          ],
        };
      }
  
      // Apply filtering
      const diffParser = new DiffParser();
      const sections = diffParser.parseDiffIntoSections(rawDiff);
      
      const filterOptions = {
        includePatterns: include_patterns,
        excludePatterns: exclude_patterns,
        filePath: file_path
      };
      
      const filteredResult = diffParser.filterSections(sections, filterOptions);
      const filteredDiff = diffParser.reconstructDiff(filteredResult.sections);
  
      // Build response with filtering metadata
      const response: any = {
        message: 'Pull request diff retrieved successfully',
        pull_request_id,
        diff: filteredDiff
      };
  
      // Add filter metadata
      if (filteredResult.metadata.excludedFiles > 0 || file_path || include_patterns || exclude_patterns) {
        response.filter_metadata = {
          total_files: filteredResult.metadata.totalFiles,
          included_files: filteredResult.metadata.includedFiles,
          excluded_files: filteredResult.metadata.excludedFiles
        };
  
        if (filteredResult.metadata.excludedFileList.length > 0) {
          response.filter_metadata.excluded_file_list = filteredResult.metadata.excludedFileList;
        }
  
        response.filter_metadata.filters_applied = {};
        if (file_path) {
          response.filter_metadata.filters_applied.file_path = file_path;
        }
        if (include_patterns) {
          response.filter_metadata.filters_applied.include_patterns = include_patterns;
        }
        if (exclude_patterns) {
          response.filter_metadata.filters_applied.exclude_patterns = exclude_patterns;
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `getting diff for pull request ${pull_request_id} in ${workspace}/${repository}`);
    }
  }

• src/types/guards.ts:165-184 (schema)

  Type guard function used in the handler to validate input arguments for get_pull_request_diff tool.

  export const isGetPullRequestDiffArgs = (
    args: any
  ): args is {
    workspace: string;
    repository: string;
    pull_request_id: number;
    context_lines?: number;
    include_patterns?: string[];
    exclude_patterns?: string[];
    file_path?: string;
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.repository === 'string' &&
    typeof args.pull_request_id === 'number' &&
    (args.context_lines === undefined || typeof args.context_lines === 'number') &&
    (args.include_patterns === undefined || (Array.isArray(args.include_patterns) && args.include_patterns.every((p: any) => typeof p === 'string'))) &&
    (args.exclude_patterns === undefined || (Array.isArray(args.exclude_patterns) && args.exclude_patterns.every((p: any) => typeof p === 'string'))) &&
    (args.file_path === undefined || typeof args.file_path === 'string');

• src/tools/definitions.ts:308-347 (schema)

  Tool definition including name, description, and input schema used for MCP tool listing and validation.

  {
    name: 'get_pull_request_diff',
    description: 'Get the diff/changes for a pull request with optional filtering',
    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',
        },
        context_lines: {
          type: 'number',
          description: 'Number of context lines around changes (optional, default: 3)',
        },
        include_patterns: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of glob patterns to include (e.g., ["*.res", "src/**/*.js"]) (optional)',
        },
        exclude_patterns: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of glob patterns to exclude (e.g., ["*.lock", "*.svg"]) (optional)',
        },
        file_path: {
          type: 'string',
          description: 'Specific file path to get diff for (e.g., "src/index.ts") (optional)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },

• src/index.ts:122-123 (registration)

  Switch case in main server request handler that routes 'get_pull_request_diff' tool calls to the ReviewHandlers.handleGetPullRequestDiff method.

  case 'get_pull_request_diff':
    return this.reviewHandlers.handleGetPullRequestDiff(request.params.arguments);