@aaarc/handfree-ssh-mcp 1.0.0 → 1.0.2

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

@@ -19,79 +19,35 @@ const CONNECTION_RESET_FIELDS = [
     "identitiesOnly",
     "authOptional",
     "socksProxy",
+    "jumpHost",
 ];
-/**
- * Default command whitelist - only allow safe Linux commands
- * These patterns are regex strings that match allowed commands
- */
-/**
- * Default command whitelist - only allow safe Linux commands
- * These patterns are regex strings that match allowed commands
- *
- * SECURITY: Commands not matching any pattern will be BLOCKED with an error message
- */
-const DEFAULT_COMMAND_WHITELIST = [
-    // Basic file operations (READ-ONLY)
-    "^ls( .*)?$",
-    "^cat .*$",
-    "^head .*$",
-    "^tail .*$",
-    "^less .*$",
-    "^more .*$",
-    "^wc .*$",
-    "^file .*$",
-    "^stat .*$",
-    "^find .*$",
-    "^grep .*$",
-    "^awk .*$",
-    "^sed .*$",
-    // Directory navigation
-    "^pwd$",
-    "^cd .*$",
-    // System info (read-only)
-    "^echo .*$",
-    "^hostname$",
-    "^whoami$",
-    "^id$",
-    "^uname .*$",
-    "^df .*$",
-    "^du .*$",
-    "^free .*$",
-    "^top -bn1.*$",
-    "^ps .*$",
-    "^uptime$",
-    "^date$",
-    "^env$",
-    "^printenv.*$",
-    // Network diagnostics (read-only)
-    "^ping -c \\d+ .*$",
-    "^curl .*$",
-    "^wget .*$",
-    "^netstat .*$",
-    "^ss .*$",
-    "^ip .*$",
-    // Git operations
-    "^git .*$",
-    // Systemctl (read-only)
-    "^systemctl status .*$",
-    "^systemctl list-.*$",
-    "^journalctl .*$",
-    // Docker (read-only)
-    "^docker ps.*$",
-    "^docker logs.*$",
-    "^docker images.*$",
-    "^docker inspect.*$",
-    // ============================================
-    // DANGEROUS COMMANDS - EXPLICITLY BANNED:
-    // - rm, rmdir (delete files/dirs)
-    // - mv (can overwrite/move files)
-    // - cp (can overwrite files)
-    // - chmod, chown (change permissions)
-    // - kill, pkill (terminate processes)
-    // - mkdir, touch (create files/dirs)
-    // - >, >> (redirect/overwrite files)
-    // - wget -O, curl -o (download and overwrite)
-    // ============================================
+export const BUILT_IN_COMMAND_BLACKLIST = [
+    { regex: /^\s*(?:sudo\s+)?(?:reboot|shutdown|halt|poweroff)(?:\s|$)/i, reason: "system power command" },
+    { regex: /\b(?:Restart-Computer|Stop-Computer)\b/i, reason: "Windows power command" },
+    { regex: /^\s*(?:sudo\s+)?(?:init\s+[06]|telinit\s+[06])(?:\s|$)/i, reason: "system runlevel power command" },
+    { regex: /^\s*(?:sudo\s+)?rm\b(?=.*(?:\s--recursive\b|\s-\S*r))(?=.*(?:\s--force\b|\s-\S*f))/i, reason: "recursive force rm" },
+    { regex: /\bRemove-Item\b(?=.*\s-Recurse(?:\s|$))(?=.*\s-Force(?:\s|$))/i, reason: "recursive force Remove-Item" },
+    { regex: /^\s*(?:del|erase|rd)\b(?=.*(?:\/s\b|\s-Recurse(?:\s|$)))(?=.*(?:\/q\b|\s-Force(?:\s|$)))/i, reason: "recursive quiet Windows delete" },
+    { regex: /^\s*(?:sudo\s+)?rmdir\s+(?:\/|\*|~|\$HOME|%USERPROFILE%|[A-Za-z]:\\)(?:\s|$)/i, reason: "dangerous rmdir target" },
+    { regex: /^\s*(?:sudo\s+)?dd\b.*\bof=/i, reason: "dd with of= (can overwrite devices/files)" },
+    { regex: /^\s*(?:sudo\s+)?mkfs(?:\.\S+)?\b/i, reason: "filesystem formatting command" },
+    { regex: /^\s*(?:sudo\s+)?(?:diskpart|format)(?:\s|$)/i, reason: "disk formatting command" },
+    { regex: /\b(?:Format-Volume|Clear-Disk|Remove-Partition)\b/i, reason: "Windows disk destructive command" },
+    { regex: /^\s*(?:sudo\s+)?chmod\s+-R\s+777\b/i, reason: "recursive world-writable chmod" },
+    { regex: /^\s*(?:sudo\s+)?chown\s+-R\s+\S+\s+\/(?:\s|$)/i, reason: "recursive chown on root" },
+];
+export const BUILT_IN_DESTRUCTIVE_GUARDS = [
+    { regex: /\brm\b/, reason: "rm in command chain" },
+    { regex: /\brmdir\b/, reason: "rmdir in command chain" },
+    { regex: /\bunlink\b/, reason: "unlink in command chain" },
+    { regex: /\bshred\b/, reason: "shred in command chain" },
+    { regex: /\btruncate\b/, reason: "truncate in command chain" },
+    { regex: /-delete\b/, reason: "find -delete detected" },
+    { regex: /-exec\s+rm\b/, reason: "find -exec rm detected" },
+    { regex: /\bmv\b/, reason: "mv detected (can overwrite)" },
+    { regex: /\bcp\b.*-f/, reason: "cp -f detected (force overwrite)" },
+    { regex: /(?<![0-9])>\s*\/(?!dev\/null)/, reason: "output redirection to absolute path" },
+    { regex: />\s*~/, reason: "output redirection to home path" },
 ];
 /**
  * SSH Connection Manager class
@@ -108,6 +64,11 @@ export class SSHConnectionManager {
     // concurrent connect attempts so we never create two SSH clients for the
     // same server and leak the loser.
     connecting = new Map();
+    // Dedicated tunneling clients for targets that use a `jumpHost`. Keyed by
+    // target server name (NOT jump name), so each target that jumps through the
+    // same bastion still gets its own jump client. This keeps tunnel lifetimes
+    // tied 1:1 to the target connection and avoids cross-target interference.
+    jumpClients = new Map();
     defaultName = "default";
     enabledServers = null; // null = all servers enabled
     outputLogRoot = null; // null = use <cwd>/.handfree-output at write time
@@ -183,52 +144,6 @@ export class SSHConnectionManager {
     getOutputLogRoot() {
         return this.outputLogRoot ?? path.join(process.cwd(), ".handfree-output");
     }
-    /**
-     * Hot-reload mutable policy fields from a fresh config map.
-     * Only updates whitelist, blacklist, safeDirectory, allowedRemoteDirectories,
-     * and allowedLocalDirectories for servers that already exist. Does NOT touch
-     * SSH connections or credentials.
-     */
-    updatePolicies(freshConfigs) {
-        let changed = 0;
-        for (const [name, existing] of Object.entries(this.configs)) {
-            const fresh = freshConfigs[name];
-            if (!fresh)
-                continue;
-            const wlChanged = JSON.stringify(existing.commandWhitelist) !==
-                JSON.stringify(fresh.commandWhitelist);
-            const blChanged = JSON.stringify(existing.commandBlacklist) !==
-                JSON.stringify(fresh.commandBlacklist);
-            const sdChanged = existing.safeDirectory !== fresh.safeDirectory;
-            const ardChanged = JSON.stringify(existing.allowedRemoteDirectories) !==
-                JSON.stringify(fresh.allowedRemoteDirectories);
-            const aldChanged = JSON.stringify(existing.allowedLocalDirectories) !==
-                JSON.stringify(fresh.allowedLocalDirectories);
-            if (wlChanged || blChanged || sdChanged || ardChanged || aldChanged) {
-                existing.commandWhitelist = fresh.commandWhitelist;
-                existing.commandBlacklist = fresh.commandBlacklist;
-                existing.safeDirectory = fresh.safeDirectory;
-                existing.allowedRemoteDirectories = fresh.allowedRemoteDirectories;
-                existing.allowedLocalDirectories = fresh.allowedLocalDirectories;
-                changed++;
-                const parts = [];
-                if (wlChanged)
-                    parts.push(`whitelist(${(fresh.commandWhitelist ?? []).length})`);
-                if (blChanged)
-                    parts.push(`blacklist(${(fresh.commandBlacklist ?? []).length})`);
-                if (sdChanged)
-                    parts.push(`safeDirectory(${fresh.safeDirectory ?? "none"})`);
-                if (ardChanged)
-                    parts.push(`allowedRemoteDirectories(${(fresh.allowedRemoteDirectories ?? []).length})`);
-                if (aldChanged)
-                    parts.push(`allowedLocalDirectories(${(fresh.allowedLocalDirectories ?? []).length})`);
-                Logger.log(`Hot-reloaded policies for [${name}]: ${parts.join(", ")}`, "info");
-            }
-        }
-        if (changed === 0) {
-            Logger.log("Config file changed but no policy updates detected", "info");
-        }
-    }
     connectionFieldsChanged(oldConfig, nextConfig) {
         return CONNECTION_RESET_FIELDS.some((key) => oldConfig[key] !== nextConfig[key]);
     }
@@ -256,6 +171,7 @@ export class SSHConnectionManager {
             }
             this.clients.delete(name);
         }
