@aaarc/handfree-ssh-mcp 1.0.5 → 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
 
@@ -276,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/server.js

@@ -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.

package/build/services/ssh-connection-manager.js

@@ -41,6 +41,7 @@ export const BUILT_IN_DESTRUCTIVE_GUARDS = [
  */
 export class SSHConnectionManager {
     static instance;
+    static CLOSED_CLIENT_ERROR_SINK = () => { };
     clients = new Map();
     configs = {};
     connected = new Map();
@@ -196,6 +197,27 @@ export class SSHConnectionManager {
         this.connected.set(name, false);
         this.connecting.delete(name);
     }
+    closeConnection(name) {
+        const key = this.resolveServer(name);
+        this.getConfig(key);
+        const affected = new Set([key]);
+        const changed = new Set([key]);
+        for (const target of Object.keys(this.configs)) {
+            if (target === key)
+                continue;
+            if (this.jumpChainTouchesChanged(target, this.configs, changed)) {
+                affected.add(target);
+            }
+        }
+        for (const target of affected) {
+            this.closeClient(target, true);
+            this.statusCache.delete(target);
+        }
+        return {
+            requested: key,
+            closed: Array.from(affected),
+        };
+    }
     bumpConnectionGeneration(name) {
         this.connectionGenerations.set(name, (this.connectionGenerations.get(name) ?? 0) + 1);
     }
@@ -278,7 +300,7 @@ export class SSHConnectionManager {
      * Concurrent callers for the same server share a single in-flight promise,
      * so we never create two SSH clients and leak the loser.
      */
-    async connect(name) {
+    async connect(name, timeout) {
         const key = name || this.defaultName;
         if (this.connected.get(key) && this.clients.get(key)) {
             return;
@@ -287,21 +309,25 @@ export class SSHConnectionManager {
         if (inFlight) {
             return inFlight;
         }
-        const promise = this.doConnect(key).finally(() => {
-            this.connecting.delete(key);
+        let trackedPromise;
+        trackedPromise = this.doConnect(key, timeout).finally(() => {
+            if (this.connecting.get(key) === trackedPromise) {
+                this.connecting.delete(key);
+            }
         });
-        this.connecting.set(key, promise);
-        return promise;
+        this.connecting.set(key, trackedPromise);
+        return trackedPromise;
     }
     /**
      * Actual SSH connect implementation. Callers must go through `connect()`
      * so concurrent requests are deduped.
      * @private
      */
-    async doConnect(key) {
+    async doConnect(key, timeout) {
         const config = this.getConfig(key);
         const client = new Client();
         const generation = this.connectionGenerations.get(key) ?? 0;
+        const connectTimeout = this.normalizeConnectTimeout(timeout);
         this.pendingClients.set(key, client);
         try {
             await new Promise(async (resolve, reject) => {
@@ -357,6 +383,9 @@ export class SSHConnectionManager {
                     port: config.port,
                     username: config.username,
                 };
+                if (connectTimeout) {
+                    sshConfig.readyTimeout = connectTimeout;
+                }
                 const agent = config.agent === false
                     ? undefined
                     : config.agent || (config.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
@@ -367,7 +396,15 @@ export class SSHConnectionManager {
                 // (enforced at config load time).
                 if (config.jumpHost) {
                     try {
-                        const sock = await this.openJumpTunnel(key, config);
+                        const sock = await this.withConnectionTimeout(this.openJumpTunnel(key, config, undefined, connectTimeout), connectTimeout, `jump tunnel for [${key}] via '${config.jumpHost}'`, undefined, () => this.teardownJumpChain(key), (stream) => {
+                            try {
+                                stream.destroy?.();
+                            }
+                            catch {
+                                // Ignore late stream cleanup errors.
+                            }
+                            this.teardownJumpChain(key);
+                        });
                         sshConfig.sock = sock;
                         Logger.log(`Using jump host '${config.jumpHost}' for [${key}]`, "info");
                     }
@@ -390,7 +427,7 @@ export class SSHConnectionManager {
                         const proxyPort = parseInt(proxyUrl.port, 10);
                         Logger.log(`Using SOCKS proxy for [${key}]: ${config.socksProxy}`, "info");
                         // Create SOCKS connection
-                        const { socket } = await SocksClient.createConnection({
+                        const { socket } = await this.withConnectionTimeout(SocksClient.createConnection({
                             proxy: {
                                 host: proxyHost,
                                 port: proxyPort,
@@ -401,6 +438,14 @@ export class SSHConnectionManager {
                                 host: config.host,
                                 port: config.port,
                             },
+                            timeout: connectTimeout,
+                        }), connectTimeout, `SOCKS proxy connection for [${key}]`, undefined, undefined, (event) => {
+                            try {
+                                event.socket.destroy();
+                            }
+                            catch {
+                                // Ignore late socket cleanup errors.
+                            }
                         });
                         // Set the socket as the sock for SSH connection
                         sshConfig.sock = socket;
@@ -451,6 +496,212 @@ export class SSHConnectionManager {
         }
         this.clients.set(key, client);
     }
+    /**
+     * Open a one-shot SSH client for a single execute-command call.
+     * Used when the caller disables connection reuse after a timeout or when a
+     * fresh TCP/SSH handshake is more important than latency.
+     */
+    async connectCommandClient(key, timeout, debug) {
+        const config = this.getConfig(key);
+        const client = new Client();
+        const jumpChainKey = `__command__:${key}:${Date.now()}:${crypto.randomBytes(4).toString("hex")}`;
+        const connectTimeout = this.normalizeConnectTimeout(timeout) ?? 30000;
+        let settled = false;
+        let closed = false;
+        const onLateError = (err) => {
+            if (!settled) {
+                return;
+            }
+            debug?.(`[mcp] one-shot SSH client emitted error after ready/settle: ${err.message}`);
+            Logger.log(`One-shot SSH command client [${key}] emitted error after settle: ${err.message}`, "error");
+        };
+        client.on("error", onLateError);
+        const close = () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            client.on("error", SSHConnectionManager.CLOSED_CLIENT_ERROR_SINK);
+            client.removeListener("error", onLateError);
+            try {
+                client.end();
+            }
+            catch {
+                // Ignore close errors for per-command clients.
+            }
+            this.connected.delete(jumpChainKey);
+            this.connecting.delete(jumpChainKey);
+            this.teardownJumpChain(jumpChainKey);
+        };
+        try {
+            const sshConfig = {
+                host: config.host,
+                port: config.port,
+                username: config.username,
+                readyTimeout: connectTimeout,
+            };
+            if (debug) {
+                sshConfig.debug = (line) => debug(`[ssh2] ${line}`);
+            }
+            const agent = config.agent === false
+                ? undefined
+                : config.agent || (config.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
+            if (agent) {
+                sshConfig.agent = agent;
+            }
+            if (config.jumpHost) {
+                try {
+                    sshConfig.sock = await this.withConnectionTimeout(this.openJumpTunnel(jumpChainKey, config, debug, connectTimeout), connectTimeout, `one-shot jump tunnel for [${key}] via '${config.jumpHost}'`, debug, () => this.teardownJumpChain(jumpChainKey), (stream) => {
+                        try {
+                            stream.destroy?.();
+                        }
+                        catch {
+                            // Ignore late stream cleanup errors.
+                        }
+                        this.teardownJumpChain(jumpChainKey);
+                    });
+                    Logger.log(`Using one-shot jump host '${config.jumpHost}' for command on [${key}]`, "info");
+                }
+                catch (err) {
+                    this.teardownJumpChain(jumpChainKey);
+                    throw new ToolError("SSH_CONNECTION_FAILED", `Failed to open one-shot jump tunnel for [${key}] via '${config.jumpHost}': ${err.message}`, true);
+                }
+            }
+            if (config.socksProxy) {
+                try {
+                    const proxyUrl = new URL(config.socksProxy);
+                    const { socket } = await this.withConnectionTimeout(SocksClient.createConnection({
+                        proxy: {
+                            host: proxyUrl.hostname,
+                            port: parseInt(proxyUrl.port, 10),
+                            type: 5,
+                        },
+                        command: "connect",
+                        destination: {
+                            host: config.host,
+                            port: config.port,
+                        },
+                        timeout: connectTimeout,
+                    }), connectTimeout, `SOCKS proxy connection for one-shot command [${key}]`, debug, undefined, (event) => {
+                        try {
+                            event.socket.destroy();
+                        }
+                        catch {
+                            // Ignore late socket cleanup errors.
+                        }
+                    });
+                    sshConfig.sock = socket;
+                }
+                catch (err) {
+                    throw new ToolError("SSH_CONNECTION_FAILED", `Failed to create SOCKS proxy connection for one-shot command [${key}]: ${err.message}`, true);
+                }
+            }
+            if (config.privateKey) {
+                try {
+                    sshConfig.privateKey = fs.readFileSync(config.privateKey, "utf8");
+                    if (config.passphrase) {
+                        sshConfig.passphrase = config.passphrase;
+                    }
+                }
+                catch (err) {
+                    throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read private key file for [${key}]: ${err.message}`, false);
+                }
+            }
+            else if (config.password) {
+                sshConfig.password = config.password;
+            }
+            else if (agent || config.authOptional) {
+                Logger.log(`Using SSH agent/default authentication for one-shot command [${key}]`, "info");
+            }
+            else {
+                throw new ToolError("SSH_AUTHENTICATION_MISSING", `No valid authentication method provided for [${key}] (password or private key)`, false);
+            }
+            await new Promise((resolve, reject) => {
+                const done = (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timeoutId);
+                    client.removeListener("ready", onReady);
+                    client.removeListener("error", onError);
+                    client.removeListener("close", onClose);
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                };
+                const onReady = () => done();
+                const onError = (err) => done(new ToolError("SSH_CONNECTION_FAILED", `SSH command connection [${key}] failed: ${err.message}`, true));
+                const onClose = () => done(new ToolError("SSH_CONNECTION_FAILED", `SSH command connection [${key}] closed before ready`, true));
+                const timeoutId = setTimeout(() => {
+                    done(new ToolError("SSH_CONNECTION_FAILED", `SSH command connection [${key}] timed out after ${connectTimeout}ms`, true));
+                    close();
+                }, connectTimeout);
+                debug?.(`[mcp] opening one-shot SSH connection for [${key}]`);
+                client.once("ready", onReady);
+                client.once("error", onError);
+                client.once("close", onClose);
+                client.connect(sshConfig);
+            });
+            Logger.log(`Opened one-shot SSH command connection for [${key}]`, "info");
+            return { client, close };
+        }
+        catch (err) {
+            close();
+            throw err;
+        }
+    }
+    withConnectionTimeout(operation, timeoutMs, description, debug, onTimeout, onLateResolve) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return operation;
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timedOut = false;
+            const timeoutId = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                timedOut = true;
+                debug?.(`[mcp] ${description} timed out after ${timeoutMs}ms`);
+                try {
+                    onTimeout?.();
+                }
+                catch {
+                    // Ignore cleanup failures after timeout.
+                }
+                reject(new ToolError("SSH_CONNECTION_FAILED", `${description} timed out after ${timeoutMs}ms`, true));
+            }, timeoutMs);
+            operation.then((value) => {
+                if (timedOut) {
+                    try {
+                        onLateResolve?.(value);
+                    }
+                    catch {
+                        // Ignore cleanup failures for a late result.
+                    }
+                    return;
+                }
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                resolve(value);
+            }, (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                reject(err);
+            });
+        });
+    }
+    normalizeConnectTimeout(timeout) {
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            return undefined;
+        }
+        return Math.max(1, Math.min(timeout, 30000));
+    }
     /**
      * Open a TCP tunnel from the target's jump chain to `config.host:config.port`
      * and return the duplex stream to be used as `sock` for the target SSH client.
@@ -466,12 +717,12 @@ export class SSHConnectionManager {
      * calls against a bastion stay isolated.
      * @private
      */
-    async openJumpTunnel(targetKey, config) {
+    async openJumpTunnel(targetKey, config, debug, timeout) {
         // Tear down any stale jump chain for this target before opening a new one.
         this.teardownJumpChain(targetKey);
         this.jumpClients.set(targetKey, []);
-        const jumpClient = await this.connectJumpChain(targetKey, config.jumpHost);
-        return this.forwardOutStream(jumpClient, config.host, config.port);
+        const jumpClient = await this.connectJumpChain(targetKey, config.jumpHost, debug, timeout);
+        return this.forwardOutStream(jumpClient, config.host, config.port, timeout);
     }
     /**
      * Recursively connect the SSH client for `jumpName`, tunneling through its own
@@ -479,7 +730,7 @@ export class SSHConnectionManager {
      * to the target's jump-client chain. Returns the connected client for this hop.
      * @private
      */
-    async connectJumpChain(targetKey, jumpName) {
+    async connectJumpChain(targetKey, jumpName, debug, timeout) {
         const jumpConfig = this.configs[jumpName];
         if (!jumpConfig) {
             // Should be caught at config load, but guard at runtime too.
@@ -489,10 +740,10 @@ export class SSHConnectionManager {
         // tunnel first and hand its stream to this hop as `sock`.
         let sock;
         if (jumpConfig.jumpHost) {
-            const innerClient = await this.connectJumpChain(targetKey, jumpConfig.jumpHost);
-            sock = await this.forwardOutStream(innerClient, jumpConfig.host, jumpConfig.port);
+            const innerClient = await this.connectJumpChain(targetKey, jumpConfig.jumpHost, debug, timeout);
+            sock = await this.forwardOutStream(innerClient, jumpConfig.host, jumpConfig.port, timeout);
         }
-        const jumpClient = await this.connectJumpClient(targetKey, jumpName, jumpConfig, sock);
+        const jumpClient = await this.connectJumpClient(targetKey, jumpName, jumpConfig, sock, debug, timeout);
         const chain = this.jumpClients.get(targetKey);
         if (chain) {
             chain.push(jumpClient);
@@ -508,14 +759,57 @@ export class SSHConnectionManager {
      * chain down so a dead hop surfaces as a clear failure on the next op.
      * @private
      */
-    connectJumpClient(targetKey, jumpName, jumpConfig, sock) {
+    connectJumpClient(targetKey, jumpName, jumpConfig, sock, debug, timeout) {
         return new Promise((resolve, reject) => {
             const jumpClient = new Client();
-            jumpClient.on("ready", () => resolve(jumpClient));
-            jumpClient.on("error", (err) => {
-                reject(new Error(`jump SSH connect failed for '${jumpName}': ${err.message}`));
-            });
+            let settled = false;
+            let timeoutId = null;
+            let closedErrorSinkInstalled = false;
+            const installClosedErrorSink = () => {
+                if (!closedErrorSinkInstalled) {
+                    closedErrorSinkInstalled = true;
+                    jumpClient.on("error", SSHConnectionManager.CLOSED_CLIENT_ERROR_SINK);
+                }
+            };
+            const onLateError = (err) => {
+                Logger.log(`Jump SSH client '${jumpName}' for [${targetKey}] emitted error after ready: ${err.message}`, "error");
+                this.teardownTargetViaJump(targetKey);
+            };
+            const cleanup = () => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                jumpClient.removeListener("ready", onReady);
+                jumpClient.removeListener("error", onError);
+            };
+            const done = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (err) {
+                    installClosedErrorSink();
+                    reject(err);
+                    return;
+                }
+                jumpClient.on("error", onLateError);
+                resolve(jumpClient);
+            };
+            const onReady = () => done();
+            const onError = (err) => {
+                done(new Error(`jump SSH connect failed for '${jumpName}': ${err.message}`));
+            };
+            jumpClient.on("ready", onReady);
+            jumpClient.on("error", onError);
             jumpClient.on("close", () => {
+                if (!settled) {
+                    done(new Error(`jump SSH connect closed for '${jumpName}' before ready`));
+                    return;
+                }
+                jumpClient.removeListener("error", onError);
+                jumpClient.removeListener("error", onLateError);
+                installClosedErrorSink();
                 // If any hop dies, kill the target too so callers get a clear failure on
                 // the next op and reconnect through a fresh chain.
                 this.teardownTargetViaJump(targetKey);
@@ -528,6 +822,21 @@ export class SSHConnectionManager {
             if (sock) {
                 jumpSsh.sock = sock;
             }
+            if (timeout) {
+                jumpSsh.readyTimeout = timeout;
+                timeoutId = setTimeout(() => {
+                    done(new Error(`jump SSH connect timed out for '${jumpName}' after ${timeout}ms`));
+                    try {
+                        jumpClient.end();
+                    }
+                    catch {
+                        // Ignore close errors after timeout.
+                    }
+                }, timeout);
+            }
+            if (debug) {
+                jumpSsh.debug = (line) => debug(`[ssh2:${jumpName}] ${line}`);
+            }
             const jumpAgent = jumpConfig.agent === false
                 ? undefined
                 : jumpConfig.agent || (jumpConfig.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
@@ -560,12 +869,39 @@ export class SSHConnectionManager {
      * Open a forwarded TCP stream from `client` to `host:port`.
      * @private
      */
-    forwardOutStream(client, host, port) {
+    forwardOutStream(client, host, port, timeout) {
         return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId = null;
+            const done = (err, stream) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve(stream);
+            };
+            if (timeout) {
+                timeoutId = setTimeout(() => {
+                    done(new Error(`forwardOut to ${host}:${port} timed out after ${timeout}ms`));
+                }, timeout);
+            }
             client.forwardOut("127.0.0.1", 0, host, port, (err, ch) => {
-                if (err)
-                    return reject(err);
-                resolve(ch);
+                if (settled) {
+                    try {
+                        ch?.close();
+                    }
+                    catch {
+                        // Ignore cleanup failures for a late forwarded channel.
+                    }
+                    return;
+                }
+                done(err, ch);
             });
         });
     }
@@ -622,10 +958,11 @@ export class SSHConnectionManager {
      * Ensure SSH client is connected
      * @private
      */
-    async ensureConnected(name) {
+    async ensureConnected(name, timeout) {
         const key = name || this.defaultName;
         if (!this.connected.get(key) || !this.clients.get(key)) {
-            await this.connect(key);
+            const connectTimeout = this.normalizeConnectTimeout(timeout);
+            await this.withConnectionTimeout(this.connect(key, timeout), connectTimeout, `cached SSH connection [${key}]`, undefined, () => this.closeClient(key, true));
         }
         const client = this.clients.get(key);
         if (!client) {
@@ -641,7 +978,10 @@ export class SSHConnectionManager {
         if (error instanceof ToolError) {
             return error.code === "SSH_CONNECTION_FAILED";
         }
-        const msg = error.message.toLowerCase();
+        return this.isConnectionShapedMessage(error.message);
+    }
+    isConnectionShapedMessage(message) {
+        const msg = message.toLowerCase();
         return (msg.includes("not connected") ||
             msg.includes("connection") ||
             msg.includes("socket") ||
@@ -650,7 +990,9 @@ export class SSHConnectionManager {
             msg.includes("epipe") ||
             msg.includes("closed") ||
             msg.includes("end of stream") ||
-            msg.includes("channel"));
+            msg.includes("channel") ||
+            msg.includes("no response from server") ||
+            msg.includes("timed out"));
     }
     /**
      * Force reconnect to SSH server
@@ -918,54 +1260,107 @@ export class SSHConnectionManager {
      */
     async runCommandStream(cmdString, client, timeout, sinks) {
         return new Promise((resolve, reject) => {
-            let timeoutId;
+            let timeoutId = null;
+            let settled = false;
             const cleanup = () => {
-                if (timeoutId)
+                if (timeoutId) {
                     clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
             };
-            client.exec(cmdString, (err, stream) => {
-                if (err) {
-                    cleanup();
-                    reject(new ToolError("COMMAND_EXECUTION_ERROR", `Command execution error: ${err.message}`, false));
+            const settle = (err, code) => {
+                if (settled)
                     return;
-                }
-                stream.on("data", (chunk) => {
-                    sinks.stdoutCollector?.push(chunk);
-                    sinks.logWriter?.appendStdout(chunk);
-                    if (sinks.onProgress)
-                        sinks.onProgress(chunk.toString());
-                });
-                stream.stderr.on("data", (chunk) => {
-                    sinks.stderrCollector?.push(chunk);
-                    sinks.logWriter?.appendStderr(chunk);
-                    if (sinks.onProgress)
-                        sinks.onProgress(`[STDERR] ${chunk.toString()}`);
-                });
-                stream.on("close", (code) => {
-                    cleanup();
+                settled = true;
+                cleanup();
+                if (err)
+                    reject(err);
+                else
                     resolve(code ?? null);
-                });
-                stream.on("error", (err) => {
-                    cleanup();
-                    reject(new ToolError("COMMAND_EXECUTION_ERROR", `Stream error: ${err.message}`, false));
-                });
+            };
+            const closeLateStream = (stream) => {
+                try {
+                    stream.close();
+                }
+                catch {
+                    // Ignore late-stream close errors after the promise has settled.
+                }
+            };
+            const armExecOpenTimeout = () => {
+                const execOpenTimeout = Math.max(1, Math.min(timeout, 30000));
                 timeoutId = setTimeout(() => {
-                    cleanup();
+                    sinks.debug?.(`[mcp] exec channel open timed out after ${execOpenTimeout}ms`);
+                    settle(new ToolError("SSH_CONNECTION_FAILED", `SSH exec channel timeout: no response from server within ${execOpenTimeout}ms while opening command channel`, true));
+                }, execOpenTimeout);
+            };
+            const armCommandTimeout = (stream) => {
+                timeoutId = setTimeout(() => {
+                    sinks.debug?.(`[mcp] remote command timed out after ${timeout}ms; closing command channel`);
+                    settle(new ToolError("COMMAND_TIMEOUT", `Command timeout: execution exceeded ${timeout}ms limit. Remote process killed.`, false));
                     try {
                         stream.signal("KILL");
                     }
-                    catch (e) {
-                        // Ignore errors when sending signal
+                    catch {
+                        // Ignore errors when sending signal.
                     }
                     try {
                         stream.close();
                     }
-                    catch (e) {
-                        // Ignore errors when closing streams during timeout
+                    catch {
+                        // Ignore errors when closing streams during timeout.
                     }
-                    reject(new ToolError("COMMAND_TIMEOUT", `Command timeout: execution exceeded ${timeout}ms limit. Remote process killed.`, false));
                 }, timeout);
-            });
+            };
+            armExecOpenTimeout();
+            sinks.debug?.(`[mcp] opening exec channel for command: ${cmdString}`);
+            try {
+                client.exec(cmdString, (err, stream) => {
+                    if (settled) {
+                        if (stream)
+                            closeLateStream(stream);
+                        return;
+                    }
+                    if (err) {
+                        const isConnectionFailure = this.isConnectionShapedMessage(err.message);
+                        const code = isConnectionFailure ? "SSH_CONNECTION_FAILED" : "COMMAND_EXECUTION_ERROR";
+                        sinks.debug?.(`[mcp] exec callback failed: ${err.message}`);
+                        settle(new ToolError(code, `Command execution error: ${err.message}`, isConnectionFailure));
+                        return;
+                    }
+                    cleanup();
+                    sinks.debug?.("[mcp] exec channel opened");
+                    stream.on("data", (chunk) => {
+                        sinks.stdoutCollector?.push(chunk);
+                        sinks.logWriter?.appendStdout(chunk);
+                        if (sinks.onProgress)
+                            sinks.onProgress(chunk.toString());
+                    });
+                    stream.stderr.on("data", (chunk) => {
+                        sinks.stderrCollector?.push(chunk);
+                        sinks.logWriter?.appendStderr(chunk);
+                        if (sinks.onProgress)
+                            sinks.onProgress(`[STDERR] ${chunk.toString()}`);
+                    });
+                    stream.on("close", (code) => {
+                        sinks.debug?.(`[mcp] exec channel closed with code ${code ?? "null"}`);
+                        settle(null, code ?? null);
+                    });
+                    stream.on("error", (err) => {
+                        const isConnectionFailure = this.isConnectionShapedMessage(err.message);
+                        const code = isConnectionFailure ? "SSH_CONNECTION_FAILED" : "COMMAND_EXECUTION_ERROR";
+                        sinks.debug?.(`[mcp] exec stream error: ${err.message}`);
+                        settle(new ToolError(code, `Stream error: ${err.message}`, isConnectionFailure));
+                    });
+                    armCommandTimeout(stream);
+                });
+            }
+            catch (err) {
+                const error = err;
+                const isConnectionFailure = this.isConnectionShapedMessage(error.message);
+                const code = isConnectionFailure ? "SSH_CONNECTION_FAILED" : "COMMAND_EXECUTION_ERROR";
+                sinks.debug?.(`[mcp] client.exec threw before callback: ${error.message}`);
+                settle(new ToolError(code, `Command execution error: ${error.message}`, isConnectionFailure));
+            }
         });
     }
     /**
@@ -974,6 +1369,45 @@ export class SSHConnectionManager {
      * full output is always persisted to disk regardless of this cap.
      */
     static DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+    static DEFAULT_DEBUG_BYTES = 64 * 1024;
+    createDebugCollector(enabled) {
+        if (!enabled) {
+            return { collector: null };
+        }
+        const collector = new OutputCollector(SSHConnectionManager.DEFAULT_DEBUG_BYTES);
+        return {
+            collector,
+            debug: (line) => {
+                collector.push(`${line}\n`);
+            },
+        };
+    }
+    appendDebugOutput(result, collector) {
+        if (!collector || collector.getTotalBytes() === 0) {
+            return result;
+        }
+        const snapshot = collector.getSnapshot();
+        const header = snapshot.truncated
+            ? `[SSH DEBUG TRUNCATED: dropped ${snapshot.droppedBytes} bytes]\n`
+            : "[SSH DEBUG]\n";
+        return `${result}\n\n${header}${snapshot.tail.toString("utf8").trimEnd()}`;
+    }
+    appendDebugToError(error, collector) {
+        if (!collector || collector.getTotalBytes() === 0) {
+            return error;
+        }
+        const snapshot = collector.getSnapshot();
+        const header = snapshot.truncated
+            ? `[SSH DEBUG TRUNCATED: dropped ${snapshot.droppedBytes} bytes]\n`
+            : "[SSH DEBUG]\n";
+        const message = `${error.message}\n\n${header}${snapshot.tail.toString("utf8").trimEnd()}`;
+        if (error instanceof ToolError) {
+            return new ToolError(error.code, message, error.retriable);
+        }
+        const wrapped = new Error(message);
+        wrapped.name = error.name;
+        return wrapped;
+    }
     /**
      * Assemble the final user-visible result string from collected tails.
      * Adds a truncation header (with the on-disk log path) and the legacy
@@ -1039,12 +1473,20 @@ export class SSHConnectionManager {
         const timeout = options.timeout || 30000; // Default 30 seconds timeout
         const maxRetries = options.maxRetries ?? 2; // Default 2 retries
         const maxOutputBytes = options.maxOutputBytes ?? SSHConnectionManager.DEFAULT_MAX_OUTPUT_BYTES;
+        const reuseConnection = options.reuseConnection !== false;
         const key = name || this.defaultName;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options.vvv === true);
         let lastError = null;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                // Ensure SSH connection is established
-                const client = await this.ensureConnected(name);
+                debug?.(`[mcp] command attempt ${attempt + 1}/${maxRetries + 1} on [${key}], reuseConnection=${reuseConnection}`);
+                const commandConnection = reuseConnection
+                    ? { client: await this.ensureConnected(name, timeout), close: () => { } }
+                    : await this.connectCommandClient(key, timeout, debug);
+                const client = commandConnection.client;
+                if (reuseConnection) {
+                    debug?.(`[mcp] using cached SSH connection for [${key}]; set reuseConnection=false to capture SSH handshake debug`);
+                }
                 // Per-attempt collectors + log writer. We rebuild them on each retry
                 // so partial output from a failed attempt is not mixed into the next.
                 const stdoutCollector = new OutputCollector(maxOutputBytes);
@@ -1057,10 +1499,12 @@ export class SSHConnectionManager {
                         stdoutCollector,
                         stderrCollector,
                         logWriter: logWriter ?? undefined,
+                        debug,
                     });
                 }
                 finally {
                     logWriter?.close({ exitCode, durationMs: Date.now() - startedMs });
+                    commandConnection.close();
                 }
                 const result = this.buildExecuteResult({
                     stdoutCollector,
@@ -1073,7 +1517,7 @@ export class SSHConnectionManager {
                 if (attempt > 0) {
                     Logger.log(`Command succeeded on retry attempt ${attempt} for [${key}]`, "info");
                 }
-                return result;
+                return this.appendDebugOutput(result, debugCollector);
             }
             catch (error) {
                 lastError = error;
@@ -1083,13 +1527,13 @@ export class SSHConnectionManager {
                     Logger.log(`Connection error on attempt ${attempt + 1}/${maxRetries + 1} for [${key}]: ${lastError.message}. Retrying in ${backoffMs}ms...`, "info");
                     // Wait with exponential backoff
                     await this.sleep(backoffMs);
-                    // Force reconnect before retry
-                    try {
-                        await this.reconnect(name);
-                    }
-                    catch (reconnectError) {
-                        Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
-                        // Continue to next retry attempt anyway
+                    if (reuseConnection) {
+                        try {
+                            await this.reconnect(name);
+                        }
+                        catch (reconnectError) {
+                            Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
+                        }
                     }
                     continue;
                 }
@@ -1098,7 +1542,7 @@ export class SSHConnectionManager {
             }
         }
         // All retries exhausted
-        throw lastError || new Error("Command execution failed after all retries");
+        throw this.appendDebugToError(lastError || new Error("Command execution failed after all retries"), debugCollector);
     }
     /**
      * Execute SSH command with real-time streaming output via progress callback
@@ -1122,12 +1566,20 @@ export class SSHConnectionManager {
         const timeout = options.timeout || 300000; // Default 5 minutes for streaming
         const maxRetries = options.maxRetries ?? 2; // Default 2 retries
         const maxOutputBytes = options.maxOutputBytes ?? SSHConnectionManager.DEFAULT_MAX_OUTPUT_BYTES;
+        const reuseConnection = options.reuseConnection !== false;
         const key = name || this.defaultName;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options.vvv === true);
         let lastError = null;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                // Ensure SSH connection is established
-                const client = await this.ensureConnected(name);
+                debug?.(`[mcp] streaming command attempt ${attempt + 1}/${maxRetries + 1} on [${key}], reuseConnection=${reuseConnection}`);
+                const commandConnection = reuseConnection
+                    ? { client: await this.ensureConnected(name, timeout), close: () => { } }
+                    : await this.connectCommandClient(key, timeout, debug);
+                const client = commandConnection.client;
+                if (reuseConnection) {
+                    debug?.(`[mcp] using cached SSH connection for [${key}]; set reuseConnection=false to capture SSH handshake debug`);
+                }
                 // Per-attempt collectors + log writer. onProgress keeps streaming
                 // every byte live; only the final returned string is capped.
                 const stdoutCollector = new OutputCollector(maxOutputBytes);
@@ -1141,10 +1593,12 @@ export class SSHConnectionManager {
                         stderrCollector,
                         logWriter: logWriter ?? undefined,
                         onProgress: options.onProgress,
+                        debug,
                     });
                 }
                 finally {
                     logWriter?.close({ exitCode, durationMs: Date.now() - startedMs });
+                    commandConnection.close();
                 }
                 const result = this.buildExecuteResult({
                     stdoutCollector,
@@ -1157,7 +1611,7 @@ export class SSHConnectionManager {
                 if (attempt > 0) {
                     Logger.log(`Streaming command succeeded on retry attempt ${attempt} for [${key}]`, "info");
                 }
-                return result;
+                return this.appendDebugOutput(result, debugCollector);
             }
             catch (error) {
                 lastError = error;
@@ -1166,18 +1620,20 @@ export class SSHConnectionManager {
                     const backoffMs = 500 * Math.pow(2, attempt);
                     Logger.log(`Connection error on streaming attempt ${attempt + 1}/${maxRetries + 1} for [${key}]: ${lastError.message}. Retrying in ${backoffMs}ms...`, "info");
                     await this.sleep(backoffMs);
-                    try {
-                        await this.reconnect(name);
-                    }
-                    catch (reconnectError) {
-                        Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
+                    if (reuseConnection) {
+                        try {
+                            await this.reconnect(name);
+                        }
+                        catch (reconnectError) {
+                            Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
+                        }
                     }
                     continue;
                 }
                 break;
             }
         }
-        throw lastError || new Error("Streaming command execution failed after all retries");
+        throw this.appendDebugToError(lastError || new Error("Streaming command execution failed after all retries"), debugCollector);
     }
     /**
      * Build an OutputLogWriter for a given server. Returns null if we cannot

package/build/tools/close-connection.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
+import { Logger } from "../utils/logger.js";
+import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
+/**
+ * Register close-connection tool
+ */
+export function registerCloseConnectionTool(server) {
+    const sshManager = SSHConnectionManager.getInstance();
+    server.tool("close-connection", "Close the cached SSH connection for a configured server. Use this after a timeout, stale connection suspicion, or before retrying a host with a clean cached connection. This affects only cached/reused SSH clients; reuseConnection=false command clients already close after each command. Closing a jump host also closes cached target connections whose jump chain uses that host.", {
+        connectionName: z
+            .string()
+            .optional()
+            .describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
+    }, async ({ connectionName }) => {
+        try {
+            const result = sshManager.closeConnection(connectionName);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const toolError = toToolError(error, "INVALID_CONFIGURATION");
+            Logger.handleError(toolError, "Failed to close SSH connection");
+            return {
+                content: [{ type: "text", text: formatToolErrorResponse(toolError) }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/execute-command.js

@@ -11,7 +11,7 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
  */
 export function registerExecuteCommandTool(server) {
     const sshManager = SSHConnectionManager.getInstance();
-    server.tool("execute-command", "Execute a shell command on a remote server over SSH. Use this for command-line actions on the selected host. Streaming mode is enabled by default so long-running commands can emit progress; set stream=false for short commands where you only want the final output. The returned text is tail-only-capped at maxOutputBytes PER STREAM (default 65536 bytes for stdout and 65536 bytes for stderr, so the response can be up to ~2x that); the FULL stdout/stderr is always persisted to a local log file under <cwd>/.handfree-output/<server>/<user>/, and the response includes that path whenever output was truncated.", {
+    server.tool("execute-command", "Execute a shell command on a remote server over SSH. Use this for command-line actions on the selected host. Streaming mode is enabled by default so long-running commands can emit progress; set stream=false for short commands where you only want the final output. SSH connections are reused by default for speed; if an execute-command call times out or you suspect a stale cached SSH connection, retry with reuseConnection=false to force a fresh TCP/SSH connection for that command. Set vvv=true only when debugging SSH/channel issues; with reuseConnection=false it includes ssh2 handshake/debug lines in the result or error. The returned text is tail-only-capped at maxOutputBytes PER STREAM (default 65536 bytes for stdout and 65536 bytes for stderr, so the response can be up to ~2x that); the FULL stdout/stderr is always persisted to a local log file under <cwd>/.handfree-output/<server>/<user>/, and the response includes that path whenever output was truncated.", {
         cmdString: z.string().describe("Exact remote shell command to run. Prefer a single command per call, for example 'pwd', 'ls -la', 'cat /etc/hostname', or 'git status'. Compound commands may be blocked by command policy even if each subcommand is safe."),
         connectionName: z
             .string()
@@ -20,18 +20,26 @@ export function registerExecuteCommandTool(server) {
         timeout: z
             .number()
             .optional()
-            .describe("Maximum runtime in milliseconds. Defaults to 300000 when stream=true and 30000 when stream=false. Increase this for long-running commands; reduce it for fast probes."),
+            .describe("Timeout in milliseconds applied separately to SSH connection setup, exec-channel opening, and remote command execution for each attempt. Defaults to 300000 when stream=true and 30000 when stream=false. Increase this for long-running commands; reduce it for fast probes."),
         stream: z
             .boolean()
             .optional()
             .describe("Whether to stream progress output. Default is true. Use false for short commands like pwd, ls, cat, head, tail, or git status when you only need the final result."),
+        reuseConnection: z
+            .boolean()
+            .optional()
+            .describe("Whether to reuse the cached SSH connection for this server. Default is true for speed. Set false after a timeout or suspected stale/bad cached connection; false opens a fresh SSH connection for this command and closes it afterwards."),
+        vvv: z
+            .boolean()
+            .optional()
+            .describe("Default false. When true, append bounded SSH/channel debug output to the result or error. For full ssh2 handshake debug, also set reuseConnection=false; already-reused cached clients cannot retroactively emit handshake logs."),
         maxOutputBytes: z
             .number()
             .int()
             .nonnegative()
             .optional()
             .describe("Per-stream cap on bytes returned to the caller (tail-only). Applied independently to stdout and stderr, so the combined response can be up to ~2x this value. Defaults to 65536 (64 KiB). The full output is always saved to disk regardless; only the returned text is trimmed. Set higher when you need more context, lower to save tokens."),
-    }, async ({ cmdString, connectionName, timeout, stream, maxOutputBytes }, extra) => {
+    }, async ({ cmdString, connectionName, timeout, stream, reuseConnection, vvv, maxOutputBytes }, extra) => {
         try {
             const resolvedName = sshManager.resolveServer(connectionName);
             const useStream = stream !== false;
@@ -54,6 +62,8 @@ export function registerExecuteCommandTool(server) {
                 const result = await sshManager.executeCommandWithProgress(cmdString, resolvedName, {
                     timeout: timeout || 300000,
                     maxOutputBytes,
+                    reuseConnection,
+                    vvv,
                     onProgress,
                 });
                 return {
@@ -63,6 +73,8 @@ export function registerExecuteCommandTool(server) {
             const result = await sshManager.executeCommand(cmdString, resolvedName, {
                 timeout: timeout || 30000,
                 maxOutputBytes,
+                reuseConnection,
+                vvv,
             });
             return {
                 content: [{ type: "text", text: result }],

package/build/tools/help.js

@@ -18,19 +18,30 @@ Example:
 Parameters:
   cmdString       (string, required)   The shell command to execute.
   connectionName  (string, see below)  Target server name from list-servers.
-  stream          (boolean, optional)  Default true. Set false for short
-                  commands when you only need the final output.
-  timeout         (number, optional)   Max runtime in ms.
-                  Defaults: 300000 (stream) / 30000 (non-stream).
+  stream          (boolean, optional)  Default true. Set false for short
+                  commands when you only need the final output.
+  reuseConnection (boolean, optional)  Default true. Set false after a timeout
+                  or suspected stale cached SSH connection to force a fresh
+                  TCP/SSH connection for this command.
+  vvv             (boolean, optional)  Default false. Append bounded
+                  SSH/channel debug output. Use with reuseConnection=false
+                  when you need fresh handshake logs.
+  timeout         (number, optional)   Per-attempt phase timeout in ms:
+                                      SSH setup, exec-channel open, and
+                                      remote command execution each use this
+                                      cap.
+                  Defaults: 300000 (stream) / 30000 (non-stream).
 
 connectionName rule:
   • If only one server is enabled → optional (auto-selected).
   • If multiple servers are enabled → REQUIRED.
 
 Examples:
-  execute-command { cmdString: "pwd" }
-  execute-command { cmdString: "docker ps -a", connectionName: "prod", stream: false }
-  execute-command { cmdString: "tail -f /var/log/syslog", stream: true, timeout: 600000 }`,
+  execute-command { cmdString: "pwd" }
+  execute-command { cmdString: "docker ps -a", connectionName: "prod", stream: false }
+  execute-command { cmdString: "tail -f /var/log/syslog", stream: true, timeout: 600000 }
+  execute-command { cmdString: "hostname", connectionName: "scnet", stream: false, reuseConnection: false }
+  execute-command { cmdString: "hostname", connectionName: "scnet", stream: false, reuseConnection: false, vvv: true }`,
     "show-whitelist": `show-whitelist — Show the active command policy for a server.
 
 Parameters:
@@ -41,7 +52,25 @@ connectionName rule:
   • If multiple servers are enabled → REQUIRED.
 
 Returns: Command mode, built-in blacklist, configured whitelist/blacklist patterns, and example commands when whitelist mode is active.`,
-    "upload": `upload — Upload a single local file to a remote server over SFTP.
+    "close-connection": `close-connection — Close a cached SSH connection.
+
+Parameters:
+  connectionName  (string, see below)  Target server name from list-servers.
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Behavior:
+  • Closes the cached/reused SSH client for the target server.
+  • Closing a jump host also closes cached targets whose jump chain uses it.
+  • Does not affect reuseConnection=false commands, because those one-shot
+    connections already close after each command.
+
+Examples:
+  close-connection { connectionName: "scnet" }
+  close-connection { connectionName: "dcu" }`,
+    "upload": `upload — Upload a single local file to a remote server over SFTP.
 
 Parameters:
   localPath       (string, required)   File path on the MCP host.
@@ -113,18 +142,20 @@ Example:
 };
 const TOOL_OVERVIEW = `Available tools (use help { tool: "<name>" } for details):
 
-  list-servers      Discover available SSH servers and their status.
-  execute-command   Run a shell command on a remote server.
+  list-servers      Discover available SSH servers and their status.
+  execute-command   Run a shell command on a remote server.
   show-whitelist    Show the active command policy.
-  upload            Upload a single file to a remote server.
-  download          Download a single file from a remote server.
+  close-connection  Close a cached SSH connection for a server.
+  upload            Upload a single file to a remote server.
+  download          Download a single file from a remote server.
   transfer          Move files: single, recursive, or cross-server relay.
   help              Show this help or detailed per-tool usage.
 
 Quick start:
-  1. list-servers → discover server names
+  1. list-servers → discover server names
   2. show-whitelist { connectionName: "<name>" } → inspect command policy
-  3. execute-command { cmdString: "pwd", connectionName: "<name>" }`;
+  3. execute-command { cmdString: "pwd", connectionName: "<name>" }
+  4. close-connection { connectionName: "<name>" } → drop a stale cached SSH client`;
 /**
  * Register help tool
  */

package/build/tools/index.js

@@ -3,6 +3,7 @@ import { registerUploadTool } from "./upload.js";
 import { registerDownloadTool } from "./download.js";
 import { registerListServersTool } from "./list-servers.js";
 import { registerShowWhitelistTool } from "./show-whitelist.js";
+import { registerCloseConnectionTool } from "./close-connection.js";
 import { registerTransferTool } from "./transfer.js";
 import { registerHelpTool } from "./help.js";
 /**
@@ -15,6 +16,7 @@ export function registerAllTools(server) {
     registerDownloadTool(server);
     registerListServersTool(server);
     registerShowWhitelistTool(server);
+    registerCloseConnectionTool(server);
     registerTransferTool(server);
     registerHelpTool(server);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaarc/handfree-ssh-mcp",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Handfree SSH MCP Server - A hands-free SSH automation tool via MCP protocol",
   "main": "build/index.js",
   "type": "module",