@yawlabs/tailscale-mcp 0.19.1 → 0.19.3

package/README.md

@@ -4,6 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/tailscale-mcp)](https://github.com/YawLabs/tailscale-mcp/stargazers)
 [![Release](https://img.shields.io/badge/release-local-blue)](./release.sh)
+[![Follow @TokenLimitNews on X](https://img.shields.io/badge/follow-%40TokenLimitNews-000000?logo=x&logoColor=white)](https://x.com/TokenLimitNews)
 
 **Ask your agent questions about your tailnet and have it act on the answers.** 97 admin-API tools + 6 optional local-CLI diagnostics + 1 always-on catalog tool + 4 resources spanning the [Tailscale v2 API](https://tailscale.com/api) — devices, ACLs, DNS, keys and trust credentials, users, invites, webhooks, log streaming, posture, services, and organization tailnets. Backed by 1100+ unit tests and an opt-in live-tailnet integration suite.
 

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.1" : 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,8 +1,8 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
-  "description": "Tailscale MCP server for managing your tailnet from AI assistants",
+  "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",
   "author": "YawLabs <contact@yaw.sh>",
   "repository": {
@@ -11,11 +11,25 @@
   },
   "keywords": [
     "tailscale",
+    "tailnet",
+    "tailscale-api",
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "ai",
+    "vpn",
     "networking",
-    "vpn"
+    "acl",
+    "dns",
+    "magicdns",
+    "auth-keys",
+    "oauth",
+    "webhooks",
+    "audit-log",
+    "gitops",
+    "claude-code",
+    "cursor",
+    "vscode"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -36,8 +50,8 @@
     "test": "npm run build && node --test-timeout=300000 --test \"dist/**/*.test.js\"",
     "test:ci": "npm run test",
     "test:coverage": "npm run build && node --test-timeout=300000 --experimental-test-coverage --test-coverage-exclude=\"**/*.test.js\" --test-coverage-exclude=\"**/dist/index.js\" --test \"dist/**/*.test.js\"",
-    "lint": "biome check src/ bin/ scripts/ build.mjs",
-    "lint:fix": "biome check --write src/ bin/ scripts/ build.mjs",
+    "lint": "node scripts/lint.mjs check src/ bin/ scripts/ build.mjs",
+    "lint:fix": "node scripts/lint.mjs check --write src/ bin/ scripts/ build.mjs",
     "check:oam": "oam check src/index.ts",
     "build:binary": "node scripts/build-binary.mjs",
     "build:binary:oam": "node scripts/build-binary-oam.mjs",
@@ -68,5 +82,6 @@
       "version": ">=22",
       "onFail": "error"
     }
-  }
+  },
+  "homepage": "https://yaw.sh/mcp-servers/tailscale-mcp/"
 }