@yawlabs/ssh-mcp 0.4.0 → 0.6.0

package/README.md

@@ -73,6 +73,17 @@ Tools that fix your local SSH setup so everything else — git, deploys, tunnels
 | `ssh_download` | Download a file from a remote host to local filesystem. |
 | `ssh_ls` | List files in a directory on a remote host. |
 
+### Higher-level operations
+
+Tools that wrap common patterns agents build with ssh_exec — faster and less error-prone.
+
+| Tool | Description |
+|------|-------------|
+| `ssh_multi_exec` | Run a command on multiple hosts in parallel. Returns results per host. |
+| `ssh_find` | Search for files remotely with structured parameters (name, type, size, depth). |
+| `ssh_tail` | Read the last N lines of a file, optionally filtered by a grep pattern. |
+| `ssh_service_status` | Check systemd service status (active, PID, uptime, description). |
+
 ### Auto-diagnostics
 
 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.
@@ -83,7 +94,13 @@ Remote operations reuse SSH connections automatically. When your agent makes mul
 
 ### 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.
+All connections respect your `~/.ssh/config`. Host aliases, custom ports, usernames, identity files, and ProxyJump settings are used automatically. If you have `Host myserver` configured in your SSH config, just pass `host: "myserver"` — ssh-mcp resolves everything.
+
+**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.
+
+### 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.
 
 ## Authentication
 

package/dist/index.js

