@owine/unifi-protect-mcp 1.0.0 → 2.0.0

package/README.md

@@ -15,15 +15,7 @@ An MCP (Model Context Protocol) server that exposes UniFi Protect's Integration
 Add to Claude Code with a single command — no clone or build needed:
 
 ```bash
-claude mcp add-json unifi-protect '{
-  "command": "npx",
-  "args": ["-y", "@owine/unifi-protect-mcp"],
-  "env": {
-    "UNIFI_PROTECT_HOST": "192.168.1.1",
-    "UNIFI_PROTECT_API_KEY": "your-api-key",
-    "UNIFI_PROTECT_VERIFY_SSL": "false"
-  }
-}' -s user
+claude mcp add-json unifi-protect '{"command":"npx","args":["-y","@owine/unifi-protect-mcp@latest"],"env":{"UNIFI_PROTECT_HOST":"192.168.1.1","UNIFI_PROTECT_API_KEY":"your-api-key","UNIFI_PROTECT_VERIFY_SSL":"false"}}' -s user
 ```
 
 Use `-s user` for global availability across all projects, or `-s project` for the current project only.
@@ -42,15 +34,7 @@ npm run build
 Then add to Claude Code:
 
 ```bash
-claude mcp add-json unifi-protect '{
-  "command": "node",
-  "args": ["/path/to/unifi-protect-mcp/dist/index.js"],
-  "env": {
-    "UNIFI_PROTECT_HOST": "192.168.1.1",
-    "UNIFI_PROTECT_API_KEY": "your-api-key",
-    "UNIFI_PROTECT_VERIFY_SSL": "false"
-  }
-}' -s user
+claude mcp add-json unifi-protect '{"command":"node","args":["/path/to/unifi-protect-mcp/dist/index.js"],"env":{"UNIFI_PROTECT_HOST":"192.168.1.1","UNIFI_PROTECT_API_KEY":"your-api-key","UNIFI_PROTECT_VERIFY_SSL":"false"}}' -s user
 ```
 
 ### Environment Variables
@@ -60,6 +44,7 @@ claude mcp add-json unifi-protect '{
 | `UNIFI_PROTECT_HOST` | Yes | — | IP or hostname of your UniFi Protect console |
 | `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) |
 
 ### Manual Configuration
 
@@ -70,7 +55,7 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
   "mcpServers": {
     "unifi-protect": {
       "command": "npx",
-      "args": ["-y", "@owine/unifi-protect-mcp"],
+      "args": ["-y", "@owine/unifi-protect-mcp@latest"],
       "env": {
         "UNIFI_PROTECT_HOST": "192.168.1.1",
         "UNIFI_PROTECT_API_KEY": "your-api-key",
@@ -81,6 +66,15 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
 }
 ```
 
+## Safety Features
+
+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
+- **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
+
 ## Tools (33 total)
 
 ### System (2)
@@ -98,9 +92,9 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
 | `protect_get_snapshot` | Get a JPEG snapshot (returns image) |
 | `protect_create_rtsp_stream` | Create an RTSPS stream session |
 | `protect_get_rtsp_streams` | Get active RTSPS stream sessions |
-| `protect_delete_rtsp_stream` | Delete/stop an RTSPS stream |
+| `protect_delete_rtsp_stream` | Stop and delete an active RTSPS stream |
 | `protect_create_talkback` | Create a talkback (two-way audio) session |
-| `protect_disable_mic` | Permanently disable camera microphone |
+| `protect_disable_mic` | **IRREVERSIBLE:** Permanently disable camera microphone |
 | `protect_start_ptz_patrol` | Start PTZ patrol at a given slot |
 | `protect_stop_ptz_patrol` | Stop PTZ patrol |
 | `protect_goto_ptz_preset` | Move PTZ to a preset position |
@@ -144,7 +138,7 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
 ### Alarm & Files (3)
 | Tool | Description |
 |---|---|
-| `protect_trigger_alarm_webhook` | Trigger an alarm webhook by ID |
+| `protect_trigger_alarm_webhook` | Trigger an alarm webhook (fires external alarm action) |
 | `protect_list_files` | List files by type |
 | `protect_upload_file` | Upload a file (base64-encoded) |
 

