@aaarc/handfree-ssh-mcp 1.0.6 → 1.0.7

package/README.md

@@ -116,9 +116,9 @@ The AI can now execute commands on your servers. All within your defined securit
 | `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`) |
+| `upload` | Upload local file to a remote server (CRLF-fix for shell scripts, skip-if-identical, optional `reuseConnection`, `vvv`, `fast`) |
+| `download` | Download remote file to local disk (optional `reuseConnection`, `vvv`, `fast`) |
+| `transfer` | Unified upload / download / server-to-server relay (`mode`: `upload` / `download` / `relay`, optional `recursive`, `skipIfIdentical`, `reuseConnection`, `vvv`, `fast`) |
 | `list-servers` | List configured (enabled) servers. Lean by default; `verbose:true` adds cached system status, `refresh:true` re-collects it (implies verbose). |
 | `help` | Self-describing help text for the MCP client |
 
@@ -298,16 +298,18 @@ Rules (enforced at config load — bad configs fail fast):
 - **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 fresh command/SFTP connections.** `execute-command`, `upload`, `download`, and `transfer` reuse cached SSH clients by default (`reuseConnection: true`). If a call times out or you suspect the cached `ssh2.Client` is stale while native `ssh` works, retry with `reuseConnection: false`; that one operation opens a fresh SSH connection and closes it afterwards. SFTP still opens a new SFTP channel/session per operation.
 - **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.
+- **Optional SFTP debug output.** Set `vvv: true` on `upload`, `download`, or `transfer` to append bounded SSH/SFTP debug where the result is textual. Recursive `transfer` success keeps its structured `{ summary, files }` JSON response, so recursive debug is surfaced on errors rather than appended to successful summaries.
+- **SFTP transfers do NOT auto-retry.** `upload` / `download` / `transfer` lazy-connect via the same acquisition path and close stale cached clients on connection-shaped SFTP/channel errors, but a mid-transfer disconnect surfaces as a single failure — re-issue the call manually, preferably with `reuseConnection: false` if you suspect the cached SSH client.
 - **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
 
-- **CRLF auto-fix for shell scripts.** When uploading a `.sh`, `.bash`, or `.zsh` file, any `\r\n` line endings are automatically converted to `\n` before the bytes are sent. The response notes when this happens and how many line endings were rewritten. The local file on disk is left untouched.
-- **Skip-if-identical (default on).** Before transferring, `upload` checks whether the remote file already matches the local payload. Files ≤ 256 MiB are compared byte-for-byte; larger files are compared via MD5 (using `md5sum` on the remote host). **Shell scripts (`.sh` / `.bash` / `.zsh`) are compared in a line-ending-agnostic way — both sides are LF-normalized before the comparison, so a CRLF-only diff is treated as identical and the upload is still skipped.** If they match, the upload is skipped and the response says so. Pass `skipIfIdentical: false` to force a re-upload. Recursive `transfer` (`mode: upload`, `recursive: true`) applies the same check per file.
-- **Relay skip-if-identical (default on).** `transfer mode=relay` does the same check between two remote servers: matching size on both sides plus matching `md5sum` skips the transfer. If `md5sum` is missing on either server, the check falls back to a normal transfer.
+- **CRLF auto-fix for shell scripts.** When uploading a `.sh`, `.bash`, or `.zsh` file, any `\r\n` line endings are automatically converted to `\n` before the bytes are sent. The response notes when this happens and how many line endings were rewritten. The local file on disk is left untouched.
+- **Skip-if-identical (default on).** Before transferring, `upload` checks whether the remote file already matches the local payload. Files ≤ 256 MiB are compared byte-for-byte; larger files are compared via MD5 (using `md5sum` on the remote host). **Shell scripts (`.sh` / `.bash` / `.zsh`) are compared in a line-ending-agnostic way — both sides are LF-normalized before the comparison, so a CRLF-only diff is treated as identical and the upload is still skipped.** If they match, the upload is skipped and the response says so. Pass `skipIfIdentical: false` to force a re-upload. Recursive `transfer` (`mode: upload`, `recursive: true`) applies the same check per file.
+- **Fast single-file SFTP (default off).** Set `fast: true` on `upload`, `download`, or `transfer` upload/download mode to use ssh2 `fastPut` / `fastGet` for host-to-remote or remote-to-host single-file throughput. Optional `sftpConcurrency` and `chunkSize` are passed to ssh2 only when `fast: true`; omitted values use ssh2 defaults. This is not multi-file concurrency: recursive directory transfer remains sequential, and relay mode keeps its remote-A → MCP host → remote-B streaming pipe path. If a shell-script upload needs CRLF-to-LF conversion, it falls back to the normal safe upload path.
+- **Relay skip-if-identical (default on).** `transfer mode=relay` does the same check between two remote servers: matching size on both sides plus matching `md5sum` skips the transfer. If `md5sum` is missing on either server, the check falls back to a normal transfer.
 
 ### `execute-command` output capping & full logs
 
@@ -375,8 +377,10 @@ Example with selective servers:
 ### Nice to Have
 - [x] **Command history / output archive**: full stdout/stderr of every `execute-command` is persisted under `<outputLogDir>/<server>/<user>/*.log`
 - [x] **Multi-command execution**: Execute multiple commands in sequence with `&&` or `;` safely (fixed: `2>/dev/null` now allowed)
-- [x] **Connection auto-recovery**: `execute-command` retries with exponential backoff and forced reconnect on connection-shaped errors
-- [ ] **SFTP retry parity**: extend the retry-with-reconnect loop to `upload` / `download` / `transfer`
+- [x] **Connection auto-recovery**: `execute-command` retries with exponential backoff and forced reconnect on connection-shaped errors
+- [x] **SFTP connection reuse controls**: `upload` / `download` / `transfer` support `reuseConnection`, `vvv`, and explicit fresh one-shot SSH clients
+- [x] **Fast single-file SFTP**: optional ssh2 `fastPut` / `fastGet` via `fast`, `sftpConcurrency`, and `chunkSize`
+- [ ] **SFTP retry parity**: extend the retry-with-reconnect loop to `upload` / `download` / `transfer`
 - [ ] **TCP keepalive**: pass `keepaliveInterval` / `keepaliveCountMax` to `ssh2.Client` so half-open connections are detected without waiting for the next command
 - [ ] **Server health check**: optional periodic ping to detect drops proactively
 

package/build/config/server.js

@@ -1,6 +1,6 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.0.5",
+    version: "1.0.7",
 };
 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.
 
@@ -11,10 +11,12 @@ Recommended workflow:
 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. 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.
