claude-code-tailscale 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# Claude Code Tailscale Plugin
+
+A Claude Code MCP server that joins a [Tailscale](https://tailscale.com) tailnet as an ephemeral device, giving Claude access to internal services, APIs, and resources on your tailnet.
+
+## How It Works
+
+```
+Claude Code
+  └── MCP Server (TypeScript)
+        └── tshelper (Go binary using tsnet)
+              └── SOCKS5 proxy on localhost
+                    └── routes through your tailnet
+```
+
+When the MCP server starts, it immediately spawns `tshelper`, which:
+1. Joins your tailnet as an ephemeral device using `tsnet`
+2. Starts a SOCKS5 proxy on localhost
+3. Returns the proxy address to the MCP server
+
+Claude can then use `tailscale_fetch` to access any service on your tailnet — internal APIs, dashboards, databases — without exposing them to the internet.
+
+When the session ends, the device explicitly logs out and is immediately removed from your tailnet.
+
+## Prerequisites
+
+- [Go 1.24+](https://go.dev/dl/) (to build tshelper)
+- [Node.js 20+](https://nodejs.org/)
+- A Tailscale account with an [auth key](https://login.tailscale.com/admin/settings/keys) (ephemeral, reusable recommended) or an [OAuth client](https://tailscale.com/kb/1215/oauth-clients)
+
+## Setup
+
+### 1. Build
+
+```bash
+# Clone the repo
+git clone https://github.com/rosskukulinski/claude-code-tailscale.git
+cd claude-code-tailscale
+
+# Build the Go helper
+cd tshelper && go build -o ../bin/tshelper . && cd ..
+
+# Install npm dependencies and build TypeScript
+npm install && npm run build
+```
+
+### 2. Configure
+
+Set your Tailscale credentials (pick one):
+
+```bash
+# Option A: Auth key (simplest)
+export TS_AUTHKEY="tskey-auth-..."
+
+# Option B: OAuth client secret (preferred for automation/CI)
+export TS_CLIENT_SECRET="tskey-client-..."
+export TS_TAGS="tag:claude-code"  # required for OAuth
+```
+
+### 3. Add to Claude Code
+
+```bash
+claude mcp add tailscale -- node /path/to/claude-code-tailscale/dist/index.js
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tailscale": {
+      "command": "node",
+      "args": ["/path/to/claude-code-tailscale/dist/index.js"],
+      "env": {
+        "TS_AUTHKEY": "tskey-auth-..."
+      }
+    }
+  }
+}
+```
+
+Or with an OAuth client secret:
+
+```json
+{
+  "mcpServers": {
+    "tailscale": {
+      "command": "node",
+      "args": ["/path/to/claude-code-tailscale/dist/index.js"],
+      "env": {
+        "TS_CLIENT_SECRET": "tskey-client-...",
+        "TS_TAGS": "tag:claude-code"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `tailscale_status` | Show tailnet connection status, IPs, and hostname |
+| `tailscale_fetch` | HTTP fetch through the tailnet (access internal services) |
+| `tailscale_connect_test` | Test TCP connectivity to a tailnet host:port |
+
+### Example Usage
+
+Once configured, Claude can access your tailnet services:
+
+```
+> Use tailscale_fetch to get the status of my internal API at http://api-server.tail1234.ts.net/health
+
+> Check if my database server is reachable: tailscale_connect_test db.tail1234.ts.net port 5432
+
+> What's my tailnet connection status?
+```
+
+## Configuration
+
+| Environment Variable | Required | Default | Description |
+|---------------------|----------|---------|-------------|
+| `TS_AUTHKEY` | One of `TS_AUTHKEY` or `TS_CLIENT_SECRET` | — | Tailscale auth key (ephemeral recommended) |
+| `TS_CLIENT_SECRET` | One of `TS_AUTHKEY` or `TS_CLIENT_SECRET` | — | OAuth client secret (`tskey-client-...`). Preferred for automation/CI |
+| `TS_TAGS` | Required for OAuth | — | Comma-separated ACL tags (e.g., `tag:claude-code,tag:dev`) |
+| `TS_HOSTNAME` | No | `cc-{user}-{context}-{rand}` | Tailnet hostname override (random suffix always appended) |
+| `TS_STATE_DIR` | No | `~/.cache/claude-code-tailscale/{hostname}` | State directory |
+| `TS_CONTROL_URL` | No | — | Custom control server (for Headscale) |
+| `TS_EPHEMERAL` | No | `true` | Register as ephemeral node |
+
+**Hostname format:** `cc-{user}-{context}-{random4}` where `{context}` is the git repo name (or machine hostname if not in a repo) and `{random4}` is 4 random hex chars for uniqueness across concurrent sessions.
+
+## Architecture
+
+This plugin follows the same pattern as [kong-tailscale-plugin](https://github.com/rosskukulinski/kong-tailscale-plugin):
+
+- **Kong plugin**: LuaJIT FFI → libtailscale → `tailscale_loopback()` → SOCKS5 → cosocket
+- **This plugin**: Go tsnet binary → SOCKS5 proxy → Node.js `http.request` with `socks-proxy-agent`
+
+The Go helper (`tshelper`) uses `tsnet.Server` directly instead of libtailscale's C API, since we're already in Go. It exposes a SOCKS5 proxy on localhost that the TypeScript MCP server routes through.
+
+Key design decisions:
+- **Eager connection**: Tailnet joins immediately on MCP server start (tools wait if not yet ready)
+- **Ephemeral by default**: Device auto-removes when the session ends, with explicit logout for instant cleanup
+- **Unique hostnames**: Each session gets a unique hostname (`cc-{user}-{repo}-{rand}`) to avoid collisions
+- **OAuth + auth key support**: Works with both `TS_CLIENT_SECRET` (OAuth) and `TS_AUTHKEY` (plain auth keys)
+- **No system Tailscale required**: tsnet embeds a full Tailscale node in the Go binary
+- **SOCKS5 loopback**: Same proven proxy pattern as the Kong plugin
+
+## License
+
+Apache 2.0

package/dist/fetch-via-tailnet.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTTP fetch through the Tailscale SOCKS5 proxy.
+ *
+ * Uses node:http/node:https with socks-proxy-agent, since Node.js native
+ * fetch (undici) doesn't support http.Agent. Same pattern as the Kong
+ * plugin's SOCKS5 cosocket path, but in Node.js.
+ */
+import { SocksProxyAgent } from "socks-proxy-agent";
+export interface FetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeout?: number;
+}
+export interface FetchResult {
+    status: number;
+    statusMessage: string;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function createSocksAgent(socks5Addr: string): SocksProxyAgent;
+export declare function fetchViaTailnet(url: string, agent: SocksProxyAgent, options?: FetchOptions): Promise<FetchResult>;

package/dist/fetch-via-tailnet.js

@@ -0,0 +1,63 @@
+/**
+ * HTTP fetch through the Tailscale SOCKS5 proxy.
+ *
+ * Uses node:http/node:https with socks-proxy-agent, since Node.js native
+ * fetch (undici) doesn't support http.Agent. Same pattern as the Kong
+ * plugin's SOCKS5 cosocket path, but in Node.js.
+ */
+import http from "node:http";
+import https from "node:https";
+import { SocksProxyAgent } from "socks-proxy-agent";
+export function createSocksAgent(socks5Addr) {
+    return new SocksProxyAgent(`socks5h://${socks5Addr}`);
+}
+export async function fetchViaTailnet(url, agent, options = {}) {
+    const { method = "GET", headers = {}, body, timeout = 30000 } = options;
+    const parsed = new URL(url);
+    const isHTTPS = parsed.protocol === "https:";
+    const lib = isHTTPS ? https : http;
+    return new Promise((resolve, reject) => {
+        const req = lib.request({
+            hostname: parsed.hostname,
+            port: parsed.port || (isHTTPS ? 443 : 80),
+            path: parsed.pathname + parsed.search,
+            method,
+            headers: {
+                ...headers,
+                host: parsed.host,
+            },
+            agent,
+            timeout,
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const respHeaders = {};
+                for (const [key, value] of Object.entries(res.headers)) {
+                    if (typeof value === "string") {
+                        respHeaders[key] = value;
+                    }
+                    else if (Array.isArray(value)) {
+                        respHeaders[key] = value.join(", ");
+                    }
+                }
+                resolve({
+                    status: res.statusCode ?? 0,
+                    statusMessage: res.statusMessage ?? "",
+                    headers: respHeaders,
+                    body: Buffer.concat(chunks).toString("utf-8"),
+                });
+            });
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+        req.on("timeout", () => {
+            req.destroy(new Error(`Request timed out after ${timeout}ms`));
+        });
+        if (body) {
+            req.write(body);
+        }
+        req.end();
+    });
+}
+//# sourceMappingURL=fetch-via-tailnet.js.map

package/dist/fetch-via-tailnet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-via-tailnet.js","sourceRoot":"","sources":["../src/fetch-via-tailnet.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Claude Code Tailscale MCP Server
+ *
+ * Joins a Tailscale tailnet as an ephemeral device and exposes tools for
+ * Claude to interact with tailnet resources (fetch internal APIs, check
+ * status, test connectivity).
+ *
+ * Architecture:
+ *   MCP Server (this file, TypeScript)
+ *     └── spawns tshelper (Go binary using tsnet)
+ *           └── SOCKS5 proxy on localhost
+ *                 └── routes through tailnet
+ *
+ * Same pattern as kong-tailscale-plugin, adapted for Node.js + MCP.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+/**
+ * Claude Code Tailscale MCP Server
+ *
+ * Joins a Tailscale tailnet as an ephemeral device and exposes tools for
+ * Claude to interact with tailnet resources (fetch internal APIs, check
+ * status, test connectivity).
+ *
+ * Architecture:
+ *   MCP Server (this file, TypeScript)
+ *     └── spawns tshelper (Go binary using tsnet)
+ *           └── SOCKS5 proxy on localhost
+ *                 └── routes through tailnet
+ *
+ * Same pattern as kong-tailscale-plugin, adapted for Node.js + MCP.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { TsHelper } from "./tshelper.js";
+import { createSocksAgent, fetchViaTailnet } from "./fetch-via-tailnet.js";
+const helper = new TsHelper();
+let agent = null;
+let connectPromise = null;
+// Connect lazily on first tool invocation to avoid wasting tsnet nodes
+// when agents don't use tailscale tools.
+function startConnection() {
+    connectPromise = helper.start().then((info) => {
+        agent = createSocksAgent(info.socks5_addr);
+    }).catch((err) => {
+        console.error(`[tailscale] connection failed: ${err.message}`);
+        connectPromise = null;
+        throw err;
+    });
+}
+async function ensureConnected() {
+    if (helper.connected && agent)
+        return;
+    if (connectPromise) {
+        await connectPromise;
+        return;
+    }
+    // Lazy: start on first tool call
+    startConnection();
+    await connectPromise;
+}
+/**
+ * Call the tshelper HTTP control API and return MCP-formatted content.
+ */
+async function callAPI(path, options) {
+    await ensureConnected();
+    try {
+        const res = await helper.callAPI(path, options);
+        if (!res.ok) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `API call failed: ${err.message}` }],
+            isError: true,
+        };
+    }
+}
+// --- MCP Server ---
+const server = new McpServer({
+    name: "tailscale",
+    version: "0.1.0",
+});
+server.tool("tailscale_status", "Show Tailscale connection status: tailnet IPs, hostname, and proxy address. Call this first to verify the tailnet connection is working.", {}, async () => {
+    await ensureConnected();
+    const info = helper.info;
+    return {
+        content: [{
+                type: "text",
+                text: [
+                    `Status: Connected`,
+                    `Hostname: ${info.hostname}`,
+                    `Tailnet IPs: ${info.tailnet_ips.join(", ")}`,
+                    `SOCKS5 Proxy: ${info.socks5_addr}`,
+                    `API: ${info.api_addr}`,
+                ].join("\n"),
+            }],
+    };
+});
+server.tool("tailscale_fetch", "Fetch a URL through the Tailscale tailnet. Use this to access internal services, APIs, and resources that are only reachable via the tailnet (e.g., *.ts.net hostnames, 100.x.y.z addresses). Supports GET, POST, PUT, DELETE, PATCH, HEAD.", {
+    url: z.string().describe("The URL to fetch (e.g., http://my-service.tail1234.ts.net/api/v1/status)"),
+    method: z
+        .enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"])
+        .optional()
+        .describe("HTTP method (default: GET)"),
+    headers: z
+        .string()
+        .optional()
+        .describe("HTTP headers as JSON object string, e.g. '{\"Authorization\": \"Bearer xxx\"}'"),
+    body: z
+        .string()
+        .optional()
+        .describe("Request body (for POST/PUT/PATCH)"),
+    timeout: z
+        .number()
+        .optional()
+        .describe("Request timeout in milliseconds (default: 30000)"),
+}, async ({ url, method, headers, body, timeout }) => {
+    await ensureConnected();
+    let parsedHeaders;
+    if (headers) {
+        try {
+            parsedHeaders = JSON.parse(headers);
+        }
+        catch {
+            return {
+                content: [{ type: "text", text: "Invalid headers JSON" }],
+                isError: true,
+            };
+        }
+    }
+    try {
+        const result = await fetchViaTailnet(url, agent, {
+            method: method ?? "GET",
+            headers: parsedHeaders,
+            body,
+            timeout: timeout ?? 30000,
+        });
+        const headerLines = Object.entries(result.headers)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join("\n");
+        // Truncate very large responses
+        const maxBody = 100_000;
+        const bodyText = result.body.length > maxBody
+            ? result.body.slice(0, maxBody) + `\n\n... (truncated, ${result.body.length} bytes total)`
+            : result.body;
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `HTTP ${result.status} ${result.statusMessage}`,
+                        headerLines,
+                        "",
+                        bodyText,
+                    ].join("\n"),
+                }],
+            isError: result.status >= 400,
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Fetch failed: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool("tailscale_connect_test", "Test TCP connectivity to a tailnet host and port. Useful for verifying a service is reachable before attempting to fetch from it.", {
+    host: z.string().describe("Tailnet hostname or IP (e.g., my-server.tail1234.ts.net or 100.x.y.z)"),
+    port: z
+        .number()
+        .int()
+        .min(1)
+        .max(65535)
+        .describe("TCP port to test"),
+}, async ({ host, port }) => {
+    await ensureConnected();
+    const start = Date.now();
+    try {
+        // Use a minimal HTTP request to test TCP connectivity through SOCKS5
+        await fetchViaTailnet(`http://${host}:${port}/`, agent, {
+            method: "HEAD",
+            timeout: 10000,
+        });
+        const elapsed = Date.now() - start;
+        return {
+            content: [{
+                    type: "text",
+                    text: `Connected to ${host}:${port} via tailnet (${elapsed}ms)`,
+                }],
+        };
+    }
+    catch (err) {
+        const elapsed = Date.now() - start;
+        // Connection errors still mean we tested connectivity
+        if (err.message.includes("ECONNREFUSED") || err.message.includes("ECONNRESET")) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `TCP connection to ${host}:${port} was rejected (${elapsed}ms) — host is reachable but port is closed or service not listening`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `Connection to ${host}:${port} failed after ${elapsed}ms: ${err.message}`,
+                }],
+            isError: true,
+        };
+    }
+});
+// --- New Tools (via HTTP control API) ---
+server.tool("tailscale_dns_lookup", "Resolve a DNS name using the tailnet's DNS resolver (MagicDNS). Useful for looking up *.ts.net hostnames and other tailnet DNS records.", {
+    name: z.string().describe("DNS name to look up (e.g., my-server.tail1234.ts.net.)"),
+    type: z
+        .enum(["A", "AAAA", "CNAME", "TXT", "MX", "SRV", "NS", "PTR"])
+        .optional()
+        .describe("DNS record type (default: A)"),
+}, async ({ name, type }) => {
+    return callAPI("/api/dns-lookup", {
+        method: "POST",
+        body: { name, type: type ?? "A" },
+    });
+});
+server.tool("tailscale_whois", "Look up information about a tailnet IP address or node: who owns it, its hostname, OS, tags, and key expiry.", {
+    addr: z.string().describe("Tailnet IP address to look up (e.g., 100.x.y.z or [fd7a::x]:port)"),
+}, async ({ addr }) => {
+    return callAPI(`/api/whois?addr=${encodeURIComponent(addr)}`);
+});
+server.tool("tailscale_devices", "List all devices on the tailnet with their IPs, hostnames, OS, online status, tags, and traffic stats.", {}, async () => {
+    return callAPI("/api/devices");
+});
+server.tool("tailscale_ping", "Ping a tailnet peer by IP to test connectivity and measure latency. Supports disco, TSMP, ICMP, and peerapi ping types.", {
+    ip: z.string().describe("Tailnet IP address to ping (e.g., 100.x.y.z)"),
+    type: z
+        .enum(["disco", "TSMP", "ICMP", "peerapi"])
+        .optional()
+        .describe("Ping type (default: disco)"),
+}, async ({ ip, type }) => {
+    return callAPI("/api/ping", {
+        method: "POST",
+        body: { ip, type: type ?? "disco" },
+        timeout: 20000,
+    });
+});
+server.tool("tailscale_port_forward", "Create, list, or close port forwards from localhost to a tailnet host. Creates a local TCP listener that forwards connections through the tailnet.", {
+    action: z
+        .enum(["create", "list", "close"])
+        .describe("Action to perform"),
+    host: z
+        .string()
+        .optional()
+        .describe("Tailnet hostname or IP to forward to (required for create)"),
+    port: z
+        .number()
+        .int()
+        .min(1)
+        .max(65535)
+        .optional()
+        .describe("Remote port to forward to (required for create)"),
+    id: z
+        .string()
+        .optional()
+        .describe("Port forward ID to close (required for close)"),
+}, async ({ action, host, port, id }) => {
+    switch (action) {
+        case "create":
+            if (!host || !port) {
+                return {
+                    content: [{ type: "text", text: "host and port are required for create action" }],
+                    isError: true,
+                };
+            }
+            return callAPI("/api/port-forward", {
+                method: "POST",
+                body: { host, port },
+            });
+        case "list":
+            return callAPI("/api/port-forwards");
+        case "close":
+            if (!id) {
+                return {
+                    content: [{ type: "text", text: "id is required for close action" }],
+                    isError: true,
+                };
+            }
+            return callAPI(`/api/port-forward?id=${encodeURIComponent(id)}`, {
+                method: "DELETE",
+            });
+    }
+});
+server.tool("tailscale_acl_check", "Show the current ACL packet filter rules as seen by this node. Useful for debugging access issues between tailnet devices.", {}, async () => {
+    return callAPI("/api/acl-check");
+});
+server.tool("tailscale_netcheck", "Show DERP relay regions and optionally probe a specific region for connectivity diagnostics. When full is true, performs active STUN probes to measure latency (ms) to every DERP region, reports the preferred DERP relay, and checks UDP/IPv4/IPv6 connectivity — similar to `tailscale netcheck` on the CLI. Without full, only lists available regions (no latency data).", {
+    region: z
+        .string()
+        .optional()
+        .describe("DERP region code to probe (e.g., 'nyc', 'sfo'). If omitted, just lists regions. Ignored when full is true."),
+    full: z
+        .boolean()
+        .optional()
+        .describe("Set to true to run active STUN probes and measure per-region latency in milliseconds. Returns: preferredDERP, preferredDERPName, udp, ipv4, ipv6, and regionLatency[] sorted by latency ascending. Takes ~5-10 seconds."),
+}, async ({ region, full }) => {
+    if (full) {
+        return callAPI("/api/netcheck-full", { timeout: 30000 });
+    }
+    const path = region
+        ? `/api/netcheck?region=${encodeURIComponent(region)}`
+        : "/api/netcheck";
+    return callAPI(path, { timeout: 20000 });
+});
+server.tool("tailscale_cert", "Get TLS certificate information for a tailnet domain. Shows issuer, expiry, and DNS names without exposing the private key.", {
+    domain: z.string().describe("Tailnet domain to get certificate for (e.g., my-host.tail1234.ts.net)"),
+}, async ({ domain }) => {
+    return callAPI(`/api/cert-info?domain=${encodeURIComponent(domain)}`, {
+        timeout: 20000,
+    });
+});
+// --- Inter-Agent Communication ---
+server.tool("tailscale_agents", "Discover other Claude Code agents on the tailnet. Returns a list of cc-* peers with their hostnames, IPs, and online status. Use this to find agents you can communicate with.", {}, async () => {
+    return callAPI("/api/agents");
+});
+server.tool("tailscale_send_message", "Send a message to another Claude Code agent on the tailnet. The recipient agent can read it with tailscale_check_messages. Use to: \"*\" to broadcast to all agents.", {
+    to: z.string().describe("Recipient agent hostname (e.g., cc-ross-frontend-a7b2) or \"*\" for broadcast"),
+    subject: z.string().describe("Message subject"),
+    body: z.string().describe("Message body (max 64KB)"),
+    type: z
+        .enum(["message", "task", "task-result", "info"])
+        .optional()
+        .describe("Message type (default: message). Use 'task' for delegation, 'task-result' for responses, 'info' for FYI"),
+    in_reply_to: z
+        .string()
+        .optional()
+        .describe("ID of the message this is replying to"),
+}, async ({ to, subject, body, type, in_reply_to }) => {
+    return callAPI("/api/messages/send", {
+        method: "POST",
+        body: { to, subject, body, type: type ?? "message", in_reply_to: in_reply_to ?? "" },
+    });
+});
+server.tool("tailscale_check_messages", "Check your message inbox for messages from other Claude Code agents. Returns unread messages by default.", {
+    unread_only: z
+        .boolean()
+        .optional()
+        .describe("Only return unread messages (default: true)"),
+    from: z
+        .string()
+        .optional()
+        .describe("Filter messages by sender hostname"),
+    type: z
+        .enum(["message", "task", "task-result", "info"])
+        .optional()
+        .describe("Filter messages by type"),
+    ack: z
+        .string()
+        .optional()
+        .describe("Message ID to acknowledge/mark as read"),
+}, async ({ unread_only, from, type, ack }) => {
+    // If ack is provided, mark the message as read first
+    if (ack) {
+        const ackResult = await callAPI(`/api/messages/${encodeURIComponent(ack)}/ack`, {
+            method: "POST",
+        });
+        if (ackResult.isError)
+            return ackResult;
+    }
+    const params = new URLSearchParams();
+    if (unread_only !== false)
+        params.set("unread", "true");
+    if (from)
+        params.set("from", from);
+    if (type)
+        params.set("type", type);
+    const query = params.toString();
+    return callAPI(`/api/messages${query ? `?${query}` : ""}`);
+});
+// --- Agent Teams (opt-in via TS_ENABLE_TEAMS=1) ---
+if (process.env.TS_ENABLE_TEAMS === "1") {
+    server.tool("tailscale_team_create", "Create a named team with this agent as lead. Other agents can then join this team to share tasks and coordinate work across machines.", {
+        name: z.string().describe("Team name (e.g., 'api-migration', 'frontend-refactor')"),
+    }, async ({ name }) => {
+        return callAPI("/api/team/create", {
+            method: "POST",
+            body: { name },
+        });
+    });
+    server.tool("tailscale_team_join", "Join a team hosted by another agent on the tailnet. Once joined, you can see and claim shared tasks.", {
+        lead_hostname: z.string().describe("Hostname of the team lead agent (e.g., cc-ross-backend-a7b2)"),
+    }, async ({ lead_hostname }) => {
+        return callAPI("/api/team/join", {
+            method: "POST",
+            body: { lead_hostname },
+        });
+    });
+    server.tool("tailscale_team_info", "Show current team membership, roles, and status. Returns team name, lead, and all members.", {}, async () => {
+        return callAPI("/api/team");
+    });
+    server.tool("tailscale_task_create", "Create a task on the team's shared task list. Tasks can be claimed by any team member.", {
+        subject: z.string().describe("Brief task title in imperative form (e.g., 'Update API response schema')"),
+        description: z.string().describe("Detailed description of what needs to be done"),
+        activeForm: z.string().optional().describe("Present continuous form shown while working (e.g., 'Updating API schema')"),
+        blocks: z.array(z.string()).optional().describe("Task IDs that this task blocks"),
+        blockedBy: z.array(z.string()).optional().describe("Task IDs that must complete before this one"),
+    }, async ({ subject, description, activeForm, blocks, blockedBy }) => {
+        await ensureConnected();
+        return callAPI("/api/tasks", {
+            method: "POST",
+            body: {
+                subject,
+                description,
+                activeForm: activeForm ?? "",
+                blocks: blocks ?? [],
+                blockedBy: blockedBy ?? [],
+                createdBy: helper.info?.hostname ?? "",
+            },
+        });
+    });
+    server.tool("tailscale_task_list", "List tasks on the team's shared task list. Filter by status to find available, in-progress, or completed tasks.", {
+        status: z
+            .enum(["pending", "in_progress", "completed", "all"])
+            .optional()
+            .describe("Filter by task status (default: all)"),
+    }, async ({ status }) => {
+        const params = status ? `?status=${encodeURIComponent(status)}` : "";
+        return callAPI(`/api/tasks${params}`);
+    });
+    server.tool("tailscale_task_update", "Claim, complete, update, or delete a task on the shared task list.", {
+        id: z.string().describe("Task ID (e.g., 'task-1')"),
+        action: z
+            .enum(["claim", "complete", "update", "delete"])
+            .describe("Action: 'claim' to start working on it, 'complete' to mark done, 'update' to modify fields, 'delete' to remove"),
+        subject: z.string().optional().describe("New subject (for update action)"),
+        description: z.string().optional().describe("New description (for update action)"),
+        activeForm: z.string().optional().describe("New activeForm (for update action)"),
+        addBlocks: z.array(z.string()).optional().describe("Task IDs to add to blocks list"),
+        addBlockedBy: z.array(z.string()).optional().describe("Task IDs to add to blockedBy list"),
+    }, async ({ id, action, subject, description, activeForm, addBlocks, addBlockedBy }) => {
+        await ensureConnected();
+        const encodedId = encodeURIComponent(id);
+        switch (action) {
+            case "claim":
+                return callAPI(`/api/tasks/${encodedId}/claim`, {
+                    method: "POST",
+                    body: { owner: helper.info?.hostname ?? "" },
+                });
+            case "complete":
+                return callAPI(`/api/tasks/${encodedId}`, {
+                    method: "PATCH",
+                    body: { status: "completed" },
+                });
+            case "update": {
+                const patch = {};
+                if (subject !== undefined)
+                    patch.subject = subject;
+                if (description !== undefined)
+                    patch.description = description;
+                if (activeForm !== undefined)
+                    patch.activeForm = activeForm;
+                if (addBlocks !== undefined)
+                    patch.addBlocks = addBlocks;
+                if (addBlockedBy !== undefined)
+                    patch.addBlockedBy = addBlockedBy;
+                return callAPI(`/api/tasks/${encodedId}`, {
+                    method: "PATCH",
+                    body: patch,
+                });
+            }
+            case "delete":
+                return callAPI(`/api/tasks/${encodedId}`, {
+                    method: "DELETE",
+                });
+        }
+    });
+}
+// --- Lifecycle ---
+async function main() {
+    // Connection is lazy: starts on first tool invocation via ensureConnected()
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Graceful shutdown
+    const shutdown = async () => {
+        await helper.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error("MCP server failed:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tshelper.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Manages the tshelper Go binary lifecycle.
+ *
+ * Spawns tshelper as a child process, reads the JSON startup info from stdout,
+ * and provides the SOCKS5 proxy coordinates to the MCP server.
+ */
+export interface TsHelperInfo {
+    tailnet_ips: string[];
+    hostname: string;
+    socks5_addr: string;
+    api_addr: string;
+    agent_port: number;
+}
+export interface APIResponse {
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+}
+export declare class TsHelper {
+    private proc;
+    private _info;
+    private _startPromise;
+    /** Max retry attempts for tsnet connection (handles rate-limiting, transient failures) */
+    private static readonly MAX_RETRIES;
+    private static readonly BACKOFF_BASE_MS;
+    get info(): TsHelperInfo | null;
+    get connected(): boolean;
+    /**
+     * Start the tshelper binary and wait for it to connect to the tailnet.
+     * Idempotent: returns the same promise if already starting/started.
+     */
+    start(): Promise<TsHelperInfo>;
+    /**
+     * Attempt to start tshelper with exponential backoff retries.
+     * Handles transient failures like control plane rate-limiting.
+     */
+    private _doStartWithRetry;
+    private _doStart;
+    /**
+     * Call the tshelper HTTP control API.
+     */
+    callAPI(path: string, options?: {
+        method?: string;
+        body?: unknown;
+        timeout?: number;
+    }): Promise<APIResponse>;
+    /**
+     * Stop the tshelper process gracefully.
+     */
+    stop(): Promise<void>;
+    /**
+     * Find the tshelper binary, checking several locations.
+     */
+    private findBinary;
+}

package/dist/tshelper.js

@@ -0,0 +1,203 @@
+/**
+ * Manages the tshelper Go binary lifecycle.
+ *
+ * Spawns tshelper as a child process, reads the JSON startup info from stdout,
+ * and provides the SOCKS5 proxy coordinates to the MCP server.
+ */
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { createInterface } from "node:readline";
+import { join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import http from "node:http";
+export class TsHelper {
+    proc = null;
+    _info = null;
+    _startPromise = null;
+    /** Max retry attempts for tsnet connection (handles rate-limiting, transient failures) */
+    static MAX_RETRIES = 3;
+    static BACKOFF_BASE_MS = 2000;
+    get info() {
+        return this._info;
+    }
+    get connected() {
+        return this._info !== null && this.proc !== null && this.proc.exitCode === null;
+    }
+    /**
+     * Start the tshelper binary and wait for it to connect to the tailnet.
+     * Idempotent: returns the same promise if already starting/started.
+     */
+    async start() {
+        if (this.connected) {
+            return this._info;
+        }
+        if (this._startPromise) {
+            return this._startPromise;
+        }
+        this._startPromise = this._doStartWithRetry();
+        this._startPromise.catch(() => {
+            // Reset so a retry can attempt again
+            this._startPromise = null;
+        });
+        return this._startPromise;
+    }
+    /**
+     * Attempt to start tshelper with exponential backoff retries.
+     * Handles transient failures like control plane rate-limiting.
+     */
+    async _doStartWithRetry() {
+        let lastErr = null;
+        for (let attempt = 0; attempt < TsHelper.MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                const delay = TsHelper.BACKOFF_BASE_MS * Math.pow(2, attempt - 1);
+                console.error(`[tailscale] retrying tshelper start (attempt ${attempt + 1}/${TsHelper.MAX_RETRIES}) after ${delay}ms...`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            try {
+                return await this._doStart();
+            }
+            catch (err) {
+                lastErr = err;
+                // Clean up failed process before retry
+                if (this.proc && this.proc.exitCode === null) {
+                    this.proc.kill("SIGKILL");
+                }
+                this.proc = null;
+                this._info = null;
+                // Don't retry config errors (missing binary, missing auth)
+                if (err.message.includes("binary not found") ||
+                    err.message.includes("TS_AUTHKEY or TS_CLIENT_SECRET is required")) {
+                    throw err;
+                }
+                console.error(`[tailscale] tshelper start failed (attempt ${attempt + 1}): ${err.message}`);
+            }
+        }
+        throw new Error(`tshelper failed after ${TsHelper.MAX_RETRIES} attempts: ${lastErr?.message}`);
+    }
+    async _doStart() {
+        const binPath = this.findBinary();
+        if (!binPath) {
+            throw new Error("tshelper binary not found. Build it with: cd tshelper && go build -o ../bin/tshelper .");
+        }
+        if (!process.env.TS_AUTHKEY && !process.env.TS_CLIENT_SECRET) {
+            throw new Error("either TS_AUTHKEY or TS_CLIENT_SECRET is required");
+        }
+        this.proc = spawn(binPath, [], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env },
+        });
+        // Forward stderr to parent stderr for diagnostics
+        this.proc.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+        });
+        // Collect stderr for error reporting on failure
+        const stderrChunks = [];
+        this.proc.stderr?.on("data", (chunk) => {
+            stderrChunks.push(chunk.toString());
+        });
+        // Read the first line of stdout — this is the JSON startup info
+        const rl = createInterface({ input: this.proc.stdout });
+        const infoPromise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error(`tshelper timed out waiting for tailnet connection (60s)\nstderr: ${stderrChunks.join("")}`));
+            }, 60_000);
+            rl.once("line", (line) => {
+                clearTimeout(timeout);
+                try {
+                    resolve(JSON.parse(line));
+                }
+                catch {
+                    reject(new Error(`tshelper output invalid JSON: ${line}`));
+                }
+            });
+            this.proc.once("exit", (code) => {
+                clearTimeout(timeout);
+                if (code !== 0 && !this._info) {
+                    reject(new Error(`tshelper exited with code ${code}\nstderr: ${stderrChunks.join("")}`));
+                }
+            });
+        });
+        this._info = await infoPromise;
+        return this._info;
+    }
+    /**
+     * Call the tshelper HTTP control API.
+     */
+    async callAPI(path, options) {
+        if (!this._info) {
+            throw new Error("tshelper not connected");
+        }
+        const method = options?.method ?? "GET";
+        const timeout = options?.timeout ?? 30000;
+        const url = `http://${this._info.api_addr}${path}`;
+        return new Promise((resolve, reject) => {
+            const req = http.request(url, { method, timeout }, (res) => {
+                const chunks = [];
+                res.on("data", (chunk) => chunks.push(chunk));
+                res.on("end", () => {
+                    const body = Buffer.concat(chunks).toString();
+                    try {
+                        resolve(JSON.parse(body));
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON from API: ${body.slice(0, 200)}`));
+                    }
+                });
+            });
+            req.on("error", (err) => reject(new Error(`API request failed: ${err.message}`)));
+            req.on("timeout", () => {
+                req.destroy();
+                reject(new Error(`API request timed out after ${timeout}ms`));
+            });
+            if (options?.body !== undefined) {
+                req.setHeader("Content-Type", "application/json");
+                req.write(JSON.stringify(options.body));
+            }
+            req.end();
+        });
+    }
+    /**
+     * Stop the tshelper process gracefully.
+     */
+    async stop() {
+        if (!this.proc || this.proc.exitCode !== null) {
+            this.proc = null;
+            this._info = null;
+            return;
+        }
+        this.proc.kill("SIGTERM");
+        // Wait up to 5 seconds for graceful shutdown
+        const exitPromise = once(this.proc, "exit");
+        const timeout = setTimeout(() => {
+            this.proc?.kill("SIGKILL");
+        }, 5000);
+        try {
+            await exitPromise;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.proc = null;
+            this._info = null;
+        }
+    }
+    /**
+     * Find the tshelper binary, checking several locations.
+     */
+    findBinary() {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const ext = process.platform === "win32" ? ".exe" : "";
+        const candidates = [
+            join(__dirname, "..", "bin", `tshelper${ext}`),
+            join(__dirname, "..", "tshelper", `tshelper${ext}`),
+            `tshelper${ext}`, // in PATH
+        ];
+        for (const p of candidates) {
+            if (p === "tshelper" || existsSync(p)) {
+                return p;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=tshelper.js.map

package/dist/tshelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tshelper.js","sourceRoot":"","sources":["../src/tshelper.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "claude-code-tailscale",
+  "version": "0.1.0",
+  "description": "Claude Code plugin that joins a Tailscale tailnet as an ephemeral device using libtailscale",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-code-tailscale": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:go": "node scripts/build-go.mjs",
+    "build:all": "npm run build:go && npm run build",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "files": [
+    "dist/",
+    "scripts/postinstall.mjs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "socks-proxy-agent": "^8.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rosskukulinski/claude-code-tailscale"
+  },
+  "keywords": [
+    "claude-code",
+    "tailscale",
+    "mcp",
+    "ai-agents",
+    "libtailscale"
+  ]
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script: downloads the prebuilt tshelper binary from
+ * the GitHub Release matching the package version.
+ *
+ * Skips the download when:
+ *  - bin/tshelper already exists (local dev / pre-built)
+ *  - Running in a CI environment with CI=true
+ */
+
+import { existsSync, mkdirSync, chmodSync, createWriteStream, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { get } from "node:https";
+import { createReadStream } from "node:fs";
+import { readFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, "..");
+const binDir = join(root, "bin");
+const ext = process.platform === "win32" ? ".exe" : "";
+const binaryPath = join(binDir, `tshelper${ext}`);
+
+// Skip if binary already exists (local dev)
+if (existsSync(binaryPath)) {
+  console.log(`[postinstall] tshelper already exists at ${binaryPath}, skipping download`);
+  process.exit(0);
+}
+
+// Platform mapping: Node → Go naming
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+};
+
+const archMap = {
+  arm64: "arm64",
+  x64: "amd64",
+};
+
+const goos = platformMap[process.platform];
+const goarch = archMap[process.arch];
+
+if (!goos || !goarch) {
+  console.error(
+    `[postinstall] Unsupported platform: ${process.platform}/${process.arch}. ` +
+      `Supported: darwin/arm64, darwin/x64, linux/arm64, linux/x64. ` +
+      `You can build from source: cd tshelper && go build -o ../bin/tshelper .`
+  );
+  process.exit(0); // exit 0 so npm install doesn't fail
+}
+
+// Read version from package.json
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+const version = pkg.version;
+const repo = "rosskukulinski/claude-code-tailscale";
+const binaryName = `tshelper-${goos}-${goarch}`;
+const url = `https://github.com/${repo}/releases/download/v${version}/${binaryName}`;
+
+console.log(`[postinstall] Downloading tshelper for ${goos}/${goarch} (v${version})...`);
+
+mkdirSync(binDir, { recursive: true });
+
+/**
+ * Follow redirects (GitHub releases redirect to S3/CDN).
+ */
+function download(url, dest, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) return reject(new Error("Too many redirects"));
+
+    get(url, { headers: { "User-Agent": "claude-code-tailscale-postinstall" } }, (res) => {
+      // Follow redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return download(res.headers.location, dest, maxRedirects - 1).then(resolve, reject);
+      }
+
+      if (res.statusCode !== 200) {
+        return reject(new Error(`Download failed: HTTP ${res.statusCode} from ${url}`));
+      }
+
+      const file = createWriteStream(dest);
+      res.pipe(file);
+      file.on("finish", () => {
+        file.close();
+        resolve();
+      });
+      file.on("error", (err) => {
+        unlinkSync(dest);
+        reject(err);
+      });
+    }).on("error", reject);
+  });
+}
+
+try {
+  await download(url, binaryPath);
+  chmodSync(binaryPath, 0o755);
+  console.log(`[postinstall] tshelper installed to ${binaryPath}`);
+} catch (err) {
+  console.error(`[postinstall] Failed to download tshelper: ${err.message}`);
+  console.error(
+    `[postinstall] You can build from source: cd tshelper && go build -o ../bin/tshelper .`
+  );
+  // Don't fail the install — the user might build from source
+  process.exit(0);
+}