@aaarc/handfree-ssh-mcp 1.0.4 → 1.0.6

package/README.md

@@ -113,9 +113,10 @@ The AI can now execute commands on your servers. All within your defined securit
 
 | Tool | Description |
 |------|-------------|
-| `execute-command` | Run SSH command (with optional `stream` for real-time output) |
-| `show-whitelist` | Show active command policy + SFTP policy + output-log path for a server |
-| `upload` | Upload local file to a remote server (CRLF-fix for shell scripts, skip-if-identical) |
+| `execute-command` | Run SSH command (with optional `stream` for real-time output) |
+| `show-whitelist` | Show active command policy + SFTP policy + output-log path for a server |
+| `close-connection` | Close a cached SSH connection for a server |
+| `upload` | Upload local file to a remote server (CRLF-fix for shell scripts, skip-if-identical) |
 | `download` | Download remote file to local disk |
 | `transfer` | Unified upload / download / server-to-server relay (`mode`: `upload` / `download` / `relay`, optional `recursive`, optional `skipIfIdentical`) |
 | `list-servers` | List configured (enabled) servers. Lean by default; `verbose:true` adds cached system status, `refresh:true` re-collects it (implies verbose). |
@@ -142,24 +143,41 @@ Returns command mode, built-in command guards, configured whitelist/blacklist pa
 {
   "tool": "execute-command",
   "params": {
-    "cmdString": "docker ps",
-    "connectionName": "dev",
-    "timeout": 300000,
-    "stream": true
-  }
-}
-```
+    "cmdString": "docker ps",
+    "connectionName": "dev",
+    "timeout": 300000,
+    "stream": true,
+    "reuseConnection": true,
+    "vvv": false
+  }
+}
+```
 
 | Param | Required | Default | Description |
 |-------|----------|---------|-------------|
 | `cmdString` | ✅ | - | Command to execute |
-| `connectionName` | ❌ | First in `--enable-servers` | Which server to run on |
-| `timeout` | ❌ | 300000ms (stream) / 30000ms (no stream) | Timeout in ms |
-| `stream` | ❌ | `true` | Real-time streaming output |
-
-**When to use `stream: false`:**
-- Simple, fast commands (ls, pwd, cat)
-- When you don't need real-time feedback
+| `connectionName` | ❌ | First in `--enable-servers` | Which server to run on |
+| `timeout` | ❌ | 300000ms (stream) / 30000ms (no stream) | Per-attempt phase timeout in ms. SSH setup, exec-channel opening, and remote command execution each use this cap. |
+| `stream` | ❌ | `true` | Real-time streaming output |
+| `reuseConnection` | ❌ | `true` | Reuse the cached SSH connection. Set `false` after a timeout or suspected stale cached connection to force a fresh TCP/SSH connection for this command. |
+| `vvv` | ❌ | `false` | Append bounded SSH/channel debug output. Use with `reuseConnection: false` when you need fresh ssh2 handshake logs. |
+
+**When to use `stream: false`:**
+- Simple, fast commands (ls, pwd, cat)
+- When you don't need real-time feedback
+
+### close-connection
+
+```json
+{
+  "tool": "close-connection",
+  "params": {
+    "connectionName": "dev"
+  }
+}
+```
+
+Closes the cached SSH client for a configured server. This is useful after a timeout or suspected stale reused connection when you want the next default `reuseConnection: true` command to reconnect cleanly. Closing a jump host also closes cached targets whose jump chain uses that host. `reuseConnection: false` commands do not need this because their one-shot SSH clients close after each command.
 
 ## 📄 YAML Config Reference
 
@@ -216,7 +234,8 @@ servers:
 
     # SFTP path policy — applies ONLY to upload / download / transfer.
     # execute-command is NOT affected by these lists.
-    # If `allowedRemoteDirectories` is unset or empty, SFTP is DISABLED for the server.
+    # Default is OPEN: with `allowedRemoteDirectories` unset/empty, any absolute
+    # POSIX remote path is allowed. Configure it to opt into an allowlist instead.
     allowedRemoteDirectories:
       - /home/user
       - /tmp
@@ -224,20 +243,23 @@ servers:
     # The MCP working directory is always permitted implicitly.
     allowedLocalDirectories:
       - /path/to/extra/local/dir
