Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/pull-request-handlers.ts:577-637 (handler)

  Core handler function that executes the merge_pull_request tool by calling the appropriate Bitbucket API endpoint for both Cloud and Server instances, handling parameters like merge strategy, close source branch, and custom commit message.

  async handleMergePullRequest(args: any) {
    if (!isMergePullRequestArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for merge_pull_request'
      );
    }
  
    const { workspace, repository, pull_request_id, merge_strategy, close_source_branch, commit_message } = args;
  
    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}/merge`;
        
        // Get current PR version
        const prPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}`;
        const currentPr = await this.apiClient.makeRequest<any>('get', prPath);
        
        requestBody.version = currentPr.version;
        if (commit_message) {
          requestBody.message = commit_message;
        }
      } else {
        // Bitbucket Cloud API
        apiPath = `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}/merge`;
        
        if (merge_strategy) {
          requestBody.merge_strategy = merge_strategy;
        }
        if (close_source_branch !== undefined) {
          requestBody.close_source_branch = close_source_branch;
        }
        if (commit_message) {
          requestBody.message = commit_message;
        }
      }
  
      const result = await this.apiClient.makeRequest<any>('post', apiPath, requestBody);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              message: 'Pull request merged successfully',
              merge_commit: this.apiClient.getIsServer() ? result.properties?.mergeCommit : result.merge_commit?.hash,
              pull_request_id
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `merging pull request ${pull_request_id} in ${workspace}/${repository}`);
    }
  }
  
  private async fetchPullRequestComments(

• src/index.ts:106-107 (registration)

  Tool registration in the main MCP server switch statement, routing calls to the PullRequestHandlers.

  case 'merge_pull_request':
    return this.pullRequestHandlers.handleMergePullRequest(request.params.arguments);

• src/tools/definitions.ts:217-251 (schema)

  MCP tool schema definition providing input validation schema, description, and parameters for the merge_pull_request tool.

  {
    name: 'merge_pull_request',
    description: 'Merge 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',
        },
        merge_strategy: {
          type: 'string',
          description: 'Merge strategy: merge-commit, squash, fast-forward (optional)',
          enum: ['merge-commit', 'squash', 'fast-forward'],
        },
        close_source_branch: {
          type: 'boolean',
          description: 'Whether to close source branch after merge (optional)',
        },
        commit_message: {
          type: 'string',
          description: 'Custom merge commit message (optional)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },

• src/types/guards.ts:114-132 (schema)

  Type guard function for validating merge_pull_request input arguments, used within the handler for runtime checks.

  export const isMergePullRequestArgs = (
    args: any
  ): args is {
    workspace: string;
    repository: string;
    pull_request_id: number;
    merge_strategy?: string;
    close_source_branch?: boolean;
    commit_message?: string;
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.repository === 'string' &&
    typeof args.pull_request_id === 'number' &&
    (args.merge_strategy === undefined || typeof args.merge_strategy === 'string') &&
    (args.close_source_branch === undefined || typeof args.close_source_branch === 'boolean') &&
    (args.commit_message === undefined || typeof args.commit_message === 'string');