@yawlabs/tailscale-mcp 0.9.1 → 0.10.2

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)
 
-**Ask your agent questions about your tailnet and have it act on the answers.** 88 tools + 4 resources covering the full [Tailscale v2 API](https://tailscale.com/api). Backed by 700+ unit tests and an opt-in live-tailnet integration suite.
+**Ask your agent questions about your tailnet and have it act on the answers.** 89 tools + 4 resources covering the full [Tailscale v2 API](https://tailscale.com/api). Backed by 700+ unit tests and an opt-in live-tailnet integration suite.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -107,7 +107,7 @@ That's it. Now ask your agent:
 
 ## Too many tools? Subset them.
 
-88 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:
+89 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)
 
@@ -120,9 +120,9 @@ That's it. Now ask your agent:
 }
 ```
 
-- **`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`** (88 tools, default) — everything. Same as omitting the env var.
+- **`minimal`** (20 tools) — `status`, `devices`, `audit`. Observe the tailnet, read the audit log.
+- **`core`** (47 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
+- **`full`** (89 tools, default) — everything. Same as omitting the env var.
 
 ### Option 2: `TAILSCALE_TOOLS` (explicit group list)
 
@@ -158,7 +158,7 @@ Set to `1` or `true` to drop every tool without `readOnlyHint: true`. Stacks wit
 The server logs the active filter to stderr on startup:
 
 ```
-@yawlabs/tailscale-mcp v0.9.1 ready (19 tools, profile=core, readonly)
+@yawlabs/tailscale-mcp v0.9.1 ready (20 tools, profile=minimal, readonly)
 ```
 
 If you don't set any filter, startup prints a tip pointing you at the profiles.
@@ -182,6 +182,23 @@ The server checks for an API key first, then falls back to OAuth. If neither is
 
 **Tailnet:** Uses your default tailnet automatically. Set `TAILSCALE_TAILNET` to specify one explicitly.
 
+## Reliability and debugging
+
+**429 retry (built-in).** API responses with HTTP 429 are retried up to 3 times, honoring the `Retry-After` header (both seconds-integer and HTTP-date forms). Falls back to exponential backoff with jitter, capped at 30s per wait. No env var needed — this is on by default. Workflows like "rotate every key older than 90 days" no longer fail mid-loop on Tailscale's per-tenant rate limits.
+
+**`TAILSCALE_DEBUG=1`** — log every HTTP method, URL, status, and elapsed time to stderr. Authorization headers are never logged. Use this when a tool returns an unexpected error and you want to see the actual request that went out. Example:
+
+```
+[tailscale-mcp] GET https://api.tailscale.com/api/v2/tailnet/-/devices
+[tailscale-mcp]   <- 200 (148ms)
+```
+
+**`TAILSCALE_MAX_CONCURRENT=N`** — cap in-flight API requests at `N`. Default is unlimited (no behavior change for users who don't opt in). Useful when an agent fans out aggressively against a tailnet that has stricter limits than the per-call retry can absorb.
+
+**`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.
+
+**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).
+
 ## Resources (4)
 
 MCP Resources expose read-only data clients can browse without a tool call.
@@ -205,7 +222,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 </details>
 
 <details>
-<summary><strong>Devices</strong> (16 tools)</summary>
+<summary><strong>Devices</strong> (17 tools)</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -213,6 +230,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | `tailscale_get_device` | Get detailed info for a specific device |
 | `tailscale_authorize_device` | Authorize a pending device |
 | `tailscale_deauthorize_device` | Deauthorize a device |
+| `tailscale_set_devices_authorized` | Authorize/deauthorize many devices in one call (parallel, per-id error reporting) |
 | `tailscale_delete_device` | Remove a device from the tailnet |
 | `tailscale_rename_device` | Rename a device |
 | `tailscale_expire_device` | Expire a device's key, forcing re-authentication |

package/dist/index.js

