@yawlabs/tailscale-mcp 0.8.1 → 0.8.3

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)
 [![CI](https://github.com/YawLabs/tailscale-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/tailscale-mcp/actions/workflows/ci.yml) [![Release](https://github.com/YawLabs/tailscale-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/tailscale-mcp/actions/workflows/release.yml) [![Integration](https://github.com/YawLabs/tailscale-mcp/actions/workflows/integration.yml/badge.svg)](https://github.com/YawLabs/tailscale-mcp/actions/workflows/integration.yml)
 
-**Ask your agent questions about your tailnet and have it act on the answers.** 99 tools + 4 resources covering the full [Tailscale v2 API](https://tailscale.com/api). Backed by 727 tests and a nightly integration run against a real tailnet.
+**Ask your agent questions about your tailnet and have it act on the answers.** 99 tools + 4 resources covering the full [Tailscale v2 API](https://tailscale.com/api). Backed by 735 tests and a nightly integration run against a real tailnet.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -35,7 +35,7 @@ Reasonable question. Both have their place. Where this MCP is better:
 - **Typed tool surface, not string parsing.** Every tool has a Zod-validated input schema and a structured response. No brittle `tailscale status --json | jq` pipelines that break when the schema evolves.
 - **Cross-client, no user rewriting.** A Claude Code skill is tied to Claude Code. An MCP server works in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and anything else that speaks MCP. Version bumps ship through `npx` — users don't re-author their skill when Tailscale adds an endpoint.
 - **Safe-by-default writes.** Every tool declares `readOnlyHint` / `destructiveHint` / `idempotentHint` so clients can skip confirmation on reads and require it on mutations. A skill that shells out to the CLI can't express that.
-- **Real tests.** 727 unit tests + an integration suite hitting a live tailnet on every tag. A skill is usually 50 lines of README without tests, and if the vendor changes output format nothing catches it.
+- **Real tests.** 727 unit tests + an integration suite hitting a live tailnet on every tag. Most skills are short markdown prompts without their own test layer — if the vendor changes output format, nothing catches it for you.
 
 If you already have a skill that covers your 10% of Tailscale workflows, great — keep it. The MCP is for the other 90%.
 
@@ -43,7 +43,7 @@ If you already have a skill that covers your 10% of Tailscale workflows, great
 
 Fair critique from Reddit: a week-old repo claiming "actively maintained" with no visible tests is worth exactly zero trust. Here's what's actually verifiable:
 
-- **727 tests** (178 suites, `node --test`) covering every tool's input validation, API shape, and error handling. Run `npm test` to see them pass locally.
+- **735 tests** (179 suites, `node --test`) covering every tool's input validation, API shape, and error handling. Run `npm test` to see them pass locally.
 - **3 CI workflows** on GitHub Actions:
   - [`ci.yml`](.github/workflows/ci.yml) — lint + typecheck + build + unit tests on every push and PR.
   - [`integration.yml`](.github/workflows/integration.yml) — runs the full tool surface against a real tailnet.
@@ -107,34 +107,70 @@ That's it. Now ask your agent:
 
 ## Too many tools? Subset them.
 
-99 tools is a lot. If you've already got a dozen MCP servers and your client is feeling heavy, trim what this one exposes:
+99 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:
+
+### Option 1: `TAILSCALE_PROFILE` (preset, easiest)
 
 ```json
 {
-  "mcpServers": {
-    "tailscale": {
-      "command": "npx",
-      "args": ["-y", "@yawlabs/tailscale-mcp"],
-      "env": {
-        "TAILSCALE_API_KEY": "tskey-api-...",
-        "TAILSCALE_TOOLS": "devices,acl,dns,audit",
-        "TAILSCALE_READONLY": "1"
-      }
-    }
+  "env": {
+    "TAILSCALE_API_KEY": "tskey-api-...",
+    "TAILSCALE_PROFILE": "core"
+  }
+}
+```
+
+- **`minimal`** (19 tools) — `status`, `devices`, `audit`. Observe the tailnet, read the audit log.
+- **`core`** (46 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
+- **`full`** (99 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"
   }
 }
 ```
 
-- **`TAILSCALE_TOOLS`** — comma-separated list of tool groups to expose. Omit for all groups.
-- **`TAILSCALE_READONLY`** — set to `1` or `true` to drop every mutating tool (only tools with `readOnlyHint: true` remain). Combine with `TAILSCALE_TOOLS` for maximum minimalism.
+Comma-separated group names. Overrides `TAILSCALE_PROFILE` when both are set — use this when the presets aren't quite right.
 
 Valid group names: `status`, `devices`, `acl`, `dns`, `keys`, `users`, `tailnet`, `webhooks`, `network-lock`, `posture`, `audit`, `invites`, `services`, `log-streaming`, `workload-identity`, `oauth-clients`.
 
-The server logs the active filter to stderr on startup so you can confirm what got loaded:
+### Option 3: `TAILSCALE_READONLY` (drop mutations)
 
+```json
+{
+  "env": {
+    "TAILSCALE_API_KEY": "tskey-api-...",
+    "TAILSCALE_PROFILE": "core",
+    "TAILSCALE_READONLY": "1"
+  }
+}
 ```
-@yawlabs/tailscale-mcp v0.8.0 ready (21 tools, groups=devices,acl,dns,audit, readonly)
+
+Set to `1` or `true` to drop every tool without `readOnlyHint: true`. Stacks with `TAILSCALE_PROFILE` or `TAILSCALE_TOOLS` as an intersection — combine for maximum minimalism.
+
+### Confirming what loaded
+
+The server logs the active filter to stderr on startup:
+
 ```
+@yawlabs/tailscale-mcp v0.8.2 ready (21 tools, profile=core, readonly)
+```
+
+If you don't set any filter, startup prints a tip pointing you at the profiles.
+
+## 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:
+
+1. **Server-side** — `TAILSCALE_PROFILE` / `TAILSCALE_TOOLS` / `TAILSCALE_READONLY` reduce the tool surface *before* mcph sees it. The unloaded tools aren't registered at all.
+2. **Client-side** — mcph's `mcp_connect_activate({ tools: [...] })` filters further for what appears in `tools/list`. Tools not in that list stay reachable via `mcp_connect_dispatch`, so you don't lose capability.
+
+Recommended pattern for mcph users: set `TAILSCALE_PROFILE=core` (or narrower) in your mcp.hosting server config, then let mcph handle per-conversation activation on top. The server stays lean by default, and `mcp_connect_dispatch` covers the long-tail tools for ad-hoc needs.
 
 ## Authentication
 
@@ -426,7 +462,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsc + esbuild bundle
-npm test           # node --test (727 tests)
+npm test           # node --test (735 tests)
 ```
 
 For integration testing against your own tailnet: set `TAILSCALE_API_KEY` and run `node dist/index.js`.

package/dist/index.js

@@ -30320,13 +30320,30 @@ async function deployAcl(filePath) {
 }
 
 // src/filter.ts
+var PROFILES = {
+  minimal: ["status", "devices", "audit"],
+  core: ["status", "devices", "acl", "dns", "keys", "users", "audit"],
+  full: []
+  // empty = all groups
+};
 function filterTools(groups, options) {
-  const enabledGroups = options.tools ? new Set(
-    options.tools.split(",").map((s) => s.trim()).filter(Boolean)
-  ) : null;
-  const readonly2 = options.readonly === "1" || options.readonly === "true";
   const validNames = new Set(Object.keys(groups));
+  let profileGroups;
+  let unknownProfile2;
+  if (options.profile) {
+    const profileKey = options.profile.trim().toLowerCase();
+    if (profileKey in PROFILES) {
+      const preset = PROFILES[profileKey];
+      profileGroups = preset.length > 0 ? [...preset] : void 0;
+    } else {
+      unknownProfile2 = profileKey;
+    }
+  }
+  const explicitTools = options.tools ? options.tools.split(",").map((s) => s.trim()).filter(Boolean) : null;
+  const effectiveGroups = explicitTools ?? profileGroups ?? null;
+  const enabledGroups = effectiveGroups ? new Set(effectiveGroups) : null;
   const unknownGroups2 = enabledGroups ? [...enabledGroups].filter((g) => !validNames.has(g)) : [];
+  const readonly2 = options.readonly === "1" || options.readonly === "true";
   const out = [];
   for (const [name, tools] of Object.entries(groups)) {
     if (enabledGroups && !enabledGroups.has(name)) continue;
@@ -30335,7 +30352,10 @@ function filterTools(groups, options) {
       out.push(t);
     }
   }
-  return { tools: out, unknownGroups: unknownGroups2 };
+  const result = { tools: out, unknownGroups: unknownGroups2 };
+  if (unknownProfile2) result.unknownProfile = unknownProfile2;
+  if (profileGroups && !explicitTools) result.profileGroups = profileGroups;
+  return result;
 }
 
 // src/tools/acl.ts
@@ -30415,7 +30435,7 @@ Pass this ETag to tailscale_update_acl when updating the policy.`
         acceptRaw: true,
         accept: "application/hujson"
       });
-      if (res.ok && (!res.rawBody || !res.rawBody.trim())) {
+      if (res.ok && !res.rawBody?.trim()) {
         return { ...res, rawBody: "ACL policy is valid." };
       }
       return res;
@@ -32459,7 +32479,7 @@ var workloadIdentityTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.8.1" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.8.3" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "deploy-acl") {
   const filePath = process.argv[3];
@@ -32494,9 +32514,14 @@ var toolGroups = {
   "workload-identity": workloadIdentityTools,
   "oauth-clients": oauthClientTools
 };
-var { tools: allTools, unknownGroups } = filterTools(toolGroups, {
+var {
+  tools: allTools,
+  unknownGroups,
+  unknownProfile
+} = filterTools(toolGroups, {
   tools: process.env.TAILSCALE_TOOLS,
-  readonly: process.env.TAILSCALE_READONLY
+  readonly: process.env.TAILSCALE_READONLY,
+  profile: process.env.TAILSCALE_PROFILE
 });
 if (unknownGroups.length > 0) {
   const validNames = Object.keys(toolGroups);
@@ -32504,6 +32529,11 @@ if (unknownGroups.length > 0) {
     `@yawlabs/tailscale-mcp: TAILSCALE_TOOLS includes unknown group(s): ${unknownGroups.join(", ")}. Valid groups: ${validNames.join(", ")}`
   );
 }
+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.`
+  );
+}
 var server = new McpServer({
   name: "@yawlabs/tailscale-mcp",
   version: version2
@@ -32606,11 +32636,18 @@ server.resource(
 var transport = new StdioServerTransport();
 await server.connect(transport);
 var readonlyMode = process.env.TAILSCALE_READONLY === "1" || process.env.TAILSCALE_READONLY === "true";
+var profileApplied = process.env.TAILSCALE_PROFILE && !unknownProfile ? process.env.TAILSCALE_PROFILE : null;
 var filterSuffix = [
+  profileApplied ? `profile=${profileApplied}` : null,
   process.env.TAILSCALE_TOOLS ? `groups=${process.env.TAILSCALE_TOOLS}` : null,
   readonlyMode ? "readonly" : null
 ].filter(Boolean).join(", ");
 console.error(
   `@yawlabs/tailscale-mcp v${version2} ready (${allTools.length} tools${filterSuffix ? `, ${filterSuffix}` : ""})`
 );
+if (!filterSuffix) {
+  console.error(
+    "@yawlabs/tailscale-mcp: tip \u2014 set TAILSCALE_PROFILE=core (46 tools) or =minimal (19) to load a smaller tool surface. See README."
+  );
+}
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",