Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/pull-request-handlers.ts:1121-1240 (handler)

  Main handler function that fetches and formats commits for a specific pull request, supporting both Bitbucket Server and Cloud APIs, pagination, and optional build status.

  async handleListPrCommits(args: any) {
    if (!isListPrCommitsArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for list_pr_commits'
      );
    }
  
    const { workspace, repository, pull_request_id, limit = 25, start = 0, include_build_status = false } = args;
  
    try {
      // First get the PR details to include in response
      const prPath = this.apiClient.getIsServer()
        ? `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}`
        : `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}`;
      
      let prTitle = '';
      try {
        const pr = await this.apiClient.makeRequest<any>('get', prPath);
        prTitle = pr.title;
      } catch (e) {
        // Ignore error, PR title is optional
      }
  
      let apiPath: string;
      let params: any = {};
      let commits: FormattedCommit[] = [];
      let totalCount = 0;
      let nextPageStart: number | null = null;
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API
        apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}/commits`;
        params = {
          limit,
          start,
          withCounts: true
        };
  
        const response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params });
  
        // Format commits
        commits = (response.values || []).map((commit: BitbucketServerCommit) => formatServerCommit(commit));
  
        totalCount = response.size || commits.length;
        if (!response.isLastPage && response.nextPageStart !== undefined) {
          nextPageStart = response.nextPageStart;
        }
      } else {
        // Bitbucket Cloud API
        apiPath = `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}/commits`;
        params = {
          pagelen: limit,
          page: Math.floor(start / limit) + 1
        };
  
        const response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params });
  
        // Format commits
        commits = (response.values || []).map((commit: BitbucketCloudCommit) => formatCloudCommit(commit));
  
        totalCount = response.size || commits.length;
        if (response.next) {
          nextPageStart = start + limit;
        }
      }
  
      // Fetch build status if requested (Server only)
      if (include_build_status && this.apiClient.getIsServer() && commits.length > 0) {
        try {
          const commitIds = commits.map(c => c.hash);
          const buildSummaries = await this.apiClient.getBuildSummaries(
            workspace,
            repository,
            commitIds
          );
  
          // Enhance commits with build status
          commits = commits.map(commit => {
            const buildData = buildSummaries[commit.hash];
            if (buildData) {
              return {
                ...commit,
                build_status: {
                  successful: buildData.successful || 0,
                  failed: buildData.failed || 0,
                  in_progress: buildData.inProgress || 0,
                  unknown: buildData.unknown || 0
                }
              };
            }
            return commit;
          });
        } catch (error) {
          console.error('Failed to fetch build status for PR commits:', error);
          // Graceful degradation - continue without build status
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              pull_request_id,
              pull_request_title: prTitle,
              commits,
              total_count: totalCount,
              start,
              limit,
              has_more: nextPageStart !== null,
              next_start: nextPageStart
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `listing commits for pull request ${pull_request_id} in ${workspace}/${repository}`);
    }
  }

• src/tools/definitions.ts:584-617 (schema)

  Tool schema definition including input schema with properties for workspace, repository, pull_request_id, pagination, and build status option.

  {
    name: 'list_pr_commits',
    description: 'List all commits that are part of a pull request',
    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',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of commits to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
        include_build_status: {
          type: 'boolean',
          description: 'Include CI/CD build status for each commit (Bitbucket Server only, default: false)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },

• src/index.ts:108-109 (registration)

  Tool registration in the main MCP server switch statement, dispatching to PullRequestHandlers.handleListPrCommits.

  case 'list_pr_commits':
    return this.pullRequestHandlers.handleListPrCommits(request.params.arguments);

• src/types/guards.ts:294-312 (schema)

  Type guard function for validating input arguments to the list_pr_commits tool.

  export const isListPrCommitsArgs = (
    args: any
  ): args is {
    workspace: string;
    repository: string;
    pull_request_id: number;
    limit?: number;
    start?: number;
    include_build_status?: boolean;
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.repository === 'string' &&
    typeof args.pull_request_id === 'number' &&
    (args.limit === undefined || typeof args.limit === 'number') &&
    (args.start === undefined || typeof args.start === 'number') &&
    (args.include_build_status === undefined || typeof args.include_build_status === 'boolean');