@yawlabs/ssh-mcp 0.3.0 → 0.5.0

package/README.md

@@ -73,10 +73,35 @@ 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.
 
+### 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, 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
 
 All remote operations accept connection parameters:
@@ -84,12 +109,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 +148,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 +164,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"