@aaarc/handfree-ssh-mcp 1.0.6 → 1.0.9

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/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/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.9",
   "description": "Handfree SSH MCP Server - A hands-free SSH automation tool via MCP protocol",
   "main": "build/index.js",
   "type": "module",