@aaarc/handfree-ssh-mcp 1.0.1 → 1.0.3

package/README.md

@@ -8,102 +8,102 @@ A hands-free SSH automation tool via MCP. Fork of [ssh-mcp-server](https://githu
 
 ## 🎯 Philosophy
 
-The original ssh-mcp-server requires passing credentials and options via CLI arguments every time. That's tedious.
-
-**handfree-ssh-mcp** takes a different approach:
-
-1. **Reuse your existing `~/.ssh/config`** automatically, or configure servers once in YAML
-2. **Set command policies** per server through a YAML overlay
-3. **Let the LLM call whatever it needs** - hands-free
+The original ssh-mcp-server requires passing credentials and options via CLI arguments every time. That's tedious.
+
+**handfree-ssh-mcp** takes a different approach:
+
+1. **Reuse your existing `~/.ssh/config`** automatically, or configure servers once in YAML
+2. **Set command policies** per server through a YAML overlay
+3. **Let the LLM call whatever it needs** - hands-free
 
 Less manual interventions. Just autonomous SSH execution with safeguards.
 
 ## ✨ What's New
 
-| Feature | Original | handfree-ssh-mcp |
-|---------|----------|------------------|
-| Configuration | CLI args | **OpenSSH `~/.ssh/config` + optional YAML overlay** |
-| Multi-server | Messy `--ssh` flags | **Clean YAML structure** |
-| Command policy | Single comma-separated whitelist | **Blacklist mode by default, optional whitelist mode** |
-| Streaming | Not supported | **Real-time output with `stream` param** |
-| Discoverability | None | **`show-whitelist` tool for LLM** |
+| Feature | Original | handfree-ssh-mcp |
+|---------|----------|------------------|
+| Configuration | CLI args | **OpenSSH `~/.ssh/config` + optional YAML overlay** |
+| Multi-server | Messy `--ssh` flags | **Clean YAML structure** |
+| Command policy | Single comma-separated whitelist | **Blacklist mode by default, optional whitelist mode** |
+| Streaming | Not supported | **Real-time output with `stream` param** |
+| Discoverability | None | **`show-whitelist` tool for LLM** |
 
 ## 🚀 Quick Start
 
-### 1. Use your existing `~/.ssh/config`
-
-If you already have:
-
-```sshconfig
-Host dev
-  HostName 192.168.1.100
-  User root
-  IdentityFile ~/.ssh/id_ed25519
-```
-
-you can start the MCP without a YAML file:
-
-```json
-{
-  "mcpServers": {
-    "ssh": {
-      "command": "npx",
-      "args": ["-y", "@aaarc/handfree-ssh-mcp", "--enable-servers", "dev"]
-    }
-  }
-}
-```
-
-`--enable-servers` is optional. If you omit it, every concrete `Host` entry loaded from `~/.ssh/config` (plus YAML entries, if any) is enabled.
-
-### 2. Optional: create `servers.yaml` for policies or overrides
-
-```yaml
-sshConfig: true  # default; loads ~/.ssh/config before applying this YAML
-
-servers:
-  dev:  # Server name - use this in --enable-servers
-    # host / port / username / privateKey can be omitted when dev exists in ~/.ssh/config.
-    # Values here override the OpenSSH config entry when present.
-    # commandMode defaults to blacklist: commands are allowed unless they
-    # match the built-in dangerous blacklist or a pattern below.
-    blacklist:
-      - "^docker system prune.*$"
-
-  prod:
-    host: XXXXX
-    port: 22
-    username: deploy
-    privateKey: ~/.ssh/id_rsa
-    commandMode: whitelist
-    whitelist:
-      - "^ls.*$"        # Read only
-      - "^cat.*$"
-      - "^tail.*$"
+### 1. Use your existing `~/.ssh/config`
+
+If you already have:
+
+```sshconfig
+Host dev
+  HostName 192.168.1.100
+  User root
+  IdentityFile ~/.ssh/id_ed25519
+```
+
+you can start the MCP without a YAML file:
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "npx",
+      "args": ["-y", "@aaarc/handfree-ssh-mcp", "--enable-servers", "dev"]
+    }
+  }
+}
+```
+
+`--enable-servers` is optional. If you omit it, every concrete `Host` entry loaded from `~/.ssh/config` (plus YAML entries, if any) is enabled.
+
+### 2. Optional: create `servers.yaml` for policies or overrides
+
+```yaml
+sshConfig: true  # default; loads ~/.ssh/config before applying this YAML
+
+servers:
+  dev:  # Server name - use this in --enable-servers
+    # host / port / username / privateKey can be omitted when dev exists in ~/.ssh/config.
+    # Values here override the OpenSSH config entry when present.
+    # commandMode defaults to blacklist: commands are allowed unless they
+    # match the built-in dangerous blacklist or a pattern below.
+    blacklist:
+      - "^docker system prune.*$"
+
+  prod:
+    host: XXXXX
+    port: 22
+    username: deploy
+    privateKey: ~/.ssh/id_rsa
+    commandMode: whitelist
+    whitelist:
+      - "^ls.*$"        # Read only
+      - "^cat.*$"
+      - "^tail.*$"
     blacklist:
       - "^rm.*$"        # Never allow delete
       - "^shutdown.*$"
       - "^reboot.*$"
-```
-
-### 3. Add to MCP Config
-
-```json
-{
+```
+
+### 3. Add to MCP Config
+
+```json
+{
   "mcpServers": {
     "ssh": {
       "command": "node",
       "args": [
-        "/path/to/handfree-ssh-mcp/build/index.js",
-        "--config", "/path/to/servers.yaml",
-        "--enable-servers", "dev,prod"
+        "/path/to/handfree-ssh-mcp/build/index.js",
+        "--config", "/path/to/servers.yaml",
+        "--enable-servers", "dev,prod"
       ]
     }
   }
-}
-```
-
-### 4. Done. Let the LLM Work.
+}
+```
+
+### 4. Done. Let the LLM Work.
 
 The AI can now execute commands on your servers. All within your defined security boundaries.
 
@@ -114,16 +114,16 @@ The AI can now execute commands on your servers. All within your defined securit
 | Tool | Description |
 |------|-------------|
 | `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 |
