Check whether the ZSpace NAS is reachable through the local desktop client proxy and, if so, return a summary of storage pools.

Call this first to verify the proxy at 127.0.0.1:13579 is online before running other file operations. Returns {"connected": true, "pools": [{name, total_tb, free_tb}]} when the NAS responds, or {"connected": false} when it does not. Never modifies NAS state.

Unlike zspace_pool_info, this is a connectivity probe that happens to include a pool summary; use pool_info when you only need capacity.

List every storage pool on the ZSpace NAS with its name and capacity.

Use to inspect free space before an upload or to report total capacity. Returns a list of {name, total_tb, free_tb} objects, one per pool. Read-only; never modifies NAS state.

Prefer this over zspace_disk_stats for capacity questions: it returns normalized per-pool numbers, whereas disk_stats returns the NAS's raw diagnostics object. Use zspace_check instead if you need to know whether the NAS is reachable at all.

Return raw disk statistics reported by the ZSpace NAS.

Use for diagnostics and health monitoring (I/O, capacity, SMART-style counters as exposed by the NAS API). Returns the raw stats object. Read-only; never modifies NAS state.

Unlike zspace_pool_info, the shape is whatever the NAS API exposes and is not normalized — choose pool_info for "how much free space", this one for "is a disk unhealthy".

List the contents of a directory on the ZSpace NAS at the given path.

Use to browse files, locate items, or pick targets for later move/copy operations. Large directories are paginated automatically (the NAS API returns at most 50 entries per call). Returns a list of {name, path, is_dir, size} objects. Read-only; pass show_hidden=True to include hidden entries.

Flat and one level deep: use zspace_tree for nested structure, zspace_search when you know a name but not the location, and zspace_info for full metadata on one path you already have.

Return detailed metadata for one file or directory on the ZSpace NAS.

Use when you need more than the ls summary exposes (permissions, timestamps, exact size, type details). Returns the raw info object from the NAS API. Read-only; the path must already exist.

One path only — use zspace_ls to enumerate a directory, or zspace_search to locate an item first.

Rename one file or directory on the ZSpace NAS, keeping it in place.

Use to fix a name without changing location; the parent directory stays the same. new_name is the bare basename, not a path. Returns the updated {name, path}. This mutates NAS state; it cannot be undone.

Same-directory only — use zspace_move to relocate to a different parent (move also accepts several paths at once, rename does not).

Create a new directory on the ZSpace NAS under the given parent.

Use to prepare a destination before moving files into it. name is the bare basename, not a path. Fails if a directory of that name already exists. Returns the created {name, path}. Mutates NAS state.

zspace_move and zspace_copy both require the destination to exist already, so call this first when reorganizing into a new folder.

Move one or more files/directories on the NAS into a destination folder.

Use to reorganize files, e.g. sort media into per-genre folders. Accepts a single path or a list; the destination must already exist (create it with zspace_mkdir). Returns {status: "moved", paths, to}. Mutates NAS state; sources are removed from their original location.

Choose move vs copy by whether the originals should survive: copy keeps them, move does not. To change only the name within the same directory, use zspace_rename instead.

Copy one or more files/directories on the NAS into a destination folder.

Use to duplicate media or create backups without removing the originals. Accepts a single path or a list; the destination must already exist (create it with zspace_mkdir). Returns {status: "copied", paths, to}. Mutates NAS state but leaves the sources untouched.

The non-destructive counterpart of zspace_move — pick copy when the original must stay where it is, move when it should not. Copies consume additional capacity; check zspace_pool_info first for large trees.

Permanently delete one or more files/directories from the ZSpace NAS.

Use only when you are sure the items are no longer needed — deletion is immediate and NOT recoverable. Accepts a single path or a list. Returns {status: "removed", paths}. Marked destructive: confirm intent before calling.

There is no trash or undo: zspace_move is the reversible alternative when the goal is only to get items out of the way. Confirm the exact paths with zspace_ls or zspace_search before calling, and never pass a pool root.

Search for files/directories on the NAS whose names contain the keyword.

Use to find a file without knowing its exact location. Returns a list of {name, path, is_dir} matches, capped at 100. Read-only; never modifies NAS state.

The NAS full-text index is searched GLOBALLY, then results are filtered client-side to path. Because path defaults to /sata11/my/data, a match living in another pool is silently dropped and you get an empty list — pass the pool root (or the widest directory you mean) before concluding a file does not exist. Unlike zspace_ls / zspace_tree this matches by name across the index rather than walking a directory.

