MCP Server for ZSpace NAS — expose file operations as MCP tools
A well-structured MCP server for ZSpace NAS file operations. Tools are clearly named with action verbs (zspace_check, zspace_ls, zspace_mkdir, etc.) and have substantive descriptions explaining WHAT they do, WHEN to use them, and key distinctions from similar tools. Most parameters have types and descriptions. However, several tools lack complete schemas (zspace_move, zspace_copy, zspace_delete, zspace_search, zspace_tree have minimal input schema documentation), and some descriptions could be more concise and LLM-optimized. Error handling is present via the @_safe_tool wrapper but lacks recovery guidance. Output schemas are documented in descriptions but not as formal JSON Schema objects in the code.
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.
Copy files or directories on the ZSpace NAS to a new location.
Delete files or directories on the ZSpace NAS.
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".
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.
zspace_move, zspace_copy, zspace_delete have minimal descriptions (under 100 chars each) that lack guidance on WHEN to use them, prerequisites, or behavioral nuance. The source code shows only bare one-liners: 'Move files or directories...', 'Copy files or directories...', 'Delete files or directories...'. LLMs need 50-200 char descriptions explaining intent, use cases, and distinctions from similar tools.
zspace_move and zspace_copy have ambiguous input schemas. The 'paths' parameter accepts 'type: ["string", "array"]' which is non-standard JSON Schema. Proper schema should be 'oneOf: [{type: "string"}, {type: "array", items: {type: "string"}}]' or clarified as 'Union[str, List[str]]' with explicit description of when to pass single vs multiple paths.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 68 | 2026-07-28+ | v2 |
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.
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 files or directories on the ZSpace NAS to a new location.
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.
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).
Search for files or directories on the ZSpace NAS by name.
Display directory tree structure on the ZSpace NAS.
zspace_search and zspace_tree have incomplete descriptions that do not explain return structure, result limits, pagination behavior, or error conditions. 'Search for files or directories...' and 'Display directory tree...' provide no actionable guidance for LLM selection or result interpretation. Per pattern:tool-description, descriptions should state WHAT, WHEN, and WHAT RETURNS.
Error handling via @_safe_tool wrapper returns {'error': str(e)} but provides no recovery guidance. When a path is not found or deletion fails, the agent receives a string error with no hint about next steps (e.g. 'Try zspace_ls() to verify the path exists'). Per pattern:recovery-guide, errors should guide the agent toward resolution.
Output schemas are documented in natural-language descriptions but not formalized as JSON Schema in the tool registration. The code shows descriptions like 'Returns a list of {name, path, is_dir, size} objects' but the server does not declare this structure in a schema field. This forces LLMs to parse descriptions to infer the response shape, increasing hallucination risk.
zspace_delete (DESTRUCTIVE) and zspace_move (high-risk WRITE) lack confirmation or dry-run support. Per pattern:confirmation-request, irreversible operations should offer a confirmation step to prevent catastrophic agent mistakes (e.g. deleting the wrong directory tree).
Parameters like 'path' in zspace_ls, zspace_info, zspace_mkdir accept absolute paths but provide no validation guidance (e.g. 'must start with /sata11/'). The descriptions include examples (e.g. '/sata11/my/data') but do not state constraints, format rules, or what happens if an invalid path is provided. Per pattern:constrained-input, descriptions should clarify valid formats.
Tool annotations use read_only_hint, destructive_hint, and open_world_hint, but the code references 'ToolAnnotations' without demonstrating support for idempotent_hint. For batch operations like zspace_move and zspace_copy (which can be retried), idempotent_hint would clarify retry safety. Current annotations are incomplete per the pattern.