+| `show-whitelist` | Show active command policy + SFTP policy + output-log path 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`) |
-| `list-servers` | List configured (enabled) servers |
+| `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 |
 
 ### show-whitelist
 
-**Use this first!** Let the LLM inspect the active command policy:
+**Use this first!** Let the LLM inspect the active command policy:
 
 ```json
 {
@@ -134,7 +134,7 @@ The AI can now execute commands on your servers. All within your defined securit
 }
 ```
 
-Returns command mode, built-in command guards, configured whitelist/blacklist patterns, and examples when whitelist mode is active.
+Returns command mode, built-in command guards, configured whitelist/blacklist patterns, and examples when whitelist mode is active.
 
 ### execute-command
 
@@ -161,53 +161,55 @@ Returns command mode, built-in command guards, configured whitelist/blacklist pa
 - Simple, fast commands (ls, pwd, cat)
 - When you don't need real-time feedback
 
-## 📄 YAML Config Reference
-
-```yaml
-# OpenSSH config loading is enabled by default.
-# true = load ~/.ssh/config, false = use YAML only.
-# You can also provide explicit paths:
-sshConfig:
-  enabled: true
-  paths:
-    - ~/.ssh/config
-    - ~/.ssh/config.d/work
-
-# Eagerly connect to all enabled servers on startup.
-# false (default) = lazy connect on first tool call.
-preConnect: false
+## 📄 YAML Config Reference
+
+```yaml
+# OpenSSH config loading is enabled by default.
+# true = load ~/.ssh/config, false = use YAML only.
+# You can also provide explicit paths:
+sshConfig:
+  enabled: true
+  paths:
+    - ~/.ssh/config
+    - ~/.ssh/config.d/work
+
+# Eagerly connect to all enabled servers on startup.
+# false (default) = lazy connect on first tool call.
+preConnect: false
 
 # Optional: root dir for execute-command full-output logs.
 # Per-call logs land under <outputLogDir>/<server>/<user>/<ts>-<pid>-<rand>.log.
 # Defaults to <cwd>/.handfree-output when unset. Supports ~ and relative paths.
 outputLogDir: ~/handfree-logs
 
