@yawlabs/ssh-mcp 0.15.1 → 0.15.2

package/README.md

@@ -303,10 +303,37 @@ for (const check of report.checks) {
 }
 ```
 
+## Runtime selection
+
+The `ssh-mcp` command — what `npx @yawlabs/ssh-mcp` runs — is a small launcher. It prefers the [oam](https://oamjs.org) runtime and otherwise runs the server on Node, so oam is optional. Two environment variables control the choice; set them in your MCP client's `env` block:
+
+- `SSH_MCP_RUNTIME` — which runtime to use. Case-insensitive; any value other than `oam` or `node` behaves as `auto`.
+  - `auto` (default) — use oam if it is usable, otherwise fall back to Node.
+  - `oam` — require oam. Fails loudly: if oam is missing or unusable, the launcher prints the reason to stderr and exits with status 1 instead of starting the server.
+  - `node` — never use oam. The launcher does not look for it, and `OAM_BIN` is ignored.
+- `OAM_BIN` — path to a specific oam binary. When set to a non-empty value it wins over discovery and nothing else is searched, so a path that does not exist counts as no oam found even if a working oam is installed elsewhere. Without it, the launcher takes the first oam it finds in `%LOCALAPPDATA%\oam\bin` (Windows only), then `~/.oam/bin`, then `PATH`, and does not keep looking if that one is unusable.
+
+oam must be **0.9.0 or newer**. By default an unusable oam is not an error: in `auto` mode the launcher falls back to Node — silently when no oam is found (including an `OAM_BIN` path that does not exist), or with a note on stderr when it finds one it cannot use: older than 0.9.0, not runnable, or on Windows only an `oam.cmd`/`oam.bat` shim on `PATH`. With `SSH_MCP_RUNTIME=oam`, each of these cases exits with status 1 instead.
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/ssh-mcp@latest"],
+      "env": { "SSH_MCP_RUNTIME": "node" }
+    }
+  }
+}
+```
+
+On Windows, add the same `env` block to the `cmd /c` form from [Quick start](#quick-start).
+
 ## Requirements
 
 - Node.js 18+
 - SSH client installed (for diagnostics and environment management)
+- Optional: [oam](https://oamjs.org) 0.9.0+ — see [Runtime selection](#runtime-selection)
 
 ## License
 

package/bin/ssh-mcp.mjs

@@ -22,6 +22,23 @@
  * For an MCP host config, point straight at oam and skip this file:
  *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
  *
+ * ALREADY RUNNING ON OAM
+ * A host can resolve this package's `bin` and launch `oam run <this file>`
+ * instead of `node <this file>` -- Yaw MCP does, and so does oam's sidecar
+ * regression matrix. This launcher used to discover oam and spawn it anyway,
+ * so one server cost two runtime boots: measured on Windows, oam.exe with a
+ * NESTED oam.exe + conhost.exe underneath it. Now, when `process.versions.oam`
+ * clears the same MINIMUM OAM VERSION a discovered binary has to, the server is
+ * imported into THIS process exactly as the Node fallback is -- no discovery,
+ * no `oam --version` probe, no second oam. OAM_BIN is a discovery input, so it
+ * is not consulted on that path: the host has already chosen which oam runs.
+ *
+ * A host oam below the floor still takes the discovery path exactly as it
+ * always did. Nothing else has to keep spawning on oam: the spawn below passes
+ * oam no runtime flags -- there is no `--permission` sandbox to apply, see NO
+ * SANDBOX HERE -- so serving in-process drops nothing a fresh oam would have
+ * applied.
+ *
  * NO SANDBOX HERE -- DELIBERATELY
  * The purpose of this server is to open outbound SSH to hosts the caller names
  * at run time and run commands there, so the net and child-process grants would
@@ -41,6 +58,7 @@
  *
  * SELECTION
  *   SSH_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *                            (already running on oam satisfies it)
  *   SSH_MCP_RUNTIME=node   never use oam
  *   SSH_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
  *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
@@ -158,17 +176,27 @@ async function errSync(message) {
 }
 
 /**
- * `oam --version` -> [major, minor, patch], or null when it cannot be read.
+ * Version text -> [major, minor, patch], or null when it holds no version.
  * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ *
+ * Shared by the two places a version is read -- a discovered binary's
+ * `oam --version` output ("oam 0.15.1") and the host's own
+ * `process.versions.oam` ("0.15.1") -- so they cannot disagree about what a
+ * version string means, or which floor it has to clear.
  */
+function parseVersion(text) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** `oam --version` -> [major, minor, patch], or null when it cannot be read. */
 function oamVersion(cmd) {
   try {
     const out = execFileSync(cmd, ["--version"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
     });
-    const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
-    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    return parseVersion(out);
   } catch {
     // Not executable, wrong arch, or deleted since the stat. Caller degrades.
     return null;
@@ -185,6 +213,27 @@ function atLeast(v, min) {
   return true;
 }
 
+/**
+ * Where the server runs, decided BEFORE any discovery:
+ *   "in-process"  import it into THIS process
+ *   "discover"    find an oam binary, gate its version, spawn it -- or fall
+ *                 back to Node in-process when that fails
+ *
+ * `hostOam` is `process.versions.oam`: oam's own key, absent on Node, so on
+ * Node every mode but `node` is the discovery path it always was. The floor is
+ * OAM_MIN itself, not a parameter, so a host oam and a discovered one can never
+ * be held to different minimums. There is no sandbox input because this
+ * launcher has no sandbox; see ALREADY RUNNING ON OAM above for why nothing
+ * else forces a spawn.
+ *
+ * Pure on purpose: every input is passed in, so the whole decision is testable
+ * without booting a runtime.
+ */
+function runtimePlan({ mode, hostOam }) {
+  if (mode === "node") return "in-process";
+  return atLeast(parseVersion(hostOam ?? ""), OAM_MIN) ? "in-process" : "discover";
+}
+
 /** Run the server in THIS process. The zero-overhead fallback. */
 async function runInProcess() {
   // A server may gate its bootstrap on being the process ENTRY POINT --
@@ -202,8 +251,9 @@ async function runInProcess() {
 }
 
 const mode = (process.env.SSH_MCP_RUNTIME ?? "auto").toLowerCase();
+const plan = runtimePlan({ mode, hostOam: process.versions.oam });
 
-if (mode === "node") {
+if (plan === "in-process") {
   await runInProcess();
 } else {
   const { path: oam, shim: oamShim } = findOam();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "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",