Bitbucket Cloud MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:1007-1010 (handler)

  Handler logic in ToolHandler.handleTool method: parses arguments using the schema and delegates to CommitsAPI.list

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

• src/tools/index.ts:628-644 (registration)

  Tool registration in toolDefinitions array, including name, description, and input schema definition

  {
    name: 'list_commits',
    description: 'List commits in a repository with optional filtering by branch.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        workspace: { type: 'string', description: 'The workspace slug' },
        repo_slug: { type: 'string', description: 'The repository slug' },
        branch: { type: 'string', description: 'Branch name to filter commits' },
        include: { type: 'string', description: 'Commit to include' },
        exclude: { type: 'string', description: 'Commit to exclude' },
        page: { type: 'number', description: 'Page number' },
        pagelen: { type: 'number', description: 'Results per page' },
      },
      required: ['workspace', 'repo_slug'],
    },
  },

• src/tools/index.ts:176-184 (schema)

  Zod schema definition for list_commits tool input validation

  list_commits: z.object({
    workspace: z.string().describe('The workspace slug'),
    repo_slug: z.string().describe('The repository slug'),
    branch: z.string().optional().describe('Branch name to filter commits'),
    include: z.string().optional().describe('Commit to include'),
    exclude: z.string().optional().describe('Commit to exclude'),
    page: z.number().optional().describe('Page number'),
    pagelen: z.number().optional().describe('Results per page'),
  }),

• src/api/commits.ts:10-33 (helper)

  Core implementation in CommitsAPI.list: constructs query parameters and makes API call to list commits

  async list(params: ListCommitsParams): Promise<PaginatedResponse<BitbucketCommit>> {
    const { workspace, repo_slug, branch, include, exclude, ...queryParams } = params;
  
    // Build query params
    const allParams: Record<string, string | number | undefined> = {
      ...queryParams,
    };
  
    // For branch filtering, use the include parameter
    if (branch) {
      allParams.include = branch;
    } else if (include) {
      allParams.include = include;
    }
  
    if (exclude) {
      allParams.exclude = exclude;
    }
  
    return this.client.get<PaginatedResponse<BitbucketCommit>>(
      `/repositories/${workspace}/${repo_slug}/commits`,
      allParams
    );
  }

• src/types/index.ts:320-328 (schema)

  TypeScript interface defining the parameters for listing commits

  export interface ListCommitsParams {
    workspace: string;
    repo_slug: string;
    branch?: string;
    include?: string;
    exclude?: string;
    page?: number;
    pagelen?: number;
  }