mcp-server-bitbucket

Instructions

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

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,
      )