@yawlabs/ssh-mcp 0.3.0 → 0.4.0

package/README.md

@@ -77,6 +77,14 @@ Tools that fix your local SSH setup so everything else — git, deploys, tunnels
 
 When any remote operation fails, ssh-mcp automatically runs diagnostics and includes the results in the error response. Your agent doesn't need to call `ssh_diagnose` separately — it gets told what's wrong and how to fix it right in the error message.
 
+### Connection pooling
+
+Remote operations reuse SSH connections automatically. When your agent makes multiple calls to the same host, the first call opens a connection and subsequent calls reuse it. Connections are kept alive for 60 seconds after the last use, then closed automatically.
+
+### SSH config support
+
+All connections respect your `~/.ssh/config`. Host aliases, custom ports, usernames, and identity files from your SSH config are used automatically. If you have `Host myserver` configured in your SSH config, just pass `host: "myserver"` — ssh-mcp resolves the real hostname, user, port, and identity file.
+
 ## Authentication
 
 All remote operations accept connection parameters:
@@ -84,12 +92,12 @@ All remote operations accept connection parameters:
 | Parameter | Description | Default |
 |-----------|-------------|---------|
 | `host` | SSH hostname or IP (required) | — |
-| `port` | SSH port | `22` |
-| `username` | SSH username | Current user |
+| `port` | SSH port | From SSH config or `22` |
+| `username` | SSH username | From SSH config or current user |
 | `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`) > default key paths (`~/.ssh/id_ed25519`, `id_rsa`, `id_ecdsa`).
+**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`).
 
 ## Example workflows
 
@@ -123,7 +131,7 @@ Agent reports: "SSH server isn't running on new-server or port 22 is blocked"
 ## Programmatic usage
 
 ```typescript
-import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh } from '@yawlabs/ssh-mcp';
+import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh, ConnectionPool } from '@yawlabs/ssh-mcp';
 
 // Fix SSH environment
 const agent = ensureAgent();
@@ -139,12 +147,25 @@ for (const key of keys) {
   console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
 }
 
-// Run a remote command
+// Run a remote command (one-off)
 const client = await connect({ host: 'my-server', username: 'deploy' });
 const result = await exec(client, 'uptime');
 console.log(result.stdout);
 client.end();
 
+// Run multiple commands with connection pooling
+const pool = new ConnectionPool();
+await pool.withConnection({ host: 'my-server' }, async (client) => {
+  const r1 = await exec(client, 'uptime');
+  console.log(r1.stdout);
+});
+// Connection stays open for 60s — next call reuses it
+await pool.withConnection({ host: 'my-server' }, async (client) => {
+  const r2 = await exec(client, 'df -h');
+  console.log(r2.stdout);
+});
+pool.drain(); // close all connections when done
+
 // Diagnose issues
 const report = diagnose('my-server');
 console.log(report.overall); // "ok" | "warning" | "error"

package/dist/index.js

@@ -3,11 +3,11 @@
 // 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 { execFileSync } from "child_process";
@@ -238,10 +238,330 @@ function diagnose(host, port = 22) {
   return { overall, checks, suggestions };
 }
 