Return a nested tree view of a directory on the ZSpace NAS.

Use to understand overall folder structure before deep operations. depth caps recursion (default 2). Returns the nested tree structure as exposed by the NAS API. Read-only.

Nested rather than flat: use zspace_ls for a single level with sizes, or zspace_search when you are looking for a name rather than a layout.

Upload a file from the local machine to a directory on the ZSpace NAS.

Use to push media or documents to the NAS. remote_dir must already exist (create it with zspace_mkdir); pass new_name to rename it on arrival. Returns the upload result from the NAS API. Mutates NAS state; a file with the same name is overwritten.

Local -> NAS, the inverse of zspace_download. Files above 64 MB go through the desktop client's sliced upload protocol (2 MB slices) automatically, because the local proxy rejects oversized single-request bodies with HTTP 413. Check zspace_pool_info for free space before large uploads.

Download a file from the ZSpace NAS to a local directory.

Use to pull media or documents off the NAS. The local_dir must already exist. Returns {saved_to: ""}. Does not modify NAS state.

NAS -> local, the inverse of zspace_upload. Unlike upload this never changes anything on the NAS, so it is safe to retry; an existing local file of the same name is overwritten.

Report where physical disk space actually goes on the ZSpace NAS.

Use this FIRST for any "is my NAS full?" or "what is using my space?" question. It is the only view that includes Time Machine backups, other users' spaces, the safe box, Docker, RAID metadata and the recycle bins -- every one of those is outside //my/data and returns N001411 to file listing, so walking the file tree systematically under-reports pool usage (measured: a full 57-minute walk of 2.69M files accounted for only 4.84 TiB of a 7.97 TiB pool).

Returns per pool: total/used/free bytes, used_pct, and entries of {kind, owner, label, label_cn, bytes} sorted largest first, where label is one of my / my_tm (Time Machine) / my_recycle / my_safe / sys_docker / sys_raid / sys_vm / sys_iscsi / sys_other. Read-only.

The my_recycle entry is the recycle bin's physical footprint, so this is the cheap way to see how much space deleted-but-not-purged data is holding before deciding whether to list or empty it. Also note these are physical sizes: my includes the second copy of every double-backed-up folder, whereas a file-level walk (zspace_du) reports logical sizes. The walk therefore comes out lower by exactly the mirrored bytes -- measured on one pool as 4.838 TiB walked vs 6.008 TiB reported here, the 1.17 TiB gap being the double-written folder. Neither number is wrong; they measure different things.

If you compare these figures against a scan run on an SMB mount, expect a mismatch: the mount exposes "@Recycle" and other directories the file API cannot see, and a mount-side scan that fails to skip "@Recycle" counts recycled data as live. That inflates totals silently rather than erroring.

For the size of one specific directory use zspace_du instead; for per-disk health use zspace_disks.

Get the size, file count and directory count of one NAS directory.

Returns {path, bytes, files, dirs, state, complete, source, categories}.

Always check complete before reporting the numbers. The server-side statistic is instant and exact for small-to-medium trees, but on large ones the NAS returns state="running" with a partial snapshot that never converges -- measured on a 1.175 TiB / 448k-file folder, fourteen consecutive calls all reported ~0.35 TiB with the file count jittering between 27k and 30k. There is no poll endpoint that works, so when complete is false either pass walk=true or tell the user the figure is a lower bound. Never present a partial number as the answer.

walk=true traverses via /v2/file/list at roughly one request per directory; a 448k-file tree needs ~93k requests and ~12 minutes. Read-only.

Do not cross-check this against a du run on an SMB mount and assume one of them is broken. The mount exposes directories the file API cannot see at all -- notably "@Recycle", the same recycle bin that zspace_recycle_list reads as "/.recycle/my" -- so a mount-side count includes recycled data this tool correctly excludes. Mount-side scans must skip "@Recycle" (and ".zspace_trash"); counting it inflates totals without raising any error.

For whole-pool accounting use zspace_usage; to list individual large files use zspace_bigfiles.

List the largest files under the given directories, biggest first.

Use to find cleanup candidates. The NAS scans server-side, which is far faster than walking: a 7k-file tree returns in ~2 seconds versus ~765 requests and ~10 seconds client-side. Returns {complete, scanned, matched, files: [{name, path, bytes, modify_time}]}.

