@owine/unifi-protect-mcp 2.1.0 → 2.2.0

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import WebSocket from "ws";
 import { Config } from "./config.js";
 export declare class ProtectClient {
     private baseUrl;
@@ -13,4 +14,5 @@ export declare class ProtectClient {
         mimeType: string;
     }>;
     postBinary(path: string, data: Buffer, contentType: string): Promise<unknown>;
+    connectWebSocket(path: string): WebSocket;
 }

package/dist/client.js

@@ -1,6 +1,10 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProtectClient = void 0;
+const ws_1 = __importDefault(require("ws"));
 class ProtectClient {
     baseUrl;
     headers;
@@ -80,5 +84,12 @@ class ProtectClient {
         }
         return response.text();
     }
+    connectWebSocket(path) {
+        const url = `wss://${this.baseUrl.replace(/^https?:\/\//, "")}${path}`;
+        return new ws_1.default(url, {
+            headers: { "X-API-KEY": this.headers["X-API-KEY"] },
+            rejectUnauthorized: process.env.NODE_TLS_REJECT_UNAUTHORIZED !== "0",
+        });
+    }
 }
 exports.ProtectClient = ProtectClient;

package/dist/tools/cameras.js

@@ -34,11 +34,20 @@ function registerCameraTools(server, client, readOnly) {
     });
     server.registerTool("protect_get_snapshot", {
         description: "Get a JPEG snapshot from a camera (returns image)",
-        inputSchema: { id: zod_1.z.string().describe("Camera ID") },
+        inputSchema: {
+            id: zod_1.z.string().describe("Camera ID"),
+            highQuality: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, request a high-quality snapshot"),
+        },
         annotations: safety_js_1.READ_ONLY,
-    }, async ({ id }) => {
+    }, async ({ id, highQuality }) => {
         try {
-            const { data, mimeType } = await client.getBinary((0, url_js_1.safePath) `/cameras/${id}/snapshot`);
+            const url = highQuality
+                ? (0, url_js_1.safePath) `/cameras/${id}/snapshot?highQuality=true`
+                : (0, url_js_1.safePath) `/cameras/${id}/snapshot`;
+            const { data, mimeType } = await client.getBinary(url);
             return {
                 content: [
                     {
@@ -75,7 +84,7 @@ function registerCameraTools(server, client, readOnly) {
             id: zod_1.z.string().describe("Camera ID"),
             settings: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Partial camera settings to update. Known fields: name (string), osdSettings (object), ledSettings (object), lcdMessage (object), videoMode (string), hdrType (string), smartDetectSettings (object)"),
+                .describe("Partial camera settings to update. Known fields: name (string), osdSettings (object), ledSettings (object), lcdMessage (object), videoMode (string: \"default\" | \"highFps\" | \"slo-mo\"), hdrType (string: \"off\" | \"normal\" | \"always\"), micVolume (number 0-100), smartDetectSettings (object)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -98,18 +107,23 @@ function registerCameraTools(server, client, readOnly) {
         description: "Create an RTSPS stream session for a camera",
         inputSchema: {
             id: zod_1.z.string().describe("Camera ID"),
+            qualities: zod_1.z
+                .array(zod_1.z.enum(["high", "medium", "low", "package"]))
+                .describe("Quality levels to include in the RTSPS stream"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
         annotations: safety_js_1.WRITE,
-    }, async ({ id, dryRun }) => {
+    }, async ({ id, qualities, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`);
+                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`, { qualities });
             }
-            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`);
+            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`, {
+                qualities,
+            });
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -120,18 +134,21 @@ function registerCameraTools(server, client, readOnly) {
         description: "Stop and delete an active RTSPS stream session for a camera",
         inputSchema: {
             id: zod_1.z.string().describe("Camera ID"),
+            qualities: zod_1.z
+                .array(zod_1.z.enum(["high", "medium", "low", "package"]))
+                .describe("Quality levels to remove from the RTSPS stream"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
         annotations: safety_js_1.DESTRUCTIVE,
-    }, async ({ id, dryRun }) => {
+    }, async ({ id, qualities, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("DELETE", (0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`);
+                return (0, safety_js_1.formatDryRun)("DELETE", (0, url_js_1.safePath) `/cameras/${id}/rtsps-stream?qualities=${qualities.join(",")}`);
             }
-            const data = await client.delete((0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`);
+            const data = await client.delete((0, url_js_1.safePath) `/cameras/${id}/rtsps-stream?qualities=${qualities.join(",")}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -185,7 +202,7 @@ function registerCameraTools(server, client, readOnly) {
         description: "Start PTZ patrol on a camera at a given slot",
         inputSchema: {
             id: zod_1.z.string().describe("Camera ID"),
-            slot: zod_1.z.number().int().describe("Patrol slot number"),
+            slot: zod_1.z.number().int().min(0).max(4).describe("Patrol slot number (0-4)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -230,7 +247,7 @@ function registerCameraTools(server, client, readOnly) {
         description: "Move camera PTZ to a preset position",
         inputSchema: {
             id: zod_1.z.string().describe("Camera ID"),
-            slot: zod_1.z.number().int().describe("PTZ preset slot number"),
+            slot: zod_1.z.number().int().min(-1).max(4).describe("PTZ preset slot number (0-4, or -1 for home position)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()

package/dist/tools/devices.js

@@ -7,8 +7,8 @@ const safety_js_1 = require("../utils/safety.js");
 const url_js_1 = require("../utils/url.js");
 const settingsHints = {
     light: "Known fields: name (string), isLightForceEnabled (boolean), lightModeSettings (object with mode, enableAt), lightDeviceSettings (object with isIndicatorEnabled, pirDuration, pirSensitivity, ledLevel)",
-    sensor: "Known fields: name (string), mountType (string), motionSettings (object), humiditySettings (object), temperatureSettings (object), lightSettings (object), alarmSettings (object)",
-    chime: "Known fields: name (string), volume (number), ringSettings (array of ring tone configurations)",
+    sensor: "Known fields: name (string), motionSettings (object), humiditySettings (object), temperatureSettings (object), lightSettings (object), alarmSettings (object)",
+    chime: "Known fields: name (string), cameraIds (array of camera IDs linked to the chime), ringSettings (array of ring tone configurations)",
     viewer: "Known fields: name (string), liveview (string, liveview ID to display)",
 };
 function registerDeviceCrud(server, client, deviceType, readOnly) {

package/dist/tools/files.js

@@ -7,11 +7,11 @@ const safety_js_1 = require("../utils/safety.js");
 const url_js_1 = require("../utils/url.js");
 function registerFileTools(server, client, readOnly) {
     server.registerTool("protect_list_files", {
-        description: "List files of a given type (e.g. 'video', 'timelapse')",
+        description: "List files of a given type (only 'animations' is supported)",
         inputSchema: {
             fileType: zod_1.z
                 .string()
-                .describe("File type to list (e.g. 'video', 'timelapse')"),
+                .describe("File type to list (only 'animations' is currently supported)"),
         },
         annotations: safety_js_1.READ_ONLY,
     }, async ({ fileType }) => {
@@ -28,7 +28,7 @@ function registerFileTools(server, client, readOnly) {
     server.registerTool("protect_trigger_alarm_webhook", {
         description: "Trigger an alarm manager webhook by ID. This fires an external alarm action.",
         inputSchema: {
-            id: zod_1.z.string().describe("Webhook ID"),
+            id: zod_1.z.string().describe("User-defined webhook ID matching an alarm manager configuration"),
             confirm: zod_1.z
                 .literal(true)
                 .describe("Must be true to confirm triggering the alarm webhook"),
@@ -53,8 +53,8 @@ function registerFileTools(server, client, readOnly) {
             base64Data: zod_1.z.string().describe("Base64-encoded file content"),
             contentType: zod_1.z
                 .string()
-                .default("application/octet-stream")
-                .describe("MIME type of the file"),
+                .default("image/gif")
+                .describe("MIME type of the file (accepted: image/gif, image/png, image/jpeg)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()

package/dist/tools/index.js

@@ -6,8 +6,10 @@ const cameras_js_1 = require("./cameras.js");
 const devices_js_1 = require("./devices.js");
 const liveviews_js_1 = require("./liveviews.js");
 const files_js_1 = require("./files.js");
+const subscriptions_js_1 = require("./subscriptions.js");
 function registerAllTools(server, client, readOnly) {
     (0, system_js_1.registerSystemTools)(server, client);
+    (0, subscriptions_js_1.registerSubscriptionTools)(server, client);
     (0, cameras_js_1.registerCameraTools)(server, client, readOnly);
     (0, devices_js_1.registerDeviceTools)(server, client, readOnly);
     (0, liveviews_js_1.registerLiveviewTools)(server, client, readOnly);

package/dist/tools/liveviews.js

@@ -38,7 +38,7 @@ function registerLiveviewTools(server, client, readOnly) {
         inputSchema: {
             settings: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Liveview configuration. Required fields: name (string), layout (number of slots), slots (array of {cameras: string[], cycleMode: string, cycleInterval: number}), isDefault (boolean), isGlobal (boolean)"),
+                .describe("Liveview configuration. Required fields: id (string), modelKey (string, must be 'liveview'), owner (string, user ID), name (string), layout (number of slots), slots (array of {cameras: string[], cycleMode: string, cycleInterval: number}), isDefault (boolean), isGlobal (boolean)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -58,12 +58,12 @@ function registerLiveviewTools(server, client, readOnly) {
         }
     });
     server.registerTool("protect_update_liveview", {
-        description: "Update an existing live view (partial update via PATCH)",
+        description: "Update an existing live view (full replacement via PUT-style PATCH — include all fields)",
         inputSchema: {
             id: zod_1.z.string().describe("Liveview ID"),
             settings: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Partial liveview settings to update. Known fields: name (string), layout (number), slots (array of {cameras: string[], cycleMode: string, cycleInterval: number}), isDefault (boolean), isGlobal (boolean)"),
+                .describe("Full liveview object for update (all fields required). Known fields: id (string), modelKey (string, must be 'liveview'), owner (string, user ID), name (string), layout (number), slots (array of {cameras: string[], cycleMode: string, cycleInterval: number}), isDefault (boolean), isGlobal (boolean)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()

package/dist/tools/subscriptions.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ProtectClient } from "../client.js";
+export declare function registerSubscriptionTools(server: McpServer, client: ProtectClient): void;

package/dist/tools/subscriptions.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSubscriptionTools = registerSubscriptionTools;
+const zod_1 = require("zod");
+const responses_js_1 = require("../utils/responses.js");
+const safety_js_1 = require("../utils/safety.js");
+const durationSchema = zod_1.z
+    .number()
+    .min(1)
+    .max(30)
+    .default(5)
+    .describe("Seconds to listen (1-30, default 5)");
+function collectMessages(client, path, duration) {
+    return new Promise((resolve) => {
+        const messages = [];
+        let error;
+        const ws = client.connectWebSocket(path);
+        const timeout = setTimeout(() => {
+            ws.close();
+        }, duration * 1000);
+        ws.on("message", (data) => {
+            const text = String(data);
+            try {
+                messages.push(JSON.parse(text));
+            }
+            catch {
+                messages.push(text);
+            }
+        });
+        ws.on("error", (err) => {
+            error = err.message;
+            clearTimeout(timeout);
+            ws.close();
+        });
+        ws.on("close", () => {
+            clearTimeout(timeout);
+            const result = { messages, duration };
+            if (error)
+                result.error = error;
+            resolve(result);
+        });
+    });
+}
+function registerSubscriptionTools(server, client) {
+    server.registerTool("protect_subscribe_devices", {
+        description: "Connect to the device update WebSocket and collect messages for a specified duration. Returns real-time add/update/remove events for Protect-managed hardware devices.",
+        inputSchema: { duration: durationSchema },
+        annotations: safety_js_1.READ_ONLY,
+    }, async ({ duration }) => {
+        try {
+            const data = await collectMessages(client, "/subscribe/devices", duration);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.registerTool("protect_subscribe_events", {
+        description: "Connect to the Protect event WebSocket and collect messages for a specified duration. Returns events including motion, ring (doorbell), and smartDetect (person/vehicle/animal/package).",
+        inputSchema: { duration: durationSchema },
+        annotations: safety_js_1.READ_ONLY,
+    }, async ({ duration }) => {
+        try {
+            const data = await collectMessages(client, "/subscribe/events", duration);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-protect-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for UniFi Protect Integration API",
   "main": "dist/index.js",
   "bin": {
@@ -37,11 +37,13 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.19.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/node": "24.12.0",
+    "@types/ws": "^8.18.0",
     "@vitest/coverage-v8": "4.0.18",
     "eslint": "10.0.3",
     "typescript": "5.9.3",