cygnus-ssh-mcp

Official

by cygnussystems

Overview Schema Source Related Servers Discussions Admin

Python

Local

ssh_dir_mkdir

Create a directory on a remote Linux, macOS, or Windows system via SSH, with optional sudo and Unix permissions.

Instructions

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 Windows - there's no equivalent to Unix octal permissions there.

Returns: {'status': 'success', 'path', 'mode' (octal string - reflects the requested mode even on Windows, where it was actually ignored), 'message', 'connection'} on success. Raises an exception on failure (e.g. missing parent directory without sudo on Linux/macOS).

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
`mode`	No	Directory permissions (octal)
`path`	Yes	Directory path to create
`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.7/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 behavioral burden and does: non-recursive SFTP mkdir vs. sudo mkdir -p, Windows New-Item -Force semantics, mode being silently ignored on Windows, exception-on-failure, and the long-running handle/poll protocol including the single-concurrent-operation 'busy' constraint.

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 purpose and organized into scannable bullets, with no filler prose. It is somewhat long, and the bulleted return-value breakdown partially duplicates the existing output schema, which keeps it short of a 5.

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 platform-divergent mutation tool with an output schema, the description covers what an agent needs: platform/sudo matrix, failure mode, and the async handle handoff to ssh_cmd_check_status. Nothing required to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is already 100%, but the description adds real meaning beyond it: `mode` applies to the created directory, is ignored entirely on Windows, and `use_sudo` not only toggles sudo but changes recursion behavior and is a no-op on Windows.

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?

The opening sentence gives a precise verb and resource ('Create a directory on the remote system'), which is unmistakable against the delete/remove siblings in the tool list. An agent can identify the operation without opening the schema.

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?

It spells out the exact conditions under which the call succeeds or fails per platform and sudo flag, which is effectively usage guidance for invoking it correctly. It does not, however, name an alternative tool or state when to prefer another approach (e.g. batch creation via ssh_cmd_run).

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

Deploy Server