+// src/ssh.ts
+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: 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 (!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 {
+      }
+    }
+  }
+  return connectConfig;
+}
+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();
+    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(() => {
+      settle(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)));
+    }, timeoutMs);
+    client.exec(command, (err, stream) => {
+      if (err) {
+        settle(() => reject(err));
+        return;
+      }
+      let stdout = "";
+      let stderr = "";
+      stream.on("close", (code) => {
+        settle(() => resolve({ stdout, stderr, code: code ?? 0 }));
+      }).on("data", (data) => {
+        stdout += data.toString();
+      }).on("error", (err2) => {
+        settle(() => reject(err2));
+      });
+      stream.stderr.on("data", (data) => {
+        stderr += data.toString();
+      }).on("error", (err2) => {
+        settle(() => reject(err2));
+      });
+    });
+  });
+}
+function getSftp(client) {
+  return new Promise((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) return reject(err);
+      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();
+  }
+}
+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();
+  }
+}
+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();
+  }
+}
+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();
+  }
+}
+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 readFileSync2, readdirSync as readdirSync2, statSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+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) {
@@ -289,7 +609,7 @@ function detectKeyType(filePath, fileName) {
   const pubPath = `${filePath}.pub`;
   if (existsSync2(pubPath)) {
     try {
-      const pub = readFileSync2(pubPath, "utf8");
+      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";
@@ -302,7 +622,7 @@ function detectKeyType(filePath, fileName) {
   if (fileName.includes("ecdsa")) return "ecdsa";
   if (fileName.includes("dsa")) return "dsa";
   try {
-    const content = readFileSync2(filePath, "utf8");
+    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";
@@ -311,7 +631,7 @@ function detectKeyType(filePath, fileName) {
   return "unknown";
 }
 function listSshKeys() {
-  const sshDir = join2(homedir2(), ".ssh");
+  const sshDir = join3(homedir3(), ".ssh");
   if (!existsSync2(sshDir)) return [];
   const loadedFingerprints = /* @__PURE__ */ new Set();
   const { stdout: agentOut, ok: agentOk } = runArgs("ssh-add", ["-l"]);
@@ -331,11 +651,11 @@ function listSshKeys() {
   }
   for (const file of files) {
     if (file.endsWith(".pub") || file.startsWith(".") || skipFiles.has(file)) continue;
-    const filePath = join2(sshDir, file);
+    const filePath = join3(sshDir, file);
     try {
       const stat = statSync(filePath);
       if (!stat.isFile()) continue;
-      const content = readFileSync2(filePath, "utf8");
+      const content = readFileSync3(filePath, "utf8");
       if (!content.includes("PRIVATE KEY")) continue;
       const type = detectKeyType(filePath, file);
       let fingerprint;
@@ -356,7 +676,7 @@ function loadKey(keyPath) {
   if (!agent.reachable) {
     return { status: "error", message: agent.message };
   }
-  const resolved = keyPath.startsWith("~") ? join2(homedir2(), keyPath.slice(1)) : keyPath;
+  const resolved = keyPath.startsWith("~") ? join3(homedir3(), keyPath.slice(1)) : keyPath;
   if (!existsSync2(resolved)) {
     return { status: "error", message: `Key not found: ${resolved}` };
   }
@@ -422,7 +742,7 @@ function fixKnownHosts(host, port = 22) {
   const { stdout: scanOut, ok: scanOk } = runArgs("ssh-keyscan", scanArgs);
   if (scanOk && scanOut.trim()) {
     try {
-      const knownHostsPath = join2(homedir2(), ".ssh", "known_hosts");
+      const knownHostsPath = join3(homedir3(), ".ssh", "known_hosts");
       appendFileSync(knownHostsPath, `
 ${scanOut.trim()}
 `);
@@ -515,194 +835,6 @@ function testConnection(host, port = 22) {
   return { status: "error", message: `Connection failed to ${host}:${port}: ${stdout}` };
 }
 
-// src/ssh.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
-import { Client } from "ssh2";
-function resolveConfig(config) {
-  const connectConfig = {
-    host: config.host,
-    port: config.port || 22,
-    username: config.username || process.env.USER || process.env.USERNAME || "root"
-  };
-  if (config.privateKeyPath) {
-    connectConfig.privateKey = readFileSync3(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 {
-    const home = homedir3();
-    const defaultKeys = ["id_ed25519", "id_rsa", "id_ecdsa"];
-    for (const keyName of defaultKeys) {
-      const keyPath = join3(home, ".ssh", keyName);
-      try {
-        connectConfig.privateKey = readFileSync3(keyPath);
-        break;
-      } catch {
-      }
-    }
-  }
-  return connectConfig;
-}
-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 connect(config) {
-  return new Promise((resolve, reject) => {
-    const client = new Client();
-    const connectConfig = resolveConfig(config);
-    client.on("ready", () => resolve(client)).on("error", (err) => {
-      const diag = formatDiagnostics(config.host);
-      if (diag) {
-        const enhanced = new Error(`${err.message}
-
-SSH Diagnostics:
-${diag}`);
-        enhanced.cause = err;
-        reject(enhanced);
-      } else {
-        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(() => {
-      settle(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)));
-    }, timeoutMs);
-    client.exec(command, (err, stream) => {
-      if (err) {
-        settle(() => reject(err));
-        return;
-      }
-      let stdout = "";
-      let stderr = "";
-      stream.on("close", (code) => {
-        settle(() => resolve({ stdout, stderr, code: code ?? 0 }));
-      }).on("data", (data) => {
-        stdout += data.toString();
-      }).on("error", (err2) => {
-        settle(() => reject(err2));
-      });
-      stream.stderr.on("data", (data) => {
-        stderr += data.toString();
-      }).on("error", (err2) => {
-        settle(() => reject(err2));
-      });
-    });
-  });
-}
-function getSftp(client) {
-  return new Promise((resolve, reject) => {
-    client.sftp((err, sftp) => {
-      if (err) return reject(err);
-      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();
-  }
-}
-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();
-  }
-}
-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();
-  }
-}
-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();
-  }
-}
-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/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
 var PortSchema = z.number().optional().describe("SSH port (default: 22)");
@@ -717,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.",
@@ -727,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);
@@ -736,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(
@@ -749,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(
@@ -767,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(
@@ -785,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(
@@ -803,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(
@@ -820,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(
@@ -988,19 +1103,26 @@ ${result.stderr}`);
 }
 
 // src/server.ts
-function createServer() {
+function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.3.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) => {

package/dist/server.d.ts

@@ -1,25 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { Client } from 'ssh2';
-
-declare function registerTools(server: McpServer): void;
-
-interface DiagnosticResult {
-    status: "ok" | "warning" | "error";
-    message: string;
-}
-interface DiagnosticReport {
-    overall: "ok" | "warning" | "error";
-    checks: Array<{
-        name: string;
-    } & DiagnosticResult>;
-    suggestions: string[];
-}
-declare function checkSshAgent(): DiagnosticResult;
-declare function checkSshKeys(): DiagnosticResult;
-declare function checkKnownHosts(host: string): DiagnosticResult;
-declare function checkConnectivity(host: string, port?: number): DiagnosticResult;
-declare function checkSshConfig(host: string): DiagnosticResult;
-declare function diagnose(host: string, port?: number): DiagnosticReport;
+import { Client, ConnectConfig } from 'ssh2';
 
 interface SSHConfig {
     host: string;
@@ -34,6 +14,8 @@ interface ExecResult {
     stderr: string;
     code: number;
 }
+declare function resolveConfig(config: SSHConfig): ConnectConfig;
+declare function connectRaw(connectConfig: ConnectConfig): Promise<Client>;
 declare function connect(config: SSHConfig): Promise<Client>;
 declare function exec(client: Client, command: string, timeoutMs?: number): Promise<ExecResult>;
 declare function readFile(client: Client, remotePath: string): Promise<string>;
@@ -42,6 +24,45 @@ declare function uploadFile(client: Client, localPath: string, remotePath: strin
 declare function downloadFile(client: Client, remotePath: string, localPath: string): Promise<void>;
 declare function listDir(client: Client, remotePath: string): Promise<string[]>;
 
+interface PoolOptions {
+    /** Milliseconds before an idle connection is closed. Default: 60000 (60s) */
+    idleTtlMs?: number;
+}
+declare class ConnectionPool {
+    private entries;
+    private idleTtlMs;
+    constructor(options?: PoolOptions);
+    acquire(config: SSHConfig): Promise<Client>;
+    release(client: Client): void;
+    withConnection<T>(config: SSHConfig, fn: (client: Client) => Promise<T>): Promise<T>;
+    drain(): void;
+    get size(): number;
+    get stats(): {
+        active: number;
+        idle: number;
+    };
+}
+
+declare function registerTools(server: McpServer, pool?: ConnectionPool): void;
+
+interface DiagnosticResult {
+    status: "ok" | "warning" | "error";
+    message: string;
+}
+interface DiagnosticReport {
+    overall: "ok" | "warning" | "error";
+    checks: Array<{
+        name: string;
+    } & DiagnosticResult>;
+    suggestions: string[];
+}
+declare function checkSshAgent(): DiagnosticResult;
+declare function checkSshKeys(): DiagnosticResult;
+declare function checkKnownHosts(host: string): DiagnosticResult;
+declare function checkConnectivity(host: string, port?: number): DiagnosticResult;
+declare function checkSshConfig(host: string): DiagnosticResult;
+declare function diagnose(host: string, port?: number): DiagnosticReport;
+
 interface KeyInfo {
     name: string;
     path: string;
@@ -95,6 +116,6 @@ declare function testConnection(host: string, port?: number): {
     message: string;
 };
 
-declare function createServer(): McpServer;
+declare function createServer(pool?: ConnectionPool): McpServer;
 
-export { type AgentResult, type ConfigLookupResult, type DiagnosticReport, type DiagnosticResult, type ExecResult, type KeyInfo, type SSHConfig, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, createServer, diagnose, downloadFile, ensureAgent, exec, fixKnownHosts, listDir, listSshKeys, loadKey, readFile, registerTools, testConnection, uploadFile, writeFile };
+export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type KeyInfo, type PoolOptions, type SSHConfig, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, createServer, diagnose, downloadFile, ensureAgent, exec, fixKnownHosts, listDir, listSshKeys, loadKey, readFile, registerTools, resolveConfig, testConnection, uploadFile, writeFile };

package/dist/server.js

@@ -515,23 +515,56 @@ import { readFileSync as readFileSync3 } from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join3 } 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 = readFileSync3(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 = homedir3();
-    const defaultKeys = ["id_ed25519", "id_rsa", "id_ecdsa"];
-    for (const keyName of defaultKeys) {
-      const keyPath = join3(home, ".ssh", keyName);
+    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;
@@ -571,24 +604,29 @@ function formatDiagnostics(host) {
     return "";
   }
 }
-function connect(config) {
+function connectRaw(connectConfig) {
   return new Promise((resolve, reject) => {
     const client = new Client();
-    const connectConfig = resolveConfig(config);
-    client.on("ready", () => resolve(client)).on("error", (err) => {
-      const diag = formatDiagnostics(config.host);
-      if (diag) {
-        const enhanced = new Error(`${err.message}
+    client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
+  });
+}
+async function connect(config) {
+  const connectConfig = resolveConfig(config);
+  try {
+    return await connectRaw(connectConfig);
+  } 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;
-        reject(enhanced);
-      } else {
-        reject(err);
-      }
-    }).connect(connectConfig);
-  });
+      enhanced.cause = err;
+      throw enhanced;
+    }
+    throw err;
+  }
 }
 function exec(client, command, timeoutMs = 3e4) {
   return new Promise((resolve, reject) => {
@@ -698,6 +736,116 @@ async function listDir(client, remotePath) {
   }
 }
 
+// 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/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
 var PortSchema = z.number().optional().describe("SSH port (default: 22)");
@@ -712,7 +860,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.",
@@ -722,8 +871,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);
@@ -731,9 +879,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(
@@ -744,13 +890,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(
@@ -762,13 +905,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(
@@ -780,13 +920,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(
@@ -798,13 +935,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(
@@ -815,13 +949,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(
@@ -983,15 +1114,16 @@ ${result.stderr}`);
 }
 
 // src/server.ts
-function createServer() {
+function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.3.0"
+    version: "0.4.0"
   });
-  registerTools(server);
+  registerTools(server, pool);
   return server;
 }
 export {
+  ConnectionPool,
   checkConnectivity,
   checkGitSsh,
   checkKnownHosts,
@@ -1000,6 +1132,7 @@ export {
   checkSshKeys,
   configLookup,
   connect,
+  connectRaw,
   createServer,
   diagnose,
   downloadFile,
@@ -1011,6 +1144,7 @@ export {
   loadKey,
   readFile,
   registerTools,
+  resolveConfig,
   testConnection,
   uploadFile,
   writeFile

package/package.json

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