@yawlabs/ssh-mcp 0.17.3 → 0.18.0

package/README.md

@@ -87,8 +87,8 @@ Tools that fix your local SSH setup so everything else — git, deploys, tunnels
 
 | Tool | Description |
 |------|-------------|
-| `ssh_exec` | Execute a command on a remote host. Returns stdout, stderr, and exit code (or `[signal: NAME]` and `code: -1` when the channel closed signal-only). Optional `env` param sets per-call environment variables (POSIX-safe prefix, works regardless of sshd's `AcceptEnv`). Subject to [command policy](#command-policy) if configured. |
-| `ssh_read_file` | Read a file from a remote host via SFTP. |
+| `ssh_exec` | Execute a command on a remote host. Returns up to three content blocks, status first: `[exit code: N]` (plus `[signal: NAME]` with `code: -1` when the channel closed signal-only, and a flag when a stream hit the 10 MB cap), then `[stderr]`, then `[stdout]`. Status leads so a proxy that cuts long results — Yaw MCP keeps about 100 KB by default — never drops the exit code. Optional `env` param sets per-call environment variables (POSIX-safe prefix, works regardless of sshd's `AcceptEnv`). Subject to [command policy](#command-policy) if configured. |
+| `ssh_read_file` | Read a file from a remote host via SFTP (whole file up to 10 MB). Optional `offset` and `length` (bytes) read one page and return a `[bytes A-B of SIZE; next offset: N]` status block before the text — use them for a large file, or behind a proxy that caps results. |
 | `ssh_write_file` | Write content to a file on a remote host via SFTP. |
 | `ssh_upload` | Upload a local file to a remote host via SFTP. |
 | `ssh_download` | Download a file from a remote host to local filesystem. |
@@ -137,11 +137,11 @@ All remote operations verify the server's host key against `~/.ssh/known_hosts`:
 
 - **Known host, key matches** — accept.
 - **Known host, key changed** — reject (MITM protection). The rejection message distinguishes a genuine key mismatch from "the server offered a key type your `known_hosts` entry doesn't cover", so a missing ed25519 line doesn't read as an attack.
-- **Unknown host** — accept, unless `SSH_MCP_STRICT_HOST_KEY=1`.
+- **Unknown host** — accept, unless strict mode is on (`SSH_MCP_STRICT_HOSTKEYS=1`).
 
 **That last branch is trust-always, not TOFU.** Real trust-on-first-use pins the key it saw the first time and rejects a change afterwards. The connection path never writes to `known_hosts` — no tool adds an entry as a side effect of connecting — so connecting pins nothing: *every* connection to a host absent from `known_hosts` is a "first" use and is accepted, including one where an attacker swapped the key since your last call. Only hosts put into `known_hosts` out of band get mismatch protection — by you, by `ssh-keyscan`, or by `ssh_known_hosts_fix`, the one tool here that does write the file. Call it explicitly to add an entry so future changes are caught.
 
-For stricter environments, set `SSH_MCP_STRICT_HOST_KEY=1` to reject unknown hosts. Add them explicitly with `ssh_known_hosts_fix` first.
+For stricter environments, set `SSH_MCP_STRICT_HOSTKEYS=1` (or `true`, case-insensitive) to reject unknown hosts. Add them explicitly with `ssh_known_hosts_fix` first. The older name `SSH_MCP_STRICT_HOST_KEY` still works and accepts the same values, but prefer the new one: credential scanners such as Yaw MCP's doctor treat any name with a `_KEY` segment as a secret, and flag the old name as a plaintext credential.
 
 The diagnostic tools (`ssh_test`, `ssh_diagnose`) use `StrictHostKeyChecking=no` for their probe commands. Those probes only run `echo SSH_OK` — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the `hostVerifier`.
 
@@ -207,6 +207,8 @@ If you don't trust the agent's `env` values at all, the simplest mitigation is t
 
 On Windows, ssh-mcp uses the OpenSSH Authentication Agent's `\\.\pipe\openssh-ssh-agent` named pipe automatically when `SSH_AUTH_SOCK` is not set. No `SSH_AUTH_SOCK` needed — just make sure the OpenSSH agent service is running.
 
+On the [oam](https://oamjs.org) runtime, agent auth needs oam 0.18.0 or newer: that is the first oam whose `net` can dial a named pipe or a Unix socket, which is how ssh2 reaches the agent (and the launcher never serves on an older one). Agent-backed remote operations have so far been verified end to end on Node only; on oam, the handshake and `ssh_config_lookup` were verified, not an agent-only `ssh_exec`. If agent auth fails on oam, set `SSH_MCP_RUNTIME=node` to rule the runtime out.
+
 `ssh_agent_ensure` and `ssh_diagnose` probe that pipe and tell you if the service is down. Remote operations do *not*: they assume the pipe and let the connection fail on its own if the agent isn't there. That is why a stopped agent service shows up as an auth failure rather than an "agent not running" error until you run the diagnostic tools.
 
 ## Authentication
@@ -336,7 +338,7 @@ Two environment variables control the choice; set them in your MCP client's `env
   - `node` — always Node. The launcher does not look for oam, and `OAM_BIN` is ignored.
 - `OAM_BIN` — path to an oam binary to use in preference to discovery, when it is 0.18.0 or newer. If it does not exist, is older, or will not run, the launcher says so on stderr and carries on with discovery.
 
-Discovery looks in `%LOCALAPPDATA%\oam\bin` (Windows only), then `~/.oam/bin`, then every directory on `PATH`; asks every oam binary it finds for its version; and uses the newest one at 0.18.0 or newer. On a tie the one found first wins, so an installed copy beats one on `PATH`. On Windows only `oam.exe` counts: an `oam.cmd`/`oam.bat` shim on `PATH` is never run, and is named on stderr when no usable oam is found.
+Discovery looks in `$OAM_INSTALL_DIR` (when set — the oam installer's install target), then `%LOCALAPPDATA%\oam\bin` (Windows only), then `~/.oam/bin`, then every directory on `PATH`; asks every oam binary it finds for its version; and uses the newest one at 0.18.0 or newer. On a tie the one found first wins, so an installed copy beats one on `PATH`. On Windows only `oam.exe` counts: an `oam.cmd`/`oam.bat` shim on `PATH` is never run, and is named on stderr when no usable oam is found.
 
 By default an unusable oam is not an error. When Node starts the launcher (`npx` or a global install, run directly by your MCP client), `auto` mode falls back to Node — silently when there was nothing to find, or with a note on stderr naming each oam (and `OAM_BIN`) it passed over and why: older than 0.18.0, not runnable, or a shim. A chosen oam that then fails to start is named on stderr too. When an older oam starts the launcher, the handoff to Node is always noted on stderr (see below). With `SSH_MCP_RUNTIME=oam`, each of these cases exits with status 1 instead.
 
@@ -346,6 +348,8 @@ When the launcher is itself started by oam (`oam run <path>/bin/ssh-mcp.mjs`, wh
 - On an older oam it never runs the server there. It hands the server off to the newest usable oam it can find, or to Node on `PATH`, or exits with status 1 when there is neither (`SSH_MCP_RUNTIME=oam` exits with status 1 rather than handing off to Node).
 - With `SSH_MCP_RUNTIME=node` it hands the server off to Node on `PATH`, whatever the oam version.
 
+Whenever an oam host starts a child (the handoffs above), the launcher removes `--permission` and `--allow-*` flags from the child's inherited `NODE_OPTIONS`. oam 0.18.0 adds its own permission flags to every child's `NODE_OPTIONS`, and Node refuses some of them there (`--allow-net is not allowed in NODE_OPTIONS`, exit 9); this server is not sandboxed, so there is nothing to pass on. An oam that was itself started with `--permission` re-adds the flags inside `spawn()`, which the launcher cannot undo, so do not start it that way.
+
 For example, to always run on Node:
 
 ```json

package/bin/ssh-mcp.mjs

@@ -79,13 +79,29 @@
  * MINIMUM OAM VERSION
  * The latest oam release, 0.18.0 -- bump OAM_MIN when oam ships a newer one.
  * Only the current oam is used and verified; an older one is passed over.
- * The floor is not cosmetic: before 0.9.0 `child_process.execFile` ran its
- * arguments through a SHELL, `exec` accepted `timeout` and ignored it,
- * `spawnSync` truncated at `maxBuffer` while reporting success, and
- * `stdio: 'inherit'`/`'ignore'` both behaved as `'pipe'`. This server shells
- * out to a CLI on its main paths, so those were reachable bugs rather than
- * theoretical ones: an argument containing shell metacharacters was re-split
- * and executed.
+ *
+ * The floor is not cosmetic. Two things this server does need 0.18.0 itself,
+ * so anyone lowering it has to answer for both:
+ *
+ *   1. An explicit child `env` that DELETES a variable. probeAgent
+ *      (src/env.ts:85-90) runs `ssh-add -l` with SSH_AUTH_SOCK removed, so
+ *      Windows ssh-add falls back to the OpenSSH named pipe instead of a stale
+ *      Unix-style socket. Up to 0.17.x oam laid an explicit `env` OVER its
+ *      startup environment, so the deleted SSH_AUTH_SOCK came back and ssh-add
+ *      probed the wrong agent. 0.18.0 makes an explicit `env` replace it, as
+ *      Node does (oam CHANGELOG 0.18.0, B4).
+ *   2. `net.connect` to a Windows named pipe or a Unix socket path.
+ *      resolveConfig (src/ssh.ts:581-584) hands ssh2 SSH_AUTH_SOCK, or on Windows
+ *      `\\.\pipe\openssh-ssh-agent`, and ssh2 dials it with
+ *      `new Socket().connect(path)` for every agent-backed connection. Up to
+ *      0.17.x oam could not dial either (oam CHANGELOG 0.18.0, F1).
+ *
+ * Background, long before the current floor: before 0.9.0
+ * `child_process.execFile` ran its arguments through a SHELL, `exec` accepted
+ * `timeout` and ignored it, `spawnSync` truncated at `maxBuffer` while
+ * reporting success, and `stdio: 'inherit'`/`'ignore'` both behaved as
+ * `'pipe'`. This server shells out to ssh, ssh-add and ssh-keygen on its main
+ * paths, so those were reachable bugs rather than theoretical ones.
  *
  * SELECTION
  *   SSH_MCP_RUNTIME=auto   newest usable oam, else Node (default)
@@ -103,7 +119,12 @@ import { constants, homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
+/**
+ * Oldest oam this server runs on: the one whose explicit child `env` replaces
+ * the environment (needed by probeAgent, src/env.ts) and whose `net` dials named
+ * pipes and Unix sockets (needed by ssh2's agent client, src/ssh.ts). See MINIMUM
+ * OAM VERSION above.
+ */
 const OAM_MIN = [0, 18, 0];
 
 /**
@@ -141,8 +162,12 @@ function pathKey(p) {
  * usually has oam/target/release on PATH, and cargo replaces that binary
  * underneath running processes; the installed copy is the release the user
  * actually installed. Both forms are checked on Windows: the installer defaults
- * to %LOCALAPPDATA%\oam\bin there, but oam's docs name ~/.oam/bin first and
- * OAM_INSTALL_DIR can pick either.
+ * to %LOCALAPPDATA%\oam\bin there, but oam's docs name ~/.oam/bin first.
+ *
+ * OAM_INSTALL_DIR, when set, is searched before both. It is the installer's
+ * install target (oam docs/cli-reference.md), so an oam put somewhere custom and
+ * left off PATH is still found -- this comment used to say it "can pick either"
+ * default while the code never read it.
  *
  * Windows: `.exe` ONLY -- deliberately narrower than PATHEXT. Node refuses to
  * run a .cmd/.bat through execFile/spawn without `shell: true` (EINVAL, and for
@@ -156,6 +181,7 @@ function discoverOamPaths() {
   if (isWin) {
     installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
   }
+  if (process.env.OAM_INSTALL_DIR) installed.unshift(join(process.env.OAM_INSTALL_DIR, exe));
   const onPath = (process.env.PATH ?? "")
     .split(delimiter)
     .filter(Boolean)
@@ -405,6 +431,48 @@ const fallbackFailed = (e) => {
   process.exitCode = 1;
 };
 
+/**
+ * A permission flag oam may have put in NODE_OPTIONS: `--permission` (and the
+ * older `--experimental-permission`) or any `--allow-*` grant, with or without
+ * an `=value`.
+ */
+const PERMISSION_FLAG = /^--(?:experimental-)?permission$|^--allow-[a-z0-9-]+(?:=.*)?$/;
+
+/**
+ * `env` with oam's permission flags removed from NODE_OPTIONS, or `env` itself
+ * when there is nothing to remove.
+ *
+ * oam 0.18.0 appends its own `--permission` / `--allow-*` flags to every child's
+ * NODE_OPTIONS "for any program" (oam CHANGELOG 0.18.0, Permissions), so a
+ * process started under a sandboxed oam carries them in its environment. Node
+ * refuses some of them there -- measured on Node 22:
+ * `NODE_OPTIONS="--permission --allow-net" node` exits 9 with "--allow-net is
+ * not allowed in NODE_OPTIONS" -- and this launcher has no sandbox to pass on
+ * (see NO SANDBOX HERE), so the tokens are dropped before a child is started.
+ *
+ * Only the INHERITED copy can be removed here. When THIS process was itself
+ * started as `oam --permission ...`, oam re-appends those flags from its own
+ * execArgv inside spawn(), after this env is built -- measured on oam 0.18.0:
+ * the Node child still exits 9 with this env. That host is outside what this
+ * launcher supports, since the server needs unrestricted net and child-process
+ * grants anyway.
+ *
+ * Tokens are split on whitespace with double-quoted spans kept whole, which is
+ * how Node itself reads NODE_OPTIONS. Pure, so src/tests/launcher.test.ts can
+ * extract and test it without booting a runtime.
+ */
+function stripPermissionFlags(env) {
+  const raw = env.NODE_OPTIONS;
+  if (!raw) return env;
+  const tokens = raw.match(/(?:[^\s"]+|"[^"]*")+/g) ?? [];
+  const kept = tokens.filter((t) => !PERMISSION_FLAG.test(t.replaceAll('"', "")));
+  if (kept.length === tokens.length) return env;
+  const next = { ...env };
+  if (kept.length === 0) delete next.NODE_OPTIONS;
+  else next.NODE_OPTIONS = kept.join(" ");
+  return next;
+}
+
 /**
  * Spawn the server in a child runtime and mirror its lifetime.
  *
@@ -428,7 +496,9 @@ async function launchChild(cmd, args, onLaunchFailed) {
       // server's shutdown path. Piping preserves both as well: bytes are copied
       // unchanged, and stdin's end propagates to the child.
       stdio: piped ? ["pipe", "pipe", "pipe"] : "inherit",
-      env: process.env,
+      // On an oam host, drop the permission flags oam put in NODE_OPTIONS; see
+      // stripPermissionFlags. A Node host's env passes through untouched.
+      env: process.versions.oam !== undefined ? stripPermissionFlags(process.env) : process.env,
       windowsHide: true,
     });
   } catch (err) {

package/dist/index.js

@@ -441,8 +441,15 @@ function cachedKnownHostTypes(hosts, port) {
   knownHostTypeCache.set(cacheKey, { at: now, types });
   return types;
 }
+function isStrictHostKeyMode(env = process.env) {
+  const on = (v) => {
+    const t = (v ?? "").trim().toLowerCase();
+    return t === "1" || t === "true";
+  };
+  return on(env.SSH_MCP_STRICT_HOSTKEYS) || on(env.SSH_MCP_STRICT_HOST_KEY);
+}
 function buildHostVerifier(hosts, port, rejection) {
-  const strict = process.env.SSH_MCP_STRICT_HOST_KEY === "1";
+  const strict = isStrictHostKeyMode();
   const label = hosts.join(" / ");
   const remediationHost = unbracketHost(hosts[0]);
   return (key) => {
@@ -452,7 +459,7 @@ function buildHostVerifier(hosts, port, rejection) {
       if (strict) {
         rejection.current = {
           reason: "unknown-host-strict",
-          message: `no known_hosts entry for ${label}, and SSH_MCP_STRICT_HOST_KEY=1 requires one. Add it: ssh-keyscan -H "${remediationHost}" >> ~/.ssh/known_hosts`
+          message: `no known_hosts entry for ${label}, and strict mode (SSH_MCP_STRICT_HOSTKEYS=1) requires one. Add it: ssh-keyscan -H "${remediationHost}" >> ~/.ssh/known_hosts`
         };
       }
       return !strict;
@@ -844,7 +851,7 @@ async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
     });
     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.`
+        `File is ${(stats.size / 1024 / 1024).toFixed(1)} MB, exceeds ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit. Read it a page at a time with ssh_read_file's offset and length arguments (byte offsets; the file is ${stats.size} bytes).`
       );
     }
     return await new Promise((resolve, reject) => {
@@ -857,6 +864,53 @@ async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
     sftp.end();
   }
 }
+async function readFileRange(client, remotePath, offset, length, maxBytes = DEFAULT_MAX_READ_BYTES) {
+  if (!Number.isSafeInteger(offset) || offset < 0)
+    throw new Error(`offset must be a non-negative integer, got ${offset}`);
+  if (!Number.isSafeInteger(length) || length <= 0) throw new Error(`length must be a positive integer, got ${length}`);
+  if (length > maxBytes) {
+    throw new Error(
+      `length ${length} exceeds the ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit for one read. Use a smaller length and page with offset.`
+    );
+  }
+  const sftp = await getSftp(client);
+  try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, st) => {
+        if (err) return reject(err);
+        resolve(st);
+      });
+    });
+    const want = Math.max(0, Math.min(length, stats.size - offset));
+    if (want === 0) return { text: "", offset, bytesRead: 0, size: stats.size };
+    const handle = await new Promise((resolve, reject) => {
+      sftp.open(remotePath, "r", (err, h) => {
+        if (err) return reject(err);
+        resolve(h);
+      });
+    });
+    try {
+      const buf = Buffer.alloc(want);
+      let got = 0;
+      while (got < want) {
+        const n = await new Promise((resolve, reject) => {
+          sftp.read(handle, buf, got, want - got, offset + got, (err, bytesRead) => {
+            if (err) return reject(err);
+            resolve(bytesRead ?? 0);
+          });
+        });
+        if (n === 0) break;
+        got += n;
+      }
+      return { text: buf.subarray(0, got).toString("utf8"), offset, bytesRead: got, size: stats.size };
+    } finally {
+      sftp.close(handle, () => {
+      });
+    }
+  } finally {
+    sftp.end();
+  }
+}
 async function writeFile(client, remotePath, content) {
   const sftp = await getSftp(client);
   try {
@@ -1532,6 +1586,7 @@ var ConnectionPool = class {
       if (entry.client === client) {
         entry.refCount = Math.max(0, entry.refCount - 1);
         if (entry.refCount === 0 && !entry.dead) {
+          if (entry.idleTimer) clearTimeout(entry.idleTimer);
           entry.idleTimer = setTimeout(() => {
             try {
               entry.client.end();
@@ -1784,14 +1839,14 @@ async function find(client, options, timeoutMs = 3e4) {
       `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "10M", "500k")`
     );
   }
-  const pathOperand = options.path.startsWith("-") || FIND_EXPRESSION_TOKENS.has(options.path) ? `./${options.path}` : options.path;
-  const args = [shellQuote(pathOperand)];
+  const defuseFindOperand = (p) => p.startsWith("-") || FIND_EXPRESSION_TOKENS.has(p) ? `./${p}` : p;
+  const args = [shellQuote(defuseFindOperand(options.path))];
   if (options.maxdepth !== void 0) args.push("-maxdepth", shellQuote(String(options.maxdepth)));
   if (options.type) args.push("-type", shellQuote(options.type));
   if (options.name) args.push("-name", shellQuote(options.name));
   if (options.minsize) args.push("-size", shellQuote(`+${options.minsize}`));
   if (options.maxsize) args.push("-size", shellQuote(`-${options.maxsize}`));
-  if (options.newer) args.push("-newer", shellQuote(options.newer));
+  if (options.newer) args.push("-newer", shellQuote(defuseFindOperand(options.newer)));
   const command = `find ${args.join(" ")}`;
   const result = await exec(client, command, timeoutMs);
   if (!result.stdout.trim() && result.stderr.trim()) {
@@ -1814,7 +1869,7 @@ async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
   return result.stdout;
 }
 async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
-  const result = await exec(client, `systemctl status -- ${shellQuote(serviceName)} 2>&1`, timeoutMs);
+  const result = await exec(client, `LC_ALL=C systemctl status -- ${shellQuote(serviceName)} 2>&1`, timeoutMs);
   const raw = result.stdout;
   const activeMatch = raw.match(/Active:\s+(\S+)\s+\(([^)]+)\)/);
   const descMatch = raw.match(/^[^\w\n]*\S+\s+-\s+(.+)$/m);
@@ -1901,6 +1956,9 @@ var connectionParams = {
 var DEFAULT_TIMEOUT_MS = 3e4;
 var poolWait = (timeoutMs = DEFAULT_TIMEOUT_MS) => ({ waitForCapacityMs: timeoutMs });
 var SFTP_POOL_WAIT_NOTE = ` If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to ${DEFAULT_TIMEOUT_MS / 1e3}s for a free slot before starting.`;
+var READ_ONLY_LOCAL = { readOnlyHint: true, openWorldHint: false };
+var READ_ONLY_REMOTE = { readOnlyHint: true, openWorldHint: true };
+var DESTRUCTIVE_REMOTE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
 var POLICY_EXEMPT_NOTE = " NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as `^rm` does NOT block this tool.";
 var ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function applyEnvPrefix(command, env) {
@@ -1921,7 +1979,7 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns up to three content blocks in this order: the status (`[exit code: N]`, plus the signal and any truncation), then `[stderr]`, then `[stdout]`. Status comes first so a proxy that cuts long results (Yaw MCP keeps about 100 KB) never drops the exit code; for big output, filter or page on the remote (head, tail, grep). Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).",
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
@@ -1936,13 +1994,16 @@ function registerTools(server, pool) {
         conn,
         async (client) => {
           const result = await exec(client, finalCommand, timeoutMs);
-          const parts = [];
-          if (result.stdout) parts.push(result.stdout);
-          if (result.stderr) parts.push(`[stderr]
-${result.stderr}`);
-          if (result.signal) parts.push(`[signal: ${result.signal}]`);
-          parts.push(`[exit code: ${result.code}]`);
-          return { content: [{ type: "text", text: parts.join("\n") }] };
+          const status = [`[exit code: ${result.code}]`];
+          if (result.signal) status.push(`[signal: ${result.signal}]`);
+          if (result.stdoutTruncated) status.push("[stdout truncated at the byte cap]");
+          if (result.stderrTruncated) status.push("[stderr truncated at the byte cap]");
+          const content = [{ type: "text", text: status.join("\n") }];
+          if (result.stderr) content.push({ type: "text", text: `[stderr]
+${result.stderr}` });
+          if (result.stdout) content.push({ type: "text", text: `[stdout]
+${result.stdout}` });
+          return { content };
         },
         poolWait(timeoutMs)
       );
@@ -1950,19 +2011,30 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_read_file",
-    `Read a file from a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}`,
+    `Read a file from a remote host via SFTP. A whole-file read is limited to 10 MB. For a large file -- or behind a proxy that caps results, such as Yaw MCP at about 100 KB -- read it in pages with \`offset\` and \`length\` (bytes): a paged read returns a status block first (\`[bytes A-B of SIZE]\` and the next offset) and then the text.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
-      path: z.string().refine((p) => p.startsWith("/"), {
-        message: "Path must be absolute (start with /). Relative paths resolve against the remote user's CWD, which is rarely what you want."
-      }).describe("Absolute path to the remote file. Must start with /.")
+      path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
+      offset: z.number().int().nonnegative().optional().describe("Byte offset to start reading at (default 0). Setting offset or length switches to a paged read."),
+      length: z.number().int().positive().max(DEFAULT_MAX_READ_BYTES).optional().describe(
+        "Number of bytes to read (default: the rest of the file, up to 10 MB). Behind Yaw MCP keep it at or under about 90000 so the page is not cut. A page boundary can split a multi-byte UTF-8 character."
+      )
     },
-    async ({ path, ...conn }) => {
+    READ_ONLY_REMOTE,
+    async ({ path, offset, length, ...conn }) => {
       return connectionPool.withConnection(
         conn,
         async (client) => {
-          const content = await readFile(client, path);
-          return { content: [{ type: "text", text: content }] };
+          if (offset === void 0 && length === void 0) {
+            const content2 = await readFile(client, path);
+            return { content: [{ type: "text", text: content2 }] };
+          }
+          const page = await readFileRange(client, path, offset ?? 0, length ?? DEFAULT_MAX_READ_BYTES);
+          const end = page.offset + page.bytesRead;
+          const where = page.bytesRead === 0 ? `[no bytes at offset ${page.offset}: the file is ${page.size} bytes]` : end < page.size ? `[bytes ${page.offset}-${end} of ${page.size}; next offset: ${end}]` : `[bytes ${page.offset}-${end} of ${page.size}; end of file]`;
+          const content = [{ type: "text", text: where }];
+          if (page.bytesRead > 0) content.push({ type: "text", text: page.text });
+          return { content };
         },
         poolWait()
       );
@@ -1976,6 +2048,7 @@ ${result.stderr}`);
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
       content: z.string().describe("File content to write")
     },
+    DESTRUCTIVE_REMOTE,
     async ({ path, content, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -1990,7 +2063,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_upload",
-    `Upload a local file to a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
+    `Upload a local file to a remote host via SFTP. Reads an arbitrary local file at an agent-chosen \`localPath\` -- any file readable by this process leaves the machine toward the remote host (the mirror direction of ssh_download's local write).${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       localPath: z.string().describe("Path to the local file to upload"),
@@ -2033,6 +2106,7 @@ ${result.stderr}`);
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote directory. Must start with /.")
     },
+    READ_ONLY_REMOTE,
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -2054,6 +2128,7 @@ ${result.stderr}`);
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file or directory. Must start with /.")
     },
+    READ_ONLY_REMOTE,
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -2104,6 +2179,7 @@ ${result.stderr}`);
         "Absolute path of the file or empty directory to delete. Must start with /."
       )
     },
+    DESTRUCTIVE_REMOTE,
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -2122,6 +2198,7 @@ ${result.stderr}`);
       host: HostSchema,
       port: PortSchema
     },
+    READ_ONLY_REMOTE,
     async ({ host, port }) => {
       const report = diagnose(host, port || 22);
       const lines = [];
@@ -2168,6 +2245,7 @@ ${result.stderr}`);
     "ssh_key_list",
     "List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded. Reports isError only when ~/.ssh exists but could not be read -- an absent or empty ~/.ssh is a successful answer with a ssh-keygen hint.",
     {},
+    READ_ONLY_LOCAL,
     async () => {
       const listing = listSshKeysDetailed();
       if (listing.status === "unreadable") {
@@ -2232,6 +2310,7 @@ ${result.stderr}`);
     {
       host: HostSchema
     },
+    READ_ONLY_LOCAL,
     async ({ host }) => {
       const result = configLookup(host);
       if ("error" in result) {
@@ -2304,7 +2383,9 @@ ${result.stderr}`);
     "ssh_multi_exec",
     "Execute a command on multiple remote hosts in parallel. Runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up. `timeout` is per host: it bounds each host's command, not the whole call. Each parallel slot works through its share of the list one host at a time, so with the pool to itself a call can take up to about ceil(hosts / SSH_MCP_MAX_POOL_SIZE) x (`timeout` + connect time). The connection pool is shared with every other tool; when it is full this call waits for slots instead of failing, and gives up only when none of its own hosts holds a slot and a full `timeout` has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report `Connection pool is full`; the queued ones are never attempted. Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out).",
     {
-      hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
+      // .min(1): `hosts: []` used to return an empty success block indistinguishable from a
+      // no-op -- the same boundary rejection ssh_git_check applies to its empty host.
+      hosts: z.array(z.string()).min(1, "hosts must not be empty. Name at least one host -- an empty list runs the command on nothing.").describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
       port: PortSchema,
       username: UsernameSchema,
@@ -2353,6 +2434,7 @@ ${result.stderr}`);
       newer: z.string().optional().describe("Reference file path -- find matches files modified more recently than this file"),
       timeout: TimeoutSchema
     },
+    READ_ONLY_REMOTE,
     async ({ path, name, type, maxdepth, minsize, maxsize, newer, timeout, ...conn }) => {
       const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
       return connectionPool.withConnection(
@@ -2379,6 +2461,7 @@ ${files.join("\n")}` }] };
       grep: z.string().optional().describe("Case-insensitive pattern to filter lines"),
       timeout: TimeoutSchema
     },
