@yawlabs/tailscale-mcp 0.10.9 → 0.11.0

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.** 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.
+**Ask your agent questions about your tailnet and have it act on the answers.** 89 admin-API tools + 4 optional local-CLI diagnostics + 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).
 
@@ -137,7 +137,7 @@ That's it. Now ask your agent:
 
 Comma-separated group names. Overrides `TAILSCALE_PROFILE` when both are set — use this when the presets aren't quite right.
 
-Valid group names: `status`, `devices`, `acl`, `dns`, `keys`, `users`, `tailnet`, `webhooks`, `posture`, `audit`, `invites`, `services`, `log-streaming`.
+Valid group names: `status`, `devices`, `acl`, `dns`, `keys`, `users`, `tailnet`, `webhooks`, `posture`, `audit`, `invites`, `services`, `log-streaming`. The `local-cli` group is also available, but only when `TAILSCALE_LOCAL_CLI=1` is set — see [Local CLI integration](#local-cli-integration-opt-in).
 
 ### Option 3: `TAILSCALE_READONLY` (drop mutations)
 
@@ -199,6 +199,23 @@ The server checks for an API key first, then falls back to OAuth. If neither is
 
 **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)
+
+Most tools talk to the Tailscale v2 admin API — they describe **the tailnet**. Sometimes you want to ask about **this machine's** view: is it actually connected? What DERP region is it on? How far is `my-laptop` from here? Those answers come from the local `tailscale` binary, not the admin API.
+
+Set `TAILSCALE_LOCAL_CLI=1` (in your shell or `.mcp.json` `env` block) to add four read-only diagnostic tools:
+
+| Tool | Equivalent CLI command | Use it for |
+|---|---|---|
+| `tailscale_local_status` | `tailscale status --json` | This machine's connection state + peers it can see |
+| `tailscale_ping` | `tailscale ping <target>` | Latency probe to another tailnet node (direct vs DERP-relayed) |
+| `tailscale_netcheck` | `tailscale netcheck --format=json` | NAT type, DERP latency map, IPv4/IPv6 support |
+| `tailscale_local_version` | `tailscale version` | Which client version is actually running |
+
+Requirements: the `tailscale` binary must be in `PATH`. If it's installed somewhere unusual, set `TAILSCALE_BINARY` to its absolute path. The MCP server doesn't need root to run these — they're all diagnostic, not state-mutating. Operations that would need elevation (`tailscale up`, `set --advertise-routes`, `lock sign`) are deliberately not exposed.
+
+When opt-in is on, the startup banner reflects it: `@yawlabs/tailscale-mcp v0.10.9 ready (93 tools, local-cli=on)`.
+
 ## Resources (4)
 
 MCP Resources expose read-only data clients can browse without a tool call.
@@ -210,7 +227,7 @@ MCP Resources expose read-only data clients can browse without a tool call.
 | ACL Policy | `tailscale://tailnet/acl` | Full ACL policy (HuJSON preserved) |
 | DNS Config | `tailscale://tailnet/dns` | Nameservers, search paths, split DNS, MagicDNS |
 
-## Tools (89)
+## Tools (89 + 4 opt-in)
 
 <details>
 <summary><strong>Status</strong> (1 tool)</summary>
@@ -413,6 +430,18 @@ MCP Resources expose read-only data clients can browse without a tool call.
 
 </details>
 
+<details>
+<summary><strong>Local CLI</strong> (4 tools, opt-in) — see <a href="#local-cli-integration-opt-in">Local CLI integration</a></summary>
+
+| Tool | Description |
+|------|-------------|
+| `tailscale_local_status` | This machine's view of the tailnet (own connection state, peers, DERP region) |
+| `tailscale_ping` | Latency probe to another tailnet node from this machine |
+| `tailscale_netcheck` | NAT type, DERP latency map, IPv4/IPv6 support diagnostics |
+| `tailscale_local_version` | Local `tailscale` binary version |
+
+</details>
+
 ## GitOps: deploy ACLs from CI
 
 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:

package/dist/index.js

