@yawlabs/tailscale-mcp 0.18.0 → 0.19.0

package/README.md

@@ -5,7 +5,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/tailscale-mcp)](https://github.com/YawLabs/tailscale-mcp/stargazers)
 [![Release](https://img.shields.io/badge/release-local-blue)](./release.sh)
 
-**Ask your agent questions about your tailnet and have it act on the answers.** 96 admin-API tools + 6 optional local-CLI diagnostics + 4 resources spanning the [Tailscale v2 API](https://tailscale.com/api) — devices, ACLs, DNS, keys and trust credentials, users, invites, webhooks, log streaming, posture, services, and organization tailnets. Backed by 1100+ unit tests and an opt-in live-tailnet integration suite.
+**Ask your agent questions about your tailnet and have it act on the answers.** 97 admin-API tools + 6 optional local-CLI diagnostics + 1 always-on catalog tool + 4 resources spanning the [Tailscale v2 API](https://tailscale.com/api) — devices, ACLs, DNS, keys and trust credentials, users, invites, webhooks, log streaming, posture, services, and organization tailnets. Backed by 1100+ unit tests and an opt-in live-tailnet integration suite.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -104,29 +104,29 @@ That's it. Now ask your agent:
 
 ## Too many tools? Subset them.
 
-96 tools is a lot. If you've already got a dozen MCP servers and your client is feeling heavy, trim what this one exposes. Three knobs, combinable:
+97 tools is a lot. If you've already got a dozen MCP servers and your client is feeling heavy, trim what this one exposes. Three knobs, combinable:
+
+> The `env` blocks below show only the variable under discussion. Your credentials come from the environment, as set in [Quick start](#quick-start) — keep them in your shell profile rather than in the client's JSON config, which is world-readable on most systems and easy to commit by accident.
 
 ### Option 1: `TAILSCALE_PROFILE` (preset, easiest)
 
 ```json
 {
   "env": {
-    "TAILSCALE_API_KEY": "tskey-api-...",
     "TAILSCALE_PROFILE": "core"
   }
 }
 ```
 
 - **`minimal`** (20 tools) — `status`, `devices`, `audit`. Observe the tailnet, read the audit log.
-- **`core`** (51 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
-- **`full`** (96 tools, default) — everything. Same as omitting the env var.
+- **`core`** (52 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
+- **`full`** (97 tools, default) — everything. Same as omitting the env var.
 
 ### Option 2: `TAILSCALE_TOOLS` (explicit group list)
 
 ```json
 {
   "env": {
-    "TAILSCALE_API_KEY": "tskey-api-...",
     "TAILSCALE_TOOLS": "devices,acl,dns,audit"
   }
 }
@@ -141,7 +141,6 @@ Valid group names: `status`, `devices`, `acl`, `dns`, `keys`, `users`, `tailnet`
 ```json
 {
   "env": {
-    "TAILSCALE_API_KEY": "tskey-api-...",
     "TAILSCALE_PROFILE": "core",
     "TAILSCALE_READONLY": "1"
   }
@@ -161,13 +160,151 @@ The server logs the active filter to stderr on startup:
 When both `TAILSCALE_PROFILE` and `TAILSCALE_TOOLS` are set, `TAILSCALE_TOOLS` wins. The banner marks the profile as overridden so the precedence is obvious at a glance — no need to guess which filter actually applied:
 
 ```
-@yawlabs/tailscale-mcp v0.12.0 ready (21 tools, profile=core (overridden by TAILSCALE_TOOLS), groups=devices,acl)
+@yawlabs/tailscale-mcp v0.12.0 ready (22 tools, profile=core (overridden by TAILSCALE_TOOLS), groups=devices,acl)
 ```
 
 The "(overridden)" marker only fires for substantive profiles (`minimal` / `core`); `profile=full` is a no-op preset, so it's shown without the marker when `TAILSCALE_TOOLS` is also set.
 
 If you don't set any filter, startup prints a tip pointing you at the profiles.
 
+### And how the *agent* knows
+
+Everything above is stderr -- your MCP client's log. The model never sees it, so a
+withheld tool and a tool that was never built look identical from the agent's side.
+That is how an agent ends up working around a restriction instead of reporting it.
+
+`tailscale_tool_groups` closes that gap. It is **always registered**, whatever the
+filters say, and answers the question in-band:
+
+```
+> "Why can't you delete that device?"
+
+  tailscale_tool_groups({ toolName: "tailscale_delete_device" })
+
+  {
+    "tool": "tailscale_delete_device",
+    "available": false,
+    "group": "devices",
+    "kind": "write",
+    "reason": "TAILSCALE_WRITE_GROUPS is set to \"dns\", which does not grant writes here",
+    "toEnable": "add \"devices\" to TAILSCALE_WRITE_GROUPS (e.g. \"dns,devices\")"
+  }
+```
+
+It separates the three cases an agent otherwise cannot tell apart:
+
+| Case | What the agent should do |
+|---|---|
+| No such tool exists, under any configuration | Find another approach -- no setting will produce it |
+| Exists, but its group is not loaded | Report `toEnable` to you; do not work around it |
+| Exists and loaded, but writes are withheld there | Same -- the fix is yours, not a workaround |
+
+Called with no arguments it lists every group with its availability and, for anything
+withheld, the exact environment change that would restore it. It reads no network and
+needs no credentials, so it works even when the server is misconfigured.
+
+## Scoping writes to areas
+
+`TAILSCALE_WRITE_GROUPS` names the areas an agent may **write** to. Everything else stays readable:
+
+```json
+{
+  "env": {
+    "TAILSCALE_WRITE_GROUPS": "devices,keys"
+  }
+}
+```
+
+That serves all 47 read tools plus the 18 writes in `devices` and `keys`, and withholds the other 38 writes — the ACL, DNS, users, webhooks, posture, services, invites, org-tailnets and log-streaming writes are simply not registered. Unset means no write gate, which is the shipped default.
+
+> **Read this first: this filters the tool list, not your API token.** The server still holds one credential with full tailnet authority in every configuration. An agent that also has a shell can `curl api.tailscale.com` with that same token and do everything this knob withheld. Scope the Tailscale OAuth client itself to the areas you actually need — that bound survives outside this process; this one does not. `TAILSCALE_WRITE_GROUPS` is the low-friction complement to credential scoping, not a replacement for it.
+
+### What a grant actually contains
+
+Group names are the same ones `TAILSCALE_TOOLS` uses. Writes per group:
+
+| Group | Writes | Group | Writes |
+|---|---|---|---|
+| `devices` | 13 | `webhooks` | 5 |
+| `invites` | 7 | `posture` | 3 |
+| `dns` | 6 | `services` | 3 |
+| `keys` | 5 | `tailnet` | 3 |
+| `users` | 5 | `log-streaming` | 3 |
+| `org-tailnets` | 2 | `acl` | 1 |
+
+`status`, `audit` and the opt-in `local-cli` group contain no writes at all, so granting them does nothing.
+
+**`devices` is the widest grant, and the one most likely to be set.** In a compose file `write=devices` reads like "device admin", but it hands over `delete_device`, `set_devices_authorized`, `expire_device`, `deauthorize_device`, `set_device_routes`, `set_device_tags` and `update_device_key` alongside `rename_device`. There is no finer setting: an honest "safe subset" of `devices` is `rename_device` alone, and a knob whose useful value is one tool is not a knob.
+
+### Three grants are tailnet-admin-equivalent
+
+`keys`, `users` and `acl` are not blocked — CI key rotation legitimately needs `keys` — but grant them knowing:
+
+- **`keys`** — `tailscale_create_key` mints an OAuth client with whatever scopes the caller asks for, including `acl`. That credential outlives the agent's session and is not subject to this or any other setting here.
+- **`users`** — `tailscale_update_user_role` accepts `owner`.
+- **`acl`** — `tailscale_update_acl` rewrites policy for every principal in the tailnet.
+
+The server prints this on startup when your grant includes one of them.
+
+### What it does and does not bound
+
+It bounds **where** an agent may write. It does not bound **severity within** a granted area: inside a granted group, writes run unattended, including the grant-direction ones. Pair it with `TAILSCALE_REQUIRE_APPROVAL=1` when a human is at the keyboard — but understand that for an unattended agent that pairing contributes nothing, because a never-prompt client *denies* those calls rather than prompting.
+
+### Precedence, and what happens when you get it wrong
+
+| Situation | Result |
+|---|---|
+| Unset, empty, whitespace, or commas-only | No write gate. `-e VAR` with no value must not silently revoke every write. |
+| `TAILSCALE_READONLY=1` also set | Readonly wins; banner says `readonly (TAILSCALE_WRITE_GROUPS ignored)`. |
+| A name is misspelled (`devises`) | **Grants nothing** and names the typo. Unlike `TAILSCALE_TOOLS`, there is no fallback — a typo'd write grant that fell back would hand over all 56 writes at the moment you were restricting them. |
+| Partly misspelled (`devices,dnss`) | Grants the valid half, warns about the rest. |
+| A granted group is not loaded by `TAILSCALE_TOOLS` / `TAILSCALE_PROFILE` | The grant has no effect; a separate warning says so, since the name is not a typo. |
+| `none`, `all`, `off`, `*` | Not reserved words — they are unknown group names, so they grant nothing. Use `TAILSCALE_READONLY=1` for no writes, or leave this unset for all writes. The server points you at the right spelling. |
+
+Names are case-sensitive, matching `TAILSCALE_TOOLS`.
+
+**The upgrade contract:** upgrading this package can never widen the set of *areas* an agent may write to. A new group is in nobody's grant until a human types its name. It can, however, add tools inside an area you already granted — a pinned test makes that a reviewed line in the diff rather than a silent change.
+
+The startup banner shows what applied:
+
+```
+@yawlabs/tailscale-mcp v0.19.0 ready (59 tools, write=devices,keys)
+```
+
+## Requiring approval on irreversible tools
+
+`readOnlyHint` / `destructiveHint` are *advisory* — the MCP spec says clients MUST treat annotations as untrusted, and most don't gate on them. `TAILSCALE_REQUIRE_APPROVAL=1` adds a stronger signal that supported clients enforce:
+
+```json
+{
+  "env": {
+    "TAILSCALE_REQUIRE_APPROVAL": "1"
+  }
+}
+```
+
+Nine tools are then advertised with `_meta["anthropic/requiresUserInteraction"]`, which forces a confirmation prompt even when an allow-rule would otherwise auto-approve the call:
+
+| Tool | Why it's on the list |
+|---|---|
+| `tailscale_update_acl` | Can lock every device out of the tailnet; the previous HuJSON (comments included) is gone unless you captured it |
+| `tailscale_delete_device` | The device must re-enroll |
+| `tailscale_delete_user` | No undelete |
+| `tailscale_delete_tailnet` | Destroys an entire tailnet |
+| `tailscale_delete_key` | The secret is never returned again |
+| `tailscale_delete_oauth_app` | Same |
+| `tailscale_delete_webhook` | Same |
+| `tailscale_delete_log_stream_config` | Same |
+| `tailscale_delete_posture_integration` | Same |
+
+The line drawn is **"this server cannot undo it with information you still hold"**, which is narrower than the 23 tools annotated `destructiveHint: true`. `tailscale_suspend_user` is deliberately *excluded* — `tailscale_restore_user` reverses it. So are `tailscale_deauthorize_device` (reversed by `tailscale_authorize_device`) and the replace-all setters, which all have a `get_*` counterpart you can read before writing.
+
+**Opt-in on purpose, and read this before turning it on.** In a client mode that never prompts (an unattended agent, a CI run), the flag causes those calls to be **denied** rather than run. That is the right default when a human is at the keyboard and the wrong one when nobody is, so it stays off unless you set it.
+
+Requires a client that honors the annotation; Claude Code added support in v2.1.199. Clients that don't recognize it ignore it, so setting the variable is never worse than leaving it off.
+
+Separately and always on, five tools whose response size scales with the tailnet rather than with the request — `tailscale_list_devices`, `tailscale_list_users`, `tailscale_get_acl`, `tailscale_get_audit_log`, `tailscale_get_network_flow_logs` — declare `_meta["anthropic/maxResultSizeChars"]`, so a large-but-legitimate result stays inline instead of being truncated into a file reference the agent has to read back mid-task.
+
 ## Using with mcp.hosting / mcph
 
 If you run this server through [mcp.hosting](https://mcp.hosting) (via the `@yawlabs/mcph` local agent), the two filtering layers compose cleanly:
@@ -227,7 +364,7 @@ Set `TAILSCALE_LOCAL_CLI=1` (in your shell or `.mcp.json` `env` block) to add si
 
 Requirements: the `tailscale` binary must be in `PATH`. If it's installed somewhere unusual, set `TAILSCALE_BINARY` to its absolute path. The MCP server doesn't need root to run these — they're all diagnostic, not state-mutating. Operations that would need elevation (`tailscale up`, `set --advertise-routes`, `lock sign`) are deliberately not exposed.
 
-When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.13.3 ready (102 tools, local-cli=on)` — the 6 local CLI tools are additive on top of the default 96.
+When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.13.3 ready (103 tools, local-cli=on)` — the 6 local CLI tools are additive on top of the default 97.
 
 ## Resources (4)
 
@@ -240,7 +377,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | ACL Policy | `tailscale://tailnet/acl` | Full ACL policy (HuJSON preserved) |
 | DNS Config | `tailscale://tailnet/dns` | Nameservers, search paths, split DNS, MagicDNS |
 
-## Tools (96 + 6 opt-in)
+## Tools (97 + 6 opt-in)
 
 <details>
 <summary><strong>Status</strong> (1 tool)</summary>
@@ -277,7 +414,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 </details>
 
 <details>
-<summary><strong>ACL / Policy</strong> (4 tools) — with HuJSON formatting preservation and ETag safety</summary>
+<summary><strong>ACL / Policy</strong> (5 tools) — with HuJSON formatting preservation and ETag safety</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -285,6 +422,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | `tailscale_update_acl` | Update ACL policy (requires ETag for safe concurrent edits) |
 | `tailscale_validate_acl` | Validate a policy without applying it |
 | `tailscale_preview_acl` | Preview rules that would apply to a user or IP |
+| `tailscale_diff_acl_access` | Compare a proposed policy against the live one — who gains and loses access |
 
 </details>
 
@@ -538,7 +676,7 @@ This shows a read-only banner in the Tailscale Admin Console pointing to your re
 
 ## Running on oam.js (optional)
 
-[oam.js](https://oamjs.org) runs this server unmodified. Verified against oam 0.9.0: full MCP handshake, all 96 tools, all 4 resources, identical error messages, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
+[oam.js](https://oamjs.org) runs this server unmodified. Verified against oam 0.9.0: full MCP handshake, all 97 tools, all 4 resources, identical error messages, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
 
 **oam 0.9.0 is the minimum.** Older releases ran `child_process.execFile` arguments through a shell, re-splitting them on whitespace and executing shell metacharacters inside an argument. This server shells out to the `tailscale` binary across its local-CLI tools, so that was a reachable bug rather than a theoretical one. The launcher enforces the floor: given an older oam it falls back to Node and says so on stderr, and `TAILSCALE_MCP_RUNTIME=oam` turns that into a hard error.
 
@@ -553,8 +691,7 @@ It is opt-in rather than default because a wrong grant does not fail loudly. oam
   "mcpServers": {
     "tailscale": {
       "command": "oam",
-      "args": ["run", "/path/to/tailscale-mcp/dist/index.js"],
-      "env": { "TAILSCALE_API_KEY": "tskey-api-..." }
+      "args": ["run", "/path/to/tailscale-mcp/dist/index.js"]
     }
   }
 }

package/bin/tailscale-mcp.mjs

@@ -192,9 +192,11 @@ function sandboxFlags() {
     "TAILSCALE_PROFILE",
     "TAILSCALE_READONLY",
     "TAILSCALE_REQUEST_BUDGET_MS",
+    "TAILSCALE_REQUIRE_APPROVAL",
     "TAILSCALE_RETRY_BASE_DELAY_MS",
     "TAILSCALE_TAILNET",
     "TAILSCALE_TOOLS",
+    "TAILSCALE_WRITE_GROUPS",
   ];
 
   const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];

package/dist/index.js

@@ -31416,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";
 }
@@ -31434,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;
@@ -31443,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);
     }
   }
@@ -31458,10 +31466,59 @@ 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");
@@ -31594,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
+        }
+      };
+    }
   }
 ];
 
@@ -34024,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,
@@ -34065,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(", ");
 }
@@ -34143,8 +34392,153 @@ async function tailnetDnsResource(uri) {
   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.18.0" : resolveVersionFallback();
+var version2 = true ? "0.19.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
 var cliSubcommandHandled = false;
 if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
@@ -34177,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);
@@ -34190,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.`
@@ -34208,28 +34631,72 @@ if (!cliSubcommandHandled) {
     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",
     {
@@ -34251,12 +34718,24 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",