@owine/unifi-network-mcp 3.1.0 → 3.2.0

package/README.md

@@ -76,9 +76,10 @@ claude mcp add-json unifi-network '{"command":"node","args":["/path/to/unifi-net
 | `UNIFI_NETWORK_WRITE_TOOLS` | No | all write tools | Comma-separated write tool names and/or groups (`devices`, `clients`, `networks`, `wifi`, `hotspot`, `firewall`, `acl`, `dns-policies`, `traffic-matching`) to load; `none` or empty loads none. Unknown names stop the server. Ignored, with a warning, while read-only (see [Limiting write mode](#limiting-write-mode)) |
 | `UNIFI_NETWORK_ALLOW_WAN_EXPOSURE` | No | `false` | Set to `true` to stop refusing writes that could let traffic in from the WAN; they then only need `confirm: true` |
 | `UNIFI_NETWORK_WAN_ZONE_IDS` | No | — | Comma-separated firewall zone IDs (UUIDs) to treat as the WAN, in addition to the system-defined zone named `External`. Recommended when writes are on |
+| `UNIFI_NETWORK_STARTUP_CHECK` | No | `true` | At startup the server reads the console's Network version and exits if that fails, so the MCP host shows it as failed rather than connected. Set to `false` to start without the check, for example while the console is down |
 | `UNIFI_NETWORK_WRITE_LOG` | No | — | Absolute path of a JSON Lines file that every write tool call is appended to. Created `0600` (parent directories `0700`); the server will not start if it is a symlink or writable by others. Ignored, with a warning, while read-only |
 
-UniFi consoles ship with a self-signed certificate, so against a local console the first call usually fails with a certificate error. The safe fix is to trust that one certificate: save it and point `UNIFI_NETWORK_CA_CERT` at the file.
+UniFi consoles ship with a self-signed certificate, so against a local console the server usually fails to start with a certificate error. The safe fix is to trust that one certificate: save it and point `UNIFI_NETWORK_CA_CERT` at the file.
 
 ```bash
 openssl s_client -connect 192.168.1.1:443 </dev/null 2>/dev/null | openssl x509 > ~/.config/unifi-console.pem
@@ -396,7 +397,7 @@ Remote Access and console (UniFi OS) SSH are UniFi OS settings outside this API,
 
 ## Troubleshooting
 
-Configuration errors go to the MCP host's server log and the server exits. Tool errors reach the agent as results starting with `Error:`.
+Configuration errors, and a console the server cannot use at startup, go to the MCP host's server log and the server exits; the host lists it as failed (in Claude Code, `/mcp`). Tool errors reach the agent as results starting with `Error:`.
 
 | Message | Cause and fix |
 |---|---|
@@ -405,11 +406,13 @@ Configuration errors go to the MCP host's server log and the server exits. Tool
 | `UNIFI_NETWORK_CA_CERT must name a PEM file containing a certificate` | The file has no `BEGIN CERTIFICATE` block; re-run the `openssl` command above. |
 | `…cannot be combined with UNIFI_NETWORK_VERIFY_SSL=false` or `TLS verification cannot be disabled for api.ui.com` | Unset `UNIFI_NETWORK_VERIFY_SSL`. |
 | `Ignoring UNIFI_NETWORK_CONSOLE_ID` (log line) | The console ID only applies with `UNIFI_NETWORK_HOST=api.ui.com`. |
+| `Cannot connect to the UniFi console at …` (log line) | The startup check could not read the console; the rest of the line is one of the errors below, or `the host answered, but not with UniFi Network application info` when something other than the console answered at `UNIFI_NETWORK_HOST`. Fix it and restart the server, or set `UNIFI_NETWORK_STARTUP_CHECK=false` to start anyway. |
 | `fetch failed (DEPTH_ZERO_SELF_SIGNED_CERT)` or another certificate code | The console's certificate did not verify. Save it to `UNIFI_NETWORK_CA_CERT`; if you already did, the console has a new certificate, so save it again. |
 | `fetch failed (ECONNREFUSED)`, `(ENOTFOUND)` or a connect timeout | Wrong or unreachable host. `UNIFI_NETWORK_HOST` is a bare IP or hostname, without `https://`. |
 | `HTTP 401` / `HTTP 403` | The key is wrong or revoked, or its admin lacks the rights (a View Only key cannot write). |
 | `HTTP 404` | A wrong `siteId` or resource ID, or an endpoint this Network version lacks (check `unifi_get_info`). |
-| `UniFi controller did not respond within …` | The console is slow. For a write, check whether it was applied before retrying. |
+| `The console is rate-limiting requests` (after `HTTP 429`, on any route) | The console refused the request as too frequent. Wait as long as the message says (or a little while, when it gives no delay) before retrying. |
+| `the console did not respond within …` (startup) or `UniFi controller did not respond within …` | The console is slow, or something drops traffic to it (at startup, often a wrong IP). For a write, check whether it was applied before retrying. |
 | `This action requires explicit confirmation: …` | Expected: the change needs `confirm: true`, and the agent should ask you first. |
 | `Use an ID returned by a list or get tool` | The agent passed a name or malformed ID. |
 | `Request refused by the request guard: …` | The server would only send a request on its allowlist; this one was not, or belongs to a write tool `UNIFI_NETWORK_WRITE_TOOLS` does not enable. Nothing was sent. If a tool you did not modify hits this, please open an issue. |
@@ -419,8 +422,8 @@ Configuration errors go to the MCP host's server log and the server exits. Tool
 | A write tool is missing, or `Tool … not found` | `UNIFI_NETWORK_WRITE_TOOLS` does not name it or its group. |
 | `cannot use UNIFI_NETWORK_WRITE_LOG (…)` | The path is a symlink, not a regular file, hard-linked elsewhere, or writable by others (`chmod 600` it), or its directory cannot be created. |
 | No write tools listed | Read-only is the default. Set `UNIFI_NETWORK_READ_ONLY=false` (only `false` counts; any other value stays read-only) and restart the host. If it is set, check `UNIFI_NETWORK_WRITE_TOOLS` is not `none` or empty. |
-| `Controller history returned HTTP …`, `non-JSON data` or `an empty body` | This console or key cannot use the history routes (see [Retained client connections](#retained-client-connections)). It is not an empty history. |
-| `Classic controller API returned HTTP …`, `non-JSON data` or `malformed JSON` | This console or key cannot read the classic controller API (see [Classic controller reads](#classic-controller-reads)). It is not an empty result. |
+| `Controller history returned HTTP …` (other than 429), `non-JSON data` or `an empty body` | This console or key cannot use the history routes (see [Retained client connections](#retained-client-connections)). It is not an empty history. |
+| `Classic controller API returned HTTP …` (other than 429), `non-JSON data` or `malformed JSON` | This console or key cannot read the classic controller API (see [Classic controller reads](#classic-controller-reads)). It is not an empty result. |
 | `Use the site's internalReference …` | History, classic-API and exposure tools take `internalReference` (often `default`) from `unifi_list_sites`, not the UUID. |
 
 ## Development

package/dist/client.d.ts

@@ -20,6 +20,13 @@ export declare class NetworkClient {
     /** Check a request against the guard before anything is sent, and note writes for the write log. */
     private guard;
     get(path: string): Promise<unknown>;
+    /**
+     * Read /info once, so a console that cannot be reached, fails TLS
+     * verification or rejects the key stops the server at startup, where the
+     * MCP host reports it, instead of the server looking connected and every
+     * tool call failing.
+     */
+    checkConnection(): Promise<void>;
     post(path: string, body?: unknown): Promise<unknown>;
     put(path: string, body: unknown): Promise<unknown>;
     patch(path: string, body: unknown): Promise<unknown>;

package/dist/client.js

@@ -14,6 +14,9 @@ const write_log_js_1 = require("./write-log.js");
 // before the MCP host gives up on it.
 const REQUEST_TIMEOUT_MS = 30_000;
 const CONTROLLER_TIMEOUT_MS = 25_000;
+// Short enough that a console that never answers fails startup well inside
+// the time an MCP host waits for a server to come up.
+const STARTUP_TIMEOUT_MS = 10_000;
 // What undici reports when the console closed the connection under a
 // request, typically a kept-alive socket it had already timed out.
 const SOCKET_CLOSED = ["UND_ERR_SOCKET", "ECONNRESET", "EPIPE"];
@@ -83,6 +86,33 @@ function describeErrorBody(text) {
     }
     return capped(text);
 }
+/**
+ * What the model should do about a 429, or undefined for any other status.
+ * Neither the Integration API docs nor a burst against a UDM (11.1.47) showed
+ * a rate limit, so nothing retries here: the model is told how long to wait
+ * and decides for itself.
+ */
+function rateLimitHint(response) {
+    if (response.status !== 429)
+        return undefined;
+    const wait = retryAfterSeconds(response.headers.get("retry-after"));
+    return `The console is rate-limiting requests; ${wait === undefined ? "wait before retrying" : `retry after ${String(wait)}s`}.`;
+}
+// A longer wait than this is no guidance for a model in a conversation.
+const MAX_RETRY_AFTER_SECONDS = 86_400;
+// RFC 9110 IMF-fixdate. Date.parse alone is too lenient: V8 reads "1.5" as a
+// date in 2001, which would come out as "retry after 0s".
+const HTTP_DATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+/** Retry-After as whole seconds from now (delay-seconds or an HTTP date), or undefined if unusable. */
+function retryAfterSeconds(value) {
+    const trimmed = value?.trim() ?? "";
+    const seconds = /^\d+$/.test(trimmed)
+        ? Number(trimmed)
+        : HTTP_DATE.test(trimmed)
+            ? Math.max(0, Math.ceil((Date.parse(trimmed) - Date.now()) / 1000))
+            : undefined;
+    return seconds !== undefined && seconds <= MAX_RETRY_AFTER_SECONDS ? seconds : undefined;
+}
 function capped(text) {
     const collapsed = text.replace(/\s+/g, " ").trim();
     return collapsed.length > ERROR_BODY_LIMIT ? `${collapsed.slice(0, ERROR_BODY_LIMIT)}…` : collapsed;
@@ -157,7 +187,11 @@ class NetworkClient {
         if (method !== "GET")
             (0, write_log_js_1.noteWriteStatus)(response.status);
         if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${describeErrorBody(await response.text())}`);
+            const body = describeErrorBody(await response.text());
+            const hint = rateLimitHint(response);
+            // One period between the body and the hint, whatever the body ends with.
+            const detail = hint === undefined ? body : [body.replace(/[.!?\s]+$/, ""), hint].filter((part) => part).join(". ");
+            throw new Error(`HTTP ${String(response.status)}: ${detail}`);
         }
         const contentType = response.headers.get("content-type") ?? "";
         if (contentType.includes("application/json")) {
@@ -181,6 +215,30 @@ class NetworkClient {
     async get(path) {
         return this.request("GET", path);
     }
+    /**
+     * Read /info once, so a console that cannot be reached, fails TLS
+     * verification or rejects the key stops the server at startup, where the
+     * MCP host reports it, instead of the server looking connected and every
+     * tool call failing.
+     */
+    async checkConnection() {
+        const timeout = AbortSignal.timeout(STARTUP_TIMEOUT_MS);
+        let info;
+        try {
+            info = await withCallSignal(timeout, () => this.get("/info"));
+        }
+        catch (err) {
+            if (timeout.aborted) {
+                throw new Error(`the console did not respond within ${STARTUP_TIMEOUT_MS / 1000}s`, { cause: err });
+            }
+            throw err;
+        }
+        // Any 2xx passes send(), so a proxy or another web server at the host
+        // would otherwise pass too, and every tool call would then fail.
+        if (!info || typeof info !== "object" || !("applicationVersion" in info) || typeof info.applicationVersion !== "string") {
+            throw new Error("the host answered, but not with UniFi Network application info; check UNIFI_NETWORK_HOST names the console");
+        }
+    }
     async post(path, body) {
         return this.request("POST", path, body);
     }
@@ -261,7 +319,9 @@ class NetworkClient {
             // Drain before throwing: an unread body pins the socket until GC, so a
             // run of failures (say, a mis-scoped API key) would leak connections.
             await response.body?.cancel();
-            throw new Error(`${kind.name} returned HTTP ${response.status}; verify API-key access and controller support. ${kind.notEmpty}`);
+            const hint = rateLimitHint(response);
+            const advice = hint === undefined ? "; verify API-key access and controller support." : `. ${hint}`;
+            throw new Error(`${kind.name} returned HTTP ${String(response.status)}${advice} ${kind.notEmpty}`);
         }
         if (!response.headers.get("content-type")?.includes("application/json")) {
             await response.body?.cancel();

package/dist/config.d.ts

@@ -11,6 +11,7 @@ declare const configSchema: z.ZodObject<{
     consoleId: z.ZodOptional<z.ZodString>;
     verifySsl: z.ZodDefault<z.ZodBoolean>;
     readOnly: z.ZodDefault<z.ZodBoolean>;
+    skipStartupCheck: z.ZodOptional<z.ZodLiteral<true>>;
     writeTools: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>>;
     allowWanExposure: z.ZodOptional<z.ZodLiteral<true>>;
     wanZoneIds: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;

package/dist/config.js

@@ -46,6 +46,10 @@ const configSchema = zod_1.z.object({
         .boolean()
         .default(true)
         .describe("When true, only read-only tools are registered"),
+    skipStartupCheck: zod_1.z
+        .literal(true)
+        .optional()
+        .describe("When true, the server starts without first reading /info to check the console can be used"),
     writeTools: zod_1.z.string()
         .transform((value, ctx) => {
         const { tools, unknown } = (0, write_tools_js_1.parseWriteTools)(value);
@@ -106,6 +110,8 @@ function loadConfig() {
             ? { consoleId: process.env.UNIFI_NETWORK_CONSOLE_ID } : {}),
         verifySsl: process.env.UNIFI_NETWORK_VERIFY_SSL?.toLowerCase() !== "false",
         readOnly: process.env.UNIFI_NETWORK_READ_ONLY?.toLowerCase() !== "false",
+        ...(process.env.UNIFI_NETWORK_STARTUP_CHECK?.toLowerCase() === "false"
+            ? { skipStartupCheck: true } : {}),
         ...(caCert !== undefined ? { caCert } : {}),
         ...(process.env.UNIFI_NETWORK_ALLOW_WAN_EXPOSURE?.toLowerCase() === "true"
             ? { allowWanExposure: true } : {}),

package/dist/index.js

@@ -9,6 +9,7 @@ const client_js_1 = require("./client.js");
 const index_js_1 = require("./tools/index.js");
 const instructions_js_1 = require("./instructions.js");
 const write_log_js_1 = require("./write-log.js");
+const responses_js_1 = require("./utils/responses.js");
 // Read at runtime rather than importing: package.json sits outside rootDir,
 // so a static import would emit dist/src/ and break the published layout.
 // It reads 0.0.0-development in the repo; the release workflow stamps the
@@ -18,6 +19,20 @@ async function main() {
     const config = (0, config_js_1.loadConfig)();
     const writeLog = config.writeLog === undefined ? undefined : (0, write_log_js_1.openWriteLog)(config.writeLog, config.apiKey);
     const client = new client_js_1.NetworkClient(config);
+    // Before the transport connects: exiting now makes the MCP host report the
+    // server as failed, with this message in its log, rather than connected.
+    if (config.skipStartupCheck !== true) {
+        try {
+            await client.checkConnection();
+        }
+        catch (err) {
+            // Exit from the write's callback: stderr to a pipe is asynchronous on
+            // macOS, and exiting first could drop the only explanation the host logs.
+            process.stderr.write(`Cannot connect to the UniFi console at ${config.host}: ${(0, responses_js_1.describeError)(err)}. ` +
+                "Fix the setting the error names and restart, or set UNIFI_NETWORK_STARTUP_CHECK=false to start without this check.\n", () => process.exit(1));
+            return;
+        }
+    }
     const server = new mcp_js_1.McpServer({ name: "unifi-network", title: "UniFi Network", version }, { instructions: (0, instructions_js_1.serverInstructions)(config.readOnly, { writeTools: config.writeTools, allowWanExposure: config.allowWanExposure === true }) });
     (0, index_js_1.registerAllTools)(server, client, config.readOnly, {
         writeTools: config.writeTools,

package/dist/tools/acl.js

@@ -299,12 +299,11 @@ function registerAclTools(server, client, readOnly = false) {
             const body = { orderedAclRuleIds };
             const current = (0, full_put_js_1.asObject)(await client.get(path), "the current ACL rule ordering");
             const before = Array.isArray(current.orderedAclRuleIds) ? current.orderedAclRuleIds.filter((id) => typeof id === "string") : [];
-            const opens = await (0, safety_js_1.reorderOpens)(before, orderedAclRuleIds, async (id) => {
-                const rule = (0, full_put_js_1.asObject)(await client.get(`/sites/${siteId}/acl-rules/${id}`), "an ACL rule");
+            const opens = await (0, safety_js_1.reorderOpens)(before, orderedAclRuleIds, () => (0, safety_js_1.listedEffects)(client, `/sites/${siteId}/acl-rules`, (rule) => {
                 // A disabled rule neither lets anything through nor blocks it.
                 const active = rule.enabled !== false;
                 return { letsThrough: active && rule.action === "ALLOW", blocks: active && rule.action === "BLOCK" };
-            });
+            }));
             const opening = opens ? "This moves an ALLOW rule ahead of a BLOCK rule it used to follow" : undefined;
             const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
             if (guard)

package/dist/tools/devices.js

@@ -42,7 +42,7 @@ function registerDeviceTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_device", {
-        description: "Get full configuration for a device. Returns (in addition to list fields): adoptedAt, provisionedAt, configurationId, uplink.deviceId (absent on the ISP modem), features (object keyed by capability: switching {lags[]} / accessPoint {}), interfaces.ports[] for switches, gateways and modems ({idx, state, connector, maxSpeedMbps, speedMbps (may be omitted on DOWN ports), poe:{standard, type, enabled, state} on PoE ports only}), interfaces.radios[] for APs ({wlanStandard, frequencyGHz, channelWidthMHz, channel}). Some devices (e.g. 5G modems) return empty features/interfaces objects. NOTE: in the LIST endpoint, features/interfaces are capability-tag string arrays instead. Use for: switch port layout/PoE state, AP radio config, uplink topology. For live throughput/CPU/memory, use unifi_get_device_statistics.",
+        description: "Get full configuration for a device. Returns (in addition to list fields): adoptedAt, provisionedAt, configurationId, uplink.deviceId (absent on the ISP modem), features (object keyed by capability: switching {lags[]} / accessPoint {}), interfaces.ports[] for switches, gateways and modems ({idx, state, connector, maxSpeedMbps, speedMbps (may be omitted on DOWN ports), poe:{standard, type, enabled, state} on PoE ports only}), interfaces.radios[] for APs ({wlanStandard, frequencyGHz, txPowerMode (e.g. MEDIUM; 11.1.47 and later), channelWidthMHz, channel}). Some devices (e.g. 5G modems) return empty features/interfaces objects. NOTE: in the LIST endpoint, features/interfaces are capability-tag string arrays instead. Use for: switch port layout/PoE state, AP radio config, uplink topology. For live throughput/CPU/memory, use unifi_get_device_statistics.",
         inputSchema: {
             siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             deviceId: (0, params_js_1.resourceId)().describe("Device ID"),

package/dist/tools/firewall.js

@@ -497,14 +497,14 @@ function registerFirewallTools(server, client, readOnly = false, wan = wan_expos
             const path = `/sites/${siteId}/firewall/policies/ordering${query}`;
             const body = { orderedFirewallPolicyIds };
             const current = (0, full_put_js_1.asObject)(await client.get(path), "the current firewall policy ordering");
-            const opens = await (0, safety_js_1.reorderOpens)(evaluationOrder(current.orderedFirewallPolicyIds), evaluationOrder(orderedFirewallPolicyIds), async (id) => {
-                // The system-defined policies are not listed, so their actions are
-                // unknown: moving anything across them counts both ways.
-                if (id === SYSTEM_DEFINED)
-                    return { letsThrough: true, blocks: true };
-                const policy = (0, full_put_js_1.asObject)(await client.get(`/sites/${siteId}/firewall/policies/${id}`), "a firewall policy");
-                const active = policy.enabled !== false;
-                return { letsThrough: active && letsThrough(policy), blocks: active && !letsThrough(policy) };
+            const opens = await (0, safety_js_1.reorderOpens)(evaluationOrder(current.orderedFirewallPolicyIds), evaluationOrder(orderedFirewallPolicyIds), async () => {
+                const effects = await (0, safety_js_1.listedEffects)(client, `/sites/${siteId}/firewall/policies`, (policy) => {
+                    const active = policy.enabled !== false;
+                    return { letsThrough: active && letsThrough(policy), blocks: active && !letsThrough(policy) };
+                });
+                // The system-defined policies are not in the ordering by ID, so their
+                // actions are unknown: moving anything across them counts both ways.
+                return effects.set(SYSTEM_DEFINED, { letsThrough: true, blocks: true });
             });
             const opening = opens ? "This moves a firewall policy that lets traffic through ahead of one that blocks it" : undefined;
             const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);

package/dist/utils/list-all.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+import type { NetworkClient } from "../client.js";
+/** Every item of a paged Integration API list, read page by page. */
+export declare function listAll<T extends z.ZodType>(client: NetworkClient, path: string, item: T): Promise<z.infer<T>[]>;

package/dist/utils/list-all.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listAll = listAll;
+const zod_1 = require("zod");
+const PAGE_LIMIT = 200;
+const MAX_PAGES = 50;
+/** Every item of a paged Integration API list, read page by page. */
+async function listAll(client, path, item) {
+    const page = zod_1.z.object({ data: zod_1.z.array(item), totalCount: zod_1.z.number().optional() }).loose();
+    const items = [];
+    for (let pages = 0; pages < MAX_PAGES; pages++) {
+        const { data, totalCount } = page.parse(await client.get(`${path}?offset=${items.length}&limit=${PAGE_LIMIT}`));
+        items.push(...data);
+        // Without a totalCount, only an empty page shows the list has ended: a
+        // controller may cap pages below PAGE_LIMIT, so a short page proves nothing.
+        if (data.length === 0 || (totalCount !== undefined && items.length >= totalCount))
+            return items;
+    }
+    // A list that does not end cannot be checked, which must not pass.
+    throw new Error(`the list did not end after ${MAX_PAGES} pages`);
+}

package/dist/utils/output-schemas.d.ts

@@ -482,6 +482,7 @@ export declare const getDeviceOutputSchema: {
         radios: z.ZodOptional<z.ZodArray<z.ZodObject<{
             wlanStandard: z.ZodOptional<z.ZodString>;
             frequencyGHz: z.ZodOptional<z.ZodNumber>;
+            txPowerMode: z.ZodOptional<z.ZodString>;
             channelWidthMHz: z.ZodOptional<z.ZodNumber>;
             channel: z.ZodOptional<z.ZodNumber>;
         }, z.core.$loose>>>;

package/dist/utils/output-schemas.js

@@ -75,6 +75,8 @@ const DeviceRadio = zod_1.z
     .object({
     wlanStandard: zod_1.z.string().optional(),
     frequencyGHz: zod_1.z.number().optional(),
+    // Undocumented; live-verified on 11.1.47 (e.g. "MEDIUM"), absent on 11.0.83.
+    txPowerMode: zod_1.z.string().optional(),
     channelWidthMHz: zod_1.z.number().optional(),
     channel: zod_1.z.number().optional(),
 })

package/dist/utils/responses.d.ts

@@ -9,6 +9,12 @@ export declare function formatSuccess(data: unknown, opts?: {
 };
 /** The message of a thrown value, which need not be an Error. */
 export declare function errorMessage(err: unknown): string;
+/**
+ * The message of a failed request, with the reason fetch keeps in cause: fetch
+ * reports every network failure as "fetch failed" and keeps the reason
+ * (ECONNREFUSED, ENOTFOUND, a certificate error) there.
+ */
+export declare function describeError(err: unknown): string;
 export declare function formatError(err: unknown): {
     content: {
         type: "text";

package/dist/utils/responses.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatSuccess = formatSuccess;
 exports.errorMessage = errorMessage;
+exports.describeError = describeError;
 exports.formatError = formatError;
 function formatSuccess(data, opts) {
     const result = {
@@ -19,18 +20,24 @@ function formatSuccess(data, opts) {
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
-function formatError(err) {
+/**
+ * The message of a failed request, with the reason fetch keeps in cause: fetch
+ * reports every network failure as "fetch failed" and keeps the reason
+ * (ECONNREFUSED, ENOTFOUND, a certificate error) there.
+ */
+function describeError(err) {
     let message = errorMessage(err);
-    // fetch reports every network failure as "fetch failed" and keeps the reason
-    // (ECONNREFUSED, ENOTFOUND, a certificate error) in cause.
     const cause = err instanceof Error ? err.cause : undefined;
     const code = cause instanceof Error && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
     if (code) {
         message += ` (${code})`;
         message += tlsHint(code);
     }
+    return message;
+}
+function formatError(err) {
     return {
-        content: [{ type: "text", text: `Error: ${message}` }],
+        content: [{ type: "text", text: `Error: ${describeError(err)}` }],
         isError: true,
     };
 }

package/dist/utils/safety.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { NetworkClient } from "../client.js";
 /** The confirm input of a DESTRUCTIVE tool. */
 export declare const confirmDestructive: () => z.ZodOptional<z.ZodBoolean>;
 export declare const READ_ONLY: ToolAnnotations;
@@ -36,13 +37,28 @@ export interface RuleEffect {
     letsThrough: boolean;
     blocks: boolean;
 }
+/**
+ * A firewall policy or ACL rule as a list returns it, typed only as far as a
+ * reorder check reads it. An entry without an ID cannot be in an ordering, so
+ * it is skipped rather than failing the check.
+ */
+declare const ListedRule: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodUnknown>;
+    action: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+/** Every rule of a list by ID, with its effect, for reorderOpens. */
+export declare function listedEffects(client: NetworkClient, path: string, effectOf: (rule: z.infer<typeof ListedRule>) => RuleEffect): Promise<Map<string, RuleEffect>>;
 /**
  * Whether a reorder opens access: whether it moves a rule that lets traffic
  * through ahead of one that blocks, which it used to follow. Only rules in
- * both orders are compared, and effect is asked only about the rules a
- * reorder actually moves past one another. IDs are compared without case.
+ * both orders are compared. effects reads every rule's effect at once (one
+ * list read, not a GET per rule, which a large reshuffle would turn into a
+ * burst of hundreds), and is called only when the reorder moves rules past
+ * one another. A moved rule it does not return (deleted since the ordering
+ * was read) is refused rather than guessed. IDs are compared without case.
  */
-export declare function reorderOpens(before: readonly string[], after: readonly string[], effect: (id: string) => Promise<RuleEffect>): Promise<boolean>;
+export declare function reorderOpens(before: readonly string[], after: readonly string[], effects: () => Promise<ReadonlyMap<string, RuleEffect>>): Promise<boolean>;
 export declare function requireConfirmation(confirm: boolean | undefined, action: string): {
     content: {
         type: "text";
@@ -50,3 +66,4 @@ export declare function requireConfirmation(confirm: boolean | undefined, action
     }[];
     isError: true;
 } | null;
+export {};

package/dist/utils/safety.js

@@ -3,10 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DESTRUCTIVE = exports.WRITE_NOT_IDEMPOTENT = exports.WRITE = exports.READ_ONLY = exports.confirmDestructive = void 0;
 exports.formatDryRun = formatDryRun;
 exports.requireConfirmationIf = requireConfirmationIf;
+exports.listedEffects = listedEffects;
 exports.reorderOpens = reorderOpens;
 exports.requireConfirmation = requireConfirmation;
 const zod_1 = require("zod");
 const write_log_js_1 = require("../write-log.js");
+const list_all_js_1 = require("./list-all.js");
+const responses_js_1 = require("./responses.js");
 /** The confirm input of a DESTRUCTIVE tool. */
 const confirmDestructive = () => zod_1.z.boolean().optional().describe("Must be true to execute this destructive action; not needed with dryRun: true");
 exports.confirmDestructive = confirmDestructive;
@@ -60,13 +63,33 @@ function formatDryRun(method, path, body, confirmationRequired) {
 function requireConfirmationIf(reason, confirm, dryRun) {
     return reason === undefined || dryRun ? null : requireConfirmation(confirm, reason);
 }
+/**
+ * A firewall policy or ACL rule as a list returns it, typed only as far as a
+ * reorder check reads it. An entry without an ID cannot be in an ordering, so
+ * it is skipped rather than failing the check.
+ */
+const ListedRule = zod_1.z.object({
+    id: zod_1.z.string().optional(),
+    enabled: zod_1.z.unknown().optional(),
+    action: zod_1.z.unknown().optional(),
+}).loose();
+/** Every rule of a list by ID, with its effect, for reorderOpens. */
+async function listedEffects(client, path, effectOf) {
+    const rules = await (0, list_all_js_1.listAll)(client, path, ListedRule).catch((err) => {
+        throw new Error(`the rules this reorder moves could not be read, so whether it opens access is unknown (${(0, responses_js_1.errorMessage)(err)})`, { cause: err });
+    });
+    return new Map(rules.flatMap((rule) => rule.id === undefined ? [] : [[rule.id, effectOf(rule)]]));
+}
 /**
  * Whether a reorder opens access: whether it moves a rule that lets traffic
  * through ahead of one that blocks, which it used to follow. Only rules in
- * both orders are compared, and effect is asked only about the rules a
- * reorder actually moves past one another. IDs are compared without case.
+ * both orders are compared. effects reads every rule's effect at once (one
+ * list read, not a GET per rule, which a large reshuffle would turn into a
+ * burst of hundreds), and is called only when the reorder moves rules past
+ * one another. A moved rule it does not return (deleted since the ordering
+ * was read) is refused rather than guessed. IDs are compared without case.
  */
-async function reorderOpens(before, after, effect) {
+async function reorderOpens(before, after, effects) {
     const rank = new Map(before.map((id, index) => [id.toLowerCase(), index]));
     const passes = [];
     after.forEach((ahead, i) => {
@@ -76,9 +99,16 @@ async function reorderOpens(before, after, effect) {
                 passes.push([ahead, behind]);
         }
     });
-    const ids = [...new Set(passes.flat())];
-    const effects = new Map(await Promise.all(ids.map(async (id) => [id, await effect(id)])));
-    return passes.some(([ahead, behind]) => effects.get(ahead)?.letsThrough === true && effects.get(behind)?.blocks === true);
+    if (passes.length === 0)
+        return false;
+    const known = new Map([...(await effects())].map(([id, effect]) => [id.toLowerCase(), effect]));
+    // Every moved rule is checked first, so the answer never rests on a guess.
+    for (const id of new Set(passes.flat())) {
+        if (!known.has(id.toLowerCase())) {
+            throw new Error(`no rule with ID ${JSON.stringify(id)} is in this site's list, though the current ordering names it; read the ordering again`);
+        }
+    }
+    return passes.some(([ahead, behind]) => known.get(ahead.toLowerCase())?.letsThrough === true && known.get(behind.toLowerCase())?.blocks === true);
 }
 function requireConfirmation(confirm, action) {
     if (confirm !== true) {

package/dist/utils/wan-exposure.js

@@ -5,6 +5,7 @@ exports.wanRefusal = wanRefusal;
 const zod_1 = require("zod");
 const write_log_js_1 = require("../write-log.js");
 const responses_js_1 = require("./responses.js");
+const list_all_js_1 = require("./list-all.js");
 exports.DEFAULT_WAN_POLICY = { allowExposure: false, zoneIds: [] };
 const Zone = zod_1.z.object({
     id: zod_1.z.string(),
@@ -19,22 +20,6 @@ const Policy = zod_1.z.object({
     source: zod_1.z.unknown().optional(),
     destination: zod_1.z.unknown().optional(),
 }).loose();
-const PAGE_LIMIT = 200;
-const MAX_PAGES = 50;
-async function listAll(client, path, item) {
-    const page = zod_1.z.object({ data: zod_1.z.array(item), totalCount: zod_1.z.number().optional() }).loose();
-    const items = [];
-    for (let pages = 0; pages < MAX_PAGES; pages++) {
-        const { data, totalCount } = page.parse(await client.get(`${path}?offset=${items.length}&limit=${PAGE_LIMIT}`));
-        items.push(...data);
-        // Without a totalCount, only an empty page shows the list has ended: a
-        // controller may cap pages below PAGE_LIMIT, so a short page proves nothing.
-        if (data.length === 0 || (totalCount !== undefined && items.length >= totalCount))
-            return items;
-    }
-    // A list that does not end cannot be checked, which must not pass.
-    throw new Error(`the list did not end after ${MAX_PAGES} pages`);
-}
 class Refusal extends Error {
 }
 /** The checks for one site; zones and policies are read at most once per call. */
@@ -176,13 +161,13 @@ class WanExposure {
         return zone;
     }
     zoneList() {
-        this.zones ??= listAll(this.client, `/sites/${this.siteId}/firewall/zones`, Zone).catch((err) => {
+        this.zones ??= (0, list_all_js_1.listAll)(this.client, `/sites/${this.siteId}/firewall/zones`, Zone).catch((err) => {
             throw new Refusal(`the firewall zones could not be read to find the WAN zone (${(0, responses_js_1.errorMessage)(err)})`);
         });
         return this.zones;
     }
     policyList() {
-        this.policies ??= listAll(this.client, `/sites/${this.siteId}/firewall/policies`, Policy).catch((err) => {
+        this.policies ??= (0, list_all_js_1.listAll)(this.client, `/sites/${this.siteId}/firewall/policies`, Policy).catch((err) => {
             throw new Refusal(`the firewall policies that the change depends on could not be read (${(0, responses_js_1.errorMessage)(err)})`);
         });
         return this.policies;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-network-mcp",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "MCP server exposing the UniFi Network Integration API as tools for Claude and other MCP clients",
   "main": "dist/index.js",
   "bin": {
@@ -23,7 +23,7 @@
   "engines": {
     "node": "^22.19.0 || ^24.0.0 || ^26.0.0"
   },
-  "packageManager": "pnpm@12.16.1",
+  "packageManager": "pnpm@12.21.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/owine/unifi-network-mcp.git"
@@ -41,18 +41,18 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.2",
-    "undici": "8.12.3",
+    "undici": "8.12.4",
     "zod": "4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/node": "26.6.6",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "5.0.5",
-    "eslint": "10.14.0",
+    "@vitest/coverage-v8": "5.1.0",
+    "eslint": "10.15.0",
     "lefthook": "2.2.2",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.72.1",
-    "vitest": "5.0.5"
+    "typescript-eslint": "8.72.2",
+    "vitest": "5.1.0"
   }
 }