@@ -3303,8 +3303,8 @@ var require_utils = __commonJS({
     var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
     var HOST_DELIM_RE = /[@/?#:]/g;
     var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
-    function reescapeHostDelimiters(host, isIP) {
-      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+    function reescapeHostDelimiters(host, isIP2) {
+      const re = isIP2 ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
       re.lastIndex = 0;
       return host.replace(re, (ch) => HOST_DELIMS[ch]);
     }
@@ -3786,7 +3786,7 @@ var require_fast_uri = __commonJS({
         fragment: void 0
       };
       let malformedAuthorityOrPort = false;
-      let isIP = false;
+      let isIP2 = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
           uri = options.scheme + ":" + uri;
@@ -3816,9 +3816,9 @@ var require_fast_uri = __commonJS({
           if (ipv4result === false) {
             const ipv6result = normalizeIPv6(parsed.host);
             parsed.host = ipv6result.host.toLowerCase();
-            isIP = ipv6result.isIPV6;
+            isIP2 = ipv6result.isIPV6;
           } else {
-            isIP = true;
+            isIP2 = true;
           }
         }
         if (parsed.scheme === void 0 && parsed.userinfo === void 0 && parsed.host === void 0 && parsed.port === void 0 && parsed.query === void 0 && !parsed.path) {
@@ -3835,7 +3835,7 @@ var require_fast_uri = __commonJS({
         }
         const schemeHandler = getSchemeHandler(options.scheme || parsed.scheme);
         if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
-          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
+          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP2 === false && nonSimpleDomain(parsed.host)) {
             try {
               parsed.host = URL.domainToASCII(parsed.host.toLowerCase());
             } catch (e) {
@@ -3849,7 +3849,7 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP2);
             }
           }
           if (parsed.path) {
@@ -32565,6 +32565,145 @@ var keyTools = [
   }
 ];
 
+// src/tools/local-cli.ts
+import * as net2 from "node:net";
+
+// src/local-cli.ts
+import { execFile as execFileCb } from "node:child_process";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+var execFileImpl = execFileCb;
+function getBinaryPath() {
+  return process.env.TAILSCALE_BINARY || "tailscale";
+}
+async function runTailscaleCli(args, options = {}) {
+  const binary = getBinaryPath();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    execFileImpl(binary, args, { timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES }, (err, stdout, stderr) => {
+      const stdoutStr = stdout == null ? "" : String(stdout);
+      const stderrStr = stderr == null ? "" : String(stderr);
+      if (err) {
+        const errno = err;
+        if (errno.code === "ENOENT") {
+          resolve({
+            ok: false,
+            error: `Could not find the 'tailscale' binary in PATH. Install Tailscale (https://tailscale.com/download) or set TAILSCALE_BINARY to its absolute path.`
+          });
+          return;
+        }
+        if (errno.killed) {
+          resolve({
+            ok: false,
+            error: `'${binary} ${args.join(" ")}' timed out after ${timeoutMs}ms`
+          });
+          return;
+        }
+        const exitCode = typeof errno.code === "number" ? errno.code : void 0;
+        resolve({
+          ok: false,
+          error: stderrStr.trim() || err.message,
+          exitCode
+        });
+        return;
+      }
+      if (options.parseJson) {
+        try {
+          const data = JSON.parse(stdoutStr);
+          resolve({ ok: true, data, exitCode: 0 });
+        } catch (parseErr) {
+          resolve({
+            ok: false,
+            error: `Failed to parse JSON output from '${binary} ${args.join(" ")}': ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`,
+            rawBody: stdoutStr,
+            exitCode: 0
+          });
+        }
+        return;
+      }
+      resolve({ ok: true, rawBody: stdoutStr, exitCode: 0 });
+    });
+  });
+}
+
+// src/tools/local-cli.ts
+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);
+}
+var localCliTools = [
+  {
+    name: "tailscale_local_status",
+    description: "Get this machine's view of its tailnet -- own connection state, peers it can see, DERP region, MagicDNS suffix, etc. Shells out to the local `tailscale` binary; distinct from `tailscale_status`, which queries the admin API for tailnet-wide info. Requires the tailscale CLI installed locally and TAILSCALE_LOCAL_CLI=1.",
+    annotations: {
+      title: "Local tailscale status",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => runTailscaleCli(["status", "--json"], { parseJson: true })
+  },
+  {
+    name: "tailscale_ping",
+    description: "Probe latency to another tailnet node from this machine. Useful for connectivity debugging -- shows whether the path is direct or DERP-relayed, plus RTT. Returns the CLI's text output verbatim.",
+    annotations: {
+      title: "Tailscale ping",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      target: external_exports.string().describe(
+        "Target hostname, IP, or MagicDNS name (e.g. 'my-laptop', '100.64.0.1', 'my-laptop.tail-scale.ts.net')"
+      ),
+      count: external_exports.number().int().positive().max(20).optional().describe(
+        "Number of ping attempts (default 1, max 20). Higher counts give a better latency picture but block the tool call for longer."
+      )
+    }),
+    handler: async (input) => {
+      if (!isValidPingTarget(input.target)) {
+        throw new Error(
+          `Invalid ping target ${JSON.stringify(input.target)}: must be a hostname, IP, or MagicDNS name (letters, digits, dots, hyphens, underscores; max 253 chars).`
+        );
+      }
+      const args = ["ping"];
+      if (input.count !== void 0) args.push("-c", String(input.count));
+      args.push(input.target);
+      return runTailscaleCli(args);
+    }
+  },
+  {
+    name: "tailscale_netcheck",
+    description: "Run Tailscale's network connectivity diagnostics from this machine: NAT type, DERP region latency map, IPv4/IPv6 support, UPnP/PMP/PCP status. Equivalent to `tailscale netcheck --format=json`. Useful when an agent reports flaky connectivity and you want to know whether to point fingers at the NAT, the upstream, or DERP.",
+    annotations: {
+      title: "Tailscale netcheck",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => runTailscaleCli(["netcheck", "--format=json"], { parseJson: true })
+  },
+  {
+    name: "tailscale_local_version",
+    description: "Get the version of the local `tailscale` binary. Different from the control plane / admin API version. Use this when filing a bug to report the client version actually in use.",
+    annotations: {
+      title: "Tailscale CLI version",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => runTailscaleCli(["version"])
+  }
+];
+
 // src/tools/log-streaming.ts
 var logStreamingTools = [
   {
@@ -33467,7 +33606,7 @@ var webhookTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.10.9" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.11.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "deploy-acl") {
   const filePath = process.argv[3];
@@ -33499,6 +33638,9 @@ var toolGroups = {
   services: serviceTools,
   "log-streaming": logStreamingTools
 };
+if (process.env.TAILSCALE_LOCAL_CLI === "1" || process.env.TAILSCALE_LOCAL_CLI === "true") {
+  toolGroups["local-cli"] = localCliTools;
+}
 var {
   tools: allTools,
   unknownGroups,
@@ -33557,10 +33699,12 @@ 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
+  readonlyMode ? "readonly" : null,
+  localCliEnabled ? "local-cli=on" : null
 ].filter(Boolean).join(", ");
 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.10.9",
+  "version": "0.11.0",
   "description": "Tailscale MCP server for managing your tailnet from AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",