+7. SFTP tools also reuse SSH connections by default. If upload/download/transfer times out or reports a connection-shaped SFTP/channel error, retry with reuseConnection=false; the fresh SSH connection closes after that transfer.
+8. 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.
+9. For SSH/channel diagnostics, add vvv=true. Use it with reuseConnection=false when you need fresh handshake/debug output.
+10. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
+11. For large host-to-remote or remote-to-host single-file SFTP transfers, fast=true enables ssh2 fastPut/fastGet with optional sftpConcurrency and chunkSize. It is off by default and does not add multi-file concurrency; relay keeps the streaming pipe path.
+12. 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.
@@ -24,5 +26,5 @@ Behavior notes:
 - A tool may automatically establish the SSH connection on first use.
 - Command execution uses blacklist mode by default, with a built-in dangerous-command blacklist. Servers can opt into whitelist mode through YAML. If a command is rejected, inspect the command policy rather than retrying the same command repeatedly.
 - Some commands return no output on success; this is normal.
-- File transfer tools use SFTP and can fail if the remote path is missing or permissions are insufficient.
+- File transfer tools use SFTP and can fail if the remote path is missing or permissions are insufficient. They open a new SFTP channel per operation; they reuse the underlying SSH client unless reuseConnection=false is set.
 - OpenSSH/YAML config changes are hot-reloaded without restarting the server. Connection-field changes close the old client so the next tool call reconnects with fresh settings.`;

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

@@ -125,10 +125,7 @@ export class SSHConnectionManager {
                 toReset.add(name);
             }
         }
-        for (const name of toReset) {
-            this.closeClient(name, true);
-            this.statusCache.delete(name);
-        }
+        this.closeClientSet(toReset, true);
         this.setConfig(configs, enabledServers);
         Logger.log(`Hot-reloaded SSH config: ${Object.keys(configs).length} server(s), ` +
             `${toReset.size} connection(s) reset`, "info");
@@ -197,6 +194,12 @@ export class SSHConnectionManager {
         this.connected.set(name, false);
         this.connecting.delete(name);
     }
+    closeClientSet(names, bumpGeneration = true) {
+        for (const name of names) {
+            this.closeClient(name, bumpGeneration);
+            this.statusCache.delete(name);
+        }
+    }
     closeConnection(name) {
         const key = this.resolveServer(name);
         this.getConfig(key);
@@ -209,10 +212,7 @@ export class SSHConnectionManager {
                 affected.add(target);
             }
         }
-        for (const target of affected) {
-            this.closeClient(target, true);
-            this.statusCache.delete(target);
-        }
+        this.closeClientSet(affected, true);
         return {
             requested: key,
             closed: Array.from(affected),
@@ -496,15 +496,34 @@ export class SSHConnectionManager {
         }
         this.clients.set(key, client);
     }
+    async acquireSshClient(key, options = {}) {
+        const reuseConnection = options.reuseConnection !== false;
+        const purpose = options.purpose ?? "command";
+        if (reuseConnection) {
+            const client = await this.ensureConnected(key, options.timeout);
+            options.debug?.(`[mcp] using cached SSH connection for [${key}]; set reuseConnection=false to capture SSH handshake debug`);
+            return { client, close: () => { } };
+        }
+        if (purpose === "command") {
+            return this.connectCommandClient(key, options.timeout ?? 30000, options.debug);
+        }
+        return this.connectOneShotClient(key, options.timeout ?? 30000, options.debug, purpose);
+    }
     /**
-     * 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.
+     * Compatibility wrapper for tests and existing command call sites.
      */
     async connectCommandClient(key, timeout, debug) {
+        return this.connectOneShotClient(key, timeout, debug, "command");
+    }
+    /**
+     * Open a one-shot SSH client for a single operation. Used when the caller
+     * disables connection reuse after a timeout or when a fresh TCP/SSH
+     * handshake is more important than latency.
+     */
+    async connectOneShotClient(key, timeout, debug, purpose = "command") {
         const config = this.getConfig(key);
         const client = new Client();
-        const jumpChainKey = `__command__:${key}:${Date.now()}:${crypto.randomBytes(4).toString("hex")}`;
+        const jumpChainKey = `__${purpose}__:${key}:${Date.now()}:${crypto.randomBytes(4).toString("hex")}`;
         const connectTimeout = this.normalizeConnectTimeout(timeout) ?? 30000;
         let settled = false;
         let closed = false;
@@ -513,7 +532,7 @@ export class SSHConnectionManager {
                 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");
+            Logger.log(`One-shot SSH ${purpose} client [${key}] emitted error after settle: ${err.message}`, "error");
         };
         client.on("error", onLateError);
         const close = () => {
@@ -560,11 +579,11 @@ export class SSHConnectionManager {
                         }
                         this.teardownJumpChain(jumpChainKey);
                     });
-                    Logger.log(`Using one-shot jump host '${config.jumpHost}' for command on [${key}]`, "info");
+                    Logger.log(`Using one-shot jump host '${config.jumpHost}' for ${purpose} 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);
+                    throw new ToolError("SSH_CONNECTION_FAILED", `Failed to open one-shot jump tunnel for ${purpose} [${key}] via '${config.jumpHost}': ${err.message}`, true);
                 }
             }
             if (config.socksProxy) {
@@ -611,7 +630,7 @@ export class SSHConnectionManager {
                 sshConfig.password = config.password;
             }
             else if (agent || config.authOptional) {
-                Logger.log(`Using SSH agent/default authentication for one-shot command [${key}]`, "info");
+                Logger.log(`Using SSH agent/default authentication for one-shot ${purpose} [${key}]`, "info");
             }
             else {
                 throw new ToolError("SSH_AUTHENTICATION_MISSING", `No valid authentication method provided for [${key}] (password or private key)`, false);
@@ -631,19 +650,19 @@ export class SSHConnectionManager {
                         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 onError = (err) => done(new ToolError("SSH_CONNECTION_FAILED", `SSH ${purpose} connection [${key}] failed: ${err.message}`, true));
+                const onClose = () => done(new ToolError("SSH_CONNECTION_FAILED", `SSH ${purpose} 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));
+                    done(new ToolError("SSH_CONNECTION_FAILED", `SSH ${purpose} connection [${key}] timed out after ${connectTimeout}ms`, true));
                     close();
                 }, connectTimeout);
-                debug?.(`[mcp] opening one-shot SSH connection for [${key}]`);
+                debug?.(`[mcp] opening one-shot SSH ${purpose} 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");
+            Logger.log(`Opened one-shot SSH ${purpose} connection for [${key}]`, "info");
             return { client, close };
         }
         catch (err) {
@@ -700,7 +719,7 @@ export class SSHConnectionManager {
         if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
             return undefined;
         }
-        return Math.max(1, Math.min(timeout, 30000));
+        return Math.max(1, timeout);
     }
     /**
      * Open a TCP tunnel from the target's jump chain to `config.host:config.port`
@@ -994,6 +1013,31 @@ export class SSHConnectionManager {
             msg.includes("no response from server") ||
             msg.includes("timed out"));
     }
+    makeSftpError(context, error) {
+        const connectionFailure = this.isConnectionShapedMessage(error.message);
+        return new ToolError(connectionFailure ? "SSH_CONNECTION_FAILED" : "SFTP_ERROR", `${context}: ${error.message}`, connectionFailure);
+    }
+    createSftpTransferOptions(options) {
+        const transferOptions = {};
+        const concurrency = this.optionalPositiveInteger(options?.sftpConcurrency, "sftpConcurrency");
+        const chunkSize = this.optionalPositiveInteger(options?.chunkSize, "chunkSize");
+        if (concurrency !== undefined) {
+            transferOptions.concurrency = concurrency;
+        }
+        if (chunkSize !== undefined) {
+            transferOptions.chunkSize = chunkSize;
+        }
+        return transferOptions;
+    }
+    optionalPositiveInteger(value, name) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new ToolError("INVALID_CONFIGURATION", `${name} must be a positive integer`, false);
+        }
+        return value;
+    }
     /**
      * Force reconnect to SSH server
      * @private
@@ -1287,7 +1331,7 @@ export class SSHConnectionManager {
                 }
             };
             const armExecOpenTimeout = () => {
-                const execOpenTimeout = Math.max(1, Math.min(timeout, 30000));
+                const execOpenTimeout = Math.max(1, timeout);
                 timeoutId = setTimeout(() => {
                     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));
@@ -1383,24 +1427,18 @@ export class SSHConnectionManager {
         };
     }
     appendDebugOutput(result, collector) {
-        if (!collector || collector.getTotalBytes() === 0) {
+        const debugBlock = this.formatDebugBlock(collector);
+        if (!debugBlock) {
             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()}`;
+        return `${result}\n\n${debugBlock}`;
     }
     appendDebugToError(error, collector) {
-        if (!collector || collector.getTotalBytes() === 0) {
+        const debugBlock = this.formatDebugBlock(collector);
+        if (!debugBlock) {
             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()}`;
+        const message = `${error.message}\n\n${debugBlock}`;
         if (error instanceof ToolError) {
             return new ToolError(error.code, message, error.retriable);
         }
@@ -1408,6 +1446,40 @@ export class SSHConnectionManager {
         wrapped.name = error.name;
         return wrapped;
     }
+    formatDebugBlock(collector) {
+        if (!collector || collector.getTotalBytes() === 0) {
+            return null;
+        }
+        const snapshot = collector.getSnapshot();
+        const header = snapshot.truncated
+            ? `[SSH DEBUG TRUNCATED: dropped ${snapshot.droppedBytes} bytes]\n`
+            : "[SSH DEBUG]\n";
+        return `${header}${snapshot.tail.toString("utf8").trimEnd()}`;
+    }
+    unpipeStream(readStream, writeStream) {
+        const candidate = readStream;
+        if (typeof candidate.unpipe !== "function") {
+            return;
+        }
+        try {
+            candidate.unpipe(writeStream);
+        }
+        catch {
+            // Ignore cleanup errors after the original stream failure.
+        }
+    }
+    destroyStream(stream) {
+        const candidate = stream;
+        if (typeof candidate.destroy !== "function") {
+            return;
+        }
+        try {
+            candidate.destroy();
+        }
+        catch {
+            // Ignore cleanup errors after the original stream failure.
+        }
+    }
     /**
      * Assemble the final user-visible result string from collected tails.
      * Adds a truncation header (with the on-disk log path) and the legacy
@@ -1480,13 +1552,13 @@ export class SSHConnectionManager {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 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 commandConnection = await this.acquireSshClient(key, {
+                    reuseConnection,
+                    timeout,
+                    debug,
+                    purpose: "command",
+                });
                 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);
@@ -1573,13 +1645,13 @@ export class SSHConnectionManager {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 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 commandConnection = await this.acquireSshClient(key, {
+                    reuseConnection,
+                    timeout,
+                    debug,
+                    purpose: "command",
+                });
                 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);
@@ -1725,6 +1797,8 @@ export class SSHConnectionManager {
      */
     async upload(localPath, remotePath, name, options) {
         const resolvedName = name || this.defaultName;
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
         const validatedLocalPath = this.validateLocalPath(localPath, resolvedName);
         const validatedRemotePath = this.validateRemotePath(remotePath, resolvedName);
         const skipIfIdentical = options?.skipIfIdentical !== false; // default true
@@ -1740,32 +1814,67 @@ export class SSHConnectionManager {
             throw new ToolError("LOCAL_FILE_READ_FAILED", `Local path '${validatedLocalPath}' is not a regular file (size=${stat.size}). ` +
                 `Use uploadDirectory / recursive=true for directories.`, false);
         }
-        let payload;
-        try {
-            payload = fs.readFileSync(validatedLocalPath);
-        }
-        catch (e) {
-            throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read local file '${validatedLocalPath}': ${e.message}`, false);
+        const isShellScript = SSHConnectionManager.SHELL_SCRIPT_EXTENSIONS.has(path.extname(validatedLocalPath).toLowerCase());
+        const fastUpload = options?.fast === true;
+        const mustReadPayload = skipIfIdentical || !fastUpload || isShellScript;
+        let payload = null;
+        let crlfFixed = {
+            buffer: Buffer.alloc(0),
+            fixed: false,
+            replacedCount: 0,
+        };
+        if (mustReadPayload) {
+            try {
+                payload = fs.readFileSync(validatedLocalPath);
+            }
+            catch (e) {
+                throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read local file '${validatedLocalPath}': ${e.message}`, false);
+            }
+            // ---- CRLF auto-fix for shell scripts ----
+            crlfFixed = SSHConnectionManager.maybeFixShellScriptLineEndings(validatedLocalPath, payload);
+            payload = crlfFixed.buffer;
         }
-        // ---- CRLF auto-fix for shell scripts ----
-        const crlfFixed = SSHConnectionManager.maybeFixShellScriptLineEndings(validatedLocalPath, payload);
-        payload = crlfFixed.buffer;
         const crlfNote = crlfFixed.fixed
             ? ` (CRLF→LF auto-fix: converted ${crlfFixed.replacedCount} line endings to LF before upload because target is a shell script).`
             : "";
-        const client = await this.ensureConnected(resolvedName);
-        // ---- Skip-if-identical check ----
-        const isShellScript = SSHConnectionManager.SHELL_SCRIPT_EXTENSIONS.has(path.extname(validatedLocalPath).toLowerCase());
-        if (skipIfIdentical) {
-            const decision = await this.shouldSkipUpload(client, payload, validatedRemotePath, isShellScript);
-            if (decision.skip) {
-                return (`Upload skipped: remote file '${validatedRemotePath}' is already identical to local ` +
-                    `'${validatedLocalPath}' (${decision.reason}).${crlfNote}`);
+        debug?.(`[mcp] sftp upload on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            const client = connection.client;
+            // ---- Skip-if-identical check ----
+            if (skipIfIdentical) {
+                const decision = await this.shouldSkipUpload(client, payload, validatedRemotePath, isShellScript, options?.timeout, debug);
+                if (decision.skip) {
+                    return this.appendDebugOutput(`Upload skipped: remote file '${validatedRemotePath}' is already identical to local ` +
+                        `'${validatedLocalPath}' (${decision.reason}).${crlfNote}`, debugCollector);
+                }
+            }
+            // ---- Actually upload ----
+            if (fastUpload && !crlfFixed.fixed) {
+                await this.sftpFastPut(client, validatedLocalPath, validatedRemotePath, options, options?.timeout, debug);
+            }
+            else {
+                await this.sftpWriteBuffer(client, validatedRemotePath, payload, options?.timeout, debug);
             }
+            const uploadedBytes = payload?.length ?? stat.size;
+            const modeNote = fastUpload && !crlfFixed.fixed ? " via fast SFTP" : "";
+            return this.appendDebugOutput(`File uploaded successfully (${uploadedBytes} bytes${modeNote})${crlfNote}`, debugCollector);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
         }
-        // ---- Actually upload ----
-        await this.sftpWriteBuffer(client, validatedRemotePath, payload);
-        return `File uploaded successfully (${payload.length} bytes)${crlfNote}`;
     }
     /**
      * Threshold above which we use MD5 hash comparison instead of byte-content
@@ -1822,10 +1931,10 @@ export class SSHConnectionManager {
      * Any error during the check is treated as 'don't skip' (i.e. fall through
      * to a normal upload), since correctness wins over an optimization.
      */
-    async shouldSkipUpload(client, localPayload, remotePath, lineEndingAgnostic) {
+    async shouldSkipUpload(client, localPayload, remotePath, lineEndingAgnostic, timeout, debug) {
         let remoteSize;
         try {
-            const sftp = await this.openSftp(client, "dest");
+            const sftp = await this.openSftp(client, "dest", timeout, debug);
             try {
                 const stat = await this.sftpStat(sftp, remotePath, "dest");
                 remoteSize = stat.size;
@@ -1846,7 +1955,7 @@ export class SSHConnectionManager {
             }
             let remoteBuf;
             try {
-                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize);
+                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize, timeout, debug);
             }
             catch {
                 return { skip: false, reason: "remote-read-failed-during-content-compare" };
@@ -1869,7 +1978,7 @@ export class SSHConnectionManager {
             // Byte-content compare
             let remoteBuf;
             try {
-                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize);
+                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize, timeout, debug);
             }
             catch {
                 return { skip: false, reason: "remote-read-failed-during-content-compare" };
@@ -1905,88 +2014,138 @@ export class SSHConnectionManager {
     /**
      * Read an SFTP file fully into a Buffer.
      */
-    async sftpReadBuffer(client, remotePath, expectedSize) {
+    async sftpReadBuffer(client, remotePath, expectedSize, timeout, debug) {
+        const sftp = await this.openSftp(client, "read", timeout, debug);
         return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP open failed: ${err.message}`, true));
+            const chunks = [];
+            let received = 0;
+            const stream = sftp.createReadStream(remotePath);
+            stream.on("data", (chunk) => {
+                chunks.push(chunk);
+                received += chunk.length;
+            });
+            stream.on("error", (e) => {
+                sftp.end();
+                reject(this.makeSftpError("Remote read failed", e));
+            });
+            stream.on("end", () => {
+                sftp.end();
+                if (received !== expectedSize) {
+                    return reject(new ToolError("SFTP_ERROR", `Remote read short: expected ${expectedSize} bytes, got ${received}`, false));
                 }
-                const chunks = [];
-                let received = 0;
-                const stream = sftp.createReadStream(remotePath);
-                stream.on("data", (chunk) => {
-                    chunks.push(chunk);
-                    received += chunk.length;
-                });
-                stream.on("error", (e) => {
-                    sftp.end();
-                    reject(new ToolError("SFTP_ERROR", `Remote read failed: ${e.message}`, false));
-                });
-                stream.on("end", () => {
-                    sftp.end();
-                    if (received !== expectedSize) {
-                        return reject(new ToolError("SFTP_ERROR", `Remote read short: expected ${expectedSize} bytes, got ${received}`, false));
-                    }
-                    resolve(Buffer.concat(chunks, received));
-                });
+                resolve(Buffer.concat(chunks, received));
             });
         });
     }
     /**
      * Write a Buffer to an SFTP path (overwrites if exists).
      */
-    async sftpWriteBuffer(client, remotePath, payload) {
+    async sftpWriteBuffer(client, remotePath, payload, timeout, debug) {
+        const sftp = await this.openSftp(client, "write", timeout, debug);
         return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
+            const writeStream = sftp.createWriteStream(remotePath);
+            writeStream.on("close", () => {
+                sftp.end();
+                resolve();
+            });
+            writeStream.on("error", (e) => {
+                sftp.end();
+                reject(this.makeSftpError("File upload failed", e));
+            });
+            writeStream.end(payload);
+        });
+    }
+    /**
+     * 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);
+        const transferOptions = this.createSftpTransferOptions(options);
+        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) => {
+                sftp.end();
                 if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP open failed: ${err.message}`, true));
+                    reject(this.makeSftpError("Fast upload failed", err));
+                    return;
                 }
-                const writeStream = sftp.createWriteStream(remotePath);
-                writeStream.on("close", () => {
-                    sftp.end();
-                    resolve();
-                });
-                writeStream.on("error", (e) => {
-                    sftp.end();
-                    reject(new ToolError("SFTP_ERROR", `File upload failed: ${e.message}`, false));
-                });
-                writeStream.end(payload);
+                resolve();
+            });
+        });
+    }
+    /**
+     * 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);
+        const transferOptions = this.createSftpTransferOptions(options);
+        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) => {
+                sftp.end();
+                if (err) {
+                    reject(this.makeSftpError("Fast download failed", err));
+                    return;
+                }
+                resolve();
             });
         });
     }
     /**
      * Download file
      */