+        this.teardownJumpChain(name);
         this.connected.set(name, false);
         this.connecting.delete(name);
     }
@@ -426,6 +342,24 @@ export class SSHConnectionManager {
                 if (agent) {
                     sshConfig.agent = agent;
                 }
+                // Add jump-host tunnel if provided. Mutually exclusive with socksProxy
+                // (enforced at config load time).
+                if (config.jumpHost) {
+                    try {
+                        const sock = await this.openJumpTunnel(key, config);
+                        sshConfig.sock = sock;
+                        Logger.log(`Using jump host '${config.jumpHost}' for [${key}]`, "info");
+                    }
+                    catch (err) {
+                        // A multi-hop chain may have partially connected (e.g. an inner hop
+                        // came up but a later hop or the final forwardOut failed) before
+                        // this rejected. Those already-connected hops were recorded in
+                        // jumpClients as each one came up, so tear them down now instead of
+                        // leaking live SSH sessions until the next connect attempt.
+                        this.teardownJumpChain(key);
+                        return reject(new ToolError("SSH_CONNECTION_FAILED", `Failed to open jump tunnel for [${key}] via '${config.jumpHost}': ${err.message}`, true));
+                    }
+                }
                 // Add SOCKS proxy configuration if provided
                 if (config.socksProxy) {
                     try {
@@ -496,6 +430,162 @@ export class SSHConnectionManager {
         }
         this.clients.set(key, client);
     }
+    /**
+     * Open a TCP tunnel from the target's jump chain to `config.host:config.port`
+     * and return the duplex stream to be used as `sock` for the target SSH client.
+     *
+     * Supports chained jumps to any depth: `target -> J1 -> J2 -> ...` where each
+     * hop's `jumpHost` names the next hop. The chain is built innermost-first —
+     * the deepest, directly-reachable hop connects normally, and each outer hop is
+     * connected through the previous hop's forwarded stream.
+     *
+     * Every hop's SSH client is cached (in order) under the target key so the whole
+     * chain can be torn down with the target connection. A hop's own client tracked
+     * in `this.clients` is intentionally NOT reused — jump usage and direct tool
+     * calls against a bastion stay isolated.
+     * @private
+     */
+    async openJumpTunnel(targetKey, config) {
+        // Tear down any stale jump chain for this target before opening a new one.
+        this.teardownJumpChain(targetKey);
+        this.jumpClients.set(targetKey, []);
+        const jumpClient = await this.connectJumpChain(targetKey, config.jumpHost);
+        return this.forwardOutStream(jumpClient, config.host, config.port);
+    }
+    /**
+     * Recursively connect the SSH client for `jumpName`, tunneling through its own
+     * `jumpHost` first when set. Each connected hop is appended (innermost-first)
+     * to the target's jump-client chain. Returns the connected client for this hop.
+     * @private
+     */
+    async connectJumpChain(targetKey, jumpName) {
+        const jumpConfig = this.configs[jumpName];
+        if (!jumpConfig) {
+            // Should be caught at config load, but guard at runtime too.
+            throw new Error(`jump host '${jumpName}' not found in config`);
+        }
+        // If this hop is itself reached through another jump, build that inner
+        // tunnel first and hand its stream to this hop as `sock`.
+        let sock;
+        if (jumpConfig.jumpHost) {
+            const innerClient = await this.connectJumpChain(targetKey, jumpConfig.jumpHost);
+            sock = await this.forwardOutStream(innerClient, jumpConfig.host, jumpConfig.port);
+        }
+        const jumpClient = await this.connectJumpClient(targetKey, jumpName, jumpConfig, sock);
+        const chain = this.jumpClients.get(targetKey);
+        if (chain) {
+            chain.push(jumpClient);
+        }
+        else {
+            this.jumpClients.set(targetKey, [jumpClient]);
+        }
+        return jumpClient;
+    }
+    /**
+     * Connect a single jump-host SSH client, optionally through `sock` (the stream
+     * from the previous hop). Wires a close handler that tears the whole target
+     * chain down so a dead hop surfaces as a clear failure on the next op.
+     * @private
+     */
+    connectJumpClient(targetKey, jumpName, jumpConfig, sock) {
+        return new Promise((resolve, reject) => {
+            const jumpClient = new Client();
+            jumpClient.on("ready", () => resolve(jumpClient));
+            jumpClient.on("error", (err) => {
+                reject(new Error(`jump SSH connect failed for '${jumpName}': ${err.message}`));
+            });
+            jumpClient.on("close", () => {
+                // If any hop dies, kill the target too so callers get a clear failure on
+                // the next op and reconnect through a fresh chain.
+                this.teardownTargetViaJump(targetKey);
+            });
+            const jumpSsh = {
+                host: jumpConfig.host,
+                port: jumpConfig.port,
+                username: jumpConfig.username,
+            };
+            if (sock) {
+                jumpSsh.sock = sock;
+            }
+            const jumpAgent = jumpConfig.agent === false
+                ? undefined
+                : jumpConfig.agent || (jumpConfig.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
+            if (jumpAgent) {
+                jumpSsh.agent = jumpAgent;
+            }
+            if (jumpConfig.privateKey) {
+                try {
+                    jumpSsh.privateKey = fs.readFileSync(jumpConfig.privateKey, "utf8");
+                    if (jumpConfig.passphrase)
+                        jumpSsh.passphrase = jumpConfig.passphrase;
+                }
+                catch (err) {
+                    return reject(new Error(`read jump private key failed: ${err.message}`));
+                }
+            }
+            else if (jumpConfig.password) {
+                jumpSsh.password = jumpConfig.password;
+            }
+            else if (jumpAgent || jumpConfig.authOptional) {
+                Logger.log(`Using SSH agent/default authentication for jump host '${jumpName}'`, "info");
+            }
+            else {
+                return reject(new Error(`jump host '${jumpName}' has no password, privateKey, or default authentication`));
+            }
+            jumpClient.connect(jumpSsh);
+        });
+    }
+    /**
+     * Open a forwarded TCP stream from `client` to `host:port`.
+     * @private
+     */
+    forwardOutStream(client, host, port) {
+        return new Promise((resolve, reject) => {
+            client.forwardOut("127.0.0.1", 0, host, port, (err, ch) => {
+                if (err)
+                    return reject(err);
+                resolve(ch);
+            });
+        });
+    }
+    /**
+     * End and forget every jump client in a target's chain (no target teardown).
+     * @private
+     */
+    teardownJumpChain(targetKey) {
+        const chain = this.jumpClients.get(targetKey);
+        if (!chain) {
+            return;
+        }
+        this.jumpClients.delete(targetKey);
+        for (const client of chain) {
+            try {
+                client.end();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /**
+     * Tear the target connection and its whole jump chain down together. Idempotent
+     * so re-entrant close events (ending one hop closes the next) settle quietly.
+     * @private
+     */
+    teardownTargetViaJump(targetKey) {
+        const chain = this.jumpClients.get(targetKey);
+        const target = this.clients.get(targetKey);
+        if (!chain && !target) {
+            return; // already torn down
+        }
+        this.connected.set(targetKey, false);
+        if (target) {
+            this.clients.delete(targetKey);
+            try {
+                target.end();
+            }
+            catch { /* ignore */ }
+        }
+        this.teardownJumpChain(targetKey);
+    }
     /**
      * Get SSH Client with specified name
      */
@@ -604,23 +694,7 @@ export class SSHConnectionManager {
      */
     getDestructiveMatch(command) {
         // This catches: "cd /; rm -rf *", "echo test && rm file", "$(rm file)", and risky writes like "> /etc/..."
-        const destructivePatterns = [
-            { regex: /\brm\b/, reason: "rm in command chain" },
-            { regex: /\brmdir\b/, reason: "rmdir in command chain" },
-            { regex: /\bunlink\b/, reason: "unlink in command chain" },
-            { regex: /\bshred\b/, reason: "shred in command chain" },
-            { regex: /\btruncate\b/, reason: "truncate in command chain" },
-            { regex: /-delete\b/, reason: "find -delete detected" },
-            { regex: /-exec\s+rm\b/, reason: "find -exec rm detected" },
-            { regex: /\bdd\b.*\bof=/, reason: "dd with of= (can overwrite files)" },
-            { regex: /\bmv\b/, reason: "mv detected (can overwrite)" },
-            { regex: /\bcp\b.*-f/, reason: "cp -f detected (force overwrite)" },
-            // Allow stderr redirection to /dev/null (2>/dev/null, 2>&1>/dev/null, etc.)
-            // Block dangerous writes like: echo x > /etc/passwd, cat > /bin/bash
-            { regex: /(?<![0-9])>\s*\/(?!dev\/null)/, reason: "output redirection to absolute path" },
-            { regex: />\s*~/, reason: "output redirection to home path" },
-        ];
-        for (const { regex, reason } of destructivePatterns) {
+        for (const { regex, reason } of BUILT_IN_DESTRUCTIVE_GUARDS) {
             if (regex.test(command)) {
                 return reason;
             }
@@ -742,32 +816,19 @@ export class SSHConnectionManager {
             }
         }
         // ========================================
-        // LAYER 2: Whitelist check for non-destructive commands
+        // LAYER 2: Built-in blacklist for high-risk operations
         // ========================================
-        // Use config whitelist if provided, otherwise use default whitelist
-        const whitelist = (config.commandWhitelist && config.commandWhitelist.length > 0)
-            ? config.commandWhitelist
-            : DEFAULT_COMMAND_WHITELIST;
-        // Check whitelist - command must match one of the patterns to be allowed
-        const matchesWhitelist = whitelist.some((pattern) => {
-            try {
-                const regex = new RegExp(pattern);
-                return regex.test(command);
-            }
-            catch (e) {
-                Logger.log(`Invalid whitelist regex pattern: ${pattern}`, "error");
-                return false;
+        for (const { regex, reason } of BUILT_IN_COMMAND_BLACKLIST) {
+            if (regex.test(command)) {
+                Logger.log(`Command blocked by built-in blacklist (${reason}): ${command}`, "info");
+                return {
+                    isAllowed: false,
+                    reason: `Command blocked by built-in blacklist: ${reason}`,
+                };
             }
-        });
-        if (!matchesWhitelist) {
-            Logger.log(`Command blocked by whitelist: ${command}`, "info");
-            return {
-                isAllowed: false,
-                reason: `Command not in whitelist, execution forbidden. Command: "${command}"`,
-            };
         }
         // ========================================
-        // LAYER 3: Blacklist check
+        // LAYER 3: User blacklist check
         // ========================================
         if (config.commandBlacklist && config.commandBlacklist.length > 0) {
             const matchesBlacklist = config.commandBlacklist.some((pattern) => {
@@ -788,6 +849,31 @@ export class SSHConnectionManager {
                 };
             }
         }
+        // ========================================
+        // LAYER 4: Optional whitelist mode
+        // ========================================
+        const commandMode = config.commandMode
+            ?? ((config.commandWhitelist && config.commandWhitelist.length > 0) ? "whitelist" : "blacklist");
+        if (commandMode === "whitelist") {
+            const whitelist = config.commandWhitelist ?? [];
+            const matchesWhitelist = whitelist.some((pattern) => {
+                try {
+                    const regex = new RegExp(pattern);
+                    return regex.test(command);
+                }
+                catch (e) {
+                    Logger.log(`Invalid whitelist regex pattern: ${pattern}`, "error");
+                    return false;
+                }
+            });
+            if (!matchesWhitelist) {
+                Logger.log(`Command blocked by whitelist: ${command}`, "info");
+                return {
+                    isAllowed: false,
+                    reason: `Command not in whitelist, execution forbidden. Command: "${command}"`,
+                };
+            }
+        }
         // Validation passed
         return {
             isAllowed: true,
@@ -914,7 +1000,7 @@ export class SSHConnectionManager {
      * Execute SSH command with auto-retry on connection errors
      *
      * Features:
-     * - Validates command against whitelist/blacklist before execution
+     * - Validates command against command policy before execution
      * - Auto-reconnects and retries on connection failures
      * - Exponential backoff between retries (500ms, 1000ms, 2000ms)
      * - Configurable timeout per command
@@ -993,7 +1079,7 @@ export class SSHConnectionManager {
      * Execute SSH command with real-time streaming output via progress callback
      *
      * Features:
-     * - Validates command against whitelist/blacklist before execution
+     * - Validates command against command policy before execution
      * - Streams stdout/stderr chunks to the onProgress callback in real-time
      * - Auto-reconnects and retries on connection failures
      * - Longer default timeout suitable for long-running tasks
@@ -1427,23 +1513,47 @@ export class SSHConnectionManager {
             }
             this.clients.clear();
         }
+        if (this.jumpClients.size > 0) {
+            for (const chain of this.jumpClients.values()) {
+                for (const client of chain) {
+                    try {
+                        client.end();
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            this.jumpClients.clear();
+        }
     }
     /**
-     * Get basic information of all configured servers
+     * Get basic information of all configured servers.
+     *
+     * Lean by default — returns only identity + connection state. Pass
+     * `verbose: true` to include the cached `status` block (hostname, CPU,
+     * memory, disk, GPUs, etc.). The status block is large and rarely useful
+     * for routing decisions, so the LLM should opt in.
      */
-    getAllServerInfos() {
+    getAllServerInfos(opts = {}) {
+        const verbose = opts.verbose === true;
         return Object.keys(this.configs).map((key) => {
             const config = this.configs[key];
-            const status = this.statusCache.get(key);
-            return {
+            const info = {
                 name: key,
                 host: config.host,
                 port: config.port,
                 username: config.username,
                 connected: this.connected.get(key) === true,
                 enabled: this.isServerEnabled(key),
-                status: status,
             };
+            if (config.jumpHost) {
+                info.jumpHost = config.jumpHost;
+            }
+            if (verbose) {
+                const status = this.statusCache.get(key);
+                if (status)
+                    info.status = status;
+            }
+            return info;
         });
     }
     /**

package/build/tools/execute-command.js

@@ -12,7 +12,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.", {
-        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 whitelist rules even if each subcommand is safe."),
+        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()
             .optional()

package/build/tools/help.js

@@ -31,7 +31,7 @@ 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 }`,
-    "show-whitelist": `show-whitelist — Show allowed/blocked command patterns for a server.
+    "show-whitelist": `show-whitelist — Show the active command policy for a server.
 
 Parameters:
   connectionName  (string, see below)  Target server name from list-servers.
@@ -40,7 +40,7 @@ connectionName rule:
   • If only one server is enabled → optional (auto-selected).
   • If multiple servers are enabled → REQUIRED.
 
-Returns: Whitelist patterns, blacklist patterns, and example commands.`,
+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.
 
 Parameters:
@@ -115,7 +115,7 @@ 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.
-  show-whitelist    Show allowed/blocked command patterns.
+  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.
   transfer          Move files: single, recursive, or cross-server relay.
@@ -123,7 +123,7 @@ const TOOL_OVERVIEW = `Available tools (use help { tool: "<name>" } for details)
 
 Quick start:
   1. list-servers → discover server names
-  2. show-whitelist { connectionName: "<name>" } → see what's allowed
+  2. show-whitelist { connectionName: "<name>" } → inspect command policy
   3. execute-command { cmdString: "pwd", connectionName: "<name>" }`;
 /**
  * Register help tool

package/build/tools/list-servers.js

@@ -6,15 +6,17 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
  * Register list-servers tool
  */
 export function registerListServersTool(server) {
-    server.tool("list-servers", "List the SSH servers that were loaded from OpenSSH config and/or YAML and enabled for this MCP process. Use this first to discover valid connectionName values, confirm whether a server is enabled, and see basic connection state before calling other tools. Set refresh=true to collect live system status (hostname, CPU, memory, disk, GPUs) from connected servers.", {
-        refresh: z.boolean().optional().describe("When true, re-collects live system status from all enabled servers before returning. Without this, cached status from connection time is returned."),
-    }, async ({ refresh }) => {
+    server.tool("list-servers", "List the SSH servers that were loaded from OpenSSH config and/or YAML and enabled for this MCP process. Use this first to discover valid connectionName values, confirm whether a server is enabled, see jumpHost wiring, and check basic connection state before calling other tools. By default the response is lean (identity + connection state only). Set verbose=true to include the cached system status block (hostname, CPU, memory, disk, GPUs). Set refresh=true to re-collect that status from live servers; refresh implies verbose.", {
+        verbose: z.boolean().optional().describe("Include the cached system status block (hostname, CPU, memory, disk, GPUs, etc.) for each server. Off by default to keep the response small. Implied by refresh=true."),
+        refresh: z.boolean().optional().describe("Re-collect live system status from all enabled servers before returning. Implies verbose=true. Without this, status (if requested via verbose) is read from the cache populated at connect time."),
+    }, async ({ verbose, refresh }) => {
         try {
             const sshManager = SSHConnectionManager.getInstance();
             if (refresh) {
                 await sshManager.refreshStatus();
             }
-            const servers = sshManager.getAllServerInfos();
+            const wantStatus = verbose === true || refresh === true;
+            const servers = sshManager.getAllServerInfos({ verbose: wantStatus });
             return {
                 content: [
                     {