@owine/unifi-protect-mcp 2.14.2 → 3.0.0

package/dist/tools/device-actions.js

@@ -5,155 +5,142 @@ 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 params_js_1 = require("../utils/params.js");
+// Each gate's confirm input and handler check share one action text.
+const STOP_SIREN = (0, safety_js_1.confirmGate)("silence the siren");
+const SWITCH_RELAY = (0, safety_js_1.confirmGate)("switch the relay output");
+const TRIGGER_HUB_OUTPUT = (0, safety_js_1.confirmGate)("trigger the alarm hub output");
 function registerDeviceActionTools(server, client, readOnly) {
     if (readOnly)
         return;
     // --- Sirens ---
     server.registerTool("protect_play_siren", {
-        description: "Activate the siren alarm for a duration. Tracks status and can be stopped early.",
+        description: "Activate the siren alarm for a duration. Stop it early with protect_stop_siren, which requires confirm: true.",
         inputSchema: {
-            id: zod_1.z.string().describe("Siren ID"),
+            id: (0, params_js_1.resourceId)().describe("Siren ID"),
             duration: zod_1.z
                 .union([zod_1.z.literal(5), zod_1.z.literal(10), zod_1.z.literal(20), zod_1.z.literal(30)])
                 .optional()
                 .describe("Duration of siren activation in seconds (5, 10, 20, or 30). Defaults to 5."),
-            dryRun: zod_1.z.boolean().optional().describe("If true, return what would happen without making changes"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
         annotations: safety_js_1.WRITE,
     }, async ({ id, duration, dryRun }) => {
-        try {
-            const body = duration !== undefined ? { duration } : undefined;
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/sirens/${id}/play`, body);
-            }
-            const data = await client.post((0, url_js_1.safePath) `/sirens/${id}/play`, body);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        const body = duration !== undefined ? { duration } : undefined;
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/sirens/${id}/play`, body);
         }
+        const data = await client.post((0, url_js_1.safePath) `/sirens/${id}/play`, body);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     server.registerTool("protect_stop_siren", {
-        description: "Stop an active siren",
+        description: "Stop an active siren. Requires confirm: true: it silences an alarm siren.",
         inputSchema: {
-            id: zod_1.z.string().describe("Siren ID"),
-            dryRun: zod_1.z.boolean().optional().describe("If true, return what would happen without making changes"),
+            id: (0, params_js_1.resourceId)().describe("Siren ID"),
+            confirm: STOP_SIREN.input,
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
-        annotations: safety_js_1.WRITE,
-    }, async ({ id, dryRun }) => {
-        try {
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/sirens/${id}/stop`);
-            }
-            const data = await client.post((0, url_js_1.safePath) `/sirens/${id}/stop`);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        annotations: safety_js_1.DESTRUCTIVE,
+    }, async ({ id, confirm, dryRun }) => {
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/sirens/${id}/stop`);
         }
+        const denied = STOP_SIREN.check(confirm);
+        if (denied)
+            return denied;
+        const data = await client.post((0, url_js_1.safePath) `/sirens/${id}/stop`);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     server.registerTool("protect_test_siren_sound", {
         description: "Test the siren sound for 5 seconds at the specified volume",
         inputSchema: {
-            id: zod_1.z.string().describe("Siren ID"),
+            id: (0, params_js_1.resourceId)().describe("Siren ID"),
             volume: zod_1.z.number().int().min(1).max(100).optional().describe("Test volume 1-100. Defaults to configured device volume."),
-            dryRun: zod_1.z.boolean().optional().describe("If true, return what would happen without making changes"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
         annotations: safety_js_1.WRITE,
     }, async ({ id, volume, dryRun }) => {
-        try {
-            const body = volume !== undefined ? { volume } : undefined;
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/sirens/${id}/test-sound`, body);
-            }
-            const data = await client.post((0, url_js_1.safePath) `/sirens/${id}/test-sound`, body);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        const body = volume !== undefined ? { volume } : undefined;
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/sirens/${id}/test-sound`, body);
         }
+        const data = await client.post((0, url_js_1.safePath) `/sirens/${id}/test-sound`, body);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     // --- Speakers ---
     server.registerTool("protect_test_speaker_sound", {
         description: "Test the speaker sound at the specified volume",
         inputSchema: {
-            id: zod_1.z.string().describe("Speaker ID"),
+            id: (0, params_js_1.resourceId)().describe("Speaker ID"),
             volume: zod_1.z.number().int().min(0).max(100).optional().describe("Test volume 0-100. Defaults to configured device volume."),
-            dryRun: zod_1.z.boolean().optional().describe("If true, return what would happen without making changes"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
         annotations: safety_js_1.WRITE,
     }, async ({ id, volume, dryRun }) => {
-        try {
-            const body = volume !== undefined ? { volume } : undefined;
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/speakers/${id}/test-sound`, body);
-            }
-            const data = await client.post((0, url_js_1.safePath) `/speakers/${id}/test-sound`, body);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        const body = volume !== undefined ? { volume } : undefined;
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/speakers/${id}/test-sound`, body);
         }
+        const data = await client.post((0, url_js_1.safePath) `/speakers/${id}/test-sound`, body);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     // --- Relays ---
     server.registerTool("protect_activate_relay_output", {
-        description: "Control a relay output. Set state to \"on\"/\"off\" to set explicitly, or omit to toggle. When state is \"on\", pulseDuration auto-turns off after the given milliseconds.",
+        description: "Control a relay output. Relays commonly drive gates, door strikes and garage doors, so this requires confirm: true. state (\"on\"/\"off\") is required: the API's toggle mode is not exposed because a retried toggle would flip the output back. Read the current output state with protect_get_relay. When state is \"on\", pulseDuration auto-turns off after the given milliseconds.",
         inputSchema: {
-            id: zod_1.z.string().describe("Relay ID"),
-            outputId: zod_1.z.number().int().min(0).describe("Output channel ID (0 or 1)"),
-            state: zod_1.z.enum(["on", "off"]).optional().describe("Desired output state. If omitted, toggles current state."),
+            id: (0, params_js_1.resourceId)().describe("Relay ID"),
+            outputId: zod_1.z.number().int().min(0).describe("Output channel ID: an outputs[].id from protect_get_relay"),
+            state: zod_1.z.enum(["on", "off"]).describe("Desired output state"),
             pulseDuration: zod_1.z.number().int().min(0).optional().describe("Auto-off duration in milliseconds (only when state is \"on\"). 0 means stay on."),
-            dryRun: zod_1.z.boolean().optional().describe("If true, return what would happen without making changes"),
+            confirm: SWITCH_RELAY.input,
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
-        annotations: safety_js_1.WRITE,
-    }, async ({ id, outputId, state, pulseDuration, dryRun }) => {
-        try {
-            const body = {};
-            if (state !== undefined)
-                body.state = state;
-            if (pulseDuration !== undefined)
-                body.pulseDuration = pulseDuration;
-            const path = (0, url_js_1.safePath) `/relays/${id}/outputs/${outputId}/activate`;
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", path, Object.keys(body).length > 0 ? body : undefined);
-            }
-            const data = await client.post(path, Object.keys(body).length > 0 ? body : undefined);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        // Not idempotent: an explicit state is safe to repeat, but a timed one
+        // is not, since a repeated call starts the timer, and the output, again.
+        annotations: safety_js_1.DESTRUCTIVE,
+    }, async ({ id, outputId, state, pulseDuration, confirm, dryRun }) => {
+        const body = { state };
+        if (pulseDuration !== undefined)
+            body.pulseDuration = pulseDuration;
+        const path = (0, url_js_1.safePath) `/relays/${id}/outputs/${outputId}/activate`;
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", path, body);
         }
+        const denied = SWITCH_RELAY.check(confirm);
+        if (denied)
+            return denied;
+        const data = await client.post(path, body);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     // --- Alarm hubs ---
     server.registerTool("protect_trigger_alarm_hub_output", {
-        description: "Trigger an alarm hub output channel. Used to turn on/off connected sirens, lights, or other actuators.",
+        description: "Trigger an alarm hub output channel. Used to turn on/off connected sirens, lights, locks, or other actuators, so this requires confirm: true. enable is required: the API's toggle mode is not exposed because a retried toggle would flip the output back.",
         inputSchema: {
-            id: zod_1.z.string().describe("Alarm hub (link station) ID"),
-            outputId: zod_1.z.number().int().min(0).describe("Output channel ID (0 or 1)"),
-            enable: zod_1.z.boolean().optional().describe("True to turn on, false to turn off. If omitted, toggles current state."),
+            id: (0, params_js_1.resourceId)().describe("Alarm hub (link station) ID"),
+            outputId: zod_1.z.number().int().min(0).describe("Output channel ID: a key of alarmHub.output from protect_get_alarm_hub"),
+            enable: zod_1.z.boolean().describe("True to turn on, false to turn off"),
             delay: zod_1.z.number().int().min(0).optional().describe("Delay in milliseconds before output activates"),
             duration: zod_1.z.number().int().min(0).optional().describe("Duration in milliseconds to keep output active. 0 = indefinite."),
-            dryRun: zod_1.z.boolean().optional().describe("If true, return what would happen without making changes"),
+            confirm: TRIGGER_HUB_OUTPUT.input,
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
-        annotations: safety_js_1.WRITE,
-    }, async ({ id, outputId, enable, delay, duration, dryRun }) => {
-        try {
-            const body = {};
-            if (enable !== undefined)
-                body.enable = enable;
-            if (delay !== undefined)
-                body.delay = delay;
-            if (duration !== undefined)
-                body.duration = duration;
-            const path = (0, url_js_1.safePath) `/alarm-hubs/${id}/outputs/${outputId}/trigger`;
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", path, Object.keys(body).length > 0 ? body : undefined);
-            }
-            const data = await client.post(path, Object.keys(body).length > 0 ? body : undefined);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        // Not idempotent: an explicit state is safe to repeat, but a timed one
+        // is not, since a repeated call starts the timer, and the output, again.
+        annotations: safety_js_1.DESTRUCTIVE,
+    }, async ({ id, outputId, enable, delay, duration, confirm, dryRun }) => {
+        const body = { enable };
+        if (delay !== undefined)
+            body.delay = delay;
+        if (duration !== undefined)
+            body.duration = duration;
+        const path = (0, url_js_1.safePath) `/alarm-hubs/${id}/outputs/${outputId}/trigger`;
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", path, body);
         }
+        const denied = TRIGGER_HUB_OUTPUT.check(confirm);
+        if (denied)
+            return denied;
+        const data = await client.post(path, body);
+        return (0, responses_js_1.formatSuccess)(data);
     });
 }

package/dist/tools/devices.d.ts

@@ -1,14 +1,17 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolRegistrar } from "./registrar.js";
 import { ProtectClient } from "../client.js";
+import { DEVICE_SCHEMAS } from "../schemas/devices.js";
 interface DeviceConfig {
     urlPath: string;
-    singular: string;
+    singular: keyof typeof DEVICE_SCHEMAS;
     plural: string;
     label: string;
     hint: string;
     returns: string;
+    note?: string;
+    confirmFields?: readonly string[];
 }
-export declare function registerDeviceTools(server: McpServer, client: ProtectClient, readOnly: boolean): void;
+export declare function registerDeviceTools(server: ToolRegistrar, client: ProtectClient, readOnly: boolean): void;
 /** Exported for tests */
 export declare const _DEVICE_CONFIGS: DeviceConfig[];
 export {};

package/dist/tools/devices.js

@@ -6,11 +6,14 @@ 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 paging_js_1 = require("../utils/paging.js");
+const params_js_1 = require("../utils/params.js");
 const devices_js_1 = require("../schemas/devices.js");
-// Field lists below are from the UniFi Protect Integration API 7.3.47 docs.
+// Field lists below are from the UniFi Protect Integration API 7.3.70 docs.
 // 7.3.x added `type` (hardware model name) and `guid` to every device. NOTE:
 // `guid` identifies the hardware MODEL, not the unit — every camera of the same
-// model returns the same guid (verified live 7.3.47). `id` is the device identity.
+// model returns the same guid (verified live 7.3.47 and 7.3.70). `id` is the
+// device identity.
 // Chimes are additionally verified against live console responses; the rest
 // have no instances on the available console (top-level fields documented,
 // nested shapes intentionally left opaque in the output schema).
@@ -21,23 +24,24 @@ const DEVICES = [
         plural: "lights",
         label: "Light",
         hint: "Known fields: name (string), isLightForceEnabled (boolean), lightModeSettings (object with mode, enableAt), lightDeviceSettings (object with isIndicatorEnabled, pirDuration, pirSensitivity, ledLevel)",
-        returns: "id, modelKey, name, mac, state, type, guid, lightModeSettings (mode, enableAt), lightDeviceSettings (isIndicatorEnabled, pirDuration, pirSensitivity, ledLevel), isDark, isLightOn, isLightForceEnabled, lastMotion, isPirMotionDetected, camera (7.3.47 docs)",
+        returns: "id, modelKey, name, mac, state, type, guid, lightModeSettings (mode, enableAt), lightDeviceSettings (isIndicatorEnabled, pirDuration, pirSensitivity, ledLevel), isDark, isLightOn, isLightForceEnabled, lastMotion, isPirMotionDetected, camera (7.3.70 docs)",
     },
     {
         urlPath: "sensors",
         singular: "sensor",
+        confirmFields: ["alarmSettings", "motionSettings", "glassBreakSettings", "armProfileIds", "scheduleMode"],
         plural: "sensors",
         label: "Sensor",
-        hint: "Known fields: name (string), motionSettings (object), humiditySettings (object), temperatureSettings (object), lightSettings (object), alarmSettings (object), glassBreakSettings (object), leakSettings (object), scheduleMode (\"always\" | \"when_armed\"), armProfileIds (array of up to 32 strings), hasCustomSensitivityWhenArmed (boolean)",
-        returns: "id, modelKey, name, mac, state, type, guid, mountType, featureFlags (temperature, humidity, light, motion, waterLeak, open, tamper, smoke — each {channelCount}), batteryStatus (percentage, isLow), stats (light, humidity, temperature), lightSettings, humiditySettings, temperatureSettings, isOpened, openStatusChangedAt, isMotionDetected, motionDetectedAt, motionSettings, glassBreakSettings, scheduleMode, armProfileIds, hasCustomSensitivityWhenArmed, alarmTriggeredAt, alarmSettings, leakDetectedAt, externalLeakDetectedAt, leakSettings, tamperingDetectedAt, wirelessConnectionState (7.3.47 docs)",
+        hint: "Known fields: name (string), lightSettings / humiditySettings / temperatureSettings (objects: isEnabled, margin, lowThreshold, highThreshold), motionSettings / glassBreakSettings (objects: isEnabled, sensitivity, sensitivityWhenArmed), alarmSettings (object: isEnabled), scheduleMode (\"always\" | \"when_armed\"), armProfileIds (array of up to 32 strings, or null), hasCustomSensitivityWhenArmed (boolean). leakSettings is read-only. Returns HTTP 409 if a setting is not supported by this sensor",
+        returns: "id, modelKey, name, mac, state, type, guid, mountType, featureFlags (temperature, humidity, light, motion, waterLeak, open, tamper, smoke — each {channelCount}), batteryStatus (percentage, isLow), stats (light, humidity, temperature — each {value, status}), lightSettings / humiditySettings / temperatureSettings (isEnabled, margin, lowThreshold, highThreshold), isOpened, openStatusChangedAt, isMotionDetected, motionDetectedAt, motionSettings / glassBreakSettings (isEnabled, sensitivity, sensitivityWhenArmed), scheduleMode, armProfileIds, hasCustomSensitivityWhenArmed, alarmTriggeredAt, alarmSettings, leakDetectedAt, externalLeakDetectedAt, leakSettings (isInternalEnabled, isExternalEnabled), tamperingDetectedAt, wirelessConnectionState (signalState: signalQuality, signalStrength; batteryStatus: percentage, isLow; bridge) (7.3.70 docs)",
     },
     {
         urlPath: "chimes",
         singular: "chime",
         plural: "chimes",
         label: "Chime",
-        hint: "Known fields: name (string), cameraIds (array of camera IDs linked to the chime), ringSettings (array of objects: cameraId, volume, ringtoneId, repeatTimes)",
-        returns: "id, modelKey, name, mac, state, type, guid, cameraIds (array of camera IDs), ringSettings (array of objects: cameraId, volume, ringtoneId, repeatTimes) — verified live 7.3.47",
+        hint: "Known fields: name (string), cameraIds (array of doorbell camera IDs linked to the chime), ringSettings (array of objects: cameraId, volume, ringtoneId, repeatTimes)",
+        returns: "id, modelKey, name, mac, state, type, guid, cameraIds (array of camera IDs), ringSettings (array of objects: cameraId, volume, ringtoneId, repeatTimes) — verified live 7.3.70",
     },
     {
         urlPath: "viewers",
@@ -45,23 +49,26 @@ const DEVICES = [
         plural: "viewers",
         label: "Viewer",
         hint: "Known fields: name (string), liveview (string, liveview ID to display, or null)",
-        returns: "id, modelKey, name, mac, state, type, guid, liveview, streamLimit (7.3.47 docs)",
+        returns: "id, modelKey, name, mac, state, type, guid, liveview, streamLimit (7.3.70 docs)",
     },
     {
         urlPath: "sirens",
         singular: "siren",
+        // A lower volume weakens the alarm as surely as stopping the siren does.
+        confirmFields: ["volume"],
         plural: "sirens",
         label: "Siren",
         hint: "Known fields: name (string), volume (integer 1-100), ledSettings (object with isEnabled boolean)",
-        returns: "id, modelKey, name, mac, state, type, guid, volume, ledSettings (isEnabled), sirenStatus (isActive, activatedAt, duration), connectionType, wirelessConnectionState (7.3.47 docs)",
+        returns: "id, modelKey, name, mac, state, type, guid, volume, ledSettings (isEnabled), sirenStatus (isActive, activatedAt, duration), connectionType, wirelessConnectionState (signalState: signalQuality, signalStrength; batteryStatus: percentage, isLow; bridge) (7.3.70 docs)",
     },
     {
         urlPath: "fobs",
         singular: "fob",
+        confirmFields: ["armControlSettings"],
         plural: "fobs",
         label: "Fob",
-        hint: "Known fields: name (string)",
-        returns: "id, modelKey, name, mac, state, type, guid, awayState, buttonLabels, featureFlags (buttons[]), hasKeypad, armControlSettings (enabled, armProfileId, nightProfileId), keypadSettings (beepEnabled, beepVolume, backlightEnabled, backlightBrightness), wirelessConnectionState (7.3.47 docs)",
+        hint: "Known fields: name (string). armControlSettings is not documented as patchable; sending it requires confirm: true",
+        returns: "id, modelKey, name, mac, state, type, guid, awayState, buttonLabels, featureFlags (buttons[], hasKeypad), armControlSettings (enabled, armProfileId, nightProfileId), keypadSettings (beepEnabled, beepVolume), wirelessConnectionState (signalState: signalQuality, signalStrength; batteryStatus: percentage, isLow; bridge) (7.3.70 docs)",
     },
     {
         urlPath: "relays",
@@ -69,7 +76,7 @@ const DEVICES = [
         plural: "relays",
         label: "Relay",
         hint: "Known fields: name (string), ledSettings (object with isEnabled boolean)",
-        returns: "id, modelKey, name, mac, state, type, guid, ledSettings (isEnabled), outputs (array), inputs (array), wirelessConnectionState (7.3.47 docs)",
+        returns: "id, modelKey, name, mac, state, type, guid, ledSettings (isEnabled), outputs (array of objects: id, name, type, delay, pulseDuration, state, rebootState — id is the outputId for protect_activate_relay_output), inputs (array of objects: id, name, state, actionTrigger, actionType, actionOutputId), wirelessConnectionState (signalState: signalQuality, signalStrength; batteryStatus: percentage, isLow; bridge) (7.3.70 docs)",
     },
     {
         urlPath: "speakers",
@@ -77,7 +84,7 @@ const DEVICES = [
         plural: "speakers",
         label: "Speaker",
         hint: "Known fields: name (string), volume (integer 0-100), micVolume (integer 0-100), isMicEnabled (boolean)",
-        returns: "id, modelKey, name, mac, state, type, guid, volume, micVolume, isMicEnabled, speakerState (status, mode), featureFlags (hasMic) (7.3.47 docs)",
+        returns: "id, modelKey, name, mac, state, type, guid, volume, micVolume, isMicEnabled, speakerState (status, mode), featureFlags (hasMic) (7.3.70 docs)",
     },
     {
         urlPath: "bridges",
@@ -85,15 +92,16 @@ const DEVICES = [
         plural: "bridges",
         label: "Bridge",
         hint: "Known fields: name (string)",
-        returns: "id, modelKey, name, mac, state, type, guid, platform, clients (array of MACs), maxClients (7.3.47 docs)",
+        returns: "id, modelKey, name, mac, state, type, guid, platform, clients (array of MACs), maxClients (7.3.70 docs)",
     },
     {
         urlPath: "link-stations",
         singular: "link_station",
         plural: "link_stations",
         label: "Link station",
+        note: "Link stations are non-alarm-hub gateways (use protect_list_alarm_hubs for alarm hubs).",
         hint: "Known fields: name (string)",
-        returns: "id, modelKey (\"linkstation\"), name, mac, state, type, guid, isAlarmHub, ledSettings (isEnabled), lastEvent, alarmHub (object), deviceTamperStatus, threadState (network: status, role, networkName, channel, panId, extendedPanId, joinedDeviceCount, errorReason, lastUpdatedAt) (7.3.47 docs)",
+        returns: "id, modelKey (\"linkstation\"), name, mac, state, type, guid, isAlarmHub, ledSettings (isEnabled), lastEvent, alarmHub (armed, battery, buckboost, connector, cover, deviceTamperStatus (e.g. \"tampered\"), currentMeterChannelStatus, currentMeterStatus, inputPower, poeout, powerMeter, output and input (maps keyed by channel), inputTerminalStatus, outputTerminalStatus, emergencyTerminalStatus, auxiliaryPowerTerminalStatus), threadState (network: status, role, networkName, channel, panId, extendedPanId, joinedDeviceCount, errorReason, lastUpdatedAt) (7.3.70 docs)",
     },
     {
         urlPath: "alarm-hubs",
@@ -101,64 +109,55 @@ const DEVICES = [
         plural: "alarm_hubs",
         label: "Alarm hub",
         hint: "Known fields: name (string)",
-        returns: "id, modelKey (\"linkstation\"), name, mac, state, type, guid, isAlarmHub, ledSettings (isEnabled), lastEvent, alarmHub (object), deviceTamperStatus, threadState (network: status, role, networkName, channel, panId, extendedPanId, joinedDeviceCount, errorReason, lastUpdatedAt) (7.3.47 docs)",
+        returns: "id, modelKey (\"linkstation\"), name, mac, state, type, guid, isAlarmHub, ledSettings (isEnabled), lastEvent, alarmHub (armed, battery, buckboost, connector, cover, deviceTamperStatus (e.g. \"tampered\"), currentMeterChannelStatus, currentMeterStatus, inputPower, poeout, powerMeter, output and input (maps keyed by channel), inputTerminalStatus, outputTerminalStatus, emergencyTerminalStatus, auxiliaryPowerTerminalStatus), threadState (network: status, role, networkName, channel, panId, extendedPanId, joinedDeviceCount, errorReason, lastUpdatedAt) (7.3.70 docs)",
     },
 ];
 function registerDeviceCrud(server, client, cfg, readOnly) {
     const schemaKey = cfg.singular;
+    const note = cfg.note ? `${cfg.note} ` : "";
     server.registerTool(`protect_list_${cfg.plural}`, {
-        description: `List all ${cfg.label.toLowerCase()}s managed by UniFi Protect. Returns array; each ${cfg.label.toLowerCase()} includes: ${cfg.returns}.`,
+        description: `List all ${cfg.label.toLowerCase()}s managed by UniFi Protect. ${note}Returns array; each ${cfg.label.toLowerCase()} includes: ${cfg.returns}.${paging_js_1.PAGING_NOTE}`,
+        inputSchema: paging_js_1.pagingInput,
         outputSchema: (0, devices_js_1.listOutputShape)(schemaKey),
         annotations: safety_js_1.READ_ONLY,
-    }, async () => {
-        try {
-            const data = await client.get(`/${cfg.urlPath}`);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+    }, async ({ limit, offset }) => {
+        const data = await client.get(`/${cfg.urlPath}`);
+        return (0, responses_js_1.formatSuccess)((0, paging_js_1.pageOf)(data, limit, offset));
     });
     server.registerTool(`protect_get_${cfg.singular}`, {
-        description: `Get full details for a specific ${cfg.label.toLowerCase()} by ID. Returns: ${cfg.returns}.`,
-        inputSchema: { id: zod_1.z.string().describe(`${cfg.label} ID`) },
+        description: `Get full details for a specific ${cfg.label.toLowerCase()} by ID. ${note}Returns: ${cfg.returns}.`,
+        inputSchema: { id: (0, params_js_1.resourceId)().describe(`${cfg.label} ID`) },
         outputSchema: (0, devices_js_1.itemOutputShape)(schemaKey),
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
-        try {
-            const data = await client.get((0, url_js_1.safePath) `/${cfg.urlPath}/${id}`);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+        const data = await client.get((0, url_js_1.safePath) `/${cfg.urlPath}/${id}`);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     if (!readOnly) {
         server.registerTool(`protect_update_${cfg.singular}`, {
-            description: `Update ${cfg.label.toLowerCase()} settings (partial update via PATCH)`,
+            description: `Update ${cfg.label.toLowerCase()} settings (partial update via PATCH).${cfg.confirmFields ? ` Changing ${cfg.confirmFields.join(", ")} affects alarm coverage and requires confirm: true.` : ""}`,
             inputSchema: {
-                id: zod_1.z.string().describe(`${cfg.label} ID`),
+                id: (0, params_js_1.resourceId)().describe(`${cfg.label} ID`),
                 settings: zod_1.z
                     .record(zod_1.z.string(), zod_1.z.unknown())
+                    .refine((o) => Object.keys(o).length > 0, "settings must include at least one field")
                     .describe(`Partial ${cfg.label.toLowerCase()} settings to update. ${cfg.hint}`),
-                dryRun: zod_1.z
-                    .boolean()
-                    .optional()
-                    .describe("If true, return what would happen without making changes"),
+                ...(cfg.confirmFields
+                    ? { confirm: (0, safety_js_1.confirmInput)(`change ${cfg.confirmFields.join(", ")}`) }
+                    : {}),
+                dryRun: (0, safety_js_1.dryRunInput)(),
             },
             outputSchema: (0, devices_js_1.itemOutputShape)(schemaKey),
-            annotations: safety_js_1.WRITE,
-        }, async ({ id, settings, dryRun }) => {
-            try {
-                if (dryRun) {
-                    return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/${cfg.urlPath}/${id}`, settings);
-                }
-                const data = await client.patch((0, url_js_1.safePath) `/${cfg.urlPath}/${id}`, settings);
-                return (0, responses_js_1.formatSuccess)(data);
-            }
-            catch (err) {
-                return (0, responses_js_1.formatError)(err);
+            annotations: safety_js_1.DESTRUCTIVE,
+        }, async ({ id, settings, dryRun, confirm }) => {
+            if (dryRun) {
+                return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/${cfg.urlPath}/${id}`, settings);
             }
+            const denied = (0, safety_js_1.requireConfirmationForFields)(settings, cfg.confirmFields ?? [], confirm);
+            if (denied)
+                return denied;
+            const data = await client.patch((0, url_js_1.safePath) `/${cfg.urlPath}/${id}`, settings);
+            return (0, responses_js_1.formatSuccess)(data);
         });
     }
 }

package/dist/tools/files.d.ts

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