@owine/unifi-protect-mcp 2.0.2 → 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

@@ -4,6 +4,7 @@ exports.registerCameraTools = registerCameraTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 const safety_js_1 = require("../utils/safety.js");
+const url_js_1 = require("../utils/url.js");
 function registerCameraTools(server, client, readOnly) {
     // --- Read-only tools (always registered) ---
     server.registerTool("protect_list_cameras", {
@@ -24,7 +25,7 @@ function registerCameraTools(server, client, readOnly) {
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
-            const data = await client.get(`/cameras/${id}`);
+            const data = await client.get((0, url_js_1.safePath) `/cameras/${id}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -33,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(`/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: [
                     {
@@ -58,7 +68,7 @@ function registerCameraTools(server, client, readOnly) {
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
-            const data = await client.get(`/cameras/${id}/rtsps-stream`);
+            const data = await client.get((0, url_js_1.safePath) `/cameras/${id}/rtsps-stream`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -74,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()
@@ -84,9 +94,9 @@ function registerCameraTools(server, client, readOnly) {
     }, async ({ id, settings, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("PATCH", `/cameras/${id}`, settings);
+                return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/cameras/${id}`, settings);
             }
-            const data = await client.patch(`/cameras/${id}`, settings);
+            const data = await client.patch((0, url_js_1.safePath) `/cameras/${id}`, settings);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -97,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", `/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(`/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) {
@@ -119,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", `/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(`/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) {
@@ -150,9 +168,9 @@ function registerCameraTools(server, client, readOnly) {
     }, async ({ id, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/talkback-session`);
+                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/cameras/${id}/talkback-session`);
             }
-            const data = await client.post(`/cameras/${id}/talkback-session`);
+            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/talkback-session`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -173,7 +191,7 @@ function registerCameraTools(server, client, readOnly) {
         if (denied)
             return denied;
         try {
-            const data = await client.post(`/cameras/${id}/disable-mic-permanently`);
+            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/disable-mic-permanently`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -184,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()
@@ -194,9 +212,9 @@ function registerCameraTools(server, client, readOnly) {
     }, async ({ id, slot, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/ptz/patrol/start/${slot}`);
+                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/cameras/${id}/ptz/patrol/start/${slot}`);
             }
-            const data = await client.post(`/cameras/${id}/ptz/patrol/start/${slot}`);
+            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/ptz/patrol/start/${slot}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -216,9 +234,9 @@ function registerCameraTools(server, client, readOnly) {
     }, async ({ id, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/ptz/patrol/stop`);
+                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/cameras/${id}/ptz/patrol/stop`);
             }
-            const data = await client.post(`/cameras/${id}/ptz/patrol/stop`);
+            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/ptz/patrol/stop`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -229,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()
@@ -239,9 +257,9 @@ function registerCameraTools(server, client, readOnly) {
     }, async ({ id, slot, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/ptz/goto/${slot}`);
+                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/cameras/${id}/ptz/goto/${slot}`);
             }
-            const data = await client.post(`/cameras/${id}/ptz/goto/${slot}`);
+            const data = await client.post((0, url_js_1.safePath) `/cameras/${id}/ptz/goto/${slot}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {

package/dist/tools/devices.js

@@ -4,10 +4,11 @@ exports.registerDeviceTools = registerDeviceTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 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) {
@@ -31,7 +32,7 @@ function registerDeviceCrud(server, client, deviceType, readOnly) {
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
-            const data = await client.get(`/${plural}/${id}`);
+            const data = await client.get((0, url_js_1.safePath) `/${plural}/${id}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -55,9 +56,9 @@ function registerDeviceCrud(server, client, deviceType, readOnly) {
         }, async ({ id, settings, dryRun }) => {
             try {
                 if (dryRun) {
-                    return (0, safety_js_1.formatDryRun)("PATCH", `/${plural}/${id}`, settings);
+                    return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/${plural}/${id}`, settings);
                 }
-                const data = await client.patch(`/${plural}/${id}`, settings);
+                const data = await client.patch((0, url_js_1.safePath) `/${plural}/${id}`, settings);
                 return (0, responses_js_1.formatSuccess)(data);
             }
             catch (err) {

package/dist/tools/files.js

@@ -4,18 +4,19 @@ exports.registerFileTools = registerFileTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 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 }) => {
         try {
-            const data = await client.get(`/files/${fileType}`);
+            const data = await client.get((0, url_js_1.safePath) `/files/${fileType}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -27,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"),
@@ -38,7 +39,7 @@ function registerFileTools(server, client, readOnly) {
         if (denied)
             return denied;
         try {
-            await client.post(`/alarm-manager/webhook/${id}`);
+            await client.post((0, url_js_1.safePath) `/alarm-manager/webhook/${id}`);
             return (0, responses_js_1.formatSuccess)({ triggered: true, webhookId: id });
         }
         catch (err) {
@@ -52,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()
@@ -63,13 +64,13 @@ function registerFileTools(server, client, readOnly) {
     }, async ({ fileType, base64Data, contentType, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", `/files/${fileType}`, {
+                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/files/${fileType}`, {
                     contentType,
                     dataLength: base64Data.length,
                 });
             }
             const buffer = Buffer.from(base64Data, "base64");
-            const data = await client.postBinary(`/files/${fileType}`, buffer, contentType);
+            const data = await client.postBinary((0, url_js_1.safePath) `/files/${fileType}`, buffer, contentType);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {

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

@@ -4,6 +4,7 @@ exports.registerLiveviewTools = registerLiveviewTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 const safety_js_1 = require("../utils/safety.js");
+const url_js_1 = require("../utils/url.js");
 function registerLiveviewTools(server, client, readOnly) {
     server.registerTool("protect_list_liveviews", {
         description: "List all live views configured in UniFi Protect",
@@ -23,7 +24,7 @@ function registerLiveviewTools(server, client, readOnly) {
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
-            const data = await client.get(`/liveviews/${id}`);
+            const data = await client.get((0, url_js_1.safePath) `/liveviews/${id}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
@@ -37,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()
@@ -57,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()
@@ -72,9 +73,9 @@ function registerLiveviewTools(server, client, readOnly) {
     }, async ({ id, settings, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("PATCH", `/liveviews/${id}`, settings);
+                return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/liveviews/${id}`, settings);
             }
-            const data = await client.patch(`/liveviews/${id}`, settings);
+            const data = await client.patch((0, url_js_1.safePath) `/liveviews/${id}`, settings);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {

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/dist/utils/url.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tagged template that encodes interpolated values for safe URL path construction.
+ *
+ * This function URL-encodes only the interpolated values, which prevents them from
+ * introducing path traversal (`/`), query (`?`), or fragment (`#`) delimiters.
+ * The literal template segments are not modified, so they must be trusted and should
+ * not contain user-controlled data.
+ *
+ * Values must be raw (unencoded). Pre-encoded values will be double-encoded
+ * (e.g. `%2F` becomes `%252F`), which is the correct defensive behavior.
+ */
+export declare function safePath(strings: TemplateStringsArray, ...values: (string | number)[]): string;

package/dist/utils/url.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safePath = safePath;
+/**
+ * Tagged template that encodes interpolated values for safe URL path construction.
+ *
+ * This function URL-encodes only the interpolated values, which prevents them from
+ * introducing path traversal (`/`), query (`?`), or fragment (`#`) delimiters.
+ * The literal template segments are not modified, so they must be trusted and should
+ * not contain user-controlled data.
+ *
+ * Values must be raw (unencoded). Pre-encoded values will be double-encoded
+ * (e.g. `%2F` becomes `%252F`), which is the correct defensive behavior.
+ */
+function safePath(strings, ...values) {
+    return strings.reduce((result, str, i) => i < values.length
+        ? result + str + encodeURIComponent(String(values[i]))
+        : result + str, "");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-protect-mcp",
-  "version": "2.0.2",
+  "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",