@owine/unifi-protect-mcp 1.1.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@latest"],
-  "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,7 +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 | `false` | Set to `true` to disable all write/mutating tools (monitoring-only mode) |
+| `UNIFI_PROTECT_READ_ONLY` | No | `true` | Set to `false` to enable write/mutating tools (default is monitoring-only mode) |
 
 ### Manual Configuration
 
@@ -87,7 +71,7 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
 This server provides layered safety controls for responsible operation:
 
 - **Tool annotations** — Every tool declares `readOnlyHint` and `destructiveHint` so MCP clients (like Claude Code) can make informed confirmation decisions
-- **Read-only mode** — Set `UNIFI_PROTECT_READ_ONLY=true` to completely hide all write/mutating tools. Only read operations (list, get, snapshot) are registered. Ideal for monitoring-only deployments
+- **Read-only mode** — Enabled by default. Only read operations (list, get, snapshot) are registered. Set `UNIFI_PROTECT_READ_ONLY=false` to enable write/mutating tools
 - **Confirmation parameter** — The most dangerous tools (`protect_disable_mic`, `protect_trigger_alarm_webhook`) require an explicit `confirm: true` parameter that must be present for the call to succeed
 - **Dry-run support** — All write tools (except those with `confirm`) accept an optional `dryRun: true` parameter that returns a preview of what would happen without making any changes
 

package/dist/config.js

@@ -13,7 +13,7 @@ function loadConfig() {
         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 === "true",
+        readOnly: process.env.UNIFI_PROTECT_READ_ONLY !== "false",
     });
     if (!result.success) {
         const errors = result.error.issues.map((i) => i.message).join(", ");

package/dist/tools/cameras.js

@@ -76,7 +76,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 (JSON object)"),
+                .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()
@@ -162,7 +162,7 @@ function registerCameraTools(server, client, readOnly) {
         }
     });
     server.registerTool("protect_disable_mic", {
-        description: "IRREVERSIBLE: Permanently disable the microphone on a camera. Cannot be re-enabled.",
+        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

package/dist/tools/devices.js

@@ -5,6 +5,12 @@ 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 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);
@@ -40,7 +46,7 @@ function registerDeviceCrud(server, client, deviceType, readOnly) {
                 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)`),
+                    .describe(`Partial ${deviceType} settings to update. ${settingsHints[deviceType]}`),
                 dryRun: zod_1.z
                     .boolean()
                     .optional()

package/dist/tools/files.js

@@ -37,8 +37,8 @@ function registerFileTools(server, client, readOnly) {
         annotations: DESTRUCTIVE_ANNOTATIONS,
     }, async ({ id }) => {
         try {
-            const data = await client.post(`/alarm-manager/webhook/${id}`);
-            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);

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 (JSON object with name, slots, etc.)"),
+                .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()
@@ -63,7 +63,7 @@ function registerLiveviewTools(server, client, readOnly) {
             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)"),
+                .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()

package/package.json

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