zspace-cli 0.1.0__py3-none-any.whl

zspace_cli/__init__.py

@@ -0,0 +1,6 @@
+"""ZSpace CLI & SDK — manage your 极空间 NAS from the terminal or AI agents."""
+
+from zspace_cli.client import ZSpaceClient
+
+__all__ = ["ZSpaceClient"]
+__version__ = "0.1.0"

zspace_cli/auth.py

@@ -0,0 +1,61 @@
+"""Authentication helpers — reads credentials from the ZSpace desktop client."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Credentials:
+    token: str
+    nas_id: str
+    device_id: str
+    username: str = ""
+
+
+_DEFAULT_CONFIG_DIR = Path.home() / "Library" / "Application Support" / "zspace"
+_VUEX_FILENAME = "vuex.json"
+
+
+def locate_config(config_dir: Path | str | None = None) -> Path:
+    """Return the path to vuex.json, raising FileNotFoundError if missing."""
+    d = Path(config_dir) if config_dir else _DEFAULT_CONFIG_DIR
+    vuex = d / _VUEX_FILENAME
+    if not vuex.exists():
+        raise FileNotFoundError(
+            f"极空间客户端配置未找到: {vuex}\n"
+            "请确认已安装并登录极空间桌面客户端。"
+        )
+    return vuex
+
+
+def load_credentials(config_dir: Path | str | None = None) -> Credentials:
+    """Load auth credentials from the ZSpace desktop client config."""
+    vuex_path = locate_config(config_dir)
+    data = json.loads(vuex_path.read_text(encoding="utf-8"))
+
+    state = data.get("state", data)
+    user = state["user"]
+    nas = state["nas"]
+    app = state.get("app", {})
+
+    return Credentials(
+        token=user["token"],
+        nas_id=nas["nasId"],
+        device_id=app.get("deviceId", ""),
+        username=user.get("username", ""),
+    )
+
+
+def check_client_running(base_url: str = "http://127.0.0.1:13579") -> bool:
+    """Quick check if the ZSpace desktop client proxy is reachable."""
+    import httpx
+
+    try:
+        r = httpx.get(f"{base_url}/home/", timeout=3)
+        return r.status_code < 500
+    except (httpx.ConnectError, httpx.TimeoutException):
+        return False

zspace_cli/cli.py

@@ -0,0 +1,271 @@
+"""Beautiful CLI for ZSpace NAS — powered by Typer + Rich."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+from rich import box
+
+from zspace_cli.client import ZSpaceClient, ZSpaceError
+
+app = typer.Typer(
+    name="zs",
+    help="ZSpace NAS CLI — 在终端管理你的极空间 NAS 文件",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+console = Console()
+
+DEFAULT_PATH = "/sata11/my/data"
+
+
+def _client() -> ZSpaceClient:
+    try:
+        return ZSpaceClient()
+    except FileNotFoundError as e:
+        console.print(f"[red]✗[/red] {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]✗ 连接失败:[/red] {e}")
+        raise typer.Exit(1)
+
+
+def _size_str(size: int) -> str:
+    if size >= 1 << 30:
+        return f"{size / (1 << 30):.1f} GB"
+    if size >= 1 << 20:
+        return f"{size / (1 << 20):.1f} MB"
+    if size >= 1 << 10:
+        return f"{size / (1 << 10):.1f} KB"
+    return f"{size} B"
+
+
+@app.command()
+def check():
+    """检查极空间客户端连接状态"""
+    with _client() as c:
+        if not c.is_connected():
+            console.print("[red]✗ 极空间客户端代理不可达[/red]")
+            raise typer.Exit(1)
+
+        console.print("[green]✓ 极空间客户端已连接[/green]")
+        try:
+            pool = c.pool_info()
+            for p in pool["data"]["pool_list"]:
+                total = p["total_size"] / (1024**4)
+                free = p["free_size"] / (1024**4)
+                used_pct = (1 - free / total) * 100 if total else 0
+                console.print(
+                    f"  [bold]{p['name']}[/bold]: "
+                    f"{total:.1f} TB 总容量, {free:.1f} TB 可用 "
+                    f"([{'red' if used_pct > 80 else 'yellow' if used_pct > 60 else 'green'}]"
+                    f"{used_pct:.0f}% 已用[/])"
+                )
+        except ZSpaceError:
+            pass
+
+
+@app.command()
+def ls(
+    path: str = typer.Argument(DEFAULT_PATH, help="目录路径"),
+    hidden: bool = typer.Option(False, "--hidden", "-a", help="显示隐藏文件"),
+    long: bool = typer.Option(False, "--long", "-l", help="详细信息"),
+):
+    """列出目录内容"""
+    with _client() as c:
+        try:
+            entries = c.ls(path, show_hidden=hidden)
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+        if long:
+            table = Table(box=box.SIMPLE, show_header=True, header_style="bold cyan")
+            table.add_column("类型", width=5)
+            table.add_column("大小", justify="right", width=10)
+            table.add_column("名称")
+            table.add_column("路径", style="dim")
+            for e in entries:
+                icon = "📁" if e.is_dir else "📄"
+                size = "" if e.is_dir else _size_str(e.size)
+                table.add_row(icon, size, e.name, e.path)
+            console.print(table)
+        else:
+            for e in entries:
+                if e.is_dir:
+                    console.print(f"  [bold blue]{e.name}/[/bold blue]")
+                else:
+                    console.print(f"  {e.name}  [dim]{_size_str(e.size)}[/dim]")
+
+        console.print(f"\n[dim]共 {len(entries)} 项[/dim]")
+
+
+@app.command()
+def info(path: str = typer.Argument(..., help="文件或目录路径")):
+    """查看文件/目录详细信息"""
+    with _client() as c:
+        try:
+            data = c.info(path)
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+        table = Table(box=box.ROUNDED, show_header=False, title=data.get("name", path))
+        table.add_column("属性", style="bold")
+        table.add_column("值")
+        table.add_row("路径", data.get("path", ""))
+        table.add_row("类型", "目录" if data.get("is_dir") == "1" else "文件")
+        if data.get("size"):
+            table.add_row("大小", _size_str(int(data["size"])))
+        if data.get("modify_time"):
+            table.add_row("修改时间", data["modify_time"])
+        if data.get("create_time"):
+            table.add_row("创建时间", data["create_time"])
+        console.print(table)
+
+
+@app.command()
+def rename(
+    path: str = typer.Argument(..., help="文件或目录路径"),
+    new_name: str = typer.Argument(..., help="新名称"),
+):
+    """重命名文件或目录"""
+    with _client() as c:
+        try:
+            result = c.rename(path, new_name)
+            console.print(f"[green]✓[/green] 已重命名为 [bold]{result.name}[/bold]")
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+
+@app.command()
+def mv(
+    src: str = typer.Argument(..., help="源路径"),
+    dest: str = typer.Argument(..., help="目标目录"),
+):
+    """移动文件或目录"""
+    with _client() as c:
+        try:
+            c.move(src, dest)
+            console.print(f"[green]✓[/green] 已移动到 [bold]{dest}[/bold]")
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+
+@app.command()
+def cp(
+    src: str = typer.Argument(..., help="源路径"),
+    dest: str = typer.Argument(..., help="目标目录"),
+):
+    """复制文件或目录"""
+    with _client() as c:
+        try:
+            c.copy(src, dest)
+            console.print(f"[green]✓[/green] 复制到 [bold]{dest}[/bold]")
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+
+@app.command()
+def mkdir(
+    parent: str = typer.Argument(..., help="父目录路径"),
+    name: str = typer.Argument(..., help="新目录名"),
+):
+    """创建新目录"""
+    with _client() as c:
+        try:
+            result = c.mkdir(parent, name)
+            console.print(f"[green]✓[/green] 已创建 [bold]{result.path}[/bold]")
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+
+@app.command()
+def rm(
+    path: str = typer.Argument(..., help="要删除的路径"),
+    force: bool = typer.Option(False, "--force", "-f", help="跳过确认"),
+):
+    """删除文件或目录"""
+    if not force:
+        confirm = typer.confirm(f"确定要删除 {path}？")
+        if not confirm:
+            raise typer.Abort()
+
+    with _client() as c:
+        try:
+            c.remove(path)
+            console.print(f"[green]✓[/green] 已删除")
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+
+@app.command()
+def find(
+    keyword: str = typer.Argument(..., help="搜索关键词"),
+    path: str = typer.Argument(DEFAULT_PATH, help="搜索目录"),
+):
+    """搜索文件名"""
+    with _client() as c:
+        try:
+            results = c.search(keyword, path)
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+        if not results:
+            console.print(f"[yellow]未找到匹配 '{keyword}' 的文件[/yellow]")
+            return
+
+        for e in results:
+            icon = "📁" if e.is_dir else "📄"
+            console.print(f"  {icon} {e.path}")
+        console.print(f"\n[dim]找到 {len(results)} 项[/dim]")
+
+
+@app.command()
+def tree(
+    path: str = typer.Argument(DEFAULT_PATH, help="根目录"),
+    depth: int = typer.Option(2, "--depth", "-d", help="递归深度"),
+):
+    """树形显示目录结构"""
+    with _client() as c:
+        try:
+            nodes = c.tree(path, max_depth=depth)
+        except ZSpaceError as e:
+            console.print(f"[red]✗[/red] {e}")
+            raise typer.Exit(1)
+
+        root_name = path.rsplit("/", 1)[-1] or path
+        rich_tree = Tree(f"[bold]{root_name}/[/bold]")
+        _build_rich_tree(rich_tree, nodes, 0)
+        console.print(rich_tree)
+
+
+def _build_rich_tree(parent: Tree, nodes: list[dict], depth: int) -> None:
+    """Convert flat node list (with depth) into a Rich Tree."""
+    stack: list[tuple[Tree, int]] = [(parent, -1)]
+    for node in nodes:
+        d = node["depth"]
+        while stack and stack[-1][1] >= d:
+            stack.pop()
+        current_parent = stack[-1][0] if stack else parent
+        if node["is_dir"]:
+            label = f"[bold blue]{node['name']}/[/bold blue]"
+        else:
+            label = f"{node['name']}  [dim]{_size_str(node.get('size', 0))}[/dim]"
+        branch = current_parent.add(label)
+        stack.append((branch, d))
+
+
+if __name__ == "__main__":
+    app()

zspace_cli/client.py

@@ -0,0 +1,220 @@
+"""Core SDK client for the ZSpace NAS API."""
+
+from __future__ import annotations
+
+import time
+import random
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from zspace_cli.auth import Credentials, check_client_running, load_credentials
+
+
+@dataclass
+class FileEntry:
+    name: str
+    path: str
+    is_dir: bool
+    size: int = 0
+    modify_time: str = ""
+    create_time: str = ""
+    ext: str = ""
+
+    @classmethod
+    def from_api(cls, d: dict[str, Any]) -> FileEntry:
+        return cls(
+            name=d["name"],
+            path=d["path"],
+            is_dir=d.get("is_dir", "0") == "1",
+            size=int(d.get("size", 0)),
+            modify_time=d.get("modify_time", ""),
+            create_time=d.get("create_time", ""),
+            ext=d.get("ext", ""),
+        )
+
+
+class ZSpaceError(Exception):
+    """Raised when the ZSpace API returns a non-200 code."""
+
+    def __init__(self, code: str, msg: str):
+        self.code = code
+        self.msg = msg
+        super().__init__(f"[{code}] {msg}")
+
+
+class ZSpaceClient:
+    """High-level client for ZSpace NAS file operations.
+
+    Connects through the local desktop client proxy (127.0.0.1:13579).
+    All operations are pure API calls — no SSH or WebDAV needed.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:13579",
+        credentials: Credentials | None = None,
+        config_dir: Path | str | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._creds = credentials or load_credentials(config_dir)
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            cookies={"token": self._creds.token},
+            timeout=30,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> ZSpaceClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ── internal ──
+
+    def _common_params(self) -> dict[str, str]:
+        return {
+            "token": self._creds.token,
+            "nasid": self._creds.nas_id,
+            "plat": "web",
+            "version": "2.3.2026042401",
+            "device_id": self._creds.device_id,
+            "_l": "zh_cn",
+        }
+
+    def _url(self, endpoint: str) -> str:
+        rnd = f"{int(time.time())}{random.randint(1000,9999)}_{random.randint(1000,9999)}"
+        return f"{endpoint}?&rnd={rnd}&webagent=v2"
+
+    def _post(self, endpoint: str, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+        data = self._common_params()
+        if extra:
+            data.update(extra)
+        resp = self._http.post(
+            self._url(endpoint),
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        body = resp.json()
+        if body.get("code") != "200":
+            raise ZSpaceError(body.get("code", "?"), body.get("msg", "unknown error"))
+        return body
+
+    def _post_with_array(
+        self, endpoint: str, paths: list[str], extra: dict[str, str] | None = None
+    ) -> dict[str, Any]:
+        """POST with paths[] array parameter (used by move/copy/delete)."""
+        params = self._common_params()
+        if extra:
+            params.update(extra)
+        parts: list[str] = []
+        for k, v in params.items():
+            parts.append(f"{_urlencode(k)}={_urlencode(v)}")
+        for p in paths:
+            parts.append(f"paths%5B%5D={_urlencode(p)}")
+        body_str = "&".join(parts)
+
+        resp = self._http.post(
+            self._url(endpoint),
+            content=body_str,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        body = resp.json()
+        if body.get("code") != "200":
+            raise ZSpaceError(body.get("code", "?"), body.get("msg", "unknown error"))
+        return body
+
+    # ── public API ──
+
+    def is_connected(self) -> bool:
+        """Check if the ZSpace desktop client proxy is reachable."""
+        return check_client_running(self.base_url)
+
+    def pool_info(self) -> dict[str, Any]:
+        """Get storage pool information."""
+        return self._post("/zspool/info")
+
+    def disk_stats(self) -> dict[str, Any]:
+        """Get disk statistics."""
+        return self._post("/disk/statics")
+
+    def ls(self, path: str = "/sata11/my/data", show_hidden: bool = False) -> list[FileEntry]:
+        """List directory contents."""
+        body = self._post("/v2/file/list", {
+            "path": path,
+            "show_hidden": "1" if show_hidden else "0",
+        })
+        return [FileEntry.from_api(f) for f in body["data"]["list"]]
+
+    def info(self, path: str) -> dict[str, Any]:
+        """Get detailed file/directory info."""
+        return self._post("/v2/file/info", {"path": path})["data"]
+
+    def rename(self, path: str, new_name: str) -> FileEntry:
+        """Rename a file or directory."""
+        body = self._post("/v2/file/modify", {"path": path, "newname": new_name})
+        return FileEntry.from_api(body["data"])
+
+    def mkdir(self, parent: str, name: str) -> FileEntry:
+        """Create a new directory."""
+        body = self._post("/v2/file/newdir", {"parent": parent, "name": name, "rename": "0"})
+        return FileEntry.from_api(body["data"])
+
+    def move(self, paths: list[str] | str, to: str) -> dict[str, Any]:
+        """Move files/directories to a destination directory."""
+        if isinstance(paths, str):
+            paths = [paths]
+        return self._post_with_array("/v2/file/move", paths, {"to": to})
+
+    def copy(self, paths: list[str] | str, to: str) -> dict[str, Any]:
+        """Copy files/directories to a destination directory."""
+        if isinstance(paths, str):
+            paths = [paths]
+        return self._post_with_array("/v2/file/copy", paths, {"to": to})
+
+    def remove(self, paths: list[str] | str) -> dict[str, Any]:
+        """Delete files/directories (moves to trash)."""
+        if isinstance(paths, str):
+            paths = [paths]
+        return self._post_with_array("/v2/file/remove", paths)
+
+    def search(self, keyword: str, path: str = "/sata11/my/data") -> list[FileEntry]:
+        """Search for files by name within a directory (client-side filtering)."""
+        entries = self.ls(path, show_hidden=True)
+        kw = keyword.lower()
+        return [e for e in entries if kw in e.name.lower()]
+
+    def tree(self, path: str = "/sata11/my/data", max_depth: int = 2) -> list[dict[str, Any]]:
+        """Recursively list directory structure up to max_depth."""
+        result: list[dict[str, Any]] = []
+        self._tree_walk(path, 0, max_depth, result)
+        return result
+
+    def _tree_walk(
+        self, path: str, depth: int, max_depth: int, acc: list[dict[str, Any]]
+    ) -> None:
+        if depth >= max_depth:
+            return
+        try:
+            entries = self.ls(path)
+        except ZSpaceError:
+            return
+        for e in entries:
+            node: dict[str, Any] = {"name": e.name, "path": e.path, "is_dir": e.is_dir, "depth": depth}
+            if not e.is_dir:
+                node["size"] = e.size
+            acc.append(node)
+            if e.is_dir:
+                self._tree_walk(e.path, depth + 1, max_depth, acc)
+
+
+def _urlencode(s: str) -> str:
+    from urllib.parse import quote
+    return quote(str(s), safe="")

zspace_cli/mcp_server.py

@@ -0,0 +1,286 @@
+"""MCP Server for ZSpace NAS — expose file operations as MCP tools.
+
+Usage:
+    python -m zspace_cli.mcp_server
+    # or via the CLI:
+    zs-mcp
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from zspace_cli.client import ZSpaceClient, ZSpaceError
+
+server = Server("zspace-nas")
+
+TOOLS = [
+    Tool(
+        name="zspace_check",
+        description="检查极空间 NAS 连接状态和存储信息 / Check ZSpace NAS connection status and storage info",
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+    Tool(
+        name="zspace_ls",
+        description="列出极空间 NAS 目录内容 / List directory contents on ZSpace NAS",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "目录路径，如 /sata11/my/data",
+                    "default": "/sata11/my/data",
+                },
+                "show_hidden": {"type": "boolean", "default": False},
+            },
+        },
+    ),
+    Tool(
+        name="zspace_info",
+        description="查看文件或目录详细信息 / Get detailed file/directory info",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "文件或目录路径"},
+            },
+            "required": ["path"],
+        },
+    ),
+    Tool(
+        name="zspace_rename",
+        description="重命名文件或目录 / Rename a file or directory",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "文件/目录路径"},
+                "new_name": {"type": "string", "description": "新名称"},
+            },
+            "required": ["path", "new_name"],
+        },
+    ),
+    Tool(
+        name="zspace_mkdir",
+        description="在极空间 NAS 上创建新目录 / Create a new directory",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "parent": {"type": "string", "description": "父目录路径"},
+                "name": {"type": "string", "description": "新目录名"},
+            },
+            "required": ["parent", "name"],
+        },
+    ),
+    Tool(
+        name="zspace_move",
+        description="移动文件或目录 / Move files or directories",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "paths": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
+                    "description": "源路径（单个字符串或数组）",
+                },
+                "to": {"type": "string", "description": "目标目录"},
+            },
+            "required": ["paths", "to"],
+        },
+    ),
+    Tool(
+        name="zspace_copy",
+        description="复制文件或目录 / Copy files or directories",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "paths": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
+                    "description": "源路径（单个字符串或数组）",
+                },
+                "to": {"type": "string", "description": "目标目录"},
+            },
+            "required": ["paths", "to"],
+        },
+    ),
+    Tool(
+        name="zspace_remove",
+        description="删除文件或目录 / Delete files or directories",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "paths": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
+                    "description": "要删除的路径（单个字符串或数组）",
+                },
+            },
+            "required": ["paths"],
+        },
+    ),
+    Tool(
+        name="zspace_search",
+        description="按文件名搜索 / Search files by name",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "keyword": {"type": "string", "description": "搜索关键词"},
+                "path": {
+                    "type": "string",
+                    "description": "搜索目录",
+                    "default": "/sata11/my/data",
+                },
+            },
+            "required": ["keyword"],
+        },
+    ),
+    Tool(
+        name="zspace_tree",
+        description="树形展示目录结构 / Show directory tree",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "根目录",
+                    "default": "/sata11/my/data",
+                },
+                "depth": {"type": "integer", "default": 2, "description": "递归深度"},
+            },
+        },
+    ),
+]
+
+
+def _ok(data: Any) -> list[TextContent]:
+    return [TextContent(type="text", text=json.dumps(data, ensure_ascii=False, indent=2))]
+
+
+def _err(e: Exception) -> list[TextContent]:
+    return [TextContent(type="text", text=f"Error: {e}")]
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return TOOLS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    try:
+        with ZSpaceClient() as c:
+            if name == "zspace_check":
+                connected = c.is_connected()
+                result: dict[str, Any] = {"connected": connected}
+                if connected:
+                    try:
+                        pool = c.pool_info()
+                        result["pools"] = [
+                            {
+                                "name": p["name"],
+                                "total_tb": round(p["total_size"] / (1024**4), 1),
+                                "free_tb": round(p["free_size"] / (1024**4), 1),
+                            }
+                            for p in pool["data"]["pool_list"]
+                        ]
+                    except ZSpaceError:
+                        pass
+                return _ok(result)
+
+            elif name == "zspace_ls":
+                entries = c.ls(
+                    arguments.get("path", "/sata11/my/data"),
+                    show_hidden=arguments.get("show_hidden", False),
+                )
+                return _ok([
+                    {
+                        "name": e.name,
+                        "path": e.path,
+                        "is_dir": e.is_dir,
+                        "size": e.size,
+                    }
+                    for e in entries
+                ])
+
+            elif name == "zspace_info":
+                data = c.info(arguments["path"])
+                return _ok(data)
+
+            elif name == "zspace_rename":
+                result = c.rename(arguments["path"], arguments["new_name"])
+                return _ok({"name": result.name, "path": result.path})
+
+            elif name == "zspace_mkdir":
+                result = c.mkdir(arguments["parent"], arguments["name"])
+                return _ok({"name": result.name, "path": result.path})
+
+            elif name == "zspace_move":
+                paths = arguments["paths"]
+                if isinstance(paths, str):
+                    paths = [paths]
+                c.move(paths, arguments["to"])
+                return _ok({"status": "moved", "paths": paths, "to": arguments["to"]})
+
+            elif name == "zspace_copy":
+                paths = arguments["paths"]
+                if isinstance(paths, str):
+                    paths = [paths]
+                c.copy(paths, arguments["to"])
+                return _ok({"status": "copied", "paths": paths, "to": arguments["to"]})
+
+            elif name == "zspace_remove":
+                paths = arguments["paths"]
+                if isinstance(paths, str):
+                    paths = [paths]
+                c.remove(paths)
+                return _ok({"status": "removed", "paths": paths})
+
+            elif name == "zspace_search":
+                results = c.search(
+                    arguments["keyword"],
+                    arguments.get("path", "/sata11/my/data"),
+                )
+                return _ok([
+                    {"name": e.name, "path": e.path, "is_dir": e.is_dir}
+                    for e in results
+                ])
+
+            elif name == "zspace_tree":
+                nodes = c.tree(
+                    arguments.get("path", "/sata11/my/data"),
+                    max_depth=arguments.get("depth", 2),
+                )
+                return _ok(nodes)
+
+            else:
+                return _err(ValueError(f"Unknown tool: {name}"))
+
+    except ZSpaceError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(e)
+
+
+async def _async_main() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main() -> None:
+    """Entry point for the MCP server (used by zs-mcp console script)."""
+    import asyncio
+    asyncio.run(_async_main())
+
+
+if __name__ == "__main__":
+    main()