package/dist/config.d.ts

@@ -3,6 +3,7 @@ declare const ConfigSchema: z.ZodObject<{
     host: z.ZodString;
     apiKey: z.ZodString;
     verifySsl: z.ZodBoolean;
+    readOnly: z.ZodBoolean;
 }, z.core.$strip>;
 export type Config = z.infer<typeof ConfigSchema>;
 export declare function loadConfig(): Config;

package/dist/config.js

@@ -6,12 +6,14 @@ 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"),
     verifySsl: zod_1.z.boolean(),
+    readOnly: zod_1.z.boolean(),
 });
 function loadConfig() {
     const result = ConfigSchema.safeParse({
         host: process.env.UNIFI_PROTECT_HOST,
         apiKey: process.env.UNIFI_PROTECT_API_KEY,
         verifySsl: process.env.UNIFI_PROTECT_VERIFY_SSL !== "false",
+        readOnly: process.env.UNIFI_PROTECT_READ_ONLY !== "false",
     });
     if (!result.success) {
         const errors = result.error.issues.map((i) => i.message).join(", ");

package/dist/index.js

@@ -13,7 +13,7 @@ async function main() {
         name: "unifi-protect",
         version: "1.0.0",
     });
-    (0, index_js_1.registerAllTools)(server, client);
+    (0, index_js_1.registerAllTools)(server, client, config.readOnly);
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
     console.error("UniFi Protect MCP server running on stdio");

package/dist/tools/cameras.d.ts

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

package/dist/tools/cameras.js

@@ -3,8 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCameraTools = registerCameraTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-function registerCameraTools(server, client) {
-    server.tool("protect_list_cameras", "List all cameras managed by UniFi Protect", {}, async () => {
+const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
+const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
+const DESTRUCTIVE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true };
+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,
+    }, async () => {
         try {
             const data = await client.get("/cameras");
             return (0, responses_js_1.formatSuccess)(data);
@@ -13,7 +20,11 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_get_camera", "Get details for a specific camera by ID", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    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,
+    }, async ({ id }) => {
         try {
             const data = await client.get(`/cameras/${id}`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -22,21 +33,11 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_update_camera", "Update camera settings (partial update via PATCH)", {
-        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 (JSON object)"),
-    }, async ({ id, settings }) => {
-        try {
-            const data = await client.patch(`/cameras/${id}`, settings);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
-    });
-    server.tool("protect_get_snapshot", "Get a JPEG snapshot from a camera (returns image)", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    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,
+    }, async ({ id }) => {
         try {
             const { data, mimeType } = await client.getBinary(`/cameras/${id}/snapshot`);
             return {
@@ -53,26 +54,84 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_create_rtsp_stream", "Create an RTSPS stream session for a camera", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    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,
+    }, async ({ id }) => {
         try {
-            const data = await client.post(`/cameras/${id}/rtsps-stream`);
+            const data = await client.get(`/cameras/${id}/rtsps-stream`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_get_rtsp_streams", "Get active RTSPS stream sessions for a camera", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    // --- Write tools (skipped in read-only mode) ---
+    if (readOnly)
+        return;
+    server.registerTool("protect_update_camera", {
+        description: "Update camera settings (partial update via PATCH)",
+        inputSchema: {
+            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)"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, settings, dryRun }) => {
         try {
-            const data = await client.get(`/cameras/${id}/rtsps-stream`);
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "PATCH", path: `/cameras/${id}`, body: settings });
+            }
+            const data = await client.patch(`/cameras/${id}`, settings);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.registerTool("protect_create_rtsp_stream", {
+        description: "Create an RTSPS stream session for a camera",
+        inputSchema: {
+            id: zod_1.z.string().describe("Camera ID"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, dryRun }) => {
+        try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/rtsps-stream` });
+            }
+            const data = await client.post(`/cameras/${id}/rtsps-stream`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_delete_rtsp_stream", "Delete/stop an RTSPS stream session for a camera", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    server.registerTool("protect_delete_rtsp_stream", {
+        description: "Stop and delete an active RTSPS stream session for a camera",
+        inputSchema: {
+            id: zod_1.z.string().describe("Camera ID"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
+    }, async ({ id, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "DELETE", path: `/cameras/${id}/rtsps-stream` });
+            }
             const data = await client.delete(`/cameras/${id}/rtsps-stream`);
             return (0, responses_js_1.formatSuccess)(data);
         }
@@ -80,8 +139,21 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_create_talkback", "Create a talkback (two-way audio) session for a camera", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    server.registerTool("protect_create_talkback", {
+        description: "Create a talkback (two-way audio) session for a camera",
+        inputSchema: {
+            id: zod_1.z.string().describe("Camera ID"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/talkback-session` });
+            }
             const data = await client.post(`/cameras/${id}/talkback-session`);
             return (0, responses_js_1.formatSuccess)(data);
         }
@@ -89,7 +161,16 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_disable_mic", "Permanently disable the microphone on a camera", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    server.registerTool("protect_disable_mic", {
+        description: "IRREVERSIBLE: Permanently disable the microphone on a camera. Can only be re-enabled by factory resetting the camera.",
+        inputSchema: {
+            id: zod_1.z.string().describe("Camera ID"),
+            confirm: zod_1.z
+                .literal(true)
+                .describe("Must be true to confirm this irreversible action"),
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
+    }, async ({ id }) => {
         try {
             const data = await client.post(`/cameras/${id}/disable-mic-permanently`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -98,11 +179,22 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_start_ptz_patrol", "Start PTZ patrol on a camera at a given slot", {
-        id: zod_1.z.string().describe("Camera ID"),
-        slot: zod_1.z.number().int().describe("Patrol slot number"),
-    }, async ({ id, slot }) => {
+    server.registerTool("protect_start_ptz_patrol", {
+        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"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, slot, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/ptz/patrol/start/${slot}` });
+            }
             const data = await client.post(`/cameras/${id}/ptz/patrol/start/${slot}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
@@ -110,8 +202,21 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_stop_ptz_patrol", "Stop PTZ patrol on a camera", { id: zod_1.z.string().describe("Camera ID") }, async ({ id }) => {
+    server.registerTool("protect_stop_ptz_patrol", {
+        description: "Stop PTZ patrol on a camera",
+        inputSchema: {
+            id: zod_1.z.string().describe("Camera ID"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/cameras/${id}/ptz/patrol/stop` });
+            }
             const data = await client.post(`/cameras/${id}/ptz/patrol/stop`);
             return (0, responses_js_1.formatSuccess)(data);
         }
@@ -119,11 +224,22 @@ function registerCameraTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_goto_ptz_preset", "Move camera PTZ to a preset position", {
-        id: zod_1.z.string().describe("Camera ID"),
-        slot: zod_1.z.number().int().describe("PTZ preset slot number"),
-    }, async ({ id, slot }) => {
+    server.registerTool("protect_goto_ptz_preset", {
+        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"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, slot, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: `/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.d.ts

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

package/dist/tools/devices.js

@@ -3,10 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDeviceTools = registerDeviceTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-function registerDeviceCrud(server, client, deviceType) {
+const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
+const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
+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)",
+    viewer: "Known fields: name (string), liveview (string, liveview ID to display)",
+};
+function registerDeviceCrud(server, client, deviceType, readOnly) {
     const plural = `${deviceType}s`;
     const label = deviceType.charAt(0).toUpperCase() + deviceType.slice(1);
-    server.tool(`protect_list_${plural}`, `List all ${plural} managed by UniFi Protect`, {}, async () => {
+    server.registerTool(`protect_list_${plural}`, {
+        description: `List all ${plural} managed by UniFi Protect`,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async () => {
         try {
             const data = await client.get(`/${plural}`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -15,7 +26,11 @@ function registerDeviceCrud(server, client, deviceType) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool(`protect_get_${deviceType}`, `Get details for a specific ${deviceType} by ID`, { id: zod_1.z.string().describe(`${label} ID`) }, async ({ id }) => {
+    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,
+    }, async ({ id }) => {
         try {
             const data = await client.get(`/${plural}/${id}`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -24,24 +39,37 @@ function registerDeviceCrud(server, client, deviceType) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool(`protect_update_${deviceType}`, `Update ${deviceType} settings (partial update via PATCH)`, {
-        id: zod_1.z.string().describe(`${label} ID`),
-        settings: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.unknown())
-            .describe(`Partial ${deviceType} settings to update (JSON object)`),
-    }, async ({ id, settings }) => {
-        try {
-            const data = await client.patch(`/${plural}/${id}`, settings);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
-    });
+    if (!readOnly) {
+        server.registerTool(`protect_update_${deviceType}`, {
+            description: `Update ${deviceType} settings (partial update via PATCH)`,
+            inputSchema: {
+                id: zod_1.z.string().describe(`${label} ID`),
+                settings: zod_1.z
+                    .record(zod_1.z.string(), zod_1.z.unknown())
+                    .describe(`Partial ${deviceType} settings to update. ${settingsHints[deviceType]}`),
+                dryRun: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe("If true, return what would happen without making changes"),
+            },
+            annotations: WRITE_ANNOTATIONS,
+        }, async ({ id, settings, dryRun }) => {
+            try {
+                if (dryRun) {
+                    return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "PATCH", path: `/${plural}/${id}`, body: settings });
+                }
+                const data = await client.patch(`/${plural}/${id}`, settings);
+                return (0, responses_js_1.formatSuccess)(data);
+            }
+            catch (err) {
+                return (0, responses_js_1.formatError)(err);
+            }
+        });
+    }
 }
-function registerDeviceTools(server, client) {
+function registerDeviceTools(server, client, readOnly) {
     const deviceTypes = ["light", "sensor", "chime", "viewer"];
     for (const dt of deviceTypes) {
-        registerDeviceCrud(server, client, dt);
+        registerDeviceCrud(server, client, dt, readOnly);
     }
 }

package/dist/tools/files.d.ts

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

package/dist/tools/files.js

@@ -3,38 +3,73 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerFileTools = registerFileTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-function registerFileTools(server, client) {
-    server.tool("protect_trigger_alarm_webhook", "Trigger an alarm manager webhook by ID", { id: zod_1.z.string().describe("Webhook ID") }, async ({ id }) => {
+const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
+const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
+const DESTRUCTIVE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true };
+function registerFileTools(server, client, readOnly) {
+    server.registerTool("protect_list_files", {
+        description: "List files of a given type (e.g. 'video', 'timelapse')",
+        inputSchema: {
+            fileType: zod_1.z
+                .string()
+                .describe("File type to list (e.g. 'video', 'timelapse')"),
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async ({ fileType }) => {
         try {
-            const data = await client.post(`/alarm-manager/webhook/${id}`);
+            const data = await client.get(`/files/${fileType}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_list_files", "List files of a given type (e.g. 'video', 'timelapse')", {
-        fileType: zod_1.z
-            .string()
-            .describe("File type to list (e.g. 'video', 'timelapse')"),
-    }, async ({ fileType }) => {
+    if (readOnly)
+        return;
+    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"),
+            confirm: zod_1.z
+                .literal(true)
+                .describe("Must be true to confirm triggering the alarm webhook"),
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
+    }, async ({ id }) => {
         try {
-            const data = await client.get(`/files/${fileType}`);
-            return (0, responses_js_1.formatSuccess)(data);
+            await client.post(`/alarm-manager/webhook/${id}`);
+            return (0, responses_js_1.formatSuccess)({ triggered: true, webhookId: id });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_upload_file", "Upload a base64-encoded file to UniFi Protect", {
-        fileType: zod_1.z.string().describe("File type category for upload"),
-        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"),
-    }, async ({ fileType, base64Data, contentType }) => {
+    server.registerTool("protect_upload_file", {
+        description: "Upload a base64-encoded file to UniFi Protect",
+        inputSchema: {
+            fileType: zod_1.z.string().describe("File type category for upload"),
+            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"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ fileType, base64Data, contentType, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({
+                    dryRun: true,
+                    action: "POST",
+                    path: `/files/${fileType}`,
+                    contentType,
+                    dataLength: base64Data.length,
+                });
+            }
             const buffer = Buffer.from(base64Data, "base64");
             const data = await client.postBinary(`/files/${fileType}`, buffer, contentType);
             return (0, responses_js_1.formatSuccess)(data);

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

@@ -6,10 +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");
-function registerAllTools(server, client) {
+function registerAllTools(server, client, readOnly) {
     (0, system_js_1.registerSystemTools)(server, client);
-    (0, cameras_js_1.registerCameraTools)(server, client);
-    (0, devices_js_1.registerDeviceTools)(server, client);
-    (0, liveviews_js_1.registerLiveviewTools)(server, client);
-    (0, files_js_1.registerFileTools)(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);
+    (0, files_js_1.registerFileTools)(server, client, readOnly);
 }

package/dist/tools/liveviews.d.ts

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

package/dist/tools/liveviews.js

@@ -3,8 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerLiveviewTools = registerLiveviewTools;
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
-function registerLiveviewTools(server, client) {
-    server.tool("protect_list_liveviews", "List all live views configured in UniFi Protect", {}, async () => {
+const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false };
+const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false };
+function registerLiveviewTools(server, client, readOnly) {
+    server.registerTool("protect_list_liveviews", {
+        description: "List all live views configured in UniFi Protect",
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async () => {
         try {
             const data = await client.get("/liveviews");
             return (0, responses_js_1.formatSuccess)(data);
@@ -13,7 +18,11 @@ function registerLiveviewTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_get_liveview", "Get details for a specific live view by ID", { id: zod_1.z.string().describe("Liveview ID") }, async ({ id }) => {
+    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,
+    }, async ({ id }) => {
         try {
             const data = await client.get(`/liveviews/${id}`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -22,12 +31,25 @@ function registerLiveviewTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_create_liveview", "Create a new live view", {
-        settings: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.unknown())
-            .describe("Liveview configuration (JSON object with name, slots, etc.)"),
-    }, async ({ settings }) => {
+    if (readOnly)
+        return;
+    server.registerTool("protect_create_liveview", {
+        description: "Create a new live view",
+        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)"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ settings, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "POST", path: "/liveviews", body: settings });
+            }
             const data = await client.post("/liveviews", settings);
             return (0, responses_js_1.formatSuccess)(data);
         }
@@ -35,13 +57,24 @@ function registerLiveviewTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_update_liveview", "Update an existing live view (partial update via PATCH)", {
-        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 (JSON object)"),
-    }, async ({ id, settings }) => {
+    server.registerTool("protect_update_liveview", {
+        description: "Update an existing live view (partial update via PATCH)",
+        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)"),
+            dryRun: zod_1.z
+                .boolean()
+                .optional()
+                .describe("If true, return what would happen without making changes"),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, settings, dryRun }) => {
         try {
+            if (dryRun) {
+                return (0, responses_js_1.formatSuccess)({ dryRun: true, action: "PATCH", path: `/liveviews/${id}`, body: settings });
+            }
             const data = await client.patch(`/liveviews/${id}`, settings);
             return (0, responses_js_1.formatSuccess)(data);
         }

package/dist/tools/system.js

@@ -2,8 +2,12 @@
 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 };
 function registerSystemTools(server, client) {
-    server.tool("protect_get_info", "Get UniFi Protect system information and version details", {}, async () => {
+    server.registerTool("protect_get_info", {
+        description: "Get UniFi Protect system information and version details",
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async () => {
         try {
             const data = await client.get("/meta/info");
             return (0, responses_js_1.formatSuccess)(data);
@@ -12,7 +16,10 @@ function registerSystemTools(server, client) {
             return (0, responses_js_1.formatError)(err);
         }
     });
-    server.tool("protect_list_nvrs", "List all NVR (Network Video Recorder) devices", {}, async () => {
+    server.registerTool("protect_list_nvrs", {
+        description: "List all NVR (Network Video Recorder) devices",
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async () => {
         try {
             const data = await client.get("/nvrs");
             return (0, responses_js_1.formatSuccess)(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-protect-mcp",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "MCP server for UniFi Protect Integration API",
   "main": "dist/index.js",
   "bin": {
@@ -42,6 +42,7 @@
   "devDependencies": {
     "@eslint/js": "9.39.2",
     "@types/node": "24.10.13",
+    "@vitest/coverage-v8": "4.0.18",
     "eslint": "9.39.2",
     "typescript": "5.9.3",
     "typescript-eslint": "8.55.0",