@yawlabs/ssh-mcp 0.17.2 → 0.18.0

package/dist/index.js

@@ -11,7 +11,16 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/env.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { appendFileSync, existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync } from "fs";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync as existsSync2,
+  constants as fsConstants,
+  fstatSync,
+  openSync,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync3
+} from "fs";
 import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
 
@@ -432,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) => {
@@ -443,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;
@@ -835,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) => {
@@ -848,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 {
@@ -1083,7 +1146,7 @@ function ensureAgent() {
     message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
   };
 }
-function detectKeyType(filePath, fileName) {
+function detectKeyType(filePath, fileName, content) {
   const pubPath = `${filePath}.pub`;
   if (existsSync2(pubPath)) {
     try {
@@ -1100,7 +1163,6 @@ function detectKeyType(filePath, fileName) {
   if (fileName.includes("ecdsa")) return "ecdsa";
   if (fileName.includes("dsa")) return "dsa";
   try {
-    const content = readFileSync3(filePath, "utf8");
     if (content.includes("RSA PRIVATE KEY")) return "rsa";
     if (content.includes("EC PRIVATE KEY")) return "ecdsa";
     if (content.includes("DSA PRIVATE KEY")) return "dsa";
@@ -1136,12 +1198,13 @@ function listSshKeysDetailed() {
   for (const file of files) {
     if (file.endsWith(".pub") || file.startsWith(".") || SSH_NON_KEY_FILES.has(file)) continue;
     const filePath = join3(sshDir, file);
+    let fd;
     try {
-      const stat = statSync(filePath);
-      if (!stat.isFile()) continue;
-      const content = readFileSync3(filePath, "utf8");
+      fd = openSync(filePath, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK ?? 0) | (fsConstants.O_NOCTTY ?? 0));
+      if (!fstatSync(fd).isFile()) continue;
+      const content = readFileSync3(fd, "utf8");
       if (!content.includes("PRIVATE KEY")) continue;
-      const type = detectKeyType(filePath, file);
+      const type = detectKeyType(filePath, file, content);
       let fingerprint;
       const { stdout: fpOut, ok: fpOk } = runArgs("ssh-keygen", ["-lf", filePath]);
       if (fpOk) {
@@ -1151,6 +1214,8 @@ function listSshKeysDetailed() {
       const loadedInAgent = fingerprint ? loadedFingerprints.has(fingerprint) : false;
       keys.push({ name: file, path: filePath, type, fingerprint, loadedInAgent });
     } catch {
+    } finally {
+      if (fd !== void 0) closeSync(fd);
     }
   }
   return { status: "ok", dir: sshDir, keys };
@@ -1306,7 +1371,7 @@ function testConnection(host, port = 22) {
 }
 
 // src/pool.ts
-import { createHash } from "crypto";
+import { createHmac, randomBytes, scryptSync } from "crypto";
 var POOL_FULL_ERROR_CODE = "ERR_SSH_MCP_POOL_FULL";
 var PoolFullError = class extends Error {
   code = POOL_FULL_ERROR_CODE;
@@ -1336,21 +1401,24 @@ function defaultMaxPoolSize() {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
 }
+var AUTH_FINGERPRINT_SECRET = randomBytes(32);
+var PASSWORD_SCRYPT_COST = 1024;
+function updateField(h, tag, value) {
+  const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : value;
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(bytes.length);
+  h.update(tag);
+  h.update(len);
+  h.update(bytes);
+}
 function authFingerprint(cc) {
-  const h = createHash("sha256");
-  if (cc.privateKey) {
-    h.update("k");
-    h.update(cc.privateKey);
-  }
+  const h = createHmac("sha256", AUTH_FINGERPRINT_SECRET);
+  if (cc.privateKey) updateField(h, "k", cc.privateKey);
   if (cc.password !== void 0) {
-    h.update("p");
-    h.update(cc.password);
+    updateField(h, "p", scryptSync(cc.password, AUTH_FINGERPRINT_SECRET, 32, { N: PASSWORD_SCRYPT_COST }));
   }
-  if (typeof cc.agent === "string") {
-    h.update("a");
-    h.update(cc.agent);
-  }
-  return h.digest("hex").slice(0, 16);
+  if (typeof cc.agent === "string") updateField(h, "a", cc.agent);
+  return h.digest("hex").slice(0, 32);
 }
 function resolveOrDiagnose(config) {
   try {
@@ -1510,7 +1578,7 @@ var ConnectionPool = class {
       return client;
     }
     throw new Error(
-      `Failed to acquire SSH connection for ${key} after ${MAX_ACQUIRE_ATTEMPTS} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+      `Failed to acquire SSH connection for ${cc.username}@${cc.host}:${cc.port} after ${MAX_ACQUIRE_ATTEMPTS} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
     );
   }
   release(client) {
@@ -1518,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();
@@ -1743,7 +1812,23 @@ async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
 }
 var VALID_FIND_SIZE = /^\d+[cwbkMG]?$/;
 var FIND_EXPRESSION_TOKENS = /* @__PURE__ */ new Set(["(", ")", "!", ","]);
+var VALID_FIND_TYPES = /* @__PURE__ */ new Set(["f", "d", "l"]);
+function isNonNegativeInteger(n) {
+  return typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+}
 async function find(client, options, timeoutMs = 3e4) {
+  if (options.type !== void 0 && !VALID_FIND_TYPES.has(options.type)) {
+    throw new Error(`Invalid type: "${String(options.type)}". Expected one of: f (file), d (directory), l (symlink)`);
+  }
+  if (options.maxdepth !== void 0 && !isNonNegativeInteger(options.maxdepth)) {
+    throw new Error(`Invalid maxdepth: ${String(options.maxdepth)}. Expected a non-negative integer`);
+  }
+  if (options.minsize !== void 0 && typeof options.minsize !== "string") {
+    throw new Error('Invalid minsize: expected a string such as "1M" or "100k"');
+  }
+  if (options.maxsize !== void 0 && typeof options.maxsize !== "string") {
+    throw new Error('Invalid maxsize: expected a string such as "10M" or "500k"');
+  }
   if (options.minsize && !VALID_FIND_SIZE.test(options.minsize)) {
     throw new Error(
       `Invalid minsize format: "${options.minsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "1M", "100k")`
@@ -1754,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)];
-  if (options.maxdepth !== void 0) args.push("-maxdepth", String(options.maxdepth));
-  if (options.type) args.push("-type", options.type);
+  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", `+${options.minsize}`);
-  if (options.maxsize) args.push("-size", `-${options.maxsize}`);
-  if (options.newer) args.push("-newer", shellQuote(options.newer));
+  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(defuseFindOperand(options.newer)));
   const command = `find ${args.join(" ")}`;
   const result = await exec(client, command, timeoutMs);
   if (!result.stdout.trim() && result.stderr.trim()) {
@@ -1770,6 +1855,9 @@ async function find(client, options, timeoutMs = 3e4) {
   return result.stdout.split("\n").filter(Boolean);
 }
 async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
+  if (!isNonNegativeInteger(lines) || lines === 0) {
+    throw new Error(`Invalid lines: ${String(lines)}. Expected a positive integer`);
+  }
   let command = `tail -n ${lines} -- ${shellQuote(path)}`;
   if (grep) {
     command += ` | grep -i -e ${shellQuote(grep)}`;
@@ -1781,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);
@@ -1868,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) {
@@ -1888,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)"),
@@ -1903,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)
       );
@@ -1917,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()
       );
@@ -1943,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,
@@ -1957,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"),
@@ -2000,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,
@@ -2021,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,
@@ -2071,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,
@@ -2089,6 +2198,7 @@ ${result.stderr}`);
       host: HostSchema,
       port: PortSchema
     },
+    READ_ONLY_REMOTE,
     async ({ host, port }) => {
       const report = diagnose(host, port || 22);
       const lines = [];
@@ -2135,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") {
@@ -2199,6 +2310,7 @@ ${result.stderr}`);
     {
       host: HostSchema
     },
+    READ_ONLY_LOCAL,
     async ({ host }) => {
       const result = configLookup(host);
       if ("error" in result) {
@@ -2271,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,
@@ -2314,12 +2428,13 @@ ${result.stderr}`);
       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"),
+      maxdepth: z.number().int().nonnegative().optional().describe("Maximum directory depth to search (0 = the path itself only)"),
       minsize: z.string().optional().describe("Minimum file size (e.g. '1M', '100k')"),
       maxsize: z.string().optional().describe("Maximum file size (e.g. '10M', '500k')"),
       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(
@@ -2346,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(
@@ -2376,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(
@@ -2400,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";