unifi-mcp-worker 1.0.0

package/README.md

@@ -0,0 +1,210 @@
+# UniFi MCP Relay Worker
+
+A Cloudflare Worker that enables cloud agents to access locally-hosted UniFi MCP servers via a secure relay gateway.
+
+---
+
+## How It Works
+
+Cloud agents communicate with your local UniFi MCP server through a two-leg relay:
+
+```
+Cloud Agent (Claude, n8n, etc.)
+        |  HTTPS POST /mcp  (Bearer AGENT_TOKEN)
+        v
+Cloudflare Worker  ──────────────────────────────────  Durable Object (RelayObject)
+                                                                |
+                                              WebSocket (WSS) /ws  (relay_token)
+                                                                |
+                                                   unifi-mcp-relay (local network)
+                                                                |
+                                                    UniFi MCP Server (stdio/HTTP)
+```
+
+The Durable Object persists location registrations in SQLite and maintains live WebSocket connections to one or more relay clients. When a tool call arrives from a cloud agent, the worker routes it to the appropriate relay client and streams the result back.
+
+**Multi-location support:** Multiple relay clients can connect simultaneously, each representing a different physical location (home lab, branch office, customer site). Read-only tool calls are automatically fanned out to all connected locations and results are aggregated. Write operations require an explicit `__location` argument to target a specific site — useful for MSP workflows.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sirkirby/unifi-mcp-worker/main/install.sh | bash
+```
+
+Or install the CLI directly:
+
+```bash
+npm install -g unifi-mcp-worker
+unifi-mcp-worker install
+```
+
+The CLI will:
+1. Check prerequisites (Node.js, Wrangler)
+2. Deploy the worker to your Cloudflare account
+3. Generate and set authentication tokens
+4. Display your tokens and next steps
+
+### Upgrade
+
+```bash
+unifi-mcp-worker upgrade
+```
+
+### Add a Location
+
+```bash
+unifi-mcp-worker add-location
+```
+
+### Manage Tokens
+
+```bash
+unifi-mcp-worker rotate-tokens
+unifi-mcp-worker status
+```
+
+### Remove
+
+```bash
+unifi-mcp-worker destroy
+```
+
+---
+
+## Configuration Reference
+
+### Secrets
+
+| Secret | Purpose |
+|--------|---------|
+| `AGENT_TOKEN` | Bearer token required by cloud agents calling the `/mcp` endpoint |
+| `ADMIN_TOKEN` | Bearer token required for admin API calls (`/api/*`) |
+
+Secrets are set automatically by the CLI and can be rotated with `unifi-mcp-worker rotate-tokens`.
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `TOOL_REGISTRATION_MODE` | `lazy` | Tool registration mode sent to relay clients. `lazy` registers only meta-tools (~200 tokens); `eager` registers all tools upfront (~5,000 tokens) |
+
+Variables are set in `wrangler.toml` under `[vars]` or overridden via the Cloudflare dashboard.
+
+---
+
+## API Reference
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `/health` | GET | None | Health check — returns `{"status":"ok"}` |
+| `/mcp` | POST | `AGENT_TOKEN` | MCP JSON-RPC endpoint for cloud agents |
+| `/ws` | GET | `relay_token` | WebSocket upgrade for relay client connections |
+| `/api/locations` | GET | `ADMIN_TOKEN` | List registered locations and connection status |
+| `/api/locations/token` | POST | `ADMIN_TOKEN` | Generate a relay token for a new location |
+
+### MCP Endpoint
+
+The `/mcp` endpoint accepts standard MCP JSON-RPC requests:
+
+```bash
+curl -X POST https://your-worker.workers.dev/mcp \
+  -H "Authorization: Bearer <agent-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+### Built-in Meta-Tools
+
+The relay always exposes three meta-tools regardless of registration mode:
+
+| Tool | Purpose |
+|------|---------|
+| `unifi_tool_index` | List all available UniFi tools with optional category or search filter |
+| `unifi_execute` | Execute any UniFi tool by name; use `__location` to target a specific site |
+| `unifi_batch` | Execute multiple UniFi tools in a single request |
+
+---
+
+## Token Management
+
+The CLI manages tokens automatically during `install` and `rotate-tokens`. You can also manage tokens manually via the admin API:
+
+```bash
+curl -X POST https://your-worker.workers.dev/api/locations/token \
+  -H "Authorization: Bearer <admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"location_name": "Home Lab"}'
+```
+
+Response:
+
+```json
+{
+  "location_id": "a1b2c3d4-...",
+  "location_name": "Home Lab",
+  "token": "<relay-token>"
+}
+```
+
+Store the `token` value securely — it is only returned once. Provide it to `unifi-mcp-relay` as `UNIFI_MCP_RELAY_TOKEN` (see [unifi-mcp](https://github.com/sirkirby/unifi-mcp) for relay client configuration).
+
+### List Registered Locations
+
+```bash
+unifi-mcp-worker status
+```
+
+Or via the admin API:
+
+```bash
+curl https://your-worker.workers.dev/api/locations \
+  -H "Authorization: Bearer <admin-token>"
+```
+
+Response includes `connected: true/false` indicating whether the relay client WebSocket is currently active.
+
+---
+
+## Connecting Cloud Agents
+
+Point any MCP-compatible client at the worker URL:
+
+- **Endpoint:** `https://your-worker.workers.dev/mcp`
+- **Auth:** `Authorization: Bearer <agent-token>`
+- **Transport:** HTTP POST (standard MCP JSON-RPC)
+
+Compatible clients include Claude connectors, ChatGPT plugins, n8n MCP nodes, and any platform that supports the MCP protocol over HTTP.
+
+### Multi-Location Writes
+
+When multiple relay clients are connected, write operations require a `__location` argument passed to `unifi_execute`:
+
+```json
+{
+  "tool_name": "block_client",
+  "arguments": { "mac": "aa:bb:cc:dd:ee:ff" },
+  "__location": "a1b2c3d4-..."
+}
+```
+
+Read-only operations (tools with `readOnlyHint: true`) are automatically fanned out to all connected locations and results are returned as an aggregated response.
+
+---
+
+## Security
+
+- **Timing-safe token comparison** — all token validation uses constant-time comparison to prevent timing attacks
+- **SHA-256 hashed storage** — relay tokens are stored as hashes in SQLite; the plaintext is never persisted
+- **Per-location isolation** — each relay client is identified by its own relay token and location ID; locations cannot access each other's data
+- **HTTPS/WSS transport** — all traffic is encrypted in transit; Cloudflare terminates TLS at the edge
+- **No credentials in config** — tokens and secrets are managed via the CLI or `wrangler secret put`, never committed to source
+
+---
+
+## Related
+
+- [unifi-mcp](https://github.com/sirkirby/unifi-mcp) — UniFi MCP server and `unifi-mcp-relay` client that connects to this relay worker

package/bin/cli.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+
+const COMMANDS = {
+  install: () => import("../src/commands/install.mjs"),
+  upgrade: () => import("../src/commands/upgrade.mjs"),
+  "add-location": () => import("../src/commands/add-location.mjs"),
+  "rotate-tokens": () => import("../src/commands/rotate-tokens.mjs"),
+  status: () => import("../src/commands/status.mjs"),
+  destroy: () => import("../src/commands/destroy.mjs"),
+};
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    version: { type: "boolean", short: "v" },
+    help: { type: "boolean", short: "h" },
+    "non-interactive": { type: "boolean" },
+    yes: { type: "boolean", short: "y" },
+    "worker-name": { type: "string" },
+    "location-name": { type: "string" },
+    "worker-url": { type: "string" },
+    "admin-token": { type: "string" },
+    token: { type: "string" },
+  },
+});
+
+if (values.version) {
+  const { readFileSync } = await import("node:fs");
+  const { fileURLToPath } = await import("node:url");
+  const { join, dirname } = await import("node:path");
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const command = positionals[0];
+
+if (values.help || !command) {
+  console.log(`
+Usage: unifi-mcp-worker <command> [options]
+
+Commands:
+  install         Deploy the Cloudflare Worker and generate tokens
+  upgrade         Redeploy the latest worker code
+  add-location    Add a new location (generates a relay token)
+  rotate-tokens   Rotate agent, admin, or relay tokens
+  status          Show deployment info and token summary
+  destroy         Remove the worker and clean up
+
+Options:
+  --version, -v          Show CLI version
+  --help, -h             Show this help
+  --non-interactive      Disable interactive prompts (requires flags for all values)
+  --yes, -y              Skip confirmation prompts
+  --worker-name <name>   Worker name (default: unifi-mcp-relay)
+  --location-name <name> Location name (default: Home Lab)
+  --worker-url <url>     Worker URL (for add-location, rotate-tokens)
+  --admin-token <token>  Admin token override
+  --token <type>         Token to rotate: agent, admin, relay, all
+`);
+  process.exit(0);
+}
+
+if (!COMMANDS[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'unifi-mcp-worker --help' for available commands.`);
+  process.exit(1);
+}
+
+const mod = await COMMANDS[command]();
+await mod.run(values);

package/install.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+COMMAND="${1:-install}"
+
+echo ""
+echo "  UniFi MCP Worker CLI"
+echo ""
+
+# Check Node.js
+if ! command -v node &>/dev/null; then
+    echo "  Error: Node.js is required but not installed."
+    echo "  Install it from https://nodejs.org/ or via your package manager:"
+    echo "    brew install node      (macOS)"
+    echo "    apt install nodejs     (Debian/Ubuntu)"
+    echo "    winget install Volta   (Windows)"
+    echo ""
+    exit 1
+fi
+
+# Check minimum Node version (18+)
+NODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1)
+if [ "$NODE_VERSION" -lt 18 ]; then
+    echo "  Error: Node.js 18+ required. Found: $(node -v)"
+    echo "  Update from https://nodejs.org/"
+    exit 1
+fi
+
+echo "  Node.js $(node -v) detected."
+
+# Install or update the CLI
+if command -v unifi-mcp-worker &>/dev/null; then
+    echo "  Updating unifi-mcp-worker CLI..."
+    npm install -g unifi-mcp-worker@latest --silent 2>/dev/null || npm install -g unifi-mcp-worker@latest
+else
+    echo "  Installing unifi-mcp-worker CLI..."
+    npm install -g unifi-mcp-worker --silent 2>/dev/null || npm install -g unifi-mcp-worker
+fi
+
+echo ""
+
+# Run the requested command, passing through any additional args
+shift 2>/dev/null || true
+unifi-mcp-worker "$COMMAND" "$@"

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "unifi-mcp-worker",
+  "version": "1.0.0",
+  "description": "CLI to deploy and manage the UniFi MCP Cloudflare Worker relay",
+  "type": "module",
+  "bin": {
+    "unifi-mcp-worker": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "worker/src/",
+    "worker/package.json",
+    "worker/package-lock.json",
+    "worker/wrangler.toml",
+    "worker/tsconfig.json",
+    "worker/vitest.config.ts",
+    "install.sh"
+  ],
+  "scripts": {
+    "test": "node --test test/cli/*.test.mjs",
+    "test:worker": "cd worker && npm test",
+    "test:all": "npm test && npm run test:worker"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "chalk": "^5.4.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sirkirby/unifi-mcp-worker.git"
+  }
+}

package/src/commands/add-location.mjs

@@ -0,0 +1,92 @@
+// src/commands/add-location.mjs
+import prompts from "prompts";
+import { loadConfig, saveConfig } from "../lib/config.mjs";
+import { healthCheck, createLocationToken } from "../lib/api.mjs";
+import { showAddLocationSuccess, showError } from "../lib/display.mjs";
+
+export async function run(flags) {
+  const config = loadConfig();
+  if (!config) {
+    showError("No deployment found. Run 'unifi-mcp-worker install' first.");
+    process.exit(1);
+  }
+
+  let locationName, workerUrl, adminToken;
+
+  if (flags["non-interactive"]) {
+    locationName = flags["location-name"];
+    workerUrl = flags["worker-url"] || config.worker_url;
+    adminToken = flags["admin-token"] || config.admin_token;
+    if (!locationName) {
+      showError("--location-name is required in non-interactive mode.");
+      process.exit(1);
+    }
+  } else {
+    const answers = await prompts([
+      {
+        type: "text",
+        name: "locationName",
+        message: "Location name",
+        validate: (v) => (v ? true : "Location name is required"),
+      },
+      {
+        type: "text",
+        name: "workerUrl",
+        message: "Worker URL",
+        initial: config.worker_url,
+      },
+      {
+        type: "text",
+        name: "adminToken",
+        message: "Admin token",
+        initial: config.admin_token,
+      },
+    ]);
+    locationName = answers.locationName;
+    workerUrl = answers.workerUrl;
+    adminToken = answers.adminToken;
+  }
+
+  console.log("\nChecking worker health...");
+  const health = await healthCheck(workerUrl);
+  if (!health.ok) {
+    showError(`Worker not reachable at ${workerUrl}`);
+    console.error("  Check that:");
+    console.error("  - The URL is correct");
+    console.error("  - The worker is deployed (run 'unifi-mcp-worker status')");
+    console.error("  - Cloudflare is not experiencing issues");
+    if (health.error) console.error(`  Error: ${health.error}`);
+    process.exit(1);
+  }
+
+  try {
+    console.log(`Creating location "${locationName}"...`);
+    const loc = await createLocationToken(workerUrl, adminToken, locationName);
+
+    const existingIdx = config.locations.findIndex(
+      (l) => l.location_name === locationName
+    );
+    if (existingIdx >= 0) {
+      config.locations[existingIdx].relay_token = loc.relayToken;
+      config.locations[existingIdx].location_id = loc.locationId;
+    } else {
+      config.locations.push({
+        location_name: locationName,
+        relay_token: loc.relayToken,
+        location_id: loc.locationId,
+        created_at: new Date().toISOString(),
+      });
+    }
+
+    saveConfig(config);
+
+    showAddLocationSuccess({
+      locationName,
+      relayToken: loc.relayToken,
+      workerUrl,
+    });
+  } catch (err) {
+    showError(`Failed to create location: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/destroy.mjs

@@ -0,0 +1,75 @@
+// src/commands/destroy.mjs
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import prompts from "prompts";
+import chalk from "chalk";
+import { loadConfig, deleteConfig } from "../lib/config.mjs";
+import { ensureWrangler, checkWranglerAuth, isGhAvailable } from "../lib/prerequisites.mjs";
+import { deleteWorker, login } from "../lib/wrangler.mjs";
+import { showError } from "../lib/display.mjs";
+
+const execFileAsync = promisify(execFile);
+
+export async function run(flags) {
+  const config = loadConfig();
+  if (!config) {
+    showError("No deployment found. Nothing to destroy.");
+    process.exit(1);
+  }
+
+  if (!flags.yes && !flags["non-interactive"]) {
+    const answer = await prompts({
+      type: "confirm",
+      name: "confirm",
+      message: `This will delete worker "${config.worker_name}" and all associated data. Are you sure?`,
+      initial: false,
+    });
+    if (!answer.confirm) {
+      console.log("Cancelled.");
+      process.exit(0);
+    }
+  }
+
+  const wranglerOk = await ensureWrangler();
+  if (!wranglerOk) process.exit(1);
+
+  const authed = await checkWranglerAuth();
+  if (!authed) {
+    console.log("You need to log in to Cloudflare.");
+    await login();
+  }
+
+  try {
+    console.log(`\nDeleting worker "${config.worker_name}"...`);
+    await deleteWorker(config.worker_name);
+    console.log("Worker deleted.");
+
+    if (config.auto_update_repo) {
+      const ghOk = await isGhAvailable();
+      if (ghOk) {
+        let deleteRepo = flags.yes || flags["non-interactive"];
+        if (!deleteRepo) {
+          const answer = await prompts({
+            type: "confirm",
+            name: "deleteRepo",
+            message: `Delete auto-update repo "${config.auto_update_repo}"?`,
+            initial: false,
+          });
+          deleteRepo = answer.deleteRepo;
+        }
+        if (deleteRepo) {
+          await execFileAsync("gh", ["repo", "delete", config.auto_update_repo, "--yes"], {
+            timeout: 30_000,
+          });
+          console.log("Auto-update repo deleted.");
+        }
+      }
+    }
+
+    deleteConfig();
+    console.log(chalk.green("\n  Worker removed. Cloudflare account and local config cleaned up.\n"));
+  } catch (err) {
+    showError(`Destroy failed: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/install.mjs

@@ -0,0 +1,149 @@
+// src/commands/install.mjs
+import prompts from "prompts";
+import { loadConfig, saveConfig } from "../lib/config.mjs";
+import { generateToken } from "../lib/tokens.mjs";
+import { ensureWrangler, checkWranglerAuth } from "../lib/prerequisites.mjs";
+import { deploy, putSecret, login } from "../lib/wrangler.mjs";
+import { createLocationToken } from "../lib/api.mjs";
+import { showInstallSuccess, showError } from "../lib/display.mjs";
+
+export async function run(flags) {
+  const existing = loadConfig();
+  if (existing && !existing.setup_incomplete) {
+    showError("A deployment already exists. Run 'unifi-mcp-worker status' to see it.");
+    showError("To start fresh, run 'unifi-mcp-worker destroy' first.");
+    process.exit(1);
+  }
+
+  const wranglerOk = await ensureWrangler();
+  if (!wranglerOk) process.exit(1);
+
+  const authed = await checkWranglerAuth();
+  if (!authed) {
+    console.log("You need to log in to Cloudflare.");
+    await login();
+  }
+
+  const resuming = existing?.setup_incomplete;
+  const resumeFrom = resuming ? existing._resume_step || "deploy" : "deploy";
+
+  let workerName, locationName, customDomain;
+
+  if (resuming) {
+    workerName = existing.worker_name;
+    locationName = flags["location-name"] || "Home Lab";
+  } else if (flags["non-interactive"]) {
+    workerName = flags["worker-name"] || "unifi-mcp-relay";
+    locationName = flags["location-name"] || "Home Lab";
+  } else {
+    const answers = await prompts([
+      {
+        type: "text",
+        name: "workerName",
+        message: "Worker name",
+        initial: "unifi-mcp-relay",
+      },
+      {
+        type: "text",
+        name: "customDomain",
+        message: "Custom domain (leave blank for default *.workers.dev)",
+        initial: "",
+      },
+      {
+        type: "text",
+        name: "locationName",
+        message: "Location name for your first relay",
+        initial: "Home Lab",
+      },
+    ]);
+    workerName = answers.workerName;
+    customDomain = answers.customDomain || null;
+    locationName = answers.locationName;
+  }
+
+  if (!workerName || !locationName) {
+    showError("Worker name and location name are required.");
+    process.exit(1);
+  }
+
+  const agentToken = resuming ? existing.agent_token : generateToken();
+  const adminToken = resuming ? existing.admin_token : generateToken();
+
+  try {
+    let workerUrl = existing?.worker_url;
+
+    if (resumeFrom === "deploy") {
+      console.log(`\nDeploying worker "${workerName}"...`);
+      const result = await deploy(workerName);
+      workerUrl = result.workerUrl;
+      if (!workerUrl) {
+        workerUrl = `https://${workerName}.workers.dev`;
+      }
+      console.log(`Deployed to ${workerUrl}`);
+
+      saveConfig({
+        setup_incomplete: true,
+        _resume_step: "secrets",
+        worker_name: workerName,
+        worker_url: workerUrl,
+        agent_token: agentToken,
+        admin_token: adminToken,
+        locations: [],
+        created_at: new Date().toISOString(),
+      });
+    }
+
+    if (resumeFrom === "deploy" || resumeFrom === "secrets") {
+      console.log("Setting AGENT_TOKEN...");
+      await putSecret(workerName, "AGENT_TOKEN", agentToken);
+      console.log("Setting ADMIN_TOKEN...");
+      await putSecret(workerName, "ADMIN_TOKEN", adminToken);
+
+      const cfg = loadConfig();
+      cfg._resume_step = "location";
+      saveConfig(cfg);
+    }
+
+    if (resumeFrom === "deploy" || resumeFrom === "secrets" || resumeFrom === "location") {
+      console.log(`Creating location "${locationName}"...`);
+      await new Promise((r) => setTimeout(r, 3000));
+
+      const loc = await createLocationToken(
+        workerUrl || existing?.worker_url,
+        adminToken || existing?.admin_token,
+        locationName
+      );
+
+      saveConfig({
+        worker_name: workerName,
+        worker_url: workerUrl || existing?.worker_url,
+        custom_domain: customDomain || null,
+        agent_token: agentToken || existing?.agent_token,
+        admin_token: adminToken || existing?.admin_token,
+        locations: [
+          {
+            location_name: locationName,
+            relay_token: loc.relayToken,
+            location_id: loc.locationId,
+            created_at: new Date().toISOString(),
+          },
+        ],
+        auto_update_repo: null,
+        created_at: existing?.created_at || new Date().toISOString(),
+        last_upgraded: new Date().toISOString(),
+      });
+
+      showInstallSuccess({
+        workerUrl: workerUrl || existing?.worker_url,
+        agentToken: agentToken || existing?.agent_token,
+        adminToken: adminToken || existing?.admin_token,
+        relayToken: loc.relayToken,
+        locationName,
+      });
+    }
+  } catch (err) {
+    showError(`Install failed: ${err.message}`);
+    console.error("\nPartial state saved. Re-run 'unifi-mcp-worker install' to resume.");
+    process.exit(1);
+  }
+}