@owine/unifi-protect-mcp 2.14.2 → 3.0.0

package/dist/tools/files.js

@@ -5,78 +5,103 @@ 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 limits_js_1 = require("../utils/limits.js");
 const misc_js_1 = require("../schemas/misc.js");
+// The only asset file type the API accepts (path param `assetFileType`).
+const FILE_TYPE = zod_1.z
+    .literal("animations")
+    .describe("Asset file type (only 'animations' is supported)");
+const UPLOAD_CONTENT_TYPES = [
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/wave",
+    "audio/x-caf",
+];
 function registerFileTools(server, client, readOnly) {
     server.registerTool("protect_list_files", {
-        description: "List files of a given type (only 'animations' is currently supported — clips uploadable to G4 Doorbell screens). Returns array; each record (7.1.83 docs): name (server-generated), type, originalName, path.",
-        inputSchema: {
-            fileType: zod_1.z
-                .string()
-                .describe("File type to list (only 'animations' is currently supported)"),
-        },
+        description: "List device asset files (only 'animations' is supported — clips uploadable to G4 Doorbell screens). Returns array; each record (verified live 7.3.70): id, name (server-generated), type, originalName, path, size, createdAt, updatedAt, metadata. An image upload (verified for GIF) later gains a derived <name>.gif preview record, created asynchronously, so a listing taken right after the upload may show only the stored image." + paging_js_1.PAGING_NOTE,
+        inputSchema: { fileType: FILE_TYPE, ...paging_js_1.pagingInput },
         outputSchema: misc_js_1.fileListOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async ({ fileType }) => {
-        try {
-            const data = await client.get((0, url_js_1.safePath) `/files/${fileType}`);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+    }, async ({ fileType, limit, offset }) => {
+        const data = await client.get((0, url_js_1.safePath) `/files/${fileType}`);
+        return (0, responses_js_1.formatSuccess)((0, paging_js_1.pageOf)(data, limit, offset));
     });
     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("User-defined webhook ID matching an alarm manager configuration"),
-            confirm: zod_1.z
-                .literal(true)
-                .describe("Must be true to confirm triggering the alarm webhook"),
-        },
-        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((0, url_js_1.safePath) `/alarm-manager/webhook/${id}`);
-            return (0, responses_js_1.formatSuccess)({ triggered: true, webhookId: id });
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
-    });
     server.registerTool("protect_upload_file", {
-        description: "Upload a base64-encoded file to UniFi Protect",
+        description: "Upload a base64-encoded device asset file (sent as multipart/form-data). Observed for GIF image uploads: Protect stores the image as PNG (appending the stored extension to originalName) and a few seconds later creates a separate <name>.gif preview asset, which protect_list_files shows once it exists. Audio uploads have not been observed. Returns: id, name (server-generated), type, originalName, path, size, createdAt, updatedAt, metadata.",
         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
+            fileType: FILE_TYPE,
+            base64Data: zod_1.z
                 .string()
+                .min(1)
+                .max(limits_js_1.MAX_UPLOAD_BASE64_CHARS, "File too large to send in one MCP message")
+                .describe("Base64-encoded file content (a data: URL prefix is accepted and stripped)"),
+            contentType: zod_1.z
+                .enum(UPLOAD_CONTENT_TYPES)
                 .default("image/gif")
-                .describe("MIME type of the file (accepted: image/gif, image/jpeg, image/png, audio/mpeg, audio/mp4, audio/wave, audio/x-caf)"),
-            dryRun: zod_1.z
-                .boolean()
+                .describe("MIME type of the file"),
+            fileName: zod_1.z
+                .string()
+                .min(1)
                 .optional()
-                .describe("If true, return what would happen without making changes"),
+                .describe("Original file name to record. Reported back as originalName, with the stored extension appended when Protect converts the file (e.g. welcome.gif → welcome.gif.png)"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
+        outputSchema: misc_js_1.fileOutputSchema,
         annotations: safety_js_1.WRITE,
-    }, async ({ fileType, base64Data, contentType, dryRun }) => {
-        try {
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/files/${fileType}`, {
-                    contentType,
-                    dataLength: base64Data.length,
-                });
-            }
-            const buffer = Buffer.from(base64Data, "base64");
-            const data = await client.postBinary((0, url_js_1.safePath) `/files/${fileType}`, buffer, contentType);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+    }, async ({ fileType, base64Data, contentType, fileName, dryRun }) => {
+        const name = fileName ?? defaultFileName(contentType);
+        const base64 = normalizeBase64(base64Data);
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", (0, url_js_1.safePath) `/files/${fileType}`, {
+                contentType,
+                fileName: name,
+                byteLength: Buffer.byteLength(base64, "base64"),
+            });
         }
+        const data = await client.postFile((0, url_js_1.safePath) `/files/${fileType}`, Buffer.from(base64, "base64"), contentType, name);
+        return (0, responses_js_1.formatSuccess)(data);
     });
 }
+const EXTENSIONS = {
+    "image/gif": "gif",
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "audio/mpeg": "mp3",
+    "audio/mp4": "m4a",
+    "audio/wave": "wav",
+    "audio/x-caf": "caf",
+};
+function defaultFileName(contentType) {
+    return `upload.${EXTENSIONS[contentType]}`;
+}
+const DATA_URL_PREFIX = /^data:[^,]*;base64,/i;
+/** Base64 encodes every 3 bytes as a group of 4 characters. */
+const BASE64_GROUP_LENGTH = 4;
+/** Standard or URL-safe base64 (one alphabet, not mixed), padded or not. */
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$|^[A-Za-z0-9_-]+={0,2}$/;
+/**
+ * Strip whitespace and a data: URL prefix, then reject anything that is not
+ * well-formed base64. Buffer.from(x, "base64") skips characters it cannot
+ * decode and ignores a dangling final character, so malformed input would
+ * otherwise upload as corrupt bytes with no error. Whitespace goes first, so
+ * a prefix after a leading line break is still found.
+ */
+function normalizeBase64(input) {
+    const cleaned = input.replace(/\s+/g, "").replace(DATA_URL_PREFIX, "");
+    // Padded input comes in whole groups; unpadded input can end in a partial
+    // group of 2 or 3 characters, but never a lone character (remainder 1).
+    const remainder = cleaned.length % BASE64_GROUP_LENGTH;
+    const wellFormed = BASE64.test(cleaned) &&
+        (cleaned.endsWith("=") ? remainder === 0 : remainder !== 1);
+    if (!wellFormed) {
+        throw new Error("base64Data is not valid base64 (expected A-Z, a-z, 0-9 with + and / or - and _, correctly = padded, or a data: URL)");
+    }
+    return cleaned;
+}

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

@@ -1,25 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAllTools = registerAllTools;
+const registrar_js_1 = require("./registrar.js");
 const system_js_1 = require("./system.js");
 const cameras_js_1 = require("./cameras.js");
 const devices_js_1 = require("./devices.js");
 const device_actions_js_1 = require("./device-actions.js");
 const liveviews_js_1 = require("./liveviews.js");
 const files_js_1 = require("./files.js");
+const alarm_manager_js_1 = require("./alarm-manager.js");
 const subscriptions_js_1 = require("./subscriptions.js");
 const arm_profiles_js_1 = require("./arm-profiles.js");
 const users_js_1 = require("./users.js");
 const pos_js_1 = require("./pos.js");
 function registerAllTools(server, client, readOnly) {
-    (0, system_js_1.registerSystemTools)(server, client);
-    (0, subscriptions_js_1.registerSubscriptionTools)(server, client);
-    (0, cameras_js_1.registerCameraTools)(server, client, readOnly);
-    (0, devices_js_1.registerDeviceTools)(server, client, readOnly);
-    (0, device_actions_js_1.registerDeviceActionTools)(server, client, readOnly);
-    (0, liveviews_js_1.registerLiveviewTools)(server, client, readOnly);
-    (0, files_js_1.registerFileTools)(server, client, readOnly);
-    (0, arm_profiles_js_1.registerArmProfileTools)(server, client, readOnly);
-    (0, users_js_1.registerUserTools)(server, client);
-    (0, pos_js_1.registerPosTools)(server, client, readOnly);
+    // Modules register through instrumentTools only; see registrar.ts.
+    const tools = (0, registrar_js_1.instrumentTools)(server, readOnly);
+    (0, system_js_1.registerSystemTools)(tools, client);
+    (0, subscriptions_js_1.registerSubscriptionTools)(tools, client);
+    (0, cameras_js_1.registerCameraTools)(tools, client, readOnly);
+    (0, devices_js_1.registerDeviceTools)(tools, client, readOnly);
+    (0, device_actions_js_1.registerDeviceActionTools)(tools, client, readOnly);
+    (0, liveviews_js_1.registerLiveviewTools)(tools, client, readOnly);
+    (0, files_js_1.registerFileTools)(tools, client, readOnly);
+    (0, alarm_manager_js_1.registerAlarmManagerTools)(tools, client, readOnly);
+    (0, arm_profiles_js_1.registerArmProfileTools)(tools, client, readOnly);
+    (0, users_js_1.registerUserTools)(tools, client);
+    (0, pos_js_1.registerPosTools)(tools, client, readOnly);
 }

package/dist/tools/liveviews.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 registerLiveviewTools(server: McpServer, client: ProtectClient, readOnly: boolean): void;
+export declare function registerLiveviewTools(server: ToolRegistrar, client: ProtectClient, readOnly: boolean): void;

package/dist/tools/liveviews.js

@@ -5,86 +5,86 @@ 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 misc_js_1 = require("../schemas/misc.js");
+// POST and PATCH both take the full liveview object; every field is required
+// (7.3.70 docs). Slot item schema is not rendered in the docs, so slots pass
+// through beyond the observed { cameras, cycleMode, cycleInterval }.
+const liveviewSlotInput = zod_1.z
+    .object({
+    cameras: zod_1.z.array(zod_1.z.string()).describe("Camera IDs shown in this slot"),
+    cycleMode: zod_1.z.string().describe('Cycle mode, e.g. "time" or "motion"'),
+    cycleInterval: zod_1.z.number().describe("Cycle interval in seconds"),
+})
+    .loose();
+const liveviewBody = zod_1.z
+    .object({
+    id: (0, params_js_1.resourceId)().describe("Liveview ID"),
+    modelKey: zod_1.z.literal("liveview").describe('Must be "liveview"'),
+    name: zod_1.z.string().describe("Liveview name"),
+    isDefault: zod_1.z.boolean().describe("Whether this is the default liveview for all viewers"),
+    isGlobal: zod_1.z.boolean().describe("Whether this liveview is available to all users"),
+    owner: zod_1.z.string().describe("Owning user ID"),
+    layout: zod_1.z.number().min(1).max(26).describe("Number of slots (1-26)"),
+    slots: zod_1.z.array(liveviewSlotInput).describe("Per-slot cameras and cycling settings"),
+})
+    .loose();
 function registerLiveviewTools(server, client, readOnly) {
     server.registerTool("protect_list_liveviews", {
-        description: "List all live views (camera grid layouts shown on viewers / in the Protect UI). Returns array; each liveview includes (Integration API 7.1.83-verified): id, modelKey, name, isDefault, isGlobal, layout (number, slot count), owner (user ID), slots (array of {cameras: string[], cycleMode, cycleInterval}). NOTE: slots use a `cameras` string-array, not a single `cameraId`.",
+        description: "List all live views (camera grid layouts shown on viewers / in the Protect UI). Returns array; each liveview includes (Integration API 7.3.70-verified): id, modelKey, name, isDefault, isGlobal, layout (number, slot count), owner (user ID), slots (array of {cameras: string[], cycleMode, cycleInterval}). NOTE: slots use a `cameras` string-array, not a single `cameraId`." + paging_js_1.PAGING_NOTE,
+        inputSchema: paging_js_1.pagingInput,
         outputSchema: misc_js_1.liveviewListOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async () => {
-        try {
-            const data = await client.get("/liveviews");
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+    }, async ({ limit, offset }) => {
+        const data = await client.get("/liveviews");
+        return (0, responses_js_1.formatSuccess)((0, paging_js_1.pageOf)(data, limit, offset));
     });
     server.registerTool("protect_get_liveview", {
         description: "Get details for a specific live view by ID. Returns: id, modelKey, name, isDefault, isGlobal, layout, owner, slots (each slot: cameras string[], cycleMode, cycleInterval). The full slot list is needed when updating because PATCH replaces the slots array.",
-        inputSchema: { id: zod_1.z.string().describe("Liveview ID") },
+        inputSchema: { id: (0, params_js_1.resourceId)().describe("Liveview ID") },
         outputSchema: misc_js_1.liveviewOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
-        try {
-            const data = await client.get((0, url_js_1.safePath) `/liveviews/${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) `/liveviews/${id}`);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     if (readOnly)
         return;
     server.registerTool("protect_create_liveview", {
-        description: "Create a new live view",
+        description: "Create a new live view. Returns: the created liveview (same fields as protect_get_liveview).",
         inputSchema: {
-            settings: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Liveview configuration. Required fields: id (string), modelKey (string, must be 'liveview'), owner (string, user ID), name (string), layout (number of slots), slots (array of {cameras: string[], cycleMode: string, cycleInterval: number}), isDefault (boolean), isGlobal (boolean)"),
-            dryRun: zod_1.z
-                .boolean()
-                .optional()
-                .describe("If true, return what would happen without making changes"),
+            settings: liveviewBody.describe("Full liveview object (all fields required)"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
         outputSchema: misc_js_1.liveviewOutputSchema,
         annotations: safety_js_1.WRITE,
     }, async ({ settings, dryRun }) => {
-        try {
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", "/liveviews", settings);
-            }
-            const data = await client.post("/liveviews", settings);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", "/liveviews", settings);
         }
+        const data = await client.post("/liveviews", settings);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     server.registerTool("protect_update_liveview", {
-        description: "Update an existing live view (full replacement via PUT-style PATCH — include all fields)",
+        description: "Update an existing live view (full replacement via PUT-style PATCH — include all fields). Returns: the updated liveview.",
         inputSchema: {
-            id: zod_1.z.string().describe("Liveview ID"),
-            settings: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Full liveview object for update (all fields required). Known fields: id (string), modelKey (string, must be 'liveview'), owner (string, user ID), name (string), layout (number), slots (array of {cameras: string[], cycleMode: string, cycleInterval: number}), isDefault (boolean), isGlobal (boolean)"),
-            dryRun: zod_1.z
-                .boolean()
-                .optional()
-                .describe("If true, return what would happen without making changes"),
+            id: (0, params_js_1.resourceId)().describe("Liveview ID"),
+            settings: liveviewBody.describe("Full liveview object (all fields required — fetch it with protect_get_liveview first)"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
         outputSchema: misc_js_1.liveviewOutputSchema,
-        annotations: safety_js_1.WRITE,
+        annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ id, settings, dryRun }) => {
-        try {
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/liveviews/${id}`, settings);
-            }
-            const data = await client.patch((0, url_js_1.safePath) `/liveviews/${id}`, settings);
-            return (0, responses_js_1.formatSuccess)(data);
+        // The body is a full liveview object, so it carries its own id. A
+        // mismatch means the caller copied the wrong liveview's body.
+        if (settings.id !== id) {
+            throw new Error(`settings.id (${settings.id}) does not match the liveview being updated (${id})`);
         }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("PATCH", (0, url_js_1.safePath) `/liveviews/${id}`, settings);
         }
+        const data = await client.patch((0, url_js_1.safePath) `/liveviews/${id}`, settings);
+        return (0, responses_js_1.formatSuccess)(data);
     });
 }

package/dist/tools/pos.d.ts

@@ -1,10 +1,12 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolRegistrar } from "./registrar.js";
 import { ProtectClient } from "../client.js";
 /**
  * Point-of-sale event ingestion (added in Protect 7.3.x).
  *
- * `lineItems` entries use `.passthrough()` because the 7.3.47 docs render the
- * item schema collapsed — the request sample shows `{ title, quantity }`, but
+ * `lineItems` entries use `.loose()` because the 7.3.70 docs render the
+ * item schema collapsed — the request sample shows `{ title, quantity: 1 }`, but
  * an undocumented extra field should reach the API rather than be stripped.
+ * Since the item constraints are not published, `quantity` is only required
+ * to be positive (fractional quantities such as weights are allowed).
  */
-export declare function registerPosTools(server: McpServer, client: ProtectClient, readOnly: boolean): void;
+export declare function registerPosTools(server: ToolRegistrar, client: ProtectClient, readOnly: boolean): void;

package/dist/tools/pos.js

@@ -5,13 +5,16 @@ 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");
 const pos_js_1 = require("../schemas/pos.js");
 /**
  * Point-of-sale event ingestion (added in Protect 7.3.x).
  *
- * `lineItems` entries use `.passthrough()` because the 7.3.47 docs render the
- * item schema collapsed — the request sample shows `{ title, quantity }`, but
+ * `lineItems` entries use `.loose()` because the 7.3.70 docs render the
+ * item schema collapsed — the request sample shows `{ title, quantity: 1 }`, but
  * an undocumented extra field should reach the API rather than be stripped.
+ * Since the item constraints are not published, `quantity` is only required
+ * to be positive (fractional quantities such as weights are allowed).
  */
 function registerPosTools(server, client, readOnly) {
     if (readOnly)
@@ -19,9 +22,9 @@ function registerPosTools(server, client, readOnly) {
     const lineItemSchema = zod_1.z
         .object({
         title: zod_1.z.string().describe("Line item name"),
-        quantity: zod_1.z.number().min(1).describe("Quantity purchased (>= 1)"),
+        quantity: zod_1.z.number().positive().describe("Quantity purchased (> 0)"),
     })
-        .passthrough();
+        .loose();
     server.registerTool("protect_ingest_pos_transaction", {
         description: "Record a point-of-sale transaction as a camera event so the transaction " +
             "details can be overlaid on recorded footage. Requires write access to the " +
@@ -33,7 +36,7 @@ function registerPosTools(server, client, readOnly) {
             "processed for this camera; retry shortly. " +
             "Returns: created (boolean), eventId (string).",
         inputSchema: {
-            id: zod_1.z.string().describe("Camera ID to attach the transaction event to"),
+            id: (0, params_js_1.resourceId)().describe("Camera ID to attach the transaction event to"),
             type: zod_1.z.enum(["sale", "refund"]).describe("Transaction type"),
             externalId: zod_1.z
                 .string()
@@ -59,7 +62,7 @@ function registerPosTools(server, client, readOnly) {
                 id: zod_1.z.string().optional().describe("Store/location ID"),
                 name: zod_1.z.string().optional().describe("Store/location name"),
             })
-                .passthrough()
+                .loose()
                 .optional()
                 .describe("Point-of-sale location"),
             paymentTypes: zod_1.z
@@ -78,24 +81,16 @@ function registerPosTools(server, client, readOnly) {
                 "out-of-range value with a 400 and clamps an in-skew value to now. " +
                 "This tool forwards the value unchanged rather than pre-checking it, " +
                 "because the window is relative to NVR time, not this process clock."),
-            dryRun: zod_1.z
-                .boolean()
-                .optional()
-                .describe("If true, return what would happen without making changes"),
+            dryRun: (0, safety_js_1.dryRunInput)(),
         },
         outputSchema: pos_js_1.posTransactionOutputSchema,
         annotations: safety_js_1.WRITE,
     }, async ({ id, dryRun, ...transaction }) => {
-        try {
-            const path = (0, url_js_1.safePath) `/pos/cameras/${id}/transactions`;
-            if (dryRun) {
-                return (0, safety_js_1.formatDryRun)("POST", path, transaction);
-            }
-            const data = await client.post(path, transaction);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
+        const path = (0, url_js_1.safePath) `/pos/cameras/${id}/transactions`;
+        if (dryRun) {
+            return (0, safety_js_1.formatDryRun)("POST", path, transaction);
         }
+        const data = await client.post(path, transaction);
+        return (0, responses_js_1.formatSuccess)(data);
     });
 }

package/dist/tools/registrar.d.ts

@@ -0,0 +1,34 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * What a tool module may do with the server: register tools, nothing else.
+ * Modules get this rather than the McpServer, so they cannot reach the
+ * registration paths that would bypass instrumentTools (the experimental
+ * task API, RegisteredTool.update(), the deprecated tool()).
+ */
+export type ToolRegistrar = Pick<McpServer, "registerTool">;
+/**
+ * A registrar that applies these rules to every tool it registers, so no tool
+ * module can forget them:
+ *
+ * - The outputSchema is published as a loose object (see looseOutput): a raw
+ *   shape would publish `additionalProperties: false`, and SDK clients would
+ *   reject any field Protect adds.
+ * - A write tool that takes `dryRun` also declares the preview fields in its
+ *   outputSchema, so its dry-run result validates and is documented.
+ * - Handlers run with their call's abort signal in scope, so ProtectClient
+ *   aborts the Protect request (and subscriptions close their WebSocket) when
+ *   the MCP client cancels the call.
+ * - In read-only mode, registering anything but a read-only tool fails at
+ *   startup. Modules also return before their write tools; this catches a
+ *   write tool placed above that return.
+ * - A handler that throws returns an error result (formatError), so tool
+ *   modules need no try/catch of their own.
+ * - A result too large for one stdio message becomes an error, instead of a
+ *   message the client cannot read (which ends its session).
+ * - Each tool gets a human-readable title derived from its name, and by
+ *   default `openWorldHint: false`: every tool talks to one known console,
+ *   not to an open set of external systems.
+ */
+export declare function instrumentTools(server: McpServer, readOnly?: boolean): ToolRegistrar;
+/** "protect_get_rtsp_streams" → "Get RTSP streams". */
+export declare function toolTitle(name: string): string;

package/dist/tools/registrar.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instrumentTools = instrumentTools;
+exports.toolTitle = toolTitle;
+const zod_1 = require("zod");
+const client_js_1 = require("../client.js");
+const common_js_1 = require("../schemas/common.js");
+const responses_js_1 = require("../utils/responses.js");
+const limits_js_1 = require("../utils/limits.js");
+/**
+ * A registrar that applies these rules to every tool it registers, so no tool
+ * module can forget them:
+ *
+ * - The outputSchema is published as a loose object (see looseOutput): a raw
+ *   shape would publish `additionalProperties: false`, and SDK clients would
+ *   reject any field Protect adds.
+ * - A write tool that takes `dryRun` also declares the preview fields in its
+ *   outputSchema, so its dry-run result validates and is documented.
+ * - Handlers run with their call's abort signal in scope, so ProtectClient
+ *   aborts the Protect request (and subscriptions close their WebSocket) when
+ *   the MCP client cancels the call.
+ * - In read-only mode, registering anything but a read-only tool fails at
+ *   startup. Modules also return before their write tools; this catches a
+ *   write tool placed above that return.
+ * - A handler that throws returns an error result (formatError), so tool
+ *   modules need no try/catch of their own.
+ * - A result too large for one stdio message becomes an error, instead of a
+ *   message the client cannot read (which ends its session).
+ * - Each tool gets a human-readable title derived from its name, and by
+ *   default `openWorldHint: false`: every tool talks to one known console,
+ *   not to an open set of external systems.
+ */
+function instrumentTools(server, readOnly = false) {
+    const registerTool = (name, config, handler) => {
+        if (readOnly && config.annotations?.readOnlyHint !== true) {
+            throw new Error(`${name} is a write tool registered in read-only mode`);
+        }
+        // outputSchema is destructured out so the inner call infers its own
+        // output type rather than the caller's generic one. The SDK also accepts
+        // Zod 3 schemas; this server uses Zod 4 throughout, so narrow to that.
+        const { outputSchema, ...rest } = config;
+        const output = outputSchema;
+        const input = config.inputSchema;
+        const bound = async (...args) => {
+            // The SDK passes the call's `extra` (with its abort signal) last.
+            const extra = args.at(-1);
+            let result;
+            try {
+                result = await (0, client_js_1.withCallSignal)(extra?.signal, () => handler(...args));
+            }
+            catch (err) {
+                return (0, responses_js_1.formatError)(err);
+            }
+            return fitsOneMessage(result);
+        };
+        return server.registerTool(name, {
+            ...rest,
+            ...(output === undefined ? {} : { outputSchema: (0, common_js_1.looseOutput)(withPreview(output, input)) }),
+            title: config.title ?? toolTitle(name),
+            annotations: { openWorldHint: false, ...config.annotations },
+        }, bound); // the one cast: bound has handler's call shape
+    };
+    return { registerTool };
+}
+function withPreview(outputSchema, inputSchema) {
+    const takesDryRun = inputSchema !== undefined && !(inputSchema instanceof zod_1.z.ZodType) && "dryRun" in inputSchema;
+    if (!takesDryRun)
+        return outputSchema;
+    if (outputSchema instanceof zod_1.z.ZodObject)
+        return { ...common_js_1.dryRunPreviewFields, ...outputSchema.shape };
+    if (outputSchema instanceof zod_1.z.ZodType)
+        return outputSchema; // looseOutput rejects it
+    return { ...common_js_1.dryRunPreviewFields, ...outputSchema };
+}
+/**
+ * The result itself, or an error when its serialised form would exceed what
+ * one stdio message carries. Measured on the final result: escaping makes a
+ * payload under the per-kind ceilings in limits.ts larger than it looks.
+ */
+function fitsOneMessage(result) {
+    const bytes = Buffer.byteLength(JSON.stringify(result), "utf8");
+    return bytes <= limits_js_1.MAX_RESULT_BYTES
+        ? result
+        : (0, responses_js_1.formatError)(new Error(`Result too large to send in one MCP message (${bytes.toString()} bytes); narrow the request, or page a list tool with limit and offset`));
+}
+// Words in tool names that read wrongly in plain sentence case.
+const TITLE_WORDS = {
+    rtsp: "RTSP",
+    ptz: "PTZ",
+    nvrs: "NVRs",
+    ulp: "ULP",
+    pos: "POS",
+    goto: "go to",
+};
+/** "protect_get_rtsp_streams" → "Get RTSP streams". */
+function toolTitle(name) {
+    const title = name
+        .replace(/^protect_/, "")
+        .split("_")
+        .map((word) => TITLE_WORDS[word] ?? word)
+        .join(" ");
+    return title.charAt(0).toUpperCase() + title.slice(1);
+}

package/dist/tools/subscriptions.d.ts

@@ -1,3 +1,14 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolRegistrar } from "./registrar.js";
 import { ProtectClient } from "../client.js";
-export declare function registerSubscriptionTools(server: McpServer, client: ProtectClient): void;
+/**
+ * Each device message carries a full device object, so a busy site can emit
+ * enough in 30s to flood the MCP client's context. Stop listening at the cap.
+ */
+export declare const MAX_SUBSCRIPTION_MESSAGES = 200;
+/**
+ * The most JSON text one listen returns, about 25k tokens: the scale at which
+ * MCP hosts commonly cap or warn about a tool result. The count cap alone
+ * allowed results several times that size.
+ */
+export declare const MAX_SUBSCRIPTION_TEXT_CHARS = 100000;
+export declare function registerSubscriptionTools(server: ToolRegistrar, client: ProtectClient): void;