+    READ_ONLY_REMOTE,
     async ({ path, lines, grep, timeout, ...conn }) => {
       const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
       return connectionPool.withConnection(
@@ -2409,6 +2492,7 @@ ${files.join("\n")}` }] };
       service: z.string().describe("Systemd service name (e.g. nginx, sshd, docker)"),
       timeout: TimeoutSchema
     },
+    READ_ONLY_REMOTE,
     async ({ service, timeout, ...conn }) => {
       const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
       return connectionPool.withConnection(
@@ -2433,11 +2517,25 @@ ${files.join("\n")}` }] };
 
 // src/server.ts
 var version = typeof __VERSION__ !== "undefined" ? __VERSION__ : JSON.parse(readFileSync4(join4(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+var SERVER_INSTRUCTIONS = [
+  "ssh-mcp runs commands and moves files on remote hosts over SSH, using ~/.ssh/config, the ssh-agent and known_hosts the way the OpenSSH client does.",
+  "",
+  "- After an auth, connect or host-key failure, run ssh_diagnose on that host before retrying. ssh_test is the quick check; ssh_key_list and ssh_key_load fix a key missing from the agent; ssh_known_hosts_fix replaces a stale host key.",
+  "- Prefer the purpose-built tools over ssh_exec: ssh_read_file, ssh_ls, ssh_stat, ssh_find, ssh_tail, ssh_service_status. Use ssh_multi_exec for the same command on several hosts.",
+  "- ssh_exec returns the exit code first, then stderr, then stdout. Proxies may cut long results (Yaw MCP keeps about 100 KB), so filter on the remote (grep, head, tail) instead of printing everything. Page a large file with ssh_read_file offset and length.",
+  "- The SFTP tools take absolute remote paths (ssh_mkdir also accepts a relative one); ~ is not expanded.",
+  "- Host keys: a host already in known_hosts must match. An unknown host is trusted on every connection unless strict mode (SSH_MCP_STRICT_HOSTKEYS=1) is on; add it with ssh_known_hosts_fix first.",
+  "- On Windows the agent is the OpenSSH Authentication Agent service pipe; if agent auth fails, ssh_agent_ensure checks that the agent is reachable.",
+  "- SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST gate only ssh_exec and ssh_multi_exec, not the SFTP write and delete tools."
+].join("\n");
 function createServer(pool) {
-  const server = new McpServer({
-    name: "ssh-mcp",
-    version
-  });
+  const server = new McpServer(
+    {
+      name: "ssh-mcp",
+      version
+    },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
   registerTools(server, pool);
   return server;
 }

package/dist/policy.d.ts

@@ -18,5 +18,5 @@ export interface PolicyContext {
  * routed through here at all.
  */
 export declare function enforcePolicy(command: string, context?: PolicyContext): void;
-/** Returns true if any policy is currently configured. Used by tool descriptions to surface that. */
+/** Returns true if any policy is currently configured. Exported for library consumers and tests; tool descriptions use static "if configured" text instead. */
 export declare function isPolicyConfigured(): boolean;

package/dist/server.d.ts

@@ -1,17 +1,24 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ConnectionPool } from "./pool.js";
 export declare const version: string;
+/**
+ * Routing guidance sent once, at initialize. Yaw MCP shows it when this server is
+ * activated, capped at 2000 UTF-8 bytes, so it stays plain ASCII, well under that, and
+ * about these tools only (src/tests/server.test.ts pins both). It must not carry
+ * Yaw MCP's own framing markers, which the proxy strips or rejects.
+ */
+export declare const SERVER_INSTRUCTIONS: string;
 export declare function createServer(pool?: ConnectionPool): McpServer;
 export type { DiagnosticReport, DiagnosticResult } from "./diagnose.js";
 export { checkConnectivity, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, diagnose, } from "./diagnose.js";
-export type { AgentResult, ConfigLookupResult, KeyInfo } from "./env.js";
-export { checkGitSsh, configLookup, ensureAgent, fixKnownHosts, listSshKeys, loadKey, testConnection, } from "./env.js";
+export type { AgentResult, ConfigLookupResult, KeyInfo, SshKeyListing } from "./env.js";
+export { checkGitSsh, configLookup, ensureAgent, fixKnownHosts, listSshKeys, listSshKeysDetailed, loadKey, testConnection, } from "./env.js";
 export type { FindOptions, MultiExecHost, MultiExecResult, ServiceStatus } from "./ops.js";
-export { find, multiExec, serviceStatus, tail } from "./ops.js";
+export { find, multiExec, serviceStatus, shellQuote, tail } from "./ops.js";
 export type { PolicyContext } from "./policy.js";
 export { enforcePolicy, isPolicyConfigured } from "./policy.js";
 export type { AcquireOptions, PoolOptions } from "./pool.js";
 export { ConnectionPool, isPoolFullError, POOL_FULL_ERROR_CODE, PoolFullError } from "./pool.js";
-export type { ExecResult, FileStats, HostKeyRejection, HostKeyRejectionReason, ResolvedConfig, SSHConfig, } from "./ssh.js";
-export { connect, connectRaw, connectWithProxy, deleteFile, downloadFile, exec, formatDiagnostics, listDir, makeDir, readFile, readKnownHostsKeys, resolveConfig, statFile, uploadFile, writeFile, } from "./ssh.js";
+export type { ExecResult, FileRange, FileStats, HostKeyRejection, HostKeyRejectionReason, ResolvedConfig, SSHConfig, } from "./ssh.js";
+export { connect, connectRaw, connectWithProxy, deleteFile, downloadFile, exec, formatDiagnostics, listDir, makeDir, readFile, readFileRange, readKnownHostsKeys, resolveConfig, statFile, uploadFile, writeFile, } from "./ssh.js";
 export { registerTools } from "./tools.js";

package/dist/server.js

@@ -449,8 +449,15 @@ function cachedKnownHostTypes(hosts, port) {
   knownHostTypeCache.set(cacheKey, { at: now, types });
   return types;
 }
+function isStrictHostKeyMode(env = process.env) {
+  const on = (v) => {
+    const t = (v ?? "").trim().toLowerCase();
+    return t === "1" || t === "true";
+  };
+  return on(env.SSH_MCP_STRICT_HOSTKEYS) || on(env.SSH_MCP_STRICT_HOST_KEY);
+}
 function buildHostVerifier(hosts, port, rejection) {
-  const strict = process.env.SSH_MCP_STRICT_HOST_KEY === "1";
+  const strict = isStrictHostKeyMode();
   const label = hosts.join(" / ");
   const remediationHost = unbracketHost(hosts[0]);
   return (key) => {
@@ -460,7 +467,7 @@ function buildHostVerifier(hosts, port, rejection) {
       if (strict) {
         rejection.current = {
           reason: "unknown-host-strict",
-          message: `no known_hosts entry for ${label}, and SSH_MCP_STRICT_HOST_KEY=1 requires one. Add it: ssh-keyscan -H "${remediationHost}" >> ~/.ssh/known_hosts`
+          message: `no known_hosts entry for ${label}, and strict mode (SSH_MCP_STRICT_HOSTKEYS=1) requires one. Add it: ssh-keyscan -H "${remediationHost}" >> ~/.ssh/known_hosts`
         };
       }
       return !strict;
@@ -861,7 +868,7 @@ async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
     });
     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.`
+        `File is ${(stats.size / 1024 / 1024).toFixed(1)} MB, exceeds ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit. Read it a page at a time with ssh_read_file's offset and length arguments (byte offsets; the file is ${stats.size} bytes).`
       );
     }
     return await new Promise((resolve, reject) => {
@@ -874,6 +881,53 @@ async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
     sftp.end();
   }
 }
+async function readFileRange(client, remotePath, offset, length, maxBytes = DEFAULT_MAX_READ_BYTES) {
+  if (!Number.isSafeInteger(offset) || offset < 0)
+    throw new Error(`offset must be a non-negative integer, got ${offset}`);
+  if (!Number.isSafeInteger(length) || length <= 0) throw new Error(`length must be a positive integer, got ${length}`);
+  if (length > maxBytes) {
+    throw new Error(
+      `length ${length} exceeds the ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit for one read. Use a smaller length and page with offset.`
+    );
+  }
+  const sftp = await getSftp(client);
+  try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (err, st) => {
+        if (err) return reject(err);
+        resolve(st);
+      });
+    });
+    const want = Math.max(0, Math.min(length, stats.size - offset));
+    if (want === 0) return { text: "", offset, bytesRead: 0, size: stats.size };
+    const handle = await new Promise((resolve, reject) => {
+      sftp.open(remotePath, "r", (err, h) => {
+        if (err) return reject(err);
+        resolve(h);
+      });
+    });
+    try {
+      const buf = Buffer.alloc(want);
+      let got = 0;
+      while (got < want) {
+        const n = await new Promise((resolve, reject) => {
+          sftp.read(handle, buf, got, want - got, offset + got, (err, bytesRead) => {
+            if (err) return reject(err);
+            resolve(bytesRead ?? 0);
+          });
+        });
+        if (n === 0) break;
+        got += n;
+      }
+      return { text: buf.subarray(0, got).toString("utf8"), offset, bytesRead: got, size: stats.size };
+    } finally {
+      sftp.close(handle, () => {
+      });
+    }
+  } finally {
+    sftp.end();
+  }
+}
 async function writeFile(client, remotePath, content) {
   const sftp = await getSftp(client);
   try {
@@ -1544,6 +1598,7 @@ var ConnectionPool = class {
       if (entry.client === client) {
         entry.refCount = Math.max(0, entry.refCount - 1);
         if (entry.refCount === 0 && !entry.dead) {
+          if (entry.idleTimer) clearTimeout(entry.idleTimer);
           entry.idleTimer = setTimeout(() => {
             try {
               entry.client.end();
@@ -1787,14 +1842,14 @@ async function find(client, options, timeoutMs = 3e4) {
       `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "10M", "500k")`
     );
   }
-  const pathOperand = options.path.startsWith("-") || FIND_EXPRESSION_TOKENS.has(options.path) ? `./${options.path}` : options.path;
-  const args = [shellQuote(pathOperand)];
+  const defuseFindOperand = (p) => p.startsWith("-") || FIND_EXPRESSION_TOKENS.has(p) ? `./${p}` : p;
+  const args = [shellQuote(defuseFindOperand(options.path))];
   if (options.maxdepth !== void 0) args.push("-maxdepth", shellQuote(String(options.maxdepth)));
   if (options.type) args.push("-type", shellQuote(options.type));
   if (options.name) args.push("-name", shellQuote(options.name));
   if (options.minsize) args.push("-size", shellQuote(`+${options.minsize}`));
   if (options.maxsize) args.push("-size", shellQuote(`-${options.maxsize}`));
-  if (options.newer) args.push("-newer", shellQuote(options.newer));
+  if (options.newer) args.push("-newer", shellQuote(defuseFindOperand(options.newer)));
   const command = `find ${args.join(" ")}`;
   const result = await exec(client, command, timeoutMs);
   if (!result.stdout.trim() && result.stderr.trim()) {
@@ -1817,7 +1872,7 @@ async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
   return result.stdout;
 }
 async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
-  const result = await exec(client, `systemctl status -- ${shellQuote(serviceName)} 2>&1`, timeoutMs);
+  const result = await exec(client, `LC_ALL=C systemctl status -- ${shellQuote(serviceName)} 2>&1`, timeoutMs);
   const raw = result.stdout;
   const activeMatch = raw.match(/Active:\s+(\S+)\s+\(([^)]+)\)/);
   const descMatch = raw.match(/^[^\w\n]*\S+\s+-\s+(.+)$/m);
@@ -1907,6 +1962,9 @@ var connectionParams = {
 var DEFAULT_TIMEOUT_MS = 3e4;
 var poolWait = (timeoutMs = DEFAULT_TIMEOUT_MS) => ({ waitForCapacityMs: timeoutMs });
 var SFTP_POOL_WAIT_NOTE = ` If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to ${DEFAULT_TIMEOUT_MS / 1e3}s for a free slot before starting.`;
+var READ_ONLY_LOCAL = { readOnlyHint: true, openWorldHint: false };
+var READ_ONLY_REMOTE = { readOnlyHint: true, openWorldHint: true };
+var DESTRUCTIVE_REMOTE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
 var POLICY_EXEMPT_NOTE = " NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as `^rm` does NOT block this tool.";
 var ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function applyEnvPrefix(command, env) {
@@ -1927,7 +1985,7 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns up to three content blocks in this order: the status (`[exit code: N]`, plus the signal and any truncation), then `[stderr]`, then `[stdout]`. Status comes first so a proxy that cuts long results (Yaw MCP keeps about 100 KB) never drops the exit code; for big output, filter or page on the remote (head, tail, grep). Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command).",
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
@@ -1942,13 +2000,16 @@ function registerTools(server, pool) {
         conn,
         async (client) => {
           const result = await exec(client, finalCommand, timeoutMs);
-          const parts = [];
-          if (result.stdout) parts.push(result.stdout);
-          if (result.stderr) parts.push(`[stderr]
-${result.stderr}`);
-          if (result.signal) parts.push(`[signal: ${result.signal}]`);
-          parts.push(`[exit code: ${result.code}]`);
-          return { content: [{ type: "text", text: parts.join("\n") }] };
+          const status = [`[exit code: ${result.code}]`];
+          if (result.signal) status.push(`[signal: ${result.signal}]`);
+          if (result.stdoutTruncated) status.push("[stdout truncated at the byte cap]");
+          if (result.stderrTruncated) status.push("[stderr truncated at the byte cap]");
+          const content = [{ type: "text", text: status.join("\n") }];
+          if (result.stderr) content.push({ type: "text", text: `[stderr]
+${result.stderr}` });
+          if (result.stdout) content.push({ type: "text", text: `[stdout]
+${result.stdout}` });
+          return { content };
         },
         poolWait(timeoutMs)
       );
@@ -1956,19 +2017,30 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_read_file",
-    `Read a file from a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}`,
+    `Read a file from a remote host via SFTP. A whole-file read is limited to 10 MB. For a large file -- or behind a proxy that caps results, such as Yaw MCP at about 100 KB -- read it in pages with \`offset\` and \`length\` (bytes): a paged read returns a status block first (\`[bytes A-B of SIZE]\` and the next offset) and then the text.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
-      path: z.string().refine((p) => p.startsWith("/"), {
-        message: "Path must be absolute (start with /). Relative paths resolve against the remote user's CWD, which is rarely what you want."
-      }).describe("Absolute path to the remote file. Must start with /.")
+      path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
+      offset: z.number().int().nonnegative().optional().describe("Byte offset to start reading at (default 0). Setting offset or length switches to a paged read."),
+      length: z.number().int().positive().max(DEFAULT_MAX_READ_BYTES).optional().describe(
+        "Number of bytes to read (default: the rest of the file, up to 10 MB). Behind Yaw MCP keep it at or under about 90000 so the page is not cut. A page boundary can split a multi-byte UTF-8 character."
+      )
     },
-    async ({ path, ...conn }) => {
+    READ_ONLY_REMOTE,
+    async ({ path, offset, length, ...conn }) => {
       return connectionPool.withConnection(
         conn,
         async (client) => {
-          const content = await readFile(client, path);
-          return { content: [{ type: "text", text: content }] };
+          if (offset === void 0 && length === void 0) {
+            const content2 = await readFile(client, path);
+            return { content: [{ type: "text", text: content2 }] };
+          }
+          const page = await readFileRange(client, path, offset ?? 0, length ?? DEFAULT_MAX_READ_BYTES);
+          const end = page.offset + page.bytesRead;
+          const where = page.bytesRead === 0 ? `[no bytes at offset ${page.offset}: the file is ${page.size} bytes]` : end < page.size ? `[bytes ${page.offset}-${end} of ${page.size}; next offset: ${end}]` : `[bytes ${page.offset}-${end} of ${page.size}; end of file]`;
+          const content = [{ type: "text", text: where }];
+          if (page.bytesRead > 0) content.push({ type: "text", text: page.text });
+          return { content };
         },
         poolWait()
       );
@@ -1982,6 +2054,7 @@ ${result.stderr}`);
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
       content: z.string().describe("File content to write")
     },
+    DESTRUCTIVE_REMOTE,
     async ({ path, content, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -1996,7 +2069,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_upload",
-    `Upload a local file to a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
+    `Upload a local file to a remote host via SFTP. Reads an arbitrary local file at an agent-chosen \`localPath\` -- any file readable by this process leaves the machine toward the remote host (the mirror direction of ssh_download's local write).${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       localPath: z.string().describe("Path to the local file to upload"),
@@ -2039,6 +2112,7 @@ ${result.stderr}`);
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote directory. Must start with /.")
     },
+    READ_ONLY_REMOTE,
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -2060,6 +2134,7 @@ ${result.stderr}`);
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file or directory. Must start with /.")
     },
+    READ_ONLY_REMOTE,
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -2110,6 +2185,7 @@ ${result.stderr}`);
         "Absolute path of the file or empty directory to delete. Must start with /."
       )
     },
+    DESTRUCTIVE_REMOTE,
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(
         conn,
@@ -2128,6 +2204,7 @@ ${result.stderr}`);
       host: HostSchema,
       port: PortSchema
     },
+    READ_ONLY_REMOTE,
     async ({ host, port }) => {
       const report = diagnose(host, port || 22);
       const lines = [];
@@ -2174,6 +2251,7 @@ ${result.stderr}`);
     "ssh_key_list",
     "List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded. Reports isError only when ~/.ssh exists but could not be read -- an absent or empty ~/.ssh is a successful answer with a ssh-keygen hint.",
     {},
+    READ_ONLY_LOCAL,
     async () => {
       const listing = listSshKeysDetailed();
       if (listing.status === "unreadable") {
@@ -2238,6 +2316,7 @@ ${result.stderr}`);
     {
       host: HostSchema
     },
+    READ_ONLY_LOCAL,
     async ({ host }) => {
       const result = configLookup(host);
       if ("error" in result) {
@@ -2310,7 +2389,9 @@ ${result.stderr}`);
     "ssh_multi_exec",
     "Execute a command on multiple remote hosts in parallel. Runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up. `timeout` is per host: it bounds each host's command, not the whole call. Each parallel slot works through its share of the list one host at a time, so with the pool to itself a call can take up to about ceil(hosts / SSH_MCP_MAX_POOL_SIZE) x (`timeout` + connect time). The connection pool is shared with every other tool; when it is full this call waits for slots instead of failing, and gives up only when none of its own hosts holds a slot and a full `timeout` has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report `Connection pool is full`; the queued ones are never attempted. Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out).",
     {
-      hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
+      // .min(1): `hosts: []` used to return an empty success block indistinguishable from a
+      // no-op -- the same boundary rejection ssh_git_check applies to its empty host.
+      hosts: z.array(z.string()).min(1, "hosts must not be empty. Name at least one host -- an empty list runs the command on nothing.").describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
       port: PortSchema,
       username: UsernameSchema,
@@ -2359,6 +2440,7 @@ ${result.stderr}`);
       newer: z.string().optional().describe("Reference file path -- find matches files modified more recently than this file"),
       timeout: TimeoutSchema
     },
+    READ_ONLY_REMOTE,
     async ({ path, name, type, maxdepth, minsize, maxsize, newer, timeout, ...conn }) => {
       const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
       return connectionPool.withConnection(
@@ -2385,6 +2467,7 @@ ${files.join("\n")}` }] };
       grep: z.string().optional().describe("Case-insensitive pattern to filter lines"),
       timeout: TimeoutSchema
     },
