cygnus-ssh-mcp

Official

Overview Schema Source Related Servers Discussions Admin

ssh_dir_batch_delete_files

Recursively delete files matching a glob pattern under a remote directory via SSH. Preview deletions by default for safety.

Instructions

Recursively find and delete files matching a filename glob pattern (same pattern syntax as ssh_dir_search_glob, e.g. *.tmp) under a directory. dry_run DEFAULTS TO True - calling this with no arguments other than path/pattern only PREVIEWS which files would be deleted and deletes NOTHING; you must explicitly pass dry_run=False to actually delete.

On a 'linux'/'flex' connection with a BusyBox-style xargs that doesn't support -0 (check ssh_conn_connect/ssh_conn_host_info's capabilities), this raises a clear error instead of running. Fallback: ssh_cmd_run with find <path> -name '<pattern>' -exec rm -f {} + instead - portable, and still safe with spaces in filenames.

Returns: {'status': 'success'/'error', 'deleted_files': [str, ...] (matching file paths that were/would be deleted)}, plus 'dry_run': True ONLY when this was a preview (check for this key to tell a preview apart from a real deletion) and 'error' (string) on failure. Note the key is deleted_files here, vs. deleted_items on ssh_dir_delete.

Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	Yes	Base directory to search in
`dry_run`	No	Preview deletion without actually deleting
`pattern`	Yes	File pattern to match for deletion (e.g. *.tmp)
`use_sudo`	No	Use sudo for the operation

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.3.0May 28, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it discloses the dry_run safety default, the BusyBox error condition with a capabilities check, the in_progress/handle_id behavior past the 50s wait cap, polling via ssh_cmd_check_status, and the 'busy' failure mode. These are exactly the behavioral traits an agent cannot infer from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the safety-critical dry_run default, then layered with fallback and long-running details. It is long, but nearly every sentence is operationally load-bearing; the Returns block is slightly verbose relative to the existing output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a destructive mutation tool with no annotations, 4 parameters, and a long-running mode, the description covers safety defaults, failure modes, fallbacks, polling, and result-shape differences. Nothing material an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3; the description adds real meaning on top by spelling out that dry_run defaults to True and only previews, that pattern uses ssh_dir_search_glob syntax, and that path is the base search directory. It stops short of describing use_sudo semantics, so not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('recursively find and delete files matching a filename glob pattern') and immediately differentiates from siblings by referencing ssh_dir_search_glob's pattern syntax and contrasting the return key with ssh_dir_delete's `deleted_items`. An agent can identify this tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the dry_run default and the consequence of omitting it (preview only, nothing deleted), names the fallback path (ssh_cmd_run with find -exec rm -f) for BusyBox xargs without -0, and explains the long-running polling workflow and the one-at-a-time constraint. When-to-use and when-to-substitute are both covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server