@yawlabs/tailscale-mcp 0.17.1 → 0.19.0

package/dist/index.js

@@ -31035,6 +31035,11 @@ async function getOAuthAccessToken(clientId, clientSecret) {
   })();
   return oauthRefreshPromise;
 }
+function invalidateOAuthTokenOnUnauthorized(authorizationHeader) {
+  if (!oauthToken) return;
+  if (authorizationHeader !== `Bearer ${oauthToken.access_token}`) return;
+  oauthToken = null;
+}
 async function getAuthHeader() {
   const config2 = getAuthConfig();
   if (config2.kind === "apiKey") {
@@ -31130,14 +31135,17 @@ function getRetryBaseDelayMs() {
 }
 async function withConcurrencyLimit(fn) {
   const limit = getConcurrencyLimit();
-  if (limit === 0) return fn();
+  if (limit === 0) return fn(0);
+  let queuedForMs = 0;
   if (inFlight >= limit) {
+    const queueStartedAt = Date.now();
     await new Promise((resolve) => concurrencyQueue.push(resolve));
+    queuedForMs = Date.now() - queueStartedAt;
   } else {
     inFlight++;
   }
   try {
-    return await fn();
+    return await fn(queuedForMs);
   } finally {
     const next = concurrencyQueue.shift();
     if (next) {
@@ -31188,6 +31196,15 @@ function describeTransportError(err, method, attemptTimeoutMs) {
   }
   return `${method} request failed: ${String(err)}`;
 }
+function describeBudgetExhaustion(budgetMs, queuedForMs, lastTransportError) {
+  if (lastTransportError) {
+    return `${lastTransportError}; request budget of ${budgetMs}ms exhausted before next attempt could begin.`;
+  }
+  if (queuedForMs > 0) {
+    return `Request budget of ${budgetMs}ms exhausted before attempt could begin: ${queuedForMs}ms of it was spent waiting for a free slot under TAILSCALE_MAX_CONCURRENT, so no request was ever sent. Raise TAILSCALE_MAX_CONCURRENT or TAILSCALE_REQUEST_BUDGET_MS -- this is queueing, not a network fault.`;
+  }
+  return `Request budget of ${budgetMs}ms exhausted before attempt could begin.`;
+}
 async function apiRequest(method, path, body, options) {
   const headers = {};
   if (options?.accept) {
@@ -31217,7 +31234,7 @@ async function apiRequest(method, path, body, options) {
   debugLog(`${method} ${url2}`);
   const isRetryable = RETRYABLE_METHODS.has(method.toUpperCase());
   const requestBudgetMs = getRequestBudgetMs();
-  return withConcurrencyLimit(async () => {
+  return withConcurrencyLimit(async (queuedForMs) => {
     headers.Authorization = await getAuthHeader();
     let res;
     let lastTransportError;
@@ -31227,7 +31244,7 @@ async function apiRequest(method, path, body, options) {
         return {
           ok: false,
           status: 0,
-          error: lastTransportError ? `${lastTransportError}; request budget of ${requestBudgetMs}ms exhausted before next attempt could begin.` : `Request budget of ${requestBudgetMs}ms exhausted before attempt could begin.`
+          error: describeBudgetExhaustion(requestBudgetMs, queuedForMs, lastTransportError)
         };
       }
       const attemptTimeoutMs = Math.min(REQUEST_TIMEOUT_MS, remaining);
@@ -31268,6 +31285,9 @@ async function apiRequest(method, path, body, options) {
     const etag = response.headers.get("etag") || void 0;
     const elapsed = Date.now() - startedAt;
     debugLog(`  <- ${response.status} (${elapsed}ms)`);
+    if (response.status === 401) {
+      invalidateOAuthTokenOnUnauthorized(headers.Authorization);
+    }
     try {
       if (options?.acceptRaw) {
         const rawBody = await response.text();
@@ -31396,6 +31416,11 @@ var PROFILES = {
   full: []
   // empty = all groups
 };
+function parseGroupList(value) {
+  if (!value) return null;
+  const parsed = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return parsed.length > 0 ? parsed : null;
+}
 function parseReadonlyFlag(value) {
   return value === "1" || value === "true";
 }
@@ -31414,8 +31439,7 @@ function filterTools(groups, options) {
       unknownProfile = profileKey;
     }
   }
-  const parsedTools = options.tools ? options.tools.split(",").map((s) => s.trim()).filter(Boolean) : null;
-  const explicitTools = parsedTools && parsedTools.length > 0 ? parsedTools : null;
+  const explicitTools = parseGroupList(options.tools);
   const explicitToolsAllUnknown = explicitTools?.every((g) => !validNames.has(g)) ?? false;
   const effectiveExplicitTools = explicitToolsAllUnknown ? null : explicitTools;
   const effectiveGroups = effectiveExplicitTools ?? profileGroups ?? null;
@@ -31423,11 +31447,15 @@ function filterTools(groups, options) {
   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 requestedWriteGroups = parseGroupList(options.writeGroups);
+  const unknownWriteGroups = requestedWriteGroups ? requestedWriteGroups.filter((g) => !validNames.has(g)) : [];
+  const writeScope = requestedWriteGroups ? new Set(requestedWriteGroups.filter((g) => validNames.has(g))) : null;
   const out = [];
   for (const [name, tools] of Object.entries(groups)) {
     if (enabledGroups && !enabledGroups.has(name)) continue;
+    const writesAllowed = !readonly2 && (writeScope === null || writeScope.has(name));
     for (const t of tools) {
-      if (readonly2 && t.annotations.readOnlyHint !== true) continue;
+      if (t.annotations.readOnlyHint !== true && !writesAllowed) continue;
       out.push(t);
     }
   }
@@ -31438,10 +31466,71 @@ function filterTools(groups, options) {
   if (effectiveExplicitTools) result.explicitTools = effectiveExplicitTools;
   if (profileWouldFilter) result.profileWouldFilter = true;
   if (explicitToolsAllUnknown) result.toolsAllUnknown = true;
+  if (writeScope) {
+    const loaded = [...writeScope].filter((g) => !enabledGroups || enabledGroups.has(g));
+    result.writeGroups = readonly2 ? [] : loaded.sort();
+    const overridden = readonly2 && writeScope.size > 0;
+    if (overridden) result.writeGroupsOverriddenByReadonly = true;
+    const notLoaded = overridden ? [] : [...writeScope].filter((g) => enabledGroups && !enabledGroups.has(g));
+    if (notLoaded.length > 0) result.writeGroupsNotLoaded = notLoaded.sort();
+  }
+  if (unknownWriteGroups.length > 0) result.unknownWriteGroups = unknownWriteGroups;
   return result;
 }
 
 // src/tools/acl.ts
+var DEFAULT_PRINCIPAL_CAP = 25;
+var DIFF_TIME_BUDGET_MS = 6e4;
+function accessSet(matches) {
+  const out = /* @__PURE__ */ new Set();
+  for (const match of matches) {
+    const via = [...match.via ?? []].sort();
+    const postures = [...match.postures ?? []].sort();
+    const qualifier = `${via.length > 0 ? ` via ${via.join(",")}` : ""}${postures.length > 0 ? ` posture ${postures.join(",")}` : ""}`;
+    for (const port of match.ports ?? []) out.add(`${port}${qualifier}`);
+  }
+  return out;
+}
+async function previewAccess(policy, principal) {
+  const params = new URLSearchParams({ type: "user", previewFor: principal });
+  const res = await apiPost(`/tailnet/${getTailnet()}/acl/preview?${params}`, void 0, {
+    rawBody: policy,
+    contentType: "application/hujson",
+    acceptRaw: true,
+    accept: "application/hujson"
+  });
+  if (!res.ok) return { ok: false, error: res.error || `HTTP ${res.status}`, status: res.status };
+  let parsed;
+  try {
+    parsed = JSON.parse(res.rawBody ?? "");
+  } catch {
+    return {
+      ok: false,
+      error: "the preview response was not valid JSON, so its rules could not be compared",
+      status: res.status
+    };
+  }
+  if (!Array.isArray(parsed.matches)) {
+    return {
+      ok: false,
+      error: "the preview response contained no `matches` array, so its rules could not be compared",
+      status: res.status
+    };
+  }
+  return { ok: true, access: accessSet(parsed.matches) };
+}
+var ETAG_FOOTER_MARKER = "// ETag: ";
+function stripEtagFooter(body) {
+  const lines = body.split("\n");
+  let cut = lines.length;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line === "") continue;
+    if (!line.startsWith("//")) break;
+    if (line.startsWith(ETAG_FOOTER_MARKER)) cut = i;
+  }
+  return lines.slice(0, cut).join("\n");
+}
 var aclTools = [
   {
     name: "tailscale_get_acl",
@@ -31462,12 +31551,12 @@ var aclTools = [
       if (res.ok && res.etag) {
         const footer = [
           "",
-          `// ETag: ${res.etag}`,
+          `${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.)",
           ""
         ].join("\n");
-        return { ...res, rawBody: `${res.rawBody ?? ""}${footer}` };
+        return { ...res, rawBody: `${stripEtagFooter(res.rawBody ?? "")}${footer}` };
       }
       return res;
     }
@@ -31478,7 +31567,10 @@ var aclTools = [
     annotations: {
       title: "Update ACL policy",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Overwrites the whole policy file in one call, and a bad push can lock
+      // every device out of the tailnet -- the widest blast radius of any write
+      // here, so clients must gate it rather than auto-approve it.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -31486,8 +31578,16 @@ var aclTools = [
       policy: external_exports.string().describe(
         "The full ACL policy text. Preserve existing formatting, comments, and structure. Only modify the specific parts that need to change."
       ),
-      etag: external_exports.string().describe("The ETag from tailscale_get_acl. Required to prevent concurrent edit conflicts.")
+      etag: external_exports.string().trim().min(1, "etag must not be empty -- an empty ETag would send this overwrite with no concurrency guard.").describe("The ETag from tailscale_get_acl. Required to prevent concurrent edit conflicts.")
     }),
+    // `.trim().min(1)`, not a bare `z.string()`: apiRequest sets If-Match behind
+    // `if (options?.ifMatch)`, so an empty etag is falsy there and the header is
+    // omitted entirely -- the write then overwrites a concurrent admin edit instead
+    // of coming back 412, on the widest-blast-radius write in the package, with
+    // no diagnostic anywhere. `.trim()` is load-bearing for the same reason it is
+    // on tailnets.ts's ids: a bare `.min(1)` accepts " ", which is truthy, so the
+    // header goes out carrying a precondition that cannot match any real ETag --
+    // a confusing 412 instead of a local validation error naming the field.
     handler: async (input) => {
       return apiPost(`/tailnet/${getTailnet()}/acl`, void 0, {
         rawBody: input.policy,
@@ -31551,6 +31651,158 @@ var aclTools = [
         accept: "application/hujson"
       });
     }
+  },
+  {
+    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; it does not detect a change to a posture DEFINITION, because the comparison keys on posture names; and a narrowed port list shows as a paired loss and gain of the whole entry rather than a clean loss. An empty result is never proof a change is safe. 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.",
+    annotations: {
+      title: "Diff ACL access",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      policy: external_exports.string().describe("The proposed ACL policy text to compare against the current live policy"),
+      principals: external_exports.array(external_exports.string().trim().min(1)).optional().describe(
+        "User emails to check. Omit to enumerate the tailnet's users automatically. Pass an explicit list to bound the request count, or to check specific users beyond the cap."
+      ),
+      maxPrincipals: external_exports.number().int().positive().optional().describe(
+        `Maximum users to check (default ${DEFAULT_PRINCIPAL_CAP}). Each costs two preview requests. Raising this on a large tailnet can be slow and may hit rate limits.`
+      )
+    }),
+    handler: async (input) => {
+      const startedAt = Date.now();
+      const current = await apiGet(`/tailnet/${getTailnet()}/acl`, {
+        acceptRaw: true,
+        accept: "application/hujson"
+      });
+      if (!current.ok) {
+        return {
+          ok: false,
+          error: `could not read the current ACL to diff against: ${current.error || `HTTP ${current.status}`}`
+        };
+      }
+      const baselinePolicy = current.rawBody ?? "";
+      let principals;
+      let availableTotal;
+      if (input.principals !== void 0) {
+        principals = [...new Set(input.principals)];
+        if (principals.length === 0) {
+          return {
+            ok: false,
+            error: "`principals` was passed as an empty list, so no users were named to compare. Omit the argument entirely to enumerate the tailnet's users, or name at least one email."
+          };
+        }
+        availableTotal = principals.length;
+      } else {
+        const usersRes = await apiGet(`/tailnet/${getTailnet()}/users`);
+        if (!usersRes.ok) {
+          return { ok: false, error: `could not list users to diff: ${usersRes.error || `HTTP ${usersRes.status}`}` };
+        }
+        const emails = (usersRes.data?.users ?? []).map((u) => u.loginName ?? u.email ?? u.name).filter((v) => typeof v === "string" && v.trim().length > 0);
+        principals = [...new Set(emails)];
+        availableTotal = principals.length;
+        if (principals.length === 0) {
+          return {
+            ok: false,
+            error: "no user emails could be read from the tailnet's user list, so there is nothing to compare. Pass `principals` explicitly with the emails to check -- an empty diff here would wrongly suggest the change affects nobody."
+          };
+        }
+      }
+      const cap = input.maxPrincipals ?? DEFAULT_PRINCIPAL_CAP;
+      const checked = principals.slice(0, cap);
+      const changed = [];
+      const unchanged = [];
+      const failed = [];
+      let attempted = 0;
+      let stoppedOnTime = false;
+      for (const principal of checked) {
+        if (Date.now() - startedAt > DIFF_TIME_BUDGET_MS) {
+          stoppedOnTime = true;
+          break;
+        }
+        attempted++;
+        const [before, after] = await Promise.all([
+          previewAccess(baselinePolicy, principal),
+          previewAccess(input.policy, principal)
+        ]);
+        if (!before.ok || !after.ok) {
+          const failure = !before.ok ? before : !after.ok ? after : void 0;
+          const which = !before.ok ? "current" : "proposed";
+          failed.push({
+            principal,
+            error: `preview against the ${which} policy failed: ${failure?.error ?? "unknown"}`
+          });
+          if (failure?.status === 401 || failure?.status === 403) {
+            return {
+              ok: false,
+              error: `authentication failed while previewing ${principal}, so the diff was abandoned rather than continued against a credential the API has already refused: ${failure?.error ?? "unknown"}`
+            };
+          }
+          continue;
+        }
+        const lost = [...before.access].filter((a) => !after.access.has(a)).sort();
+        const gained = [...after.access].filter((a) => !before.access.has(a)).sort();
+        if (lost.length === 0 && gained.length === 0) unchanged.push(principal);
+        else changed.push({ principal, lost, gained });
+      }
+      const compared = attempted - failed.length;
+      if (compared === 0) {
+        return {
+          ok: false,
+          error: stoppedOnTime ? `no users could be compared: the ${DIFF_TIME_BUDGET_MS / 1e3}s budget for this call was spent before any comparison finished. Narrow the run with \`principals\`, or lower \`maxPrincipals\`.` : `no users could be compared: all ${attempted} preview attempts failed. First failure: ${failed[0]?.error ?? "unknown"}`
+        };
+      }
+      const losing = changed.filter((c) => c.lost.length > 0).length;
+      const gaining = changed.filter((c) => c.gained.length > 0).length;
+      const notChecked = principals.length - attempted;
+      const truncated = notChecked > 0;
+      const summary = [
+        // Failures lead when present, so the headline cannot read as an
+        // all-clear over a partially-compared run.
+        failed.length > 0 ? `${failed.length} of ${attempted} users could not be checked` : null,
+        `${losing} of ${compared} users compared lose access`,
+        `${gaining} gain access`,
+        `${unchanged.length} unchanged`,
+        // Names WHICH limit stopped the run: "cap 25" tells the caller to raise
+        // maxPrincipals, and the time budget tells them the opposite -- that
+        // raising it would make things worse, and the run needs narrowing.
+        truncated ? `${notChecked} not checked (${stoppedOnTime ? `${DIFF_TIME_BUDGET_MS / 1e3}s time budget` : `cap ${cap}`})` : null
+      ].filter(Boolean).join(", ");
+      return {
+        ok: true,
+        data: {
+          tailnet: getTailnet(),
+          summary,
+          // Three numbers, because two of them were being conflated. `Compared`
+          // is the only one that describes work actually done.
+          principalsCompared: compared,
+          principalsFailed: failed.length,
+          principalsAvailable: availableTotal,
+          truncated,
+          // Distinguishes the two truncation causes for a machine reader, which
+          // the summary string does only in prose. They call for opposite
+          // responses: a cap stop means raise maxPrincipals, a time stop means
+          // narrow the run.
+          stoppedOnTimeBudget: stoppedOnTime,
+          // Restated in the payload, not just the tool description: whoever
+          // reads this output is deciding whether to apply the change, and may
+          // never have read the description. Each clause names a way this diff
+          // can come back empty while real access changed.
+          scope: [
+            "User principals only.",
+            "Not compared: access granted via tags or groups;",
+            "changes to a posture DEFINITION (the diff keys on posture names, so redefining `posture:corp` more strictly leaves every key identical);",
+            "and a destination whose port list is narrowed appears as a paired loss and gain of the whole entry (`tag:prod:22,80` -> `tag:prod:22`) rather than a clean loss, so `gained` is not a literal list of newly-reachable destinations.",
+            "An empty diff is not proof the change is safe."
+          ].join(" "),
+          changed,
+          unchanged,
+          failed
+        }
+      };
+    }
   }
 ];
 
@@ -31805,7 +32057,9 @@ var deviceTools = [
     annotations: {
       title: "Set device routes",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Replace-all: the routes array is the new enabled set, so `[]` silently
+      // withdraws every subnet the device currently routes.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -31890,7 +32144,9 @@ var deviceTools = [
     annotations: {
       title: "Set device tags",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Replace-all: `[]` strips every ACL tag, which can drop the device out of
+      // the policy rules that grant it access.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -31969,7 +32225,7 @@ var deviceTools = [
       const failed = {};
       for (const { deviceId, res } of results) {
         if (res.ok) succeeded.push(deviceId);
-        else failed[deviceId] = { status: res.status, error: res.error ?? `HTTP ${res.status}` };
+        else failed[deviceId] = { status: res.status, error: res.error || `HTTP ${res.status}` };
       }
       const failedCount = Object.keys(failed).length;
       if (failedCount === unique.length) {
@@ -32053,7 +32309,9 @@ var dnsTools = [
     annotations: {
       title: "Set nameservers",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Replace-all: `[]` clears tailnet DNS resolution rather than leaving the
+      // current nameservers in place.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -32085,7 +32343,8 @@ var dnsTools = [
     annotations: {
       title: "Set DNS search paths",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Replace-all: `[]` clears every configured search domain.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -32119,7 +32378,9 @@ var dnsTools = [
     annotations: {
       title: "Set split DNS",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Replace-all (PUT): every domain absent from the map is dropped, so `{}`
+      // clears the whole split DNS config. The PATCH sibling below merges instead.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -32206,7 +32467,9 @@ var dnsTools = [
     annotations: {
       title: "Set DNS configuration (unified)",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Replace-all across every DNS setting at once -- a superset of the wipe
+      // the individual setters above can do.
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -32663,6 +32926,48 @@ var keyTools = [
     handler: async (input) => {
       return apiGet(`/tailnet/${getTailnet()}/oauth-apps/${encPath(input.appId)}`);
     }
+  },
+  {
+    name: "tailscale_list_oauth_apps",
+    description: "List the OAuth Apps registered in your tailnet (Tailscale alpha). Returns an `oauthApps` array describing each app (id, name, redirect URIs, scopes). Client secrets are NOT included -- a secret is only returned once, by tailscale_create_oauth_app at creation time. This is how you recover the id of an app you did not record; pass that id to tailscale_delete_oauth_app to revoke it.",
+    annotations: {
+      title: "List OAuth apps",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    // No limit/cursor: the live endpoint takes no parameters and returns the
+    // whole collection. Advertising pagination the API ignores would let a
+    // caller believe it had paged through the list when it had not.
+    inputSchema: external_exports.object({}),
+    handler: async () => {
+      return apiGet(`/tailnet/${getTailnet()}/oauth-apps`);
+    }
+  },
+  {
+    name: "tailscale_delete_oauth_app",
+    description: "Delete an OAuth App (Tailscale alpha). This is irreversible: the app's client secret stops working immediately and any integration using it loses its device-enrollment path, so no further device can be authorized through it. Devices already enrolled stay in the tailnet, exactly as they do when the auth key that added them is deleted. Use tailscale_list_oauth_apps to find the id.",
+    annotations: {
+      title: "Delete OAuth app",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      // `.trim().min(1)` rather than the bare `.min(1)` on
+      // tailscale_get_oauth_app's appId, for the reason tailnets.ts spells out
+      // on tailscale_delete_tailnet: a bare min(1) accepts " ", which encPath
+      // then sends as the literal segment "%20". On a read that costs a wasted
+      // round-trip; on an irreversible revoke it returns a 404 that reads like
+      // the app is already gone. Trimming at the schema makes it a validation
+      // error instead.
+      appId: external_exports.string().trim().min(1).describe("The OAuth app ID to delete (see tailscale_list_oauth_apps)")
+    }),
+    handler: async (input) => {
+      return apiDelete(`/tailnet/${getTailnet()}/oauth-apps/${encPath(input.appId)}`);
+    }
   }
 ];
 
@@ -32866,8 +33171,8 @@ var logStreamingTools = [
         apiGet(`/tailnet/${getTailnet()}/logging/network/stream`)
       ]);
       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) errors.configuration = configuration.error || `HTTP ${configuration.status}`;
+      if (!network.ok) errors.network = network.error || `HTTP ${network.status}`;
       if (!configuration.ok && !network.ok) {
         return {
           ok: false,
@@ -33353,8 +33658,8 @@ function composeTailnetStatusData(devicesRes, settingsRes, extras = {}) {
     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 (!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;
 }
@@ -33486,7 +33791,7 @@ var tailnetTools = [
       const failed = {};
       for (const { contactType, res } of results) {
         if (res.ok) applied[contactType] = res.data;
-        else failed[contactType] = { status: res.status, error: res.error ?? `HTTP ${res.status}` };
+        else failed[contactType] = { status: res.status, error: res.error || `HTTP ${res.status}` };
       }
       const hasFailed = Object.keys(failed).length > 0;
       const hasApplied = Object.keys(applied).length > 0;
@@ -33573,7 +33878,7 @@ var tailnetsTools = [
   },
   {
     name: "tailscale_delete_tailnet",
-    description: "Permanently delete a tailnet. This is IRREVERSIBLE and removes every device, user, ACL, and key in it.\n\nBy default it acts on the tailnet the current credentials point at (TAILSCALE_TAILNET, or TAILSCALE_OAUTH_TAILNET when targeting an API-only tailnet). Pass `tailnet` to name a different one -- e.g. an id returned by tailscale_list_org_tailnets -- which requires credentials scoped to reach it; UNVERIFIED against a live tailnet, so expect a 403/404 if your token cannot. You must always pass `confirmTailnet` matching the effective target exactly; the call is refused locally otherwise. Intended for tearing down API-only tailnets created by tailscale_create_org_tailnet.",
+    description: "Permanently delete a tailnet. This is IRREVERSIBLE and removes every device, user, ACL, and key in it.\n\nBy default it acts on the tailnet the current credentials point at (TAILSCALE_TAILNET, or TAILSCALE_OAUTH_TAILNET when targeting an API-only tailnet). Pass `tailnet` to name a different one -- e.g. an id returned by tailscale_list_org_tailnets -- which requires credentials scoped to reach it; UNVERIFIED against a live tailnet, so expect a 403/404 if your token cannot. You must always pass `confirmTailnet` matching the effective target exactly; the call is refused locally otherwise. That check is a typo guard, not an authorization gate: when you also pass `tailnet` you are supplying both halves of the comparison, so it proves only that they agree -- it is a genuine second look only on the omit-`tailnet` path, where the value has to match the operator's environment. Restricting who may delete at all is TAILSCALE_READONLY / TAILSCALE_TOOLS, which drop this tool from the server entirely. Intended for tearing down API-only tailnets created by tailscale_create_org_tailnet.",
     annotations: {
       title: "Delete tailnet",
       readOnlyHint: false,
@@ -33586,7 +33891,7 @@ var tailnetsTools = [
         "Tailnet to delete (e.g. an id from tailscale_list_org_tailnets). Omit to target the configured tailnet. Requires credentials scoped to reach it."
       ),
       confirmTailnet: external_exports.string().trim().min(1).describe(
-        "Must exactly match the effective target -- `tailnet` when given, otherwise the configured tailnet (TAILSCALE_TAILNET / TAILSCALE_OAUTH_TAILNET). A deliberate second look before an irreversible org-wide delete."
+        "Must exactly match the effective target -- `tailnet` when given, otherwise the configured tailnet (TAILSCALE_TAILNET / TAILSCALE_OAUTH_TAILNET). A typo guard, not an authorization gate: on the explicit-`tailnet` path the caller writes both halves of the comparison, so it proves only self-agreement. It is a real second look only when `tailnet` is omitted and the value has to match the operator's environment."
       )
     }),
     // `.trim().min(1)` on both fields, not just `.min(1)`: a bare min(1) accepts
@@ -33604,8 +33909,9 @@ var tailnetsTools = [
         );
       }
       if (input.confirmTailnet !== target) {
+        const source = input.tailnet?.trim() ? "tailnet you named" : "configured tailnet";
         throw new Error(
-          `confirmTailnet ${JSON.stringify(input.confirmTailnet)} does not match the configured tailnet ${JSON.stringify(target)}. Refusing to delete.`
+          `confirmTailnet ${JSON.stringify(input.confirmTailnet)} does not match the ${source} ${JSON.stringify(target)}. Refusing to delete.`
         );
       }
       return apiDelete(`/tailnet/${encPath(target)}`);
@@ -33927,6 +34233,42 @@ var webhookTools = [
 function isLocalCliEnabled(env) {
   return env.TAILSCALE_LOCAL_CLI === "1" || env.TAILSCALE_LOCAL_CLI === "true";
 }
+function isRequireApprovalEnabled(env) {
+  return env.TAILSCALE_REQUIRE_APPROVAL === "1" || env.TAILSCALE_REQUIRE_APPROVAL === "true";
+}
+var FORCED_APPROVAL_TOOLS = [
+  "tailscale_delete_device",
+  "tailscale_delete_key",
+  "tailscale_delete_log_stream_config",
+  "tailscale_delete_oauth_app",
+  "tailscale_delete_posture_integration",
+  "tailscale_delete_tailnet",
+  "tailscale_delete_user",
+  "tailscale_delete_webhook",
+  "tailscale_update_acl"
+];
+var MAX_RESULT_SIZE_CHARS = 5e5;
+var LARGE_RESULT_TOOLS = [
+  // Scales with BOTH the number of principals checked and each one's grant
+  // count, so for a given tailnet its payload is strictly larger than
+  // list_users below.
+  "tailscale_diff_acl_access",
+  "tailscale_get_acl",
+  "tailscale_get_audit_log",
+  "tailscale_get_network_flow_logs",
+  "tailscale_list_devices",
+  "tailscale_list_users"
+];
+function buildToolMeta(toolName, options) {
+  const meta3 = {};
+  if (options.requireApproval && FORCED_APPROVAL_TOOLS.includes(toolName)) {
+    meta3["anthropic/requiresUserInteraction"] = true;
+  }
+  if (LARGE_RESULT_TOOLS.includes(toolName)) {
+    meta3["anthropic/maxResultSizeChars"] = MAX_RESULT_SIZE_CHARS;
+  }
+  return Object.keys(meta3).length > 0 ? meta3 : void 0;
+}
 function buildToolGroups(env) {
   const toolGroups = {
     status: statusTools,
@@ -33968,7 +34310,11 @@ function formatBannerFilterSuffix(inputs) {
   return [
     profileLabel,
     groupsLabel,
-    inputs.readonlyMode ? "readonly" : null,
+    inputs.readonlyMode ? inputs.writeGroupsOverriddenByReadonly ? "readonly (TAILSCALE_WRITE_GROUPS ignored)" : "readonly" : null,
+    // `write=none` (configured, granted nothing) is a different state from no segment
+    // at all (knob unset, every write served), and an operator debugging "why can it
+    // not write" needs to tell them apart at a glance.
+    inputs.writeGroups ? inputs.writeGroups.length > 0 ? `write=${inputs.writeGroups.join(",")}` : "write=none" : null,
     inputs.localCliEnabled ? "local-cli=on" : null
   ].filter(Boolean).join(", ");
 }
@@ -34011,7 +34357,7 @@ async function tailnetStatusResource(uri) {
 }
 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);
+  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) {
@@ -34019,7 +34365,7 @@ async function tailnetAclResource(uri) {
   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 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" }] };
@@ -34038,16 +34384,161 @@ async function tailnetDnsResource(uri) {
     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 (!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/meta.ts
+function explainNotLoaded(group, state) {
+  if (group === "local-cli" && !state.localCliEnabled) {
+    return {
+      reason: "the local-CLI group is opt-in and is not enabled in this process",
+      toEnable: "set TAILSCALE_LOCAL_CLI=1"
+    };
+  }
+  if (state.toolsEnv) {
+    return {
+      reason: `TAILSCALE_TOOLS is set to "${state.toolsEnv}", which does not include this group`,
+      toEnable: `add "${group}" to TAILSCALE_TOOLS`
+    };
+  }
+  if (state.profileEnv) {
+    return {
+      reason: `TAILSCALE_PROFILE="${state.profileEnv}" does not include this group`,
+      toEnable: `set TAILSCALE_PROFILE=full, or list the groups you want in TAILSCALE_TOOLS`
+    };
+  }
+  return {
+    reason: "this group did not register, and no load filter is configured to explain why",
+    toEnable: "no env change is known to enable it -- please report this at https://github.com/YawLabs/tailscale-mcp/issues"
+  };
+}
+function explainWritesWithheld(group, state) {
+  if (state.readonlyMode) {
+    return {
+      reason: "TAILSCALE_READONLY is enabled, so no group serves writes",
+      toEnable: "unset TAILSCALE_READONLY"
+    };
+  }
+  const current = state.writeGroupsEnv?.trim();
+  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`
+  };
+}
+function buildGroupReports(state) {
+  const reports = [];
+  for (const [group, tools] of Object.entries(state.fullRegistry)) {
+    const available = tools.filter((t) => state.registeredNames.has(t.name));
+    const writes = tools.filter((t) => t.annotations.readOnlyHint !== true);
+    const writesAvailable = writes.filter((t) => state.registeredNames.has(t.name));
+    const base = {
+      group,
+      tools: tools.length,
+      available: available.length,
+      writes: writes.length,
+      writesAvailable: writesAvailable.length
+    };
+    if (available.length === 0) {
+      reports.push({ ...base, status: "unavailable", ...explainNotLoaded(group, state) });
+      continue;
+    }
+    if (writes.length > 0 && writesAvailable.length === 0) {
+      reports.push({ ...base, status: "read-only", ...explainWritesWithheld(group, state) });
+      continue;
+    }
+    reports.push({ ...base, status: "full" });
+  }
+  return reports;
+}
+function explainTool(toolName, state) {
+  const query = toolName.trim();
+  for (const [group, tools] of Object.entries(state.fullRegistry)) {
+    const tool = tools.find((t) => t.name === query);
+    if (!tool) continue;
+    const isWrite = tool.annotations.readOnlyHint !== true;
+    if (state.registeredNames.has(query)) {
+      return {
+        tool: query,
+        available: true,
+        group,
+        kind: isWrite ? "write" : "read",
+        reason: "this tool is registered and callable right now"
+      };
+    }
+    const groupHasAny = tools.some((t) => state.registeredNames.has(t.name));
+    const explain = groupHasAny ? explainWritesWithheld(group, state) : explainNotLoaded(group, state);
+    return {
+      tool: query,
+      available: false,
+      group,
+      kind: isWrite ? "write" : "read",
+      ...explain
+    };
+  }
+  return {
+    tool: query,
+    available: false,
+    // The case an agent most needs separated from the others: no configuration
+    // change will produce this tool, so retrying or asking the operator is wasted.
+    // Only here is "find another way" the right conclusion.
+    reason: "no tool by that name exists in this server, under any configuration. Check the spelling, or call this tool with no arguments to see what is available."
+  };
+}
+function buildMetaTools(state) {
+  return [
+    {
+      name: "tailscale_tool_groups",
+      description: "Explain which of this server's tools are available and why. Call this FIRST when a Tailscale tool you expected is missing, instead of assuming the capability does not exist -- tools can be withheld by configuration, and the fix is usually one environment variable. Pass `toolName` to ask about one specific tool (e.g. 'tailscale_delete_device'): the answer distinguishes 'no such tool exists' -- where you should find another approach -- from 'it exists but its group is not loaded' and 'it exists and loaded but writes are withheld there', both of which the operator can enable and neither of which you should work around. With no arguments it lists every group with its availability and, where something is withheld, the exact environment change that would restore it. Always available regardless of filters.",
+      annotations: {
+        title: "Explain available tools",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        // The only tool here that touches no network: it reports this process's own
+        // configuration, so it cannot fail on credentials, scope or connectivity.
+        openWorldHint: false
+      },
+      inputSchema: external_exports.object({
+        toolName: external_exports.string().trim().min(1).optional().describe("A specific tool to ask about, e.g. 'tailscale_delete_device'. Omit to list every group.")
+      }),
+      handler: async (input) => {
+        if (input.toolName) {
+          return { ok: true, data: explainTool(input.toolName, state) };
+        }
+        const groups = buildGroupReports(state);
+        const withheld = groups.filter((g) => g.status !== "full");
+        const totalTools = groups.reduce((n, g) => n + g.tools, 0);
+        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.writeGroupsEnv?.trim() ? `TAILSCALE_WRITE_GROUPS=${state.writeGroupsEnv.trim()}` : null,
+          state.localCliEnabled ? "TAILSCALE_LOCAL_CLI=1" : null
+        ].filter(Boolean);
+        return {
+          ok: true,
+          data: {
+            summary: withheld.length === 0 ? `All ${totalAvailable} tools are available; nothing is withheld by configuration.` : `${totalAvailable} of ${totalTools} tools are available. ${withheld.length} group(s) are limited by configuration -- see \`groups\` for the exact environment change for each.`,
+            activeFilters: activeFilters.length > 0 ? activeFilters : ["none -- no filters are configured"],
+            groups,
+            // Addressed to the model, because it is the model that has to decide
+            // what to do next when a tool is absent.
+            guidance: "A tool listed as unavailable here EXISTS -- it is withheld by this server's configuration, not missing from the API. Do not work around it by using a different tool to achieve the same effect; report the `toEnable` value to the human instead, since only they can change it."
+          }
+        };
+      }
+    }
+  ];
+}
+
 // src/index.ts
-var version2 = true ? "0.17.1" : resolveVersionFallback();
+var version2 = true ? "0.19.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
 var cliSubcommandHandled = false;
 if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
@@ -34080,11 +34571,16 @@ if (!cliSubcommandHandled) {
     unknownProfile,
     explicitTools,
     profileWouldFilter,
-    toolsAllUnknown
+    toolsAllUnknown,
+    writeGroups,
+    unknownWriteGroups,
+    writeGroupsNotLoaded,
+    writeGroupsOverriddenByReadonly
   } = filterTools(toolGroups, {
     tools: process.env.TAILSCALE_TOOLS,
     readonly: process.env.TAILSCALE_READONLY,
-    profile: process.env.TAILSCALE_PROFILE
+    profile: process.env.TAILSCALE_PROFILE,
+    writeGroups: process.env.TAILSCALE_WRITE_GROUPS
   });
   if (unknownGroups.length > 0) {
     const validNames = Object.keys(toolGroups);
@@ -34093,6 +34589,30 @@ if (!cliSubcommandHandled) {
       `@yawlabs/tailscale-mcp: TAILSCALE_TOOLS includes unknown group(s): ${unknownGroups.join(", ")}. Valid groups: ${validNames.join(", ")}.${fallbackNote}`
     );
   }
+  if (unknownWriteGroups && unknownWriteGroups.length > 0) {
+    const validNames = Object.keys(toolGroups);
+    const everyPossibleGroup = Object.keys(buildToolGroups({ ...process.env, TAILSCALE_LOCAL_CLI: "1" }));
+    const notEnabled = unknownWriteGroups.filter((g) => everyPossibleGroup.includes(g));
+    const realTypos = unknownWriteGroups.filter((g) => !everyPossibleGroup.includes(g));
+    if (notEnabled.length > 0) {
+      console.error(
+        `@yawlabs/tailscale-mcp: TAILSCALE_WRITE_GROUPS names group(s) that exist but are not enabled in this process: ${notEnabled.join(", ")}. Set TAILSCALE_LOCAL_CLI=1 to register the local-cli group. Not a typo -- the grant simply had nothing to apply to.`
+      );
+    }
+    if (realTypos.length > 0) {
+      const sentinels = /* @__PURE__ */ new Set(["none", "off", "false", "0", "all", "*"]);
+      const guessed = realTypos.filter((g) => sentinels.has(g.toLowerCase()));
+      const hint = guessed.some((g) => ["all", "*"].includes(g.toLowerCase())) ? ' Note: "all" is not a group name -- leave TAILSCALE_WRITE_GROUPS unset to allow writes in every loaded group.' : guessed.length > 0 ? " Note: to disable writes entirely, TAILSCALE_READONLY=1 is the shipped spelling." : "";
+      console.error(
+        `@yawlabs/tailscale-mcp: TAILSCALE_WRITE_GROUPS includes unknown group(s): ${realTypos.join(", ")}. Valid groups: ${validNames.join(", ")}. Those names granted no write access; tools outside the granted groups are served read-only.${hint}`
+      );
+    }
+  }
+  if (writeGroupsNotLoaded && writeGroupsNotLoaded.length > 0) {
+    console.error(
+      `@yawlabs/tailscale-mcp: TAILSCALE_WRITE_GROUPS names group(s) that your TAILSCALE_TOOLS / TAILSCALE_PROFILE filter does not load: ${writeGroupsNotLoaded.join(", ")}. Those grants had no effect.`
+    );
+  }
   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.`
@@ -34104,35 +34624,79 @@ if (!cliSubcommandHandled) {
   }
   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.`
+      `@yawlabs/tailscale-mcp: TAILSCALE_PROFILE="${unknownProfile}" is not a known profile. Valid profiles: ${Object.keys(PROFILES).join(", ")}. Falling back to no profile filter.`
     );
   }
   const server = new McpServer({
     name: "@yawlabs/tailscale-mcp",
     version: version2
   });
+  const requireApproval = isRequireApprovalEnabled(process.env);
+  const metaTools = buildMetaTools({
+    // The FULL registry, with opt-ins forced on, so the catalog can report on a group
+    // 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" }),
+    // 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.
+    registeredNames: new Set(allTools.map((t) => t.name)),
+    toolsEnv: process.env.TAILSCALE_TOOLS,
+    profileEnv: process.env.TAILSCALE_PROFILE,
+    writeGroupsEnv: process.env.TAILSCALE_WRITE_GROUPS,
+    readonlyMode: parseReadonlyFlag(process.env.TAILSCALE_READONLY),
+    localCliEnabled
+  });
+  for (const tool of metaTools) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.annotations.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema.shape,
+        annotations: tool.annotations,
+        _meta: buildToolMeta(tool.name, { requireApproval })
+      },
+      wrapToolHandler(tool)
+    );
+  }
   for (const tool of allTools) {
-    server.tool(tool.name, tool.description, tool.inputSchema.shape, tool.annotations, wrapToolHandler(tool));
+    server.registerTool(
+      tool.name,
+      {
+        // Hoisted out of annotations.title, which every tool file already sets.
+        // The annotations copy deliberately stays where it is: clients reading
+        // the legacy location keep working, so this is purely additive on the
+        // wire rather than a move.
+        title: tool.annotations.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema.shape,
+        annotations: tool.annotations,
+        _meta: buildToolMeta(tool.name, { requireApproval })
+      },
+      wrapToolHandler(tool)
+    );
   }
-  server.resource(
+  server.registerResource(
     "tailnet-status",
     "tailscale://tailnet/status",
     { description: "Current tailnet status including device count and settings", mimeType: "application/json" },
     tailnetStatusResource
   );
-  server.resource(
+  server.registerResource(
     "tailnet-devices",
     "tailscale://tailnet/devices",
     { description: "List of all devices in the tailnet with their status", mimeType: "application/json" },
     tailnetDevicesResource
   );
-  server.resource(
+  server.registerResource(
     "tailnet-acl",
     "tailscale://tailnet/acl",
     { description: "Current ACL policy (HuJSON with comments preserved)", mimeType: "application/hujson" },
     tailnetAclResource
   );
-  server.resource(
+  server.registerResource(
     "tailnet-dns",
     "tailscale://tailnet/dns",
     {
@@ -34154,18 +34718,30 @@ if (!cliSubcommandHandled) {
     profileWouldFilter,
     profileEnv: process.env.TAILSCALE_PROFILE,
     readonlyMode,
-    localCliEnabled
+    localCliEnabled,
+    writeGroups,
+    writeGroupsOverriddenByReadonly
   });
   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 registeredNames = new Set(allTools.map((t) => t.name));
+  const adminWritable = ADMIN_EQUIVALENT.filter(
+    (g) => (toolGroups[g] ?? []).some((t) => t.annotations.readOnlyHint !== true && registeredNames.has(t.name))
+  );
+  if (adminWritable.length > 0 && hasCreds) {
+    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.`
+    );
+  }
   if (!filterSuffix && hasCreds) {
     const profileCount = (groups) => groups.reduce((n, g) => n + (toolGroups[g]?.length ?? 0), 0);
     const coreCount = profileCount(PROFILES.core);
     const minimalCount = profileCount(PROFILES.minimal);
     console.error(
-      `@yawlabs/tailscale-mcp: tip \u2014 set TAILSCALE_PROFILE=core (${coreCount} tools) or =minimal (${minimalCount}) to load a smaller tool surface. See README.`
+      `@yawlabs/tailscale-mcp: tip -- set TAILSCALE_PROFILE=core (${coreCount} tools) or =minimal (${minimalCount}) to load a smaller tool surface. See README.`
     );
   }
 }