zspace_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: zspace-cli
+Version: 0.1.0
+Summary: CLI & SDK for ZSpace (极空间) NAS — manage files from your terminal or AI agents
+Author: skyzhao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/skyzhao/zspace-cli
+Project-URL: Documentation, https://github.com/skyzhao/zspace-cli#readme
+Project-URL: Repository, https://github.com/skyzhao/zspace-cli
+Project-URL: Issues, https://github.com/skyzhao/zspace-cli/issues
+Keywords: zspace,nas,cli,sdk,mcp,极空间,file-manager
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# zspace-cli
+
+**CLI, SDK & MCP Server for ZSpace (极空间) NAS**
+
+> Manage your 极空间 NAS files from the terminal, Python scripts, or AI agents — zero config, no SSH needed.
+
+[English](#features) | [中文](#功能特性)
+
+---
+
+## Why zspace-cli?
+
+ZSpace (极空间) is a popular NAS brand in China, but it lacks official CLI tools or developer APIs.
+
+**zspace-cli** reverse-engineered the internal API used by the ZSpace desktop client and wraps it into:
+
+- **`zs` CLI** — 10 commands covering all file operations, powered by [Rich](https://github.com/Textualize/rich) for beautiful output
+- **Python SDK** — `ZSpaceClient` with a clean, typed interface for automation scripts
+- **MCP Server** — one-line config to add ZSpace file management to Claude, Cursor, or any MCP-compatible AI agent
+
+### Zero Configuration
+
+Just install and run. zspace-cli reads auth tokens directly from your running ZSpace desktop client — no passwords, no SSH keys, no port forwarding.
+
+```
+pip install zspace-cli
+zs check   # ✓ Connected, 11.8 TB total, 1.2 TB free
+zs ls      # List your NAS files
+```
+
+---
+
+## Features
+
+| Operation | CLI | SDK | MCP |
+|-----------|-----|-----|-----|
+| List directory | `zs ls [path]` | `client.ls(path)` | `zspace_ls` |
+| File info | `zs info <path>` | `client.info(path)` | `zspace_info` |
+| Rename | `zs rename <path> <name>` | `client.rename(path, name)` | `zspace_rename` |
+| Create dir | `zs mkdir <parent> <name>` | `client.mkdir(parent, name)` | `zspace_mkdir` |
+| Move | `zs mv <src> <dest>` | `client.move(src, dest)` | `zspace_move` |
+| Copy | `zs cp <src> <dest>` | `client.copy(src, dest)` | `zspace_copy` |
+| Delete | `zs rm <path>` | `client.remove(path)` | `zspace_remove` |
+| Search | `zs find <keyword>` | `client.search(kw)` | `zspace_search` |
+| Tree view | `zs tree [path]` | `client.tree(path)` | `zspace_tree` |
+| Health check | `zs check` | `client.is_connected()` | `zspace_check` |
+
+---
+
+## Installation
+
+```bash
+pip install zspace-cli
+```
+
+**Prerequisites:** ZSpace desktop client running on macOS (logged in).
+
+### With MCP Server support
+
+```bash
+pip install "zspace-cli[mcp]"
+```
+
+---
+
+## Quick Start
+
+### CLI
+
+```bash
+# Check connection
+zs check
+
+# List files
+zs ls /sata11/my/data
+zs ls -l /sata11/my/data/影视    # detailed view
+
+# File operations
+zs mkdir /sata11/my/data 新建文件夹
+zs rename /sata11/my/data/old_name new_name
+zs mv /sata11/my/data/file.mp4 /sata11/my/data/影视
+zs cp /sata11/my/data/important /sata11/my/data/backup
+zs rm /sata11/my/data/temp
+
+# Search & explore
+zs find "权力的游戏"
+zs tree /sata11/my/data -d 3
+```
+
+### Python SDK
+
+```python
+from zspace_cli import ZSpaceClient
+
+with ZSpaceClient() as zs:
+    # List files
+    for f in zs.ls("/sata11/my/data"):
+        print(f"{'📁' if f.is_dir else '📄'} {f.name}")
+
+    # Batch rename videos
+    for f in zs.ls("/sata11/my/data/影视"):
+        if f.name.startswith("[raw]"):
+            new_name = f.name.replace("[raw]", "").strip()
+            zs.rename(f.path, new_name)
+            print(f"Renamed: {new_name}")
+
+    # Organize files
+    zs.mkdir("/sata11/my/data", "已整理")
+    zs.move("/sata11/my/data/散文件.pdf", "/sata11/my/data/已整理")
+```
+
+### MCP Server (for AI Agents)
+
+Add to your Claude Desktop / Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "zspace": {
+      "command": "zs-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Then ask your AI: "帮我把 NAS 上影视文件夹里的视频按年份整理一下"
+
+---
+
+## How It Works
+
+```
+┌─────────────┐      ┌──────────────────┐      ┌──────────┐
+│  zs CLI     │      │  ZSpace Desktop  │      │  ZSpace  │
+│  Python SDK ├─────►│  Client (proxy)  ├─────►│  NAS     │
+│  MCP Server │ HTTP │  127.0.0.1:13579 │ P2P  │  Device  │
+└─────────────┘      └──────────────────┘      └──────────┘
+```
+
+The ZSpace desktop client maintains an encrypted tunnel to your NAS and exposes a local HTTP proxy. zspace-cli communicates with this proxy using the same API the official web UI uses.
+
+**No direct network access to the NAS is needed** — works even when your NAS is behind NAT or on a different network.
+
+---
+
+## API Reference
+
+All operations go through the ZSpace internal API at `127.0.0.1:13579`.
+
+| Endpoint | Method | Key Parameters |
+|----------|--------|---------------|
+| `/v2/file/list` | POST | `path`, `show_hidden` |
+| `/v2/file/info` | POST | `path` |
+| `/v2/file/modify` | POST | `path`, `newname` |
+| `/v2/file/newdir` | POST | `parent` (not path!), `name`, `rename=0` |
+| `/v2/file/move` | POST | `paths[]` (array), `to` (not dest!) |
+| `/v2/file/copy` | POST | `paths[]` (array), `to` (not dest!) |
+| `/v2/file/remove` | POST | `paths[]` (array) |
+
+> **Key discovery:** The parameter names are non-standard — `newdir` uses `parent` instead of `path`, and `move`/`copy` use `to` instead of `dest`. These were found by reverse-engineering the ZSpace web UI.
+
+---
+
+## Roadmap
+
+- [ ] File upload/download support
+- [ ] Linux client support
+- [ ] Windows client support
+- [ ] Docker image for headless deployment
+- [ ] Batch operations with glob patterns
+- [ ] File watching / sync triggers
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue first to discuss what you'd like to change.
+
+---
+
+## License
+
+MIT
+
+---
+
+<details>
+<summary><h2>中文说明</h2></summary>
+
+## 功能特性
+
+**zspace-cli** 是极空间 NAS 的命令行工具、Python SDK 和 MCP Server。
+
+通过逆向工程极空间桌面客户端的内部 API，实现了**完整的文件管理功能**——无需 SSH，无需 WebDAV，零配置即可使用。
+
+### 安装
+
+```bash
+pip install zspace-cli
+```
+
+**前提条件：** macOS 上已安装并登录极空间桌面客户端。
+
+### 使用方法
+
+```bash
+# 检查连接
+zs check
+
+# 文件操作
+zs ls                             # 列出目录
+zs ls -l /sata11/my/data/影视     # 详细模式
+zs info /sata11/my/data/影视      # 查看详情
+zs mkdir /sata11/my/data 新文件夹  # 创建目录
+zs rename /path/old new_name       # 重命名
+zs mv /path/src /path/dest         # 移动
+zs cp /path/src /path/dest         # 复制
+zs rm /path/to/delete              # 删除
+zs find "关键词"                    # 搜索
+zs tree /sata11/my/data -d 3       # 树形视图
+```
+
+### MCP Server 配置（AI 智能体）
+
+在 Claude Desktop 或 Cursor 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "zspace": {
+      "command": "zs-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+配置完成后，你可以用自然语言让 AI 管理你的 NAS 文件：
+- "帮我把影视文件夹里的电影按年份分类"
+- "查找所有大于 10GB 的文件"
+- "把百度网盘文件夹里的文档移到文档同步文件夹"
+
+### 工作原理
+
+极空间桌面客户端在本机 `127.0.0.1:13579` 建立了到 NAS 的加密代理。zspace-cli 通过这个代理调用和官方 Web UI 完全相同的 API，因此：
+
+- 不需要 NAS 在局域网内
+- 不需要配置 DDNS 或端口转发
+- 不需要开启 SSH
+- 只要桌面客户端在运行，就能操作
+
+</details>

zspace_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+zspace_cli/__init__.py,sha256=yNbNxF0I8FLon2jOntTbWpwamQSy9YKIu9rwOtFKCfc,179
+zspace_cli/auth.py,sha256=63UE1B1qQ0Q3eRd7yLTXEJBuqPp77nGQ0S3oy-Om_B4,1768
+zspace_cli/cli.py,sha256=_zZMmmzXnQ8bltXykD23dpxgBrdlxXQgVRw8lxVLQEo,8697
+zspace_cli/client.py,sha256=baelFWaOhMtVvNWCXbJTRM61jK17p3iDJMwgtQorVKQ,7414
+zspace_cli/mcp_server.py,sha256=0sZiySpcsdoKM0T4ekBlVXhlMjza5htWBX-rj1Yo9n4,9535
+zspace_cli-0.1.0.dist-info/licenses/LICENSE,sha256=GdTKqt3IjvlxTIpk_tdIxpj7eVNl41bxIgXVn8FkP8Q,1064
+zspace_cli-0.1.0.dist-info/METADATA,sha256=ocxzvxclKU9aaE6wlyNVCoBny1G6fscrpLf99ulObZI,8799
+zspace_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+zspace_cli-0.1.0.dist-info/entry_points.txt,sha256=f2FlYYCsomK9zdGcnW3gE-w7E5G6Ipx8IWeCaxSE2IQ,78
+zspace_cli-0.1.0.dist-info/top_level.txt,sha256=1tQGk75bTnkcGLdXJ0m3egDGO2KqUKmSmV6opnqgDSU,11
+zspace_cli-0.1.0.dist-info/RECORD,,

zspace_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zspace_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+zs = zspace_cli.cli:app
+zs-mcp = zspace_cli.mcp_server:main

zspace_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skyzhao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zspace_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zspace_cli