list_branches
Retrieve a list of branches in a Bitbucket repository, filter by name pattern, and manage pagination with start index and limit parameters.
Instructions
List branches in a repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter branches by name pattern (optional) | |
| limit | No | Maximum number of branches to return (default: 25) | |
| repository | Yes | Repository slug (e.g., "my-repo") | |
| start | No | Start index for pagination (default: 0) | |
| workspace | Yes | Bitbucket workspace/project key (e.g., "PROJ") |
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);