list_folders

Instructions

Args:
    limit: Maximum number of folders to return (default 100, max 200)
    offset: Number of folders to skip for pagination

Implementation Reference

• code/mcp/sifter_mcp/server.py:101-111 (handler)

  The MCP tool handler for 'list_folders'. Calls the async SDK client's list_folders method and returns paginated folder data.

  @mcp.tool()
  async def list_folders(limit: int = 100, offset: int = 0) -> dict:
      """List folders with their name and document count.
  
      Args:
          limit: Maximum number of folders to return (default 100, max 200)
          offset: Number of folders to skip for pagination
      """
      async with _get_client() as client:
          page = await client.list_folders(limit=min(limit, 200), offset=offset)
      return {"items": [h._data for h in page.items], "total": page.total, "limit": page.limit, "offset": page.offset}

• code/mcp/sifter_mcp/server.py:101-101 (registration)

  The @mcp.tool() decorator registers this function as the 'list_folders' MCP tool.

  @mcp.tool()

• code/sdk-python/sifter/async_client.py:588-602 (helper)

  Async SDK client method that calls the REST API GET /api/folders and returns paginated FolderHandle objects.

  async def list_folders(self, limit: int = 200, offset: int = 0) -> Page:
      async with httpx.AsyncClient() as http:
          r = await http.get(
              f"{self.api_url}/api/folders",
              headers=self._auth_headers(),
              params={"limit": limit, "offset": offset},
          )
          r.raise_for_status()
          data = r.json()
      raw = data if isinstance(data, list) else data.get("items", [])
      items = [AsyncFolderHandle(item, self) for item in raw]
      total = len(raw) if isinstance(data, list) else data.get("total", 0)
      return Page(items=items, total=total, limit=data.get("limit", limit) if isinstance(data, dict) else limit,
                  offset=data.get("offset", offset) if isinstance(data, dict) else offset,
                  next_cursor=data.get("next_cursor") if isinstance(data, dict) else None)

• code/sdk-python/sifter/client.py:825-841 (helper)

  Sync SDK client method that calls the REST API GET /api/folders and returns paginated FolderHandle objects.

  def list_folders(self, limit: int = 200, offset: int = 0) -> "Page":
      """Return one page of folders as FolderHandle objects."""
      import httpx
      with httpx.Client() as http:
          r = http.get(
              f"{self.api_url}/api/folders",
              headers=self._auth_headers(),
              params={"limit": limit, "offset": offset},
          )
          r.raise_for_status()
          data = r.json()
      raw = data if isinstance(data, list) else data.get("items", [])
      items = [FolderHandle(item, self) for item in raw]
      total = len(raw) if isinstance(data, list) else data.get("total", 0)
      return Page(items=items, total=total, limit=data.get("limit", limit) if isinstance(data, dict) else limit,
                  offset=data.get("offset", offset) if isinstance(data, dict) else offset,
                  next_cursor=data.get("next_cursor") if isinstance(data, dict) else None)

• code/server/sifter/api/folders.py:93-112 (helper)

  Server-side REST API endpoint GET /api/folders that handles the HTTP request and delegates to DocumentService.list_folders.

  @router.get("")
  async def list_folders(
      limit: int = 200,
      offset: int = 0,
      parent_id: Optional[str] = None,
      all: bool = True,
      principal: Principal = Depends(get_current_principal),
      db=Depends(get_db),
  ):
      """List folders. By default returns all folders (flat).
      Pass ?all=false&parent_id=root for root-level folders.
      Pass ?all=false&parent_id={id} for direct children."""
      svc = DocumentService(db)
      if all:
          folders, total = await svc.list_folders(skip=offset, limit=limit, parent_id="ALL", org_id=principal.org_id)
      elif parent_id == "root":
          folders, total = await svc.list_folders(skip=offset, limit=limit, parent_id=None, org_id=principal.org_id)
      else:
          folders, total = await svc.list_folders(skip=offset, limit=limit, parent_id=parent_id, org_id=principal.org_id)
      return paginated([_folder_dict(f) for f in folders], total, limit, offset)