@yawlabs/tailscale-mcp 0.11.0 → 0.12.0

package/README.md

@@ -9,7 +9,7 @@
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
-[![Add to mcp.hosting](https://mcp.hosting/install-button.svg)](https://mcp.hosting/install?name=Tailscale&command=npx&args=-y%2C%40yawlabs%2Ftailscale-mcp&env=TAILSCALE_API_KEY&description=Manage%20your%20Tailscale%20tailnet%20-%20devices%2C%20ACLs%2C%20DNS%2C%20keys&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Ftailscale-mcp)
+[![Add to mcp.hosting](https://mcp.hosting/install-button.svg)](https://mcp.hosting/install?name=Tailscale&command=npx&args=-y%2C%40yawlabs%2Ftailscale-mcp&description=Manage%20your%20Tailscale%20tailnet%20-%20devices%2C%20ACLs%2C%20DNS%2C%20keys&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Ftailscale-mcp)
 
 One click adds this to your [mcp.hosting](https://mcp.hosting) account so it syncs to every MCP client you use. Or install manually below.
 
@@ -197,6 +197,8 @@ The server checks for an API key first, then falls back to OAuth. If neither is
 
 **`TAILSCALE_REQUEST_BUDGET_MS=N`** — total wall-clock budget per request, including 429 retries and their sleeps. Default `90000` (90s). When the next retry's predicted wall time would exceed the budget, the call surfaces the 429 immediately instead of holding the line. Tune lower if your MCP client has a tighter outer timeout. 429s on non-idempotent methods (POST, PATCH) are never retried — those return immediately regardless of budget.
 
+**`TAILSCALE_EXTRA_WEBHOOK_EVENTS=eventA,eventB`** — opt-in escape hatch for webhook event types Tailscale ships after the latest release of this package. The webhook tools validate `subscriptions` against a strict static catalog so typos and stale event names fail fast with a clear error; if you need a brand-new event before the catalog catches up, list it here (comma-separated) and the schema will accept it. Please also [open an issue](https://github.com/YawLabs/tailscale-mcp/issues) so the static list catches up.
+
 **Friendlier error messages.** JSON error bodies of the form `{"message":"..."}` or `{"error":"..."}` are unwrapped before display, so you see the prose explanation instead of raw JSON. 401s still get the full multi-line auth-error formatter (with the Windows env-var hint when applicable).
 
 ## Local CLI integration (opt-in)

package/dist/index.js

@@ -31288,18 +31288,20 @@ function filterTools(groups, options) {
   const validNames = new Set(Object.keys(groups));
   let profileGroups;
   let unknownProfile2;
+  let profileWouldFilter2 = false;
   if (options.profile) {
     const profileKey = options.profile.trim().toLowerCase();
     if (Object.hasOwn(PROFILES, profileKey)) {
       const preset = PROFILES[profileKey];
-      profileGroups = preset.length > 0 ? [...preset] : void 0;
+      profileWouldFilter2 = preset.length > 0;
+      profileGroups = profileWouldFilter2 ? [...preset] : void 0;
     } else {
       unknownProfile2 = profileKey;
     }
   }
   const parsedTools = options.tools ? options.tools.split(",").map((s) => s.trim()).filter(Boolean) : null;
-  const explicitTools = parsedTools && parsedTools.length > 0 ? parsedTools : null;
-  const effectiveGroups = explicitTools ?? profileGroups ?? null;
+  const explicitTools2 = parsedTools && parsedTools.length > 0 ? parsedTools : null;
+  const effectiveGroups = explicitTools2 ?? 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";
@@ -31313,11 +31315,27 @@ function filterTools(groups, options) {
   }
   const result = { tools: out, unknownGroups: unknownGroups2 };
   if (unknownProfile2) result.unknownProfile = unknownProfile2;
-  if (profileGroups && !explicitTools) result.profileGroups = profileGroups;
+  if (profileGroups && !explicitTools2) result.profileGroups = profileGroups;
+  if (explicitTools2) result.explicitTools = explicitTools2;
+  if (profileWouldFilter2) result.profileWouldFilter = true;
   return result;
 }
 
 // src/server-wiring.ts
+function isLocalCliEnabled(env) {
+  return env.TAILSCALE_LOCAL_CLI === "1" || env.TAILSCALE_LOCAL_CLI === "true";
+}
+function formatBannerFilterSuffix(inputs) {
+  const profileValid = !!inputs.profileEnv && !inputs.unknownProfile;
+  const profileLabel = profileValid ? inputs.explicitTools && inputs.profileWouldFilter ? `profile=${inputs.profileEnv} (overridden by TAILSCALE_TOOLS)` : `profile=${inputs.profileEnv}` : null;
+  const groupsLabel = inputs.explicitTools ? `groups=${inputs.explicitTools.join(",")}` : null;
+  return [
+    profileLabel,
+    groupsLabel,
+    inputs.readonlyMode ? "readonly" : null,
+    inputs.localCliEnabled ? "local-cli=on" : null
+  ].filter(Boolean).join(", ");
+}
 function wrapToolHandler(tool) {
   return async (input) => {
     try {
@@ -31354,7 +31372,11 @@ async function tailnetStatusResource(uri) {
   ]);
   const data = {
     tailnet: getTailnet(),
-    deviceCount: devicesRes.ok ? devicesRes.data?.devices?.length ?? 0 : null,
+    // `?? null` (not `?? 0`): the request succeeded but the body was missing
+    // a `devices` array (204 / empty content-length / unexpected shape).
+    // Reporting `0` in that case would be confidently wrong; null signals
+    // "unknown" so the caller doesn't conflate it with an actually-empty tailnet.
+    deviceCount: devicesRes.ok ? devicesRes.data?.devices?.length ?? null : null,
     settings: settingsRes.ok ? settingsRes.data : null
   };
   const errors = {};
@@ -31623,6 +31645,11 @@ var deviceTools = [
       if (input.fields) params.set("fields", input.fields);
       if (input.filters) {
         for (const [key, value] of Object.entries(input.filters)) {
+          if (key === "fields") {
+            throw new Error(
+              "filters.fields is not allowed -- use the top-level 'fields' parameter to select which device fields to return."
+            );
+          }
           params.set(key, value);
         }
       }
@@ -32627,10 +32654,12 @@ async function runTailscaleCli(args, options = {}) {
 }
 
 // src/tools/local-cli.ts
+var HOSTNAME_LABEL = /^[a-zA-Z0-9_]([a-zA-Z0-9_-]*[a-zA-Z0-9_])?$/;
 function isValidPingTarget(s) {
   if (s.length === 0 || s.length > 253) return false;
   if (net2.isIP(s)) return true;
-  return /^[a-zA-Z0-9._-]+$/.test(s);
+  const labels = s.split(".");
+  return labels.every((label) => label.length >= 1 && label.length <= 63 && HOSTNAME_LABEL.test(label));
 }
 var localCliTools = [
   {
@@ -32805,6 +32834,21 @@ var logStreamingTools = [
           );
         }
       } else {
+        const s3Only = [
+          "s3Bucket",
+          "s3Region",
+          "s3KeyPrefix",
+          "s3AuthenticationType",
+          "s3AccessKeyId",
+          "s3SecretAccessKey",
+          "s3RoleArn"
+        ];
+        const wrongFields = s3Only.filter((f) => input[f] !== void 0);
+        if (wrongFields.length > 0) {
+          throw new Error(
+            `${wrongFields.join(", ")} can only be used with destinationType 's3', not '${input.destinationType}'.`
+          );
+        }
         const missing = [];
         if (!input.url) missing.push("url");
         if (!input.token) missing.push("token");
@@ -33055,7 +33099,7 @@ var serviceTools = [
       ports: external_exports.array(
         external_exports.object({
           protocol: external_exports.enum(["tcp", "udp"]).describe("Protocol (tcp or udp)"),
-          port: external_exports.number().describe("Port number")
+          port: external_exports.number().int().min(1).max(65535).describe("Port number (1-65535)")
         })
       ).optional().describe("Ports the service listens on"),
       tags: external_exports.array(external_exports.string()).optional().describe("ACL tags for the service"),
@@ -33176,7 +33220,11 @@ var statusTools = [
       const data = {
         connected: true,
         tailnet: getTailnet(),
-        deviceCount: devicesRes.ok ? devicesRes.data?.devices?.length ?? 0 : null,
+        // `?? null` (not `?? 0`): the request succeeded but the body was missing
+        // a `devices` array (204 / empty content-length / unexpected shape).
+        // Reporting `0` in that case would be confidently wrong; null signals
+        // "unknown" so the caller doesn't conflate it with an actually-empty tailnet.
+        deviceCount: devicesRes.ok ? devicesRes.data?.devices?.length ?? null : null,
         settings: settingsRes.ok ? settingsRes.data : null
       };
       const errors = {};
@@ -33451,7 +33499,7 @@ var userTools = [
 ];
 
 // src/tools/webhooks.ts
-var webhookEventTypes = [
+var STATIC_WEBHOOK_EVENT_TYPES = [
   "nodeCreated",
   "nodeNeedsApproval",
   "nodeApproved",
@@ -33471,6 +33519,31 @@ var webhookEventTypes = [
   "subnetIPForwardingNotEnabled",
   "exitNodeIPForwardingNotEnabled"
 ];
+function getAllowedWebhookEvents() {
+  const raw = process.env.TAILSCALE_EXTRA_WEBHOOK_EVENTS;
+  if (!raw) return new Set(STATIC_WEBHOOK_EVENT_TYPES);
+  const extras = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...extras]);
+}
+var webhookSubscriptionsSchema = external_exports.array(external_exports.string()).min(1).superRefine((arr, ctx) => {
+  const allowed = getAllowedWebhookEvents();
+  let knownEventsList = null;
+  for (let i = 0; i < arr.length; i++) {
+    const value = arr[i];
+    if (!allowed.has(value)) {
+      knownEventsList ??= [...allowed].sort().join(", ");
+      ctx.addIssue({
+        code: "custom",
+        // `path: [i]` so the issue locates the bad element. Zod prepends the
+        // parent path (e.g. "subscriptions") when reporting through the
+        // surrounding object schema, producing a final path of
+        // ["subscriptions", i] in error.issues.
+        path: [i],
+        message: `Unknown webhook event ${JSON.stringify(value)}. Known events: ${knownEventsList}. To allow a new event Tailscale has shipped before this package updates, set TAILSCALE_EXTRA_WEBHOOK_EVENTS=eventName1,eventName2 in your MCP config.`
+      });
+    }
+  }
+});
 var webhookTools = [
   {
     name: "tailscale_list_webhooks",
@@ -33516,7 +33589,7 @@ var webhookTools = [
     },
     inputSchema: external_exports.object({
       endpointUrl: external_exports.string().url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://").describe("The HTTPS URL to send webhook events to"),
-      subscriptions: external_exports.array(external_exports.enum(webhookEventTypes)).min(1).describe("Event types to subscribe to (at least one)")
+      subscriptions: webhookSubscriptionsSchema.describe("Event types to subscribe to (at least one)")
     }),
     handler: async (input) => {
       return apiPost(`/tailnet/${getTailnet()}/webhooks`, {
@@ -33538,7 +33611,7 @@ var webhookTools = [
     inputSchema: external_exports.object({
       webhookId: external_exports.string().describe("The webhook ID to update"),
       endpointUrl: external_exports.string().url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://").optional().describe("New HTTPS URL to send webhook events to"),
-      subscriptions: external_exports.array(external_exports.enum(webhookEventTypes)).min(1).optional().describe("Updated list of event types to subscribe to (at least one)")
+      subscriptions: webhookSubscriptionsSchema.optional().describe("Updated list of event types to subscribe to (at least one)")
     }),
     handler: async (input) => {
       const body = {};
@@ -33606,7 +33679,7 @@ var webhookTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.11.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.12.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "deploy-acl") {
   const filePath = process.argv[3];
@@ -33638,13 +33711,16 @@ var toolGroups = {
   services: serviceTools,
   "log-streaming": logStreamingTools
 };
-if (process.env.TAILSCALE_LOCAL_CLI === "1" || process.env.TAILSCALE_LOCAL_CLI === "true") {
+var localCliEnabled = isLocalCliEnabled(process.env);
+if (localCliEnabled) {
   toolGroups["local-cli"] = localCliTools;
 }
 var {
   tools: allTools,
   unknownGroups,
-  unknownProfile
+  unknownProfile,
+  explicitTools,
+  profileWouldFilter
 } = filterTools(toolGroups, {
   tools: process.env.TAILSCALE_TOOLS,
   readonly: process.env.TAILSCALE_READONLY,
@@ -33698,14 +33774,14 @@ 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 localCliEnabled = process.env.TAILSCALE_LOCAL_CLI === "1" || process.env.TAILSCALE_LOCAL_CLI === "true";
-var filterSuffix = [
-  profileApplied ? `profile=${profileApplied}` : null,
-  process.env.TAILSCALE_TOOLS ? `groups=${process.env.TAILSCALE_TOOLS}` : null,
-  readonlyMode ? "readonly" : null,
-  localCliEnabled ? "local-cli=on" : null
-].filter(Boolean).join(", ");
+var filterSuffix = formatBannerFilterSuffix({
+  unknownProfile,
+  explicitTools,
+  profileWouldFilter,
+  profileEnv: process.env.TAILSCALE_PROFILE,
+  readonlyMode,
+  localCliEnabled
+});
 console.error(
   `@yawlabs/tailscale-mcp v${version2} ready (${allTools.length} tools${filterSuffix ? `, ${filterSuffix}` : ""})`
 );

package/package.json

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