@yawlabs/tailscale-mcp 0.12.8 → 0.13.0

package/README.md

@@ -454,10 +454,47 @@ MCP Resources expose read-only data clients can browse without a tool call.
 For the simple "deploy ACL from git on merge" workflow, you don't need an MCP server or an agent — use the built-in CLI:
 
 ```bash
+# PR check: validate the proposed policy without touching the tailnet
+npx -y @yawlabs/tailscale-mcp@latest validate-acl tailscale/acl.json
+
+# On merge: ETag fetch + validate + deploy with If-Match, fail-closed at every step
 npx -y @yawlabs/tailscale-mcp@latest deploy-acl tailscale/acl.json
 ```
 
-Handles ETag fetching, validation, and deployment in one command. Works in any CI system. Set `TAILSCALE_API_KEY` and `TAILSCALE_TAILNET` as env vars.
+Works in any CI system. Set `TAILSCALE_API_KEY` and `TAILSCALE_TAILNET` as env vars. Both commands exit non-zero on any failure; `deploy-acl` refuses to deploy without an ETag (so a concurrent Admin Console edit can never be silently clobbered) and reports a 412 as a concurrent-edit conflict you resolve by re-running.
+
+A complete GitHub Actions workflow — validate on PR, deploy on merge:
+
+```yaml
+name: tailscale-acl
+on:
+  pull_request:
+    paths: ["tailscale/acl.json"]
+  push:
+    branches: [main]
+    paths: ["tailscale/acl.json"]
+
+jobs:
+  acl:
+    runs-on: ubuntu-latest
+    env:
+      TAILSCALE_API_KEY: ${{ secrets.TAILSCALE_API_KEY }}
+      TAILSCALE_TAILNET: your-tailnet.ts.net # or omit: defaults to the key's tailnet
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Validate ACL
+        if: github.event_name == 'pull_request'
+        run: npx -y @yawlabs/tailscale-mcp@latest validate-acl tailscale/acl.json
+      - name: Deploy ACL
+        if: github.event_name == 'push'
+        run: npx -y @yawlabs/tailscale-mcp@latest deploy-acl tailscale/acl.json
+```
+
+For reproducible deploys, replace `@latest` with a pinned version.
+
+> **If you hand-roll this with `curl` instead:** Tailscale's ACL endpoint only returns the `ETag` header on **GET**, not HEAD. A `curl -I` (HEAD) ETag fetch silently yields an empty value — and an empty `If-Match` either deploys unguarded (clobbering concurrent edits) or trips your guard and fails the deploy. Fetch the ETag with a GET (`curl -fsS -D - -o /dev/null ...`), and fail the job if it comes back empty. The CLI above does all of this for you.
 
 **Optional:** Lock the Admin Console to prevent manual edits that drift from git. Ask your agent:
 
@@ -467,7 +504,7 @@ This shows a read-only banner in the Tailscale Admin Console pointing to your re
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 20+ to run the server (22+ to develop — the test script passes a glob to `node --test`, supported from Node 21)
 - A Tailscale API key or OAuth client credentials
 
 ## Contributing

package/dist/index.js

@@ -31264,19 +31264,15 @@ function parseValidationError(rawBody) {
   if (typeof obj.error === "string" && obj.error.length > 0) return obj.error;
   return void 0;
 }
