@yawlabs/tailscale-mcp 0.9.0 → 0.10.1

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.0 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,21 @@ 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.
+
+**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 +220,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 +228,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,6 +30116,9 @@ 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 oauthToken = null;
 var oauthRefreshPromise = null;
 function getAuthConfig() {
@@ -30157,7 +30160,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 +30222,71 @@ 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;
+}
+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 +30307,41 @@ 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 startedAt = Date.now();
+  debugLog(`${method} ${url2}`);
+  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) break;
+      const delay = compute429DelayMs(res.headers.get("retry-after"), attempt);
+      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));
+    }
+    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 };
   });
-  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 };
-    }
-    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 };
 }
 async function apiGet(path, options) {
   return apiRequest("GET", path, void 0, options);
@@ -30270,14 +30349,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
@@ -30378,14 +30457,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;
     }
@@ -30476,6 +30555,19 @@ function assertRFC3339(value, label) {
     throw new Error(`${label} must be a valid RFC3339 date-time (e.g. '2026-04-01T00:00:00Z'), got: '${value}'`);
   }
 }
+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 = [
   {
     name: "tailscale_get_audit_log",
@@ -30494,6 +30586,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 +30609,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 +30781,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 +30894,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 +30920,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.",
@@ -31094,7 +31239,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 +31327,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 +31378,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 +31396,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({
@@ -31284,16 +31431,16 @@ var keyTools = [
   },
   {
     name: "tailscale_get_key",
-    description: "Get details for a specific auth key.",
+    description: "Get details for a specific key (auth key, OAuth client, or federated identity).",
     annotations: {
-      title: "Get auth key",
+      title: "Get key",
       readOnlyHint: true,
       destructiveHint: false,
       idempotentHint: true,
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      keyId: external_exports3.string().describe("The auth key ID")
+      keyId: external_exports3.string().describe("The key ID (auth key, OAuth client, or federated identity)")
     }),
     handler: async (input) => {
       return apiGet(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`);
@@ -31343,7 +31490,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: {
@@ -31376,16 +31526,16 @@ var keyTools = [
   },
   {
     name: "tailscale_delete_key",
-    description: "Delete an auth key. This is irreversible \u2014 devices already authenticated with this key are unaffected, but no new devices can use it.",
+    description: "Delete a key (auth key, OAuth client, or federated identity). This is irreversible. For auth keys, devices already authenticated are unaffected but no new devices can use it. For OAuth clients and federated identities, any integrations using them lose access immediately.",
     annotations: {
-      title: "Delete auth key",
+      title: "Delete key",
       readOnlyHint: false,
       destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      keyId: external_exports3.string().describe("The auth key ID to delete")
+      keyId: external_exports3.string().describe("The key ID to delete (auth key, OAuth client, or federated identity)")
     }),
     handler: async (input) => {
       return apiDelete(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`);
@@ -31414,7 +31564,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;
@@ -31433,7 +31586,7 @@ var keyTools = [
 var logStreamingTools = [
   {
     name: "tailscale_list_log_stream_configs",
-    description: "List all log streaming configurations for your tailnet. Fetches both 'configuration' (audit) and 'network' (flow) log stream configs. Log streaming sends logs to external destinations like Axiom, Datadog, Splunk, Elasticsearch, S3, or GCS.",
+    description: "List all log streaming configurations for your tailnet. Fetches both 'configuration' (audit) and 'network' (flow) log stream configs. Log streaming sends logs to external destinations like Axiom, Datadog, Splunk, Elasticsearch, or S3.",
     annotations: {
       title: "List log stream configs",
       readOnlyHint: true,
@@ -31484,7 +31637,7 @@ var logStreamingTools = [
   },
   {
     name: "tailscale_set_log_stream_config",
-    description: "Set the log streaming configuration for a specific log type. Configures where logs are sent (e.g. Axiom, Datadog, Splunk, Elasticsearch, S3, GCS).",
+    description: "Set the log streaming configuration for a specific log type. Configures where logs are sent (e.g. Axiom, Datadog, Splunk, Elasticsearch, S3).\n\nPer-destination required fields:\n- splunk / elastic / panther / cribl / datadog / axiom: url + token (user optional)\n- s3: s3Bucket + s3Region + s3AuthenticationType, plus either (s3AccessKeyId + s3SecretAccessKey) for 'accesskey' auth or s3RoleArn for 'rolearn' auth. Call tailscale_create_aws_external_id first when using 'rolearn'.",
     annotations: {
       title: "Set log stream config",
       readOnlyHint: false,
@@ -31494,12 +31647,49 @@ var logStreamingTools = [
     },
     inputSchema: external_exports3.object({
       logType: external_exports3.enum(["configuration", "network"]).describe("The log type: 'configuration' for audit logs, 'network' for network flow logs"),
-      destinationType: external_exports3.enum(["splunk", "elastic", "panther", "cribl", "datadog", "axiom", "s3", "gcs"]).describe("The log streaming destination type"),
-      url: external_exports3.string().optional().describe("Destination URL (required for most destination types)"),
+      destinationType: external_exports3.enum(["splunk", "elastic", "panther", "cribl", "datadog", "axiom", "s3"]).describe("The log streaming destination type"),
+      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)")
+      user: external_exports3.string().optional().describe("Username for the destination (if required)"),
+      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'."),
+      s3KeyPrefix: external_exports3.string().optional().describe("(s3 only) Optional prefix prepended to the auto-generated S3 object key."),
+      s3AuthenticationType: external_exports3.enum(["accesskey", "rolearn"]).optional().describe(
+        "(s3 only) Authentication mode. Required when destinationType is 's3'. Tailscale recommends 'rolearn'."
+      ),
+      s3AccessKeyId: external_exports3.string().optional().describe("(s3 only) AWS access key id. Required when s3AuthenticationType is 'accesskey'."),
+      s3SecretAccessKey: external_exports3.string().optional().describe("(s3 only) AWS secret access key. Required when s3AuthenticationType is 'accesskey'."),
+      s3RoleArn: external_exports3.string().optional().describe(
+        "(s3 only) IAM role ARN that Tailscale will assume. Required when s3AuthenticationType is 'rolearn'."
+      )
     }),
     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)) {
@@ -31698,7 +31888,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,
@@ -31953,17 +32143,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}` };
       }
@@ -31986,7 +32183,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({
@@ -32192,7 +32390,7 @@ var webhookTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      endpointUrl: external_exports3.string().describe("The URL to send webhook events 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)).describe("Event types to subscribe to")
     }),
     handler: async (input) => {
@@ -32214,7 +32412,7 @@ 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"),
+      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)).optional().describe("Updated list of event types to subscribe to")
     }),
     handler: async (input) => {
@@ -32268,7 +32466,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({
@@ -32281,7 +32481,7 @@ var webhookTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.9.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.10.1" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "deploy-acl") {
   const filePath = process.argv[3];
@@ -32455,9 +32655,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.0",
+  "version": "0.10.1",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",