There is a single shared task slot, so this call clears any stale task before starting one; that is harmless but means two concurrent bigfiles scans would interfere. Check complete -- if the timeout elapsed the results are partial. Read-only.

For a directory's total size use zspace_du; for pool-level accounting use zspace_usage.

Report every physical disk: free space, temperature, health, SMART counters, fragmentation and power-on hours, plus how many bays are empty.

Use before recommending a drive purchase or when a pool is nearly full -- pool-level free space can be misleading, since in a ZDR pool the space may all sit on one spindle while another is effectively full (observed: a pool reporting 476 GiB free had one disk with only 59.8 GiB left).

Returns {free_bays: {sata, nvme, esata}, disks: [{pool, position, model, sn, dev_type, total_bytes, free_bytes, used_pct, temp_c, health, power_on_hours, reallocated_sectors, fragment_pct, suspected_smr}]}. Read-only.

Tip: power_on_hours greater than the hours since the disk was installed means the drive was previously used elsewhere. For full SMART attributes use zspace_smart; for pool totals use zspace_usage.

Return the full SMART attribute table for one disk.

The endpoint is keyed on serial number -- passing a pool id or a /dev name returns N300403. Get serials from zspace_disks first. Returns {health, attributes: [{id, attr_name, en_attr_name, now_value, worst, thresh, str_value, health}]}; the server also supplies warning/fault text per attribute. NVMe drives report no classic attributes. Read-only.

Focus on ids 5 (reallocated), 187 (reported uncorrectable), 197 (current pending), 198 (offline uncorrectable) and 199 (UDMA CRC) -- those are the ones that predict failure. For a quick health overview use zspace_disks.

List what is currently in a recycle bin, including each item's original location.

Always call this before zspace_recycle_empty -- emptying purges every item in the bin, including files deleted earlier by other means, and is irreversible. The personal and public bins are separate stores; files deleted from //my/data land in the personal one.

The listing triggers a server-side scan and this call waits for it to settle, so an in-progress scan is not mistaken for an empty bin. Returns {bin, total, items: [{name, path, original_path, is_dir, bytes}]}. The path is the in-bin location and is what zspace_recycle_restore and zspace_recycle_purge need. Read-only.

Naming: this tool reaches the bin through the API, where it is "/.recycle/my". The same bin is visible on an SMB mount as a directory called "@Recycle" at the share root (plus a ".zspace_trash" variant), which is outside //my/data and therefore not readable through the file API at all. If you are also running scripts against a mounted path -- the skills/ scanners do exactly that -- they must skip "@Recycle", or recycled files get counted as live data. That miscount raises no error, it just quietly inflates totals; it survived in 8 of the 9 scanners before being caught. Do not try to list "@Recycle" through this API to cross-check: it returns N001411 for every path outside my/data whether or not it exists, so that response tells you nothing.

Read the recycle bin retention policy: {my_cycle, public_cycle} in days.

-1 means never auto-purge, which is the factory default -- so deleted data keeps occupying pool space indefinitely until something empties the bin. If a user reports that deleting files did not free space, check this first. Read-only; there is deliberately no MCP tool for changing it.

Restore items from the personal recycle bin to their original locations.

Paths must be the in-bin paths reported by zspace_recycle_list, not the original locations. Returns {restored, failed}. Restores data rather than removing it, so this is the recovery path after an accidental zspace_remove -- but it only works while the bin has not been emptied.

Permanently delete only the named items from the personal recycle bin, leaving everything else untouched. Irreversible.

Prefer this over zspace_recycle_empty whenever the goal is to free the space held by specific files: the bin may also contain items the user did not put there. Call zspace_recycle_list first and show the user what will be destroyed. Requires confirm=true; without it the call is refused and nothing happens. Returns {purged, failed}.

Permanently purge an entire recycle bin. Irreversible, and this is the only way deleted files actually stop occupying pool space.

Two things make this easy to get wrong. First, the personal and public bins are separate stores: emptying the public bin after deleting from a personal space succeeds with total_num=0 and frees nothing. Second, it purges EVERYTHING in that bin, not just what the current task deleted.

Always call zspace_recycle_list first, show the user the contents, and get their agreement. Requires confirm=true. Returns the server task summary {total_num, succeed_num, fail_num, total_size} -- verify total_num is non-zero before claiming space was freed. Use zspace_recycle_purge to remove specific items instead.