+    # Bypasses both the remote allowlist and the local directory check entirely.
+    # disableSftpPathPolicy: true
 ```
 
 ### Security note: command policy
 
-`execute-command` defaults to `commandMode: blacklist`. In that mode commands are allowed unless they match built-in destructive guards, the built-in dangerous-command blacklist, or a server's configured `blacklist:` patterns. Built-in blocked operations include hidden/chained destructive file operations, risky absolute-path output redirection, system power commands (`reboot`, `shutdown`, `halt`, `poweroff`), recursive force delete (`rm -rf`), destructive disk writes (`dd ... of=`), and filesystem formatting commands. Set `commandMode: whitelist` to require every command to match `whitelist:` after blacklist checks. For compatibility, a YAML server that contains `whitelist:` without `commandMode:` is treated as whitelist mode.
+`execute-command` defaults to `commandMode: blacklist`. In that mode commands are allowed unless they match built-in destructive guards, the built-in dangerous-command blacklist, or a server's configured `blacklist:` patterns. Built-in blocked operations include hidden/chained destructive file operations, risky absolute-path output redirection, system power commands (`reboot`, `shutdown`, `halt`, `poweroff`), recursive force delete (`rm -rf`), destructive disk writes (`dd ... of=`), and filesystem formatting commands. Set `commandMode: whitelist` to require every command to match `whitelist:` after blacklist checks. For compatibility, a YAML server that contains `whitelist:` without `commandMode:` is treated as whitelist mode. Set `disableBuiltinGuards: true` and/or `disableBuiltinBlacklist: true` to turn off the built-in guards/blacklist for a server (your own `blacklist:`/`whitelist:` still apply).
 
 ### SFTP path policy
 
 | Field | Scope | Default behavior |
 |---|---|---|
-| `allowedRemoteDirectories` | `upload` / `download` / `transfer` only | **Unset = SFTP disabled.** Must list absolute POSIX directories. |
+| `allowedRemoteDirectories` | `upload` / `download` / `transfer` only | **Unset/empty = open.** Any absolute POSIX path is allowed. Configuring this list opts into restricting SFTP to those directories. |
 | `allowedLocalDirectories` | `upload` / `download` only | Unset = only the MCP working directory is allowed. |
+| `disableSftpPathPolicy` | all SFTP tools | When `true`, bypasses both checks above entirely — any remote path, any local path. |
 
-Path matching is exact-equal or `dir + separator` prefix. `..` segments and null bytes are rejected. Use `show-whitelist` to inspect a server's current SFTP policy.
+Path matching (when an allowlist is configured) is exact-equal or `dir + separator` prefix. `..` segments and null bytes are always rejected regardless of policy. Use `show-whitelist` to inspect a server's current SFTP policy.
 
 ### Jump host (ProxyJump-style)
 
@@ -272,10 +294,14 @@ Rules (enforced at config load — bad configs fail fast):
 
 ### Connection lifecycle (connect / reconnect)
 
-- **Lazy by default.** A server's SSH client is created on its first tool call via `ensureConnected()`. Set `preConnect: true` (or pass `--pre-connect`) to open all enabled servers at startup in parallel; failures are logged but don't block startup.
-- **Auto-reconnect on `execute-command`.** Every command runs inside a retry loop (default 3 attempts: 1 initial + 2 retries) with exponential backoff. If the underlying error matches a connection-shaped pattern (`econnreset`, `epipe`, `socket`, `closed`, `channel`, `end of stream`, or a `SSH_CONNECTION_FAILED` ToolError), the manager closes the dead client, reconnects, and retries the command. Non-connection errors (permission denied, validation, command-not-found) are returned immediately without retry.
-- **SFTP transfers do NOT auto-retry.** `upload` / `download` / `transfer` lazy-connect via the same path, but a mid-transfer disconnect surfaces as a single failure — re-issue the call manually. This is a known gap.
-- **No background keepalive or health probe.** Dead connections are only discovered on the next tool call. If you idle for hours through a NATed network, expect the first call after the gap to fail-then-reconnect on its own (you'll see one retry in the logs).
+- **Lazy by default.** A server's SSH client is created on its first tool call via `ensureConnected()`. Set `preConnect: true` (or pass `--pre-connect`) to open all enabled servers at startup in parallel; failures are logged but don't block startup.
+- **Cached clients stay open while reused.** With the default `reuseConnection: true`, `execute-command` does not close the SSH client after each command. If a cached client must be opened first, SSH setup, jump, SOCKS, and channel-open waits are bounded by the call's `timeout`. The cached client is closed on explicit disconnect/server shutdown, config hot-reload for changed connection fields, underlying SSH close/error cleanup, or reconnect after a connection-shaped command failure.
+- **Manual cached-client close.** Use `close-connection { connectionName: "name" }` to drop a cached SSH client on demand. If the named server is a jump host, cached targets that jump through it are closed too.
+- **Auto-reconnect on `execute-command`.** Every command runs inside a retry loop (default 3 attempts: 1 initial + 2 retries) with exponential backoff. If the underlying error matches a connection-shaped pattern (`econnreset`, `epipe`, `socket`, `closed`, `channel`, `end of stream`, or a `SSH_CONNECTION_FAILED` ToolError), the manager closes the dead client, reconnects, and retries the command. Non-connection errors (permission denied, validation, command-not-found) are returned immediately without retry.
+- **Optional fresh command connections.** `execute-command` reuses the cached SSH client by default (`reuseConnection: true`). If a command times out or you suspect the cached `ssh2.Client` is stale while native `ssh` works, retry with `reuseConnection: false`; that command opens a fresh SSH connection and closes it afterwards.
+- **Optional SSH debug output.** Set `vvv: true` on `execute-command` to append bounded SSH/channel debug output to the result or error. For full ssh2 handshake logs, combine it with `reuseConnection: false`; an already-open cached client cannot retroactively emit handshake debug.
+- **SFTP transfers do NOT auto-retry.** `upload` / `download` / `transfer` lazy-connect via the same path, but a mid-transfer disconnect surfaces as a single failure — re-issue the call manually. This is a known gap.
+- **No background keepalive or health probe.** Dead connections are only discovered on the next tool call. If you idle for hours through a NATed network, expect the first call after the gap to fail-then-reconnect on its own (you'll see one retry in the logs).
 
 ### Upload behaviors
 

package/build/config/config-loader.js

@@ -163,6 +163,9 @@ function buildYamlServerConfig(name, serverConfig, options = {}) {
     if (serverConfig.allowedLocalDirectories !== undefined) {
         merged.allowedLocalDirectories = normalizeAllowedLocalDirectories(name, serverConfig.allowedLocalDirectories);
     }
+    if (serverConfig.disableSftpPathPolicy !== undefined) {
+        merged.disableSftpPathPolicy = serverConfig.disableSftpPathPolicy === true;
+    }
     if (!allowPartial) {
         Logger.log(`Loaded server config: ${name} -> ${merged.username}@${merged.host}:${merged.port}`, "info");
     }
@@ -183,6 +186,7 @@ function mergeConfigMaps(sshConfigs, yamlConfigs) {
             commandBlacklist: yamlConfig.commandBlacklist ?? merged[name]?.commandBlacklist,
             disableBuiltinGuards: yamlConfig.disableBuiltinGuards ?? merged[name]?.disableBuiltinGuards,
             disableBuiltinBlacklist: yamlConfig.disableBuiltinBlacklist ?? merged[name]?.disableBuiltinBlacklist,
+            disableSftpPathPolicy: yamlConfig.disableSftpPathPolicy ?? merged[name]?.disableSftpPathPolicy,
             safeDirectory: yamlConfig.safeDirectory ?? merged[name]?.safeDirectory,
         };
     }

package/build/config/server.js

@@ -1,6 +1,6 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.0.4",
+    version: "1.0.5",
 };
 export const SERVER_INSTRUCTIONS = `This server provides SSH access to servers loaded from OpenSSH config (~/.ssh/config by default) and optional YAML config/policy overlays.
 
