Cygnus SSH MCP

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>…

Calculate the total size of a directory recursively: the sum of the sizes of all regular files under it (directories' own sizes are not counted - same on every platform). On a 'linux' connection whose `find` lacks `-printf` (check `ssh_conn_connect`/ `ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running. Fallback: `ssh_cmd_run("du -sk <path>")` - kilobytes, and it includes directory overhead, but works on most BusyBox builds. Returns: `{'path', 'size_bytes' (int), 'size_human' (e.g. "1.23 MB", "512.00 KB", "3.50 GB" - 2 decimal places, binary/1024-based…

Copy a directory recursively (remote-to-remote; for local<->remote use ssh_dir_transfer instead). `overwrite` controls what happens if `destination_path` already exists: - `True`: the entire existing destination directory is deleted first, then a fresh copy is made. - `False` (default): does NOT block the copy - it copies into the existing destination as-is, merging with whatever's already there, and any file that shares a name with a source file gets silently overwritten anyway. This does NOT behave like the "fail if destination exists" semantics of ssh_file_move/ssh_file_copy's ow…

Delete a directory and all its contents recursively. `dry_run` DEFAULTS TO `True` - calling this with no arguments other than `path` only PREVIEWS what would be deleted and deletes NOTHING; you must explicitly pass `dry_run=False` to actually delete. Refuses to delete a small set of critical paths outright (root, home directory, `C:\Windows`, `C:\Users`, etc.) regardless of `dry_run`. For a simpler non-recursive removal without the preview step, see ssh_dir_remove. Returns: `{'status': 'success'/'error', 'deleted_items': [str, ...] (paths that were/would be removed, depth-first order…

List contents of a directory recursively with full metadata (size, permissions, ownership, modification time) - use this instead of ssh_dir_list_files_basic (which only returns bare filenames, non-recursive) when you need more than just names, or ssh_dir_search_glob when you only need to filter by filename pattern without full metadata (that tool is also faster for large trees). `max_depth` uses standard `find -maxdepth` semantics: `max_depth=1` means `path` itself plus its immediate children only; omit for unlimited recursion. On a 'linux'/'flex' connection with a limited BusyBox-style `fin…

List the immediate contents of a directory (via SFTP - not recursive, no metadata). For recursive listing with size/permissions/type/etc., or to filter by filename pattern, use ssh_dir_list_advanced or ssh_dir_search_glob instead. Returns: List of bare filenames (strings) directly inside `path` - not full paths, not recursive, and no indication of which entries are files vs. directories (use ssh_file_stat on an entry, or ssh_dir_list_advanced, if you need that).

Create a directory on the remote system. Parent-directory creation and `mode` behavior differ by platform/sudo: - Linux/macOS, `use_sudo=False` (default): uses SFTP `mkdir`, which is NOT recursive - this FAILS if the parent directory doesn't already exist. `mode` applies to the created directory. - Linux/macOS, `use_sudo=True`: uses `mkdir -p -m <mode>`, which DOES create any missing parent directories. - Windows: always creates missing parent directories (`New-Item -Force`, regardless of `use_sudo`, which has no effect on Windows anyway). The `mode` parameter is IGNORED entirely on…

Remove a directory on the remote system - this is the simple `rmdir`/`Remove-Item` equivalent. There is NO dry-run/preview mode here (unlike ssh_dir_delete below) - it acts immediately. If `recursive=False` (default) and the directory is not empty, this RAISES an exception rather than returning an error dict - it does not partially delete anything. For a safer recursive delete with a preview step, use ssh_dir_delete instead, which defaults to `dry_run=True` and returns a graceful `{'status': 'error', ...}` on failure instead of raising. Returns: `{'status': 'success', 'path', 'recursive'…

Recursively search file CONTENTS for a pattern under a directory (unlike ssh_dir_search_glob/ssh_file_find_lines_with_pattern, which match filenames or search within a single already-known file respectively). Regex flavor differs by platform when `regex=True`: POSIX extended regex (`grep -E`) on Linux/macOS - avoid PCRE-only syntax like `\d`, use `[0-9]` or `[[:digit:]]` instead; Python's `re` module on Windows. When `regex=False` (default), the pattern is matched as a literal fixed string. On Windows the whole search runs over SFTP (directory listings + raw file reads, matched locally), so …

Recursively search for files (or directories, with `include_dirs=True`) matching a filename glob pattern (e.g. `*.log`) - matches by NAME only, not content; use ssh_dir_search_files_content instead to search inside files. For metadata beyond just path/type (size, mtime, permissions), use ssh_dir_list_advanced instead. `max_depth` uses standard `find -maxdepth` semantics: this is the same on both Linux/macOS and Windows despite the different underlying commands. `max_depth=1` means the given `path` itself plus its immediate children only (not grandchildren); omit `max_depth` for unlimited recu…

Transfer directories between local and remote systems. Uses archive-based transfer for efficiency: - Upload: Archives locally, transfers, extracts on remote - Download: Archives on remote, transfers, extracts locally Archive format is automatically selected based on remote OS: - Linux/macOS: tar.gz - Windows: zip Where the files end up (check `files_location` in the result): - upload: the CONTENTS of local_path are placed directly in remote_path (local /x/proj/a.txt -> remote_path/a.txt) - download: the remote folder itself is placed inside local_path (remote /srv/proj/a.txt -> local_pa…

Copy a file on the remote host (source and destination are both remote paths - for local<->remote transfers use ssh_file_transfer instead). If `append_timestamp=True`, a timestamp is inserted before the destination's file extension in the format `%Y%m%dT%H%M%S`, e.g. `destination_path="/etc/hosts.bak"` becomes `/etc/hosts.20260704T153045.bak` - not appended after the extension, and not configurable to a different format. Returns: On success: `{'success': True, 'copied_to': <actual destination path used, including the timestamp if applied>}`. On failure (source not found, permissi…

Delete a line by its exact content. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing which line(s) to delete. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. (Equivalent to ssh_file_replace_line_multi(new_lines=[]), provided as a clearer-named shortcut.) Returns: On success: `{'success': True}` (no count field - only ever deletes the one matched line). On failure (match not found, match no…

Search for a pattern in a remote file and return matching lines with their line numbers. Use this to find WHERE a pattern occurs before using ssh_file_get_context_around_line to see surrounding lines, or ssh_file_replace_line/ssh_file_delete_line_by_content to edit (those require an exact, unique line match - this tool helps you find that exact line first). Regex flavor differs by platform when `regex=True`: POSIX extended regex (`grep -E`) on Linux/macOS - avoid PCRE-only syntax like `\d`, use `[0-9]` or `[[:digit:]]` instead; Python's `re` module on Windows (matched locally after an SFTP re…

Get lines before and after a line, to see it in context before editing. Like the line-editing tools (ssh_file_replace_line and siblings), `match_line` must match exactly one line in the file (whitespace-trimmed, literal text, not a pattern) - use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. Reads the file via SFTP and matches locally (same as ssh_file_find_lines_with_pattern) - Unicode/non-ASCII content is safe on all platforms, including Windows. Returns: On a unique match: `{'match_found': True, 'match_line_number': int, 'context_block': [{'line_num…

Insert one or more new lines immediately after a matching line. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. PARAMETERS: * file_path: Path to the file to modify * match_line: Exact line content to match (whitespace-trimmed) * lines_to_insert: List of lines to insert after the match - To insert multiple lines: use ["first line", "second line", …

Move or rename a file or directory (works for both - whichever `source` is). If `destination` already exists: fails cleanly with `overwrite=False` (default); with `overwrite=True`, it's replaced (`mv -f`/`Move-Item -Force`). If `source` doesn't exist, also fails cleanly rather than raising. Returns: `{'success': True, 'message': str}` on success, or `{'success': False, 'message': str}` on failure (source not found, destination exists and `overwrite=False`, permission error) - not a raised exception.

Read file contents directly via SFTP. This tool reads raw bytes from the remote file using SFTP and decodes them on the client side. Unlike command-based file reading (cat, Get-Content), SFTP completely bypasses shell and console encoding issues. **Why use this instead of ssh_cmd_run with cat/Get-Content?** - Works correctly with Unicode on ALL platforms including Windows - Bypasses Windows PowerShell's OEM code page encoding problem - More efficient for binary-safe file transfer - No shell escaping issues with special characters in content Returns: Dictionary with: - success: True …

Replace a line in a file with a new line. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing which line you meant. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. PARAMETERS: * file_path: Path to the file to modify * match_line: Exact line content to match and replace (whitespace-trimmed) * new_line: New line to insert in place of the match * use_sudo: Use sudo for the operation (default: false) * f…

Replace a line in a file with one or more new lines (or delete it, with an empty list). Use this instead of ssh_file_replace_line when you need to insert more than one line, or delete a line without using the separate ssh_file_delete_line_by_content tool. `match_line` must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique. PARAMETERS: * file_path: Path to the file to …

Get status information about a file or directory (via SFTP stat - works the same way on all platforms, no shell command involved). On Windows, `mode`/`uid`/`gid` come from the SFTP subsystem's own cross-platform attribute reporting, not real Windows ACLs/ownership - Windows has no equivalent concept, so these values (e.g. `uid`/`gid` of `0`) are not meaningful there and should not be relied on to reason about actual Windows permissions/ownership. `type`/`size`/`atime`/`mtime` are unaffected and accurate on all platforms. Returns: `{'exists': True, 'path', 'type' ('file'/'directory'/'syml…

Transfer a single FILE between the local machine (running this MCP server) and the remote host, via SFTP. Both `local_path` and `remote_path` must be file paths, not directories - for whole-directory transfers, use ssh_dir_transfer instead. For remote-to-remote copies (no local machine involved), use ssh_file_copy instead. Caveat: `use_sudo=True` on download/upload stages a copy through `/tmp/` using Unix shell commands (`mv`/`chmod`/`rm`) - this only works against Linux/macOS remote hosts. Windows has no per-command sudo concept anyway (see ssh_conn_verify_sudo), so `use_sudo=True` against a…

Create a new file, or overwrite/append to an existing one, with the given content (works the same whether or not the file already exists - `append=True` on a nonexistent file just creates it). Handles special characters and multi-line content properly. `mode` (Unix permission bits) is applied via a `chmod` command after writing - this only works on Linux/macOS. On Windows there's no equivalent, so `mode` is silently ignored there (same convention as `ssh_dir_mkdir`'s `mode` parameter). Returns: On success: `{'success': True, 'file_path', 'bytes_written' (int), 'mode' (octal string, o…

Disconnect the current SSH connection if one exists. Use this when you want to explicitly close the current SSH connection before connecting to a different host or when you're done with SSH operations. Returns: Dictionary with disconnection status

List all configured SSH hosts with their aliases and descriptions. This is the ONLY correct way to see what hosts are configured - never read the host configuration TOML file directly (ssh_conn_add_host's docstring names its path). That file stores every host's password, sudo password, and key passphrase in plaintext; this tool deliberately omits all of that and returns only the fields below. If you need to add, change, or remove a host, use ssh_conn_add_host, ssh_host_update, or ssh_host_remove instead of editing the file - between those and ssh_host_use_config, there is no legitimate reason …

Remove a host configuration from the host configuration TOML file (see ssh_conn_add_host's docstring for its exact path and why you should never read it directly - use ssh_host_list to see what's configured instead). To change a host's password/port/etc. rather than deleting it, use ssh_host_update instead - removing and re-adding loses every field you don't explicitly resupply. Returns: Dictionary with operation status

Update one or more fields of an existing host configuration - this is the safe way to rotate a password, change a port, or adjust other settings without ever needing to read or hand-edit the host configuration TOML file (which stores every host's credentials in plaintext - never read it directly; this tool, ssh_conn_add_host, ssh_host_remove, and ssh_host_list cover everything you should need). Only the fields you pass are changed - any parameter left at its default (omitted/`None`) keeps its current value. To clear a field entirely (e.g. drop a password when switching a host to key-only auth…

Switch which host configuration file ssh_host_list, ssh_conn_connect, ssh_conn_add_host, ssh_host_update, and ssh_host_remove all operate against, for the rest of this session (or until you call this again) - not just for one call. This is the same "one active thing at a time" model ssh_conn_connect uses for SSH connections, applied to host configuration files instead; the two are completely independent (switching config files doesn't affect any current SSH connection, and vice versa). Use this when you want to browse or use hosts from a different TOML file than the server's default - e.g. a …

Terminate a background task (launched via ssh_task_launch, or any other real remote PID) by sending a signal to its PID. If force=True and the process doesn't exit after wait_seconds, it will be forcibly killed with SIGKILL (signal 9). With `use_sudo=True` on a 'linux'/'flex' connection with a BusyBox-style `ps` that doesn't support `-o pgid=` (check `ssh_conn_connect`/ `ssh_conn_host_info`'s `capabilities`), this raises a clear error instead of running - there is no clean fallback, since killing just the captured PID (rather than its whole process group) can leave the sudo'd command's real …

Launch a command in the background and return its PID immediately, without waiting for it to complete. Prefer this over ssh_cmd_run for commands that will take a long time or may be quiet for extended periods: package installs, container/image pulls, large downloads, backups, compilation. It avoids holding a blocking tool call open and the ambiguity of io_timeout - the PID it returns survives reconnects and can be checked anytime with ssh_task_status(pid), and stdout_log/stderr_log can be read with ssh_file_read while the task is still running. Output is redirected to files (see stdout_log/s…

Check the liveness of a background task by PID (from ssh_task_launch, or any other real remote PID - e.g. the `pid` field from ssh_cmd_run). This does a live check on the remote host every call, not a cached lookup, so it's safe to call repeatedly. Returns: `{'pid', 'status', 'running' (bool, True iff status=='running'), 'timestamp'}`. `status` is one of: - 'running': the process currently exists. - 'exited': the process is gone - it either completed or was killed; there's no way to distinguish which, or recover its exit code, from this tool alone. - 'invalid': the g…