@owine/unifi-protect-mcp 2.13.0 → 2.14.0

package/README.md

@@ -48,6 +48,7 @@ claude mcp add-json unifi-protect '{"command":"node","args":["/path/to/unifi-pro
 | `UNIFI_PROTECT_API_KEY` | Yes | — | API key from Protect integration settings |
 | `UNIFI_PROTECT_VERIFY_SSL` | No | `true` | Set to `false` to skip TLS certificate verification (needed for self-signed certs) |
 | `UNIFI_PROTECT_READ_ONLY` | No | `true` | Set to `false` to enable write/mutating tools (default is monitoring-only mode) |
+| `UNIFI_PROTECT_CONSOLE_ID` | No | — | Cloud Connector console ID. Only used when `UNIFI_PROTECT_HOST` is `api.ui.com`; ignored (with a warning on stderr) otherwise |
 
 ### Manual Configuration
 
@@ -74,6 +75,34 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
 This server provides layered safety controls for responsible operation:
 
 - **Tool annotations** — Every tool declares `readOnlyHint` and `destructiveHint` so MCP clients (like Claude Code) can make informed confirmation decisions
+### Cloud Connector
+
+To reach a console through Ubiquiti's Cloud Connector instead of over the local
+network, set `UNIFI_PROTECT_HOST=api.ui.com` and `UNIFI_PROTECT_CONSOLE_ID` to
+the console's ID, and supply a **Site Manager** API key (unifi.ui.com →
+Settings → API) as `UNIFI_PROTECT_API_KEY`. That is a different credential
+from a local console API key. Requests are routed through
+`/v1/connector/consoles/{id}`. Keep TLS verification enabled.
+
+Find your console ID with:
+
+```bash
+curl -s https://api.ui.com/v1/hosts -H "X-API-KEY: $KEY" | jq -r '.data[].id'
+```
+
+**WebSocket subscriptions do not work over Cloud Connector.** The connector
+proxies REST calls but returns HTTP 404 on a WebSocket upgrade, so
+`protect_subscribe_devices` and `protect_subscribe_events` fail fast with an
+explanatory error. Every other tool, including snapshots and file uploads,
+works. Connect directly to the console host if you need subscriptions.
+
+Note that `/v1/hosts` reports `protect` under `controllers` for consoles where
+Protect is merely available, not necessarily installed; only consoles actually
+running Protect will answer.
+
+Setting `UNIFI_PROTECT_CONSOLE_ID` against a local host is not fatal: the
+server logs a warning and talks to that host directly.
+
 - **Read-only mode** — Enabled by default. Only read operations (list, get, snapshot) are registered. Set `UNIFI_PROTECT_READ_ONLY=false` to enable write/mutating tools
 - **Confirmation parameter** — The most dangerous tools (`protect_disable_mic`, `protect_trigger_alarm_webhook`) require an explicit `confirm: true` parameter that must be present for the call to succeed
 - **Dry-run support** — All write tools (except those with `confirm`) accept an optional `dryRun: true` parameter that returns a preview of what would happen without making any changes

package/dist/client.d.ts

