list_directory
Browse repository contents without cloning by listing files and directories in a specified path. View structure, types, and sizes for repositories in Bitbucket.
Instructions
List contents of a directory in a repository.
Browse repository structure without cloning.
Args:
repo_slug: Repository slug
path: Directory path (empty string for root)
ref: Branch, tag, or commit hash (default: "main")
limit: Maximum number of entries (default: 100)
Returns:
List of files and directories with their types and sizes
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_slug | Yes | ||
| path | No | ||
| ref | No | main | |
| limit | No |
Implementation Reference
- src/server.py:1473-1502 (handler)MCP tool handler for list_directory. Registers the tool via @mcp.tool(), handles input parameters, calls BitbucketClient.list_directory helper, and formats output using DirectoryEntry models.@mcp.tool() @handle_bitbucket_error @formatted def list_directory( repo_slug: str, path: str = "", ref: str = "main", limit: int = 100, ) -> dict: """List contents of a directory in a repository. Browse repository structure without cloning. Args: repo_slug: Repository slug path: Directory path (empty string for root) ref: Branch, tag, or commit hash (default: "main") limit: Maximum number of entries (default: 100) Returns: List of files and directories with their types and sizes """ client = get_client() entries = client.list_directory(repo_slug, path, ref=ref, limit=validate_limit(limit)) return { "path": path or "/", "ref": ref, "entries": [DirectoryEntry.from_api(e).model_dump() for e in entries], }
- src/models.py:666-680 (schema)Pydantic model defining the output schema for directory entries returned by the list_directory tool.class DirectoryEntry(BaseModel): """Directory entry info.""" path: str type: str # "commit_file" or "commit_directory" size: Optional[int] = None @classmethod def from_api(cls, data: dict) -> "DirectoryEntry": return cls( path=data.get("path", ""), type=data.get("type", ""), size=data.get("size"), )
- src/bitbucket_client.py:1473-1494 (helper)BitbucketClient helper method implementing the core API logic to list directory contents via Bitbucket src endpoint using _paginated_list.def list_directory( self, repo_slug: str, path: str = "", ref: str = "main", limit: int = 100, ) -> list[dict[str, Any]]: """List directory contents. Args: repo_slug: Repository slug path: Directory path (empty for root) ref: Branch, tag, or commit (default: main) limit: Maximum results to return Returns: List of file/directory info dicts """ return self._paginated_list( self._repo_path(repo_slug, "src", ref, path) if path else self._repo_path(repo_slug, "src", ref), limit=limit, )