@yawlabs/ssh-mcp 0.1.0 → 0.4.0

package/dist/index.js

@@ -3,23 +3,29 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-// src/tools.ts
-import { z } from "zod";
+// src/ssh.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { Client } from "ssh2";
 
 // src/diagnose.ts
-import { execSync } from "child_process";
-import { existsSync, readFileSync } from "fs";
+import { execFileSync } from "child_process";
+import { existsSync, readFileSync, readdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-function run(cmd) {
+function isValidHostname(host) {
+  return /^[a-zA-Z0-9._\-:[\]]+$/.test(host) && host.length <= 253;
+}
+function runArgs(cmd, args) {
   try {
-    const stdout = execSync(cmd, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
+    const stdout = execFileSync(cmd, args, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
-    return { stdout: e.stdout?.toString().trim() || e.message || "", ok: false };
+    const stdout = e.stdout?.toString().trim() || "";
+    const stderr = e.stderr?.toString().trim() || "";
+    const output = [stdout, stderr].filter(Boolean).join("\n") || e.message || "";
+    return { stdout: output, ok: false };
   }
 }
 function checkSshAgent() {
@@ -30,7 +36,7 @@ function checkSshAgent() {
       message: "SSH_AUTH_SOCK is not set. ssh-agent is not running or not exported to this shell."
     };
   }
-  const { stdout, ok } = run("ssh-add -l");
+  const { stdout, ok } = runArgs("ssh-add", ["-l"]);
   if (!ok && stdout.includes("Could not open a connection")) {
     return {
       status: "error",
@@ -61,8 +67,9 @@ function checkSshKeys() {
     }
   }
   try {
-    const { stdout } = run(`ls "${sshDir}"`);
-    const allFiles = stdout.split("\n").filter((f) => !f.endsWith(".pub") && !["known_hosts", "config", "authorized_keys"].includes(f));
+    const allFiles = readdirSync(sshDir).filter(
+      (f) => !f.endsWith(".pub") && !["known_hosts", "known_hosts.old", "config", "authorized_keys"].includes(f)
+    );
     for (const f of allFiles) {
       if (!keyTypes.includes(f) && existsSync(join(sshDir, f))) {
         try {
@@ -92,19 +99,35 @@ function checkKnownHosts(host) {
       message: "~/.ssh/known_hosts does not exist. First connection to any host will prompt for verification."
     };
   }
-  const { stdout, ok } = run(`ssh-keygen -F "${host}"`);
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
+  const { stdout, ok } = runArgs("ssh-keygen", ["-F", host]);
   if (!ok || !stdout.trim()) {
     return {
       status: "warning",
-      message: `Host "${host}" is not in known_hosts. First connection will prompt for host key verification. To add it: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`
+      message: `Host "${host}" is not in known_hosts. First connection will prompt for host key verification. To add it: ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`
     };
   }
   return { status: "ok", message: `Host "${host}" found in known_hosts` };
 }
 function checkConnectivity(host, port = 22) {
-  const { ok, stdout } = run(
-    `ssh -o ConnectTimeout=5 -o BatchMode=yes -o StrictHostKeyChecking=no -p ${port} ${host} echo SSH_OK 2>&1`
-  );
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
+  const { ok, stdout } = runArgs("ssh", [
+    "-o",
+    "ConnectTimeout=5",
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=no",
+    "-p",
+    String(port),
+    host,
+    "echo",
+    "SSH_OK"
+  ]);
   if (ok && stdout.includes("SSH_OK")) {
     return { status: "ok", message: `SSH connection to ${host}:${port} succeeded` };
   }
@@ -129,7 +152,7 @@ function checkConnectivity(host, port = 22) {
   if (stdout.includes("Host key verification failed")) {
     return {
       status: "error",
-      message: `Host key verification failed for ${host}. The host key changed (instance recreated?). Fix: ssh-keygen -R ${host} && ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`
+      message: `Host key verification failed for ${host}. The host key changed (instance recreated?). Fix: ssh-keygen -R "${host}" && ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`
     };
   }
   if (stdout.includes("Could not resolve hostname")) {
@@ -153,8 +176,16 @@ function checkSshConfig(host) {
     for (const line of lines) {
       const trimmed = line.trim();
       if (/^Host\s+/i.test(trimmed)) {
-        const pattern = trimmed.replace(/^Host\s+/i, "").trim();
-        inHostBlock = pattern === host || pattern === "*";
+        const patterns = trimmed.replace(/^Host\s+/i, "").trim().split(/\s+/);
+        inHostBlock = patterns.some((p) => {
+          if (p === "*") return true;
+          if (p === host) return true;
+          if (p.includes("*")) {
+            const regex = new RegExp("^" + p.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$");
+            return regex.test(host);
+          }
+          return false;
+        });
         if (inHostBlock) hostConfig.push(trimmed);
       } else if (inHostBlock && trimmed) {
         hostConfig.push(trimmed);
@@ -174,6 +205,13 @@ ${hostConfig.join("\n")}` };
 function diagnose(host, port = 22) {
   const checks = [];
   const suggestions = [];
+  if (!isValidHostname(host)) {
+    return {
+      overall: "error",
+      checks: [{ name: "Input Validation", status: "error", message: `Invalid hostname: "${host}"` }],
+      suggestions: ["Provide a valid hostname (alphanumeric, dots, hyphens, colons, brackets only)"]
+    };
+  }
   const agent = checkSshAgent();
   checks.push({ name: "SSH Agent", ...agent });
   if (agent.status === "error") suggestions.push('Start ssh-agent: eval "$(ssh-agent -s)"');
@@ -185,12 +223,12 @@ function diagnose(host, port = 22) {
   checks.push({ name: "SSH Config", ...config });
   const known = checkKnownHosts(host);
   checks.push({ name: "Known Hosts", ...known });
-  if (known.status === "warning") suggestions.push(`Add host key: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`);
+  if (known.status === "warning") suggestions.push(`Add host key: ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`);
   const conn = checkConnectivity(host, port);
   checks.push({ name: "Connectivity", ...conn });
   if (conn.status === "error" && conn.message.includes("Host key verification")) {
-    suggestions.push(`Remove stale host key: ssh-keygen -R ${host}`);
-    suggestions.push(`Re-add host key: ssh-keyscan -H ${host} >> ~/.ssh/known_hosts`);
+    suggestions.push(`Remove stale host key: ssh-keygen -R "${host}"`);
+    suggestions.push(`Re-add host key: ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`);
   }
   if (conn.status === "error" && conn.message.includes("Permission denied")) {
     suggestions.push("Check loaded keys: ssh-add -l");
@@ -201,27 +239,56 @@ function diagnose(host, port = 22) {
 }
 
 // src/ssh.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
-import { Client } from "ssh2";
+function resolveFromSshConfig(host) {
+  try {
+    const { stdout, ok } = runArgs("ssh", ["-G", host]);
+    if (!ok) return null;
+    const config = {};
+    const identityFiles = [];
+    for (const line of stdout.split("\n")) {
+      const spaceIdx = line.indexOf(" ");
+      if (spaceIdx > 0) {
+        const key = line.substring(0, spaceIdx);
+        const value = line.substring(spaceIdx + 1);
+        if (key === "identityfile") {
+          identityFiles.push(value);
+        } else {
+          config[key] = value;
+        }
+      }
+    }
+    return {
+      hostname: config.hostname || host,
+      user: config.user || "",
+      port: config.port || "22",
+      identityFiles
+    };
+  } catch {
+    return null;
+  }
+}
 function resolveConfig(config) {
+  const sshConfig = resolveFromSshConfig(config.host);
   const connectConfig = {
-    host: config.host,
-    port: config.port || 22,
-    username: config.username || process.env.USER || process.env.USERNAME || "root"
+    host: sshConfig?.hostname || config.host,
+    port: config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22),
+    username: config.username || sshConfig?.user || process.env.USER || process.env.USERNAME || "root",
+    keepaliveInterval: 15e3,
+    keepaliveCountMax: 3
   };
+  const agentSock = config.agent || process.env.SSH_AUTH_SOCK;
+  if (agentSock) {
+    connectConfig.agent = agentSock;
+  }
+  if (config.password) {
+    connectConfig.password = config.password;
+  }
   if (config.privateKeyPath) {
     connectConfig.privateKey = readFileSync2(config.privateKeyPath);
-  } else if (config.password) {
-    connectConfig.password = config.password;
-  } else if (config.agent || process.env.SSH_AUTH_SOCK) {
-    connectConfig.agent = config.agent || process.env.SSH_AUTH_SOCK;
-  } else {
+  } else if (!agentSock) {
     const home = homedir2();
-    const defaultKeys = ["id_ed25519", "id_rsa", "id_ecdsa"];
-    for (const keyName of defaultKeys) {
-      const keyPath = join2(home, ".ssh", keyName);
+    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;
@@ -231,90 +298,541 @@ function resolveConfig(config) {
   }
   return connectConfig;
 }
-function connect(config) {
+function formatDiagnostics(host) {
+  try {
+    const checks = [
+      { name: "SSH Agent", ...checkSshAgent() },
+      { name: "SSH Keys", ...checkSshKeys() },
+      { name: "SSH Config", ...checkSshConfig(host) },
+      { name: "Known Hosts", ...checkKnownHosts(host) }
+    ];
+    const parts = [];
+    const suggestions = [];
+    for (const check of checks) {
+      if (check.status !== "ok") {
+        parts.push(`[${check.status.toUpperCase()}] ${check.name}: ${check.message}`);
+      }
+    }
+    const agent = checks[0];
+    if (agent.status === "error") suggestions.push('Start ssh-agent: eval "$(ssh-agent -s)"');
+    if (agent.status === "warning") suggestions.push("Load a key: ssh-add ~/.ssh/id_ed25519");
+    const keys = checks[1];
+    if (keys.status === "error") suggestions.push('Generate a key: ssh-keygen -t ed25519 -C "your@email.com"');
+    const known = checks[3];
+    if (known.status === "warning") suggestions.push(`Add host key: ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`);
+    if (suggestions.length > 0) {
+      parts.push(`Suggested fixes: ${suggestions.join(" | ")}`);
+    }
+    return parts.length > 0 ? parts.join("\n") : "";
+  } catch {
+    return "";
+  }
+}
+function connectRaw(connectConfig) {
   return new Promise((resolve, reject) => {
     const client = new Client();
-    const connectConfig = resolveConfig(config);
     client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
   });
 }
 function exec(client, command, timeoutMs = 3e4) {
   return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
     const timer = setTimeout(() => {
-      reject(new Error(`Command timed out after ${timeoutMs}ms`));
+      settle(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)));
     }, timeoutMs);
     client.exec(command, (err, stream) => {
       if (err) {
-        clearTimeout(timer);
-        return reject(err);
+        settle(() => reject(err));
+        return;
       }
       let stdout = "";
       let stderr = "";
       stream.on("close", (code) => {
-        clearTimeout(timer);
-        resolve({ stdout, stderr, code: code ?? 0 });
+        settle(() => resolve({ stdout, stderr, code: code ?? 0 }));
       }).on("data", (data) => {
         stdout += data.toString();
-      }).stderr.on("data", (data) => {
+      }).on("error", (err2) => {
+        settle(() => reject(err2));
+      });
+      stream.stderr.on("data", (data) => {
         stderr += data.toString();
+      }).on("error", (err2) => {
+        settle(() => reject(err2));
       });
     });
   });
 }
-function readFile(client, remotePath) {
+function getSftp(client) {
   return new Promise((resolve, reject) => {
     client.sftp((err, sftp) => {
       if (err) return reject(err);
-      sftp.readFile(remotePath, (err2, data) => {
-        if (err2) return reject(err2);
+      resolve(sftp);
+    });
+  });
+}
+async function readFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    return await new Promise((resolve, reject) => {
+      sftp.readFile(remotePath, (err, data) => {
+        if (err) return reject(err);
         resolve(data.toString("utf8"));
       });
     });
-  });
+  } finally {
+    sftp.end();
+  }
 }
-function writeFile(client, remotePath, content) {
-  return new Promise((resolve, reject) => {
-    client.sftp((err, sftp) => {
-      if (err) return reject(err);
-      sftp.writeFile(remotePath, content, (err2) => {
-        if (err2) return reject(err2);
+async function writeFile(client, remotePath, content) {
+  const sftp = await getSftp(client);
+  try {
+    await new Promise((resolve, reject) => {
+      sftp.writeFile(remotePath, content, (err) => {
+        if (err) return reject(err);
         resolve();
       });
     });
-  });
+  } finally {
+    sftp.end();
+  }
 }
-function uploadFile(client, localPath, remotePath) {
-  return new Promise((resolve, reject) => {
-    client.sftp((err, sftp) => {
-      if (err) return reject(err);
-      sftp.fastPut(localPath, remotePath, (err2) => {
-        if (err2) return reject(err2);
+async function uploadFile(client, localPath, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    await new Promise((resolve, reject) => {
+      sftp.fastPut(localPath, remotePath, (err) => {
+        if (err) return reject(err);
         resolve();
       });
     });
-  });
+  } finally {
+    sftp.end();
+  }
 }
-function downloadFile(client, remotePath, localPath) {
-  return new Promise((resolve, reject) => {
-    client.sftp((err, sftp) => {
-      if (err) return reject(err);
-      sftp.fastGet(remotePath, localPath, (err2) => {
-        if (err2) return reject(err2);
+async function downloadFile(client, remotePath, localPath) {
+  const sftp = await getSftp(client);
+  try {
+    await new Promise((resolve, reject) => {
+      sftp.fastGet(remotePath, localPath, (err) => {
+        if (err) return reject(err);
         resolve();
       });
     });
-  });
+  } finally {
+    sftp.end();
+  }
 }
-function listDir(client, remotePath) {
-  return new Promise((resolve, reject) => {
-    client.sftp((err, sftp) => {
-      if (err) return reject(err);
-      sftp.readdir(remotePath, (err2, list) => {
-        if (err2) return reject(err2);
+async function listDir(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    return await new Promise((resolve, reject) => {
+      sftp.readdir(remotePath, (err, list) => {
+        if (err) return reject(err);
         resolve(list.map((item) => item.filename));
       });
     });
-  });
+  } finally {
+    sftp.end();
+  }
+}
+
+// src/pool.ts
+var ConnectionPool = class {
+  entries = /* @__PURE__ */ new Map();
+  idleTtlMs;
+  constructor(options) {
+    this.idleTtlMs = options?.idleTtlMs ?? 6e4;
+  }
+  async acquire(config) {
+    const connectConfig = resolveConfig(config);
+    const key = `${connectConfig.username}@${connectConfig.host}:${connectConfig.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);
+    }
+    try {
+      const client = await connectRaw(connectConfig);
+      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);
+        }
+      };
+      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}
+
+SSH Diagnostics:
+${diag}`);
+        enhanced.cause = err;
+        throw enhanced;
+      }
+      throw err;
+    }
+  }
+  release(client) {
+    for (const entry of this.entries.values()) {
+      if (entry.client === client) {
+        entry.refCount = Math.max(0, entry.refCount - 1);
+        if (entry.refCount === 0 && !entry.dead) {
+          entry.idleTimer = setTimeout(() => {
+            try {
+              entry.client.end();
+            } catch {
+            }
+            this.entries.delete(entry.key);
+          }, this.idleTtlMs);
+          entry.idleTimer.unref();
+        }
+        return;
+      }
+    }
+    try {
+      client.end();
+    } catch {
+    }
+  }
+  async withConnection(config, fn) {
+    const client = await this.acquire(config);
+    try {
+      return await fn(client);
+    } finally {
+      this.release(client);
+    }
+  }
+  drain() {
+    for (const entry of this.entries.values()) {
+      if (entry.idleTimer) {
+        clearTimeout(entry.idleTimer);
+      }
+      try {
+        entry.client.end();
+      } catch {
+      }
+    }
+    this.entries.clear();
+  }
+  get size() {
+    return this.entries.size;
+  }
+  get stats() {
+    let active = 0;
+    let idle = 0;
+    for (const entry of this.entries.values()) {
+      if (entry.refCount > 0) active++;
+      else idle++;
+    }
+    return { active, idle };
+  }
+};
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/env.ts
+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 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 { stdout, ok } = runArgs("ssh-agent", ["-s"]);
+  if (ok) {
+    const sockMatch = stdout.match(/SSH_AUTH_SOCK=([^;]+)/);
+    const pidMatch = stdout.match(/SSH_AGENT_PID=([^;]+)/);
+    if (sockMatch) {
+      process.env.SSH_AUTH_SOCK = sockMatch[1];
+      if (pidMatch) process.env.SSH_AGENT_PID = pidMatch[1];
+      return {
+        running: true,
+        reachable: true,
+        socket: sockMatch[1],
+        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."
+      };
+    }
+  }
+  return {
+    running: false,
+    reachable: false,
+    keys: [],
+    started: false,
+    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+  };
+}
+function detectKeyType(filePath, fileName) {
+  const pubPath = `${filePath}.pub`;
+  if (existsSync2(pubPath)) {
+    try {
+      const pub = readFileSync3(pubPath, "utf8");
+      if (pub.includes("ssh-ed25519")) return "ed25519";
+      if (pub.includes("ssh-rsa")) return "rsa";
+      if (pub.includes("ecdsa")) return "ecdsa";
+      if (pub.includes("ssh-dss")) return "dsa";
+    } catch {
+    }
+  }
+  if (fileName.includes("ed25519")) return "ed25519";
+  if (fileName.includes("rsa")) return "rsa";
+  if (fileName.includes("ecdsa")) return "ecdsa";
+  if (fileName.includes("dsa")) return "dsa";
+  try {
+    const content = readFileSync3(filePath, "utf8");
+    if (content.includes("RSA PRIVATE KEY")) return "rsa";
+    if (content.includes("EC PRIVATE KEY")) return "ecdsa";
+    if (content.includes("DSA PRIVATE KEY")) return "dsa";
+  } catch {
+  }
+  return "unknown";
+}
+function listSshKeys() {
+  const sshDir = join3(homedir3(), ".ssh");
+  if (!existsSync2(sshDir)) return [];
+  const loadedFingerprints = /* @__PURE__ */ new Set();
+  const { stdout: agentOut, ok: agentOk } = runArgs("ssh-add", ["-l"]);
+  if (agentOk && !agentOut.includes("no identities")) {
+    for (const line of agentOut.split("\n").filter(Boolean)) {
+      const match = line.match(/(\S+:\S+)/);
+      if (match) loadedFingerprints.add(match[1]);
+    }
+  }
+  const skipFiles = /* @__PURE__ */ new Set(["known_hosts", "known_hosts.old", "config", "authorized_keys", "environment"]);
+  const keys = [];
+  let files;
+  try {
+    files = readdirSync2(sshDir);
+  } catch {
+    return [];
+  }
+  for (const file of files) {
+    if (file.endsWith(".pub") || file.startsWith(".") || skipFiles.has(file)) continue;
+    const filePath = join3(sshDir, file);
+    try {
+      const stat = statSync(filePath);
+      if (!stat.isFile()) continue;
+      const content = readFileSync3(filePath, "utf8");
+      if (!content.includes("PRIVATE KEY")) continue;
+      const type = detectKeyType(filePath, file);
+      let fingerprint;
+      const { stdout: fpOut, ok: fpOk } = runArgs("ssh-keygen", ["-lf", filePath]);
+      if (fpOk) {
+        const match = fpOut.match(/(\S+:\S+)/);
+        fingerprint = match?.[1];
+      }
+      const loadedInAgent = fingerprint ? loadedFingerprints.has(fingerprint) : false;
+      keys.push({ name: file, path: filePath, type, fingerprint, loadedInAgent });
+    } catch {
+    }
+  }
+  return keys;
+}
+function loadKey(keyPath) {
+  const agent = ensureAgent();
+  if (!agent.reachable) {
+    return { status: "error", message: agent.message };
+  }
+  const resolved = keyPath.startsWith("~") ? join3(homedir3(), keyPath.slice(1)) : keyPath;
+  if (!existsSync2(resolved)) {
+    return { status: "error", message: `Key not found: ${resolved}` };
+  }
+  const { stdout, ok } = runArgs("ssh-add", [resolved]);
+  if (ok) {
+    return { status: "ok", message: `Key loaded: ${resolved}` };
+  }
+  if (stdout.includes("passphrase") || stdout.includes("incorrect") || stdout.includes("bad permissions")) {
+    if (stdout.includes("UNPROTECTED PRIVATE KEY")) {
+      return { status: "error", message: `Key ${resolved} has too-open permissions. Fix: chmod 600 ${resolved}` };
+    }
+    return { status: "error", message: `Key ${resolved} requires a passphrase. Add it manually: ssh-add ${resolved}` };
+  }
+  return { status: "error", message: `Failed to load key: ${stdout}` };
+}
+function configLookup(host) {
+  if (!isValidHostname(host)) {
+    return { error: `Invalid hostname: "${host}"` };
+  }
+  const { stdout, ok } = runArgs("ssh", ["-G", host]);
+  if (!ok) {
+    return { error: `Failed to resolve SSH config for ${host}: ${stdout}` };
+  }
+  const all = {};
+  const identityFiles = [];
+  for (const line of stdout.split("\n")) {
+    const spaceIdx = line.indexOf(" ");
+    if (spaceIdx > 0) {
+      const key = line.substring(0, spaceIdx);
+      const value = line.substring(spaceIdx + 1);
+      if (key === "identityfile") {
+        identityFiles.push(value);
+      } else {
+        all[key] = value;
+      }
+    }
+  }
+  return {
+    hostname: all.hostname || 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,
+    all,
+    raw: stdout
+  };
+}
+function fixKnownHosts(host, port = 22) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"`, actions: [] };
+  }
+  const actions = [];
+  const { ok: removeOk } = runArgs("ssh-keygen", ["-R", host]);
+  if (removeOk) {
+    actions.push(`Removed old host key for ${host}`);
+  }
+  if (port !== 22) {
+    const { ok } = runArgs("ssh-keygen", ["-R", `[${host}]:${port}`]);
+    if (ok) actions.push(`Removed old host key for [${host}]:${port}`);
+  }
+  const scanArgs = port !== 22 ? ["-H", "-p", String(port), host] : ["-H", host];
+  const { stdout: scanOut, ok: scanOk } = runArgs("ssh-keyscan", scanArgs);
+  if (scanOk && scanOut.trim()) {
+    try {
+      const knownHostsPath = join3(homedir3(), ".ssh", "known_hosts");
+      appendFileSync(knownHostsPath, `
+${scanOut.trim()}
+`);
+      actions.push(`Added new host key for ${host}`);
+      return { status: "ok", message: `Host key refreshed for ${host}`, actions };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { status: "error", message: `Scanned key but failed to write known_hosts: ${msg}`, actions };
+    }
+  }
+  return { status: "error", message: `Could not scan host key for ${host}. Host may be unreachable.`, actions };
+}
+function checkGitSsh(host = "github.com", user = "git") {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
+  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+)/);
+    return {
+      status: "ok",
+      message: `Git SSH authentication to ${host} succeeded${userMatch ? ` as ${userMatch[1]}` : ""}`,
+      authenticatedAs: userMatch?.[1]
+    };
+  }
+  if (text.includes("Permission denied")) {
+    return {
+      status: "error",
+      message: `Permission denied for ${host}. Either no key is loaded in the agent or your key isn't registered with ${host}. Run ssh_key_list to check, then ssh_key_load if needed.`
+    };
+  }
+  if (text.includes("Connection refused")) {
+    return { status: "error", message: `Connection refused by ${host}. SSH may not be available on this host.` };
+  }
+  if (text.includes("timed out") || text.includes("Connection timed out")) {
+    return { status: "error", message: `Connection to ${host} timed out. Check your network or firewall.` };
+  }
+  if (text.includes("Could not resolve")) {
+    return { status: "error", message: `Could not resolve hostname "${host}". Check DNS or spelling.` };
+  }
+  return { status: "error", message: `Git SSH check for ${host}: ${text || "no response (agent may not be running)"}` };
+}
+function testConnection(host, port = 22) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
+  const start = Date.now();
+  const { ok, stdout } = runArgs("ssh", [
+    "-o",
+    "ConnectTimeout=5",
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "StrictHostKeyChecking=no",
+    "-p",
+    String(port),
+    host,
+    "echo",
+    "SSH_OK"
+  ]);
+  const elapsed = Date.now() - start;
+  if (ok && stdout.includes("SSH_OK")) {
+    return { status: "ok", message: `Connected to ${host}:${port} in ${elapsed}ms` };
+  }
+  if (stdout.includes("Permission denied")) {
+    return {
+      status: "error",
+      message: `Authentication failed to ${host}:${port} (${elapsed}ms). Key not authorized. Check: ssh-add -l, verify correct username, verify key is in remote authorized_keys.`
+    };
+  }
+  if (stdout.includes("Connection refused")) {
+    return {
+      status: "error",
+      message: `Connection refused at ${host}:${port}. SSH server not running or port blocked.`
+    };
+  }
+  if (stdout.includes("timed out")) {
+    return { status: "error", message: `Connection timed out to ${host}:${port}. Host down or firewall blocking.` };
+  }
+  if (stdout.includes("Host key verification failed")) {
+    return {
+      status: "error",
+      message: `Host key mismatch for ${host}. Instance was likely recreated. Fix with ssh_known_hosts_fix.`
+    };
+  }
+  if (stdout.includes("Could not resolve")) {
+    return { status: "error", message: `Could not resolve "${host}". Check DNS, /etc/hosts, or SSH config.` };
+  }
+  return { status: "error", message: `Connection failed to ${host}:${port}: ${stdout}` };
 }
 
 // src/tools.ts
@@ -331,7 +849,8 @@ var connectionParams = {
   privateKeyPath: KeyPathSchema,
   password: PasswordSchema
 };
-function registerTools(server) {
+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.",
@@ -341,8 +860,7 @@ function registerTools(server) {
       timeout: TimeoutSchema
     },
     async ({ host, port, username, privateKeyPath, password, command, timeout }) => {
-      const client = await connect({ host, port, username, privateKeyPath, password });
-      try {
+      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
         const result = await exec(client, command, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
@@ -350,9 +868,7 @@ function registerTools(server) {
 ${result.stderr}`);
         parts.push(`[exit code: ${result.code}]`);
         return { content: [{ type: "text", text: parts.join("\n") }] };
-      } finally {
-        client.end();
-      }
+      });
     }
   );
   server.tool(
@@ -363,13 +879,10 @@ ${result.stderr}`);
       path: z.string().describe("Absolute path to the remote file")
     },
     async ({ host, port, username, privateKeyPath, password, path }) => {
-      const client = await connect({ host, port, username, privateKeyPath, password });
-      try {
+      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
         const content = await readFile(client, path);
         return { content: [{ type: "text", text: content }] };
-      } finally {
-        client.end();
-      }
+      });
     }
   );
   server.tool(
@@ -381,13 +894,10 @@ ${result.stderr}`);
       content: z.string().describe("File content to write")
     },
     async ({ host, port, username, privateKeyPath, password, path, content }) => {
-      const client = await connect({ host, port, username, privateKeyPath, password });
-      try {
+      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
         await writeFile(client, path, content);
         return { content: [{ type: "text", text: `Wrote ${content.length} bytes to ${path}` }] };
-      } finally {
-        client.end();
-      }
+      });
     }
   );
   server.tool(
@@ -399,13 +909,10 @@ ${result.stderr}`);
       remotePath: z.string().describe("Absolute path on the remote host")
     },
     async ({ host, port, username, privateKeyPath, password, localPath, remotePath }) => {
-      const client = await connect({ host, port, username, privateKeyPath, password });
-      try {
+      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
         await uploadFile(client, localPath, remotePath);
         return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
-      } finally {
-        client.end();
-      }
+      });
     }
   );
   server.tool(
@@ -417,13 +924,10 @@ ${result.stderr}`);
       localPath: z.string().describe("Local path to save the downloaded file")
     },
     async ({ host, port, username, privateKeyPath, password, remotePath, localPath }) => {
-      const client = await connect({ host, port, username, privateKeyPath, password });
-      try {
+      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
         await downloadFile(client, remotePath, localPath);
         return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
-      } finally {
-        client.end();
-      }
+      });
     }
   );
   server.tool(
@@ -434,13 +938,10 @@ ${result.stderr}`);
       path: z.string().describe("Absolute path to the remote directory")
     },
     async ({ host, port, username, privateKeyPath, password, path }) => {
-      const client = await connect({ host, port, username, privateKeyPath, password });
-      try {
+      return connectionPool.withConnection({ host, port, username, privateKeyPath, password }, async (client) => {
         const files = await listDir(client, path);
         return { content: [{ type: "text", text: files.join("\n") }] };
-      } finally {
-        client.end();
-      }
+      });
     }
   );
   server.tool(
@@ -471,22 +972,157 @@ ${result.stderr}`);
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
+  server.tool(
+    "ssh_agent_ensure",
+    "Ensure ssh-agent is running and reachable. Starts a new agent if needed and sets environment variables so subsequent SSH operations work. Use this FIRST when SSH operations fail with agent-related errors.",
+    {},
+    async () => {
+      const result = ensureAgent();
+      const lines = [];
+      lines.push(result.message);
+      if (result.socket) lines.push(`Socket: ${result.socket}`);
+      if (result.keys.length > 0) {
+        lines.push("Loaded keys:");
+        for (const k of result.keys) lines.push(`  ${k}`);
+      }
+      if (result.env) {
+        lines.push("Environment variables set in this session:");
+        if (result.env.SSH_AUTH_SOCK) lines.push(`  SSH_AUTH_SOCK=${result.env.SSH_AUTH_SOCK}`);
+        if (result.env.SSH_AGENT_PID) lines.push(`  SSH_AGENT_PID=${result.env.SSH_AGENT_PID}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: !result.reachable };
+    }
+  );
+  server.tool(
+    "ssh_key_list",
+    "List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded.",
+    {},
+    async () => {
+      const keys = listSshKeys();
+      if (keys.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: 'No SSH private keys found in ~/.ssh/. Generate one: ssh-keygen -t ed25519 -C "your@email.com"'
+            }
+          ]
+        };
+      }
+      const lines = [`Found ${keys.length} SSH key(s):`, ""];
+      for (const key of keys) {
+        const status = key.loadedInAgent ? "LOADED" : "not loaded";
+        lines.push(`${key.name} (${key.type}) [${status}]`);
+        lines.push(`  Path: ${key.path}`);
+        if (key.fingerprint) lines.push(`  Fingerprint: ${key.fingerprint}`);
+        lines.push("");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "ssh_key_load",
+    "Load an SSH private key into the running agent. Ensures the agent is running first. Use this after ssh_key_list shows a key that is not loaded.",
+    {
+      keyPath: z.string().describe("Path to the SSH private key to load (e.g. ~/.ssh/id_ed25519)")
+    },
+    async ({ keyPath }) => {
+      const result = loadKey(keyPath);
+      return { content: [{ type: "text", text: result.message }], isError: result.status === "error" };
+    }
+  );
+  server.tool(
+    "ssh_config_lookup",
+    "Resolve the effective SSH configuration for a host. Shows hostname, user, port, identity files, proxy settings, and all other options from ~/.ssh/config. Use this to understand how SSH will connect to a host.",
+    {
+      host: HostSchema
+    },
+    async ({ host }) => {
+      const result = configLookup(host);
+      if ("error" in result) {
+        return { content: [{ type: "text", text: result.error }], isError: true };
+      }
+      const lines = [`SSH config for "${host}":`, ""];
+      lines.push(`  Hostname: ${result.hostname}`);
+      lines.push(`  User: ${result.user}`);
+      lines.push(`  Port: ${result.port}`);
+      if (result.identityFile.length > 0) {
+        lines.push(`  Identity files: ${result.identityFile.join(", ")}`);
+      }
+      if (result.proxyJump) lines.push(`  ProxyJump: ${result.proxyJump}`);
+      if (result.proxyCommand) lines.push(`  ProxyCommand: ${result.proxyCommand}`);
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "ssh_known_hosts_fix",
+    "Remove a stale host key from known_hosts and re-scan the host to add the current key. Use this when you see 'Host key verification failed' errors, typically after a server has been recreated or reprovisioned.",
+    {
+      host: HostSchema,
+      port: PortSchema
+    },
+    async ({ host, port }) => {
+      const result = fixKnownHosts(host, port || 22);
+      const lines = [result.message];
+      if (result.actions.length > 0) {
+        lines.push("");
+        lines.push("Actions taken:");
+        for (const a of result.actions) lines.push(`  - ${a}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: result.status === "error" };
+    }
+  );
+  server.tool(
+    "ssh_test",
+    "Quick connectivity test to an SSH host. Reports success/failure with timing and actionable error details. Lighter and faster than ssh_diagnose \u2014 use this for a quick check before running operations.",
+    {
+      host: HostSchema,
+      port: PortSchema
+    },
+    async ({ host, port }) => {
+      const result = testConnection(host, port || 22);
+      return { content: [{ type: "text", text: result.message }], isError: result.status === "error" };
+    }
+  );
+  server.tool(
+    "ssh_git_check",
+    "Test Git-over-SSH authentication to a hosting provider (GitHub, GitLab, Bitbucket, etc). Verifies your SSH key is registered and working. Use this when git clone/pull/push fails with SSH errors.",
+    {
+      host: z.string().optional().describe('Git hosting hostname (default: "github.com")'),
+      user: z.string().optional().describe('SSH user for the git host (default: "git")')
+    },
+    async ({ host, user }) => {
+      const result = checkGitSsh(host || "github.com", user || "git");
+      const lines = [result.message];
+      if (result.authenticatedAs) {
+        lines.push(`Authenticated as: ${result.authenticatedAs}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: result.status === "error" };
+    }
+  );
 }
 
 // src/server.ts
-function createServer() {
+function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.1.0"
+    version: "0.4.0"
   });
-  registerTools(server);
+  registerTools(server, pool);
   return server;
 }
 
 // src/index.ts
 async function main() {
-  const server = createServer();
+  const pool = new ConnectionPool();
+  const server = createServer(pool);
   const transport = new StdioServerTransport();
+  const shutdown = () => {
+    pool.drain();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
   await server.connect(transport);
 }
 main().catch((err) => {