-    async download(remotePath, localPath, name) {
+    async download(remotePath, localPath, name, options) {
         const resolvedName = name || this.defaultName;
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
         const validatedLocalPath = this.validateLocalPath(localPath, resolvedName);
         const validatedRemotePath = this.validateRemotePath(remotePath, resolvedName);
-        const client = await this.ensureConnected(resolvedName);
-        return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
-                }
+        debug?.(`[mcp] sftp download on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            if (options?.fast === true) {
+                await this.sftpFastGet(connection.client, validatedRemotePath, validatedLocalPath, options, options?.timeout, debug);
+                return this.appendDebugOutput("File downloaded successfully via fast SFTP", debugCollector);
+            }
+            const sftp = await this.openSftp(connection.client, "download", options?.timeout, debug);
+            await new Promise((resolve, reject) => {
+                let settled = false;
                 const readStream = sftp.createReadStream(validatedRemotePath);
                 const writeStream = fs.createWriteStream(validatedLocalPath);
-                const cleanup = () => {
+                const settle = (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (err) {
+                        this.unpipeStream(readStream, writeStream);
+                        this.destroyStream(readStream);
+                        this.destroyStream(writeStream);
+                    }
                     sftp.end();
+                    err ? reject(err) : resolve();
                 };
-                writeStream.on("finish", () => {
-                    cleanup();
-                    resolve("File downloaded successfully");
-                });
-                writeStream.on("error", (err) => {
-                    cleanup();
-                    reject(new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${err.message}`, false));
-                });
-                readStream.on("error", (err) => {
-                    cleanup();
-                    reject(new ToolError("SFTP_ERROR", `File download failed: ${err.message}`, false));
-                });
+                writeStream.on("finish", () => settle());
+                writeStream.on("error", (err) => settle(new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${err.message}`, false)));
+                readStream.on("error", (err) => settle(this.makeSftpError("File download failed", err)));
                 readStream.pipe(writeStream);
             });
-        });
+            return this.appendDebugOutput("File downloaded successfully", debugCollector);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
+        }
     }
     /**
      * Disconnect SSH connection
@@ -2080,11 +2239,30 @@ export class SSHConnectionManager {
         const validatedSourcePath = this.validateRemotePath(sourceRemotePath, sourceName);
         const validatedDestPath = this.validateRemotePath(destRemotePath, destName);
         const skipIfIdentical = options?.skipIfIdentical !== false; // default true
-        const srcClient = await this.ensureConnected(sourceName);
-        const dstClient = await this.ensureConnected(destName);
-        const srcSftp = await this.openSftp(srcClient, "source");
-        const dstSftp = await this.openSftp(dstClient, "dest");
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
+        debug?.(`[mcp] sftp relay ${sourceName} -> ${destName}, reuseConnection=${reuseConnection}`);
+        let srcConnection = null;
+        let dstConnection = null;
+        let srcSftp = null;
+        let dstSftp = null;
         try {
+            srcConnection = await this.acquireSshClient(sourceName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            dstConnection = 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);
+            dstSftp = await this.openSftp(dstClient, "dest", options?.timeout, debug);
             // Get source file size before transfer
             const srcStat = await this.sftpStat(srcSftp, validatedSourcePath, "source");
             // Skip-if-identical: same size on both sides AND matching md5sum (when
@@ -2101,10 +2279,10 @@ export class SSHConnectionManager {
                     if (srcMd5 && dstMd5 && srcMd5 === dstMd5) {
                         const srcConfig = this.getConfig(sourceName);
                         const dstConfig = this.getConfig(destName);
-                        return (`Transfer skipped: destination already identical ` +
+                        return this.appendDebugOutput(`Transfer skipped: destination already identical ` +
                             `(size=${srcStat.size} bytes, md5=${srcMd5}). ` +
                             `${srcConfig.username}@${srcConfig.host}:${validatedSourcePath}` +
-                            ` == ${dstConfig.username}@${dstConfig.host}:${validatedDestPath}`);
+                            ` == ${dstConfig.username}@${dstConfig.host}:${validatedDestPath}`, debugCollector);
                     }
                 }
             }
@@ -2120,11 +2298,16 @@ export class SSHConnectionManager {
                     if (settled)
                         return;
                     settled = true;
+                    if (err) {
+                        this.unpipeStream(readStream, writeStream);
+                        this.destroyStream(readStream);
+                        this.destroyStream(writeStream);
+                    }
                     err ? reject(err) : resolve();
                 };
                 writeStream.on("close", () => settle());
-                writeStream.on("error", (err) => settle(new ToolError("SFTP_ERROR", `Dest write error: ${err.message}`, false)));
-                readStream.on("error", (err) => settle(new ToolError("SFTP_ERROR", `Source read error: ${err.message}`, false)));
+                writeStream.on("error", (err) => settle(this.makeSftpError("Dest write error", err)));
+                readStream.on("error", (err) => settle(this.makeSftpError("Source read error", err)));
                 readStream.pipe(writeStream);
             });
             // --- Verification ---
@@ -2148,13 +2331,22 @@ export class SSHConnectionManager {
             }
             const srcConfig = this.getConfig(sourceName);
             const dstConfig = this.getConfig(destName);
-            return (`Transfer complete (streamed via SFTP, verified: ${verification.join(", ")}): ` +
+            return this.appendDebugOutput(`Transfer complete (streamed via SFTP, verified: ${verification.join(", ")}): ` +
                 `${srcConfig.username}@${srcConfig.host}:${sourceRemotePath}` +
-                ` → ${dstConfig.username}@${dstConfig.host}:${destRemotePath}`);
+                ` → ${dstConfig.username}@${dstConfig.host}:${destRemotePath}`, debugCollector);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(sourceName, true);
+                this.closeClient(destName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
         }
         finally {
-            srcSftp.end();
-            dstSftp.end();
+            srcSftp?.end();
+            dstSftp?.end();
+            srcConnection?.close();
+            dstConnection?.close();
         }
     }
     /**
@@ -2164,7 +2356,7 @@ export class SSHConnectionManager {
         return new Promise((resolve, reject) => {
             sftp.stat(remotePath, (err, stats) => {
                 if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `Failed to stat ${label} file: ${err.message}`, false));
+                    return reject(this.makeSftpError(`Failed to stat ${label} file`, err));
                 }
                 resolve({ size: stats.size });
             });
@@ -2201,40 +2393,68 @@ export class SSHConnectionManager {
     /**
      * Open an SFTP session from an existing SSH client.
      */
-    openSftp(client, label) {
-        return new Promise((resolve, reject) => {
+    openSftp(client, label, timeout, debug) {
+        const open = new Promise((resolve, reject) => {
             client.sftp((err, sftp) => {
                 if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed (${label}): ${err.message}`, true));
