@yawlabs/tailscale-mcp 0.12.9 → 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:
 

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");
@@ -33706,15 +33722,16 @@ var webhookTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.12.9" : 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);
   });
@@ -33724,7 +33741,7 @@ if (subcommand === "deploy-acl") {
   process.exit(0);
 } else if (subcommand !== void 0) {
   console.error(
-    `@yawlabs/tailscale-mcp: unrecognized argument "${subcommand}" -- known subcommands: deploy-acl, version. Starting the MCP server.`
+    `@yawlabs/tailscale-mcp: unrecognized argument "${subcommand}" -- known subcommands: deploy-acl, validate-acl, version. Starting the MCP server.`
   );
 }
 var toolGroups = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/tailscale-mcp",
-  "version": "0.12.9",
+  "version": "0.13.0",
   "mcpName": "io.github.YawLabs/tailscale-mcp",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",