@owine/unifi-protect-mcp 2.14.2 → 3.0.0

package/dist/tools/subscriptions.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SUBSCRIPTION_TEXT_CHARS = exports.MAX_SUBSCRIPTION_MESSAGES = void 0;
 exports.registerSubscriptionTools = registerSubscriptionTools;
 const zod_1 = require("zod");
+const client_js_1 = require("../client.js");
 const responses_js_1 = require("../utils/responses.js");
 const safety_js_1 = require("../utils/safety.js");
 const misc_js_1 = require("../schemas/misc.js");
@@ -11,64 +13,183 @@ const durationSchema = zod_1.z
     .max(30)
     .default(5)
     .describe("Seconds to listen (1-30, default 5)");
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.MAX_SUBSCRIPTION_TEXT_CHARS = 100_000;
+/**
+ * The most bytes a UTF-16 code unit takes in UTF-8 (a surrogate pair is four
+ * bytes for two units). A frame larger than the budget times this could never
+ * be returned, so it is not accepted; a smaller one is measured as parsed.
+ */
+const MAX_UTF8_BYTES_PER_CHAR = 3;
+const MAX_FRAME_BYTES = exports.MAX_SUBSCRIPTION_TEXT_CHARS * MAX_UTF8_BYTES_PER_CHAR;
+/** ws's error code for a frame over maxPayload. */
+const FRAME_TOO_LARGE = "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH";
+/** The text a message that cannot fit the budget is reported with. */
+const TOO_LARGE = `a message larger than the ${exports.MAX_SUBSCRIPTION_TEXT_CHARS.toLocaleString("en-US")}-character limit for one listen arrived, and cannot be returned`;
+/**
+ * How long a closing socket may wait for the peer's close frame before it is
+ * dropped. ws itself waits 30 s, which on a half-open connection held a 30 s
+ * listen past the MCP client's default request timeout.
+ */
+const CLOSE_GRACE_MS = 1_000;
+const MS_PER_SECOND = 1000;
+/** The reported listen time is rounded to this many decimal places (0.1s). */
+const ELAPSED_DECIMALS = 1;
 function collectMessages(client, path, duration) {
     return new Promise((resolve) => {
         const messages = [];
         let error;
-        const ws = client.connectWebSocket(path);
-        const timeout = setTimeout(() => {
+        let truncated = false;
+        let opened = false;
+        let finishedAt;
+        // Start with the result's own envelope ({"messages":[],"duration":…}).
+        let textChars = JSON.stringify({ messages: [], duration, truncated: true }).length;
+        const startedAt = Date.now();
+        const ws = client.connectWebSocket(path, { maxPayload: MAX_FRAME_BYTES });
+        let grace;
+        /**
+         * Stop collecting now and close the socket. Messages that arrive after
+         * this are dropped, and a peer that never answers the close frame is cut
+         * off after CLOSE_GRACE_MS.
+         */
+        const finish = () => {
+            if (finishedAt !== undefined)
+                return;
+            finishedAt = Date.now();
+            clearTimeout(window);
+            // Armed before close(): a socket may report "close" synchronously, and
+            // the close handler must find the timer to clear it.
+            grace = setTimeout(() => { ws.terminate(); }, CLOSE_GRACE_MS);
             ws.close();
-        }, duration * 1000);
+        };
+        /**
+         * A message too large for the budget ends the listen as truncated. When
+         * nothing was collected before it, say why the result is empty.
+         */
+        const tooLarge = () => {
+            truncated = true;
+            if (messages.length === 0)
+                error = TOO_LARGE;
+            finish();
+        };
+        // A window that ends before the socket opened listened to nothing, which
+        // an empty result would report as a quiet site.
+        const window = setTimeout(() => {
+            if (!opened)
+                error = `the connection was not established within ${duration.toString()} s; try a longer duration`;
+            finish();
+        }, duration * MS_PER_SECOND);
+        // A cancelled call gets no result, so drop the socket at once rather than
+        // holding it open for the rest of the listen window.
+        const signal = (0, client_js_1.currentCallSignal)();
+        const onAbort = () => {
+            finish();
+            ws.terminate();
+        };
+        ws.on("open", () => {
+            opened = true;
+        });
         ws.on("message", (data) => {
+            if (finishedAt !== undefined)
+                return;
             const text = String(data);
+            let message;
             try {
-                messages.push(JSON.parse(text));
+                message = JSON.parse(text);
             }
             catch {
-                messages.push(text);
+                message = text;
+            }
+            // The comma between array elements counts too.
+            const chars = JSON.stringify(message).length + 1;
+            if (textChars + chars > exports.MAX_SUBSCRIPTION_TEXT_CHARS) {
+                tooLarge();
+                return;
+            }
+            textChars += chars;
+            messages.push(message);
+            if (messages.length >= exports.MAX_SUBSCRIPTION_MESSAGES) {
+                truncated = true;
+                finish();
             }
         });
         ws.on("error", (err) => {
-            error = err.message;
-            clearTimeout(timeout);
-            ws.close();
+            // After finish(), an error is the close it started: closing a socket
+            // that is still connecting aborts the handshake with an error.
+            if (finishedAt !== undefined)
+                return;
+            if (err.code === FRAME_TOO_LARGE) {
+                tooLarge();
+                return;
+            }
+            error = (0, client_js_1.errorReason)(err);
+            finish();
         });
-        ws.on("close", () => {
-            clearTimeout(timeout);
-            const result = { messages, duration };
+        ws.on("close", (code, reason) => {
+            // A close this listen did not start (the console refusing the
+            // subscription, or a dropped connection) ended it early.
+            if (finishedAt === undefined && error === undefined) {
+                const why = reason.length > 0 ? `: ${reason.toString("utf8")}` : "";
+                error = `the console closed the connection (code ${code.toString()}${why})`;
+            }
+            clearTimeout(window);
+            clearTimeout(grace);
+            signal?.removeEventListener("abort", onAbort);
+            // Time actually spent listening: the cap, an error or a cancel can end
+            // the listen early, and the close handshake is not part of it.
+            const elapsed = Number((((finishedAt ?? Date.now()) - startedAt) / MS_PER_SECOND).toFixed(ELAPSED_DECIMALS));
+            const result = { messages, duration: elapsed };
             if (error)
                 result.error = error;
+            if (truncated)
+                result.truncated = true;
             resolve(result);
         });
+        // Last, once every listener is attached: a call cancelled before its
+        // listen began gets no abort event, and must still see its close.
+        if (signal?.aborted)
+            onAbort();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
+/**
+ * A listen that failed before receiving anything is an error, not an empty
+ * result: `{messages: []}` would read as "no activity" when the socket was
+ * refused or unauthorised. One that failed partway returns what it collected,
+ * with the error alongside.
+ */
+function listenResult(data) {
+    return data.error !== undefined && data.messages.length === 0
+        ? (0, responses_js_1.formatError)(new Error(`Subscription failed: ${data.error}`))
+        : (0, responses_js_1.formatSuccess)(data);
+}
 function registerSubscriptionTools(server, client) {
     server.registerTool("protect_subscribe_devices", {
-        description: "Connect to the device update WebSocket and collect messages for a specified duration (1-30s). Returns {messages, duration, error?}; each message has {type: 'add'|'update'|'remove', modelKey: 'camera'|'light'|'sensor'|..., id, payload: partial device fields that changed}. Use to detect state changes like isRecording flipping, battery drops, or new devices being adopted — fields delivered are only those that changed, not the full device object.",
+        description: `Connect to the device update WebSocket and collect messages for a specified duration (1-30s). Returns {messages, duration, error?, truncated?}; stops early with truncated=true after ${exports.MAX_SUBSCRIPTION_MESSAGES.toString()} messages or ${exports.MAX_SUBSCRIPTION_TEXT_CHARS.toLocaleString("en-US")} characters of JSON, whichever comes first. A connection that fails before any message arrives returns an error. Each message is an envelope {type, item} where item is a device resource carrying id and modelKey (camera, light, sensor, nvr, …). The 7.3.70 docs show type 'add' with the full device object as item; other message types and whether updates carry only changed fields are not documented — inspect the captured messages. Use to detect device state changes or newly adopted devices. Not available over Cloud Connector (api.ui.com).`,
         inputSchema: { duration: durationSchema },
         outputSchema: misc_js_1.subscriptionOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async ({ duration }) => {
-        try {
-            const data = await collectMessages(client, "/subscribe/devices", duration);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+        const data = await collectMessages(client, "/subscribe/devices", duration);
+        return listenResult(data);
     });
     server.registerTool("protect_subscribe_events", {
-        description: "Connect to the Protect event WebSocket and collect messages for a specified duration (1-30s). Returns {messages, duration, error?}; each event message includes: id, type ('motion' | 'ring' | 'smartDetectZone' | 'smartDetectLine' | 'sensorMotion' | 'sensorAlarm' | 'fingerprint' | 'nfcCard' | ...), start, end (null while ongoing), camera/sensor id, score, smartDetectTypes (['person','vehicle','animal','package','license_plate','face']), metadata (e.g. detected license plate text, NFC card id, fingerprint id, ULP user match).",
+        description: `Connect to the Protect event WebSocket and collect messages for a specified duration (1-30s). Returns {messages, duration, error?, truncated?}; stops early with truncated=true after ${exports.MAX_SUBSCRIPTION_MESSAGES.toString()} messages or ${exports.MAX_SUBSCRIPTION_TEXT_CHARS.toLocaleString("en-US")} characters of JSON, whichever comes first. A connection that fails before any message arrives returns an error. Each message is an envelope {type: 'add' | 'update', item: {id, modelKey: 'event', type (event kind, e.g. 'ring'), start, end (epoch ms), device (ID of the camera/sensor that raised it)}} (7.3.70 docs). The full set of event kinds and any further event fields are not documented — inspect the captured messages. Not available over Cloud Connector (api.ui.com).`,
         inputSchema: { duration: durationSchema },
         outputSchema: misc_js_1.subscriptionOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async ({ duration }) => {
-        try {
-            const data = await collectMessages(client, "/subscribe/events", duration);
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+        const data = await collectMessages(client, "/subscribe/events", duration);
+        return listenResult(data);
     });
 }

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

package/dist/tools/system.js

@@ -10,25 +10,15 @@ function registerSystemTools(server, client) {
         outputSchema: misc_js_1.infoOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async () => {
-        try {
-            const data = await client.get("/meta/info");
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+        const data = await client.get("/meta/info");
+        return (0, responses_js_1.formatSuccess)(data);
     });
     server.registerTool("protect_list_nvrs", {
-        description: "Get the NVR (Network Video Recorder) console info. NOTE: despite the name, the Protect Integration API's /nvrs endpoint returns a SINGLE NVR object, not an array. Returns: id, modelKey, name, type (e.g. UNVR-PRO), guid, mac, doorbellSettings (defaultMessageText, defaultMessageResetTimeoutMs, customMessages[], customImages[]), armMode (status, armedAt, willBeArmedAt, breachDetectedAt, breachEventCount, breachTriggerEventId, breachEventId).",
+        description: "Get the NVR (Network Video Recorder) console info. NOTE: despite the name, the Protect Integration API's /nvrs endpoint returns a SINGLE NVR object, not an array. Returns: id, modelKey, name, type (e.g. UNVR-PRO), guid, mac, doorbellSettings (defaultMessageText, defaultMessageResetTimeoutMs, customMessages[], customImages[] (preview, sprite)), armMode (status, armProfileId, armedAt, willBeArmedAt, breachDetectedAt, breachEventCount, breachTriggerEventId, breachEventId).",
         outputSchema: misc_js_1.nvrOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async () => {
-        try {
-            const data = await client.get("/nvrs");
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+        const data = await client.get("/nvrs");
+        return (0, responses_js_1.formatSuccess)(data);
     });
 }

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

package/dist/tools/users.js

@@ -1,64 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerUserTools = registerUserTools;
-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");
 function registerUserTools(server, client) {
     server.registerTool("protect_list_users", {
-        description: "List all Protect users (filtered by the API key's access permissions). Returns array; each user includes (Integration API 7.3.47-verified): id, modelKey, name, firstName, lastName, email, ucoreUserId. The Integration API does NOT expose roles, permissions, login history, groups, or notification settings.",
+        description: "List all Protect users (filtered by the API key's access permissions). Returns array; each user includes (Integration API 7.3.70-verified): id, modelKey, name, firstName, lastName, email, ucoreUserId. The Integration API does NOT expose roles, permissions, login history, groups, or notification settings." + paging_js_1.PAGING_NOTE,
+        inputSchema: paging_js_1.pagingInput,
         outputSchema: misc_js_1.userListOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async () => {
-        try {
-            const data = await client.get("/users");
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+    }, async ({ limit, offset }) => {
+        const data = await client.get("/users");
+        return (0, responses_js_1.formatSuccess)((0, paging_js_1.pageOf)(data, limit, offset));
     });
     server.registerTool("protect_get_user", {
         description: "Get details for a specific Protect user by ID. Returns the same fields as protect_list_users entries: id, modelKey, name, firstName, lastName, email, ucoreUserId.",
-        inputSchema: { id: zod_1.z.string().describe("User ID") },
+        inputSchema: { id: (0, params_js_1.resourceId)().describe("User ID") },
         outputSchema: misc_js_1.userOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
-        try {
-            const data = await client.get((0, url_js_1.safePath) `/users/${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) `/users/${id}`);
+        return (0, responses_js_1.formatSuccess)(data);
     });
     server.registerTool("protect_list_ulp_users", {
-        description: "List all UniFi Identity (ULP) users. Returns array; each ULP user includes (Integration API 7.3.47-verified): id, modelKey, firstName, lastName, fullName, email (empty string for service accounts), status (e.g. ACTIVE). Enrolled-credential detail (NFC cards, fingerprints) is NOT exposed by this API surface.",
+        description: "List UniFi Identity (ULP) users — per the API docs, those with enrolled credentials (NFC cards, fingerprints). Returns array; each ULP user includes (Integration API 7.3.70-verified): id, modelKey, firstName, lastName, fullName, email (empty string for service accounts), status (e.g. ACTIVE). Enrolled-credential detail (NFC cards, fingerprints) is NOT exposed by this API surface." + paging_js_1.PAGING_NOTE,
+        inputSchema: paging_js_1.pagingInput,
         outputSchema: misc_js_1.ulpUserListOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async () => {
-        try {
-            const data = await client.get("/ulp-users");
-            return (0, responses_js_1.formatSuccess)(data);
-        }
-        catch (err) {
-            return (0, responses_js_1.formatError)(err);
-        }
+    }, async ({ limit, offset }) => {
+        const data = await client.get("/ulp-users");
+        return (0, responses_js_1.formatSuccess)((0, paging_js_1.pageOf)(data, limit, offset));
     });
     server.registerTool("protect_get_ulp_user", {
         description: "Get details for a specific UniFi Identity (ULP) user by ID. Returns: id, modelKey, firstName, lastName, fullName, email, status.",
-        inputSchema: { id: zod_1.z.string().describe("ULP user ID") },
+        inputSchema: { id: (0, params_js_1.resourceId)().describe("ULP user ID") },
         outputSchema: misc_js_1.ulpUserOutputSchema,
         annotations: safety_js_1.READ_ONLY,
     }, async ({ id }) => {
-        try {
-            const data = await client.get((0, url_js_1.safePath) `/ulp-users/${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) `/ulp-users/${id}`);
+        return (0, responses_js_1.formatSuccess)(data);
     });
 }

package/dist/utils/limits.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The largest serialised tool result. The ceilings below keep payloads near
+ * this, but a result's text copy is JSON-escaped again inside the JSON-RPC
+ * line (quotes double at each level), so instrumentTools measures the final
+ * result against this and refuses one that would not fit.
+ */
+export declare const MAX_RESULT_BYTES: number;
+/**
+ * The most of a JSON response that is read. The bound is on memory, not on
+ * what is returned (a result carries its JSON twice, as text and as
+ * structuredContent, so half a message): bounding the response by that would
+ * fail a large site's list call however small a page it asked for.
+ */
+export declare const MAX_RESPONSE_BYTES: number;
+/** A snapshot reaches the client base64-encoded, inside its result. */
+export declare const MAX_SNAPSHOT_BYTES: number;
+/** An upload arrives from the client base64-encoded. */
+export declare const MAX_UPLOAD_BASE64_CHARS: number;
+/** The server's stdio read buffer (see READ_HEADROOM). */
+export declare const SERVER_READ_BUFFER_BYTES: number;
+/**
+ * How much of an error body is read. Only its start reaches the model, so a
+ * proxy's error page or a runaway body is not buffered whole.
+ */
+export declare const MAX_ERROR_BODY_BYTES: number;
+/** Protect answers JSON calls quickly; a longer wait means something is wrong. */
+export declare const REQUEST_TIMEOUT_MS = 25000;
+/**
+ * Snapshots and uploads get the longest budget that still ends before the MCP
+ * SDK client's default request timeout. It used to equal that timeout, so a
+ * slow snapshot always lost the race.
+ */
+export declare const BINARY_TIMEOUT_MS: number;

package/dist/utils/limits.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BINARY_TIMEOUT_MS = exports.REQUEST_TIMEOUT_MS = exports.MAX_ERROR_BODY_BYTES = exports.SERVER_READ_BUFFER_BYTES = exports.MAX_UPLOAD_BASE64_CHARS = exports.MAX_SNAPSHOT_BYTES = exports.MAX_RESPONSE_BYTES = exports.MAX_RESULT_BYTES = void 0;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/shared/stdio.js");
+const protocol_js_1 = require("@modelcontextprotocol/sdk/shared/protocol.js");
+/**
+ * Payload ceilings, all derived from what one MCP stdio message can carry.
+ *
+ * Over stdio each JSON-RPC message is one line, and the SDK's reader closes
+ * the transport once a line exceeds STDIO_DEFAULT_MAX_BUFFER_SIZE: an SDK
+ * client disconnects (every later call fails with "Not connected"), and this
+ * server's own transport closing ends the process. So nothing this server
+ * returns may exceed that, and what it accepts is checked before it could.
+ */
+/** Room kept for the JSON-RPC envelope and the rest of a result around its payload. */
+const ENVELOPE_BYTES = 64 * 1024;
+/** Base64 encodes every 3 bytes as 4 characters. */
+const BASE64_CHARS_PER_BYTE = 4 / 3;
+/** The largest payload, in bytes or base64 characters, one message can carry. */
+const MAX_PAYLOAD = stdio_js_1.STDIO_DEFAULT_MAX_BUFFER_SIZE - ENVELOPE_BYTES;
+/**
+ * The largest serialised tool result. The ceilings below keep payloads near
+ * this, but a result's text copy is JSON-escaped again inside the JSON-RPC
+ * line (quotes double at each level), so instrumentTools measures the final
+ * result against this and refuses one that would not fit.
+ */
+exports.MAX_RESULT_BYTES = MAX_PAYLOAD;
+/**
+ * How many times one message a JSON response may be. A list tool returns
+ * only the page it was asked for, so the response it pages can be larger than
+ * any result; instrumentTools still refuses a result that would not fit.
+ */
+const RESPONSE_HEADROOM = 4;
+/**
+ * The most of a JSON response that is read. The bound is on memory, not on
+ * what is returned (a result carries its JSON twice, as text and as
+ * structuredContent, so half a message): bounding the response by that would
+ * fail a large site's list call however small a page it asked for.
+ */
+exports.MAX_RESPONSE_BYTES = stdio_js_1.STDIO_DEFAULT_MAX_BUFFER_SIZE * RESPONSE_HEADROOM;
+/** Room for a result's own wrapping around a payload (content type, mimeType). */
+const RESULT_WRAPPER_BYTES = 1024;
+/** A snapshot reaches the client base64-encoded, inside its result. */
+exports.MAX_SNAPSHOT_BYTES = Math.floor((MAX_PAYLOAD - RESULT_WRAPPER_BYTES) / BASE64_CHARS_PER_BYTE);
+/** An upload arrives from the client base64-encoded. */
+exports.MAX_UPLOAD_BASE64_CHARS = MAX_PAYLOAD;
+/**
+ * How much larger than one message the server's own stdio reader accepts.
+ * An upload over MAX_UPLOAD_BASE64_CHARS then still reaches input validation
+ * and is refused with a message, instead of closing the transport and taking
+ * the server down mid-session. Only a message beyond this still does that.
+ */
+const READ_HEADROOM = 4;
+/** The server's stdio read buffer (see READ_HEADROOM). */
+exports.SERVER_READ_BUFFER_BYTES = stdio_js_1.STDIO_DEFAULT_MAX_BUFFER_SIZE * READ_HEADROOM;
+/**
+ * How much of an error body is read. Only its start reaches the model, so a
+ * proxy's error page or a runaway body is not buffered whole.
+ */
+exports.MAX_ERROR_BODY_BYTES = 64 * 1024;
+/** Protect answers JSON calls quickly; a longer wait means something is wrong. */
+exports.REQUEST_TIMEOUT_MS = 25_000;
+/**
+ * Time left for the MCP client between our timeout and its own, so the
+ * server's error (which names the call, and says whether a write may have
+ * landed) reaches the model instead of a bare client-side timeout.
+ */
+const CLIENT_TIMEOUT_MARGIN_MS = 15_000;
+/**
+ * Snapshots and uploads get the longest budget that still ends before the MCP
+ * SDK client's default request timeout. It used to equal that timeout, so a
+ * slow snapshot always lost the race.
+ */
+exports.BINARY_TIMEOUT_MS = protocol_js_1.DEFAULT_REQUEST_TIMEOUT_MSEC - CLIENT_TIMEOUT_MARGIN_MS;

package/dist/utils/paging.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/**
+ * Optional paging for list tools. Protect's list endpoints return every item,
+ * so a large site can produce a result bigger than a host will pass to the
+ * model; these slice it server-side. With neither given, a list tool returns
+ * exactly what Protect returned.
+ */
+export declare const pagingInput: {
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+};
+/** Appended to every list tool's description. */
+export declare const PAGING_NOTE = " On a large site, use limit and offset to page; a paged result also returns totalCount and offset.";
+/** The page of a list that limit/offset select, or the list unchanged when neither is set. */
+export declare function pageOf(data: unknown, limit: number | undefined, offset: number | undefined): unknown;

package/dist/utils/paging.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAGING_NOTE = exports.pagingInput = void 0;
+exports.pageOf = pageOf;
+const zod_1 = require("zod");
+/**
+ * Optional paging for list tools. Protect's list endpoints return every item,
+ * so a large site can produce a result bigger than a host will pass to the
+ * model; these slice it server-side. With neither given, a list tool returns
+ * exactly what Protect returned.
+ */
+exports.pagingInput = {
+    limit: zod_1.z.number().int().min(1).optional().describe("Return at most this many items"),
+    offset: zod_1.z.number().int().min(0).optional().describe("Skip this many items first (default 0)"),
+};
+/** Appended to every list tool's description. */
+exports.PAGING_NOTE = " On a large site, use limit and offset to page; a paged result also returns totalCount and offset.";
+/** The page of a list that limit/offset select, or the list unchanged when neither is set. */
+function pageOf(data, limit, offset) {
+    if ((limit === undefined && offset === undefined) || !Array.isArray(data))
+        return data;
+    const start = offset ?? 0;
+    return {
+        result: data.slice(start, limit === undefined ? undefined : start + limit),
+        totalCount: data.length,
+        offset: start,
+    };
+}

package/dist/utils/params.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/** An Integration API resource ID, as returned by the list and get tools. */
+export declare function resourceId(): z.ZodString;
+/**
+ * An arm profile ID: a resource ID that is not one of the literal routes
+ * beside it, in any case, since a router may match paths case-insensitively.
+ */
+export declare function armProfileId(): z.ZodString;
+/**
+ * An alarm manager webhook ID. These are user-defined in the alarm manager,
+ * so any text is allowed (safePath encodes it) except a bare dot segment.
+ */
+export declare function webhookId(): z.ZodString;

package/dist/utils/params.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceId = resourceId;
+exports.armProfileId = armProfileId;
+exports.webhookId = webhookId;
+const zod_1 = require("zod");
+/**
+ * Protect resource IDs are 24-character hex ObjectIds or UUIDs. The pattern
+ * allows that charset with headroom, and nothing else: IDs are interpolated
+ * into request paths, and while safePath encodes `/ ? # % \`, a bare `.` or
+ * `..` survives encoding and URL parsing then folds it out of the path.
+ */
+const RESOURCE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** An Integration API resource ID, as returned by the list and get tools. */
+function resourceId() {
+    return zod_1.z.string().regex(RESOURCE_ID, "Use an ID returned by a list or get tool");
+}
+/**
+ * Literal routes that sit beside /arm-profiles/{id}. An "ID" naming one would
+ * reach that endpoint instead: PATCH /arm-profiles/settings is the set-current
+ * call, which requires confirm, so update_arm_profile must not reach it.
+ */
+const ARM_PROFILE_ROUTES = new Set(["settings", "enable", "disable"]);
+/**
+ * An arm profile ID: a resource ID that is not one of the literal routes
+ * beside it, in any case, since a router may match paths case-insensitively.
+ */
+function armProfileId() {
+    return resourceId().refine((id) => !ARM_PROFILE_ROUTES.has(id.toLowerCase()), "Use an arm profile ID from protect_list_arm_profiles");
+}
+/**
+ * An alarm manager webhook ID. These are user-defined in the alarm manager,
+ * so any text is allowed (safePath encodes it) except a bare dot segment.
+ */
+function webhookId() {
+    return zod_1.z
+        .string()
+        .min(1)
+        .refine((id) => id !== "." && id !== "..", "A webhook ID cannot be . or ..");
+}

package/dist/utils/responses.js

@@ -10,9 +10,8 @@ function formatSuccess(data) {
         ? data
         : { result: data };
     return {
-        content: [
-            { type: "text", text: JSON.stringify(data, null, 2) },
-        ],
+        // Compact: indentation is whitespace the model pays for in tokens.
+        content: [{ type: "text", text: JSON.stringify(data) }],
         structuredContent: structured,
     };
 }

package/dist/utils/safety.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /** Annotation constants for tool safety classification */
 export declare const READ_ONLY: {
     readonly readOnlyHint: true;
@@ -23,10 +24,45 @@ export declare function formatDryRun(method: string, path: string, body?: unknow
     structuredContent: Record<string, unknown>;
 };
 /**
- * Guard for destructive actions that require explicit confirmation.
- * Returns an error result if `confirm` is not `true`, otherwise `null`.
+ * The `confirm` input of a gated tool. Optional in the schema: a dry run
+ * changes nothing, so it never needs confirming, and the handler checks
+ * confirm only on the real call (see requireConfirmation).
  */
-export declare function requireConfirmation(confirm: boolean, action: string): {
+export declare function confirmInput(action: string): z.ZodOptional<z.ZodBoolean>;
+/** The `dryRun` input every write tool takes; instrumentTools keys on its name. */
+export declare function dryRunInput(): z.ZodOptional<z.ZodBoolean>;
+/**
+ * A confirm gate: the tool's `confirm` input and the handler's check, built
+ * from one action text so the two cannot drift apart. Call `check` after the
+ * dry-run branch.
+ */
+export declare function confirmGate(action: string): {
+    readonly input: z.ZodOptional<z.ZodBoolean>;
+    readonly check: (confirm: boolean | undefined) => {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    } | null;
+};
+/**
+ * Guard for a gated action, checked after the dry-run branch. Returns an
+ * error result if `confirm` is not `true`, otherwise `null`.
+ */
+export declare function requireConfirmation(confirm: boolean | undefined, action: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | null;
+/**
+ * Confirmation for an update that is routine in general but, for these
+ * settings, weakens alarm coverage. Returns null when the update touches none
+ * of `fields`. Call it after the dry-run branch, like requireConfirmation.
+ */
+export declare function requireConfirmationForFields(settings: Record<string, unknown>, fields: readonly string[], confirm: boolean | undefined): {
     content: {
         type: "text";
         text: string;