@@ -10,12 +10,15 @@ Recommended workflow:
 3. Use execute-command for remote shell commands. Prefer a single command per call. Compound commands may be rejected by command policy even if each subcommand is individually safe.
 4. Use stream=false for short commands that should finish quickly, such as pwd, ls, cat, head, tail, git status, or docker ps.
 5. Use stream=true for commands that may take longer or where incremental output is useful.
-6. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
-7. Call help or help { tool: "<name>" } for detailed per-tool parameter docs and examples.
+6. execute-command reuses SSH connections by default. If an execute-command call times out, retry the next command with reuseConnection=false to bypass a potentially stale cached SSH connection.
+7. Use close-connection to close a cached SSH connection for a server before retrying with a clean reused connection. Closing a jump host also closes cached targets that jump through it.
+8. For SSH/channel diagnostics, add vvv=true. Use it with reuseConnection=false when you need fresh handshake/debug output.
+9. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
+10. Call help or help { tool: "<name>" } for detailed per-tool parameter docs and examples.
 
 Server targeting:
 - When only one server is enabled, connectionName can be omitted and the server is auto-selected.
-- When multiple servers are enabled, connectionName is REQUIRED on execute-command, upload, download, show-whitelist, and transfer (upload/download mode). Omitting it returns an error listing the available names.
+- When multiple servers are enabled, connectionName is REQUIRED on execute-command, close-connection, upload, download, show-whitelist, and transfer (upload/download mode). Omitting it returns an error listing the available names.
 
 Behavior notes:
 - A tool may automatically establish the SSH connection on first use.