-servers:
-  server_name:
-    # Required only for YAML-only servers. If a same-named Host exists in
-    # ~/.ssh/config, these fields are optional overrides.
-    host: 192.168.1.1
-    port: 22
-    username: root
+servers:
+  server_name:
+    # Required only for YAML-only servers. If a same-named Host exists in
+    # ~/.ssh/config, these fields are optional overrides.
+    host: 192.168.1.1
+    port: 22
+    username: root
     
-    # Auth: use ONE of these. Omit agent to use SSH_AUTH_SOCK when present;
-    # set agent only when you need a specific socket path.
-    password: xxx
-    privateKey: ~/.ssh/id_rsa
-    agent: /path/to/ssh-agent.sock
-    passphrase: key_password    # If privateKey is encrypted
+    # Auth: use ONE of these. Omit agent to use SSH_AUTH_SOCK when present;
+    # set agent only when you need a specific socket path.
+    password: xxx
+    privateKey: ~/.ssh/id_rsa
+    agent: /path/to/ssh-agent.sock
+    passphrase: key_password    # If privateKey is encrypted
     
-    # Network
-    socksProxy: socks5://host:port
+    # Network — at most ONE of `socksProxy` or `jumpHost`. See "Jump host" below.
+    # socksProxy: socks5://host:port
+    # jumpHost: bastion
+
     
-    # Command policy (regex patterns)
-    # Default is blacklist. Set commandMode: whitelist to require a whitelist.
-    commandMode: blacklist
-    whitelist:                  # Active only in whitelist mode
-      - "^ls.*$"
-      - "^cat.*$"
-    blacklist:                  # Block matching commands
-      - "^docker system prune.*$"
+    # Command policy (regex patterns)
+    # Default is blacklist. Set commandMode: whitelist to require a whitelist.
+    commandMode: blacklist
+    whitelist:                  # Active only in whitelist mode
+      - "^ls.*$"
+      - "^cat.*$"
+    blacklist:                  # Block matching commands
+      - "^docker system prune.*$"
     
     # Safe directory for destructive commands (rm, etc.)
     safeDirectory: /home/user   # rm allowed only within this path