@@ -3,6 +3,7 @@ import { Config } from "./config.js";
 export declare class ProtectClient {
     private baseUrl;
     private headers;
+    private usingConnector;
     constructor(config: Config);
     private request;
     get(path: string): Promise<unknown>;

package/dist/client.js

@@ -5,11 +5,59 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProtectClient = void 0;
 const ws_1 = __importDefault(require("ws"));
+/** Protect answers JSON calls quickly; a longer wait means something is wrong. */
+const REQUEST_TIMEOUT_MS = 25_000;
+/** Snapshots and file uploads are larger, so they get a longer budget. */
+const BINARY_TIMEOUT_MS = 60_000;
+const MAX_JSON_BYTES = 10_000_000;
+const MAX_BINARY_BYTES = 100_000_000;
+/** Error text is forwarded to the MCP client, so keep it context-sized. */
+const MAX_ERROR_BODY_CHARS = 2_000;
+/**
+ * Best-effort size guard. Protect sets content-length on the responses that
+ * can actually get large (snapshots, exports); a chunked response without the
+ * header is not caught here.
+ */
+function enforceSizeLimit(response, limit) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit) {
+        throw new Error(`Response exceeds the ${limit.toString()}-byte limit (content-length ${declared.toString()})`);
+    }
+}
+/**
+ * Read an error body for inclusion in a thrown message. Error responses bypass
+ * the caller's size check, so bound them here too: an oversized body is left
+ * unread, and a merely long one is truncated before it reaches an MCP client's
+ * context window.
+ */
+async function readErrorBody(response, limit) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit) {
+        await response.body?.cancel();
+        return `<error body exceeds the ${limit.toString()}-byte limit and was not read>`;
+    }
+    const text = await response.text();
+    return text.length > MAX_ERROR_BODY_CHARS
+        ? `${text.slice(0, MAX_ERROR_BODY_CHARS)}… (truncated)`
+        : text;
+}
 class ProtectClient {
     baseUrl;
     headers;
+    usingConnector;
     constructor(config) {
-        this.baseUrl = `https://${config.host}/proxy/protect/integration/v1`;
+        // Cloud Connector only exists behind api.ui.com. A console ID set against
+        // a local console is ignored rather than fatal: every tool still works
+        // against that console, and refusing to start helps nobody.
+        const useConnector = config.consoleId !== undefined && config.host === "api.ui.com";
+        if (config.consoleId !== undefined && !useConnector) {
+            console.error(`Ignoring UNIFI_PROTECT_CONSOLE_ID: Cloud Connector requires host api.ui.com, but host is ${config.host}.`);
+        }
+        const consolePath = useConnector
+            ? `/v1/connector/consoles/${config.consoleId ?? ""}`
+            : "";
+        this.usingConnector = useConnector;
+        this.baseUrl = `https://${config.host}${consolePath}/proxy/protect/integration/v1`;
         this.headers = {
             "X-API-KEY": config.apiKey,
             "Content-Type": "application/json",
@@ -27,16 +75,24 @@ class ProtectClient {
         if (body !== undefined) {
             options.body = JSON.stringify(body);
         }
+        options.redirect = "error";
+        options.signal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
         const response = await fetch(url, options);
         if (!response.ok) {
-            const text = await response.text();
-            throw new Error(`HTTP ${response.status}: ${text}`);
+            throw new Error(`HTTP ${response.status}: ${await readErrorBody(response, MAX_JSON_BYTES)}`);
         }
+        enforceSizeLimit(response, MAX_JSON_BYTES);
         const contentType = response.headers.get("content-type") ?? "";
+        const text = await response.text();
         if (contentType.includes("application/json")) {
-            return response.json();
+            if (text.trim() === "") {
+                // A bare JSON.parse would report "Unexpected end of JSON input", which
+                // reads as a broken tool rather than an unusable Protect response.
+                throw new Error(`Protect returned an empty body for ${method} ${path} with a JSON content type`);
+            }
+            return JSON.parse(text);
         }
-        return response.text();
+        return text;
     }
     async get(path) {
         return this.request("GET", path);
@@ -55,11 +111,13 @@ class ProtectClient {
         const response = await fetch(url, {
             method: "GET",
             headers: { "X-API-KEY": this.headers["X-API-KEY"] },
+            redirect: "error",
+            signal: AbortSignal.timeout(BINARY_TIMEOUT_MS),
         });
         if (!response.ok) {
-            const text = await response.text();
-            throw new Error(`HTTP ${response.status}: ${text}`);
+            throw new Error(`HTTP ${response.status}: ${await readErrorBody(response, MAX_BINARY_BYTES)}`);
         }
+        enforceSizeLimit(response, MAX_BINARY_BYTES);
         const mimeType = response.headers.get("content-type") ?? "application/octet-stream";
         const arrayBuffer = await response.arrayBuffer();
         return { data: Buffer.from(arrayBuffer), mimeType };
@@ -73,10 +131,11 @@ class ProtectClient {
                 "Content-Type": contentType,
             },
             body: new Uint8Array(data),
+            redirect: "error",
+            signal: AbortSignal.timeout(BINARY_TIMEOUT_MS),
         });
         if (!response.ok) {
-            const text = await response.text();
-            throw new Error(`HTTP ${response.status}: ${text}`);
+            throw new Error(`HTTP ${response.status}: ${await readErrorBody(response, MAX_BINARY_BYTES)}`);
         }
         const ct = response.headers.get("content-type") ?? "";
         if (ct.includes("application/json")) {
@@ -85,6 +144,12 @@ class ProtectClient {
         return response.text();
     }
     connectWebSocket(path) {
+        if (this.usingConnector) {
+            // Verified against a live console: the connector proxies REST calls but
+            // answers 404 to a WebSocket upgrade on the same path. Say so plainly
+            // rather than letting an opaque 404 reach the MCP client.
+            throw new Error("WebSocket subscriptions are not available over Cloud Connector; connect directly to the console host instead");
+        }
         const url = `wss://${this.baseUrl.replace(/^https?:\/\//, "")}${path}`;
         return new ws_1.default(url, {
             headers: { "X-API-KEY": this.headers["X-API-KEY"] },

package/dist/config.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 declare const ConfigSchema: z.ZodObject<{
     host: z.ZodString;
     apiKey: z.ZodString;
+    consoleId: z.ZodOptional<z.ZodString>;
     verifySsl: z.ZodBoolean;
     readOnly: z.ZodBoolean;
 }, z.core.$strip>;

package/dist/config.js

@@ -5,6 +5,13 @@ const zod_1 = require("zod");
 const ConfigSchema = zod_1.z.object({
     host: zod_1.z.string().min(1, "UNIFI_PROTECT_HOST is required"),
     apiKey: zod_1.z.string().min(1, "UNIFI_PROTECT_API_KEY is required"),
+    // Console IDs are hex, UUID- or colon-shaped depending on vintage. The
+    // charset excludes anything that could escape the URL path segment it is
+    // interpolated into.
+    consoleId: zod_1.z
+        .string()
+        .regex(/^[A-Za-z0-9:_-]{1,128}$/, "UNIFI_PROTECT_CONSOLE_ID must be alphanumeric with : _ -")
+        .optional(),
     verifySsl: zod_1.z.boolean(),
     readOnly: zod_1.z.boolean(),
 });
@@ -12,6 +19,9 @@ function loadConfig() {
     const result = ConfigSchema.safeParse({
         host: process.env.UNIFI_PROTECT_HOST,
         apiKey: process.env.UNIFI_PROTECT_API_KEY,
+        ...(process.env.UNIFI_PROTECT_CONSOLE_ID
+            ? { consoleId: process.env.UNIFI_PROTECT_CONSOLE_ID }
+            : {}),
         verifySsl: process.env.UNIFI_PROTECT_VERIFY_SSL !== "false",
         readOnly: process.env.UNIFI_PROTECT_READ_ONLY !== "false",
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-protect-mcp",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "MCP server for UniFi Protect Integration API",
   "main": "dist/index.js",
   "bin": {
@@ -22,7 +22,7 @@
   "engines": {
     "node": "^22.13.0 || ^24.0.0"
   },
-  "packageManager": "pnpm@12.4.1",
+  "packageManager": "pnpm@12.5.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/owine/unifi-protect-mcp.git"
@@ -39,18 +39,18 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "ws": "8.21.3",
-    "zod": "4.6.2"
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.13.4",
+    "@types/node": "24.13.6",
     "@types/ws": "8.18.1",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.10.0",
-    "lefthook": "2.1.12",
+    "@vitest/coverage-v8": "5.0.1",
+    "eslint": "10.11.0",
+    "lefthook": "2.1.14",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.70.0",
-    "vitest": "5.0.0"
+    "vitest": "5.0.1"
   }
 }