@yawlabs/ssh-mcp 0.6.0 → 0.8.0

package/README.md

@@ -98,6 +98,18 @@ All connections respect your `~/.ssh/config`. Host aliases, custom ports, userna
 
 **ProxyJump / bastion hosts** are supported automatically. If your SSH config has `ProxyJump bastion` for a host, ssh-mcp connects through the bastion transparently. Chained proxies work too.
 
+### Host key verification
+
+All remote operations verify the server's host key against `~/.ssh/known_hosts`:
+
+- **Known host, key matches** — accept.
+- **Known host, key changed** — reject (MITM protection).
+- **Unknown host** — accept on first connection (TOFU). Use `ssh_known_hosts_fix` to pin the key for future mismatch detection.
+
+For stricter environments, set `SSH_MCP_STRICT_HOST_KEY=1` to reject unknown hosts. Add them explicitly with `ssh_known_hosts_fix` first.
+
+The diagnostic tools (`ssh_test`, `ssh_diagnose`) use `StrictHostKeyChecking=no` for their probe commands. Those probes only run `echo SSH_OK` — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the `hostVerifier`.
+
 ### Windows support
 
 On Windows, ssh-mcp detects the OpenSSH Authentication Agent service automatically (via the `\\.\pipe\openssh-ssh-agent` named pipe). No `SSH_AUTH_SOCK` needed — just make sure the OpenSSH agent service is running.
@@ -114,7 +126,13 @@ All remote operations accept connection parameters:
 | `privateKeyPath` | Path to SSH private key | Auto-detect |
 | `password` | SSH password (prefer keys) | — |
 
-**Auth resolution order:** explicit key > explicit password > ssh-agent (`SSH_AUTH_SOCK`) > SSH config identity files > default key paths (`~/.ssh/id_ed25519`, `id_rsa`, `id_ecdsa`).
+**Auth resolution order:** ssh-mcp picks the first match from this list and does not fall through to later entries — this makes the auth method deterministic and predictable.
+
+1. Explicit `privateKeyPath`
+2. Explicit `password`
+3. ssh-agent (`SSH_AUTH_SOCK` on Unix, `\\.\pipe\openssh-ssh-agent` on Windows)
+4. Identity files from `~/.ssh/config` for the host
+5. Default key paths (`~/.ssh/id_ed25519`, `id_rsa`, `id_ecdsa`)
 
 ## Example workflows
 

package/dist/index.js

@@ -290,42 +290,99 @@ function resolveFromSshConfig(host) {
     return null;
   }
 }
+function readKnownHostsKeys(host, port) {
+  if (!isValidHostname(host)) return [];
+  const targets = port && port !== 22 ? [`[${host}]:${port}`, host] : [host];
+  const keys = [];
+  for (const target of targets) {
+    const { stdout, ok } = runArgs("ssh-keygen", ["-F", target]);
+    if (!ok || !stdout.trim()) continue;
+    for (const line of stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts.length < 3) continue;
+      try {
+        keys.push(Buffer.from(parts[2], "base64"));
+      } catch {
+      }
+    }
+  }
+  return keys;
+}
+function buildHostVerifier(hosts, port) {
+  const strict = process.env.SSH_MCP_STRICT_HOST_KEY === "1";
+  return (key) => {
+    const known = hosts.flatMap((h) => readKnownHostsKeys(h, port));
+    if (known.length === 0) {
+      return !strict;
+    }
+    return known.some((k) => k.equals(key));
+  };
+}
 function resolveConfig(config) {
   const sshConfig = resolveFromSshConfig(config.host);
+  const port = config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22);
+  const verifierHosts = [config.host];
+  if (sshConfig?.hostname && sshConfig.hostname !== config.host) {
+    verifierHosts.push(sshConfig.hostname);
+  }
   const connectConfig = {
     host: sshConfig?.hostname || config.host,
-    port: config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22),
+    port,
     username: config.username || sshConfig?.user || process.env.USER || process.env.USERNAME || "root",
     keepaliveInterval: 15e3,
-    keepaliveCountMax: 3
+    keepaliveCountMax: 3,
+    hostVerifier: buildHostVerifier(verifierHosts, port)
   };
-  const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
-  if (agentSock) {
-    connectConfig.agent = agentSock;
-  }
-  if (config.password) {
-    connectConfig.password = config.password;
-  }
   if (config.privateKeyPath) {
     connectConfig.privateKey = readFileSync2(config.privateKeyPath);
-  } else if (!agentSock) {
-    const home = homedir2();
-    const keyPaths = sshConfig && sshConfig.identityFiles.length > 0 ? sshConfig.identityFiles.map((p) => p.startsWith("~") ? join2(home, p.slice(1)) : p) : [join2(home, ".ssh", "id_ed25519"), join2(home, ".ssh", "id_rsa"), join2(home, ".ssh", "id_ecdsa")];
-    for (const keyPath of keyPaths) {
-      try {
-        connectConfig.privateKey = readFileSync2(keyPath);
-        break;
-      } catch {
+  } else if (config.password) {
+    connectConfig.password = config.password;
+  } else {
+    const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
+    if (agentSock) {
+      connectConfig.agent = agentSock;
+    } else {
+      const home = homedir2();
+      const keyPaths = sshConfig && sshConfig.identityFiles.length > 0 ? sshConfig.identityFiles.map((p) => p.startsWith("~") ? join2(home, p.slice(1)) : p) : [join2(home, ".ssh", "id_ed25519"), join2(home, ".ssh", "id_rsa"), join2(home, ".ssh", "id_ecdsa")];
+      for (const keyPath of keyPaths) {
+        try {
+          connectConfig.privateKey = readFileSync2(keyPath);
+          break;
+        } catch {
+        }
       }
     }
   }
   return { connectConfig, proxyJump: sshConfig?.proxyJump };
 }
+var DIAG_CACHE_TTL_MS = 2e3;
+var diagAgentCache = null;
+var diagKeysCache = null;
+function cachedAgentCheck() {
+  const now = Date.now();
+  if (diagAgentCache && now - diagAgentCache.at < DIAG_CACHE_TTL_MS) {
+    return diagAgentCache.result;
+  }
+  const result = checkSshAgent();
+  diagAgentCache = { at: now, result };
+  return result;
+}
+function cachedKeysCheck() {
+  const now = Date.now();
+  if (diagKeysCache && now - diagKeysCache.at < DIAG_CACHE_TTL_MS) {
+    return diagKeysCache.result;
+  }
+  const result = checkSshKeys();
+  diagKeysCache = { at: now, result };
+  return result;
+}
 function formatDiagnostics(host) {
   try {
     const checks = [
-      { name: "SSH Agent", ...checkSshAgent() },
-      { name: "SSH Keys", ...checkSshKeys() },
+      { name: "SSH Agent", ...cachedAgentCheck() },
+      { name: "SSH Keys", ...cachedKeysCheck() },
       { name: "SSH Config", ...checkSshConfig(host) },
       { name: "Known Hosts", ...checkKnownHosts(host) }
     ];
@@ -384,7 +441,8 @@ async function connectWithProxy(resolved) {
     }).connect({ ...resolved.connectConfig, sock: stream });
   });
 }
