@aaarc/handfree-ssh-mcp 1.0.7 → 1.0.9

package/build/config/server.js

@@ -1,6 +1,6 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.0.7",
+    version: "1.0.9",
 };
 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.
 

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

@@ -721,6 +721,62 @@ export class SSHConnectionManager {
         }
         return Math.max(1, timeout);
     }
+    /**
+     * Run a transfer that reports progress through a callback, aborting it if no
+     * progress arrives within `timeoutMs` (an INACTIVITY watchdog, not a total
+     * duration cap -- a long but actively-streaming transfer is never killed).
+     * When `timeoutMs` is falsy the operation runs unbounded, preserving the
+     * previous behavior. `onTimeout` is invoked to tear down the stalled session.
+     */
+    runWithInactivityTimeout(start, timeoutMs, description, debug, onTimeout) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return start(() => { });
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer = null;
+            const clear = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            };
+            const arm = () => {
+                clear();
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    debug?.(`[mcp] ${description} stalled: no progress for ${timeoutMs}ms`);
+                    try {
+                        onTimeout?.();
+                    }
+                    catch {
+                        // Ignore cleanup failures after a stall.
+                    }
+                    reject(new ToolError("SSH_CONNECTION_FAILED", `${description} stalled: no progress for ${timeoutMs}ms`, true));
+                }, timeoutMs);
+            };
+            const onProgress = () => {
+                if (!settled)
+                    arm();
+            };
+            arm();
+            start(onProgress).then((value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clear();
+                resolve(value);
+            }, (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clear();
+                reject(err);
+            });
+        });
+    }
     /**
      * 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.
@@ -1306,12 +1362,29 @@ export class SSHConnectionManager {
         return new Promise((resolve, reject) => {
             let timeoutId = null;
             let settled = false;
-            const cleanup = () => {
+            let channelOpened = false;
+            let activeStream = null;
+            const eventedClient = client;
+            const canObserveClientLifecycle = typeof eventedClient.once === "function" &&
+                typeof eventedClient.removeListener === "function";
+            const clearCommandTimer = () => {
                 if (timeoutId) {
                     clearTimeout(timeoutId);
                     timeoutId = null;
                 }
             };
+            const removeClientLifecycleListeners = () => {
+                if (!canObserveClientLifecycle) {
+                    return;
+                }
+                eventedClient.removeListener?.("error", onClientError);
+                eventedClient.removeListener?.("end", onClientEnd);
+                eventedClient.removeListener?.("close", onClientClose);
+            };
+            const cleanup = () => {
+                clearCommandTimer();
+                removeClientLifecycleListeners();
+            };
             const settle = (err, code) => {
                 if (settled)
                     return;
@@ -1330,6 +1403,24 @@ export class SSHConnectionManager {
                     // Ignore late-stream close errors after the promise has settled.
                 }
             };
+            const failOnClientEvent = (event, message) => {
+                const phase = channelOpened ? "running command" : "opening command channel";
+                const detail = message ? `: ${message}` : "";
+                sinks.debug?.(`[mcp] SSH client ${event} while ${phase}${detail}`);
+                if (activeStream) {
+                    closeLateStream(activeStream);
+                }
+                settle(new ToolError("SSH_CONNECTION_FAILED", `SSH connection ${event} while ${phase}${detail}`, true));
+            };
+            const onClientError = (err) => {
+                failOnClientEvent("failed", err.message);
+            };
+            const onClientEnd = () => {
+                failOnClientEvent("ended");
+            };
+            const onClientClose = () => {
+                failOnClientEvent("closed");
+            };
             const armExecOpenTimeout = () => {
                 const execOpenTimeout = Math.max(1, timeout);
                 timeoutId = setTimeout(() => {
@@ -1356,6 +1447,11 @@ export class SSHConnectionManager {
                 }, timeout);
             };
             armExecOpenTimeout();
+            if (canObserveClientLifecycle) {
+                eventedClient.once?.("error", onClientError);
+                eventedClient.once?.("end", onClientEnd);
+                eventedClient.once?.("close", onClientClose);
+            }
             sinks.debug?.(`[mcp] opening exec channel for command: ${cmdString}`);
             try {
                 client.exec(cmdString, (err, stream) => {
@@ -1371,7 +1467,9 @@ export class SSHConnectionManager {
                         settle(new ToolError(code, `Command execution error: ${err.message}`, isConnectionFailure));
                         return;
                     }
-                    cleanup();
+                    clearCommandTimer();
+                    channelOpened = true;
+                    activeStream = stream;
                     sinks.debug?.("[mcp] exec channel opened");
                     stream.on("data", (chunk) => {
                         sinks.stdoutCollector?.push(chunk);
@@ -2059,37 +2157,65 @@ export class SSHConnectionManager {
      * Upload a local file using ssh2's parallel SFTP fastPut implementation.
      */
     async sftpFastPut(client, localPath, remotePath, options, timeout, debug) {
-        const sftp = await this.openSftp(client, "fastPut", timeout, debug);
+        // Validate transfer options BEFORE opening the channel so invalid options
+        // can never leak an SFTP channel.
         const transferOptions = this.createSftpTransferOptions(options);
+        const sftp = await this.openSftp(client, "fastPut", timeout, debug);
         debug?.(`[mcp] fastPut ${localPath} -> ${remotePath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
-        return new Promise((resolve, reject) => {
-            sftp.fastPut(localPath, remotePath, transferOptions, (err) => {
+        const endSftp = () => {
+            try {
                 sftp.end();
-                if (err) {
-                    reject(this.makeSftpError("Fast upload failed", err));
-                    return;
-                }
-                resolve();
-            });
-        });
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                sftp.fastPut(localPath, remotePath, { ...transferOptions, step: () => onProgress() }, (err) => {
+                    if (err) {
+                        reject(this.makeSftpError("Fast upload failed", err));
+                        return;
+                    }
+                    resolve();
+                });
+            }), this.normalizeConnectTimeout(timeout), `fast upload ${localPath} -> ${remotePath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * Download a remote file using ssh2's parallel SFTP fastGet implementation.
      */
     async sftpFastGet(client, remotePath, localPath, options, timeout, debug) {
-        const sftp = await this.openSftp(client, "fastGet", timeout, debug);
+        // Validate transfer options BEFORE opening the channel so invalid options
+        // can never leak an SFTP channel.
         const transferOptions = this.createSftpTransferOptions(options);
+        const sftp = await this.openSftp(client, "fastGet", timeout, debug);
         debug?.(`[mcp] fastGet ${remotePath} -> ${localPath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
-        return new Promise((resolve, reject) => {
-            sftp.fastGet(remotePath, localPath, transferOptions, (err) => {
+        const endSftp = () => {
+            try {
                 sftp.end();
-                if (err) {
-                    reject(this.makeSftpError("Fast download failed", err));
-                    return;
-                }
-                resolve();
-            });
-        });
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                sftp.fastGet(remotePath, localPath, { ...transferOptions, step: () => onProgress() }, (err) => {
+                    if (err) {
+                        reject(this.makeSftpError("Fast download failed", err));
+                        return;
+                    }
+                    resolve();
+                });
+            }), this.normalizeConnectTimeout(timeout), `fast download ${remotePath} -> ${localPath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * Download file
@@ -2240,6 +2366,7 @@ export class SSHConnectionManager {
         const validatedDestPath = this.validateRemotePath(destRemotePath, destName);
         const skipIfIdentical = options?.skipIfIdentical !== false; // default true
         const reuseConnection = options?.reuseConnection !== false;
+        const selfRelay = sourceName === destName;
         const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
         debug?.(`[mcp] sftp relay ${sourceName} -> ${destName}, reuseConnection=${reuseConnection}`);
         let srcConnection = null;
@@ -2253,12 +2380,16 @@ export class SSHConnectionManager {
                 debug,
                 purpose: "sftp",
             });
-            dstConnection = await this.acquireSshClient(destName, {
-                reuseConnection,
-                timeout: options?.timeout,
-                debug,
-                purpose: "sftp",
-            });
+            // Same host on both ends: reuse the one SSH client (two SFTP channels are
+            // still opened below) so we never open or close a second connection.
+            dstConnection = selfRelay
+                ? srcConnection
+                : await this.acquireSshClient(destName, {
+                    reuseConnection,
+                    timeout: options?.timeout,
+                    debug,
+                    purpose: "sftp",
+                });
             const srcClient = srcConnection.client;
             const dstClient = dstConnection.client;
             srcSftp = await this.openSftp(srcClient, "source", options?.timeout, debug);
@@ -2338,7 +2469,8 @@ export class SSHConnectionManager {
         catch (error) {
             if (reuseConnection && this.isConnectionError(error)) {
                 this.closeClient(sourceName, true);
-                this.closeClient(destName, true);
+                if (!selfRelay)
+                    this.closeClient(destName, true);
             }
             throw this.appendDebugToError(error, debugCollector);
         }
@@ -2346,7 +2478,8 @@ export class SSHConnectionManager {
             srcSftp?.end();
             dstSftp?.end();
             srcConnection?.close();
-            dstConnection?.close();
+            if (!selfRelay)
+                dstConnection?.close();
         }
     }
     /**
@@ -2397,7 +2530,10 @@ export class SSHConnectionManager {
         const open = new Promise((resolve, reject) => {
             client.sftp((err, sftp) => {
                 if (err) {
-                    return reject(this.makeSftpError(`SFTP connection failed (${label})`, err));
+                    // A client that cannot open an SFTP channel is unusable, so treat the
+                    // failure as connection-shaped regardless of wording. This lets the
+                    // caller force-drop the stale cached client and self-heal on retry.
+                    return reject(new ToolError("SSH_CONNECTION_FAILED", `SFTP connection failed (${label}): ${err.message}`, true));
                 }
                 debug?.(`[mcp] sftp channel opened (${label})`);
                 resolve(sftp);
@@ -2537,21 +2673,37 @@ export class SSHConnectionManager {
      */
     async sftpMkdirRecursive(client, remotePath, timeout, debug) {
         const sftp = await this.openSftp(client, "mkdir", timeout, debug);
-        return new Promise((resolve) => {
+        const walk = new Promise((resolve, reject) => {
             const parts = remotePath.split("/").filter(Boolean);
             let current = "";
             const mkdirNext = (index) => {
                 if (index >= parts.length) {
-                    sftp.end();
                     return resolve();
                 }
                 current += "/" + parts[index];
-                sftp.mkdir(current, () => {
-                    // EEXIST is fine
+                sftp.mkdir(current, (err) => {
+                    // An existing directory (or other non-connection failure) is fine and
+                    // just means the path component already exists. A connection-shaped
+                    // error means the channel died mid-walk -- surface it instead of
+                    // silently marching on (and eventually hanging the per-file uploads).
+                    if (err && this.isConnectionShapedMessage(err.message)) {
+                        return reject(this.makeSftpError("Remote mkdir failed", err));
+                    }
                     mkdirNext(index + 1);
                 });
             };
             mkdirNext(0);
         });
+        try {
+            await this.withConnectionTimeout(walk, this.normalizeConnectTimeout(timeout), `SFTP mkdir ${remotePath}`, debug);
+        }
+        finally {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        }
     }
 }

package/build/tools/execute-command.js

@@ -19,6 +19,7 @@ export function registerExecuteCommandTool(server) {
             .describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
         timeout: z
             .number()
+            .positive()
             .optional()
             .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

package/package.json

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