@aaarc/handfree-ssh-mcp 1.0.4 → 1.0.6

package/build/tools/close-connection.js

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

package/build/tools/download.js

@@ -7,8 +7,8 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
  */
 export function registerDownloadTool(server) {
     const sshManager = SSHConnectionManager.getInstance();
-    server.tool("download", "Download a file from the remote server to the MCP host over SFTP. Use this when you need to inspect or save a remote file locally. The remote source must live inside one of the server's allowedRemoteDirectories; call show-whitelist to discover the allowed paths.", {
-        remotePath: z.string().describe("Path to the file on the remote server. Must be an absolute POSIX path inside one of the server's allowedRemoteDirectories (e.g. /var/log/app.log)."),
+    server.tool("download", "Download a file from the remote server to the MCP host over SFTP. Use this when you need to inspect or save a remote file locally. By default any absolute remote path is allowed; if the server configures allowedRemoteDirectories, the source must live inside one of those entries — call show-whitelist to check.", {
+        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 }) => {

package/build/tools/execute-command.js

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

package/build/tools/help.js

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

package/build/tools/index.js

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

package/build/tools/show-whitelist.js

@@ -100,15 +100,18 @@ export function registerShowWhitelistTool(server) {
             const allowedLocalDirs = config.allowedLocalDirectories ?? [];
             const mcpCwd = process.cwd();
             output += `## 📂 SFTP Path Policy (upload / download / transfer)\n\n`;
+            if (config.disableSftpPathPolicy) {
+                output += `**\`disableSftpPathPolicy\` is set — all path containment checks below are bypassed.** ` +
+                    `Any absolute remote path and any local path is allowed for upload/download/transfer.\n\n`;
+            }
             // ----- Remote directories -----
             output += `### Allowed remote directories\n\n`;
-            if (allowedRemoteDirs.length === 0) {
-                output += `⚠️ **\`allowedRemoteDirectories\` is NOT configured.** ` +
-                    `SFTP upload/download/transfer is **disabled** for this server — every call will be rejected with \`REMOTE_PATH_NOT_ALLOWED\`. ` +
-                    `To enable file transfer, add absolute POSIX directories under \`allowedRemoteDirectories\` in the server's YAML config.\n\n`;
+            if (config.disableSftpPathPolicy || allowedRemoteDirs.length === 0) {
+                output += `\`allowedRemoteDirectories\` is not configured, so **any absolute POSIX path is allowed** (default is open). ` +
+                    `To restrict SFTP to specific directories, add them under \`allowedRemoteDirectories\` in the server's YAML config.\n\n`;
             }
             else {
-                output += `${allowedRemoteDirs.length} entr${allowedRemoteDirs.length === 1 ? "y" : "ies"}:\n\n`;
+                output += `${allowedRemoteDirs.length} entr${allowedRemoteDirs.length === 1 ? "y" : "ies"} (restricting SFTP to these paths only):\n\n`;
                 for (const dir of allowedRemoteDirs) {
                     output += `- \`${dir}\`\n`;
                 }
@@ -116,24 +119,31 @@ export function registerShowWhitelistTool(server) {
             }
             // ----- Local directories -----
             output += `### Allowed local directories\n\n`;
-            output += `Always implicitly allowed: \`${mcpCwd}\` _(the MCP working directory)_\n\n`;
-            if (allowedLocalDirs.length === 0) {
-                output += `⚠️ **\`allowedLocalDirectories\` is NOT configured.** ` +
-                    `Only paths inside the MCP working directory above can be used as the local side of upload/download — any other path will be rejected with \`LOCAL_PATH_NOT_ALLOWED\`. ` +
-                    `To allow more locations, add absolute host paths under \`allowedLocalDirectories\` in the server's YAML config.\n\n`;
+            if (config.disableSftpPathPolicy) {
+                output += `\`disableSftpPathPolicy\` is set, so **any local path is allowed**.\n\n`;
             }
             else {
-                output += `Additional entries (${allowedLocalDirs.length}):\n\n`;
-                for (const dir of allowedLocalDirs) {
-                    output += `- \`${dir}\`\n`;
+                output += `Always implicitly allowed: \`${mcpCwd}\` _(the MCP working directory)_\n\n`;
+                if (allowedLocalDirs.length === 0) {
+                    output += `\`allowedLocalDirectories\` is not configured. ` +
+                        `Only paths inside the MCP working directory above can be used as the local side of upload/download — any other path will be rejected with \`LOCAL_PATH_NOT_ALLOWED\`. ` +
+                        `To allow more locations, add absolute host paths under \`allowedLocalDirectories\`, or set \`disableSftpPathPolicy: true\` to allow any local path.\n\n`;
+                }
+                else {
+                    output += `Additional entries (${allowedLocalDirs.length}):\n\n`;
+                    for (const dir of allowedLocalDirs) {
+                        output += `- \`${dir}\`\n`;
+                    }
+                    output += `\n`;
                 }
-                output += `\n`;
             }
             // ----- Matching rules -----
             output += `### Matching rules\n\n`;
-            output += `- A path is allowed iff it equals an entry above, or starts with \`<entry> + separator\`.\n`;
-            output += `- Remote paths must be absolute POSIX (\`/...\`); \`..\` segments and null bytes are rejected up-front.\n`;
-            output += `- Local paths are resolved on the MCP host first, then matched.\n`;
+            output += `- Default is open: with no \`allowedRemoteDirectories\` configured, any absolute POSIX remote path is allowed.\n`;
+            output += `- Configuring \`allowedRemoteDirectories\` opts into an allowlist — a path is then allowed iff it equals an entry, or starts with \`<entry> + separator\`.\n`;
+            output += `- \`disableSftpPathPolicy: true\` bypasses both the remote allowlist and the local directory check entirely.\n`;
+            output += `- Remote paths must be absolute POSIX (\`/...\`); \`..\` segments and null bytes are rejected up-front regardless of policy.\n`;
+            output += `- Local paths are resolved on the MCP host first, then matched (unless \`disableSftpPathPolicy\` is set).\n`;
             output += `- These path lists do **not** affect \`execute-command\`. They only restrict SFTP file transfers.\n\n`;
             // ----- Output log policy (execute-command full-output persistence) -----
             const outputLogRoot = sshManager.getOutputLogRoot();

package/build/tools/transfer.js

@@ -26,12 +26,12 @@ Set recursive=true when transferring a directory (upload/download only).
 For relay mode, specify sourceServer, sourceRemotePath, destServer, destRemotePath.`, {
         mode: z.enum(["upload", "download", "relay"]).describe("'upload' pushes local → remote. 'download' pulls remote → local. 'relay' copies remote-A → remote-B through the MCP host."),
         localPath: z.string().optional().describe("(upload/download only) Path on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
-        remotePath: z.string().optional().describe("(upload/download only) Absolute POSIX path on the remote server. Must live inside one of the server's allowedRemoteDirectories — call show-whitelist to discover the allowed paths."),
+        remotePath: z.string().optional().describe("(upload/download only) Absolute POSIX path on the remote server. Any path is allowed by default; restricted to allowedRemoteDirectories only if the server configures that list — call show-whitelist to check."),
         connectionName: z.string().optional().describe("(upload/download only) Target server name from list-servers. Required when multiple servers are enabled."),
         sourceServer: z.string().optional().describe("(relay only) Server name to download the file from."),
-        sourceRemotePath: z.string().optional().describe("(relay only) Absolute POSIX file path on the source server. Must live inside the source server's allowedRemoteDirectories."),
+        sourceRemotePath: z.string().optional().describe("(relay only) Absolute POSIX file path on the source server. Any path is allowed by default unless the source server configures allowedRemoteDirectories."),
         destServer: z.string().optional().describe("(relay only) Server name to upload the file to."),
-        destRemotePath: z.string().optional().describe("(relay only) Absolute POSIX destination path on the target server. Must live inside the destination server's allowedRemoteDirectories."),
+        destRemotePath: z.string().optional().describe("(relay only) Absolute POSIX destination path on the target server. Any path is allowed by default unless the destination server configures allowedRemoteDirectories."),
         recursive: z.boolean().optional().describe("(upload/download only) When true, transfers an entire directory tree recursively. Default false."),
         skipIfIdentical: z.boolean().optional().describe("When true (default), skip the transfer if the destination already matches the source. " +
             "Upload: byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts (.sh / .bash / .zsh) ignore CRLF\u2194LF differences. " +

package/build/tools/upload.js

@@ -7,11 +7,11 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
  */
 export function registerUploadTool(server) {
     const sshManager = SSHConnectionManager.getInstance();
-    server.tool("upload", "Upload a local file from the MCP host to the remote server over SFTP. Use this when the file already exists locally and must be copied to the selected SSH server. The remote destination must live inside one of the server's allowedRemoteDirectories; call show-whitelist to discover the allowed paths. " +
+    server.tool("upload", "Upload a local file from the MCP host to the remote server over SFTP. Use this when the file already exists locally and must be copied to the selected SSH server. By default any absolute remote path is allowed; if the server configures allowedRemoteDirectories, the destination must live inside one of those entries — call show-whitelist to check. " +
         "Shell scripts (.sh / .bash / .zsh) with CRLF line endings are auto-converted to LF before upload (the response notes when this happens). " +
         "By default the upload is skipped if the remote file is already identical to the local one (byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts are compared in a line-ending-agnostic way so CRLF\u2194LF differences alone do not trigger a re-upload) \u2014 pass skipIfIdentical=false to force a re-upload.", {
         localPath: z.string().describe("Path to a local file on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
-        remotePath: z.string().describe("Destination path on the remote server. Must be an absolute POSIX path inside one of the server's allowedRemoteDirectories (e.g. /home/user/uploads/file.txt)."),
+        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 }) => {

package/package.json

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