Bitbucket Cloud MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:988-991 (handler)

  Tool handler case for 'list_branches' that parses arguments using Zod schema and delegates to BranchesAPI.list method.

  case 'list_branches': {
    const params = toolSchemas.list_branches.parse(args);
    return this.branches.list(params);
  }

• src/api/branches.ts:15-21 (helper)

  BranchesAPI.list method that performs the actual Bitbucket API GET request to list branches.

  async list(params: ListBranchesParams): Promise<PaginatedResponse<BitbucketBranch>> {
    const { workspace, repo_slug, ...queryParams } = params;
    return this.client.get<PaginatedResponse<BitbucketBranch>>(
      `/repositories/${workspace}/${repo_slug}/refs/branches`,
      queryParams as Record<string, string | number | undefined>
    );
  }

• src/tools/index.ts:147-154 (schema)

  Zod input schema definition for the list_branches tool used for validation in the handler.

  list_branches: z.object({
    workspace: z.string().describe('The workspace slug'),
    repo_slug: z.string().describe('The repository slug'),
    q: z.string().optional().describe('Query string for filtering'),
    sort: z.string().optional().describe('Sort field'),
    page: z.number().optional().describe('Page number'),
    pagelen: z.number().optional().describe('Results per page'),
  }),

• src/tools/index.ts:570-585 (registration)

  MCP tool registration/definition for 'list_branches' including name, description, and input schema.

  {
    name: 'list_branches',
    description: 'List all branches in a repository.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        workspace: { type: 'string', description: 'The workspace slug' },
        repo_slug: { type: 'string', description: 'The repository slug' },
        q: { type: 'string', description: 'Query string for filtering' },
        sort: { type: 'string', description: 'Sort field' },
        page: { type: 'number', description: 'Page number' },
        pagelen: { type: 'number', description: 'Results per page' },
      },
      required: ['workspace', 'repo_slug'],
    },
  },

• src/types/index.ts:304-311 (schema)

  TypeScript interface defining the parameters for list_branches, used in BranchesAPI.

  export interface ListBranchesParams {
    workspace: string;
    repo_slug: string;
    q?: string;
    sort?: string;
    page?: number;
    pagelen?: number;
  }