@yawlabs/tailscale-mcp 0.21.2 → 0.22.0

package/dist/index.js

@@ -31350,9 +31350,6 @@ var StdioServerTransport = class {
   }
 };
 
-// src/cli.ts
-import { readFileSync } from "node:fs";
-
 // src/api.ts
 var BASE_URL = "https://api.tailscale.com/api/v2";
 var REQUEST_TIMEOUT_MS = 3e4;
@@ -31390,17 +31387,27 @@ function getAuthConfig() {
     `No Tailscale credentials configured. Set TAILSCALE_API_KEY, or set both TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET.${hint}`
   );
 }
+function hasUsableCredentials() {
+  try {
+    getAuthConfig();
+    return true;
+  } catch {
+    return false;
+  }
+}
 function getOAuthTailnet() {
   const raw = process.env.TAILSCALE_OAUTH_TAILNET?.trim();
   return raw ? raw : void 0;
 }
-async function getOAuthAccessToken(clientId, clientSecret) {
+var OAUTH_FALLBACK_EXPIRES_IN_SEC = 300;
+async function getOAuthAccessToken(clientId, clientSecret, timeoutMs = REQUEST_TIMEOUT_MS) {
   if (oauthToken && Date.now() < oauthToken.expires_at - 6e4) {
     return oauthToken.access_token;
   }
   if (oauthRefreshPromise) {
     return oauthRefreshPromise;
   }
+  const exchangeTimeoutMs = Math.min(REQUEST_TIMEOUT_MS, Math.max(1, timeoutMs));
   oauthRefreshPromise = (async () => {
     try {
       const oauthTailnet = getOAuthTailnet();
@@ -31413,7 +31420,7 @@ async function getOAuthAccessToken(clientId, clientSecret) {
           client_secret: clientSecret,
           grant_type: "client_credentials"
         }),
-        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        signal: AbortSignal.timeout(exchangeTimeoutMs)
       });
       if (!res.ok) {
         const body = await res.text();
@@ -31421,9 +31428,13 @@ async function getOAuthAccessToken(clientId, clientSecret) {
         throw new Error(`OAuth token exchange failed (${res.status}): ${body}.${guidance}`);
       }
       const data = await res.json();
+      if (typeof data.access_token !== "string" || data.access_token === "") {
+        throw new Error("OAuth token exchange succeeded but the response carried no access_token.");
+      }
+      const expiresInSec = typeof data.expires_in === "number" && Number.isFinite(data.expires_in) ? data.expires_in : OAUTH_FALLBACK_EXPIRES_IN_SEC;
       oauthToken = {
         access_token: data.access_token,
-        expires_at: Date.now() + data.expires_in * 1e3
+        expires_at: Date.now() + expiresInSec * 1e3
       };
       return oauthToken.access_token;
     } finally {
@@ -31437,12 +31448,12 @@ function invalidateOAuthTokenOnUnauthorized(authorizationHeader) {
   if (authorizationHeader !== `Bearer ${oauthToken.access_token}`) return;
   oauthToken = null;
 }
-async function getAuthHeader() {
+async function getAuthHeader(timeoutMs = REQUEST_TIMEOUT_MS) {
   const config2 = getAuthConfig();
   if (config2.kind === "apiKey") {
     return `Basic ${Buffer.from(`${config2.apiKey}:`).toString("base64")}`;
   }
-  const token = await getOAuthAccessToken(config2.clientId, config2.clientSecret);
+  const token = await getOAuthAccessToken(config2.clientId, config2.clientSecret, timeoutMs);
   return `Bearer ${token}`;
 }
 function getTailnet() {
@@ -31662,11 +31673,22 @@ async function executeFetch(method, url2, headers, body, timeoutMs) {
     signal: AbortSignal.timeout(timeoutMs)
   });
 }
+var UNDICI_TIMEOUT_PHASES = {
+  UND_ERR_CONNECT_TIMEOUT: "while connecting",
+  UND_ERR_HEADERS_TIMEOUT: "waiting for the response headers",
+  UND_ERR_BODY_TIMEOUT: "reading the response body"
+};
+function undiciTimeoutPhase(err) {
+  const code = err?.cause?.code;
+  return typeof code === "string" ? UNDICI_TIMEOUT_PHASES[code] ?? null : null;
+}
 function describeTransportError(err, method, attemptTimeoutMs) {
   if (err instanceof Error) {
     if (err.name === "TimeoutError" || err.name === "AbortError") {
       return `${method} request timed out after ${attemptTimeoutMs}ms`;
     }
+    const phase = undiciTimeoutPhase(err);
+    if (phase) return `${method} request timed out ${phase}`;
     const cause = err.cause;
     if (cause instanceof Error && cause.message) {
       return `${method} request failed: ${err.message} (${cause.message})`;
@@ -31685,7 +31707,8 @@ function describeBudgetExhaustion(budgetMs, queuedForMs, lastTransportError) {
   return `Request budget of ${budgetMs}ms exhausted before attempt could begin.`;
 }
 function annotateAmbiguousDelete(error51, status, method, priorGatewayStatus, priorTransportError) {
-  if (status !== 404 || method.toUpperCase() !== "DELETE") return error51;
+  if (status !== 404 && status !== 0) return error51;
+  if (method.toUpperCase() !== "DELETE") return error51;
   const causes = [];
   if (priorGatewayStatus !== void 0) causes.push(`returned HTTP ${priorGatewayStatus}`);
   if (priorTransportError !== void 0) causes.push(`never returned a response (${priorTransportError})`);
@@ -31693,6 +31716,11 @@ function annotateAmbiguousDelete(error51, status, method, priorGatewayStatus, pr
   const subject = causes.length > 1 ? "earlier attempts" : "an earlier attempt";
   return `${error51 || `HTTP ${status}`} (${subject} ${causes.join(" and ")}; the delete may already have succeeded)`;
 }
+function annotateTransportFailure(error51, method, priorGatewayStatus, priorTransportError) {
+  if (method.toUpperCase() !== "DELETE") return error51;
+  if (priorGatewayStatus === void 0 && priorTransportError === void 0) return error51;
+  return annotateAmbiguousDelete(error51, 0, method, priorGatewayStatus, priorTransportError);
+}
 async function apiRequest(method, path, body, options) {
   const headers = {};
   if (options?.accept) {
@@ -31723,11 +31751,14 @@ async function apiRequest(method, path, body, options) {
   const isRetryable = RETRYABLE_METHODS.has(method.toUpperCase());
   const requestBudgetMs = getRequestBudgetMs();
   return withConcurrencyLimit(async (queuedForMs) => {
-    headers.Authorization = await getAuthHeader();
+    const authTimeoutMs = Math.min(REQUEST_TIMEOUT_MS, requestBudgetMs - (Date.now() - startedAt));
+    headers.Authorization = await getAuthHeader(authTimeoutMs);
     let res;
     let lastTransportError;
     let priorGatewayStatus;
     let priorTransportError;
+    let priorRateLimited = false;
+    const withRateLimitNote = (error51) => priorRateLimited ? `${error51} (an earlier attempt was rate-limited: HTTP 429)` : error51;
     let budgetMs = requestBudgetMs;
     for (let attempt = 0; attempt <= MAX_429_RETRIES; attempt++) {
       const remaining = budgetMs - (Date.now() - startedAt);
@@ -31735,7 +31766,14 @@ async function apiRequest(method, path, body, options) {
         return {
           ok: false,
           status: 0,
-          error: describeBudgetExhaustion(budgetMs, queuedForMs, lastTransportError)
+          error: withRateLimitNote(
+            annotateTransportFailure(
+              describeBudgetExhaustion(budgetMs, queuedForMs, lastTransportError),
+              method,
+              priorGatewayStatus,
+              priorTransportError
+            )
+          )
         };
       }
       const attemptTimeoutMs = Math.min(REQUEST_TIMEOUT_MS, remaining);
@@ -31747,12 +31785,27 @@ async function apiRequest(method, path, body, options) {
         const desc = describeTransportError(err, method, attemptTimeoutMs);
         lastTransportError = desc;
         if (!isRetryable || attempt === MAX_429_RETRIES) {
-          return { ok: false, status: 0, error: desc };
+          return {
+            ok: false,
+            status: 0,
+            error: withRateLimitNote(annotateTransportFailure(desc, method, priorGatewayStatus, priorTransportError))
+          };
         }
         const delay2 = compute429DelayMs(null, attempt);
         const elapsed3 = Date.now() - startedAt;
         if (budgetMs - elapsed3 - delay2 <= 0) {
-          return { ok: false, status: 0, error: `${desc}; request budget exhausted before retry.` };
+          return {
+            ok: false,
+            status: 0,
+            error: withRateLimitNote(
+              annotateTransportFailure(
+                `${desc}; request budget exhausted before retry.`,
+                method,
+                priorGatewayStatus,
+                priorTransportError
+              )
+            )
+          };
         }
         debugLog(
           `  -> transport error (attempt ${attempt + 1}/${MAX_429_RETRIES + 1}): ${desc}, retrying in ${delay2}ms`
@@ -31776,7 +31829,9 @@ async function apiRequest(method, path, body, options) {
         break;
       }
       debugLog(`  -> ${res.status} (attempt ${attempt + 1}/${MAX_429_RETRIES + 1}), retrying in ${delay}ms`);
-      if (res.status !== 429) {
+      if (res.status === 429) {
+        priorRateLimited = true;
+      } else {
         priorGatewayStatus = res.status;
         budgetMs = retryCeilingMs;
       }
@@ -31818,13 +31873,17 @@ async function apiRequest(method, path, body, options) {
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return { ok: true, status: response.status, etag };
       }
-      const data = await response.json();
+      const text = await response.text();
+      if (text.trim() === "") {
+        return { ok: true, status: response.status, etag };
+      }
+      const data = JSON.parse(text);
       return { ok: true, status: response.status, data, etag };
     } catch (err) {
       return {
         ok: false,
         status: response.status,
-        error: `Failed to read response body from ${method} ${url2} (HTTP ${response.status}): ${err instanceof Error ? err.message : String(err)}`,
+        error: `Failed to read response body from ${method} ${url2} (HTTP ${response.status}): ${undiciTimeoutPhase(err) ? `timed out ${undiciTimeoutPhase(err)}` : err instanceof Error ? err.message : String(err)}`,
         etag
       };
     }
@@ -31847,6 +31906,7 @@ async function apiDelete(path, options) {
 }
 
 // src/cli.ts
+import { readFileSync } from "node:fs";
 function isWarningsOnly(message, data) {
   if (!/^warning/i.test(message)) return false;
   if (!Array.isArray(data) || data.length === 0) return false;
@@ -31880,13 +31940,22 @@ function parseValidationError(rawBody) {
     ...details ? { details } : {}
   };
 }
+var CliFailure = class extends Error {
+  constructor() {
+    super("CLI failure reported on stderr");
+    this.name = "CliFailure";
+  }
+};
 function readPolicyFile(filePath) {
   try {
     const text = readFileSync(filePath, "utf-8");
     return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
   } catch (err) {
-    console.error(`Failed to read ${filePath}: ${err instanceof Error ? err.message : err}`);
-    process.exit(1);
+    const denied = err?.code === "ERR_ACCESS_DENIED";
+    const hint = denied ? " -- file access is denied by the tailscale-mcp permission sandbox; run this command with the sandbox off (README: Sandboxing)" : "";
+    console.error(`Failed to read ${filePath}: ${err instanceof Error ? err.message : err}${hint}`);
+    process.exitCode = 1;
+    throw new CliFailure();
   }
 }
 async function validatePolicy(policy) {
@@ -31898,13 +31967,15 @@ async function validatePolicy(policy) {
   });
   if (!validateRes.ok) {
     console.error(`ACL validation failed: ${validateRes.error}`);
-    process.exit(1);
+    process.exitCode = 1;
+    throw new CliFailure();
   }
   const validation = parseValidationError(validateRes.rawBody);
   if (validation.kind !== "valid") {
     console.error(`ACL validation failed: ${validation.message}${validation.details ? `
 ${validation.details}` : ""}`);
-    process.exit(1);
+    process.exitCode = 1;
+    throw new CliFailure();
   }
 }
 async function validateAcl(filePath) {
@@ -31914,12 +31985,13 @@ async function validateAcl(filePath) {
 }
 async function deployAcl(filePath) {
   const policy = readPolicyFile(filePath);
+  await validatePolicy(policy);
   const getRes = await apiGet(`/tailnet/${getTailnet()}/acl`, { acceptRaw: true, accept: "application/hujson" });
   if (!getRes.ok || !getRes.etag) {
     console.error(`Failed to get current ACL: ${getRes.error || "no ETag returned"}`);
-    process.exit(1);
+    process.exitCode = 1;
+    throw new CliFailure();
   }
-  await validatePolicy(policy);
   const deployRes = await apiPost(`/tailnet/${getTailnet()}/acl`, void 0, {
     rawBody: policy,
     contentType: "application/hujson",
@@ -31935,7 +32007,8 @@ async function deployAcl(filePath) {
     } else {
       console.error(`ACL deploy failed: ${deployRes.error}`);
     }
-    process.exit(1);
+    process.exitCode = 1;
+    throw new CliFailure();
   }
   console.log("ACL deployed successfully");
 }
@@ -32055,13 +32128,13 @@ async function previewAccess(policy, principal) {
   }
   return {
     ok: true,
-    access: accessSet(parsed.matches, parsed.postures, false),
     hasPostureDefs: !!parsed.postures,
     matches: parsed.matches,
     postureDefs: parsed.postures
   };
 }
 var ETAG_FOOTER_MARKER = "// ETag: ";
+var NO_ETAG_MARKER = "// WARNING: the API returned no ETag";
 function stripEtagFooter(body) {
   const lines = body.split("\n");
   let cut = lines.length;
@@ -32069,7 +32142,7 @@ function stripEtagFooter(body) {
     const line = lines[i].trim();
     if (line === "") continue;
     if (!line.startsWith("//")) break;
-    if (line.startsWith(ETAG_FOOTER_MARKER)) cut = i;
+    if (line.startsWith(ETAG_FOOTER_MARKER) || line.startsWith(NO_ETAG_MARKER)) cut = i;
   }
   return lines.slice(0, cut).join("\n");
 }
@@ -32087,7 +32160,7 @@ function normalizeIfMatch(etag) {
 var aclTools = [
   {
     name: "tailscale_get_acl",
-    description: "Get the current ACL policy for your tailnet. Returns the raw policy text with original formatting preserved, including comments and trailing commas (HuJSON). Also returns an ETag \u2014 you must pass it to tailscale_update_acl to safely update the policy.",
+    description: "Get the current ACL policy for your tailnet. Returns the raw policy text with original formatting preserved, including comments and trailing commas (HuJSON). Also returns an ETag -- you must pass it to tailscale_update_acl to safely update the policy.",
     annotations: {
       title: "Get ACL policy",
       readOnlyHint: true,
@@ -32106,11 +32179,20 @@ var aclTools = [
           "",
           `${ETAG_FOOTER_MARKER}${res.etag}`,
           "// Pass this ETag to tailscale_update_acl when updating the policy.",
-          "// (HuJSON treats // as a comment \u2014 safe to leave in or strip before re-submitting.)",
+          "// (HuJSON treats // as a comment -- safe to leave in or strip before re-submitting.)",
           ""
         ].join("\n");
         return { ...res, rawBody: `${stripEtagFooter(res.rawBody ?? "")}${footer}` };
       }
+      if (res.ok) {
+        const warning = [
+          "",
+          `${NO_ETAG_MARKER} for this policy, so there is none to pass to`,
+          "// tailscale_update_acl. Call tailscale_get_acl again before updating.",
+          ""
+        ].join("\n");
+        return { ...res, rawBody: `${stripEtagFooter(res.rawBody ?? "")}${warning}` };
+      }
       return res;
     }
   },
@@ -32147,9 +32229,12 @@ var aclTools = [
     // this is the code that builds the header, and because the handlers are what
     // the tests call directly -- a transform on the schema would be invisible to
     // every assertion made at the header.
+    // The get_acl footer is stripped before the POST: it is inert HuJSON, but left
+    // in it would store a comment naming an ETag that stops matching on this very
+    // write, and diff_acl_access would compare against that decorated baseline.
     handler: async (input) => {
       return apiPost(`/tailnet/${getTailnet()}/acl`, void 0, {
-        rawBody: input.policy,
+        rawBody: stripEtagFooter(input.policy),
         contentType: "application/hujson",
         ifMatch: normalizeIfMatch(input.etag),
         acceptRaw: true,
@@ -32213,7 +32298,7 @@ var aclTools = [
   },
   {
     name: "tailscale_diff_acl_access",
-    description: "Answer 'who loses access?' before applying an ACL change. Compares the CURRENT policy against a proposed one and reports, per user, which destinations they gain and lose. Run this before tailscale_update_acl -- validate_acl only checks syntax and the policy's own tests block, so a policy with no tests validates clean while revoking everyone. LIMITS, all reported in the response rather than left to be discovered. It compares USER principals only, so a revocation that runs through a tag or group can show a clean diff, and an empty result is never proof a change is safe. Posture DEFINITION changes ARE detected: posture names are resolved to their rules, so tightening `posture:corp` shows as a change -- except when a preview omits the definitions map, where it falls back to comparing names. It costs two preview requests per user, so it checks the first 25 by default and stops after 60 seconds regardless; either way it sets `truncated`, reports how many were skipped, and says which limit stopped it. Users whose preview fails are listed in `failed` and excluded from the compared count -- a failure is never reported as lost access, and if nothing could be compared the call fails rather than returning an empty diff.",
+    description: "Answer 'who loses access?' before applying an ACL change. Compares the CURRENT policy against a proposed one and reports, per user, which destinations they gain and lose. Run this before tailscale_update_acl -- validate_acl only checks syntax and the policy's own tests block, so a policy with no tests validates clean while revoking everyone. LIMITS, all reported in the response rather than left to be discovered. It compares USER principals only, so a revocation that runs through a tag or group can show a clean diff, and an empty result is never proof a change is safe. Posture DEFINITION changes ARE detected: posture names are resolved to their rules, so tightening `posture:corp` shows as a change -- except when a preview omits the definitions map, where it falls back to comparing names. It costs two preview requests per user, so it checks the first 25 by default and stops starting new users after 60 seconds (a user whose previews are already in flight still finishes); either way it sets `truncated`, reports how many were skipped, and says which limit stopped it. Users whose preview fails are listed in `failed` and excluded from the compared count -- a failure is never reported as lost access, and if nothing could be compared the call fails rather than returning an empty diff.",
     annotations: {
       title: "Diff ACL access",
       readOnlyHint: true,
@@ -32370,7 +32455,9 @@ var aclTools = [
 // src/tools/audit.ts
 function assertRFC3339(value, label) {
   const rfc3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
-  const err = () => new Error(`${label} must be a valid RFC3339 date-time (e.g. '2026-04-01T00:00:00Z'), got: '${value}'`);
+  const err = () => new Error(
+    `${label} must be a valid RFC3339 date-time with an uppercase 'T' and 'Z' (e.g. '2026-04-01T00:00:00Z'), got: '${value}'`
+  );
   if (!rfc3339.test(value) || Number.isNaN(Date.parse(value))) {
     throw err();
   }
@@ -32454,7 +32541,7 @@ var auditTools = [
   },
   {
     name: "tailscale_get_network_flow_logs",
-    description: "Get network traffic flow logs showing connections between devices. Shows source/destination nodes, timestamps, and traffic metadata \u2014 useful for security monitoring and debugging connectivity.",
+    description: "Get network traffic flow logs showing connections between devices. Shows source/destination nodes, timestamps, and traffic metadata -- useful for security monitoring and debugging connectivity.",
     annotations: {
       title: "Get network flow logs",
       readOnlyHint: true,
@@ -32491,7 +32578,7 @@ function isCidr(s) {
   if (!/^\d+$/.test(prefix)) return false;
   const prefixN = Number(prefix);
   if (net.isIPv4(addr)) return prefixN <= 32;
-  if (net.isIPv6(addr)) return prefixN <= 128;
+  if (net.isIPv6(addr)) return !addr.includes("%") && prefixN <= 128;
   return false;
 }
 var DEVICE_FIELDS_DESC = "Which device fields to return. Tailscale documents exactly two values. 'default' (also what you get when this is omitted) is the limited set: addresses, id, nodeId, user, name, hostname, clientVersion, updateAvailable, os, created, connectedToControl, lastSeen, keyExpiryDisabled, expires, authorized, isExternal, machineKey, nodeKey, blocksIncomingConnections, tailnetLockKey, tailnetLockError, tags, isEphemeral. 'all' adds advertisedRoutes, enabledRoutes, clientConnectivity (endpoints, DERP latency), sshEnabled, distro, multipleConnections and postureIdentity (serial numbers and, where a posture integration collects them, hardware/MAC addresses). Omitting it does NOT return everything.";
@@ -32587,7 +32674,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_delete_device",
-    description: "Permanently remove a device from the tailnet. This is irreversible \u2014 the device must re-authenticate to rejoin.",
+    description: "Permanently remove a device from the tailnet. This is irreversible -- the device must re-authenticate to rejoin.",
     annotations: {
       title: "Delete device",
       readOnlyHint: false,
@@ -32596,7 +32683,10 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe(`The device ID to delete. ${DEVICE_ID_HINT}`)
+      // `.trim().min(1)`, not a bare string: a whitespace-only device id encodes
+      // to "%20" and this irreversible delete returns a 404 that reads like the
+      // device is already gone (rationale: tailnets.ts delete_tailnet).
+      deviceId: external_exports.string().trim().min(1).describe(`The device ID to delete. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiDelete(`/device/${encPath(input.deviceId)}`);
@@ -32658,7 +32748,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_set_device_routes",
-    description: "Set the enabled subnet routes for a device. Replaces all currently enabled routes \u2014 pass the full list of routes you want enabled.",
+    description: "Set the enabled subnet routes for a device. Replaces all currently enabled routes -- pass the full list of routes you want enabled.",
     annotations: {
       title: "Set device routes",
       readOnlyHint: false,
@@ -32756,7 +32846,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_set_device_tags",
-    description: "Set ACL tags on a device. Replaces all existing tags \u2014 pass the full list of tags you want applied.",
+    description: "Set ACL tags on a device. Replaces all existing tags -- pass the full list of tags you want applied.",
     annotations: {
       title: "Set device tags",
       readOnlyHint: false,
@@ -32815,7 +32905,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_set_devices_authorized",
-    description: "Authorize or deauthorize multiple devices in one call. Each device's POST runs in parallel; per-device errors are returned alongside the successes so a partial failure doesn't lose the work that succeeded. On partial failure the call still returns success (ok) with data: { authorized, succeeded, failed } -- inspect data.failed for the per-device errors. Common use: authorize a batch of newly-enrolled CI hosts, or deauthorize a group of devices flagged by a security review.",
+    description: "Authorize or deauthorize multiple devices in one call. Each device's POST runs in parallel; per-device errors are returned alongside the successes so a partial failure doesn't lose the work that succeeded. On partial failure the call still returns success (ok) with data: { authorized, succeeded, failed } -- inspect data.failed for the per-device errors. POSTs are never retried, so on a large batch a rate-limited device lands in data.failed with status 429: re-call with just those ids, or set TAILSCALE_MAX_CONCURRENT to cap requests in flight. Common use: authorize a batch of newly-enrolled CI hosts, or deauthorize a group of devices flagged by a security review.",
     annotations: {
       title: "Set devices authorized (bulk)",
       readOnlyHint: false,
@@ -32857,7 +32947,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_batch_update_posture_attributes",
-    description: "Batch update custom posture attributes across multiple devices. Each attribute key must start with 'custom:'. Uses JSON Merge Patch semantics \u2014 pass null as the attribute config to delete.",
+    description: "Batch update custom posture attributes across multiple devices. Each attribute key must start with 'custom:'. Uses JSON Merge Patch semantics -- pass null as the attribute config to delete.",
     annotations: {
       title: "Batch update posture attributes",
       readOnlyHint: false,
@@ -33085,7 +33175,7 @@ var dnsTools = [
   },
   {
     name: "tailscale_set_dns_configuration",
-    description: "Set the unified DNS configuration for your tailnet in a single call. Replaces all DNS settings (nameservers, search paths, split DNS, MagicDNS preference).",
+    description: "Set the unified DNS configuration for your tailnet in a single call. Replaces all DNS settings (nameservers, search paths, split DNS, MagicDNS preference). This is a replace-all endpoint: pass every top-level field you want to keep, because a field you omit may be cleared rather than left alone.",
     annotations: {
       title: "Set DNS configuration (unified)",
       readOnlyHint: false,
@@ -33098,9 +33188,16 @@ var dnsTools = [
     inputSchema: external_exports.object({
       dns: external_exports.array(external_exports.string()).optional().describe("List of DNS server IP addresses"),
       searchPaths: external_exports.array(external_exports.string()).optional().describe("List of DNS search domains"),
-      splitDns: external_exports.record(external_exports.string(), external_exports.array(external_exports.string())).optional().describe("Map of domain to nameserver list for split DNS"),
+      // `.nullable()` to match the PUT/PATCH split-dns siblings above: the
+      // spec's SplitDns schema types each value as an array OR null.
+      splitDns: external_exports.record(external_exports.string(), external_exports.array(external_exports.string()).nullable()).optional().describe("Map of domain to nameserver list for split DNS, or to null to clear that domain"),
       magicDNS: external_exports.boolean().optional().describe("Whether to enable MagicDNS")
     }),
+    // UNVERIFIED: whether an omitted top-level field is preserved or cleared by
+    // the API on a partial body has never been probed live here. The description
+    // warns the caller it MAY be cleared rather than promising a merge -- the
+    // safe reading of a replace-all endpoint -- because claiming preservation we
+    // have not observed is how a silent wipe gets shipped.
     handler: async (input) => {
       const body = {};
       for (const [key, value] of Object.entries(input)) {
@@ -33114,6 +33211,155 @@ var dnsTools = [
   }
 ];
 
+// src/tools/users.ts
+var USER_ROLES = [
+  "owner",
+  "admin",
+  "it-admin",
+  "network-admin",
+  "billing-admin",
+  "auditor",
+  "member"
+];
+var INVITABLE_ROLES = [
+  "member",
+  "admin",
+  "it-admin",
+  "network-admin",
+  "billing-admin",
+  "auditor"
+];
+var userTools = [
+  {
+    name: "tailscale_list_users",
+    description: "List all users in your tailnet.",
+    annotations: {
+      title: "List users",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      type: external_exports.enum(["member", "shared", "all"]).optional().describe("Filter by user type: 'member' (direct members), 'shared' (shared-in users), or 'all' (default)"),
+      role: external_exports.enum(USER_ROLES).optional().describe("Filter by user role")
+    }),
+    handler: async (input) => {
+      const params = new URLSearchParams();
+      if (input.type) params.set("type", input.type);
+      if (input.role) params.set("role", input.role);
+      const qs = params.toString();
+      return apiGet(`/tailnet/${getTailnet()}/users${qs ? `?${qs}` : ""}`);
+    }
+  },
+  {
+    name: "tailscale_get_user",
+    description: "Get details for a specific user.",
+    annotations: {
+      title: "Get user",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      userId: external_exports.string().describe("The user ID")
+    }),
+    handler: async (input) => {
+      return apiGet(`/users/${encPath(input.userId)}`);
+    }
+  },
+  {
+    name: "tailscale_approve_user",
+    description: "Approve a pending user, granting them access to the tailnet.",
+    annotations: {
+      title: "Approve user",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      userId: external_exports.string().describe("The user ID to approve")
+    }),
+    handler: async (input) => {
+      return apiPost(`/users/${encPath(input.userId)}/approve`);
+    }
+  },
+  {
+    name: "tailscale_suspend_user",
+    description: "Suspend a user, immediately revoking their access to the tailnet. Their devices will be disconnected. Can be reversed with tailscale_restore_user.",
+    annotations: {
+      title: "Suspend user",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      userId: external_exports.string().describe("The user ID to suspend")
+    }),
+    handler: async (input) => {
+      return apiPost(`/users/${encPath(input.userId)}/suspend`);
+    }
+  },
+  {
+    name: "tailscale_restore_user",
+    description: "Restore a previously suspended user, re-granting them access to the tailnet.",
+    annotations: {
+      title: "Restore user",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      userId: external_exports.string().describe("The user ID to restore")
+    }),
+    handler: async (input) => {
+      return apiPost(`/users/${encPath(input.userId)}/restore`);
+    }
+  },
+  {
+    name: "tailscale_update_user_role",
+    description: "Update a user's role in the tailnet.",
+    annotations: {
+      title: "Update user role",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      userId: external_exports.string().describe("The user ID"),
+      role: external_exports.enum(USER_ROLES).describe("The new role to assign")
+    }),
+    handler: async (input) => {
+      return apiPost(`/users/${encPath(input.userId)}/role`, { role: input.role });
+    }
+  },
+  {
+    name: "tailscale_delete_user",
+    description: "Delete a user from the tailnet. This is irreversible -- the user and all their devices will be removed.",
+    annotations: {
+      title: "Delete user",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      // `.trim().min(1)`, not a bare string: a whitespace-only user id encodes
+      // to "%20" and this irreversible delete returns a 404 that reads like the
+      // user is already gone (rationale: tailnets.ts delete_tailnet).
+      userId: external_exports.string().trim().min(1).describe("The user ID to delete")
+    }),
+    handler: async (input) => {
+      return apiPost(`/users/${encPath(input.userId)}/delete`);
+    }
+  }
+];
+
 // src/tools/invites.ts
 var inviteTools = [
   // --- Device Invites ---
@@ -33155,6 +33401,9 @@ var inviteTools = [
       if (input.multiUse !== void 0) body.multiUse = input.multiUse;
       if (input.allowExitNode !== void 0) body.allowExitNode = input.allowExitNode;
       if (input.email !== void 0) body.email = input.email;
+      if (Object.keys(body).length === 0) {
+        throw new Error("No fields to update. Provide at least one of: multiUse, allowExitNode, email.");
+      }
       return apiPost(`/device/${encPath(input.deviceId)}/device-invites`, body);
     }
   },
@@ -33177,7 +33426,7 @@ var inviteTools = [
   },
   {
     name: "tailscale_delete_device_invite",
-    description: "Delete a device invite. This is irreversible \u2014 the invite link will stop working.",
+    description: "Delete a device invite. This is irreversible -- the invite link will stop working.",
     annotations: {
       title: "Delete device invite",
       readOnlyHint: false,
@@ -33237,12 +33486,15 @@ var inviteTools = [
     },
     inputSchema: external_exports.object({
       email: external_exports.email().optional().describe("Email address to send the invite to"),
-      role: external_exports.enum(["member", "admin", "it-admin", "network-admin", "billing-admin", "auditor"]).optional().describe("Role to assign to the invited user (default: member)")
+      role: external_exports.enum(INVITABLE_ROLES).optional().describe("Role to assign to the invited user (default: member)")
     }),
     handler: async (input) => {
       const body = {};
       if (input.email !== void 0) body.email = input.email;
       if (input.role !== void 0) body.role = input.role;
+      if (Object.keys(body).length === 0) {
+        throw new Error("No fields to update. Provide at least one of: email, role.");
+      }
       return apiPost(`/tailnet/${getTailnet()}/user-invites`, body);
     }
   },
@@ -33265,7 +33517,7 @@ var inviteTools = [
   },
   {
     name: "tailscale_delete_user_invite",
-    description: "Delete a user invite. This is irreversible \u2014 the invite link will stop working.",
+    description: "Delete a user invite. This is irreversible -- the invite link will stop working.",
     annotations: {
       title: "Delete user invite",
       readOnlyHint: false,
@@ -33349,7 +33601,7 @@ var keyTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      keyId: external_exports.string().describe("The key ID (auth key, API access token, OAuth client, or federated identity)")
+      keyId: external_exports.string().trim().min(1).describe("The key ID (auth key, API access token, OAuth client, or federated identity)")
     }),
     handler: async (input) => {
       return apiGet(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`);
@@ -33374,7 +33626,8 @@ var keyTools = [
       reusable: external_exports.boolean().optional().describe("(auth only) Whether the key can be used more than once (default: false)"),
       ephemeral: external_exports.boolean().optional().describe("(auth only) Whether devices using this key are ephemeral (default: false)"),
       preauthorized: external_exports.boolean().optional().describe("(auth only) Whether devices are pre-authorized (default: false)"),
-      expirySeconds: external_exports.number().optional().describe("(auth only) Key expiry in seconds (default: 90 days)"),
+      // Seconds, so a fractional or non-positive value is nonsense to send.
+      expirySeconds: external_exports.number().int().positive().optional().describe("(auth only) Key expiry in seconds (default: 90 days)"),
       // Shared fields
       tags: external_exports.array(external_exports.string()).optional().describe(
         "ACL tags (must start with 'tag:'). Required for client/federated if scopes include 'devices:core' or 'auth_keys'"
@@ -33454,7 +33707,14 @@ var keyTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      keyId: external_exports.string().describe("The key ID to delete (auth key, API access token, OAuth client, or federated identity)")
+      // `.trim().min(1)`, as on tailscale_delete_oauth_app's appId below and for
+      // the reason tailnets.ts spells out on tailscale_delete_tailnet: a bare
+      // z.string() lets "" through (encPath then sends a DELETE on the keys
+      // collection path itself) and " " through as the literal segment "%20".
+      // On a read that is a wasted round-trip; on this irreversible delete it
+      // returns a 404 that reads like the key is already gone, with no retry to
+      // notice it with.
+      keyId: external_exports.string().trim().min(1).describe("The key ID to delete (auth key, API access token, OAuth client, or federated identity)")
     }),
     handler: async (input) => {
       return apiDelete(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`);
@@ -33462,7 +33722,7 @@ var keyTools = [
   },
   {
     name: "tailscale_update_key",
-    description: "Update an existing key. Supported fields depend on the key type: all key types accept 'description'; OAuth clients and federated identities additionally accept 'scopes' and 'tags'; federated identities additionally accept 'issuer', 'subject', 'audience', and 'customClaimRules'. For auth keys, pass only 'description' \u2014 the Tailscale API will reject other fields.",
+    description: "Update an existing key. Supported fields depend on the key type: all key types accept 'description'; OAuth clients and federated identities additionally accept 'scopes' and 'tags'; federated identities additionally accept 'issuer', 'subject', 'audience', and 'customClaimRules'. For auth keys, pass only 'description' -- the Tailscale API will reject other fields.",
     annotations: {
       title: "Update key",
       readOnlyHint: false,
@@ -33471,7 +33731,7 @@ var keyTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      keyId: external_exports.string().describe("The key ID to update"),
+      keyId: external_exports.string().trim().min(1).describe("The key ID to update"),
       description: external_exports.string().optional().describe("Updated description (max 50 chars, alphanumeric/hyphens/spaces)"),
       scopes: external_exports.array(external_exports.string()).optional().describe("(client/federated) Updated OAuth scopes"),
       tags: external_exports.array(external_exports.string()).optional().describe("Updated ACL tags (must start with 'tag:')"),
@@ -33615,6 +33875,10 @@ var DARWIN_CANDIDATES = [
 ];
 var LINUX_CANDIDATES = ["/usr/bin/tailscale", "/snap/bin/tailscale"];
 var execFileImpl = execFileCb;
+function describeUnexecutableBinary(binary, fromEnv) {
+  const where = fromEnv ? `'${binary}', which is where TAILSCALE_BINARY points` : `'${binary}', found in PATH`;
+  return `Found the 'tailscale' binary at ${where}, but it could not be executed (EACCES). It must be an executable file -- not a directory -- with execute permission for the user running this server. Set TAILSCALE_BINARY to the absolute path of the tailscale executable, or reinstall Tailscale (https://tailscale.com/download).`;
+}
 function binaryCandidates(platform) {
   if (platform === "darwin") return DARWIN_CANDIDATES;
   if (platform === "linux") return LINUX_CANDIDATES;
@@ -33642,7 +33906,7 @@ function readProcVersion() {
 }
 function describeMissingBinary(binary, fromEnv, platform, wsl) {
   if (fromEnv) {
-    const pathNote = platform === "win32" ? `On Windows the value must be a Windows path (C:/Program Files/Tailscale/tailscale.exe), not an MSYS one (/c/...) -- Git Bash rewrites /c/... when you type it at the prompt, but a value read from an MCP client's JSON config or a .env file arrives untranslated.` : `It must be the absolute path of an executable file -- not a directory, and not a shell alias or function.`;
+    const pathNote = platform === "win32" ? `On Windows the value must be a Windows path (C:/Program Files/Tailscale/tailscale.exe), not an MSYS one (/c/...) -- Git Bash rewrites /c/... when you type it at the prompt, but a value read from an MCP client's JSON config or a .env file arrives untranslated. It must also name tailscale.exe itself, not the folder it is in.` : `It must be the absolute path of an executable file, not a shell alias or function.`;
     return `Could not find the 'tailscale' binary at '${binary}', which is where TAILSCALE_BINARY points. PATH was never consulted, so nothing here is a PATH problem. ${pathNote}`;
   }
   if (platform === "darwin") {
@@ -33653,12 +33917,30 @@ function describeMissingBinary(binary, fromEnv, platform, wsl) {
   }
   return `Could not find the 'tailscale' binary in PATH. Install Tailscale (https://tailscale.com/download) or set TAILSCALE_BINARY to its absolute path.`;
 }
+var MAX_CLI_CONCURRENCY = 4;
+var cliInFlight = 0;
+var cliQueue = [];
+async function acquireCliSlot() {
+  if (cliInFlight < MAX_CLI_CONCURRENCY) {
+    cliInFlight++;
+    return;
+  }
+  await new Promise((resolve) => cliQueue.push(resolve));
+}
+function releaseCliSlot() {
+  const next = cliQueue.shift();
+  if (next)
+    next();
+  else cliInFlight--;
+}
 async function runTailscaleCli(args, options = {}) {
   const binary = resolveBinary();
   const fromEnv = Boolean(process.env.TAILSCALE_BINARY);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  await acquireCliSlot();
   return new Promise((resolve) => {
     execFileImpl(binary, args, { timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES }, (err, stdout, stderr) => {
+      releaseCliSlot();
       const stdoutStr = stdout == null ? "" : String(stdout);
       const stderrStr = stderr == null ? "" : String(stderr);
       if (err) {
@@ -33670,6 +33952,10 @@ async function runTailscaleCli(args, options = {}) {
           });
           return;
         }
+        if (errno.code === "EACCES") {
+          resolve({ ok: false, error: describeUnexecutableBinary(binary, fromEnv) });
+          return;
+        }
         if (errno.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
           resolve({
             ok: false,
@@ -33864,10 +34150,12 @@ var logStreamingTools = [
         apiGet(`/tailnet/${getTailnet()}/logging/configuration/stream`),
         apiGet(`/tailnet/${getTailnet()}/logging/network/stream`)
       ]);
+      const describeFailure = (r) => r.status === 404 ? "HTTP 404: not configured (Tailscale also answers 404 when this log type is unsupported or the caller cannot view it)" : r.error || `HTTP ${r.status}`;
       const errors = {};
-      if (!configuration.ok) errors.configuration = configuration.error || `HTTP ${configuration.status}`;
-      if (!network.ok) errors.network = network.error || `HTTP ${network.status}`;
-      if (!configuration.ok && !network.ok) {
+      if (!configuration.ok) errors.configuration = describeFailure(configuration);
+      if (!network.ok) errors.network = describeFailure(network);
+      const hardFail = (r) => !r.ok && r.status !== 404;
+      if (hardFail(configuration) && hardFail(network)) {
         return {
           ok: false,
           status: configuration.status || network.status || 500,
@@ -33912,7 +34200,7 @@ var logStreamingTools = [
     inputSchema: external_exports.object({
       logType: external_exports.enum(["configuration", "network"]).describe("The log type: 'configuration' for audit logs, 'network' for network flow logs"),
       destinationType: external_exports.enum(["splunk", "elastic", "panther", "cribl", "datadog", "axiom", "s3"]).describe("The log streaming destination type"),
-      url: external_exports.string().optional().describe("Destination URL (required for non-s3 destinations)"),
+      url: external_exports.string().optional().describe("Destination URL (required for non-s3 destinations; for s3, an optional S3-compatible endpoint)"),
       token: external_exports.string().optional().describe(
         "Authentication token or API key for the destination. SENSITIVE: passed straight to Tailscale and not echoed back, but MCP clients may log the input value you supply."
       ),
@@ -33939,11 +34227,19 @@ var logStreamingTools = [
         if (!input.s3Bucket) missing.push("s3Bucket");
         if (!input.s3Region) missing.push("s3Region");
         if (!input.s3AuthenticationType) missing.push("s3AuthenticationType");
+        let wrongAuthFields = [];
         if (input.s3AuthenticationType === "accesskey") {
           if (!input.s3AccessKeyId) missing.push("s3AccessKeyId");
           if (!input.s3SecretAccessKey) missing.push("s3SecretAccessKey");
+          if (input.s3RoleArn !== void 0) wrongAuthFields = ["s3RoleArn"];
         } else if (input.s3AuthenticationType === "rolearn") {
           if (!input.s3RoleArn) missing.push("s3RoleArn");
+          wrongAuthFields = ["s3AccessKeyId", "s3SecretAccessKey"].filter((f) => input[f] !== void 0);
+        }
+        if (wrongAuthFields.length > 0) {
+          throw new Error(
+            `${wrongAuthFields.join(", ")} cannot be used with s3AuthenticationType '${input.s3AuthenticationType}'.`
+          );
         }
         if (missing.length > 0) {
           throw new Error(
@@ -34036,9 +34332,11 @@ var logStreamingTools = [
     // The flag was previously never sent at all, so the server applied whatever
     // default it applies to an absent body -- undocumented either way. It now
     // goes on the wire explicitly, as the Go client always does. The default
-    // lives here rather than in a Zod `.default()` because handlers are called
-    // with the client's raw input, and `??` rather than `||` because false is a
-    // meaningful value.
+    // lives here rather than in a Zod `.default()` because the tests call the
+    // handlers directly, bypassing the schema, so a schema default would be
+    // invisible to every body assertion (in production the SDK does parse the
+    // input, so a `.default()` would apply there). `??` rather than `||`
+    // because false is a meaningful value.
     handler: async (input) => {
       return apiPost(`/tailnet/${getTailnet()}/aws-external-id`, { reusable: input?.reusable ?? true });
     }
@@ -34216,7 +34514,7 @@ var postureTools = [
 var serviceTools = [
   {
     name: "tailscale_list_services",
-    description: "List all Tailscale Services in your tailnet. Services provide stable MagicDNS names and virtual IPs, decoupled from individual devices. Note: services are created implicitly when a node first advertises one (`tailscale up --advertise-services=svc:name`); there is no API endpoint to create a service from this MCP. Use the update/delete/approval tools here once the service exists.",
+    description: "List all Tailscale Services in your tailnet. Services provide stable MagicDNS names and virtual IPs, decoupled from individual devices. Note: this MCP has no create-service tool. The API documents its Service PUT as create-or-update, but tailscale_update_service sends only the fields you pass, so do not use it to create one. Use the update/delete/approval tools here once the service exists.",
     annotations: {
       title: "List services",
       readOnlyHint: true,
@@ -34282,7 +34580,7 @@ var serviceTools = [
   },
   {
     name: "tailscale_delete_service",
-    description: "Delete a Tailscale Service. This is irreversible \u2014 the service's MagicDNS name and virtual IP will be released.",
+    description: "Delete a Tailscale Service. This is irreversible -- the service's MagicDNS name and virtual IP will be released.",
     annotations: {
       title: "Delete service",
       readOnlyHint: false,
@@ -34291,7 +34589,10 @@ var serviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      serviceName: external_exports.string().describe("The service name to delete")
+      // `.trim().min(1)`, not a bare string: a whitespace-only service name
+      // encodes to "%20" and this irreversible delete returns a 404 that reads
+      // like the service is already gone (rationale: tailnets.ts delete_tailnet).
+      serviceName: external_exports.string().trim().min(1).describe("The service name to delete")
     }),
     handler: async (input) => {
       return apiDelete(`/tailnet/${getTailnet()}/services/${encPath(input.serviceName)}`);
@@ -34372,6 +34673,12 @@ function composeTailnetStatusData(devicesRes, settingsRes, extras = {}) {
   if (Object.keys(errors).length > 0) data.errors = errors;
   return data;
 }
+function fetchTailnetStatusInputs() {
+  return Promise.all([
+    apiGet(`/tailnet/${getTailnet()}/devices?fields=default`),
+    apiGet(`/tailnet/${getTailnet()}/settings`)
+  ]);
+}
 var statusTools = [
   {
     name: "tailscale_status",
@@ -34385,10 +34692,7 @@ var statusTools = [
     },
     inputSchema: external_exports.object({}),
     handler: async () => {
-      const [devicesRes, settingsRes] = await Promise.all([
-        apiGet(`/tailnet/${getTailnet()}/devices?fields=id`),
-        apiGet(`/tailnet/${getTailnet()}/settings`)
-      ]);
+      const [devicesRes, settingsRes] = await fetchTailnetStatusInputs();
       if (!devicesRes.ok && !settingsRes.ok) {
         return devicesRes;
       }
@@ -34431,7 +34735,7 @@ var tailnetTools = [
     inputSchema: external_exports.object({
       devicesApprovalOn: external_exports.boolean().optional().describe("Whether device approval is required"),
       devicesAutoUpdatesOn: external_exports.boolean().optional().describe("Whether auto-updates are enabled"),
-      devicesKeyDurationDays: external_exports.number().optional().describe("Key expiry duration in days"),
+      devicesKeyDurationDays: external_exports.number().int().min(1).max(180).optional().describe("Key expiry duration in days (whole days, 1-180)"),
       usersApprovalOn: external_exports.boolean().optional().describe("Whether user approval is required"),
       usersRoleAllowedToJoinExternalTailnets: external_exports.enum(["none", "admin", "member"]).optional().describe("Which user roles can join external tailnets"),
       networkFlowLoggingOn: external_exports.boolean().optional().describe("Whether network flow logging is enabled"),
@@ -34499,7 +34803,7 @@ var tailnetTools = [
       const applied = {};
       const failed = {};
       for (const { contactType, res } of results) {
-        if (res.ok) applied[contactType] = res.data;
+        if (res.ok) applied[contactType] = res.data ?? { status: res.status };
         else failed[contactType] = { status: res.status, error: res.error || `HTTP ${res.status}` };
       }
       const hasFailed = Object.keys(failed).length > 0;
@@ -34635,135 +34939,6 @@ var tailnetsTools = [
   }
 ];
 
-// src/tools/users.ts
-var userTools = [
-  {
-    name: "tailscale_list_users",
-    description: "List all users in your tailnet.",
-    annotations: {
-      title: "List users",
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      type: external_exports.enum(["member", "shared", "all"]).optional().describe("Filter by user type: 'member' (direct members), 'shared' (shared-in users), or 'all' (default)"),
-      role: external_exports.enum(["owner", "admin", "it-admin", "network-admin", "billing-admin", "auditor", "member"]).optional().describe("Filter by user role")
-    }),
-    handler: async (input) => {
-      const params = new URLSearchParams();
-      if (input.type) params.set("type", input.type);
-      if (input.role) params.set("role", input.role);
-      const qs = params.toString();
-      return apiGet(`/tailnet/${getTailnet()}/users${qs ? `?${qs}` : ""}`);
-    }
-  },
-  {
-    name: "tailscale_get_user",
-    description: "Get details for a specific user.",
-    annotations: {
-      title: "Get user",
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      userId: external_exports.string().describe("The user ID")
-    }),
-    handler: async (input) => {
-      return apiGet(`/users/${encPath(input.userId)}`);
-    }
-  },
-  {
-    name: "tailscale_approve_user",
-    description: "Approve a pending user, granting them access to the tailnet.",
-    annotations: {
-      title: "Approve user",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      userId: external_exports.string().describe("The user ID to approve")
-    }),
-    handler: async (input) => {
-      return apiPost(`/users/${encPath(input.userId)}/approve`);
-    }
-  },
-  {
-    name: "tailscale_suspend_user",
-    description: "Suspend a user, immediately revoking their access to the tailnet. Their devices will be disconnected. Can be reversed with tailscale_restore_user.",
-    annotations: {
-      title: "Suspend user",
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      userId: external_exports.string().describe("The user ID to suspend")
-    }),
-    handler: async (input) => {
-      return apiPost(`/users/${encPath(input.userId)}/suspend`);
-    }
-  },
-  {
-    name: "tailscale_restore_user",
-    description: "Restore a previously suspended user, re-granting them access to the tailnet.",
-    annotations: {
-      title: "Restore user",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      userId: external_exports.string().describe("The user ID to restore")
-    }),
-    handler: async (input) => {
-      return apiPost(`/users/${encPath(input.userId)}/restore`);
-    }
-  },
-  {
-    name: "tailscale_update_user_role",
-    description: "Update a user's role in the tailnet.",
-    annotations: {
-      title: "Update user role",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      userId: external_exports.string().describe("The user ID"),
-      role: external_exports.enum(["owner", "admin", "it-admin", "network-admin", "billing-admin", "auditor", "member"]).describe("The new role to assign")
-    }),
-    handler: async (input) => {
-      return apiPost(`/users/${encPath(input.userId)}/role`, { role: input.role });
-    }
-  },
-  {
-    name: "tailscale_delete_user",
-    description: "Delete a user from the tailnet. This is irreversible \u2014 the user and all their devices will be removed.",
-    annotations: {
-      title: "Delete user",
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: true,
-      openWorldHint: true
-    },
-    inputSchema: external_exports.object({
-      userId: external_exports.string().describe("The user ID to delete")
-    }),
-    handler: async (input) => {
-      return apiPost(`/users/${encPath(input.userId)}/delete`);
-    }
-  }
-];
-
 // src/tools/webhooks.ts
 var STATIC_WEBHOOK_EVENT_TYPES = [
   "nodeCreated",
@@ -34792,7 +34967,13 @@ function getAllowedWebhookEvents() {
   const extras = raw.split(",").map((s) => s.trim()).filter(Boolean);
   return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...WEBHOOK_CATEGORY_SUBSCRIPTIONS, ...extras]);
 }
-var endpointUrlSchema = external_exports.url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://");
+var endpointUrlSchema = external_exports.url().refine((u) => {
+  try {
+    return new URL(u).protocol === "https:";
+  } catch {
+    return false;
+  }
+}, "endpointUrl must use https://");
 var webhookSubscriptionsSchema = external_exports.array(external_exports.string().meta({ enum: [...getAllowedWebhookEvents()].sort() })).min(1).superRefine((arr, ctx) => {
   const allowed = getAllowedWebhookEvents();
   let knownEventsList = null;
@@ -34839,7 +35020,7 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      webhookId: external_exports.string().describe("The webhook ID")
+      webhookId: external_exports.string().trim().min(1).describe("The webhook ID")
     }),
     handler: async (input) => {
       return apiGet(`/webhooks/${encPath(input.webhookId)}`);
@@ -34884,7 +35065,7 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      webhookId: external_exports.string().describe("The webhook ID to update"),
+      webhookId: external_exports.string().trim().min(1).describe("The webhook ID to update"),
       endpointUrl: endpointUrlSchema.optional().describe("New HTTPS URL to send webhook events to"),
       subscriptions: webhookSubscriptionsSchema.optional().describe(
         "Updated list of event types to subscribe to (at least one). 'categoryTailnetManagement' and 'categoryDeviceMisconfigurations' subscribe to a whole category, including events Tailscale adds to it later."
@@ -34902,7 +35083,7 @@ var webhookTools = [
   },
   {
     name: "tailscale_delete_webhook",
-    description: "Delete a webhook. This is irreversible \u2014 the webhook secret cannot be recovered.",
+    description: "Delete a webhook. This is irreversible -- the webhook secret cannot be recovered.",
     annotations: {
       title: "Delete webhook",
       readOnlyHint: false,
@@ -34911,7 +35092,10 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      webhookId: external_exports.string().describe("The webhook ID to delete")
+      // `.trim().min(1)`, not a bare string: a whitespace-only webhook id
+      // encodes to "%20" and this irreversible delete returns a 404 that reads
+      // like the webhook is already gone (rationale: tailnets.ts delete_tailnet).
+      webhookId: external_exports.string().trim().min(1).describe("The webhook ID to delete")
     }),
     handler: async (input) => {
       return apiDelete(`/webhooks/${encPath(input.webhookId)}`);
@@ -34919,7 +35103,7 @@ var webhookTools = [
   },
   {
     name: "tailscale_rotate_webhook_secret",
-    description: "Rotate a webhook's secret. Returns the new secret \u2014 save it immediately, as it cannot be retrieved again. The old secret is immediately invalidated.\n\nSECURITY: the response body contains the secret verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.",
+    description: "Rotate a webhook's secret. Returns the new secret -- save it immediately, as it cannot be retrieved again. The old secret is immediately invalidated.\n\nSECURITY: the response body contains the secret verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.",
     annotations: {
       title: "Rotate webhook secret",
       readOnlyHint: false,
@@ -34928,7 +35112,7 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      webhookId: external_exports.string().describe("The webhook ID whose secret to rotate")
+      webhookId: external_exports.string().trim().min(1).describe("The webhook ID whose secret to rotate")
     }),
     handler: async (input) => {
       return apiPost(`/webhooks/${encPath(input.webhookId)}/rotate`);
@@ -34947,7 +35131,7 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      webhookId: external_exports.string().describe("The webhook ID to test")
+      webhookId: external_exports.string().trim().min(1).describe("The webhook ID to test")
     }),
     handler: async (input) => {
       return apiPost(`/webhooks/${encPath(input.webhookId)}/test`);
@@ -35036,8 +35220,9 @@ function formatTailnetMismatchWarning(env) {
   return `TAILSCALE_OAUTH_TAILNET="${oauthTailnet}" but TAILSCALE_TAILNET="${explicit}". The OAuth token will be scoped to the former while tool requests are addressed to the latter, so every tailnet-scoped tool will fail with HTTP 403. Either unset TAILSCALE_TAILNET (or set it to "-") to follow the token, or set both to the same tailnet.`;
 }
 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 profileEnv = inputs.profileEnv?.trim();
+  const profileValid = !!profileEnv && !inputs.unknownProfile;
+  const profileLabel = profileValid ? inputs.explicitTools && inputs.profileWouldFilter ? `profile=${profileEnv} (overridden by TAILSCALE_TOOLS)` : `profile=${profileEnv}` : null;
   const groupsLabel = inputs.explicitTools ? `groups=${inputs.explicitTools.join(",")}` : null;
   return [
     profileLabel,
@@ -35055,6 +35240,11 @@ function wrapToolHandler(tool) {
     try {
       const result = await tool.handler(input);
       const response = result;
+      if (typeof response?.ok !== "boolean") {
+        return {
+          content: [{ type: "text", text: JSON.stringify(result ?? null, null, 2) }]
+        };
+      }
       if (!response.ok) {
         return {
           content: [
@@ -35080,10 +35270,7 @@ function wrapToolHandler(tool) {
   };
 }
 async function tailnetStatusResource(uri) {
-  const [devicesRes, settingsRes] = await Promise.all([
-    apiGet(`/tailnet/${getTailnet()}/devices?fields=id`),
-    apiGet(`/tailnet/${getTailnet()}/settings`)
-  ]);
+  const [devicesRes, settingsRes] = await fetchTailnetStatusInputs();
   const data = composeTailnetStatusData(devicesRes, settingsRes, { tailnet: getTailnet() });
   return { contents: [{ uri: uri.href, text: JSON.stringify(data, null, 2), mimeType: "application/json" }] };
 }
@@ -35132,7 +35319,7 @@ function explainNotLoaded(group, state) {
       toEnable: "set TAILSCALE_LOCAL_CLI=1"
     };
   }
-  if (state.toolsEnv) {
+  if (parseGroupList(state.toolsEnv) && !state.toolsIgnored) {
     return {
       reason: `TAILSCALE_TOOLS is set to "${state.toolsEnv}", which does not include this group`,
       toEnable: `add "${group}" to TAILSCALE_TOOLS`
@@ -35156,10 +35343,16 @@ function explainWritesWithheld(group, state) {
       toEnable: "unset TAILSCALE_READONLY"
     };
   }
-  const current = state.writeGroupsEnv?.trim();
+  const granted = parseGroupList(state.writeGroupsEnv);
+  if (!granted) {
+    return { reason: "writes are withheld in this group", toEnable: `add "${group}" to TAILSCALE_WRITE_GROUPS` };
+  }
+  const unknown2 = granted.filter((g) => !Object.hasOwn(state.fullRegistry, g));
+  const known = granted.filter((g) => Object.hasOwn(state.fullRegistry, g));
+  const unknownNote = unknown2.length > 0 ? `; ${unknown2.map((g) => `"${g}"`).join(", ")} ${unknown2.length > 1 ? "are not group names and grant" : "is not a group name and grants"} nothing` : "";
   return {
-    reason: current ? `TAILSCALE_WRITE_GROUPS is set to "${current}", which does not grant writes here` : "writes are withheld in this group",
-    toEnable: current ? `add "${group}" to TAILSCALE_WRITE_GROUPS (e.g. "${current},${group}")` : `add "${group}" to TAILSCALE_WRITE_GROUPS`
+    reason: `TAILSCALE_WRITE_GROUPS is set to "${state.writeGroupsEnv?.trim()}", which does not grant writes here${unknownNote}`,
+    toEnable: `add "${group}" to TAILSCALE_WRITE_GROUPS (e.g. "${[...known, group].join(",")}")`
   };
 }
 function buildGroupReports(state) {
@@ -35248,8 +35441,8 @@ function buildMetaTools(state) {
         const totalAvailable = groups.reduce((n, g) => n + g.available, 0);
         const activeFilters = [
           state.profileEnv ? `TAILSCALE_PROFILE=${state.profileEnv}` : null,
-          state.toolsEnv ? `TAILSCALE_TOOLS=${state.toolsEnv}` : null,
-          state.readonlyMode ? "TAILSCALE_READONLY=1" : null,
+          state.toolsEnv ? `TAILSCALE_TOOLS=${state.toolsEnv}${state.toolsIgnored ? " (ignored: names no known group)" : ""}` : null,
+          state.readonlyMode ? `TAILSCALE_READONLY=${state.readonlyEnv ?? "1"}` : null,
           state.writeGroupsEnv?.trim() ? `TAILSCALE_WRITE_GROUPS=${state.writeGroupsEnv.trim()}` : null,
           state.localCliEnabled ? "TAILSCALE_LOCAL_CLI=1" : null
         ].filter(Boolean);
@@ -35289,7 +35482,7 @@ Install a newer Node (https://nodejs.org/en/download), or point your MCP client'
   );
   process.exit(1);
 }
-var version2 = true ? "0.21.2" : resolveVersionFallback();
+var version2 = true ? "0.22.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
 var USAGE = `Usage: tailscale-mcp [command]
 
@@ -35318,6 +35511,9 @@ if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
   }
   const run = subcommand === "deploy-acl" ? deployAcl : validateAcl;
   run(filePath).then(() => process.exit(0)).catch((err) => {
+    if (err instanceof Error && err.name === "CliFailure") {
+      process.exit(1);
+    }
     console.error(`Fatal: ${err instanceof Error ? err.message : err}`);
     process.exit(1);
   });
@@ -35335,6 +35531,8 @@ if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
 if (!cliSubcommandHandled) {
   const localCliEnabled = isLocalCliEnabled(process.env);
   const toolGroups = buildToolGroups(process.env);
+  const fullRegistry = buildToolGroups({ ...process.env, TAILSCALE_LOCAL_CLI: "1" });
+  const readonlyMode = parseReadonlyFlag(process.env.TAILSCALE_READONLY);
   const {
     tools: allTools,
     unknownGroups,
@@ -35353,6 +35551,10 @@ if (!cliSubcommandHandled) {
     profile: process.env.TAILSCALE_PROFILE,
     writeGroups: process.env.TAILSCALE_WRITE_GROUPS
   });
+  const tailnetMismatch = formatTailnetMismatchWarning(process.env);
+  if (tailnetMismatch) {
+    console.error(`@yawlabs/tailscale-mcp: ${tailnetMismatch}`);
+  }
   if (unknownGroups.length > 0) {
     const validNames = Object.keys(toolGroups);
     const fallbackNote = toolsAllUnknown ? " Every requested group was unknown, so TAILSCALE_TOOLS was ignored and the default tool set was loaded instead." : "";
@@ -35362,7 +35564,7 @@ if (!cliSubcommandHandled) {
   }
   if (unknownWriteGroups && unknownWriteGroups.length > 0) {
     const validNames = Object.keys(toolGroups);
-    const everyPossibleGroup = Object.keys(buildToolGroups({ ...process.env, TAILSCALE_LOCAL_CLI: "1" }));
+    const everyPossibleGroup = Object.keys(fullRegistry);
     const notEnabled = unknownWriteGroups.filter((g) => everyPossibleGroup.includes(g));
     const realTypos = unknownWriteGroups.filter((g) => !everyPossibleGroup.includes(g));
     if (notEnabled.length > 0) {
@@ -35389,10 +35591,6 @@ if (!cliSubcommandHandled) {
       `@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.`
     );
   }
-  const tailnetMismatch = formatTailnetMismatchWarning(process.env);
-  if (tailnetMismatch) {
-    console.error(`@yawlabs/tailscale-mcp: ${tailnetMismatch}`);
-  }
   if (unknownProfile) {
     console.error(
       `@yawlabs/tailscale-mcp: TAILSCALE_PROFILE="${unknownProfile}" is not a known profile. Valid profiles: ${Object.keys(PROFILES).join(", ")}. Falling back to no profile filter.`
@@ -35408,7 +35606,7 @@ if (!cliSubcommandHandled) {
     // that is currently disabled -- which is exactly the group an agent needs
     // explained. Reporting only what loaded would make local-cli invisible rather
     // than explained.
-    fullRegistry: buildToolGroups({ ...process.env, TAILSCALE_LOCAL_CLI: "1" }),
+    fullRegistry,
     // Ground truth for availability: what this server actually serves. Deliberately
     // not a re-derivation of the filter logic, so the catalog cannot disagree with
     // the server about what exists.
@@ -35416,8 +35614,10 @@ if (!cliSubcommandHandled) {
     toolsEnv: process.env.TAILSCALE_TOOLS,
     profileEnv: process.env.TAILSCALE_PROFILE,
     writeGroupsEnv: process.env.TAILSCALE_WRITE_GROUPS,
-    readonlyMode: parseReadonlyFlag(process.env.TAILSCALE_READONLY),
-    localCliEnabled
+    readonlyMode,
+    readonlyEnv: process.env.TAILSCALE_READONLY,
+    localCliEnabled,
+    toolsIgnored: toolsAllUnknown
   });
   for (const tool of metaTools) {
     server.registerTool(
@@ -35482,7 +35682,6 @@ if (!cliSubcommandHandled) {
 `);
     process.exit(1);
   });
-  const readonlyMode = parseReadonlyFlag(process.env.TAILSCALE_READONLY);
   const filterSuffix = formatBannerFilterSuffix({
     unknownProfile,
     explicitTools,
@@ -35496,15 +35695,22 @@ if (!cliSubcommandHandled) {
   console.error(
     `@yawlabs/tailscale-mcp v${version2} ready (${allTools.length} tools${filterSuffix ? `, ${filterSuffix}` : ""})`
   );
-  const hasCreds = !!process.env.TAILSCALE_API_KEY || !!process.env.TAILSCALE_OAUTH_CLIENT_ID && !!process.env.TAILSCALE_OAUTH_CLIENT_SECRET;
-  const ADMIN_EQUIVALENT = ["keys", "users", "acl"];
+  const hasCreds = hasUsableCredentials();
+  const ADMIN_EQUIVALENT = {
+    keys: "tailscale_create_key mints an OAuth client with any scopes the caller asks for",
+    users: 'tailscale_update_user_role accepts "owner"',
+    acl: "tailscale_update_acl rewrites policy for every principal"
+  };
   const registeredNames = new Set(allTools.map((t) => t.name));
-  const adminWritable = ADMIN_EQUIVALENT.filter(
+  const adminWritable = Object.keys(ADMIN_EQUIVALENT).filter(
     (g) => (toolGroups[g] ?? []).some((t) => t.annotations.readOnlyHint !== true && registeredNames.has(t.name))
   );
   if (adminWritable.length > 0 && hasCreds) {
+    const examples = adminWritable.map((g) => ADMIN_EQUIVALENT[g]);
+    const last = examples.pop();
+    const exampleText = examples.length === 0 ? last : `${examples.join(", ")}${examples.length > 1 ? "," : ""} and ${last}`;
     console.error(
-      `@yawlabs/tailscale-mcp: note -- this server can write to ${adminWritable.join(", ")}, which is tailnet-admin-equivalent. tailscale_create_key mints an OAuth client with any scopes the caller asks for, tailscale_update_user_role accepts "owner", and tailscale_update_acl rewrites policy for every principal. Scope the Tailscale OAuth client itself to the areas you need -- that bound survives outside this process; this one does not. TAILSCALE_WRITE_GROUPS narrows what this server exposes.`
+      `@yawlabs/tailscale-mcp: note -- this server can write to ${adminWritable.join(", ")}, which is tailnet-admin-equivalent. ${exampleText}. Scope the Tailscale OAuth client itself to the areas you need -- that bound survives outside this process; this one does not. TAILSCALE_WRITE_GROUPS narrows what this server exposes.`
     );
   }
   if (!filterSuffix && hasCreds) {