+    READ_ONLY_REMOTE,
     async ({ path, lines, grep, timeout, ...conn }) => {
       const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
       return connectionPool.withConnection(
@@ -2415,6 +2498,7 @@ ${files.join("\n")}` }] };
       service: z.string().describe("Systemd service name (e.g. nginx, sshd, docker)"),
       timeout: TimeoutSchema
     },
+    READ_ONLY_REMOTE,
     async ({ service, timeout, ...conn }) => {
       const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
       return connectionPool.withConnection(
@@ -2439,11 +2523,25 @@ ${files.join("\n")}` }] };
 
 // src/server.ts
 var version = typeof __VERSION__ !== "undefined" ? __VERSION__ : JSON.parse(readFileSync4(join4(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+var SERVER_INSTRUCTIONS = [
+  "ssh-mcp runs commands and moves files on remote hosts over SSH, using ~/.ssh/config, the ssh-agent and known_hosts the way the OpenSSH client does.",
+  "",
+  "- After an auth, connect or host-key failure, run ssh_diagnose on that host before retrying. ssh_test is the quick check; ssh_key_list and ssh_key_load fix a key missing from the agent; ssh_known_hosts_fix replaces a stale host key.",
+  "- Prefer the purpose-built tools over ssh_exec: ssh_read_file, ssh_ls, ssh_stat, ssh_find, ssh_tail, ssh_service_status. Use ssh_multi_exec for the same command on several hosts.",
+  "- ssh_exec returns the exit code first, then stderr, then stdout. Proxies may cut long results (Yaw MCP keeps about 100 KB), so filter on the remote (grep, head, tail) instead of printing everything. Page a large file with ssh_read_file offset and length.",
+  "- The SFTP tools take absolute remote paths (ssh_mkdir also accepts a relative one); ~ is not expanded.",
+  "- Host keys: a host already in known_hosts must match. An unknown host is trusted on every connection unless strict mode (SSH_MCP_STRICT_HOSTKEYS=1) is on; add it with ssh_known_hosts_fix first.",
+  "- On Windows the agent is the OpenSSH Authentication Agent service pipe; if agent auth fails, ssh_agent_ensure checks that the agent is reachable.",
+  "- SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST gate only ssh_exec and ssh_multi_exec, not the SFTP write and delete tools."
+].join("\n");
 function createServer(pool) {
-  const server = new McpServer({
-    name: "ssh-mcp",
-    version
-  });
+  const server = new McpServer(
+    {
+      name: "ssh-mcp",
+      version
+    },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
   registerTools(server, pool);
   return server;
 }
@@ -2451,6 +2549,7 @@ export {
   ConnectionPool,
   POOL_FULL_ERROR_CODE,
   PoolFullError,
+  SERVER_INSTRUCTIONS,
   checkConnectivity,
   checkGitSsh,
   checkKnownHosts,
@@ -2475,14 +2574,17 @@ export {
   isPoolFullError,
   listDir,
   listSshKeys,
+  listSshKeysDetailed,
   loadKey,
   makeDir,
   multiExec,
   readFile,
+  readFileRange,
   readKnownHostsKeys,
   registerTools,
   resolveConfig,
   serviceStatus,
+  shellQuote,
   statFile,
   tail,
   testConnection,

package/dist/ssh.d.ts

@@ -20,7 +20,7 @@ export interface ExecResult {
 }
 /** Why the hostVerifier turned a server's host key down. */
 export type HostKeyRejectionReason = 
-/** No known_hosts entry at all, and SSH_MCP_STRICT_HOST_KEY=1. */
+/** No known_hosts entry at all, and strict mode is on (SSH_MCP_STRICT_HOSTKEYS, see isStrictHostKeyMode). */
 "unknown-host-strict"
 /** known_hosts has entries for this host, but none of the algorithm the server offered. */
  | "algorithm-not-in-known-hosts"
@@ -107,6 +107,21 @@ export declare function hostKeyBlobType(key: Buffer): string | null;
 export declare function hostKeyAlgorithmOrder(knownHostTypes: ReadonlyArray<string>): string[] | null;
 /** Test-only: drop the memoized known_hosts key types. */
 export declare function clearKnownHostTypeCache(): void;
+/**
+ * Strict host-key mode: reject a host with no known_hosts entry instead of trusting it.
+ *
+ * Two names, one switch. SSH_MCP_STRICT_HOSTKEYS is the documented one.
+ * SSH_MCP_STRICT_HOST_KEY is the original name and keeps working, but it is
+ * credential-shaped -- `KEY` is a whole underscore segment -- so Yaw MCP's doctor
+ * listed `SSH_MCP_STRICT_HOST_KEY=1` as a plaintext secret and suggested moving it
+ * into the vault. `HOSTKEYS` is not a credential segment, so the new name is not
+ * flagged. Either one turns strict mode on.
+ *
+ * Both are read the way Yaw MCP reads an opt-in: trimmed, case-insensitive `1` or
+ * `true`. Only the exact string "1" used to count, so `=true` silently left strict
+ * mode OFF -- the unsafe direction for a security switch.
+ */
+export declare function isStrictHostKeyMode(env?: NodeJS.ProcessEnv): boolean;
 export declare function resolveConfig(config: SSHConfig): ResolvedConfig;
 export declare function formatDiagnostics(host: string): string;
 export declare function connectRaw(connectConfig: ConnectConfig): Promise<Client>;
@@ -136,7 +151,7 @@ export interface JumpHop {
  *
  * It is also a host-key issue, not only a connectivity one: `knownHostsTargets`
  * rejects those mangled spellings and returns [], and a verifier with zero known
- * entries accepts ANY key unless SSH_MCP_STRICT_HOST_KEY=1. Parsing correctly is
+ * entries accepts ANY key unless SSH_MCP_STRICT_HOSTKEYS=1. Parsing correctly is
  * what puts the bastion hop back under real known_hosts checking.
  *
  * Grammar (OpenSSH ssh_config(5)): `[user@]host[:port]`, or the equivalent
@@ -173,7 +188,28 @@ export declare function enhanceSshError(err: unknown, host: string, resolved?: R
 export declare function connect(config: SSHConfig): Promise<Client>;
 export declare const DEFAULT_MAX_EXEC_BYTES: number;
 export declare function exec(client: Client, command: string, timeoutMs?: number, maxBytes?: number): Promise<ExecResult>;
+export declare const DEFAULT_MAX_READ_BYTES: number;
 export declare function readFile(client: Client, remotePath: string, maxBytes?: number): Promise<string>;
+/** One page of a remote file, plus where it sits in the whole. */
+export interface FileRange {
+    /** The bytes read, decoded as UTF-8. A page boundary can split a multi-byte character. */
+    text: string;
+    /** Byte offset the page starts at (as requested). */
+    offset: number;
+    /** Number of bytes actually read: less than requested at end of file. */
+    bytesRead: number;
+    /** Size of the whole file, from the same stat. */
+    size: number;
+}
+/**
+ * Read `length` bytes of a remote file starting at byte `offset`.
+ *
+ * The paging half of ssh_read_file. A whole-file read is capped at 10 MB here, but a
+ * proxy in front of this server can cap far lower -- Yaw MCP keeps 100 KB of a result
+ * by default and cuts the rest -- so a large file has to be readable in pages without
+ * turning a cap off. `length` is bounded by the same `maxBytes` as a whole read.
+ */
+export declare function readFileRange(client: Client, remotePath: string, offset: number, length: number, maxBytes?: number): Promise<FileRange>;
 export declare function writeFile(client: Client, remotePath: string, content: string): Promise<void>;
 export declare function uploadFile(client: Client, localPath: string, remotePath: string): Promise<void>;
 export declare function downloadFile(client: Client, remotePath: string, localPath: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "mcpName": "io.github.YawLabs/ssh-mcp",
   "description": "SSH MCP server: run remote commands, transfer files over SFTP, manage ssh-agent keys and known_hosts, and auto-diagnose SSH failures.",
   "type": "module",
@@ -28,6 +28,8 @@
     "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",
+    "check:compliance": "node scripts/check-compliance.mjs",
+    "check:oam-floor": "node scripts/check-oam-floor.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -72,6 +74,7 @@
     "@types/node": "^26.1.1",
     "@types/ssh2": "^1.15.5",
     "@vitest/coverage-v8": "^4.1.11",
+    "@yawlabs/mcp-compliance": "^0.20.4",
     "esbuild": "^0.28.1",
     "postject": "^1.0.0-alpha.6",
     "tsup": "^8.5.1",