list_directory_content
Access and display files and directories within a specified repository path on Bitbucket, enabling easy navigation and management of repository content.
Instructions
List files and directories in a repository path
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | Branch name (optional, defaults to default branch) | |
| path | No | Directory path (optional, defaults to root, e.g., "src/components") | |
| repository | Yes | Repository slug (e.g., "my-repo") | |
| workspace | Yes | Bitbucket workspace/project key (e.g., "PROJ") |
Implementation Reference
- src/handlers/file-handlers.ts:29-115 (handler)The core handler function that implements the list_directory_content tool. It validates arguments, queries the Bitbucket API (supporting both Cloud and Server), processes the directory listing, and returns a formatted JSON response with file/directory details.async handleListDirectoryContent(args: any) { if (!isListDirectoryContentArgs(args)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid arguments for list_directory_content' ); } const { workspace, repository, path: dirPath = '', branch } = args; try { let apiPath: string; let params: any = {}; let response: any; if (this.apiClient.getIsServer()) { // Bitbucket Server API apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/browse`; if (dirPath) { apiPath += `/${dirPath}`; } if (branch) { params.at = `refs/heads/${branch}`; } response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params }); } else { // Bitbucket Cloud API const branchOrDefault = branch || 'HEAD'; apiPath = `/repositories/${workspace}/${repository}/src/${branchOrDefault}`; if (dirPath) { apiPath += `/${dirPath}`; } response = await this.apiClient.makeRequest<any>('get', apiPath); } // Format the response let contents: any[] = []; let actualBranch = branch; if (this.apiClient.getIsServer()) { // Bitbucket Server response const entries = response.children?.values || []; contents = entries.map((entry: BitbucketServerDirectoryEntry) => ({ name: entry.path.name, type: entry.type === 'FILE' ? 'file' : 'directory', size: entry.size, path: dirPath ? `${dirPath}/${entry.path.name}` : entry.path.name })); // Get the actual branch from the response if available if (!branch && response.path?.components) { // Server returns default branch info in the response actualBranch = 'default'; } } else { // Bitbucket Cloud response const entries = response.values || []; contents = entries.map((entry: BitbucketCloudDirectoryEntry) => ({ name: entry.path.split('/').pop() || entry.path, type: entry.type === 'commit_file' ? 'file' : 'directory', size: entry.size, path: entry.path })); // Cloud returns the branch in the response actualBranch = branch || response.commit?.branch || 'main'; } return { content: [ { type: 'text', text: JSON.stringify({ path: dirPath || '/', branch: actualBranch, contents, total_items: contents.length }, null, 2), }, ], }; } catch (error) { return this.apiClient.handleApiError(error, `listing directory '${dirPath}' in ${workspace}/${repository}`); } }
- src/tools/definitions.ts:466-491 (schema)Official tool definition including name, description, and input schema used for tool discovery and validation.{ 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'], }, },
- src/types/guards.ts:229-243 (schema)Type guard function used in the handler to validate and type-check input arguments for the list_directory_content tool.export const isListDirectoryContentArgs = ( args: any ): args is { workspace: string; repository: string; path?: string; branch?: string; } => typeof args === 'object' && args !== null && typeof args.workspace === 'string' && typeof args.repository === 'string' && (args.path === undefined || typeof args.path === 'string') && (args.branch === undefined || typeof args.branch === 'string');
- src/index.ts:134-135 (registration)Registration and dispatch logic in the main MCP server that maps tool calls for 'list_directory_content' to the appropriate handler method.case 'list_directory_content': return this.fileHandlers.handleListDirectoryContent(request.params.arguments);