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
`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);
```

Bitbucket MCP Server