@yawlabs/tailscale-mcp 0.19.2 → 0.19.3

package/bin/tailscale-mcp.mjs

@@ -22,6 +22,27 @@
  * 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.
+ *
+ * Two cases still go through discovery, deliberately. TAILSCALE_MCP_SANDBOX=1,
+ * because `--permission` is a process-level flag that only a FRESH oam can
+ * apply -- serving in-process there would drop the sandbox without a word, a
+ * security downgrade dressed up as an optimisation. And a host oam below the
+ * floor. Both then run exactly as they did before this shortcut existed,
+ * fallback included: discovery spawns a fresh oam only when it finds one at or
+ * above the floor that launches. Otherwise auto serves in-process as before --
+ * for a sandbox request that means WITHOUT --permission, so pair the sandbox
+ * with TAILSCALE_MCP_RUNTIME=oam to make that a hard failure instead.
+ *
  * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
  * `TAILSCALE_MCP_SANDBOX=1` runs the server under oam's permission model:
  * network limited to the one host the bundle actually calls
@@ -48,6 +69,7 @@
  *
  * SELECTION
  *   TAILSCALE_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *                                (already running on oam satisfies it)
  *   TAILSCALE_MCP_RUNTIME=node   never use oam
  *   TAILSCALE_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
  *   anything else                warns on stderr, then behaves as auto
@@ -116,17 +138,27 @@ function findOam() {
 }
 
 /**
- * `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;
@@ -143,6 +175,34 @@ 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; when that
+ *                 fails, auto falls back in-process and `oam` exits 1
+ *
+ * `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. Only `node`
+ * is distinguished here: `oam` is satisfied by a host that already is one, and
+ * an unrecognized value has been warned about and lands with auto, as it does
+ * in the discovery branch.
+ *
+ * `sandbox` is whether a spawn would carry flags only a fresh oam can apply;
+ * see ALREADY RUNNING ON OAM above for why that alone forces discovery. It does
+ * not guarantee a spawn: when discovery finds no launchable oam at the floor,
+ * auto still serves in-process, without --permission. The
+ * floor is OAM_MIN itself, not a parameter, so a host oam and a discovered one
+ * can never be held to different minimums.
+ *
+ * Pure on purpose: every input is passed in, so the whole decision is testable
+ * without booting a runtime.
+ */
+function runtimePlan({ mode, hostOam, sandbox }) {
+  if (mode === "node") return "in-process";
+  if (sandbox) return "discover";
+  return atLeast(parseVersion(hostOam ?? ""), OAM_MIN) ? "in-process" : "discover";
+}
+
 /**
  * The `--permission` grant list, or [] when the sandbox is not requested.
  *
@@ -280,7 +340,12 @@ if (requested && !RUNTIMES.includes(mode)) {
   );
 }
 
-if (mode === "node") {
+// The sandbox is read off the grant list rather than TAILSCALE_MCP_SANDBOX, so
+// "would the spawn carry --permission" cannot drift from what the spawn below
+// actually passes.
+const plan = runtimePlan({ mode, hostOam: process.versions.oam, sandbox: sandboxFlags().length > 0 });
+
+if (plan === "in-process") {
   await runInProcess();
 } else {
   const oam = findOam();

package/dist/index.js

@@ -34551,12 +34551,29 @@ function buildMetaTools(state) {
 }
 
 // src/index.ts
-var version2 = true ? "0.19.2" : resolveVersionFallback();
+var version2 = true ? "0.19.3" : resolveVersionFallback();
 var subcommand = process.argv[2];
+var USAGE = `Usage: tailscale-mcp [command]
+
+Commands:
+  deploy-acl <path-to-acl.json>    Deploy an ACL policy
+  validate-acl <path-to-acl.json>  Validate an ACL policy
+  version                          Print the installed version
+  help                             Print this message
+
+Flags:
+  --version, -V                    Print the installed version
+  --help, -h                       Print this message
+
+Run without a command to start the MCP server on stdio.`;
 var cliSubcommandHandled = false;
 if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
   cliSubcommandHandled = true;
   const filePath = process.argv[3];
+  if (filePath === "--help" || filePath === "-h") {
+    console.log(`Usage: tailscale-mcp ${subcommand} <path-to-acl.json>`);
+    process.exit(0);
+  }
   if (!filePath) {
     console.error(`Usage: tailscale-mcp ${subcommand} <path-to-acl.json>`);
     process.exit(1);
@@ -34566,12 +34583,15 @@ if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
     console.error(`Fatal: ${err instanceof Error ? err.message : err}`);
     process.exit(1);
   });
-} else if (subcommand === "version" || subcommand === "--version") {
+} else if (subcommand === "version" || subcommand === "--version" || subcommand === "-V") {
   console.log(version2);
   process.exit(0);
+} else if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
+  console.log(USAGE);
+  process.exit(0);
 } else if (subcommand !== void 0) {
   console.error(
-    `@yawlabs/tailscale-mcp: unrecognized argument "${subcommand}" -- known subcommands: deploy-acl, validate-acl, version. Starting the MCP server.`
+    `@yawlabs/tailscale-mcp: unrecognized argument "${subcommand}" -- known subcommands: deploy-acl, validate-acl, version, help (or --help). Starting the MCP server.`
   );
 }
 if (!cliSubcommandHandled) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
   "description": "Tailscale MCP server: admin-API tools for devices, ACLs, DNS, auth keys, users, and audit logs, plus a CLI to validate and deploy ACLs.",
   "license": "MIT",