+                    return reject(this.makeSftpError(`SFTP connection failed (${label})`, err));
                 }
+                debug?.(`[mcp] sftp channel opened (${label})`);
                 resolve(sftp);
             });
         });
+        return this.withConnectionTimeout(open, this.normalizeConnectTimeout(timeout), `SFTP channel open (${label})`, debug, undefined, (sftp) => {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        });
     }
     /**
      * List remote files/directories via SFTP readdir
      */
-    async listRemoteDir(remotePath, name) {
-        const client = await this.ensureConnected(name);
-        return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
-                }
-                sftp.readdir(remotePath, (err, list) => {
-                    sftp.end();
-                    if (err) {
-                        return reject(new ToolError("SFTP_ERROR", `Failed to list remote directory: ${err.message}`, false));
-                    }
-                    const entries = list.map((entry) => ({
-                        filename: entry.filename,
-                        isDirectory: (entry.attrs.mode & 0o40000) !== 0,
-                        size: entry.attrs.size,
-                    }));
-                    resolve(entries);
-                });
+    async listRemoteDir(remotePath, name, options) {
+        const resolvedName = name || this.defaultName;
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
+        debug?.(`[mcp] sftp list on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
             });
-        });
+            const entries = await new Promise((resolve, reject) => {
+                this.openSftp(connection.client, "list", options?.timeout, debug).then((sftp) => {
+                    sftp.readdir(remotePath, (err, list) => {
+                        sftp.end();
+                        if (err) {
+                            return reject(this.makeSftpError("Failed to list remote directory", err));
+                        }
+                        const entries = list.map((entry) => ({
+                            filename: entry.filename,
+                            isDirectory: (entry.attrs.mode & 0o40000) !== 0,
+                            size: entry.attrs.size,
+                        }));
+                        resolve(entries);
+                    });
+                }, reject);
+            });
+            return entries;
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
+        }
     }
     /**
      * Upload a local directory recursively to a remote server
@@ -2247,8 +2467,28 @@ export class SSHConnectionManager {
             throw new ToolError("LOCAL_FILE_READ_FAILED", `Not a directory: ${localDir}`, false);
         }
         const results = [];
-        const client = await this.ensureConnected(resolvedName);
-        await this.sftpMkdirRecursive(client, validatedRemoteDir);
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
+        debug?.(`[mcp] sftp recursive upload mkdir on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            await this.sftpMkdirRecursive(connection.client, validatedRemoteDir, options?.timeout, debug);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
+        }
         const entries = fs.readdirSync(resolvedLocal, { withFileTypes: true });
         for (const entry of entries) {
             const localPath = path.join(localDir, entry.name);
@@ -2267,7 +2507,7 @@ export class SSHConnectionManager {
     /**
      * Download a remote directory recursively to a local path
      */
-    async downloadDirectory(remoteDir, localDir, name) {
+    async downloadDirectory(remoteDir, localDir, name, options) {
         const resolvedName = name || this.defaultName;
         const resolvedLocal = this.validateLocalPath(localDir, resolvedName);
         const validatedRemoteDir = this.validateRemotePath(remoteDir, resolvedName);
@@ -2275,18 +2515,18 @@ export class SSHConnectionManager {
             fs.mkdirSync(resolvedLocal, { recursive: true });
         }
         const results = [];
-        const entries = await this.listRemoteDir(validatedRemoteDir, resolvedName);
+        const entries = await this.listRemoteDir(validatedRemoteDir, resolvedName, options);
         for (const entry of entries) {
             if (entry.filename === "." || entry.filename === "..")
                 continue;
             const remotePath = `${validatedRemoteDir}/${entry.filename}`;
             const localPath = path.join(localDir, entry.filename);
             if (entry.isDirectory) {
-                const subResults = await this.downloadDirectory(remotePath, localPath, resolvedName);
+                const subResults = await this.downloadDirectory(remotePath, localPath, resolvedName, options);
                 results.push(...subResults);
             }
             else {
-                await this.download(remotePath, localPath, resolvedName);
+                await this.download(remotePath, localPath, resolvedName, options);
                 results.push(localPath);
             }
         }
@@ -2295,27 +2535,23 @@ export class SSHConnectionManager {
     /**
      * Create remote directory recursively via SFTP
      */
-    async sftpMkdirRecursive(client, remotePath) {
-        return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
+    async sftpMkdirRecursive(client, remotePath, timeout, debug) {
+        const sftp = await this.openSftp(client, "mkdir", timeout, debug);
+        return new Promise((resolve) => {
+            const parts = remotePath.split("/").filter(Boolean);
+            let current = "";
+            const mkdirNext = (index) => {
+                if (index >= parts.length) {
+                    sftp.end();
+                    return resolve();
                 }
-                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, (err) => {
-                        // EEXIST is fine
-                        mkdirNext(index + 1);
-                    });
-                };
-                mkdirNext(0);
-            });
+                current += "/" + parts[index];
+                sftp.mkdir(current, () => {
+                    // EEXIST is fine
+                    mkdirNext(index + 1);
+                });
+            };
+            mkdirNext(0);
         });
     }
 }

package/build/tools/download.js

@@ -11,10 +11,23 @@ export function registerDownloadTool(server) {
         remotePath: z.string().describe("Path to the file on the remote server. Must be an absolute POSIX path (e.g. /var/log/app.log); restricted to allowedRemoteDirectories only if the server configures that list."),
         localPath: z.string().describe("Destination path on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
         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 ({ remotePath, localPath, connectionName }) => {
+        reuseConnection: z.boolean().optional().describe("Default true. Reuse the cached SSH connection for SFTP. Set false after a timeout or suspected stale cached SSH connection to force a fresh TCP/SSH connection for this transfer; the fresh connection closes afterwards."),
+        timeout: z.number().positive().optional().describe("Timeout in ms for SSH setup and SFTP channel opening. Transfer stream duration itself is not forcibly interrupted by this option."),
+        vvv: z.boolean().optional().describe("Default false. Append bounded SSH/SFTP debug output. For fresh ssh2 handshake logs, also set reuseConnection=false."),
+        fast: z.boolean().optional().describe("Default false. When true, use ssh2 fastGet for a single-file download, which performs parallel SFTP reads for better throughput."),
+        sftpConcurrency: z.number().int().positive().optional().describe("Only used when fast=true. Number of concurrent SFTP chunks for ssh2 fastGet; omitted uses ssh2's default."),
+        chunkSize: z.number().int().positive().optional().describe("Only used when fast=true. Chunk size in bytes for ssh2 fastGet; omitted uses ssh2's default."),
+    }, async ({ remotePath, localPath, connectionName, reuseConnection, timeout, vvv, fast, sftpConcurrency, chunkSize }) => {
         try {
             const resolvedName = sshManager.resolveServer(connectionName);
-            const result = await sshManager.download(remotePath, localPath, resolvedName);
+            const result = await sshManager.download(remotePath, localPath, resolvedName, {
+                reuseConnection,
+                timeout,
+                vvv,
+                fast,
+                sftpConcurrency,
+                chunkSize,
+            });
             return {
                 content: [{ type: "text", text: result }],
             };

package/build/tools/help.js

@@ -75,29 +75,52 @@ Examples:
 Parameters:
   localPath       (string, required)   File path on the MCP host.
                   Must be inside the MCP working directory.
-  remotePath      (string, required)   Destination path on the remote server.
-  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.
-
-Example:
-  upload { localPath: "data.csv", remotePath: "/tmp/data.csv" }`,
+  remotePath      (string, required)   Destination path on the remote server.
+  connectionName  (string, see below)  Target server name from list-servers.
+  skipIfIdentical (boolean, optional)  Default true. Skip when remote matches.
+  reuseConnection (boolean, optional)  Default true. Set false after timeout
+                  or suspected stale cached SSH connection.
+  timeout         (number, optional)   SSH setup and SFTP channel-open timeout.
+  vvv             (boolean, optional)  Default false. Append bounded SSH/SFTP debug.
+                  Recursive success returns structured JSON; debug is surfaced
+                  for single-file results, relay results, and recursive errors.
+  fast            (boolean, optional)  Default false. Use ssh2 fastPut for
+                  single-file upload throughput. Not multi-file concurrency.
+  sftpConcurrency (number, optional)   Only with fast=true. Concurrent SFTP chunks.
+  chunkSize       (number, optional)   Only with fast=true. SFTP chunk bytes.
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Example:
+  upload { localPath: "data.csv", remotePath: "/tmp/data.csv" }
+  upload { localPath: "big.bin", remotePath: "/tmp/big.bin", fast: true,
+           sftpConcurrency: 32, chunkSize: 131072 }`,
     "download": `download — Download a single file from a remote server over SFTP.
 
 Parameters:
-  remotePath      (string, required)   File path on the remote server.
-  localPath       (string, required)   Destination on the MCP host.
-                  Must be inside the MCP working directory.
-  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.
-
-Example:
-  download { remotePath: "/var/log/app.log", localPath: "app.log" }`,
+  remotePath      (string, required)   File path on the remote server.
+  localPath       (string, required)   Destination on the MCP host.
+                  Must be inside the MCP working directory.
+  connectionName  (string, see below)  Target server name from list-servers.
+  reuseConnection (boolean, optional)  Default true. Set false after timeout
+                  or suspected stale cached SSH connection.
+  timeout         (number, optional)   SSH setup and SFTP channel-open timeout.
+  vvv             (boolean, optional)  Default false. Append bounded SSH/SFTP debug.
+  fast            (boolean, optional)  Default false. Use ssh2 fastGet for
+                  single-file download throughput. Not multi-file concurrency.
+  sftpConcurrency (number, optional)   Only with fast=true. Concurrent SFTP chunks.
+  chunkSize       (number, optional)   Only with fast=true. SFTP chunk bytes.
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Example:
+  download { remotePath: "/var/log/app.log", localPath: "app.log" }
+  download { remotePath: "/tmp/big.bin", localPath: "big.bin", fast: true,
+             sftpConcurrency: 32, chunkSize: 131072 }`,
     "transfer": `transfer — Move files between hosts (single/recursive/cross-server).
 
 Modes:
@@ -112,15 +135,28 @@ Parameters for upload / download:
   mode            (string, required)   "upload" or "download"
   localPath       (string, required)   Path on the MCP host.
   remotePath      (string, required)   Path on the remote server.
-  connectionName  (string, see below)  Target server name.
-  recursive       (boolean, optional)  True to transfer a whole directory tree.
-
-Parameters for relay:
+  connectionName  (string, see below)  Target server name.
+  recursive       (boolean, optional)  True to transfer a whole directory tree.
+  reuseConnection (boolean, optional)  Default true. Set false after timeout.
+  timeout         (number, optional)   SSH setup and SFTP channel-open timeout.
+  vvv             (boolean, optional)  Default false. Append bounded SSH/SFTP debug.
+  fast            (boolean, optional)  Default false. upload/download only:
+                  use ssh2 fastPut/fastGet for each single file. Directory
+                  recursion stays sequential; no multi-file concurrency.
+  sftpConcurrency (number, optional)   Only with fast=true. Concurrent SFTP chunks.
+  chunkSize       (number, optional)   Only with fast=true. SFTP chunk bytes.
+
+Parameters for relay:
   mode              (string, required)   "relay"
   sourceServer      (string, required)   Server name to read from.
-  sourceRemotePath  (string, required)   File path on source server.
-  destServer        (string, required)   Server name to write to.
-  destRemotePath    (string, required)   File path on dest server.
+  sourceRemotePath  (string, required)   File path on source server.
+  destServer        (string, required)   Server name to write to.
+  destRemotePath    (string, required)   File path on dest server.
+  reuseConnection   (boolean, optional)  Default true. Set false after timeout.
+  timeout           (number, optional)   SSH setup and SFTP channel-open timeout.
+  vvv               (boolean, optional)  Default false. Append bounded SSH/SFTP debug.
+  fast              (boolean, optional)  Accepted but relay keeps the streaming
+                    SFTP pipe path; fastGet/fastPut apply to host<->remote only.
 
 connectionName rule (upload/download):
   • If only one server is enabled → optional.

package/build/tools/transfer.js

@@ -37,22 +37,28 @@ For relay mode, specify sourceServer, sourceRemotePath, destServer, destRemotePa
             "Upload: byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts (.sh / .bash / .zsh) ignore CRLF\u2194LF differences. " +
             "Relay: size match + md5sum match on both servers (when available); falls back to transferring if md5sum is missing on either side. " +
             "Download is never skipped. Set to false to force the transfer."),
+        reuseConnection: z.boolean().optional().describe("Default true. Reuse cached SSH connection(s) for SFTP. Set false after a timeout or suspected stale cached connection to force fresh TCP/SSH connection(s) for this transfer; fresh connections close afterwards."),
+        timeout: z.number().positive().optional().describe("Timeout in ms for SSH setup and SFTP channel opening. Transfer stream duration itself is not forcibly interrupted by this option."),
+        vvv: z.boolean().optional().describe("Default false. Append bounded SSH/SFTP debug output for single-file and relay results, and for recursive errors. For fresh ssh2 handshake logs, also set reuseConnection=false."),
+        fast: z.boolean().optional().describe("Default false. Upload/download only: use ssh2 fastPut/fastGet for single files, with parallel SFTP chunks for better throughput. Relay mode keeps the streaming pipe path."),
+        sftpConcurrency: z.number().int().positive().optional().describe("Only used when fast=true for upload/download. Number of concurrent SFTP chunks; omitted uses ssh2's default."),
+        chunkSize: z.number().int().positive().optional().describe("Only used when fast=true for upload/download. Chunk size in bytes; omitted uses ssh2's default."),
     }, async (params) => {
         try {
             const { mode } = params;
             if (mode === "relay") {
-                const { sourceServer, sourceRemotePath, destServer, destRemotePath, skipIfIdentical } = params;
+                const { sourceServer, sourceRemotePath, destServer, destRemotePath, skipIfIdentical, reuseConnection, timeout, vvv } = params;
                 if (!sourceServer || !sourceRemotePath || !destServer || !destRemotePath) {
                     return {
                         content: [{ type: "text", text: "relay mode requires: sourceServer, sourceRemotePath, destServer, destRemotePath" }],
                         isError: true,
                     };
                 }
-                const result = await sshManager.transferBetweenServers(sourceServer, sourceRemotePath, destServer, destRemotePath, { skipIfIdentical: skipIfIdentical !== false });
+                const result = await sshManager.transferBetweenServers(sourceServer, sourceRemotePath, destServer, destRemotePath, { skipIfIdentical: skipIfIdentical !== false, reuseConnection, timeout, vvv });
                 return { content: [{ type: "text", text: result }] };
             }
             // upload or download
-            const { localPath, remotePath, connectionName, recursive, skipIfIdentical } = params;
+            const { localPath, remotePath, connectionName, recursive, skipIfIdentical, reuseConnection, timeout, vvv, fast, sftpConcurrency, chunkSize } = params;
             if (!localPath || !remotePath) {
                 return {
                     content: [{ type: "text", text: `${mode} mode requires: localPath, remotePath` }],
@@ -60,14 +66,15 @@ For relay mode, specify sourceServer, sourceRemotePath, destServer, destRemotePa
                 };
             }
             const resolvedName = sshManager.resolveServer(connectionName);
-            const uploadOptions = { skipIfIdentical: skipIfIdentical !== false };
+            const sftpOptions = { reuseConnection, timeout, vvv, fast, sftpConcurrency, chunkSize };
+            const uploadOptions = { skipIfIdentical: skipIfIdentical !== false, ...sftpOptions };
             if (recursive) {
                 let files;
                 if (mode === "upload") {
                     files = await sshManager.uploadDirectory(localPath, remotePath, resolvedName, uploadOptions);
                 }
                 else {
-                    files = await sshManager.downloadDirectory(remotePath, localPath, resolvedName);
+                    files = await sshManager.downloadDirectory(remotePath, localPath, resolvedName, sftpOptions);
                 }
                 const summary = `Recursive ${mode} complete. ${files.length} file(s) transferred.`;
                 return {
@@ -80,7 +87,7 @@ For relay mode, specify sourceServer, sourceRemotePath, destServer, destRemotePa
                 return { content: [{ type: "text", text: result }] };
             }
             else {
-                const result = await sshManager.download(remotePath, localPath, resolvedName);
+                const result = await sshManager.download(remotePath, localPath, resolvedName, sftpOptions);
                 return { content: [{ type: "text", text: result }] };
             }
         }

package/build/tools/upload.js

@@ -14,11 +14,23 @@ export function registerUploadTool(server) {
         remotePath: z.string().describe("Destination path on the remote server. Must be an absolute POSIX path (e.g. /home/user/uploads/file.txt); restricted to allowedRemoteDirectories only if the server configures that list."),
         connectionName: z.string().optional().describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
         skipIfIdentical: z.boolean().optional().describe("When true (default), skip the upload if the remote file is already identical (byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts ignore CRLF\u2194LF differences). Set to false to force re-upload."),
-    }, async ({ localPath, remotePath, connectionName, skipIfIdentical }) => {
+        reuseConnection: z.boolean().optional().describe("Default true. Reuse the cached SSH connection for SFTP. Set false after a timeout or suspected stale cached SSH connection to force a fresh TCP/SSH connection for this transfer; the fresh connection closes afterwards."),
+        timeout: z.number().positive().optional().describe("Timeout in ms for SSH setup and SFTP channel opening. Transfer stream duration itself is not forcibly interrupted by this option."),
+        vvv: z.boolean().optional().describe("Default false. Append bounded SSH/SFTP debug output. For fresh ssh2 handshake logs, also set reuseConnection=false."),
+        fast: z.boolean().optional().describe("Default false. When true, use ssh2 fastPut for a single-file upload, which performs parallel SFTP reads/writes for better throughput. If a shell script needs CRLF-to-LF conversion, the upload falls back to the normal safe path."),
+        sftpConcurrency: z.number().int().positive().optional().describe("Only used when fast=true. Number of concurrent SFTP chunks for ssh2 fastPut; omitted uses ssh2's default."),
+        chunkSize: z.number().int().positive().optional().describe("Only used when fast=true. Chunk size in bytes for ssh2 fastPut; omitted uses ssh2's default."),
+    }, async ({ localPath, remotePath, connectionName, skipIfIdentical, reuseConnection, timeout, vvv, fast, sftpConcurrency, chunkSize }) => {
         try {
             const resolvedName = sshManager.resolveServer(connectionName);
             const result = await sshManager.upload(localPath, remotePath, resolvedName, {
                 skipIfIdentical: skipIfIdentical !== false,
+                reuseConnection,
+                timeout,
+                vvv,
+                fast,
+                sftpConcurrency,
+                chunkSize,
             });
             return {
                 content: [{ type: "text", text: result }],

package/package.json

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