Bitbucket MCP Server

Overview Schema Related Servers Score Discussions

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: [],
    },
  },
];

Tool Definition Quality

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'detailed information' but doesn't specify what details are included (e.g., commit hash, author, date, message) or behavioral traits like pagination, rate limits, or error handling. The description is vague and lacks critical operational context for a tool with 10 parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose. It avoids redundancy and wastes no words, though it could be slightly more structured by explicitly listing key filtering options. It's appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain the return format, pagination behavior, or error cases, leaving significant gaps for the agent. Without annotations or output schema, the description should provide more context on what 'detailed information' entails and how results are structured.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with all parameters well-documented in the input schema. The description adds minimal value beyond the schema by implying filtering options ('with detailed information and filtering options'), but doesn't provide additional semantics, examples, or clarification on parameter interactions. This meets the baseline score of 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'List commits in a branch with detailed information and filtering options,' which specifies the verb ('List'), resource ('commits in a branch'), and scope ('detailed information and filtering options'). It distinguishes from siblings like 'list_branches' (which lists branches) and 'list_pr_commits' (which lists commits for pull requests), but doesn't explicitly differentiate from 'list_directory_content' or 'search_code' in terms of commit-specific filtering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_pr_commits' for pull request commits or 'search_code' for code search, nor does it specify prerequisites or contexts for usage. The agent must infer usage from the tool name and parameters alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Related Tools

bb_list_branchesA
@aashari/mcp-server-atlassian-bitbucket
git_commit_history
@bsreeram08/git-commands-mcp
bb_get_commit_historyA
@aashari/mcp-server-atlassian-bitbucket
list_commits
@PhialsBasement/mcp-github-server-plus
list_branchesC
@pdogra1299/bitbucket-mcp-server
list_commits
@MissionSquad/mcp-github

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pdogra1299/bitbucket-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server