list_branch_commits

Retrieve and filter commits from a specific branch in Bitbucket repositories, with options to control pagination, date ranges, authorship, merge commits, and message searches for detailed commit analysis.

Instructions

List commits in a branch with detailed information and filtering options

Input Schema

TableJSON Schema

Name	Required	Description
`author`	No	Filter by author email/username (optional)
`branch_name`	Yes	Branch name to get commits from
`include_merge_commits`	No	Include merge commits in results (default: true)
`limit`	No	Maximum number of commits to return (default: 25)
`repository`	Yes	Repository slug (e.g., "my-repo")
`search`	No	Search for text in commit messages (optional)
`since`	No	ISO date string - only show commits after this date (optional)
`start`	No	Start index for pagination (default: 0)
`until`	No	ISO date string - only show commits before this date (optional)
`workspace`	Yes	Bitbucket workspace/project key (e.g., "PROJ")

Implementation Reference

src/handlers/branch-handlers.ts:404-623 (handler)

The primary handler function executing the list_branch_commits tool. Fetches commits from a specified branch using Bitbucket APIs (Server/Cloud), applies filters (date, author, search, merges), supports pagination, optionally includes build status (Server), and returns formatted JSON response.

async handleListBranchCommits(args: any) {
  if (!isListBranchCommitsArgs(args)) {
    throw new McpError(
      ErrorCode.InvalidParams,
      'Invalid arguments for list_branch_commits'
    );
  }

  const {
    workspace,
    repository,
    branch_name,
    limit = 25,
    start = 0,
    since,
    until,
    author,
    include_merge_commits = true,
    search,
    include_build_status = false
  } = args;

  try {
    let apiPath: string;
    let params: any = {};
    let commits: FormattedCommit[] = [];
    let totalCount = 0;
    let nextPageStart: number | null = null;

    if (this.apiClient.getIsServer()) {
      // Bitbucket Server API
      apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/commits`;
      params = {
        until: `refs/heads/${branch_name}`,
        limit,
        start,
        withCounts: true
      };

      // Add filters
      if (since) {
        params.since = since;
      }
      if (!include_merge_commits) {
        params.merges = 'exclude';
      }

      const response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params });

      // Format commits
      commits = (response.values || []).map((commit: BitbucketServerCommit) => formatServerCommit(commit));
      
      // Apply client-side filters for Server API
      if (author) {
        // Filter by author email or name
        commits = commits.filter(c => 
          c.author.email === author || 
          c.author.name === author ||
          c.author.email.toLowerCase() === author.toLowerCase() ||
          c.author.name.toLowerCase() === author.toLowerCase()
        );
      }
      
      // Filter by date if 'until' is provided (Server API doesn't support 'until' param directly)
      if (until) {
        const untilDate = new Date(until).getTime();
        commits = commits.filter(c => new Date(c.date).getTime() <= untilDate);
      }

      // Filter by message search if provided
      if (search) {
        const searchLower = search.toLowerCase();
        commits = commits.filter(c => c.message.toLowerCase().includes(searchLower));
      }

      // If we applied client-side filters, update the total count
      if (author || until || search) {
        totalCount = commits.length;
        // Can't determine if there are more results when filtering client-side
        nextPageStart = null;
      } else {
        totalCount = response.size || commits.length;
        if (!response.isLastPage && response.nextPageStart !== undefined) {
          nextPageStart = response.nextPageStart;
        }
      }
    } else {
      // Bitbucket Cloud API
      apiPath = `/repositories/${workspace}/${repository}/commits/${encodeURIComponent(branch_name)}`;
      params = {
        pagelen: limit,
        page: Math.floor(start / limit) + 1
      };

      // Build query string for filters
      const queryParts: string[] = [];
      if (author) {
        queryParts.push(`author.raw ~ "${author}"`);
      }
      if (!include_merge_commits) {
        // Cloud API doesn't have direct merge exclusion, we'll filter client-side
      }
      if (queryParts.length > 0) {
        params.q = queryParts.join(' AND ');
      }

      const response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params });

      // Format commits
      let cloudCommits = (response.values || []).map((commit: BitbucketCloudCommit) => formatCloudCommit(commit));

      // Apply client-side filters
      if (!include_merge_commits) {
        cloudCommits = cloudCommits.filter((c: FormattedCommit) => !c.is_merge_commit);
      }
      if (since) {
        const sinceDate = new Date(since).getTime();
        cloudCommits = cloudCommits.filter((c: FormattedCommit) => new Date(c.date).getTime() >= sinceDate);
      }
      if (until) {
        const untilDate = new Date(until).getTime();
        cloudCommits = cloudCommits.filter((c: FormattedCommit) => new Date(c.date).getTime() <= untilDate);
      }
      if (search) {
        const searchLower = search.toLowerCase();
        cloudCommits = cloudCommits.filter((c: FormattedCommit) => c.message.toLowerCase().includes(searchLower));
      }

      commits = cloudCommits;
      totalCount = response.size || commits.length;
      if (response.next) {
        nextPageStart = start + limit;
      }
    }

    // Fetch build status if requested (Server only)
    if (include_build_status && this.apiClient.getIsServer() && commits.length > 0) {
      try {
        // Extract commit hashes (use full hash, not abbreviated)
        const commitIds = commits.map(c => c.hash);

        // Fetch build summaries for all commits
        const buildSummaries = await this.apiClient.getBuildSummaries(
          workspace,
          repository,
          commitIds
        );

        // Merge build status into commits
        commits = commits.map(commit => {
          const buildData = buildSummaries[commit.hash];
          if (buildData) {
            return {
              ...commit,
              build_status: {
                successful: buildData.successful || 0,
                failed: buildData.failed || 0,
                in_progress: buildData.inProgress || 0,
                unknown: buildData.unknown || 0
              }
            };
          }
          return commit;
        });
      } catch (error) {
        // Gracefully degrade - log error but don't fail the entire request
        console.error('Failed to fetch build status:', error);
      }
    }

    // Get branch head info
    let branchHead: string | null = null;
    try {
      if (this.apiClient.getIsServer()) {
        const branchesPath = `/rest/api/latest/projects/${workspace}/repos/${repository}/branches`;
        const branchesResponse = await this.apiClient.makeRequest<any>('get', branchesPath, undefined, {
          params: { filterText: branch_name, limit: 1 }
        });
        const branch = branchesResponse.values?.find((b: any) => b.displayId === branch_name);
        branchHead = branch?.latestCommit || null;
      } else {
        const branchPath = `/repositories/${workspace}/${repository}/refs/branches/${encodeURIComponent(branch_name)}`;
        const branch = await this.apiClient.makeRequest<any>('get', branchPath);
        branchHead = branch.target?.hash || null;
      }
    } catch (e) {
      // Ignore error, branch head is optional
    }

    // Build filters applied summary
    const filtersApplied: any = {};
    if (author) filtersApplied.author = author;
    if (since) filtersApplied.since = since;
    if (until) filtersApplied.until = until;
    if (include_merge_commits !== undefined) filtersApplied.include_merge_commits = include_merge_commits;
    if (search) filtersApplied.search = search;
    if (include_build_status) filtersApplied.include_build_status = include_build_status;

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            branch_name,
            branch_head: branchHead,
            commits,
            total_count: totalCount,
            start,
            limit,
            has_more: nextPageStart !== null,
            next_start: nextPageStart,
            filters_applied: filtersApplied
          }, null, 2),
        },
      ],
    };
  } catch (error) {
    return this.apiClient.handleApiError(error, `listing commits for branch '${branch_name}' in ${workspace}/${repository}`);
  }
}

src/tools/definitions.ts:531-582 (schema)

JSON schema definition for the list_branch_commits tool inputs, used for MCP tool listing and validation.

name: 'list_branch_commits',
description: 'List commits in a branch with detailed information and filtering options',
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")',
    },
    branch_name: {
      type: 'string',
      description: 'Branch name to get commits from',
    },
    limit: {
      type: 'number',
      description: 'Maximum number of commits to return (default: 25)',
    },
    start: {
      type: 'number',
      description: 'Start index for pagination (default: 0)',
    },
    since: {
      type: 'string',
      description: 'ISO date string - only show commits after this date (optional)',
    },
    until: {
      type: 'string',
      description: 'ISO date string - only show commits before this date (optional)',
    },
    author: {
      type: 'string',
      description: 'Filter by author email/username (optional)',
    },
    include_merge_commits: {
      type: 'boolean',
      description: 'Include merge commits in results (default: true)',
    },
    search: {
      type: 'string',
      description: 'Search for text in commit messages (optional)',
    },
    include_build_status: {
      type: 'boolean',
      description: 'Include CI/CD build status for each commit (Bitbucket Server only, default: false)',
    },
  },
  required: ['workspace', 'repository', 'branch_name'],
},

src/types/guards.ts:265-292 (schema)

Type guard function for validating arguments to list_branch_commits handler.

export const isListBranchCommitsArgs = (
  args: any
): args is {
  workspace: string;
  repository: string;
  branch_name: string;
  limit?: number;
  start?: number;
  since?: string;
  until?: string;
  author?: string;
  include_merge_commits?: boolean;
  search?: string;
  include_build_status?: boolean;
} =>
  typeof args === 'object' &&
  args !== null &&
  typeof args.workspace === 'string' &&
  typeof args.repository === 'string' &&
  typeof args.branch_name === 'string' &&
  (args.limit === undefined || typeof args.limit === 'number') &&
  (args.start === undefined || typeof args.start === 'number') &&
  (args.since === undefined || typeof args.since === 'string') &&
  (args.until === undefined || typeof args.until === 'string') &&
  (args.author === undefined || typeof args.author === 'string') &&
  (args.include_merge_commits === undefined || typeof args.include_merge_commits === 'boolean') &&
  (args.search === undefined || typeof args.search === 'string') &&
  (args.include_build_status === undefined || typeof args.include_build_status === 'boolean');

src/index.ts:118-119 (registration)
Registration of the tool handler in the main MCP server switch statement, dispatching calls to BranchHandlers.handleListBranchCommits.
```
case 'list_branch_commits':
  return this.branchHandlers.handleListBranchCommits(request.params.arguments);
```

src/tools/definitions.ts:1-718 (registration)

The tool is included in the exported toolDefinitions array used by the MCP server for listing available tools.

export const toolDefinitions = [
  {
    name: 'get_pull_request',
    description: 'Get details of a Bitbucket pull request including merge commit information',
    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',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    name: 'list_pull_requests',
    description: 'List pull requests for a repository with optional filters',
    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")',
        },
        state: {
          type: 'string',
          description: 'Filter by PR state: OPEN, MERGED, DECLINED, ALL (default: OPEN)',
          enum: ['OPEN', 'MERGED', 'DECLINED', 'ALL'],
        },
        author: {
          type: 'string',
          description: 'Filter by author username',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of PRs to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
      },
      required: ['workspace', 'repository'],
    },
  },
  {
    name: 'create_pull_request',
    description: 'Create a new 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")',
        },
        title: {
          type: 'string',
          description: 'Title of the pull request',
        },
        source_branch: {
          type: 'string',
          description: 'Source branch name',
        },
        destination_branch: {
          type: 'string',
          description: 'Destination branch name (e.g., "main", "master")',
        },
        description: {
          type: 'string',
          description: 'Description of the pull request (optional)',
        },
        reviewers: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of reviewer usernames/emails (optional)',
        },
        close_source_branch: {
          type: 'boolean',
          description: 'Whether to close source branch after merge (optional, default: false)',
        },
      },
      required: ['workspace', 'repository', 'title', 'source_branch', 'destination_branch'],
    },
  },
  {
    name: 'update_pull_request',
    description: 'Update an existing pull request. When updating without specifying reviewers, existing reviewers and their approval status will be preserved.',
    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',
        },
        title: {
          type: 'string',
          description: 'New title (optional)',
        },
        description: {
          type: 'string',
          description: 'New description (optional)',
        },
        destination_branch: {
          type: 'string',
          description: 'New destination branch (optional)',
        },
        reviewers: {
          type: 'array',
          items: { type: 'string' },
          description: 'New list of reviewer usernames/emails. If provided, replaces the reviewer list (preserving approval status for existing reviewers). If omitted, existing reviewers are preserved. (optional)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    name: 'add_comment',
    description: 'Add a comment to a pull request. Supports: 1) General PR comments, 2) Replies to existing comments, 3) Inline comments on specific code lines (using line_number OR code_snippet), 4) Code suggestions for single or multi-line replacements. For inline comments, you can either provide exact line_number or use code_snippet to auto-detect the line.',
    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_text: {
          type: 'string',
          description: 'The main comment text. For suggestions, this is the explanation before the code suggestion.',
        },
        parent_comment_id: {
          type: 'number',
          description: 'ID of comment to reply to. Use this to create threaded conversations (optional)',
        },
        file_path: {
          type: 'string',
          description: 'File path for inline comment. Required for inline comments. Example: "src/components/Button.js" (optional)',
        },
        line_number: {
          type: 'number',
          description: 'Exact line number in the file. Use this OR code_snippet, not both. Required with file_path unless using code_snippet (optional)',
        },
        line_type: {
          type: 'string',
          description: 'Type of line: ADDED (green/new lines), REMOVED (red/deleted lines), or CONTEXT (unchanged lines). Default: CONTEXT',
          enum: ['ADDED', 'REMOVED', 'CONTEXT'],
        },
        suggestion: {
          type: 'string',
          description: 'Replacement code for a suggestion. Creates a suggestion block that can be applied in Bitbucket UI. Requires file_path and line_number. For multi-line, include newlines in the string (optional)',
        },
        suggestion_end_line: {
          type: 'number',
          description: 'For multi-line suggestions: the last line number to replace. If not provided, only replaces the single line at line_number (optional)',
        },
        code_snippet: {
          type: 'string',
          description: 'Exact code text from the diff to find and comment on. Use this instead of line_number for auto-detection. Must match exactly including whitespace (optional)',
        },
        search_context: {
          type: 'object',
          properties: {
            before: {
              type: 'array',
              items: { type: 'string' },
              description: 'Array of code lines that appear BEFORE the target line. Helps disambiguate when code_snippet appears multiple times',
            },
            after: {
              type: 'array',
              items: { type: 'string' },
              description: 'Array of code lines that appear AFTER the target line. Helps disambiguate when code_snippet appears multiple times',
            },
          },
          description: 'Additional context lines to help locate the exact position when using code_snippet. Useful when the same code appears multiple times (optional)',
        },
        match_strategy: {
          type: 'string',
          enum: ['strict', 'best'],
          description: 'How to handle multiple matches when using code_snippet. "strict": fail with detailed error showing all matches. "best": automatically pick the highest confidence match. Default: "strict"',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id', 'comment_text'],
    },
  },
  {
    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'],
    },
  },
  {
    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'],
    },
  },
  {
    name: 'delete_branch',
    description: 'Delete a branch',
    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")',
        },
        branch_name: {
          type: 'string',
          description: 'Branch name to delete',
        },
        force: {
          type: 'boolean',
          description: 'Force delete even if branch is not merged (optional, default: false)',
        },
      },
      required: ['workspace', 'repository', 'branch_name'],
    },
  },
  {
    name: 'get_pull_request_diff',
    description: 'Get the diff/changes for a pull request with optional filtering',
    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',
        },
        context_lines: {
          type: 'number',
          description: 'Number of context lines around changes (optional, default: 3)',
        },
        include_patterns: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of glob patterns to include (e.g., ["*.res", "src/**/*.js"]) (optional)',
        },
        exclude_patterns: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of glob patterns to exclude (e.g., ["*.lock", "*.svg"]) (optional)',
        },
        file_path: {
          type: 'string',
          description: 'Specific file path to get diff for (e.g., "src/index.ts") (optional)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    name: 'approve_pull_request',
    description: 'Approve 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',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    name: 'unapprove_pull_request',
    description: 'Remove approval from 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',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    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'],
    },
  },
  {
    name: 'remove_requested_changes',
    description: 'Remove change request from 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',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    name: 'get_branch',
    description: 'Get detailed information about a branch including associated pull requests',
    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")',
        },
        branch_name: {
          type: 'string',
          description: 'Branch name to get details for',
        },
        include_merged_prs: {
          type: 'boolean',
          description: 'Include merged PRs from this branch (default: false)',
        },
      },
      required: ['workspace', 'repository', 'branch_name'],
    },
  },
  {
    name: 'list_directory_content',
    description: 'List files and directories in a repository path',
    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")',
        },
        path: {
          type: 'string',
          description: 'Directory path (optional, defaults to root, e.g., "src/components")',
        },
        branch: {
          type: 'string',
          description: 'Branch name (optional, defaults to default branch)',
        },
      },
      required: ['workspace', 'repository'],
    },
  },
  {
    name: 'get_file_content',
    description: 'Get file content from a repository with smart truncation for large files',
    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")',
        },
        file_path: {
          type: 'string',
          description: 'Path to the file (e.g., "src/index.ts")',
        },
        branch: {
          type: 'string',
          description: 'Branch name (optional, defaults to default branch)',
        },
        start_line: {
          type: 'number',
          description: 'Starting line number (1-based). Use negative for lines from end (optional)',
        },
        line_count: {
          type: 'number',
          description: 'Number of lines to return (optional, default varies by file size)',
        },
        full_content: {
          type: 'boolean',
          description: 'Force return full content regardless of size (optional, default: false)',
        },
      },
      required: ['workspace', 'repository', 'file_path'],
    },
  },
  {
    name: 'list_branch_commits',
    description: 'List commits in a branch with detailed information and filtering options',
    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")',
        },
        branch_name: {
          type: 'string',
          description: 'Branch name to get commits from',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of commits to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
        since: {
          type: 'string',
          description: 'ISO date string - only show commits after this date (optional)',
        },
        until: {
          type: 'string',
          description: 'ISO date string - only show commits before this date (optional)',
        },
        author: {
          type: 'string',
          description: 'Filter by author email/username (optional)',
        },
        include_merge_commits: {
          type: 'boolean',
          description: 'Include merge commits in results (default: true)',
        },
        search: {
          type: 'string',
          description: 'Search for text in commit messages (optional)',
        },
        include_build_status: {
          type: 'boolean',
          description: 'Include CI/CD build status for each commit (Bitbucket Server only, default: false)',
        },
      },
      required: ['workspace', 'repository', 'branch_name'],
    },
  },
  {
    name: 'list_pr_commits',
    description: 'List all commits that are part of 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',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of commits to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
        include_build_status: {
          type: 'boolean',
          description: 'Include CI/CD build status for each commit (Bitbucket Server only, default: false)',
        },
      },
      required: ['workspace', 'repository', 'pull_request_id'],
    },
  },
  {
    name: 'search_code',
    description: 'Search for code across Bitbucket repositories with enhanced context-aware search patterns (currently only supported for Bitbucket Server)',
    inputSchema: {
      type: 'object',
      properties: {
        workspace: {
          type: 'string',
          description: 'Bitbucket workspace/project key (e.g., "PROJ")',
        },
        repository: {
          type: 'string',
          description: 'Repository slug to search in (optional, searches all repos if not specified)',
        },
        search_query: {
          type: 'string',
          description: 'The search term or phrase to look for in code (e.g., "variable")',
        },
        search_context: {
          type: 'string',
          enum: ['assignment', 'declaration', 'usage', 'exact', 'any'],
          description: 'Context to search for: assignment (term=value), declaration (defining term), usage (calling/accessing term), exact (quoted match), or any (all patterns)',
        },
        file_pattern: {
          type: 'string',
          description: 'File path pattern to filter results (e.g., "*.java", "src/**/*.ts") (optional)',
        },
        include_patterns: {
          type: 'array',
          items: { type: 'string' },
          description: 'Additional custom search patterns to include (e.g., ["variable =", ".variable"]) (optional)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
      },
      required: ['workspace', 'search_query'],
    },
  },
  {
    name: 'list_projects',
    description: 'List all accessible Bitbucket projects with optional filtering',
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Filter by project name (partial match, optional)',
        },
        permission: {
          type: 'string',
          description: 'Filter by permission level (e.g., PROJECT_READ, PROJECT_WRITE, PROJECT_ADMIN, optional)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of projects to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
      },
      required: [],
    },
  },
  {
    name: 'list_repositories',
    description: 'List repositories in a project or across all accessible projects',
    inputSchema: {
      type: 'object',
      properties: {
        workspace: {
          type: 'string',
          description: 'Bitbucket workspace/project key to filter repositories (optional, if not provided lists all accessible repos)',
        },
        name: {
          type: 'string',
          description: 'Filter by repository name (partial match, optional)',
        },
        permission: {
          type: 'string',
          description: 'Filter by permission level (e.g., REPO_READ, REPO_WRITE, REPO_ADMIN, optional)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of repositories to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
      },
      required: [],
    },
  },
];

Bitbucket MCP Server