-function exec(client, command, timeoutMs = 3e4) {
+var DEFAULT_MAX_EXEC_BYTES = 10 * 1024 * 1024;
+function exec(client, command, timeoutMs = 3e4, maxBytes = DEFAULT_MAX_EXEC_BYTES) {
   return new Promise((resolve, reject) => {
     let settled = false;
     const settle = (fn) => {
@@ -401,18 +459,52 @@ function exec(client, command, timeoutMs = 3e4) {
         settle(() => reject(err));
         return;
       }
-      let stdout = "";
-      let stderr = "";
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      let stdoutBytes = 0;
+      let stderrBytes = 0;
+      let stdoutTruncated = false;
+      let stderrTruncated = false;
+      const appendStdout = (data) => {
+        if (stdoutTruncated) return;
+        const remaining = maxBytes - stdoutBytes;
+        if (data.length <= remaining) {
+          stdoutChunks.push(data);
+          stdoutBytes += data.length;
+        } else {
+          if (remaining > 0) {
+            stdoutChunks.push(data.subarray(0, remaining));
+            stdoutBytes += remaining;
+          }
+          stdoutTruncated = true;
+        }
+      };
+      const appendStderr = (data) => {
+        if (stderrTruncated) return;
+        const remaining = maxBytes - stderrBytes;
+        if (data.length <= remaining) {
+          stderrChunks.push(data);
+          stderrBytes += data.length;
+        } else {
+          if (remaining > 0) {
+            stderrChunks.push(data.subarray(0, remaining));
+            stderrBytes += remaining;
+          }
+          stderrTruncated = true;
+        }
+      };
       stream.on("close", (code) => {
+        let stdout = Buffer.concat(stdoutChunks).toString("utf8");
+        let stderr = Buffer.concat(stderrChunks).toString("utf8");
+        if (stdoutTruncated) stdout += `
+[output truncated at ${maxBytes} bytes]`;
+        if (stderrTruncated) stderr += `
+[stderr truncated at ${maxBytes} bytes]`;
         settle(() => resolve({ stdout, stderr, code: code ?? 0 }));
-      }).on("data", (data) => {
-        stdout += data.toString();
-      }).on("error", (err2) => {
+      }).on("data", appendStdout).on("error", (err2) => {
         settle(() => reject(err2));
       });
-      stream.stderr.on("data", (data) => {
-        stderr += data.toString();
-      }).on("error", (err2) => {
+      stream.stderr.on("data", appendStderr).on("error", (err2) => {
         settle(() => reject(err2));
       });
     });
@@ -507,8 +599,14 @@ async function listDir(client, remotePath) {
 // src/pool.ts
 var ConnectionPool = class {
   entries = /* @__PURE__ */ new Map();
+  // Coalesces concurrent connect attempts for the same key so we don't open N
+  // duplicate TCP connections when N tool calls fire simultaneously.
+  pending = /* @__PURE__ */ new Map();
   idleTtlMs;
   maxPoolSize;
+  // Total number of successful connects ever made by this pool. Useful for
+  // introspection and for tests that want to prove connection reuse.
+  _connectCount = 0;
   constructor(options) {
     this.idleTtlMs = options?.idleTtlMs ?? 6e4;
     this.maxPoolSize = options?.maxPoolSize ?? 100;
@@ -517,67 +615,98 @@ var ConnectionPool = class {
     const resolved = resolveConfig(config);
     const cc = resolved.connectConfig;
     const key = `${cc.username}@${cc.host}:${cc.port}`;
-    const existing = this.entries.get(key);
-    if (existing && !existing.dead) {
-      existing.refCount++;
-      if (existing.idleTimer) {
-        clearTimeout(existing.idleTimer);
-        existing.idleTimer = null;
-      }
-      return existing.client;
-    }
-    if (existing?.dead) {
-      this.entries.delete(key);
-    }
-    if (this.entries.size >= this.maxPoolSize) {
-      let evicted = false;
-      for (const [k, e] of this.entries) {
-        if (e.refCount === 0) {
-          if (e.idleTimer) clearTimeout(e.idleTimer);
-          try {
-            e.client.end();
-          } catch {
-          }
-          this.entries.delete(k);
-          evicted = true;
-          break;
+    const MAX_ACQUIRE_ATTEMPTS = 3;
+    let lastErr;
+    for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
+      const existing = this.entries.get(key);
+      if (existing && !existing.dead) {
+        existing.refCount++;
+        if (existing.idleTimer) {
+          clearTimeout(existing.idleTimer);
+          existing.idleTimer = null;
         }
+        return existing.client;
       }
-      if (!evicted) {
-        throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+      if (existing?.dead) {
+        this.entries.delete(key);
       }
-    }
-    try {
-      const client = await connectWithProxy(resolved);
-      const entry = { client, key, refCount: 1, idleTimer: null, dead: false };
-      const markDead = () => {
-        entry.dead = true;
-        if (entry.idleTimer) {
-          clearTimeout(entry.idleTimer);
-          entry.idleTimer = null;
-        }
-        if (this.entries.get(key) === entry) {
-          this.entries.delete(key);
+      let pending = this.pending.get(key);
+      if (!pending) {
+        if (this.entries.size >= this.maxPoolSize) {
+          let evicted = false;
+          for (const [k, e] of this.entries) {
+            if (e.refCount === 0) {
+              if (e.idleTimer) clearTimeout(e.idleTimer);
+              try {
+                e.client.end();
+              } catch {
+              }
+              this.entries.delete(k);
+              evicted = true;
+              break;
+            }
+          }
+          if (!evicted) {
+            throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+          }
         }
-      };
-      client.on("close", markDead);
-      client.on("end", markDead);
-      client.on("error", markDead);
-      this.entries.set(key, entry);
-      return client;
-    } catch (err) {
-      const diag = formatDiagnostics(config.host);
-      if (diag) {
-        const message = err instanceof Error ? err.message : String(err);
-        const enhanced = new Error(`${message}
+        pending = (async () => {
+          try {
+            const client2 = await connectWithProxy(resolved);
+            this._connectCount++;
+            const entry2 = { client: client2, key, refCount: 0, idleTimer: null, dead: false };
+            const markDead = () => {
+              entry2.dead = true;
+              if (entry2.idleTimer) {
+                clearTimeout(entry2.idleTimer);
+                entry2.idleTimer = null;
+              }
+              if (this.entries.get(key) === entry2) {
+                this.entries.delete(key);
+              }
+            };
+            client2.on("close", markDead);
+            client2.on("end", markDead);
+            client2.on("error", markDead);
+            this.entries.set(key, entry2);
+            return client2;
+          } finally {
+            this.pending.delete(key);
+          }
+        })();
+        this.pending.set(key, pending);
+      }
+      let client;
+      try {
+        client = await pending;
+      } catch (err) {
+        const diag = formatDiagnostics(config.host);
+        if (diag) {
+          const message = err instanceof Error ? err.message : String(err);
+          const enhanced = new Error(`${message}
 
 SSH Diagnostics:
 ${diag}`);
-        enhanced.cause = err;
-        throw enhanced;
+          enhanced.cause = err;
+          throw enhanced;
+        }
+        throw err;
+      }
+      const entry = this.entries.get(key);
+      if (!entry || entry.dead || entry.client !== client) {
+        lastErr = new Error("connection died before acquire could take a ref");
+        continue;
+      }
+      entry.refCount++;
+      if (entry.idleTimer) {
+        clearTimeout(entry.idleTimer);
+        entry.idleTimer = null;
       }
-      throw err;
+      return client;
     }
+    throw new Error(
+      `Failed to acquire SSH connection for ${key} after ${MAX_ACQUIRE_ATTEMPTS} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+    );
   }
   release(client) {
     for (const entry of this.entries.values()) {
@@ -633,6 +762,10 @@ ${diag}`);
     }
     return { active, idle };
   }
+  /** Total number of successful SSH connects made by this pool since construction. */
+  get connectCount() {
+    return this._connectCount;
+  }
 };
 
 // src/server.ts
@@ -645,37 +778,29 @@ import { z } from "zod";
 import { appendFileSync, existsSync as existsSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, statSync } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
+function probeAgent(socket, agentLabel) {
+  const { stdout, ok } = runArgs("ssh-add", ["-l"]);
+  const noIdentities = stdout.includes("no identities") || stdout.includes("The agent has no identities");
+  if (!ok && !noIdentities) return null;
+  const keys = ok && !noIdentities ? stdout.split("\n").filter(Boolean) : [];
+  return {
+    running: true,
+    reachable: true,
+    socket,
+    keys,
+    started: false,
+    message: keys.length > 0 ? `${agentLabel} running with ${keys.length} key(s) loaded` : `${agentLabel} running but no keys loaded. Use ssh_key_load to add one.`
+  };
+}
 function ensureAgent() {
   const sock = process.env.SSH_AUTH_SOCK;
   if (sock) {
-    const { stdout: stdout2, ok: ok2 } = runArgs("ssh-add", ["-l"]);
-    const noIdentities = stdout2.includes("no identities") || stdout2.includes("The agent has no identities");
-    if (ok2 || noIdentities) {
-      const keys = ok2 && !noIdentities ? stdout2.split("\n").filter(Boolean) : [];
-      return {
-        running: true,
-        reachable: true,
-        socket: sock,
-        keys,
-        started: false,
-        message: keys.length > 0 ? `ssh-agent running with ${keys.length} key(s) loaded` : "ssh-agent running but no keys loaded. Use ssh_key_load to add one."
-      };
-    }
+    const result = probeAgent(sock, "ssh-agent");
+    if (result) return result;
   }
   if (!sock && process.platform === "win32") {
-    const { stdout: stdout2, ok: ok2 } = runArgs("ssh-add", ["-l"]);
-    const noIdentities = stdout2.includes("no identities") || stdout2.includes("The agent has no identities");
-    if (ok2 || noIdentities) {
-      const keys = ok2 && !noIdentities ? stdout2.split("\n").filter(Boolean) : [];
-      return {
-        running: true,
-        reachable: true,
-        socket: "\\\\.\\pipe\\openssh-ssh-agent",
-        keys,
-        started: false,
-        message: keys.length > 0 ? `Windows OpenSSH agent running with ${keys.length} key(s) loaded` : "Windows OpenSSH agent running but no keys loaded. Use ssh_key_load to add one."
-      };
-    }
+    const result = probeAgent("\\\\.\\pipe\\openssh-ssh-agent", "Windows OpenSSH agent");
+    if (result) return result;
   }
   const { stdout, ok } = runArgs("ssh-agent", ["-s"]);
   if (ok) {
@@ -691,7 +816,7 @@ function ensureAgent() {
         keys: [],
         started: true,
         env: { SSH_AUTH_SOCK: sockMatch[1], SSH_AGENT_PID: pidMatch?.[1] },
-        message: "Started new ssh-agent. No keys loaded yet \u2014 use ssh_key_load to add one."
+        message: "Started new ssh-agent scoped to the ssh-mcp server process. Your shell's environment is NOT modified \u2014 this agent is only visible to this MCP server and will terminate when the server exits. No keys loaded yet \u2014 use ssh_key_load to add one."
       };
     }
   }
@@ -817,8 +942,8 @@ function configLookup(host) {
     user: all.user || "",
     port: all.port || "22",
     identityFile: identityFiles,
-    proxyJump: all.proxyjump !== "none" ? all.proxyjump : void 0,
-    proxyCommand: all.proxycommand !== "none" ? all.proxycommand : void 0,
+    proxyJump: all.proxyjump && all.proxyjump !== "none" ? all.proxyjump : void 0,
+    proxyCommand: all.proxycommand && all.proxycommand !== "none" ? all.proxycommand : void 0,
     all,
     raw: stdout
   };
@@ -860,7 +985,7 @@ function checkGitSsh(host = "github.com", user = "git") {
   const { stdout } = runArgs("ssh", ["-T", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", `${user}@${host}`]);
   const text = stdout;
   if (text.includes("successfully authenticated") || text.includes("Welcome to GitLab") || text.includes("logged in as")) {
-    const userMatch = text.match(/Hi (\S+?)!/) || text.match(/@(\S+?)!/) || text.match(/logged in as (\S+)/);
+    const userMatch = text.match(/Hi (\S+)!/) || text.match(/@(\S+)!/) || text.match(/logged in as (\S+)/);
     return {
       status: "ok",
       message: `Git SSH authentication to ${host} succeeded${userMatch ? ` as ${userMatch[1]}` : ""}`,
@@ -978,8 +1103,11 @@ async function find(client, options, timeoutMs = 3e4) {
   if (options.minsize) args.push("-size", `+${options.minsize}`);
   if (options.maxsize) args.push("-size", `-${options.maxsize}`);
   if (options.newer) args.push("-newer", shellQuote(options.newer));
-  const command = `find ${args.join(" ")} 2>/dev/null`;
+  const command = `find ${args.join(" ")}`;
   const result = await exec(client, command, timeoutMs);
+  if (!result.stdout.trim() && result.stderr.trim()) {
+    throw new Error(result.stderr.trim());
+  }
   return result.stdout.split("\n").filter(Boolean);
 }
 async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
@@ -988,7 +1116,7 @@ async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
     command += ` | grep -i ${shellQuote(grep)}`;
   }
   const result = await exec(client, command, timeoutMs);
-  if (result.code !== 0 && result.stderr && !grep) {
+  if (result.stderr.trim()) {
     throw new Error(result.stderr.trim());
   }
   return result.stdout;
@@ -1016,7 +1144,9 @@ var HostSchema = z.string().describe("SSH hostname or IP address");
 var PortSchema = z.number().int().min(1).max(65535).optional().describe("SSH port (default: 22)");
 var UsernameSchema = z.string().optional().describe("SSH username (default: current user)");
 var KeyPathSchema = z.string().optional().describe("Path to SSH private key");
-var PasswordSchema = z.string().optional().describe("SSH password (prefer keys)");
+var PasswordSchema = z.string().optional().describe(
+  "SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."
+);
 var TimeoutSchema = z.number().int().positive().optional().describe("Command timeout in milliseconds (default: 30000)");
 var connectionParams = {
   host: HostSchema,
@@ -1029,14 +1159,14 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. Returns stdout, stderr, and exit code.",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code.",
     {
       ...connectionParams,
-      command: z.string().describe("Shell command to execute on the remote host"),
+      command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
       timeout: TimeoutSchema
     },
-    async ({ host, port, username, privateKeyPath, password, command, timeout }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ command, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const result = await exec(client, command, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
@@ -1054,8 +1184,8 @@ ${result.stderr}`);
       ...connectionParams,
       path: z.string().describe("Absolute path to the remote file")
     },
-    async ({ host, port, username, privateKeyPath, password, path }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const content = await readFile(client, path);
         return { content: [{ type: "text", text: content }] };
       });
@@ -1069,8 +1199,8 @@ ${result.stderr}`);
       path: z.string().describe("Absolute path to the remote file"),
       content: z.string().describe("File content to write")
     },
-    async ({ host, port, username, privateKeyPath, password, path, content }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, content, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         await writeFile(client, path, content);
         return { content: [{ type: "text", text: `Wrote ${content.length} bytes to ${path}` }] };
       });
@@ -1084,8 +1214,8 @@ ${result.stderr}`);
       localPath: z.string().describe("Path to the local file to upload"),
       remotePath: z.string().describe("Absolute path on the remote host")
     },
-    async ({ host, port, username, privateKeyPath, password, localPath, remotePath }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ localPath, remotePath, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         await uploadFile(client, localPath, remotePath);
         return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
       });
@@ -1099,8 +1229,8 @@ ${result.stderr}`);
       remotePath: z.string().describe("Absolute path to the remote file"),
       localPath: z.string().describe("Local path to save the downloaded file")
     },
-    async ({ host, port, username, privateKeyPath, password, remotePath, localPath }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ remotePath, localPath, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         await downloadFile(client, remotePath, localPath);
         return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
       });
@@ -1113,8 +1243,8 @@ ${result.stderr}`);
       ...connectionParams,
       path: z.string().describe("Absolute path to the remote directory")
     },
-    async ({ host, port, username, privateKeyPath, password, path }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const files = await listDir(client, path);
         return { content: [{ type: "text", text: files.join("\n") }] };
       });
@@ -1320,21 +1450,8 @@ ${result.stderr}`);
       maxsize: z.string().optional().describe("Maximum file size (e.g. '10M', '500k')"),
       timeout: TimeoutSchema
     },
-    async ({
-      host,
-      port,
-      username,
-      privateKeyPath,
-      password,
-      path,
-      name,
-      type,
-      maxdepth,
-      minsize,
-      maxsize,
-      timeout
-    }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, name, type, maxdepth, minsize, maxsize, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const files = await find(client, { path, name, type, maxdepth, minsize, maxsize }, timeout || 3e4);
         if (files.length === 0) {
           return { content: [{ type: "text", text: "No files found." }] };
@@ -1354,8 +1471,8 @@ ${files.join("\n")}` }] };
       grep: z.string().optional().describe("Case-insensitive pattern to filter lines"),
       timeout: TimeoutSchema
     },
-    async ({ host, port, username, privateKeyPath, password, path, lines, grep, timeout }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, lines, grep, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const output = await tail(client, path, lines || 100, grep, timeout || 3e4);
         if (!output.trim()) {
           return {
@@ -1379,8 +1496,8 @@ ${files.join("\n")}` }] };
       service: z.string().describe("Systemd service name (e.g. nginx, sshd, docker)"),
       timeout: TimeoutSchema
     },
-    async ({ host, port, username, privateKeyPath, password, service, timeout }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ service, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const status = await serviceStatus(client, service, timeout || 3e4);
         const lines = [];
         lines.push(`Service: ${status.name}`);
@@ -1400,7 +1517,7 @@ ${files.join("\n")}` }] };
 function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.6.0"
+    version: "0.7.0"
   });
   registerTools(server, pool);
   return server;

package/dist/server.d.ts

@@ -18,12 +18,13 @@ interface ResolvedConfig {
     connectConfig: ConnectConfig;
     proxyJump?: string;
 }
+declare function readKnownHostsKeys(host: string, port?: number): Buffer[];
 declare function resolveConfig(config: SSHConfig): ResolvedConfig;
 declare function formatDiagnostics(host: string): string;
 declare function connectRaw(connectConfig: ConnectConfig): Promise<Client>;
 declare function connectWithProxy(resolved: ResolvedConfig): Promise<Client>;
 declare function connect(config: SSHConfig): Promise<Client>;
-declare function exec(client: Client, command: string, timeoutMs?: number): Promise<ExecResult>;
+declare function exec(client: Client, command: string, timeoutMs?: number, maxBytes?: number): Promise<ExecResult>;
 declare function readFile(client: Client, remotePath: string, maxBytes?: number): Promise<string>;
 declare function writeFile(client: Client, remotePath: string, content: string): Promise<void>;
 declare function uploadFile(client: Client, localPath: string, remotePath: string): Promise<void>;
@@ -38,8 +39,10 @@ interface PoolOptions {
 }
 declare class ConnectionPool {
     private entries;
+    private pending;
     private idleTtlMs;
     private maxPoolSize;
+    private _connectCount;
     constructor(options?: PoolOptions);
     acquire(config: SSHConfig): Promise<Client>;
     release(client: Client): void;
@@ -50,6 +53,8 @@ declare class ConnectionPool {
         active: number;
         idle: number;
     };
+    /** Total number of successful SSH connects made by this pool since construction. */
+    get connectCount(): number;
 }
 
 declare function registerTools(server: McpServer, pool?: ConnectionPool): void;
@@ -164,4 +169,4 @@ declare function testConnection(host: string, port?: number): {
 
 declare function createServer(pool?: ConnectionPool): McpServer;
 
-export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, diagnose, downloadFile, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, listDir, listSshKeys, loadKey, multiExec, readFile, registerTools, resolveConfig, serviceStatus, tail, testConnection, uploadFile, writeFile };
+export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, diagnose, downloadFile, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, listDir, listSshKeys, loadKey, multiExec, readFile, readKnownHostsKeys, registerTools, resolveConfig, serviceStatus, tail, testConnection, uploadFile, writeFile };

package/dist/server.js

@@ -259,37 +259,29 @@ function diagnose(host, port = 22) {
 import { appendFileSync, existsSync as existsSync2, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync } from "fs";
 import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
+function probeAgent(socket, agentLabel) {
+  const { stdout, ok } = runArgs("ssh-add", ["-l"]);
+  const noIdentities = stdout.includes("no identities") || stdout.includes("The agent has no identities");
+  if (!ok && !noIdentities) return null;
+  const keys = ok && !noIdentities ? stdout.split("\n").filter(Boolean) : [];
+  return {
+    running: true,
+    reachable: true,
+    socket,
+    keys,
+    started: false,
+    message: keys.length > 0 ? `${agentLabel} running with ${keys.length} key(s) loaded` : `${agentLabel} running but no keys loaded. Use ssh_key_load to add one.`
+  };
+}
 function ensureAgent() {
   const sock = process.env.SSH_AUTH_SOCK;
   if (sock) {
-    const { stdout: stdout2, ok: ok2 } = runArgs("ssh-add", ["-l"]);
-    const noIdentities = stdout2.includes("no identities") || stdout2.includes("The agent has no identities");
-    if (ok2 || noIdentities) {
-      const keys = ok2 && !noIdentities ? stdout2.split("\n").filter(Boolean) : [];
-      return {
-        running: true,
-        reachable: true,
-        socket: sock,
-        keys,
-        started: false,
-        message: keys.length > 0 ? `ssh-agent running with ${keys.length} key(s) loaded` : "ssh-agent running but no keys loaded. Use ssh_key_load to add one."
-      };
-    }
+    const result = probeAgent(sock, "ssh-agent");
+    if (result) return result;
   }
   if (!sock && process.platform === "win32") {
-    const { stdout: stdout2, ok: ok2 } = runArgs("ssh-add", ["-l"]);
-    const noIdentities = stdout2.includes("no identities") || stdout2.includes("The agent has no identities");
-    if (ok2 || noIdentities) {
-      const keys = ok2 && !noIdentities ? stdout2.split("\n").filter(Boolean) : [];
-      return {
-        running: true,
-        reachable: true,
-        socket: "\\\\.\\pipe\\openssh-ssh-agent",
-        keys,
-        started: false,
-        message: keys.length > 0 ? `Windows OpenSSH agent running with ${keys.length} key(s) loaded` : "Windows OpenSSH agent running but no keys loaded. Use ssh_key_load to add one."
-      };
-    }
+    const result = probeAgent("\\\\.\\pipe\\openssh-ssh-agent", "Windows OpenSSH agent");
+    if (result) return result;
   }
   const { stdout, ok } = runArgs("ssh-agent", ["-s"]);
   if (ok) {
@@ -305,7 +297,7 @@ function ensureAgent() {
         keys: [],
         started: true,
         env: { SSH_AUTH_SOCK: sockMatch[1], SSH_AGENT_PID: pidMatch?.[1] },
-        message: "Started new ssh-agent. No keys loaded yet \u2014 use ssh_key_load to add one."
+        message: "Started new ssh-agent scoped to the ssh-mcp server process. Your shell's environment is NOT modified \u2014 this agent is only visible to this MCP server and will terminate when the server exits. No keys loaded yet \u2014 use ssh_key_load to add one."
       };
     }
   }
@@ -431,8 +423,8 @@ function configLookup(host) {
     user: all.user || "",
     port: all.port || "22",
     identityFile: identityFiles,
-    proxyJump: all.proxyjump !== "none" ? all.proxyjump : void 0,
-    proxyCommand: all.proxycommand !== "none" ? all.proxycommand : void 0,
+    proxyJump: all.proxyjump && all.proxyjump !== "none" ? all.proxyjump : void 0,
+    proxyCommand: all.proxycommand && all.proxycommand !== "none" ? all.proxycommand : void 0,
     all,
     raw: stdout
   };
@@ -474,7 +466,7 @@ function checkGitSsh(host = "github.com", user = "git") {
   const { stdout } = runArgs("ssh", ["-T", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", `${user}@${host}`]);
   const text = stdout;
   if (text.includes("successfully authenticated") || text.includes("Welcome to GitLab") || text.includes("logged in as")) {
-    const userMatch = text.match(/Hi (\S+?)!/) || text.match(/@(\S+?)!/) || text.match(/logged in as (\S+)/);
+    const userMatch = text.match(/Hi (\S+)!/) || text.match(/@(\S+)!/) || text.match(/logged in as (\S+)/);
     return {
       status: "ok",
       message: `Git SSH authentication to ${host} succeeded${userMatch ? ` as ${userMatch[1]}` : ""}`,
@@ -581,42 +573,99 @@ function resolveFromSshConfig(host) {
     return null;
   }
 }
+function readKnownHostsKeys(host, port) {
+  if (!isValidHostname(host)) return [];
+  const targets = port && port !== 22 ? [`[${host}]:${port}`, host] : [host];
+  const keys = [];
+  for (const target of targets) {
+    const { stdout, ok } = runArgs("ssh-keygen", ["-F", target]);
+    if (!ok || !stdout.trim()) continue;
+    for (const line of stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts.length < 3) continue;
+      try {
+        keys.push(Buffer.from(parts[2], "base64"));
+      } catch {
+      }
+    }
+  }
+  return keys;
+}
+function buildHostVerifier(hosts, port) {
+  const strict = process.env.SSH_MCP_STRICT_HOST_KEY === "1";
+  return (key) => {
+    const known = hosts.flatMap((h) => readKnownHostsKeys(h, port));
+    if (known.length === 0) {
+      return !strict;
+    }
+    return known.some((k) => k.equals(key));
+  };
+}
 function resolveConfig(config) {
   const sshConfig = resolveFromSshConfig(config.host);
+  const port = config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22);
+  const verifierHosts = [config.host];
+  if (sshConfig?.hostname && sshConfig.hostname !== config.host) {
+    verifierHosts.push(sshConfig.hostname);
+  }
   const connectConfig = {
     host: sshConfig?.hostname || config.host,
-    port: config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22),
+    port,
     username: config.username || sshConfig?.user || process.env.USER || process.env.USERNAME || "root",
     keepaliveInterval: 15e3,
-    keepaliveCountMax: 3
+    keepaliveCountMax: 3,
+    hostVerifier: buildHostVerifier(verifierHosts, port)
   };
-  const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
-  if (agentSock) {
-    connectConfig.agent = agentSock;
-  }
-  if (config.password) {
-    connectConfig.password = config.password;
-  }
   if (config.privateKeyPath) {
     connectConfig.privateKey = readFileSync3(config.privateKeyPath);
-  } else if (!agentSock) {
-    const home = homedir3();
-    const keyPaths = sshConfig && sshConfig.identityFiles.length > 0 ? sshConfig.identityFiles.map((p) => p.startsWith("~") ? join3(home, p.slice(1)) : p) : [join3(home, ".ssh", "id_ed25519"), join3(home, ".ssh", "id_rsa"), join3(home, ".ssh", "id_ecdsa")];
-    for (const keyPath of keyPaths) {
-      try {
-        connectConfig.privateKey = readFileSync3(keyPath);
-        break;
-      } catch {
+  } else if (config.password) {
+    connectConfig.password = config.password;
+  } else {
+    const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
+    if (agentSock) {
+      connectConfig.agent = agentSock;
+    } else {
+      const home = homedir3();
+      const keyPaths = sshConfig && sshConfig.identityFiles.length > 0 ? sshConfig.identityFiles.map((p) => p.startsWith("~") ? join3(home, p.slice(1)) : p) : [join3(home, ".ssh", "id_ed25519"), join3(home, ".ssh", "id_rsa"), join3(home, ".ssh", "id_ecdsa")];
+      for (const keyPath of keyPaths) {
+        try {
+          connectConfig.privateKey = readFileSync3(keyPath);
+          break;
+        } catch {
+        }
       }
     }
   }
   return { connectConfig, proxyJump: sshConfig?.proxyJump };
 }
+var DIAG_CACHE_TTL_MS = 2e3;
+var diagAgentCache = null;
+var diagKeysCache = null;
+function cachedAgentCheck() {
+  const now = Date.now();
+  if (diagAgentCache && now - diagAgentCache.at < DIAG_CACHE_TTL_MS) {
+    return diagAgentCache.result;
+  }
+  const result = checkSshAgent();
+  diagAgentCache = { at: now, result };
+  return result;
+}
+function cachedKeysCheck() {
+  const now = Date.now();
+  if (diagKeysCache && now - diagKeysCache.at < DIAG_CACHE_TTL_MS) {
+    return diagKeysCache.result;
+  }
+  const result = checkSshKeys();
+  diagKeysCache = { at: now, result };
+  return result;
+}
 function formatDiagnostics(host) {
   try {
     const checks = [
-      { name: "SSH Agent", ...checkSshAgent() },
-      { name: "SSH Keys", ...checkSshKeys() },
+      { name: "SSH Agent", ...cachedAgentCheck() },
+      { name: "SSH Keys", ...cachedKeysCheck() },
       { name: "SSH Config", ...checkSshConfig(host) },
       { name: "Known Hosts", ...checkKnownHosts(host) }
     ];
@@ -693,7 +742,8 @@ ${diag}`);
     throw err;
   }
 }
-function exec(client, command, timeoutMs = 3e4) {
+var DEFAULT_MAX_EXEC_BYTES = 10 * 1024 * 1024;
+function exec(client, command, timeoutMs = 3e4, maxBytes = DEFAULT_MAX_EXEC_BYTES) {
   return new Promise((resolve, reject) => {
     let settled = false;
     const settle = (fn) => {
@@ -710,18 +760,52 @@ function exec(client, command, timeoutMs = 3e4) {
         settle(() => reject(err));
         return;
       }
-      let stdout = "";
-      let stderr = "";
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      let stdoutBytes = 0;
+      let stderrBytes = 0;
+      let stdoutTruncated = false;
+      let stderrTruncated = false;
+      const appendStdout = (data) => {
+        if (stdoutTruncated) return;
+        const remaining = maxBytes - stdoutBytes;
+        if (data.length <= remaining) {
+          stdoutChunks.push(data);
+          stdoutBytes += data.length;
+        } else {
+          if (remaining > 0) {
+            stdoutChunks.push(data.subarray(0, remaining));
+            stdoutBytes += remaining;
+          }
+          stdoutTruncated = true;
+        }
+      };
+      const appendStderr = (data) => {
+        if (stderrTruncated) return;
+        const remaining = maxBytes - stderrBytes;
+        if (data.length <= remaining) {
+          stderrChunks.push(data);
+          stderrBytes += data.length;
+        } else {
+          if (remaining > 0) {
+            stderrChunks.push(data.subarray(0, remaining));
+            stderrBytes += remaining;
+          }
+          stderrTruncated = true;
+        }
+      };
       stream.on("close", (code) => {
+        let stdout = Buffer.concat(stdoutChunks).toString("utf8");
+        let stderr = Buffer.concat(stderrChunks).toString("utf8");
+        if (stdoutTruncated) stdout += `
+[output truncated at ${maxBytes} bytes]`;
+        if (stderrTruncated) stderr += `
+[stderr truncated at ${maxBytes} bytes]`;
         settle(() => resolve({ stdout, stderr, code: code ?? 0 }));
-      }).on("data", (data) => {
-        stdout += data.toString();
-      }).on("error", (err2) => {
+      }).on("data", appendStdout).on("error", (err2) => {
         settle(() => reject(err2));
       });
-      stream.stderr.on("data", (data) => {
-        stderr += data.toString();
-      }).on("error", (err2) => {
+      stream.stderr.on("data", appendStderr).on("error", (err2) => {
         settle(() => reject(err2));
       });
     });
@@ -858,8 +942,11 @@ async function find(client, options, timeoutMs = 3e4) {
   if (options.minsize) args.push("-size", `+${options.minsize}`);
   if (options.maxsize) args.push("-size", `-${options.maxsize}`);
   if (options.newer) args.push("-newer", shellQuote(options.newer));
-  const command = `find ${args.join(" ")} 2>/dev/null`;
+  const command = `find ${args.join(" ")}`;
   const result = await exec(client, command, timeoutMs);
+  if (!result.stdout.trim() && result.stderr.trim()) {
+    throw new Error(result.stderr.trim());
+  }
   return result.stdout.split("\n").filter(Boolean);
 }
 async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
@@ -868,7 +955,7 @@ async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
     command += ` | grep -i ${shellQuote(grep)}`;
   }
   const result = await exec(client, command, timeoutMs);
-  if (result.code !== 0 && result.stderr && !grep) {
+  if (result.stderr.trim()) {
     throw new Error(result.stderr.trim());
   }
   return result.stdout;
@@ -894,8 +981,14 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
 // src/pool.ts
 var ConnectionPool = class {
   entries = /* @__PURE__ */ new Map();
+  // Coalesces concurrent connect attempts for the same key so we don't open N
+  // duplicate TCP connections when N tool calls fire simultaneously.
+  pending = /* @__PURE__ */ new Map();
   idleTtlMs;
   maxPoolSize;
+  // Total number of successful connects ever made by this pool. Useful for
+  // introspection and for tests that want to prove connection reuse.
+  _connectCount = 0;
   constructor(options) {
     this.idleTtlMs = options?.idleTtlMs ?? 6e4;
     this.maxPoolSize = options?.maxPoolSize ?? 100;
@@ -904,67 +997,98 @@ var ConnectionPool = class {
     const resolved = resolveConfig(config);
     const cc = resolved.connectConfig;
     const key = `${cc.username}@${cc.host}:${cc.port}`;
-    const existing = this.entries.get(key);
-    if (existing && !existing.dead) {
-      existing.refCount++;
-      if (existing.idleTimer) {
-        clearTimeout(existing.idleTimer);
-        existing.idleTimer = null;
-      }
-      return existing.client;
-    }
-    if (existing?.dead) {
-      this.entries.delete(key);
-    }
-    if (this.entries.size >= this.maxPoolSize) {
-      let evicted = false;
-      for (const [k, e] of this.entries) {
-        if (e.refCount === 0) {
-          if (e.idleTimer) clearTimeout(e.idleTimer);
-          try {
-            e.client.end();
-          } catch {
-          }
-          this.entries.delete(k);
-          evicted = true;
-          break;
+    const MAX_ACQUIRE_ATTEMPTS = 3;
+    let lastErr;
+    for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
+      const existing = this.entries.get(key);
+      if (existing && !existing.dead) {
+        existing.refCount++;
+        if (existing.idleTimer) {
+          clearTimeout(existing.idleTimer);
+          existing.idleTimer = null;
         }
+        return existing.client;
       }
-      if (!evicted) {
-        throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+      if (existing?.dead) {
+        this.entries.delete(key);
       }
-    }
-    try {
-      const client = await connectWithProxy(resolved);
-      const entry = { client, key, refCount: 1, idleTimer: null, dead: false };
-      const markDead = () => {
-        entry.dead = true;
-        if (entry.idleTimer) {
-          clearTimeout(entry.idleTimer);
-          entry.idleTimer = null;
-        }
-        if (this.entries.get(key) === entry) {
-          this.entries.delete(key);
+      let pending = this.pending.get(key);
+      if (!pending) {
+        if (this.entries.size >= this.maxPoolSize) {
+          let evicted = false;
+          for (const [k, e] of this.entries) {
+            if (e.refCount === 0) {
+              if (e.idleTimer) clearTimeout(e.idleTimer);
+              try {
+                e.client.end();
+              } catch {
+              }
+              this.entries.delete(k);
+              evicted = true;
+              break;
+            }
+          }
+          if (!evicted) {
+            throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+          }
         }
-      };
-      client.on("close", markDead);
-      client.on("end", markDead);
-      client.on("error", markDead);
-      this.entries.set(key, entry);
-      return client;
-    } catch (err) {
-      const diag = formatDiagnostics(config.host);
-      if (diag) {
-        const message = err instanceof Error ? err.message : String(err);
-        const enhanced = new Error(`${message}
+        pending = (async () => {
+          try {
+            const client2 = await connectWithProxy(resolved);
+            this._connectCount++;
+            const entry2 = { client: client2, key, refCount: 0, idleTimer: null, dead: false };
+            const markDead = () => {
+              entry2.dead = true;
+              if (entry2.idleTimer) {
+                clearTimeout(entry2.idleTimer);
+                entry2.idleTimer = null;
+              }
+              if (this.entries.get(key) === entry2) {
+                this.entries.delete(key);
+              }
+            };
+            client2.on("close", markDead);
+            client2.on("end", markDead);
+            client2.on("error", markDead);
+            this.entries.set(key, entry2);
+            return client2;
+          } finally {
+            this.pending.delete(key);
+          }
+        })();
+        this.pending.set(key, pending);
+      }
+      let client;
+      try {
+        client = await pending;
+      } catch (err) {
+        const diag = formatDiagnostics(config.host);
+        if (diag) {
+          const message = err instanceof Error ? err.message : String(err);
+          const enhanced = new Error(`${message}
 
 SSH Diagnostics:
 ${diag}`);
-        enhanced.cause = err;
-        throw enhanced;
+          enhanced.cause = err;
+          throw enhanced;
+        }
+        throw err;
+      }
+      const entry = this.entries.get(key);
+      if (!entry || entry.dead || entry.client !== client) {
+        lastErr = new Error("connection died before acquire could take a ref");
+        continue;
+      }
+      entry.refCount++;
+      if (entry.idleTimer) {
+        clearTimeout(entry.idleTimer);
+        entry.idleTimer = null;
       }
-      throw err;
+      return client;
     }
+    throw new Error(
+      `Failed to acquire SSH connection for ${key} after ${MAX_ACQUIRE_ATTEMPTS} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+    );
   }
   release(client) {
     for (const entry of this.entries.values()) {
@@ -1020,6 +1144,10 @@ ${diag}`);
     }
     return { active, idle };
   }
+  /** Total number of successful SSH connects made by this pool since construction. */
+  get connectCount() {
+    return this._connectCount;
+  }
 };
 
 // src/tools.ts
@@ -1027,7 +1155,9 @@ var HostSchema = z.string().describe("SSH hostname or IP address");
 var PortSchema = z.number().int().min(1).max(65535).optional().describe("SSH port (default: 22)");
 var UsernameSchema = z.string().optional().describe("SSH username (default: current user)");
 var KeyPathSchema = z.string().optional().describe("Path to SSH private key");
-var PasswordSchema = z.string().optional().describe("SSH password (prefer keys)");
+var PasswordSchema = z.string().optional().describe(
+  "SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."
+);
 var TimeoutSchema = z.number().int().positive().optional().describe("Command timeout in milliseconds (default: 30000)");
 var connectionParams = {
   host: HostSchema,
@@ -1040,14 +1170,14 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. Returns stdout, stderr, and exit code.",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code.",
     {
       ...connectionParams,
-      command: z.string().describe("Shell command to execute on the remote host"),
+      command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
       timeout: TimeoutSchema
     },
-    async ({ host, port, username, privateKeyPath, password, command, timeout }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ command, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const result = await exec(client, command, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
@@ -1065,8 +1195,8 @@ ${result.stderr}`);
       ...connectionParams,
       path: z.string().describe("Absolute path to the remote file")
     },
-    async ({ host, port, username, privateKeyPath, password, path }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const content = await readFile(client, path);
         return { content: [{ type: "text", text: content }] };
       });
@@ -1080,8 +1210,8 @@ ${result.stderr}`);
       path: z.string().describe("Absolute path to the remote file"),
       content: z.string().describe("File content to write")
     },
-    async ({ host, port, username, privateKeyPath, password, path, content }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, content, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         await writeFile(client, path, content);
         return { content: [{ type: "text", text: `Wrote ${content.length} bytes to ${path}` }] };
       });
@@ -1095,8 +1225,8 @@ ${result.stderr}`);
       localPath: z.string().describe("Path to the local file to upload"),
       remotePath: z.string().describe("Absolute path on the remote host")
     },
-    async ({ host, port, username, privateKeyPath, password, localPath, remotePath }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ localPath, remotePath, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         await uploadFile(client, localPath, remotePath);
         return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
       });
@@ -1110,8 +1240,8 @@ ${result.stderr}`);
       remotePath: z.string().describe("Absolute path to the remote file"),
       localPath: z.string().describe("Local path to save the downloaded file")
     },