@@ -15,21 +15,43 @@ import { existsSync, readFileSync, readdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 function isValidHostname(host) {
-  return /^[a-zA-Z0-9._\-:[\]]+$/.test(host) && host.length <= 253;
+  if (host.length === 0 || host.length > 253) return false;
+  if (host.startsWith("[")) {
+    return /^\[[0-9a-fA-F:]+\]$/.test(host);
+  }
+  return /^[a-zA-Z0-9._\-]+$/.test(host);
 }
 function runArgs(cmd, args) {
   try {
     const stdout = execFileSync(cmd, args, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
-    const stdout = e.stdout?.toString().trim() || "";
-    const stderr = e.stderr?.toString().trim() || "";
-    const output = [stdout, stderr].filter(Boolean).join("\n") || e.message || "";
+    const err = e;
+    const stdout = err.stdout?.toString().trim() || "";
+    const stderr = err.stderr?.toString().trim() || "";
+    const output = [stdout, stderr].filter(Boolean).join("\n") || err.message || "";
     return { stdout: output, ok: false };
   }
 }
 function checkSshAgent() {
   const sock = process.env.SSH_AUTH_SOCK;
+  if (!sock && process.platform === "win32") {
+    const { stdout: stdout2, ok: ok2 } = runArgs("ssh-add", ["-l"]);
+    if (ok2) {
+      return { status: "ok", message: `Windows OpenSSH agent running with keys:
+${stdout2}` };
+    }
+    if (stdout2.includes("no identities") || stdout2.includes("The agent has no identities")) {
+      return {
+        status: "warning",
+        message: "Windows OpenSSH agent is running but has no keys loaded. Run: ssh-add <key-path>"
+      };
+    }
+    return {
+      status: "error",
+      message: "Windows OpenSSH Authentication Agent is not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent"
+    };
+  }
   if (!sock) {
     return {
       status: "error",
@@ -92,6 +114,9 @@ function checkSshKeys() {
   return { status: "ok", message: `Found SSH keys: ${found.join(", ")}` };
 }
 function checkKnownHosts(host) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
   const knownHostsPath = join(homedir(), ".ssh", "known_hosts");
   if (!existsSync(knownHostsPath)) {
     return {
@@ -99,9 +124,6 @@ function checkKnownHosts(host) {
       message: "~/.ssh/known_hosts does not exist. First connection to any host will prompt for verification."
     };
   }
-  if (!isValidHostname(host)) {
-    return { status: "error", message: `Invalid hostname: "${host}"` };
-  }
   const { stdout, ok } = runArgs("ssh-keygen", ["-F", host]);
   if (!ok || !stdout.trim()) {
     return {
@@ -261,7 +283,8 @@ function resolveFromSshConfig(host) {
       hostname: config.hostname || host,
       user: config.user || "",
       port: config.port || "22",
-      identityFiles
+      identityFiles,
+      proxyJump: config.proxyjump && config.proxyjump !== "none" ? config.proxyjump : void 0
     };
   } catch {
     return null;
@@ -276,7 +299,7 @@ function resolveConfig(config) {
     keepaliveInterval: 15e3,
     keepaliveCountMax: 3
   };
-  const agentSock = config.agent || process.env.SSH_AUTH_SOCK;
+  const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
   if (agentSock) {
     connectConfig.agent = agentSock;
   }
@@ -296,7 +319,7 @@ function resolveConfig(config) {
       }
     }
   }
-  return connectConfig;
+  return { connectConfig, proxyJump: sshConfig?.proxyJump };
 }
 function formatDiagnostics(host) {
   try {
@@ -334,6 +357,33 @@ function connectRaw(connectConfig) {
     client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
   });
 }
+async function connectWithProxy(resolved) {
+  if (!resolved.proxyJump) {
+    return connectRaw(resolved.connectConfig);
+  }
+  const jumpResolved = resolveConfig({ host: resolved.proxyJump });
+  const jumpClient = await connectWithProxy(jumpResolved);
+  const targetHost = resolved.connectConfig.host;
+  const targetPort = resolved.connectConfig.port;
+  const stream = await new Promise((resolve, reject) => {
+    jumpClient.forwardOut("127.0.0.1", 0, targetHost, targetPort, (err, stream2) => {
+      if (err) {
+        jumpClient.end();
+        return reject(err);
+      }
+      resolve(stream2);
+    });
+  });
+  return new Promise((resolve, reject) => {
+    const client = new Client();
+    client.on("ready", () => resolve(client)).on("error", (err) => {
+      jumpClient.end();
+      reject(err);
+    }).on("close", () => {
+      jumpClient.end();
+    }).connect({ ...resolved.connectConfig, sock: stream });
+  });
+}
 function exec(client, command, timeoutMs = 3e4) {
   return new Promise((resolve, reject) => {
     let settled = false;
@@ -376,9 +426,21 @@ function getSftp(client) {
     });
   });
 }
-async function readFile(client, remotePath) {
+var DEFAULT_MAX_READ_BYTES = 10 * 1024 * 1024;
+async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
   const sftp = await getSftp(client);
   try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, stats2) => {
+        if (err) return reject(err);
+        resolve(stats2);
+      });
+    });
+    if (stats.size > maxBytes) {
+      throw new Error(
+        `File is ${(stats.size / 1024 / 1024).toFixed(1)} MB, exceeds ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit. Use ssh_exec with head/tail to read a portion.`
+      );
+    }
     return await new Promise((resolve, reject) => {
       sftp.readFile(remotePath, (err, data) => {
         if (err) return reject(err);
@@ -446,12 +508,15 @@ async function listDir(client, remotePath) {
 var ConnectionPool = class {
   entries = /* @__PURE__ */ new Map();
   idleTtlMs;
+  maxPoolSize;
   constructor(options) {
     this.idleTtlMs = options?.idleTtlMs ?? 6e4;
+    this.maxPoolSize = options?.maxPoolSize ?? 100;
   }
   async acquire(config) {
-    const connectConfig = resolveConfig(config);
-    const key = `${connectConfig.username}@${connectConfig.host}:${connectConfig.port}`;
+    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++;
@@ -464,8 +529,26 @@ var ConnectionPool = class {
     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;
+        }
+      }
+      if (!evicted) {
+        throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+      }
+    }
     try {
-      const client = await connectRaw(connectConfig);
+      const client = await connectWithProxy(resolved);
       const entry = { client, key, refCount: 1, idleTimer: null, dead: false };
       const markDead = () => {
         entry.dead = true;
@@ -579,6 +662,21 @@ function ensureAgent() {
       };
     }
   }
+  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 { stdout, ok } = runArgs("ssh-agent", ["-s"]);
   if (ok) {
     const sockMatch = stdout.match(/SSH_AUTH_SOCK=([^;]+)/);
@@ -602,7 +700,7 @@ function ensureAgent() {
     reachable: false,
     keys: [],
     started: false,
-    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+    message: process.platform === "win32" ? "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent" : 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
   };
 }
 function detectKeyType(filePath, fileName) {
@@ -835,13 +933,91 @@ function testConnection(host, port = 22) {
   return { status: "error", message: `Connection failed to ${host}:${port}: ${stdout}` };
 }
 
+// src/ops.ts
+function shellQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
+  const results = await Promise.allSettled(
+    hosts.map(async (hostConfig) => {
+      return pool.withConnection(hostConfig, async (client) => {
+        const result = await exec(client, command, timeoutMs);
+        return { host: hostConfig.host, ...result };
+      });
+    })
+  );
+  return results.map((result, i) => {
+    if (result.status === "fulfilled") {
+      return result.value;
+    }
+    return {
+      host: hosts[i].host,
+      stdout: "",
+      stderr: "",
+      code: -1,
+      error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+    };
+  });
+}
+var VALID_FIND_SIZE = /^\d+[kMGTP]?$/;
+async function find(client, options, timeoutMs = 3e4) {
+  if (options.minsize && !VALID_FIND_SIZE.test(options.minsize)) {
+    throw new Error(
+      `Invalid minsize format: "${options.minsize}". Expected: digits followed by optional k/M/G/T/P (e.g. "1M", "100k")`
+    );
+  }
+  if (options.maxsize && !VALID_FIND_SIZE.test(options.maxsize)) {
+    throw new Error(
+      `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional k/M/G/T/P (e.g. "10M", "500k")`
+    );
+  }
+  const args = [shellQuote(options.path)];
+  if (options.maxdepth !== void 0) args.push("-maxdepth", String(options.maxdepth));
+  if (options.type) args.push("-type", options.type);
+  if (options.name) args.push("-name", shellQuote(options.name));
+  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 result = await exec(client, command, timeoutMs);
+  return result.stdout.split("\n").filter(Boolean);
+}
+async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
+  let command = `tail -n ${lines} ${shellQuote(path)}`;
+  if (grep) {
+    command += ` | grep -i ${shellQuote(grep)}`;
+  }
+  const result = await exec(client, command, timeoutMs);
+  if (result.code !== 0 && result.stderr && !grep) {
+    throw new Error(result.stderr.trim());
+  }
+  return result.stdout;
+}
+async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
+  const result = await exec(client, `systemctl status ${shellQuote(serviceName)} 2>&1`, timeoutMs);
+  const raw = result.stdout;
+  const activeMatch = raw.match(/Active:\s+(\S+)\s+\(([^)]+)\)/);
+  const descMatch = raw.match(/^\s+.*?-\s+(.+)$/m);
+  const pidMatch = raw.match(/Main PID:\s+(\d+)/);
+  const sinceMatch = raw.match(/since\s+(.+?);/);
+  return {
+    name: serviceName,
+    active: activeMatch?.[1] === "active",
+    status: activeMatch ? `${activeMatch[1]} (${activeMatch[2]})` : result.code === 0 ? "active" : "unknown",
+    description: descMatch?.[1]?.trim(),
+    since: sinceMatch?.[1]?.trim(),
+    pid: pidMatch ? Number.parseInt(pidMatch[1], 10) : void 0,
+    raw
+  };
+}
+
 // src/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
-var PortSchema = z.number().optional().describe("SSH port (default: 22)");
+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 TimeoutSchema = z.number().optional().describe("Command timeout in milliseconds (default: 30000)");
+var TimeoutSchema = z.number().int().positive().optional().describe("Command timeout in milliseconds (default: 30000)");
 var connectionParams = {
   host: HostSchema,
   port: PortSchema,
@@ -969,7 +1145,7 @@ ${result.stderr}`);
           lines.push(`  - ${s}`);
         }
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: report.overall === "error" };
     }
   );
   server.tool(
@@ -1100,13 +1276,131 @@ ${result.stderr}`);
       return { content: [{ type: "text", text: lines.join("\n") }], isError: result.status === "error" };
     }
   );
+  server.tool(
+    "ssh_multi_exec",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side.",
+    {
+      hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
+      command: z.string().describe("Shell command to execute on all hosts"),
+      port: PortSchema,
+      username: UsernameSchema,
+      privateKeyPath: KeyPathSchema,
+      password: PasswordSchema,
+      timeout: TimeoutSchema
+    },
+    async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
+      const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
+      const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
+      const lines = [];
+      for (const r of results) {
+        lines.push(`--- ${r.host} ---`);
+        if (r.error) {
+          lines.push(`[ERROR] ${r.error}`);
+        } else {
+          if (r.stdout) lines.push(r.stdout);
+          if (r.stderr) lines.push(`[stderr] ${r.stderr}`);
+          lines.push(`[exit code: ${r.code}]`);
+        }
+        lines.push("");
+      }
+      const hasErrors = results.some((r) => r.error || r.code !== 0);
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: hasErrors };
+    }
+  );
+  server.tool(
+    "ssh_find",
+    "Search for files on a remote host. Wraps the find command with structured parameters so you don't have to construct find syntax manually.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Directory to search in (e.g. /var/log, /home/user)"),
+      name: z.string().optional().describe("Filename pattern with wildcards (e.g. '*.log', 'config.*')"),
+      type: z.enum(["f", "d", "l"]).optional().describe("File type: f=file, d=directory, l=symlink"),
+      maxdepth: z.number().optional().describe("Maximum directory depth to search"),
+      minsize: z.string().optional().describe("Minimum file size (e.g. '1M', '100k')"),
+      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) => {
+        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." }] };
+        }
+        return { content: [{ type: "text", text: `Found ${files.length} result(s):
+${files.join("\n")}` }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_tail",
+    "Read the last N lines of a file on a remote host, optionally filtering by a grep pattern. Use this for reading log files instead of ssh_exec with manual tail/grep commands.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the file to tail"),
+      lines: z.number().optional().describe("Number of lines to read from the end (default: 100)"),
+      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) => {
+        const output = await tail(client, path, lines || 100, grep, timeout || 3e4);
+        if (!output.trim()) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: grep ? `No lines matching "${grep}" in last ${lines || 100} lines.` : "File is empty or does not exist."
+              }
+            ]
+          };
+        }
+        return { content: [{ type: "text", text: output }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_service_status",
+    "Check the status of a systemd service on a remote host. Returns whether it's active, its PID, uptime, and description. Use this instead of ssh_exec with systemctl.",
+    {
+      ...connectionParams,
+      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) => {
+        const status = await serviceStatus(client, service, timeout || 3e4);
+        const lines = [];
+        lines.push(`Service: ${status.name}`);
+        lines.push(`Status: ${status.status}`);
+        if (status.description) lines.push(`Description: ${status.description}`);
+        if (status.pid) lines.push(`PID: ${status.pid}`);
+        if (status.since) lines.push(`Since: ${status.since}`);
+        lines.push("");
+        lines.push(status.raw);
+        return { content: [{ type: "text", text: lines.join("\n") }], isError: !status.active };
+      });
+    }
+  );
 }
 
 // src/server.ts
 function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.4.0"
