Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/branch-handlers.ts:24-112 (handler)

  Core handler function that implements the list_branches tool: validates args, calls Bitbucket API (Server/Cloud), formats branches with pagination info, returns JSON text content.

  async handleListBranches(args: any) {
    if (!isListBranchesArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for list_branches'
      );
    }
  
    const { workspace, repository, filter, limit = 25, start = 0 } = args;
  
    try {
      let apiPath: string;
      let params: any = {};
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API - using latest version for better filtering support
        apiPath = `/rest/api/latest/projects/${workspace}/repos/${repository}/branches`;
        params = {
          limit,
          start,
          details: true,
          orderBy: 'MODIFICATION'
        };
        if (filter) {
          params.filterText = filter;
        }
      } else {
        // Bitbucket Cloud API
        apiPath = `/repositories/${workspace}/${repository}/refs/branches`;
        params = {
          pagelen: limit,
          page: Math.floor(start / limit) + 1,
        };
        if (filter) {
          params.q = `name ~ "${filter}"`;
        }
      }
  
      const response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params });
  
      // Format the response
      let branches: any[] = [];
      let totalCount = 0;
      let nextPageStart = null;
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server response
        branches = (response.values || []).map((branch: any) => ({
          name: branch.displayId,
          id: branch.id,
          latest_commit: branch.latestCommit,
          is_default: branch.isDefault || false
        }));
        totalCount = response.size || 0;
        if (!response.isLastPage && response.nextPageStart !== undefined) {
          nextPageStart = response.nextPageStart;
        }
      } else {
        // Bitbucket Cloud response
        branches = (response.values || []).map((branch: any) => ({
          name: branch.name,
          target: branch.target.hash,
          is_default: branch.name === 'main' || branch.name === 'master'
        }));
        totalCount = response.size || 0;
        if (response.next) {
          nextPageStart = start + limit;
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              branches,
              total_count: totalCount,
              start,
              limit,
              has_more: nextPageStart !== null,
              next_start: nextPageStart
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `listing branches in ${workspace}/${repository}`);
    }
  }

• src/tools/definitions.ts:253-281 (schema)

  Tool definition schema for list_branches including input parameters: workspace, repository, optional filter/limit/start.

    name: 'list_branches',
    description: 'List branches in a repository',
    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")',
        },
        filter: {
          type: 'string',
          description: 'Filter branches by name pattern (optional)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of branches to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
      },
      required: ['workspace', 'repository'],
    },
  },

• src/types/guards.ts:148-163 (schema)

  Type guard function isListBranchesArgs for runtime validation of tool input arguments.

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

• src/index.ts:112-113 (registration)

  Registration/dispatch in main MCP server: routes 'list_branches' calls to BranchHandlers.handleListBranches.

  case 'list_branches':
    return this.branchHandlers.handleListBranches(request.params.arguments);