@@ -224,9 +226,9 @@ servers:
       - /path/to/extra/local/dir
 ```
 
-### Security note: command policy
-
-`execute-command` defaults to `commandMode: blacklist`. In that mode commands are allowed unless they match built-in destructive guards, the built-in dangerous-command blacklist, or a server's configured `blacklist:` patterns. Built-in blocked operations include hidden/chained destructive file operations, risky absolute-path output redirection, system power commands (`reboot`, `shutdown`, `halt`, `poweroff`), recursive force delete (`rm -rf`), destructive disk writes (`dd ... of=`), and filesystem formatting commands. Set `commandMode: whitelist` to require every command to match `whitelist:` after blacklist checks. For compatibility, a YAML server that contains `whitelist:` without `commandMode:` is treated as whitelist mode.
+### Security note: command policy
+
+`execute-command` defaults to `commandMode: blacklist`. In that mode commands are allowed unless they match built-in destructive guards, the built-in dangerous-command blacklist, or a server's configured `blacklist:` patterns. Built-in blocked operations include hidden/chained destructive file operations, risky absolute-path output redirection, system power commands (`reboot`, `shutdown`, `halt`, `poweroff`), recursive force delete (`rm -rf`), destructive disk writes (`dd ... of=`), and filesystem formatting commands. Set `commandMode: whitelist` to require every command to match `whitelist:` after blacklist checks. For compatibility, a YAML server that contains `whitelist:` without `commandMode:` is treated as whitelist mode.
 
 ### SFTP path policy
 
@@ -237,6 +239,37 @@ servers:
 
 Path matching is exact-equal or `dir + separator` prefix. `..` segments and null bytes are rejected. Use `show-whitelist` to inspect a server's current SFTP policy.
 
+### Jump host (ProxyJump-style)
+
+Tunnel a target's SSH connection through another server defined in the same YAML. Useful when the target isn't directly reachable from your machine but a bastion is.
+
+```yaml
+servers:
+  bastion:
+    host: 1.2.3.4
+    username: gate
+    privateKey: ~/.ssh/id_rsa
+
+  target:                       # NOT directly reachable
+    host: 10.0.0.5
+    username: app
+    password: <target-password>
+    jumpHost: bastion           # <- tunnel through `bastion`
+    whitelist:                  # target's own policy
+      - "^ls( .*)?$"
+      - "^pwd$"
+```
+
+Rules (enforced at config load — bad configs fail fast):
+
+- **Chaining to any depth.** The referenced jump host may itself set `jumpHost`, forming a chain `target -> J1 -> J2 -> ...`. The chain is built innermost-first (the deepest, directly-reachable hop connects first). Only **cycles** are rejected.
+- **Mutually exclusive with `socksProxy`** on the same target.
+- **Self-reference is rejected.** `target.jumpHost: target` is invalid.
+- **Independent policy.** The target authenticates with its OWN `username` / `password` / `privateKey`, and its own `whitelist` / `blacklist` / `safeDirectory` / `allowed*Directories` apply. The jump host is purely transport.
+- **Jump host is still a normal server.** You can run tools against `bastion` directly; its connection is separate from the tunneling one.
+
+**Hot-reload note:** `jumpHost` is a connection-level field, so it hot-reloads. Editing a server's `jumpHost` (or any hop's connection fields) in `servers.yaml` resets the affected connection on the fly — the change takes effect on the next tool call, no restart needed. This is chain-aware: if an intermediate hop's host / port / credentials change, every target that tunnels through it is reset too.
+
 ### Connection lifecycle (connect / reconnect)
 
 - **Lazy by default.** A server's SSH client is created on its first tool call via `ensureConnected()`. Set `preConnect: true` (or pass `--pre-connect`) to open all enabled servers at startup in parallel; failures are logged but don't block startup.
@@ -269,27 +302,27 @@ servers:
   dev: { ... }
 ```
 