-    async ({ host, port, username, privateKeyPath, password, remotePath, localPath }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ remotePath, localPath, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         await downloadFile(client, remotePath, localPath);
         return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
       });
@@ -1124,8 +1254,8 @@ ${result.stderr}`);
       ...connectionParams,
       path: z.string().describe("Absolute path to the remote directory")
     },
-    async ({ host, port, username, privateKeyPath, password, path }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const files = await listDir(client, path);
         return { content: [{ type: "text", text: files.join("\n") }] };
       });
@@ -1331,21 +1461,8 @@ ${result.stderr}`);
       maxsize: z.string().optional().describe("Maximum file size (e.g. '10M', '500k')"),
       timeout: TimeoutSchema
     },
-    async ({
-      host,
-      port,
-      username,
-      privateKeyPath,
-      password,
-      path,
-      name,
-      type,
-      maxdepth,
-      minsize,
-      maxsize,
-      timeout
-    }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, name, type, maxdepth, minsize, maxsize, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const files = await find(client, { path, name, type, maxdepth, minsize, maxsize }, timeout || 3e4);
         if (files.length === 0) {
           return { content: [{ type: "text", text: "No files found." }] };
@@ -1365,8 +1482,8 @@ ${files.join("\n")}` }] };
       grep: z.string().optional().describe("Case-insensitive pattern to filter lines"),
       timeout: TimeoutSchema
     },
-    async ({ host, port, username, privateKeyPath, password, path, lines, grep, timeout }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ path, lines, grep, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const output = await tail(client, path, lines || 100, grep, timeout || 3e4);
         if (!output.trim()) {
           return {
@@ -1390,8 +1507,8 @@ ${files.join("\n")}` }] };
       service: z.string().describe("Systemd service name (e.g. nginx, sshd, docker)"),
       timeout: TimeoutSchema
     },
-    async ({ host, port, username, privateKeyPath, password, service, timeout }) => {
-      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
+    async ({ service, timeout, ...conn }) => {
+      return connectionPool.withConnection(conn, async (client) => {
         const status = await serviceStatus(client, service, timeout || 3e4);
         const lines = [];
         lines.push(`Service: ${status.name}`);
@@ -1411,7 +1528,7 @@ ${files.join("\n")}` }] };
 function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.6.0"
+    version: "0.7.0"
   });
   registerTools(server, pool);
   return server;
@@ -1441,6 +1558,7 @@ export {
   loadKey,
   multiExec,
   readFile,
+  readKnownHostsKeys,
   registerTools,
   resolveConfig,
   serviceStatus,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "MCP server for SSH operations with built-in diagnostics",
   "type": "module",
   "bin": {