@yawlabs/tailscale-mcp 0.13.3 → 0.15.0

package/README.md

@@ -202,6 +202,8 @@ The server checks for an API key first, then falls back to OAuth. If neither is
 
 **`TAILSCALE_REQUEST_BUDGET_MS=N`** — total wall-clock budget per request, including 429 retries and their sleeps. Default `90000` (90s). When the next retry's predicted wall time would exceed the budget, the call surfaces the 429 immediately instead of holding the line. Tune lower if your MCP client has a tighter outer timeout. 429s on non-idempotent methods (POST, PATCH) are never retried — those return immediately regardless of budget.
 
+**`TAILSCALE_RETRY_BASE_DELAY_MS=N`** — base delay for the exponential backoff between retries; attempt `N` waits `base * 2^N` (capped at 30s, plus jitter). Default `1000` (1s), so a fully-exhausted retry chain spends roughly 1s + 2s + 4s sleeping. Pairs with `TAILSCALE_REQUEST_BUDGET_MS`: lowering the budget on its own doesn't get you more retries, it just makes the default backoff exhaust the budget sooner and give up. Shrink both if you want "retry hard, fail fast". A server-supplied `Retry-After` header always wins over this value.
+
 **`TAILSCALE_EXTRA_WEBHOOK_EVENTS=eventA,eventB`** — opt-in escape hatch for webhook event types Tailscale ships after the latest release of this package. The webhook tools validate `subscriptions` against a strict static catalog so typos and stale event names fail fast with a clear error; if you need a brand-new event before the catalog catches up, list it here (comma-separated) and the schema will accept it. Please also [open an issue](https://github.com/YawLabs/tailscale-mcp/issues) so the static list catches up.
 
 **Friendlier error messages.** JSON error bodies of the form `{"message":"..."}` or `{"error":"..."}` are unwrapped before display, so you see the prose explanation instead of raw JSON. 401s still get the full multi-line auth-error formatter (with the Windows env-var hint when applicable).
@@ -221,7 +223,7 @@ Set `TAILSCALE_LOCAL_CLI=1` (in your shell or `.mcp.json` `env` block) to add fo
 
 Requirements: the `tailscale` binary must be in `PATH`. If it's installed somewhere unusual, set `TAILSCALE_BINARY` to its absolute path. The MCP server doesn't need root to run these — they're all diagnostic, not state-mutating. Operations that would need elevation (`tailscale up`, `set --advertise-routes`, `lock sign`) are deliberately not exposed.
 
-When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.10.9 ready (89 tools, local-cli=on)`.
+When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.13.3 ready (93 tools, local-cli=on)` — the 4 local CLI tools are additive on top of the default 89.
 
 ## Resources (4)
 
@@ -507,6 +509,31 @@ This shows a read-only banner in the Tailscale Admin Console pointing to your re
 - Node.js 20+ to run the server (22+ to develop — the test script passes a glob to `node --test`, supported from Node 21)
 - A Tailscale API key or OAuth client credentials
 
+## Running on oam.js (optional)
+
+[oam.js](https://oamjs.org) runs this server unmodified. Verified against oam 0.8.2: full MCP handshake, all 89 tools, all 4 resources, identical error messages, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
+
+```jsonc
+{
+  "mcpServers": {
+    "tailscale": {
+      "command": "oam",
+      "args": ["run", "/path/to/tailscale-mcp/dist/index.js"],
+      "env": { "TAILSCALE_API_KEY": "tskey-api-..." }
+    }
+  }
+}
+```
+
+**Node stays the default, deliberately.** An MCP client cold-starts this server once per session, so startup is the cost that actually gets paid, and on the machine this was measured on node won it — 437ms vs 1554ms for `oam run` over 10 warmed runs (an earlier 5-run round showed 326ms vs 427ms; the box was busy, so treat the magnitude as noisy and the direction as the finding). Preferring oam automatically would mean either a launcher that probes for it on every start — a cost paid by everyone, including the majority who do not have oam — or making oam a hard requirement. Neither is worth it to reach a runtime that is not faster here. Measure on your own hardware before concluding anything; if oam wins on yours, the config above is all you need.
+
+Two places oam *does* win for this repo, both opt-in and neither touching the npm package:
+
+- **`npm run check:oam`** — type-checks via `oam check` (tsgo, TypeScript 7 native). Measured 4015ms against 7680ms for `tsc --noEmit`, same clean result. `npx tsc --noEmit` remains the portable default.
+- **`npm run build:binary:oam`** — builds the standalone binary via `oam compile` instead of Node SEA. Measured ~57.7 MB against ~73.6 MB for the Node SEA carrier *before* its blob is injected. Writes to the same `bin/<platform>-<arch>/` path as `npm run build:binary`, so the release staging script consumes either unchanged — run one or the other. If you redistribute that binary it embeds oam's runtime, so ship oam's `LICENSE`, `NOTICE` and `THIRD_PARTY_LICENSES.md` with it.
+
+The source stays runtime-agnostic on purpose: no `oam:` imports anywhere, and tests stay on `node:test`. That is what keeps the Node fallback real rather than nominal. Note that any `oam` invocation writes a bytecode cache to `oam/` in the working directory — already in `.gitignore`.
+
 ## Contributing
 
 Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR workflow and AI-agent guidelines. Please [open an issue](https://github.com/YawLabs/tailscale-mcp/issues) to discuss before a PR for anything beyond a typo fix.

package/bin/tailscale-mcp.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Runtime launcher for @yawlabs/tailscale-mcp.
+ *
+ * Prefers the oam runtime (https://oamjs.org) and falls back to the Node
+ * process already running this file.
+ *
+ *
+ * WHY THE FALLBACK COSTS NOTHING
+ * npm has already started Node to run this launcher, so falling back is a
+ * plain `import()` of the server into THIS process: no extra spawn, no extra
+ * startup, byte-identical to invoking dist/index.js directly. Discovery is
+ * stat-only -- never a subprocess -- so the miss case stays sub-millisecond.
+ *
+ * WHAT THE OAM PATH COSTS
+ * Reaching oam through an npm `bin` means Node boots first and oam boots
+ * second, so the launcher is slower than either runtime alone. Measured on
+ * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
+ * oam 116ms, node 172ms, launcher 243ms. oam is the fastest runtime and the
+ * launcher is the slowest path -- it exists for `npx` convenience.
+ *
+ * For an MCP host config, point straight at oam and skip this file:
+ *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
+ *
+ * SELECTION
+ *   TAILSCALE_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *   TAILSCALE_MCP_RUNTIME=node   never use oam
+ *   TAILSCALE_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
+// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
+// in-process fallback must use the file:// URL. spawn() needs a real path.
+const SERVER_URL = new URL("../dist/index.js", import.meta.url);
+const SERVER_ENTRY = fileURLToPath(SERVER_URL);
+const isWin = process.platform === "win32";
+const exe = isWin ? "oam.exe" : "oam";
+
+/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
+function findOam() {
+  // 1. Explicit override wins and is never second-guessed.
+  const override = process.env.OAM_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself
+  //    usually has oam/target/release on PATH, and a build directory is the
+  //    wrong thing for a user-facing launcher to bind to: cargo replaces the
+  //    binary underneath running processes, and the dev build is not the
+  //    release the user installed. Preferring the installed copy makes the
+  //    default path "what a normal user has", and OAM_BIN remains the way to
+  //    point deliberately at a dev build.
+  //
+  //    Both forms are checked on Windows: the installer defaults to
+  //    %LOCALAPPDATA%oamin there, but oam's docs name ~/.oam/bin first and
+  //    OAM_INSTALL_DIR can pick either, so checking one silently misses a real
+  //    install.
+  const installed = [join(homedir(), ".oam", "bin", exe)];
+  if (isWin) {
+    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
+  }
+  for (const candidate of installed) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
+  //    would cost a subprocess on every launch just to decide whether to spawn.
+  const pathExt = isWin ? (process.env.PATHEXT ?? ".EXE").split(";").filter(Boolean) : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of isWin ? pathExt : [""]) {
+      const candidate = join(dir, isWin ? `oam${ext.toLowerCase()}` : "oam");
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** 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 --
+  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
+  // test file can import the module for unit tests without connecting a stdio
+  // transport. aws-mcp does exactly this. Importing the server here would leave
+  // argv[1] pointing at THIS launcher, the guard would read false, and the
+  // server would load but never serve: the MCP handshake just hangs.
+  //
+  // Point argv[1] at the server first, so the in-process path is
+  // indistinguishable from having executed the file directly. The spawn path
+  // needs no equivalent -- there argv[1] is already the server.
+  process.argv[1] = SERVER_ENTRY;
+  await import(SERVER_URL.href);
+}
+
+const mode = (process.env.TAILSCALE_MCP_RUNTIME ?? "auto").toLowerCase();
+
+if (mode === "node") {
+  await runInProcess();
+} else {
+  const oam = findOam();
+
+  if (!oam) {
+    if (mode === "oam") {
+      // Explicitly demanded, so this is a real misconfiguration. writeSync
+      // because stderr is async for TTYs/pipes on Windows and process.exit
+      // truncates pending writes.
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        "tailscale-mcp: TAILSCALE_MCP_RUNTIME=oam but no oam binary was found.\n" +
+          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use TAILSCALE_MCP_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    await runInProcess();
+  } else {
+    // `--` separates oam's own flags from the script's argv, so `tailscale-mcp
+    // --version` and any host-supplied flags survive the hop unchanged.
+    const child = spawn(oam, ["run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+      // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
+      // stdin/stdout is untouched and the host's stdin-close still reaches the
+      // server's shutdown path.
+      stdio: "inherit",
+      env: process.env,
+      windowsHide: true,
+    });
+
+    // If oam cannot be executed at all (deleted between the stat and the spawn,
+    // wrong arch, permission), fall back rather than failing the whole server.
+    // `spawned` prevents falling back AFTER the child started, which would
+    // double-start the server on the same stdio.
+    let spawned = false;
+    child.on("spawn", () => {
+      spawned = true;
+    });
+    child.on("error", (err) => {
+      if (spawned) return;
+      if (mode === "oam") {
+        process.stderr.write(`tailscale-mcp: failed to launch oam (${err.message})\n`);
+        process.exit(1);
+      }
+      void runInProcess();
+    });
+
+    // Forward termination so the server's own shutdown path runs in the child
+    // rather than the child being orphaned. No-op on Windows, harmless to add.
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+      process.on(sig, () => {
+        if (!child.killed) child.kill(sig);
+      });
+    }
+
+    child.on("exit", (code, signal) => {
+      // Mirror the child's fate: a signal death becomes 128+n so callers see a
+      // conventional shell exit status rather than a bare 0.
+      if (signal) {
+        process.exit(128 + (constants.signals[signal] ?? 15));
+      }
+      process.exit(code ?? 0);
+    });
+  }
+}

package/dist/index.js

@@ -30964,6 +30964,7 @@ var REQUEST_TIMEOUT_MS = 3e4;
 var MAX_429_RETRIES = 3;
 var DEFAULT_429_DELAY_MS = 1e3;
 var MAX_429_DELAY_MS = 3e4;
+var MAX_429_JITTER_MS = 250;
 var MAX_REQUEST_BUDGET_MS = 9e4;
 var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
 var oauthToken = null;
@@ -31115,6 +31116,12 @@ function getRequestBudgetMs() {
   const n = Number(raw);
   return Number.isInteger(n) && n > 0 ? n : MAX_REQUEST_BUDGET_MS;
 }
+function getRetryBaseDelayMs() {
+  const raw = process.env.TAILSCALE_RETRY_BASE_DELAY_MS;
+  if (!raw) return DEFAULT_429_DELAY_MS;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_429_DELAY_MS;
+}
 async function withConcurrencyLimit(fn) {
   const limit = getConcurrencyLimit();
   if (limit === 0) return fn();
@@ -31151,8 +31158,8 @@ function compute429DelayMs(retryAfter, attempt) {
       if (delta > 0) return Math.min(delta, MAX_429_DELAY_MS);
     }
   }
-  const base = Math.min(DEFAULT_429_DELAY_MS * 2 ** attempt, MAX_429_DELAY_MS);
-  return base + Math.floor(Math.random() * 250);
+  const base = Math.min(getRetryBaseDelayMs() * 2 ** attempt, MAX_429_DELAY_MS);
+  return base + Math.floor(Math.random() * Math.min(MAX_429_JITTER_MS, base));
 }
 async function executeFetch(method, url2, headers, body, timeoutMs) {
   return fetch(url2, {
@@ -31188,7 +31195,7 @@ async function apiRequest(method, path, body, options) {
     headers["Content-Type"] = options.contentType || "application/json";
     fetchBody = options.rawBody;
   } else if (body !== void 0) {
-    headers["Content-Type"] = "application/json";
+    headers["Content-Type"] = options?.contentType || "application/json";
     fetchBody = JSON.stringify(body);
   }
   const isAbsolute = path.startsWith("http://") || path.startsWith("https://");
@@ -31407,7 +31414,8 @@ function filterTools(groups, options) {
   const effectiveExplicitTools = explicitToolsAllUnknown ? null : explicitTools;
   const effectiveGroups = effectiveExplicitTools ?? profileGroups ?? null;
   const enabledGroups = effectiveGroups ? new Set(effectiveGroups) : null;
-  const unknownGroups = explicitTools ? explicitTools.filter((g) => !validNames.has(g)) : enabledGroups ? [...enabledGroups].filter((g) => !validNames.has(g)) : [];
+  const unknownGroups = explicitTools ? explicitTools.filter((g) => !validNames.has(g)) : [];
+  const unknownProfileGroups = profileGroups && !effectiveExplicitTools ? profileGroups.filter((g) => !validNames.has(g)) : [];
   const readonly2 = parseReadonlyFlag(options.readonly);
   const out = [];
   for (const [name, tools] of Object.entries(groups)) {
@@ -31418,6 +31426,7 @@ function filterTools(groups, options) {
     }
   }
   const result = { tools: out, unknownGroups };
+  if (unknownProfileGroups.length > 0) result.unknownProfileGroups = unknownProfileGroups;
   if (unknownProfile) result.unknownProfile = unknownProfile;
   if (profileGroups && !effectiveExplicitTools) result.profileGroups = profileGroups;
   if (effectiveExplicitTools) result.explicitTools = effectiveExplicitTools;
@@ -31426,138 +31435,6 @@ function filterTools(groups, options) {
   return result;
 }
 
-// src/tools/status.ts
-function composeTailnetStatusData(devicesRes, settingsRes, extras = {}) {
-  const { deviceCount: _deviceCount, settings: _settings, errors: _errors, ...safeExtras } = extras;
-  const data = {
-    ...safeExtras,
-    deviceCount: devicesRes.ok ? devicesRes.data?.devices?.length ?? null : null,
-    settings: settingsRes.ok ? settingsRes.data : null
-  };
-  const errors = {};
-  if (!devicesRes.ok) errors.devices = devicesRes.error ?? `HTTP ${devicesRes.status}`;
-  if (!settingsRes.ok) errors.settings = settingsRes.error ?? `HTTP ${settingsRes.status}`;
-  if (Object.keys(errors).length > 0) data.errors = errors;
-  return data;
-}
-var statusTools = [
-  {
-    name: "tailscale_status",
-    description: "Check that the Tailscale API connection is working. Returns your tailnet name, device count, and confirms authentication is valid. Use this to verify setup.",
-    annotations: {
-      title: "Check API status",
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({}),
-    handler: async () => {
-      const [devicesRes, settingsRes] = await Promise.all([
-        apiGet(`/tailnet/${getTailnet()}/devices?fields=id`),
-        apiGet(`/tailnet/${getTailnet()}/settings`)
-      ]);
-      if (!devicesRes.ok && !settingsRes.ok) {
-        return devicesRes;
-      }
-      const data = composeTailnetStatusData(devicesRes, settingsRes, {
-        connected: true,
-        tailnet: getTailnet()
-      });
-      return { ok: true, status: 200, data };
-    }
-  }
-];
-
-// src/server-wiring.ts
-function isLocalCliEnabled(env) {
-  return env.TAILSCALE_LOCAL_CLI === "1" || env.TAILSCALE_LOCAL_CLI === "true";
-}
-function formatBannerFilterSuffix(inputs) {
-  const profileValid = !!inputs.profileEnv && !inputs.unknownProfile;
-  const profileLabel = profileValid ? inputs.explicitTools && inputs.profileWouldFilter ? `profile=${inputs.profileEnv} (overridden by TAILSCALE_TOOLS)` : `profile=${inputs.profileEnv}` : null;
-  const groupsLabel = inputs.explicitTools ? `groups=${inputs.explicitTools.join(",")}` : null;
-  return [
-    profileLabel,
-    groupsLabel,
-    inputs.readonlyMode ? "readonly" : null,
-    inputs.localCliEnabled ? "local-cli=on" : null
-  ].filter(Boolean).join(", ");
-}
-function wrapToolHandler(tool) {
-  return async (input) => {
-    try {
-      const result = await tool.handler(input);
-      const response = result;
-      if (!response.ok) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${response.error || "Unknown error"}`
-            }
-          ],
-          isError: true
-        };
-      }
-      const text = response.rawBody ?? JSON.stringify(response.data ?? { success: true }, null, 2);
-      return {
-        content: [{ type: "text", text }]
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true
-      };
-    }
-  };
-}
-async function tailnetStatusResource(uri) {
-  const [devicesRes, settingsRes] = await Promise.all([
-    apiGet(`/tailnet/${getTailnet()}/devices?fields=id`),
-    apiGet(`/tailnet/${getTailnet()}/settings`)
-  ]);
-  const data = composeTailnetStatusData(devicesRes, settingsRes, { tailnet: getTailnet() });
-  return { contents: [{ uri: uri.href, text: JSON.stringify(data, null, 2), mimeType: "application/json" }] };
-}
-async function tailnetDevicesResource(uri) {
-  const res = await apiGet(`/tailnet/${getTailnet()}/devices`);
-  const text = res.ok ? JSON.stringify(res.data, null, 2) : JSON.stringify({ error: res.error ?? `HTTP ${res.status}` }, null, 2);
-  return { contents: [{ uri: uri.href, text, mimeType: "application/json" }] };
-}
-async function tailnetAclResource(uri) {
-  const res = await apiGet(`/tailnet/${getTailnet()}/acl`, { acceptRaw: true, accept: "application/hujson" });
-  if (res.ok) {
-    return { contents: [{ uri: uri.href, text: res.rawBody ?? "", mimeType: "application/hujson" }] };
-  }
-  const lines = `Error: ${res.error ?? `HTTP ${res.status}`}`.split("\n");
-  const text = `${lines.map((l) => `// ${l}`).join("\n")}
-`;
-  return { contents: [{ uri: uri.href, text, mimeType: "application/hujson" }] };
-}
-async function tailnetDnsResource(uri) {
-  const [nameservers, searchPaths, splitDns, preferences] = await Promise.all([
-    apiGet(`/tailnet/${getTailnet()}/dns/nameservers`),
-    apiGet(`/tailnet/${getTailnet()}/dns/searchpaths`),
-    apiGet(`/tailnet/${getTailnet()}/dns/split-dns`),
-    apiGet(`/tailnet/${getTailnet()}/dns/preferences`)
-  ]);
-  const data = {
-    nameservers: nameservers.ok ? nameservers.data : null,
-    searchPaths: searchPaths.ok ? searchPaths.data : null,
-    splitDns: splitDns.ok ? splitDns.data : null,
-    preferences: preferences.ok ? preferences.data : null
-  };
-  const errors = {};
-  if (!nameservers.ok) errors.nameservers = nameservers.error ?? `HTTP ${nameservers.status}`;
-  if (!searchPaths.ok) errors.searchPaths = searchPaths.error ?? `HTTP ${searchPaths.status}`;
-  if (!splitDns.ok) errors.splitDns = splitDns.error ?? `HTTP ${splitDns.status}`;
-  if (!preferences.ok) errors.preferences = preferences.error ?? `HTTP ${preferences.status}`;
-  if (Object.keys(errors).length > 0) data.errors = errors;
-  return { contents: [{ uri: uri.href, text: JSON.stringify(data, null, 2), mimeType: "application/json" }] };
-}
-
 // src/tools/acl.ts
 var aclTools = [
   {
@@ -32758,6 +32635,13 @@ async function runTailscaleCli(args, options = {}) {
           });
           return;
         }
+        if (errno.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+          resolve({
+            ok: false,
+            error: `'${binary} ${args.join(" ")}' exceeded the ${MAX_BUFFER_BYTES / 1024 / 1024} MB output limit and was aborted -- no output was captured. This usually means a very large tailnet; narrow the query if the command supports it.`
+          });
+          return;
+        }
         if (errno.killed) {
           resolve({
             ok: false,
@@ -33343,6 +33227,49 @@ var serviceTools = [
   }
 ];
 
+// src/tools/status.ts
+function composeTailnetStatusData(devicesRes, settingsRes, extras = {}) {
+  const { deviceCount: _deviceCount, settings: _settings, errors: _errors, ...safeExtras } = extras;
+  const data = {
+    ...safeExtras,
+    deviceCount: devicesRes.ok ? devicesRes.data?.devices?.length ?? null : null,
+    settings: settingsRes.ok ? settingsRes.data : null
+  };
+  const errors = {};
+  if (!devicesRes.ok) errors.devices = devicesRes.error ?? `HTTP ${devicesRes.status}`;
+  if (!settingsRes.ok) errors.settings = settingsRes.error ?? `HTTP ${settingsRes.status}`;
+  if (Object.keys(errors).length > 0) data.errors = errors;
+  return data;
+}
+var statusTools = [
+  {
+    name: "tailscale_status",
+    description: "Check that the Tailscale API connection is working. Returns your tailnet name, device count, and confirms authentication is valid. Use this to verify setup.",
+    annotations: {
+      title: "Check API status",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => {
+      const [devicesRes, settingsRes] = await Promise.all([
+        apiGet(`/tailnet/${getTailnet()}/devices?fields=id`),
+        apiGet(`/tailnet/${getTailnet()}/settings`)
+      ]);
+      if (!devicesRes.ok && !settingsRes.ok) {
+        return devicesRes;
+      }
+      const data = composeTailnetStatusData(devicesRes, settingsRes, {
+        connected: true,
+        tailnet: getTailnet()
+      });
+      return { ok: true, status: 200, data };
+    }
+  }
+];
+
 // src/tools/tailnet.ts
 var tailnetTools = [
   {
@@ -33786,8 +33713,118 @@ var webhookTools = [
   }
 ];
 
+// src/server-wiring.ts
+function isLocalCliEnabled(env) {
+  return env.TAILSCALE_LOCAL_CLI === "1" || env.TAILSCALE_LOCAL_CLI === "true";
+}
+function buildToolGroups(env) {
+  const toolGroups = {
+    status: statusTools,
+    devices: deviceTools,
+    acl: aclTools,
+    dns: dnsTools,
+    keys: keyTools,
+    users: userTools,
+    tailnet: tailnetTools,
+    webhooks: webhookTools,
+    posture: postureTools,
+    audit: auditTools,
+    invites: inviteTools,
+    services: serviceTools,
+    "log-streaming": logStreamingTools
+  };
+  if (isLocalCliEnabled(env)) {
+    toolGroups["local-cli"] = localCliTools;
+  }
+  return toolGroups;
+}
+function formatBannerFilterSuffix(inputs) {
+  const profileValid = !!inputs.profileEnv && !inputs.unknownProfile;
+  const profileLabel = profileValid ? inputs.explicitTools && inputs.profileWouldFilter ? `profile=${inputs.profileEnv} (overridden by TAILSCALE_TOOLS)` : `profile=${inputs.profileEnv}` : null;
+  const groupsLabel = inputs.explicitTools ? `groups=${inputs.explicitTools.join(",")}` : null;
+  return [
+    profileLabel,
+    groupsLabel,
+    inputs.readonlyMode ? "readonly" : null,
+    inputs.localCliEnabled ? "local-cli=on" : null
+  ].filter(Boolean).join(", ");
+}
+function wrapToolHandler(tool) {
+  return async (input) => {
+    try {
+      const result = await tool.handler(input);
+      const response = result;
+      if (!response.ok) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${response.error || "Unknown error"}`
+            }
+          ],
+          isError: true
+        };
+      }
+      const text = response.rawBody ?? JSON.stringify(response.data ?? { success: true }, null, 2);
+      return {
+        content: [{ type: "text", text }]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true
+      };
+    }
+  };
+}
+async function tailnetStatusResource(uri) {
+  const [devicesRes, settingsRes] = await Promise.all([
+    apiGet(`/tailnet/${getTailnet()}/devices?fields=id`),
+    apiGet(`/tailnet/${getTailnet()}/settings`)
+  ]);
+  const data = composeTailnetStatusData(devicesRes, settingsRes, { tailnet: getTailnet() });
+  return { contents: [{ uri: uri.href, text: JSON.stringify(data, null, 2), mimeType: "application/json" }] };
+}
+async function tailnetDevicesResource(uri) {
+  const res = await apiGet(`/tailnet/${getTailnet()}/devices`);
+  const text = res.ok ? JSON.stringify(res.data, null, 2) : JSON.stringify({ error: res.error ?? `HTTP ${res.status}` }, null, 2);
+  return { contents: [{ uri: uri.href, text, mimeType: "application/json" }] };
+}
+async function tailnetAclResource(uri) {
+  const res = await apiGet(`/tailnet/${getTailnet()}/acl`, { acceptRaw: true, accept: "application/hujson" });
+  if (res.ok) {
+    return { contents: [{ uri: uri.href, text: res.rawBody ?? "", mimeType: "application/hujson" }] };
+  }
+  const lines = `Error: ${res.error ?? `HTTP ${res.status}`}`.split("\n");
+  const text = `${lines.map((l) => `// ${l}`).join("\n")}
+`;
+  return { contents: [{ uri: uri.href, text, mimeType: "application/hujson" }] };
+}
+async function tailnetDnsResource(uri) {
+  const [nameservers, searchPaths, splitDns, preferences] = await Promise.all([
+    apiGet(`/tailnet/${getTailnet()}/dns/nameservers`),
+    apiGet(`/tailnet/${getTailnet()}/dns/searchpaths`),
+    apiGet(`/tailnet/${getTailnet()}/dns/split-dns`),
+    apiGet(`/tailnet/${getTailnet()}/dns/preferences`)
+  ]);
+  const data = {
+    nameservers: nameservers.ok ? nameservers.data : null,
+    searchPaths: searchPaths.ok ? searchPaths.data : null,
+    splitDns: splitDns.ok ? splitDns.data : null,
+    preferences: preferences.ok ? preferences.data : null
+  };
+  const errors = {};
+  if (!nameservers.ok) errors.nameservers = nameservers.error ?? `HTTP ${nameservers.status}`;
+  if (!searchPaths.ok) errors.searchPaths = searchPaths.error ?? `HTTP ${searchPaths.status}`;
+  if (!splitDns.ok) errors.splitDns = splitDns.error ?? `HTTP ${splitDns.status}`;
+  if (!preferences.ok) errors.preferences = preferences.error ?? `HTTP ${preferences.status}`;
+  if (Object.keys(errors).length > 0) data.errors = errors;
+  return { contents: [{ uri: uri.href, text: JSON.stringify(data, null, 2), mimeType: "application/json" }] };
+}
+
 // src/index.ts
-var version2 = true ? "0.13.3" : resolveVersionFallback();
+var version2 = true ? "0.15.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
 var cliSubcommandHandled = false;
 if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
@@ -33811,28 +33848,12 @@ if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
   );
 }
 if (!cliSubcommandHandled) {
-  const toolGroups = {
-    status: statusTools,
-    devices: deviceTools,
-    acl: aclTools,
-    dns: dnsTools,
-    keys: keyTools,
-    users: userTools,
-    tailnet: tailnetTools,
-    webhooks: webhookTools,
-    posture: postureTools,
-    audit: auditTools,
-    invites: inviteTools,
-    services: serviceTools,
-    "log-streaming": logStreamingTools
-  };
   const localCliEnabled = isLocalCliEnabled(process.env);
-  if (localCliEnabled) {
-    toolGroups["local-cli"] = localCliTools;
-  }
+  const toolGroups = buildToolGroups(process.env);
   const {
     tools: allTools,
     unknownGroups,
+    unknownProfileGroups,
     unknownProfile,
     explicitTools,
     profileWouldFilter,
@@ -33849,6 +33870,11 @@ if (!cliSubcommandHandled) {
       `@yawlabs/tailscale-mcp: TAILSCALE_TOOLS includes unknown group(s): ${unknownGroups.join(", ")}. Valid groups: ${validNames.join(", ")}.${fallbackNote}`
     );
   }
+  if (unknownProfileGroups && unknownProfileGroups.length > 0) {
+    console.error(
+      `@yawlabs/tailscale-mcp: internal inconsistency -- TAILSCALE_PROFILE="${process.env.TAILSCALE_PROFILE}" references group(s) that are not registered: ${unknownProfileGroups.join(", ")}. Those groups contributed no tools. This is a bug in @yawlabs/tailscale-mcp, not your configuration -- please report it at https://github.com/YawLabs/tailscale-mcp/issues.`
+    );
+  }
   if (unknownProfile) {
     console.error(
       `@yawlabs/tailscale-mcp: TAILSCALE_PROFILE="${unknownProfile}" is not a known profile. Valid profiles: minimal, core, full. Falling back to no profile filter.`
@@ -33916,4 +33942,3 @@ if (!cliSubcommandHandled) {
     );
   }
 }
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.13.3",
+  "version": "0.15.0",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",
@@ -20,9 +20,10 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "tailscale-mcp": "dist/index.js"
+    "tailscale-mcp": "bin/tailscale-mcp.mjs"
   },
   "files": [
+    "bin/tailscale-mcp.mjs",
     "dist/index.js",
     "LICENSE",
     "README.md"
@@ -36,6 +37,9 @@
     "test:ci": "npm run test",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
+    "check:oam": "oam check src/index.ts",
+    "build:binary": "node scripts/build-binary.mjs",
+    "build:binary:oam": "node scripts/build-binary-oam.mjs",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "overrides": {