cygnus-ssh-mcp

Official

by cygnussystems

Overview Schema Source Related Servers Discussions Admin

Python

Local

ssh_archive_create

Creates a compressed archive from a remote directory via SSH, supporting tar.gz and tar formats.

Instructions

Create a compressed archive from a directory.

IMPORTANT cross-platform caveat: on Windows, tar.gz/tar are NOT natively available - requesting either one silently creates a .zip file instead (via Compress-Archive), and archive_path's extension is auto-corrected to .zip if needed. The only way to tell this happened is the returned format field saying 'zip' even though you asked for tar.gz/tar. An archive created this way on Windows can only be extracted with ssh_archive_extract on another Windows host - Linux/macOS's extractor only recognizes .tar/.tar.gz/.tgz files, not .zip. There is no cross-platform-portable archive format currently available through this tool.

Returns: On success: {'status': 'success', 'success': True, 'archive_created' (the actual path used, which may differ from archive_path if the extension was corrected on Windows), 'format' (the ACTUAL format used - 'tar.gz'/'tar' on Linux/macOS, always 'zip' on Windows), 'size_bytes'}. On failure: {'status': 'error', 'message': str} - not a raised exception.

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	Default
`format`	No	Archive format	tar.gz
`use_sudo`	No	Use sudo for the operation
`source_path`	Yes	Directory to archive
`archive_path`	Yes	Path for the created archive

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.6/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 richly: it discloses the silent Windows format substitution, the archive_path extension auto-correction, that failures return an error dict rather than raising, and the long-running in_progress/handle_id contract with ssh_cmd_check_status polling plus the single-concurrent-operation 'busy' limit. This is behavior an agent cannot infer from schema or annotations.

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?

The purpose and the critical cross-platform caveat are front-loaded, and each caveat sentence carries distinct, actionable information. The 'Returns' block partially restates fields already covered by the output schema, which is the main source of redundancy.

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?

For a cross-platform archive tool with no annotations, the description covers the exact traps an agent needs: format degradation, extension correction, non-exception failure mode, and the async polling contract. Nothing required to invoke it 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that requesting tar.gz/tar on Windows actually yields zip and that archive_path may be auto-corrected. It says nothing extra about use_sudo, so it stops short of 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 ('Create a compressed archive from a directory'), which cleanly distinguishes it from the sibling ssh_archive_extract that does the inverse operation. An agent can identify the tool's job from the first line alone.

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

Usage Guidelines4/5

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

The Windows caveat effectively guides format selection by telling the agent that tar.gz/tar are silently degraded to zip and that no cross-platform-portable format exists, and it names ssh_archive_extract as the counterpart extractor. However, it never states plainly when to choose this tool over alternatives such as ssh_dir_transfer or ssh_cmd_run, so guidance is strong but implicit rather than explicit.

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

Deploy Server