-## ⚙️ CLI Options
-
-```text
---config          Optional path to YAML config/policy overlay
---ssh-config      Optional OpenSSH config path(s), comma-separated or repeated
---no-ssh-config   Disable automatic ~/.ssh/config loading
---enable-servers  Optional comma-separated list of servers to enable
---pre-connect     Eagerly connect to all enabled servers on startup
-                  (overrides `preConnect` in YAML). Default: lazy connect.
-```
-
-> **Note**: `--enable-servers` controls which servers are available. The first server listed becomes the default when `connectionName` is not specified.
-> If `--enable-servers` is omitted, all loaded servers are enabled; when more than one server is enabled, tools require `connectionName`.
-
-### OpenSSH config support
-
-The loader understands concrete `Host` entries and applies normal OpenSSH-style first-value matching against wildcard defaults. It supports `HostName`, `User`, `Port`, `IdentityFile`, `IdentityAgent`, `Include`, and common tokens such as `%h`, `%n`, `%p`, `%r`, `%u`, `%d`, and `%%`. Wildcard-only `Host *` blocks are used as defaults but are not exposed as runnable server names. `Match` blocks are ignored.
-
-Connection settings are hot-reloaded when the loaded YAML/OpenSSH config files change. If host, user, port, identity, agent, passphrase, or proxy settings change, the existing SSH client for that server is closed and the next tool call reconnects with the new values. Whitelist, blacklist, SFTP policy, and output log settings also update live.
-
-Example with selective servers:
+## ⚙️ CLI Options
+
+```text
+--config          Optional path to YAML config/policy overlay
+--ssh-config      Optional OpenSSH config path(s), comma-separated or repeated
+--no-ssh-config   Disable automatic ~/.ssh/config loading
+--enable-servers  Optional comma-separated list of servers to enable
+--pre-connect     Eagerly connect to all enabled servers on startup
+                  (overrides `preConnect` in YAML). Default: lazy connect.
+```
+
+> **Note**: `--enable-servers` controls which servers are available. The first server listed becomes the default when `connectionName` is not specified.
+> If `--enable-servers` is omitted, all loaded servers are enabled; when more than one server is enabled, tools require `connectionName`.
+
+### OpenSSH config support
+
+The loader understands concrete `Host` entries and applies normal OpenSSH-style first-value matching against wildcard defaults. It supports `HostName`, `User`, `Port`, `IdentityFile`, `IdentityAgent`, `Include`, and common tokens such as `%h`, `%n`, `%p`, `%r`, `%u`, `%d`, and `%%`. Wildcard-only `Host *` blocks are used as defaults but are not exposed as runnable server names. `Match` blocks are ignored.
+
+Connection settings are hot-reloaded when the loaded YAML/OpenSSH config files change. If host, user, port, identity, agent, passphrase, or proxy settings change, the existing SSH client for that server is closed and the next tool call reconnects with the new values. Whitelist, blacklist, SFTP policy, and output log settings also update live.
+
+Example with selective servers:
 
 ```json
 {
@@ -302,7 +335,7 @@ Example with selective servers:
 
 ## 🛡️ Security
 
-- **Pick the right command policy**: use default blacklist mode for flexible automation, or `commandMode: whitelist` for locked-down hosts
+- **Pick the right command policy**: use default blacklist mode for flexible automation, or `commandMode: whitelist` for locked-down hosts
 - **Keep secrets safe**: Add `servers.yaml` to `.gitignore`
 - **Per-server control**: Prod can be locked down, dev can be permissive
 

package/build/config/config-loader.js

@@ -76,6 +76,9 @@ function loadYamlConfig(configPath, options) {
     if (options.requireServers && Object.keys(configMap).length === 0) {
         throw new Error("No servers defined in config file");
     }
+    if (options.requireServers) {
+        validateMergedConfigs(configMap);
+    }
     Logger.log(`Total YAML servers loaded: ${Object.keys(configMap).length}`, "info");
     // Resolve outputLogDir if provided. Default applied later (in ssh-connection-manager)
     // so it always tracks the current cwd at execution time.
@@ -130,6 +133,8 @@ function buildYamlServerConfig(name, serverConfig, options = {}) {
     }
     if (serverConfig.socksProxy !== undefined)
         merged.socksProxy = serverConfig.socksProxy ?? undefined;
+    if (serverConfig.jumpHost !== undefined)
+        merged.jumpHost = serverConfig.jumpHost ?? undefined;
     if (serverConfig.commandMode !== undefined) {
         if (serverConfig.commandMode !== "blacklist" && serverConfig.commandMode !== "whitelist") {
             throw new Error(`Server '${name}': 'commandMode' must be 'blacklist' or 'whitelist'`);
@@ -166,6 +171,7 @@ function mergeConfigMaps(sshConfigs, yamlConfigs) {
             name,
             allowedRemoteDirectories: yamlConfig.allowedRemoteDirectories ?? merged[name]?.allowedRemoteDirectories,
             allowedLocalDirectories: yamlConfig.allowedLocalDirectories ?? merged[name]?.allowedLocalDirectories,
+            jumpHost: yamlConfig.jumpHost ?? merged[name]?.jumpHost,
             commandMode: yamlConfig.commandMode ?? merged[name]?.commandMode,
             commandWhitelist: yamlConfig.commandWhitelist ?? merged[name]?.commandWhitelist,
             commandBlacklist: yamlConfig.commandBlacklist ?? merged[name]?.commandBlacklist,
@@ -194,6 +200,7 @@ function validateMergedConfigs(configs) {
             throw new Error(`Server '${name}': either 'password', 'privateKey', 'agent', or OpenSSH/default authentication is required`);
         }
     }
+    validateJumpHosts(configs);
 }
 function resolveSshConfigEnabled(options, yamlParsed) {
     if (options.loadUserSshConfig !== undefined) {
@@ -277,6 +284,51 @@ export function getLoadUserSshConfigFlag(args) {
 export function getPreConnectFlag(args) {
     return args.includes("--pre-connect");
 }
+/**
+ * Validate every server's `jumpHost` reference.
+ *
+ * Rules:
+ *  - target with `jumpHost` must not also set `socksProxy` (mutually exclusive).
+ *  - referenced jump host must exist in the same config.
+ *  - self-reference is rejected.
+ *  - chained jumps are allowed to any depth (target -> J1 -> J2 -> ...), but the
+ *    chain must be acyclic — a cycle is rejected to prevent infinite recursion.
+ */
+function validateJumpHosts(configMap) {
+    for (const [name, cfg] of Object.entries(configMap)) {
+        if (cfg.jumpHost === undefined) {
+            continue;
+        }
+        if (typeof cfg.jumpHost !== "string" || cfg.jumpHost.length === 0) {
+            throw new Error(`Server '${name}': 'jumpHost' must be a non-empty string`);
+        }
+        if (cfg.socksProxy) {
+            throw new Error(`Server '${name}': 'jumpHost' and 'socksProxy' are mutually exclusive`);
+        }
+        if (cfg.jumpHost === name) {
+            throw new Error(`Server '${name}': 'jumpHost' must not reference itself`);
+        }
+        if (!configMap[cfg.jumpHost]) {
+            throw new Error(`Server '${name}': 'jumpHost' references unknown server '${cfg.jumpHost}'`);
+        }
+        // Walk the jump chain and detect cycles. Every intermediate hop is itself a
+        // server entry, so its own socksProxy / existence rules are enforced when it
+        // is visited by the outer loop — here we only need to guard against a loop.
+        const seen = [name];
+        let hop = cfg.jumpHost;
+        while (hop !== undefined) {
+            if (seen.includes(hop)) {
+                throw new Error(`Server '${name}': 'jumpHost' chain forms a cycle (${[...seen, hop].join(" -> ")})`);
+            }
+            seen.push(hop);
+            const next = configMap[hop];
+            if (!next) {
+                throw new Error(`Server '${hop}': 'jumpHost' references unknown server`);
+            }
+            hop = next.jumpHost;
+        }
+    }
+}
 /**
  * Normalize and validate allowedRemoteDirectories.
  * Each entry must be an absolute POSIX path. Trailing slashes are stripped

package/build/config/server.js

@@ -1,6 +1,6 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.0.1",
+    version: "1.0.3",
 };
 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.
 
@@ -8,15 +8,15 @@ Recommended workflow:
 1. Call list-servers first to discover which server names are available, enabled, and currently connected.
 2. Use show-whitelist before execute-command when you are unsure which command policy is active.
 3. Use execute-command for remote shell commands. Prefer a single command per call. Compound commands may be rejected by command policy even if each subcommand is individually safe.
-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. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
-7. 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.
-- When multiple servers are enabled, connectionName is REQUIRED on execute-command, upload, download, show-whitelist, and transfer (upload/download mode). Omitting it returns an error listing the available names.
-
+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. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
+7. 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.
+- When multiple servers are enabled, connectionName is REQUIRED on execute-command, upload, download, show-whitelist, and transfer (upload/download mode). Omitting it returns an error listing the available names.
+
 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.

package/build/config/ssh-config-loader.js

@@ -9,6 +9,7 @@ const SUPPORTED_KEYS = new Set([
     "identityfile",
     "identityagent",
     "identitiesonly",
+    "proxyjump",
 ]);
 export function getDefaultUserSshConfigPath() {
     return path.join(os.homedir(), ".ssh", "config");
@@ -21,9 +22,10 @@ export function loadSshConfigFiles(configPaths = [getDefaultUserSshConfigPath()]
         parseConfigFile(resolveLocalPath(configPath, process.cwd()), ["*"], directives, loadedFiles, visitedFiles);
     }
     const rawHosts = buildRawHostConfigs(directives);
+    const aliases = new Map(rawHosts.map((raw) => [raw.alias.toLowerCase(), raw.alias]));
     const configs = {};
     for (const raw of rawHosts) {
-        configs[raw.alias] = toSshConfig(raw);
+        configs[raw.alias] = toSshConfig(raw, aliases);
     }
     const configCount = Object.keys(configs).length;
     if (configCount > 0) {
@@ -126,7 +128,7 @@ function buildRawHostConfigs(directives) {
     }
     return rawHosts;
 }
-function toSshConfig(raw) {
+function toSshConfig(raw, aliases) {
     const rawHost = raw.options.get("hostname") ?? raw.alias;
     const rawUser = raw.options.get("user") ?? os.userInfo().username;
     const rawPort = raw.options.get("port") ?? "22";
@@ -174,8 +176,49 @@ function toSshConfig(raw) {
     else if (identityAgent) {
         config.agent = resolveLocalPath(expandTokens(identityAgent, resolvedContext), process.cwd());
     }
+    const jumpHost = resolveProxyJumpAlias(raw.alias, raw.options.get("proxyjump"), aliases);
+    if (jumpHost) {
+        config.jumpHost = jumpHost;
+    }
     return config;
 }
+function resolveProxyJumpAlias(alias, proxyJump, aliases) {
+    if (!proxyJump)
+        return undefined;
+    if (proxyJump.toLowerCase() === "none")
+        return undefined;
+    if (proxyJump.includes(",")) {
+        Logger.log(`SSH config Host '${alias}': ProxyJump chains are not supported by native jumpHost; ignoring '${proxyJump}'`, "info");
+        return undefined;
+    }
+    const jumpAlias = extractProxyJumpHost(proxyJump);
+    if (!jumpAlias)
+        return undefined;
+    const canonical = aliases.get(jumpAlias.toLowerCase());
+    if (!canonical) {
+        Logger.log(`SSH config Host '${alias}': ProxyJump '${proxyJump}' does not reference a loaded Host alias; ignoring`, "info");
+        return undefined;
+    }
+    return canonical;
+}
+function extractProxyJumpHost(proxyJump) {
+    let endpoint = proxyJump.trim();
+    if (!endpoint)
+        return undefined;
+    const atIndex = endpoint.lastIndexOf("@");
+    if (atIndex >= 0) {
+        endpoint = endpoint.slice(atIndex + 1);
+    }
+    if (endpoint.startsWith("[")) {
+        const closeIndex = endpoint.indexOf("]");
+        return closeIndex > 1 ? endpoint.slice(1, closeIndex) : undefined;
+    }
+    const colonIndex = endpoint.lastIndexOf(":");
+    if (colonIndex > 0 && endpoint.indexOf(":") === colonIndex) {
+        endpoint = endpoint.slice(0, colonIndex);
+    }
+    return endpoint || undefined;
+}
 function findDefaultIdentityFile() {
     const sshDir = path.join(os.homedir(), ".ssh");
     const candidates = [

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

@@ -19,6 +19,7 @@ const CONNECTION_RESET_FIELDS = [
     "identitiesOnly",
     "authOptional",
     "socksProxy",
+    "jumpHost",
 ];
 export const BUILT_IN_COMMAND_BLACKLIST = [
     { regex: /^\s*(?:sudo\s+)?(?:reboot|shutdown|halt|poweroff)(?:\s|$)/i, reason: "system power command" },
@@ -63,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
@@ -110,18 +116,52 @@ export class SSHConnectionManager {
      */
     replaceConfig(configs, enabledServers) {
         const previous = this.configs;
-        const changedConnections = [];
+        // Pass 1: servers whose own connection fields changed (or that vanished).
+        const directlyChanged = new Set();
         for (const [name, oldConfig] of Object.entries(previous)) {
             const nextConfig = configs[name];
             if (!nextConfig || this.connectionFieldsChanged(oldConfig, nextConfig)) {
-                this.closeClient(name, true);
-                this.statusCache.delete(name);
-                changedConnections.push(name);
+                directlyChanged.add(name);
             }
         }
+        // Pass 2: a target must ALSO reset if any hop in its jump chain directly
+        // changed — otherwise it keeps tunneling through a stale intermediate hop.
+        // Walk both the old and new chains so topology shifts (added/removed hops)
+        // are covered too.
+        const toReset = new Set(directlyChanged);
+        for (const name of Object.keys(previous)) {
+            if (toReset.has(name))
+                continue;
+            if (this.jumpChainTouchesChanged(name, previous, directlyChanged) ||
+                this.jumpChainTouchesChanged(name, configs, directlyChanged)) {
+                toReset.add(name);
+            }
+        }
+        for (const name of toReset) {
+            this.closeClient(name, true);
+            this.statusCache.delete(name);
+        }
         this.setConfig(configs, enabledServers);
         Logger.log(`Hot-reloaded SSH config: ${Object.keys(configs).length} server(s), ` +
-            `${changedConnections.length} connection(s) reset`, "info");
+            `${toReset.size} connection(s) reset`, "info");
+    }
+    /**
+     * Walk `name`'s jump chain in `configMap` and report whether any hop is in the
+     * `changed` set. Guards against cycles defensively (config load rejects them).
+     * @private
+     */
+    jumpChainTouchesChanged(name, configMap, changed) {
+        const seen = new Set([name]);
+        let hop = configMap[name]?.jumpHost;
+        while (hop !== undefined) {
+            if (changed.has(hop))
+                return true;
+            if (seen.has(hop))
+                break;
+            seen.add(hop);
+            hop = configMap[hop]?.jumpHost;
+        }
+        return false;
     }
     /**
      * Set the root directory under which execute-command full-output logs are
@@ -165,6 +205,7 @@ export class SSHConnectionManager {
             }
             this.clients.delete(name);
         }
+        this.teardownJumpChain(name);
         this.connected.set(name, false);
         this.connecting.delete(name);
     }
@@ -335,6 +376,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 {
@@ -405,6 +464,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
      */
@@ -1332,23 +1547,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/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: [
                     {

package/package.json

@@ -1,24 +1,24 @@
 {
-  "name": "@aaarc/handfree-ssh-mcp",
-  "version": "1.0.1",
+  "name": "@aaarc/handfree-ssh-mcp",
+  "version": "1.0.3",
   "description": "Handfree SSH MCP Server - A hands-free SSH automation tool via MCP protocol",
   "main": "build/index.js",
   "type": "module",
   "bin": {
     "handfree-ssh-mcp": "build/index.js"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Ironboxplus/handfree-ssh-mcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Ironboxplus/handfree-ssh-mcp/issues"
-  },
-  "homepage": "https://github.com/Ironboxplus/handfree-ssh-mcp#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ironboxplus/handfree-ssh-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ironboxplus/handfree-ssh-mcp/issues"
+  },
+  "homepage": "https://github.com/Ironboxplus/handfree-ssh-mcp#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
     "test": "npm run build && node --test build/tests/config.test.js build/tests/command-validation.test.js build/tests/tool-error.test.js build/tests/tools.test.js build/tests/output-collector.test.js build/tests/output-log-writer.test.js build/tests/recent-fixes.test.js",
     "test:config": "npm run build && node --test build/tests/config.test.js",
     "test:cmd": "npm run build && node --test build/tests/command-validation.test.js",
@@ -49,13 +49,13 @@
     "@types/ssh2": "^1.15.5",
     "typescript": "^5.8.2"
   },
-  "files": [
-    "build/config/**/*",
-    "build/core/**/*",
-    "build/models/**/*",
-    "build/services/**/*",
-    "build/tools/**/*",
-    "build/utils/**/*",
-    "build/index.js"
-  ]
-}
+  "files": [
+    "build/config/**/*",
+    "build/core/**/*",
+    "build/models/**/*",
+    "build/services/**/*",
+    "build/tools/**/*",
+    "build/utils/**/*",
+    "build/index.js"
+  ]
+}