-async function deployAcl(filePath) {
-  let policy;
+function readPolicyFile(filePath) {
   try {
-    policy = readFileSync(filePath, "utf-8");
+    return readFileSync(filePath, "utf-8");
   } catch (err) {
     console.error(`Failed to read ${filePath}: ${err instanceof Error ? err.message : err}`);
     process.exit(1);
   }
-  const getRes = await apiGet(`/tailnet/${getTailnet()}/acl`, { acceptRaw: true, accept: "application/hujson" });
-  if (!getRes.ok || !getRes.etag) {
-    console.error(`Failed to get current ACL: ${getRes.error || "no ETag returned"}`);
-    process.exit(1);
-  }
+}
+async function validatePolicy(policy) {
   const validateRes = await apiPost(`/tailnet/${getTailnet()}/acl/validate`, void 0, {
     rawBody: policy,
     contentType: "application/hujson",
@@ -31292,6 +31288,20 @@ async function deployAcl(filePath) {
     console.error(`ACL validation failed: ${validationError}`);
     process.exit(1);
   }
+}
+async function validateAcl(filePath) {
+  const policy = readPolicyFile(filePath);
+  await validatePolicy(policy);
+  console.log("ACL policy is valid");
+}
+async function deployAcl(filePath) {
+  const policy = readPolicyFile(filePath);
+  const getRes = await apiGet(`/tailnet/${getTailnet()}/acl`, { acceptRaw: true, accept: "application/hujson" });
+  if (!getRes.ok || !getRes.etag) {
+    console.error(`Failed to get current ACL: ${getRes.error || "no ETag returned"}`);
+    process.exit(1);
+  }
+  await validatePolicy(policy);
   const deployRes = await apiPost(`/tailnet/${getTailnet()}/acl`, void 0, {
     rawBody: policy,
     contentType: "application/hujson",
@@ -31300,7 +31310,13 @@ async function deployAcl(filePath) {
     accept: "application/hujson"
   });
   if (!deployRes.ok) {
-    console.error(`ACL deploy failed: ${deployRes.error}`);
+    if (deployRes.status === 412) {
+      console.error(
+        `ACL deploy failed: the tailnet ACL changed between the ETag fetch and the deploy (concurrent edit). Re-run to retry against the current version. (${deployRes.error})`
+      );
+    } else {
+      console.error(`ACL deploy failed: ${deployRes.error}`);
+    }
     process.exit(1);
   }
   console.log("ACL deployed successfully");
@@ -31959,7 +31975,7 @@ var deviceTools = [
     },
     inputSchema: external_exports.object({
       deviceId: external_exports.string().describe("The device ID"),
-      ipv4: external_exports.string().ipv4().describe("The new Tailscale IPv4 address for the device (e.g. '100.64.0.1')")
+      ipv4: external_exports.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 });
@@ -33551,7 +33567,7 @@ function getAllowedWebhookEvents() {
   const extras = raw.split(",").map((s) => s.trim()).filter(Boolean);
   return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...extras]);
 }
-var endpointUrlSchema = external_exports.string().url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://");
+var endpointUrlSchema = external_exports.url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://");
 var webhookSubscriptionsSchema = external_exports.array(external_exports.string()).min(1).superRefine((arr, ctx) => {
   const allowed = getAllowedWebhookEvents();
   let knownEventsList = null;
@@ -33706,15 +33722,16 @@ var webhookTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.12.8" : resolveVersionFallback();
+var version2 = true ? "0.13.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
-if (subcommand === "deploy-acl") {
+if (subcommand === "deploy-acl" || subcommand === "validate-acl") {
   const filePath = process.argv[3];
   if (!filePath) {
-    console.error("Usage: tailscale-mcp deploy-acl <path-to-acl.json>");
+    console.error(`Usage: tailscale-mcp ${subcommand} <path-to-acl.json>`);
     process.exit(1);
   }
-  await deployAcl(filePath).catch((err) => {
+  const run = subcommand === "deploy-acl" ? deployAcl : validateAcl;
+  await run(filePath).catch((err) => {
     console.error(`Fatal: ${err instanceof Error ? err.message : err}`);
     process.exit(1);
   });
@@ -33722,6 +33739,10 @@ if (subcommand === "deploy-acl") {
 } else if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
   process.exit(0);
+} else if (subcommand !== void 0) {
+  console.error(
+    `@yawlabs/tailscale-mcp: unrecognized argument "${subcommand}" -- known subcommands: deploy-acl, validate-acl, version. Starting the MCP server.`
+  );
 }
 var toolGroups = {
   status: statusTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.12.8",
+  "version": "0.13.0",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "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": "npm run build && node --test \"dist/**/*.test.js\"",
     "test:ci": "npm run test",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
@@ -40,10 +40,11 @@
   },
   "dependencies": {},
   "overrides": {
-    "hono": "^4.12.18",
+    "hono": "^4.12.21",
     "@hono/node-server": "^1.19.13",
     "fast-uri": "^3.1.2",
-    "ip-address": "^10.1.1"
+    "ip-address": "^10.1.1",
+    "qs": "^6.15.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
@@ -55,5 +56,12 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22",
+      "onFail": "error"
+    }
   }
 }