@@ -30116,20 +30116,31 @@ var StdioServerTransport = class {
 // src/api.ts
 var BASE_URL = "https://api.tailscale.com/api/v2";
 var REQUEST_TIMEOUT_MS = 3e4;
+var MAX_429_RETRIES = 3;
+var DEFAULT_429_DELAY_MS = 1e3;
+var MAX_429_DELAY_MS = 3e4;
+var MAX_REQUEST_BUDGET_MS = 9e4;
+var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE"]);
 var oauthToken = null;
 var oauthRefreshPromise = null;
 function getAuthConfig() {
   const apiKey = process.env.TAILSCALE_API_KEY;
   const oauthClientId = process.env.TAILSCALE_OAUTH_CLIENT_ID;
   const oauthClientSecret = process.env.TAILSCALE_OAUTH_CLIENT_SECRET;
-  if (apiKey) {
-    if (apiKey.trim() === "") {
+  if (apiKey !== void 0) {
+    const trimmedKey = apiKey.trim();
+    if (trimmedKey === "") {
       throw new Error("TAILSCALE_API_KEY is set but empty. Provide a valid API key.");
     }
-    return { kind: "apiKey", apiKey };
+    return { kind: "apiKey", apiKey: trimmedKey };
   }
-  if (oauthClientId && oauthClientSecret) {
-    return { kind: "oauth", clientId: oauthClientId, clientSecret: oauthClientSecret };
+  if (oauthClientId !== void 0 || oauthClientSecret !== void 0) {
+    const trimmedId = (oauthClientId ?? "").trim();
+    const trimmedSecret = (oauthClientSecret ?? "").trim();
+    if (trimmedId === "" || trimmedSecret === "") {
+      throw new Error("TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET must both be set and non-empty.");
+    }
+    return { kind: "oauth", clientId: trimmedId, clientSecret: trimmedSecret };
   }
   const hint = process.platform === "win32" ? ' On Windows, env vars set in bash/WSL profiles are not visible to MCP servers launched via cmd. Either add "env": {"TAILSCALE_API_KEY": "tskey-api-..."} to your .mcp.json, or set it as a Windows user environment variable.' : "";
   throw new Error(
@@ -30157,7 +30168,8 @@ async function getOAuthAccessToken(clientId, clientSecret) {
       });
       if (!res.ok) {
         const body = await res.text();
-        throw new Error(`OAuth token exchange failed (${res.status}): ${body}`);
+        const guidance = res.status === 401 || res.status === 403 ? " Verify TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET, and that the client has the scopes your tools need (https://login.tailscale.com/admin/settings/oauth)." : "";
+        throw new Error(`OAuth token exchange failed (${res.status}): ${body}.${guidance}`);
       }
       const data = await res.json();
       oauthToken = {
@@ -30218,6 +30230,77 @@ function formatAuthError(apiBody) {
   }
   return lines.join("\n");
 }
+function extractErrorMessage(body) {
+  if (!body) return body;
+  const trimmed = body.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return body;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object") {
+      const obj = parsed;
+      if (typeof obj.message === "string" && obj.message.length > 0) return obj.message;
+      if (typeof obj.error === "string" && obj.error.length > 0) return obj.error;
+    }
+  } catch {
+  }
+  return body;
+}
+var inFlight = 0;
+var concurrencyQueue = [];
+function getConcurrencyLimit() {
+  const raw = process.env.TAILSCALE_MAX_CONCURRENT;
+  if (!raw) return 0;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function getRequestBudgetMs() {
+  const raw = process.env.TAILSCALE_REQUEST_BUDGET_MS;
+  if (!raw) return MAX_REQUEST_BUDGET_MS;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : MAX_REQUEST_BUDGET_MS;
+}
+async function withConcurrencyLimit(fn) {
+  const limit = getConcurrencyLimit();
+  if (limit === 0) return fn();
+  if (inFlight >= limit) {
+    await new Promise((resolve) => concurrencyQueue.push(resolve));
+  }
+  inFlight++;
+  try {
+    return await fn();
+  } finally {
+    inFlight--;
+    const next = concurrencyQueue.shift();
+    if (next) next();
+  }
+}
+function debugLog(...parts) {
+  if (process.env.TAILSCALE_DEBUG === "1" || process.env.TAILSCALE_DEBUG === "true") {
+    console.error("[tailscale-mcp]", ...parts);
+  }
+}
+function compute429DelayMs(retryAfter, attempt) {
+  if (retryAfter) {
+    const asInt = Number.parseInt(retryAfter, 10);
+    if (Number.isFinite(asInt) && asInt >= 0) {
+      return Math.min(asInt * 1e3, MAX_429_DELAY_MS);
+    }
+    const asDate = Date.parse(retryAfter);
+    if (Number.isFinite(asDate)) {
+      return Math.max(0, Math.min(asDate - Date.now(), MAX_429_DELAY_MS));
+    }
+  }
+  const base = Math.min(DEFAULT_429_DELAY_MS * 2 ** attempt, MAX_429_DELAY_MS);
+  return base + Math.floor(Math.random() * 250);
+}
+async function executeFetch(method, url2, headers, body) {
+  return fetch(url2, {
+    method,
+    headers,
+    body,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+}
 async function apiRequest(method, path, body, options) {
   const auth = await getAuthHeader();
   const headers = {
@@ -30238,31 +30321,48 @@ async function apiRequest(method, path, body, options) {
     fetchBody = JSON.stringify(body);
   }
   const url2 = path.startsWith("http") ? path : `${BASE_URL}${path}`;
-  const res = await fetch(url2, {
-    method,
-    headers,
-    body: fetchBody,
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-  });
-  const etag = res.headers.get("etag") || void 0;
-  if (options?.acceptRaw) {
-    const rawBody = await res.text();
-    if (!res.ok) {
-      const error48 = res.status === 401 ? formatAuthError(rawBody) : rawBody;
-      return { ok: false, status: res.status, error: error48, rawBody, etag };
+  const startedAt = Date.now();
+  debugLog(`${method} ${url2}`);
+  const isRetryable = RETRYABLE_METHODS.has(method.toUpperCase());
+  const requestBudgetMs = getRequestBudgetMs();
+  return withConcurrencyLimit(async () => {
+    let res;
+    for (let attempt = 0; attempt <= MAX_429_RETRIES; attempt++) {
+      res = await executeFetch(method, url2, headers, fetchBody);
+      if (res.status !== 429 || attempt === MAX_429_RETRIES || !isRetryable) break;
+      const delay = compute429DelayMs(res.headers.get("retry-after"), attempt);
+      const elapsed2 = Date.now() - startedAt;
+      if (elapsed2 + delay + REQUEST_TIMEOUT_MS > requestBudgetMs) {
+        debugLog(`  -> 429 (attempt ${attempt + 1}), giving up: budget exhausted (${elapsed2}ms + ${delay}ms)`);
+        break;
+      }
+      debugLog(`  -> 429 (attempt ${attempt + 1}/${MAX_429_RETRIES + 1}), retrying in ${delay}ms`);
+      await res.text().catch(() => void 0);
+      await new Promise((r) => setTimeout(r, delay));
     }
-    return { ok: true, status: res.status, rawBody, etag };
-  }
-  if (!res.ok) {
-    const errorBody = await res.text();
-    const error48 = res.status === 401 ? formatAuthError(errorBody) : errorBody;
-    return { ok: false, status: res.status, error: error48, etag };
-  }
-  if (res.status === 204 || res.headers.get("content-length") === "0") {
-    return { ok: true, status: res.status, etag };
-  }
-  const data = await res.json();
-  return { ok: true, status: res.status, data, etag };
+    const response = res;
+    const etag = response.headers.get("etag") || void 0;
+    const elapsed = Date.now() - startedAt;
+    debugLog(`  <- ${response.status} (${elapsed}ms)`);
+    if (options?.acceptRaw) {
+      const rawBody = await response.text();
+      if (!response.ok) {
+        const error48 = response.status === 401 ? formatAuthError(rawBody) : extractErrorMessage(rawBody);
+        return { ok: false, status: response.status, error: error48, rawBody, etag };
+      }
+      return { ok: true, status: response.status, rawBody, etag };
+    }
+    if (!response.ok) {
+      const errorBody = await response.text();
+      const error48 = response.status === 401 ? formatAuthError(errorBody) : extractErrorMessage(errorBody);
+      return { ok: false, status: response.status, error: error48, etag };
+    }
+    if (response.status === 204 || response.headers.get("content-length") === "0") {
+      return { ok: true, status: response.status, etag };
+    }
+    const data = await response.json();
+    return { ok: true, status: response.status, data, etag };
+  });
 }
 async function apiGet(path, options) {
   return apiRequest("GET", path, void 0, options);
@@ -30270,14 +30370,14 @@ async function apiGet(path, options) {
 async function apiPost(path, body, options) {
   return apiRequest("POST", path, body, options);
 }
-async function apiPut(path, body) {
-  return apiRequest("PUT", path, body);
+async function apiPut(path, body, options) {
+  return apiRequest("PUT", path, body, options);
 }
-async function apiPatch(path, body) {
-  return apiRequest("PATCH", path, body);
+async function apiPatch(path, body, options) {
+  return apiRequest("PATCH", path, body, options);
 }
-async function apiDelete(path) {
-  return apiRequest("DELETE", path);
+async function apiDelete(path, options) {
+  return apiRequest("DELETE", path, void 0, options);
 }
 
 // src/cli.ts
@@ -30332,7 +30432,7 @@ function filterTools(groups, options) {
   let unknownProfile2;
   if (options.profile) {
     const profileKey = options.profile.trim().toLowerCase();
-    if (profileKey in PROFILES) {
+    if (Object.hasOwn(PROFILES, profileKey)) {
       const preset = PROFILES[profileKey];
       profileGroups = preset.length > 0 ? [...preset] : void 0;
     } else {
@@ -30378,14 +30478,14 @@ var aclTools = [
         accept: "application/hujson"
       });
       if (res.ok && res.etag) {
-        return {
-          ...res,
-          rawBody: `${res.rawBody}
-
----
-ETag: ${res.etag}
-Pass this ETag to tailscale_update_acl when updating the policy.`
-        };
+        const footer = [
+          "",
+          `// ETag: ${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;
     }
@@ -30472,8 +30572,28 @@ Pass this ETag to tailscale_update_acl when updating the policy.`
 // src/tools/audit.ts
 function assertRFC3339(value, label) {
   const rfc3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+  const err = () => new Error(`${label} must be a valid RFC3339 date-time (e.g. '2026-04-01T00:00:00Z'), got: '${value}'`);
   if (!rfc3339.test(value) || Number.isNaN(Date.parse(value))) {
-    throw new Error(`${label} must be a valid RFC3339 date-time (e.g. '2026-04-01T00:00:00Z'), got: '${value}'`);
+    throw err();
+  }
+  const dateOnly = value.slice(0, 10);
+  const [y, m, d] = dateOnly.split("-").map(Number);
+  const utc = /* @__PURE__ */ new Date(`${dateOnly}T00:00:00Z`);
+  if (Number.isNaN(utc.getTime()) || utc.getUTCFullYear() !== y || utc.getUTCMonth() + 1 !== m || utc.getUTCDate() !== d) {
+    throw err();
+  }
+}
+var MAX_LOG_RANGE_MS = 30 * 24 * 60 * 60 * 1e3;
+function assertLogRange(start, end, label) {
+  const startMs = Date.parse(start);
+  const endMs = end ? Date.parse(end) : Date.now();
+  if (endMs < startMs) {
+    throw new Error(`${label}: end must be >= start. start=${start} end=${end ?? "<now>"}`);
+  }
+  if (endMs - startMs > MAX_LOG_RANGE_MS) {
+    throw new Error(
+      `${label}: range exceeds the 30-day Tailscale API limit. start=${start} end=${end ?? "<now>"}. Split the query into <=30-day windows.`
+    );
   }
 }
 var auditTools = [
@@ -30494,6 +30614,7 @@ var auditTools = [
     handler: async (input) => {
       assertRFC3339(input.start, "start");
       if (input.end) assertRFC3339(input.end, "end");
+      assertLogRange(input.start, input.end, "tailscale_get_audit_log");
       const params = new URLSearchParams({ start: input.start });
       if (input.end) params.set("end", input.end);
       return apiGet(`/tailnet/${getTailnet()}/logging/configuration?${params}`);
@@ -30516,6 +30637,7 @@ var auditTools = [
     handler: async (input) => {
       assertRFC3339(input.start, "start");
       if (input.end) assertRFC3339(input.end, "end");
+      assertLogRange(input.start, input.end, "tailscale_get_network_flow_logs");
       const params = new URLSearchParams({ start: input.start });
       if (input.end) params.set("end", input.end);
       return apiGet(`/tailnet/${getTailnet()}/logging/network?${params}`);
@@ -30687,7 +30809,16 @@ var deviceTools = [
     },
     inputSchema: external_exports3.object({
       deviceId: external_exports3.string().describe("The device ID"),
-      routes: external_exports3.array(external_exports3.string()).describe(
+      routes: external_exports3.array(
+        external_exports3.string().refine(
+          // Accept v4 (10.0.0.0/24) or v6 (fd7a:115c::/48) CIDRs. Routes can be either.
+          // Loose check: must contain a '/' followed by 1-3 digits, and the address part
+          // must look like an IPv4 quad-dotted or an IPv6 colon-form. The Tailscale API
+          // is the authoritative validator; this just rejects obvious typos client-side.
+          (s) => /^([\d.]+|[\da-fA-F:]+)\/\d{1,3}$/.test(s),
+          { message: "must be a CIDR (e.g. '10.0.0.0/24' or 'fd7a:115c::/48')" }
+        )
+      ).describe(
         "Full list of CIDR routes to enable (e.g. ['10.0.0.0/24', '192.168.1.0/24']). Replaces existing enabled routes."
       )
     }),
@@ -30791,7 +30922,7 @@ var deviceTools = [
     },
     inputSchema: external_exports3.object({
       deviceId: external_exports3.string().describe("The device ID"),
-      ipv4: external_exports3.string().describe("The new Tailscale IPv4 address for the device (e.g. '100.64.0.1')")
+      ipv4: external_exports3.string().ipv4().describe("The new Tailscale IPv4 address for the device (e.g. '100.64.0.1')")
     }),
     handler: async (input) => {
       return apiPost(`/device/${encPath(input.deviceId)}/ip`, { ipv4: input.ipv4 });
@@ -30817,6 +30948,48 @@ var deviceTools = [
       });
     }
   },
+  {
+    name: "tailscale_set_devices_authorized",
+    description: "Authorize or deauthorize multiple devices in one call. Each device's POST runs in parallel; per-device errors are returned alongside the successes so a partial failure doesn't lose the work that succeeded. Common use: authorize a batch of newly-enrolled CI hosts, or deauthorize a group of devices flagged by a security review.",
+    annotations: {
+      title: "Set devices authorized (bulk)",
+      readOnlyHint: false,
+      // Deauthorize is destructive; authorize is not. Mark destructive so MCP
+      // clients gate the bulk call the safer way.
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      deviceIds: external_exports3.array(external_exports3.string().min(1)).min(1).describe("Device IDs to update"),
+      authorized: external_exports3.boolean().describe("true to authorize, false to deauthorize")
+    }),
+    handler: async (input) => {
+      const unique = [...new Set(input.deviceIds)];
+      const results = await Promise.all(
+        unique.map(async (deviceId) => {
+          const res = await apiPost(`/device/${encPath(deviceId)}/authorized`, { authorized: input.authorized });
+          return { deviceId, res };
+        })
+      );
+      const succeeded = [];
+      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}` };
+      }
+      const failedCount = Object.keys(failed).length;
+      if (failedCount === unique.length) {
+        const first = Object.values(failed)[0];
+        return {
+          ok: false,
+          status: first.status,
+          error: `All ${failedCount} device updates failed: ${JSON.stringify(failed)}`
+        };
+      }
+      return { ok: true, status: 200, data: { authorized: input.authorized, succeeded, failed } };
+    }
+  },
   {
     name: "tailscale_batch_update_posture_attributes",
     description: "Batch update custom posture attributes across multiple devices. Each attribute key must start with 'custom:'. Uses JSON Merge Patch semantics \u2014 pass null as the attribute config to delete.",
@@ -31055,6 +31228,9 @@ var dnsTools = [
       for (const [key, value] of Object.entries(input)) {
         if (value !== void 0) body[key] = value;
       }
+      if (Object.keys(body).length === 0) {
+        throw new Error("No fields to update. Provide at least one of: dns, searchPaths, splitDns, magicDNS.");
+      }
       return apiPost(`/tailnet/${getTailnet()}/dns/configuration`, body);
     }
   }
@@ -31094,7 +31270,7 @@ var inviteTools = [
       deviceId: external_exports3.string().describe("The device ID to create an invite for"),
       multiUse: external_exports3.boolean().optional().describe("Whether the invite can be used more than once (default: false)"),
       allowExitNode: external_exports3.boolean().optional().describe("Whether the invited device can be used as an exit node (default: false)"),
-      email: external_exports3.string().optional().describe("Email address to send the invite to")
+      email: external_exports3.string().email().optional().describe("Email address to send the invite to")
     }),
     handler: async (input) => {
       const body = {};
@@ -31182,7 +31358,7 @@ var inviteTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      email: external_exports3.string().optional().describe("Email address to send the invite to"),
+      email: external_exports3.string().email().optional().describe("Email address to send the invite to"),
       role: external_exports3.enum(["member", "admin", "it-admin", "network-admin", "billing-admin", "auditor"]).optional().describe("Role to assign to the invited user (default: member)")
     }),
     handler: async (input) => {
@@ -31233,7 +31409,8 @@ var inviteTools = [
       title: "Resend device invite",
       readOnlyHint: false,
       destructiveHint: false,
-      idempotentHint: true,
+      // Each call delivers a separate email to the recipient.
+      idempotentHint: false,
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
@@ -31250,7 +31427,8 @@ var inviteTools = [
       title: "Resend user invite",
       readOnlyHint: false,
       destructiveHint: false,
-      idempotentHint: true,
+      // Each call delivers a separate email to the recipient.
+      idempotentHint: false,
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
@@ -31343,7 +31521,10 @@ var keyTools = [
       }
       const body = {};
       if (keyType !== "auth") body.keyType = keyType;
-      if (input.description !== void 0) body.description = sanitizeDescription(input.description);
+      if (input.description !== void 0) {
+        const sanitized = sanitizeDescription(input.description);
+        if (sanitized.length > 0) body.description = sanitized;
+      }
       if (keyType === "auth") {
         body.capabilities = {
           devices: {
@@ -31414,7 +31595,10 @@ var keyTools = [
     handler: async (input) => {
       validateTags(input.tags);
       const body = {};
-      if (input.description !== void 0) body.description = sanitizeDescription(input.description);
+      if (input.description !== void 0) {
+        const sanitized = sanitizeDescription(input.description);
+        if (sanitized.length > 0) body.description = sanitized;
+      }
       if (input.scopes !== void 0) body.scopes = input.scopes;
       if (input.tags !== void 0) body.tags = input.tags;
       if (input.issuer !== void 0) body.issuer = input.issuer;
@@ -31498,7 +31682,7 @@ var logStreamingTools = [
       url: external_exports3.string().optional().describe("Destination URL (required for non-s3 destinations)"),
       token: external_exports3.string().optional().describe("Authentication token or API key for the destination"),
       user: external_exports3.string().optional().describe("Username for the destination (if required)"),
-      uploadPeriodMinutes: external_exports3.number().optional().describe("Minutes to wait between uploads (max 1440). Optional."),
+      uploadPeriodMinutes: external_exports3.number().int().positive().max(1440).optional().describe("Minutes to wait between uploads (1-1440). Optional."),
       compressionFormat: external_exports3.enum(["zstd", "gzip", "none"]).optional().describe("Compression algorithm for log uploads. Defaults to 'none'."),
       s3Bucket: external_exports3.string().optional().describe("(s3 only) S3 bucket name. Required when destinationType is 's3'."),
       s3Region: external_exports3.string().optional().describe("(s3 only) AWS region of the S3 bucket. Required when destinationType is 's3'."),
@@ -31513,6 +31697,30 @@ var logStreamingTools = [
       )
     }),
     handler: async (input) => {
+      if (input.destinationType === "s3") {
+        const missing = [];
+        if (!input.s3Bucket) missing.push("s3Bucket");
+        if (!input.s3Region) missing.push("s3Region");
+        if (!input.s3AuthenticationType) missing.push("s3AuthenticationType");
+        if (input.s3AuthenticationType === "accesskey") {
+          if (!input.s3AccessKeyId) missing.push("s3AccessKeyId");
+          if (!input.s3SecretAccessKey) missing.push("s3SecretAccessKey");
+        } else if (input.s3AuthenticationType === "rolearn") {
+          if (!input.s3RoleArn) missing.push("s3RoleArn");
+        }
+        if (missing.length > 0) {
+          throw new Error(
+            `destinationType 's3' requires: ${missing.join(", ")}. For 'rolearn' auth, call tailscale_create_aws_external_id first to get the external ID for your IAM role trust policy.`
+          );
+        }
+      } else {
+        const missing = [];
+        if (!input.url) missing.push("url");
+        if (!input.token) missing.push("token");
+        if (missing.length > 0) {
+          throw new Error(`destinationType '${input.destinationType}' requires: ${missing.join(", ")}.`);
+        }
+      }
       const { logType, ...body } = input;
       const cleanBody = {};
       for (const [key, value] of Object.entries(body)) {
@@ -31711,7 +31919,7 @@ var postureTools = [
 var serviceTools = [
   {
     name: "tailscale_list_services",
-    description: "List all Tailscale Services in your tailnet. Services provide stable MagicDNS names and virtual IPs, decoupled from individual devices.",
+    description: "List all Tailscale Services in your tailnet. Services provide stable MagicDNS names and virtual IPs, decoupled from individual devices. Note: services are created implicitly when a node first advertises one (`tailscale up --advertise-services=svc:name`); there is no API endpoint to create a service from this MCP. Use the update/delete/approval tools here once the service exists.",
     annotations: {
       title: "List services",
       readOnlyHint: true,
@@ -31957,7 +32165,7 @@ var tailnetTools = [
   },
   {
     name: "tailscale_set_contacts",
-    description: "Update tailnet contact information.",
+    description: "Update tailnet contact information. Each provided contact type (account/support/security) is PATCHed in parallel; per-type errors are returned alongside the successes so a partial failure doesn't lose the work that succeeded. On partial failure the response is data: { applied, failed } -- inspect data.failed for per-type error details.",
     annotations: {
       title: "Set contacts",
       readOnlyHint: false,
@@ -31966,17 +32174,24 @@ var tailnetTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      account: external_exports3.object({ email: external_exports3.string() }).optional().describe("Account contact email"),
-      support: external_exports3.object({ email: external_exports3.string() }).optional().describe("Support contact email"),
-      security: external_exports3.object({ email: external_exports3.string() }).optional().describe("Security contact email")
+      account: external_exports3.object({ email: external_exports3.string().email() }).optional().describe("Account contact email"),
+      support: external_exports3.object({ email: external_exports3.string().email() }).optional().describe("Support contact email"),
+      security: external_exports3.object({ email: external_exports3.string().email() }).optional().describe("Security contact email")
     }),
     handler: async (input) => {
+      const types = ["account", "support", "security"].filter((t) => input[t] !== void 0);
+      const results = await Promise.all(
+        types.map(async (contactType) => {
+          const res = await apiPatch(
+            `/tailnet/${getTailnet()}/contacts/${encPath(contactType)}`,
+            input[contactType]
+          );
+          return { contactType, res };
+        })
+      );
       const applied = {};
       const failed = {};
-      for (const contactType of ["account", "support", "security"]) {
-        const value = input[contactType];
-        if (value === void 0) continue;
-        const res = await apiPatch(`/tailnet/${getTailnet()}/contacts/${encPath(contactType)}`, value);
+      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}` };
       }
@@ -31999,7 +32214,8 @@ var tailnetTools = [
       title: "Resend contact verification",
       readOnlyHint: false,
       destructiveHint: false,
-      idempotentHint: true,
+      // Each call sends a separate verification email.
+      idempotentHint: false,
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
@@ -32205,8 +32421,8 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      endpointUrl: external_exports3.string().describe("The URL to send webhook events to"),
-      subscriptions: external_exports3.array(external_exports3.enum(webhookEventTypes)).describe("Event types to subscribe to")
+      endpointUrl: external_exports3.string().url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://").describe("The HTTPS URL to send webhook events to"),
+      subscriptions: external_exports3.array(external_exports3.enum(webhookEventTypes)).min(1).describe("Event types to subscribe to (at least one)")
     }),
     handler: async (input) => {
       return apiPost(`/tailnet/${getTailnet()}/webhooks`, {
@@ -32227,8 +32443,8 @@ var webhookTools = [
     },
     inputSchema: external_exports3.object({
       webhookId: external_exports3.string().describe("The webhook ID to update"),
-      endpointUrl: external_exports3.string().optional().describe("New URL to send webhook events to"),
-      subscriptions: external_exports3.array(external_exports3.enum(webhookEventTypes)).optional().describe("Updated list of event types to subscribe to")
+      endpointUrl: external_exports3.string().url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://").optional().describe("New HTTPS URL to send webhook events to"),
+      subscriptions: external_exports3.array(external_exports3.enum(webhookEventTypes)).min(1).optional().describe("Updated list of event types to subscribe to (at least one)")
     }),
     handler: async (input) => {
       const body = {};
@@ -32281,7 +32497,9 @@ var webhookTools = [
       title: "Test webhook",
       readOnlyHint: false,
       destructiveHint: false,
-      idempotentHint: true,
+      // Each invocation delivers a separate test event to the endpoint —
+      // not idempotent in the strict sense.
+      idempotentHint: false,
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
@@ -32294,7 +32512,7 @@ var webhookTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.9.1" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.10.2" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "deploy-acl") {
   const filePath = process.argv[3];
@@ -32468,9 +32686,10 @@ var filterSuffix = [
 console.error(
   `@yawlabs/tailscale-mcp v${version2} ready (${allTools.length} tools${filterSuffix ? `, ${filterSuffix}` : ""})`
 );
-if (!filterSuffix) {
+var hasCreds = !!process.env.TAILSCALE_API_KEY || !!process.env.TAILSCALE_OAUTH_CLIENT_ID && !!process.env.TAILSCALE_OAUTH_CLIENT_SECRET;
+if (!filterSuffix && hasCreds) {
   console.error(
-    "@yawlabs/tailscale-mcp: tip \u2014 set TAILSCALE_PROFILE=core (46 tools) or =minimal (19) to load a smaller tool surface. See README."
+    "@yawlabs/tailscale-mcp: tip \u2014 set TAILSCALE_PROFILE=core (47 tools) or =minimal (20) 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.9.1",
+  "version": "0.10.2",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
@@ -28,13 +28,14 @@
   ],
   "scripts": {
     "build": "tsc && node build.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "test": "npm run build && node --test dist/**/*.test.js",
     "test:ci": "npm run test",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {},
   "overrides": {