+    version: "0.6.0"
   });
   registerTools(server, pool);
   return server;

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { Client, ConnectConfig } from 'ssh2';
+import { ConnectConfig, Client } from 'ssh2';
 
 interface SSHConfig {
     host: string;
@@ -14,11 +14,17 @@ interface ExecResult {
     stderr: string;
     code: number;
 }
-declare function resolveConfig(config: SSHConfig): ConnectConfig;
+interface ResolvedConfig {
+    connectConfig: ConnectConfig;
+    proxyJump?: string;
+}
+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 readFile(client: Client, remotePath: string): Promise<string>;
+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>;
 declare function downloadFile(client: Client, remotePath: string, localPath: string): Promise<void>;
@@ -27,10 +33,13 @@ declare function listDir(client: Client, remotePath: string): Promise<string[]>;
 interface PoolOptions {
     /** Milliseconds before an idle connection is closed. Default: 60000 (60s) */
     idleTtlMs?: number;
+    /** Maximum number of connections in the pool. Default: 100 */
+    maxPoolSize?: number;
 }
 declare class ConnectionPool {
     private entries;
     private idleTtlMs;
+    private maxPoolSize;
     constructor(options?: PoolOptions);
     acquire(config: SSHConfig): Promise<Client>;
     release(client: Client): void;
@@ -63,6 +72,43 @@ declare function checkConnectivity(host: string, port?: number): DiagnosticResul
 declare function checkSshConfig(host: string): DiagnosticResult;
 declare function diagnose(host: string, port?: number): DiagnosticReport;
 
+interface MultiExecResult {
+    host: string;
+    stdout: string;
+    stderr: string;
+    code: number;
+    error?: string;
+}
+interface MultiExecHost {
+    host: string;
+    port?: number;
+    username?: string;
+    privateKeyPath?: string;
+    password?: string;
+}
+declare function multiExec(pool: ConnectionPool, hosts: MultiExecHost[], command: string, timeoutMs?: number): Promise<MultiExecResult[]>;
+interface FindOptions {
+    path: string;
+    name?: string;
+    type?: "f" | "d" | "l";
+    maxdepth?: number;
+    minsize?: string;
+    maxsize?: string;
+    newer?: string;
+}
+declare function find(client: Client, options: FindOptions, timeoutMs?: number): Promise<string[]>;
+declare function tail(client: Client, path: string, lines?: number, grep?: string, timeoutMs?: number): Promise<string>;
+interface ServiceStatus {
+    name: string;
+    active: boolean;
+    status: string;
+    description?: string;
+    since?: string;
+    pid?: number;
+    raw: string;
+}
+declare function serviceStatus(client: Client, serviceName: string, timeoutMs?: number): Promise<ServiceStatus>;
+
 interface KeyInfo {
     name: string;
     path: string;
@@ -118,4 +164,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 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 };
+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 };

package/dist/server.js

@@ -10,21 +10,43 @@ import { existsSync, readFileSync, readdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 function isValidHostname(host) {
-  return /^[a-zA-Z0-9._\-:[\]]+$/.test(host) && host.length <= 253;
+  if (host.length === 0 || host.length > 253) return false;
+  if (host.startsWith("[")) {
+    return /^\[[0-9a-fA-F:]+\]$/.test(host);
+  }
+  return /^[a-zA-Z0-9._\-]+$/.test(host);
 }
 function runArgs(cmd, args) {
   try {
     const stdout = execFileSync(cmd, args, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
-    const stdout = e.stdout?.toString().trim() || "";
-    const stderr = e.stderr?.toString().trim() || "";
-    const output = [stdout, stderr].filter(Boolean).join("\n") || e.message || "";
+    const err = e;
+    const stdout = err.stdout?.toString().trim() || "";
+    const stderr = err.stderr?.toString().trim() || "";
+    const output = [stdout, stderr].filter(Boolean).join("\n") || err.message || "";
     return { stdout: output, ok: false };
   }
 }
 function checkSshAgent() {
   const sock = process.env.SSH_AUTH_SOCK;
+  if (!sock && process.platform === "win32") {
+    const { stdout: stdout2, ok: ok2 } = runArgs("ssh-add", ["-l"]);
+    if (ok2) {
+      return { status: "ok", message: `Windows OpenSSH agent running with keys:
+${stdout2}` };
+    }
+    if (stdout2.includes("no identities") || stdout2.includes("The agent has no identities")) {
+      return {
+        status: "warning",
+        message: "Windows OpenSSH agent is running but has no keys loaded. Run: ssh-add <key-path>"
+      };
+    }
+    return {
+      status: "error",
+      message: "Windows OpenSSH Authentication Agent is not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent"
+    };
+  }
   if (!sock) {
     return {
       status: "error",
@@ -87,6 +109,9 @@ function checkSshKeys() {
   return { status: "ok", message: `Found SSH keys: ${found.join(", ")}` };
 }
 function checkKnownHosts(host) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
   const knownHostsPath = join(homedir(), ".ssh", "known_hosts");
   if (!existsSync(knownHostsPath)) {
     return {
@@ -94,9 +119,6 @@ function checkKnownHosts(host) {
       message: "~/.ssh/known_hosts does not exist. First connection to any host will prompt for verification."
     };
   }
-  if (!isValidHostname(host)) {
-    return { status: "error", message: `Invalid hostname: "${host}"` };
-  }
   const { stdout, ok } = runArgs("ssh-keygen", ["-F", host]);
   if (!ok || !stdout.trim()) {
     return {
@@ -254,6 +276,21 @@ function ensureAgent() {
       };
     }
   }
+  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 { stdout, ok } = runArgs("ssh-agent", ["-s"]);
   if (ok) {
     const sockMatch = stdout.match(/SSH_AUTH_SOCK=([^;]+)/);
@@ -277,7 +314,7 @@ function ensureAgent() {
     reachable: false,
     keys: [],
     started: false,
-    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+    message: process.platform === "win32" ? "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent" : 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
   };
 }
 function detectKeyType(filePath, fileName) {
@@ -537,7 +574,8 @@ function resolveFromSshConfig(host) {
       hostname: config.hostname || host,
       user: config.user || "",
       port: config.port || "22",
-      identityFiles
+      identityFiles,
+      proxyJump: config.proxyjump && config.proxyjump !== "none" ? config.proxyjump : void 0
     };
   } catch {
     return null;
@@ -552,7 +590,7 @@ function resolveConfig(config) {
     keepaliveInterval: 15e3,
     keepaliveCountMax: 3
   };
-  const agentSock = config.agent || process.env.SSH_AUTH_SOCK;
+  const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
   if (agentSock) {
     connectConfig.agent = agentSock;
   }
@@ -572,7 +610,7 @@ function resolveConfig(config) {
       }
     }
   }
-  return connectConfig;
+  return { connectConfig, proxyJump: sshConfig?.proxyJump };
 }
 function formatDiagnostics(host) {
   try {
@@ -610,10 +648,37 @@ function connectRaw(connectConfig) {
     client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
   });
 }
+async function connectWithProxy(resolved) {
+  if (!resolved.proxyJump) {
+    return connectRaw(resolved.connectConfig);
+  }
+  const jumpResolved = resolveConfig({ host: resolved.proxyJump });
+  const jumpClient = await connectWithProxy(jumpResolved);
+  const targetHost = resolved.connectConfig.host;
+  const targetPort = resolved.connectConfig.port;
+  const stream = await new Promise((resolve, reject) => {
+    jumpClient.forwardOut("127.0.0.1", 0, targetHost, targetPort, (err, stream2) => {
+      if (err) {
+        jumpClient.end();
+        return reject(err);
+      }
+      resolve(stream2);
+    });
+  });
+  return new Promise((resolve, reject) => {
+    const client = new Client();
+    client.on("ready", () => resolve(client)).on("error", (err) => {
+      jumpClient.end();
+      reject(err);
+    }).on("close", () => {
+      jumpClient.end();
+    }).connect({ ...resolved.connectConfig, sock: stream });
+  });
+}
 async function connect(config) {
-  const connectConfig = resolveConfig(config);
+  const resolved = resolveConfig(config);
   try {
-    return await connectRaw(connectConfig);
+    return await connectWithProxy(resolved);
   } catch (err) {
     const diag = formatDiagnostics(config.host);
     if (diag) {
@@ -670,9 +735,21 @@ function getSftp(client) {
     });
   });
 }
-async function readFile(client, remotePath) {
+var DEFAULT_MAX_READ_BYTES = 10 * 1024 * 1024;
+async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
   const sftp = await getSftp(client);
   try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, stats2) => {
+        if (err) return reject(err);
+        resolve(stats2);
+      });
+    });
+    if (stats.size > maxBytes) {
+      throw new Error(
+        `File is ${(stats.size / 1024 / 1024).toFixed(1)} MB, exceeds ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit. Use ssh_exec with head/tail to read a portion.`
+      );
+    }
     return await new Promise((resolve, reject) => {
       sftp.readFile(remotePath, (err, data) => {
         if (err) return reject(err);
@@ -736,16 +813,97 @@ async function listDir(client, remotePath) {
   }
 }
 
+// src/ops.ts
+function shellQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
+  const results = await Promise.allSettled(
+    hosts.map(async (hostConfig) => {
+      return pool.withConnection(hostConfig, async (client) => {
+        const result = await exec(client, command, timeoutMs);
+        return { host: hostConfig.host, ...result };
+      });
+    })
+  );
+  return results.map((result, i) => {
+    if (result.status === "fulfilled") {
+      return result.value;
+    }
+    return {
+      host: hosts[i].host,
+      stdout: "",
+      stderr: "",
+      code: -1,
+      error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+    };
+  });
+}
+var VALID_FIND_SIZE = /^\d+[kMGTP]?$/;
+async function find(client, options, timeoutMs = 3e4) {
+  if (options.minsize && !VALID_FIND_SIZE.test(options.minsize)) {
+    throw new Error(
+      `Invalid minsize format: "${options.minsize}". Expected: digits followed by optional k/M/G/T/P (e.g. "1M", "100k")`
+    );
+  }
+  if (options.maxsize && !VALID_FIND_SIZE.test(options.maxsize)) {
+    throw new Error(
+      `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional k/M/G/T/P (e.g. "10M", "500k")`
+    );
+  }
+  const args = [shellQuote(options.path)];
+  if (options.maxdepth !== void 0) args.push("-maxdepth", String(options.maxdepth));
+  if (options.type) args.push("-type", options.type);
+  if (options.name) args.push("-name", shellQuote(options.name));
+  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 result = await exec(client, command, timeoutMs);
+  return result.stdout.split("\n").filter(Boolean);
+}
+async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
+  let command = `tail -n ${lines} ${shellQuote(path)}`;
+  if (grep) {
+    command += ` | grep -i ${shellQuote(grep)}`;
+  }
+  const result = await exec(client, command, timeoutMs);
+  if (result.code !== 0 && result.stderr && !grep) {
+    throw new Error(result.stderr.trim());
+  }
+  return result.stdout;
+}
+async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
+  const result = await exec(client, `systemctl status ${shellQuote(serviceName)} 2>&1`, timeoutMs);
+  const raw = result.stdout;
+  const activeMatch = raw.match(/Active:\s+(\S+)\s+\(([^)]+)\)/);
+  const descMatch = raw.match(/^\s+.*?-\s+(.+)$/m);
+  const pidMatch = raw.match(/Main PID:\s+(\d+)/);
+  const sinceMatch = raw.match(/since\s+(.+?);/);
+  return {
+    name: serviceName,
+    active: activeMatch?.[1] === "active",
+    status: activeMatch ? `${activeMatch[1]} (${activeMatch[2]})` : result.code === 0 ? "active" : "unknown",
+    description: descMatch?.[1]?.trim(),
+    since: sinceMatch?.[1]?.trim(),
+    pid: pidMatch ? Number.parseInt(pidMatch[1], 10) : void 0,
+    raw
+  };
+}
+
 // src/pool.ts
 var ConnectionPool = class {
   entries = /* @__PURE__ */ new Map();
   idleTtlMs;
+  maxPoolSize;
   constructor(options) {
     this.idleTtlMs = options?.idleTtlMs ?? 6e4;
+    this.maxPoolSize = options?.maxPoolSize ?? 100;
   }
   async acquire(config) {
-    const connectConfig = resolveConfig(config);
-    const key = `${connectConfig.username}@${connectConfig.host}:${connectConfig.port}`;
+    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++;
@@ -758,8 +916,26 @@ var ConnectionPool = class {
     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;
+        }
+      }
+      if (!evicted) {
+        throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+      }
+    }
     try {
-      const client = await connectRaw(connectConfig);
+      const client = await connectWithProxy(resolved);
       const entry = { client, key, refCount: 1, idleTimer: null, dead: false };
       const markDead = () => {
         entry.dead = true;
@@ -848,11 +1024,11 @@ ${diag}`);
 
 // src/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
-var PortSchema = z.number().optional().describe("SSH port (default: 22)");
+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 TimeoutSchema = z.number().optional().describe("Command timeout in milliseconds (default: 30000)");
+var TimeoutSchema = z.number().int().positive().optional().describe("Command timeout in milliseconds (default: 30000)");
 var connectionParams = {
   host: HostSchema,
   port: PortSchema,
@@ -980,7 +1156,7 @@ ${result.stderr}`);
           lines.push(`  - ${s}`);
         }
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: report.overall === "error" };
     }
   );
   server.tool(
@@ -1111,13 +1287,131 @@ ${result.stderr}`);
       return { content: [{ type: "text", text: lines.join("\n") }], isError: result.status === "error" };
     }
   );
+  server.tool(
+    "ssh_multi_exec",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side.",
+    {
+      hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
+      command: z.string().describe("Shell command to execute on all hosts"),
+      port: PortSchema,
+      username: UsernameSchema,
+      privateKeyPath: KeyPathSchema,
+      password: PasswordSchema,
+      timeout: TimeoutSchema
+    },
+    async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
+      const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
+      const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
+      const lines = [];
+      for (const r of results) {
+        lines.push(`--- ${r.host} ---`);
+        if (r.error) {
+          lines.push(`[ERROR] ${r.error}`);
+        } else {
+          if (r.stdout) lines.push(r.stdout);
+          if (r.stderr) lines.push(`[stderr] ${r.stderr}`);
+          lines.push(`[exit code: ${r.code}]`);
+        }
+        lines.push("");
+      }
+      const hasErrors = results.some((r) => r.error || r.code !== 0);
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: hasErrors };
+    }
+  );
+  server.tool(
+    "ssh_find",
+    "Search for files on a remote host. Wraps the find command with structured parameters so you don't have to construct find syntax manually.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Directory to search in (e.g. /var/log, /home/user)"),
+      name: z.string().optional().describe("Filename pattern with wildcards (e.g. '*.log', 'config.*')"),
+      type: z.enum(["f", "d", "l"]).optional().describe("File type: f=file, d=directory, l=symlink"),
+      maxdepth: z.number().optional().describe("Maximum directory depth to search"),
+      minsize: z.string().optional().describe("Minimum file size (e.g. '1M', '100k')"),
+      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) => {
+        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." }] };
+        }
+        return { content: [{ type: "text", text: `Found ${files.length} result(s):
+${files.join("\n")}` }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_tail",
+    "Read the last N lines of a file on a remote host, optionally filtering by a grep pattern. Use this for reading log files instead of ssh_exec with manual tail/grep commands.",
+    {
+      ...connectionParams,
+      path: z.string().describe("Absolute path to the file to tail"),
+      lines: z.number().optional().describe("Number of lines to read from the end (default: 100)"),
+      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) => {
+        const output = await tail(client, path, lines || 100, grep, timeout || 3e4);
+        if (!output.trim()) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: grep ? `No lines matching "${grep}" in last ${lines || 100} lines.` : "File is empty or does not exist."
+              }
+            ]
+          };
+        }
+        return { content: [{ type: "text", text: output }] };
+      });
+    }
+  );
+  server.tool(
+    "ssh_service_status",
+    "Check the status of a systemd service on a remote host. Returns whether it's active, its PID, uptime, and description. Use this instead of ssh_exec with systemctl.",
+    {
+      ...connectionParams,
+      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) => {
+        const status = await serviceStatus(client, service, timeout || 3e4);
+        const lines = [];
+        lines.push(`Service: ${status.name}`);
+        lines.push(`Status: ${status.status}`);
+        if (status.description) lines.push(`Description: ${status.description}`);
+        if (status.pid) lines.push(`PID: ${status.pid}`);
+        if (status.since) lines.push(`Since: ${status.since}`);
+        lines.push("");
+        lines.push(status.raw);
+        return { content: [{ type: "text", text: lines.join("\n") }], isError: !status.active };
+      });
+    }
+  );
 }
 
 // src/server.ts
 function createServer(pool) {
   const server = new McpServer({
     name: "ssh-mcp",
-    version: "0.4.0"
+    version: "0.6.0"
   });
   registerTools(server, pool);
   return server;
@@ -1133,18 +1427,24 @@ export {
   configLookup,
   connect,
   connectRaw,
+  connectWithProxy,
   createServer,
   diagnose,
   downloadFile,
   ensureAgent,
   exec,
+  find,
   fixKnownHosts,
+  formatDiagnostics,
   listDir,
   listSshKeys,
   loadKey,
+  multiExec,
   readFile,
   registerTools,
   resolveConfig,
+  serviceStatus,
+  tail,
   testConnection,
   uploadFile,
   writeFile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP server for SSH operations with built-in diagnostics",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "lint:fix": "biome check --write src/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:integration": "docker compose -f test/docker/docker-compose.yml up -d --build --wait && SSH_MCP_INTEGRATION=1 vitest run src/tests/integration.test.ts; docker compose -f test/docker/docker-compose.yml down",
     "test:ci": "npm run build && npm test",
     "prepublishOnly": "npm run build"
   },