@owine/unifi-protect-mcp 2.0.0 → 2.0.1

package/dist/tools/cameras.js

@@ -3,14 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCameraTools = registerCameraTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
-const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
-const DESTRUCTIVE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true };
+const safety_js_1 = require("../utils/safety.js");
 function registerCameraTools(server, client, readOnly) {
     // --- Read-only tools (always registered) ---
     server.registerTool("protect_list_cameras", {
         description: "List all cameras managed by UniFi Protect",
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async () => {
         try {
             const data = await client.get("/cameras");
@@ -23,7 +21,7 @@ function registerCameraTools(server, client, readOnly) {
     server.registerTool("protect_get_camera", {
         description: "Get details for a specific camera by ID",
         inputSchema: { id: zod_1.z.string().describe("Camera ID") },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
             const data = await client.get(`/cameras/${id}`);
@@ -36,7 +34,7 @@ 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") },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
             const { data, mimeType } = await client.getBinary(`/cameras/${id}/snapshot`);
@@ -57,7 +55,7 @@ function registerCameraTools(server, client, readOnly) {
     server.registerTool("protect_get_rtsp_streams", {
         description: "Get active RTSPS stream sessions for a camera",
         inputSchema: { id: zod_1.z.string().describe("Camera ID") },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
             const data = await client.get(`/cameras/${id}/rtsps-stream`);
@@ -82,11 +80,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, settings, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "PATCH", path: `/cameras/${id}`, body: settings });
+                return (0, safety_js_1.formatDryRun)("PATCH", `/cameras/${id}`, settings);
             }
             const data = await client.patch(`/cameras/${id}`, settings);
             return (0, responses_js_1.formatSuccess)(data);
@@ -104,11 +102,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/rtsps-stream` });
+                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/rtsps-stream`);
             }
             const data = await client.post(`/cameras/${id}/rtsps-stream`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -126,11 +124,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: DESTRUCTIVE_ANNOTATIONS,
+        annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ id, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "DELETE", path: `/cameras/${id}/rtsps-stream` });
+                return (0, safety_js_1.formatDryRun)("DELETE", `/cameras/${id}/rtsps-stream`);
             }
             const data = await client.delete(`/cameras/${id}/rtsps-stream`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -148,11 +146,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/talkback-session` });
+                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/talkback-session`);
             }
             const data = await client.post(`/cameras/${id}/talkback-session`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -169,8 +167,11 @@ function registerCameraTools(server, client, readOnly) {
                 .literal(true)
                 .describe("Must be true to confirm this irreversible action"),
         },
-        annotations: DESTRUCTIVE_ANNOTATIONS,
-    }, async ({ id }) => {
+        annotations: safety_js_1.DESTRUCTIVE,
+    }, async ({ id, confirm }) => {
+        const denied = (0, safety_js_1.requireConfirmation)(confirm, "permanently disable the microphone");
+        if (denied)
+            return denied;
         try {
             const data = await client.post(`/cameras/${id}/disable-mic-permanently`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -189,11 +190,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, slot, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/ptz/patrol/start/${slot}` });
+                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/ptz/patrol/start/${slot}`);
             }
             const data = await client.post(`/cameras/${id}/ptz/patrol/start/${slot}`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -211,11 +212,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/ptz/patrol/stop` });
+                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/ptz/patrol/stop`);
             }
             const data = await client.post(`/cameras/${id}/ptz/patrol/stop`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -234,11 +235,11 @@ function registerCameraTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, slot, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/ptz/goto/${slot}` });
+                return (0, safety_js_1.formatDryRun)("POST", `/cameras/${id}/ptz/goto/${slot}`);
             }
             const data = await client.post(`/cameras/${id}/ptz/goto/${slot}`);
             return (0, responses_js_1.formatSuccess)(data);

package/dist/tools/devices.js

@@ -3,8 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDeviceTools = registerDeviceTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
-const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
+const safety_js_1 = require("../utils/safety.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)",
@@ -16,7 +15,7 @@ function registerDeviceCrud(server, client, deviceType, readOnly) {
     const label = deviceType.charAt(0).toUpperCase() + deviceType.slice(1);
     server.registerTool(`protect_list_${plural}`, {
         description: `List all ${plural} managed by UniFi Protect`,
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async () => {
         try {
             const data = await client.get(`/${plural}`);
@@ -29,7 +28,7 @@ function registerDeviceCrud(server, client, deviceType, readOnly) {
     server.registerTool(`protect_get_${deviceType}`, {
         description: `Get details for a specific ${deviceType} by ID`,
         inputSchema: { id: zod_1.z.string().describe(`${label} ID`) },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
             const data = await client.get(`/${plural}/${id}`);
@@ -52,11 +51,11 @@ function registerDeviceCrud(server, client, deviceType, readOnly) {
                     .optional()
                     .describe("If true, return what would happen without making changes"),
             },
-            annotations: WRITE_ANNOTATIONS,
+            annotations: safety_js_1.WRITE,
         }, async ({ id, settings, dryRun }) => {
             try {
                 if (dryRun) {
-                    return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "PATCH", path: `/${plural}/${id}`, body: settings });
+                    return (0, safety_js_1.formatDryRun)("PATCH", `/${plural}/${id}`, settings);
                 }
                 const data = await client.patch(`/${plural}/${id}`, settings);
                 return (0, responses_js_1.formatSuccess)(data);

package/dist/tools/files.js

@@ -3,9 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerFileTools = registerFileTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
-const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
-const DESTRUCTIVE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true };
+const safety_js_1 = require("../utils/safety.js");
 function registerFileTools(server, client, readOnly) {
     server.registerTool("protect_list_files", {
         description: "List files of a given type (e.g. 'video', 'timelapse')",
@@ -14,7 +12,7 @@ function registerFileTools(server, client, readOnly) {
                 .string()
                 .describe("File type to list (e.g. 'video', 'timelapse')"),
         },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async ({ fileType }) => {
         try {
             const data = await client.get(`/files/${fileType}`);
@@ -34,8 +32,11 @@ function registerFileTools(server, client, readOnly) {
                 .literal(true)
                 .describe("Must be true to confirm triggering the alarm webhook"),
         },
-        annotations: DESTRUCTIVE_ANNOTATIONS,
-    }, async ({ id }) => {
+        annotations: safety_js_1.DESTRUCTIVE,
+    }, async ({ id, confirm }) => {
+        const denied = (0, safety_js_1.requireConfirmation)(confirm, "trigger the alarm webhook");
+        if (denied)
+            return denied;
         try {
             await client.post(`/alarm-manager/webhook/${id}`);
             return (0, responses_js_1.formatSuccess)({ triggered: true, webhookId: id });
@@ -58,14 +59,11 @@ function registerFileTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ fileType, base64Data, contentType, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({
-                    dryRun: true,
-                    action: "POST",
-                    path: `/files/${fileType}`,
+                return (0, safety_js_1.formatDryRun)("POST", `/files/${fileType}`, {
                     contentType,
                     dataLength: base64Data.length,
                 });

package/dist/tools/liveviews.js

@@ -3,12 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerLiveviewTools = registerLiveviewTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
-const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
+const safety_js_1 = require("../utils/safety.js");
 function registerLiveviewTools(server, client, readOnly) {
     server.registerTool("protect_list_liveviews", {
         description: "List all live views configured in UniFi Protect",
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async () => {
         try {
             const data = await client.get("/liveviews");
@@ -21,7 +20,7 @@ function registerLiveviewTools(server, client, readOnly) {
     server.registerTool("protect_get_liveview", {
         description: "Get details for a specific live view by ID",
         inputSchema: { id: zod_1.z.string().describe("Liveview ID") },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
         try {
             const data = await client.get(`/liveviews/${id}`);
@@ -44,11 +43,11 @@ function registerLiveviewTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ settings, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: "/liveviews", body: settings });
+                return (0, safety_js_1.formatDryRun)("POST", "/liveviews", settings);
             }
             const data = await client.post("/liveviews", settings);
             return (0, responses_js_1.formatSuccess)(data);
@@ -69,11 +68,11 @@ function registerLiveviewTools(server, client, readOnly) {
                 .optional()
                 .describe("If true, return what would happen without making changes"),
         },
-        annotations: WRITE_ANNOTATIONS,
+        annotations: safety_js_1.WRITE,
     }, async ({ id, settings, dryRun }) => {
         try {
             if (dryRun) {
-                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "PATCH", path: `/liveviews/${id}`, body: settings });
+                return (0, safety_js_1.formatDryRun)("PATCH", `/liveviews/${id}`, settings);
             }
             const data = await client.patch(`/liveviews/${id}`, settings);
             return (0, responses_js_1.formatSuccess)(data);

package/dist/tools/system.js

@@ -2,11 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerSystemTools = registerSystemTools;
 const responses_js_1 = require("../utils/responses.js");
-const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
+const safety_js_1 = require("../utils/safety.js");
 function registerSystemTools(server, client) {
     server.registerTool("protect_get_info", {
         description: "Get UniFi Protect system information and version details",
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async () => {
         try {
             const data = await client.get("/meta/info");
@@ -18,7 +18,7 @@ function registerSystemTools(server, client) {
     });
     server.registerTool("protect_list_nvrs", {
         description: "List all NVR (Network Video Recorder) devices",
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: safety_js_1.READ_ONLY,
     }, async () => {
         try {
             const data = await client.get("/nvrs");

package/dist/utils/safety.d.ts

@@ -0,0 +1,34 @@
+/** Annotation constants for tool safety classification */
+export declare const READ_ONLY: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+};
+export declare const WRITE: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: false;
+};
+export declare const DESTRUCTIVE: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+};
+/**
+ * Build a standard dry-run preview response.
+ * Returns the MCP tool result that describes what *would* happen.
+ */
+export declare function formatDryRun(method: string, path: string, body?: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Guard for destructive actions that require explicit confirmation.
+ * Returns an error result if `confirm` is not `true`, otherwise `null`.
+ */
+export declare function requireConfirmation(confirm: boolean, action: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | null;

package/dist/utils/safety.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESTRUCTIVE = exports.WRITE = exports.READ_ONLY = void 0;
+exports.formatDryRun = formatDryRun;
+exports.requireConfirmation = requireConfirmation;
+const responses_js_1 = require("./responses.js");
+/** Annotation constants for tool safety classification */
+exports.READ_ONLY = { readOnlyHint: true, destructiveHint: false };
+exports.WRITE = { readOnlyHint: false, destructiveHint: false };
+exports.DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
+/**
+ * Build a standard dry-run preview response.
+ * Returns the MCP tool result that describes what *would* happen.
+ */
+function formatDryRun(method, path, body) {
+    const preview = { dryRun: true, action: method, path };
+    if (body !== undefined) {
+        preview.body = body;
+    }
+    return (0, responses_js_1.formatSuccess)(preview);
+}
+/**
+ * Guard for destructive actions that require explicit confirmation.
+ * Returns an error result if `confirm` is not `true`, otherwise `null`.
+ */
+function requireConfirmation(confirm, action) {
+    if (confirm !== true) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: You must set confirm to true to ${action}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-protect-mcp",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "MCP server for UniFi Protect Integration API",
   "main": "dist/index.js",
   "bin": {
@@ -20,7 +20,7 @@
     "lint:fix": "eslint . --fix"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^20.19.0 || ^22.13.0 || >=24"
   },
   "repository": {
     "type": "git",
@@ -40,12 +40,12 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.2",
+    "@eslint/js": "10.0.1",
     "@types/node": "24.10.13",
     "@vitest/coverage-v8": "4.0.18",
-    "eslint": "9.39.2",
+    "eslint": "10.0.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.55.0",
+    "typescript-eslint": "8.56.0",
     "vitest": "4.0.18"
   }
 }