Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/review-handlers.ts:212-264 (handler)

  The main handler function that implements the request_changes tool. It validates arguments using isRequestChangesArgs, makes API calls to Bitbucket Cloud or Server to set 'needs work' or 'request-changes' status on the pull request, optionally adds a comment, and returns a success message.

  async handleRequestChanges(args: any) {
    if (!isRequestChangesArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for request_changes'
      );
    }
  
    const { workspace, repository, pull_request_id, comment } = args;
  
    try {
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API - use needs-work status
        const username = this.username.replace('@', '_');
        const apiPath = `/rest/api/latest/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}/participants/${username}`;
        await this.apiClient.makeRequest<any>('put', apiPath, { status: 'NEEDS_WORK' });
        
        // Add comment if provided
        if (comment) {
          const commentPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests/${pull_request_id}/comments`;
          await this.apiClient.makeRequest<any>('post', commentPath, { text: comment });
        }
      } else {
        // Bitbucket Cloud API - use request-changes status
        const apiPath = `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}/request-changes`;
        await this.apiClient.makeRequest<any>('post', apiPath);
        
        // Add comment if provided
        if (comment) {
          const commentPath = `/repositories/${workspace}/${repository}/pullrequests/${pull_request_id}/comments`;
          await this.apiClient.makeRequest<any>('post', commentPath, {
            content: { raw: comment }
          });
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              message: 'Changes requested on pull request',
              pull_request_id,
              requested_by: this.username,
              comment: comment || 'No comment provided'
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `requesting changes on pull request ${pull_request_id} in ${workspace}/${repository}`);
    }
  }

• src/tools/definitions.ts:392-417 (schema)

  The tool definition including name, description, and input schema for validation in the MCP server.

  {
    name: 'request_changes',
    description: 'Request changes on 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',
        },
        comment: {
          type: 'string',
          description: 'Comment explaining requested changes (optional)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },

• src/index.ts:128-129 (registration)

  Registration of the request_changes tool in the main server switch statement, routing calls to the ReviewHandlers.handleRequestChanges method.

  case 'request_changes':
    return this.reviewHandlers.handleRequestChanges(request.params.arguments);

• src/types/guards.ts:199-213 (helper)

  Type guard function used in the handler to validate input arguments match the expected schema for request_changes.

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