@owine/unifi-network-mcp 2.15.0 → 3.0.0

package/dist/tools/switching.js

@@ -6,24 +6,25 @@ const responses_js_1 = require("../utils/responses.js");
 const query_js_1 = require("../utils/query.js");
 const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+const params_js_1 = require("../utils/params.js");
 function registerSwitchingTools(server, client) {
     server.registerTool("unifi_list_switch_stacks", {
         description: "List Switch Stacks (multiple physical switches managed as one logical unit) at a site. Returns: id, deviceId (the stack's primary device), name, units[] (the stacked switches — named `members` on consoles older than 10.6.106), lags[] (LAGs spanning the stack), metadata.origin. Per-unit schema is not rendered in the 11.0.83 docs — call unifi_get_switch_stack to inspect. Use for: identifying stacked switches; individual member configs/stats still come from unifi_get_device.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -44,8 +45,8 @@ function registerSwitchingTools(server, client) {
     server.registerTool("unifi_get_switch_stack", {
         description: "Get full details of a Switch Stack including all units and stacking topology. Returns the same fields as the list response but for a single stack: id, deviceId, name, units[] (named `members` before 10.6.106), lags[], metadata.origin.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            switchStackId: zod_1.z.string().describe("Switch Stack ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            switchStackId: (0, params_js_1.resourceId)().describe("Switch Stack ID"),
         },
         outputSchema: output_schemas_js_1.switchStackOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -61,20 +62,20 @@ function registerSwitchingTools(server, client) {
     server.registerTool("unifi_list_mc_lag_domains", {
         description: "List MC-LAG (Multi-Chassis Link Aggregation) Domains — pairs of switches presenting as one for LAG redundancy. Returns: id, name, peers[] (per the older 10.4.57 spec: {deviceId, linkPortIdxs[], role TOP|BOTTOM}; not live-verified), lags[] (LAGs spanning the domain), metadata.origin.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -95,8 +96,8 @@ function registerSwitchingTools(server, client) {
     server.registerTool("unifi_get_mc_lag_domain", {
         description: "Get full details of an MC-LAG Domain (peer switches and member LAGs).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            mcLagDomainId: zod_1.z.string().describe("MC-LAG Domain ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            mcLagDomainId: (0, params_js_1.resourceId)().describe("MC-LAG Domain ID"),
         },
         outputSchema: output_schemas_js_1.mcLagDomainOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -112,20 +113,20 @@ function registerSwitchingTools(server, client) {
     server.registerTool("unifi_list_lags", {
         description: "List LAGs (Link Aggregation Groups — bonded switch ports) at a site. Returns: id, type (LOCAL/SWITCH_STACK/MULTI_CHASSIS), members[] ({deviceId, portIdxs[]}), switchStackId (SWITCH_STACK) or mcLagDomainId (MULTI_CHASSIS), metadata.origin.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -146,8 +147,8 @@ function registerSwitchingTools(server, client) {
     server.registerTool("unifi_get_lag", {
         description: "Get full details of a LAG including its type (LOCAL/SWITCH_STACK/MULTI_CHASSIS) and member ports.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            lagId: zod_1.z.string().describe("LAG ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            lagId: (0, params_js_1.resourceId)().describe("LAG ID"),
         },
         outputSchema: output_schemas_js_1.lagOutputSchema,
         annotations: safety_js_1.READ_ONLY,

package/dist/tools/system.js

@@ -6,7 +6,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
 function registerSystemTools(server, client) {
     server.registerTool("unifi_get_info", {
-        description: "Get UniFi Network application info. Returns: applicationVersion. NOTE: verified against 10.6.106 on a UniFi OS console — the Integration API returns ONLY applicationVersion here; there is no isUniFiOSConsole or other field. Use for: version checks before calling version-gated tools.",
+        description: "Get UniFi Network application info. Returns: applicationVersion only — the Integration API returns no isUniFiOSConsole or other field here. Use for: checking the Network version when a tool's description notes version-specific behaviour.",
         inputSchema: {},
         outputSchema: output_schemas_js_1.getInfoOutputSchema,
         annotations: safety_js_1.READ_ONLY,

package/dist/tools/traffic-matching.d.ts

@@ -1,3 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { NetworkClient } from "../client.js";
-export declare function registerTrafficMatchingTools(server: McpServer, client: NetworkClient, readOnly?: boolean): void;
+import { type WanPolicy } from "../utils/wan-exposure.js";
+export declare function registerTrafficMatchingTools(server: McpServer, client: NetworkClient, readOnly?: boolean, wan?: WanPolicy): void;

package/dist/tools/traffic-matching.js

@@ -6,28 +6,30 @@ const responses_js_1 = require("../utils/responses.js");
 const query_js_1 = require("../utils/query.js");
 const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+const params_js_1 = require("../utils/params.js");
+const wan_exposure_js_1 = require("../utils/wan-exposure.js");
 const matchingItems = zod_1.z
-    .array(zod_1.z.object({ type: zod_1.z.string().describe("Item type, e.g. PORT_NUMBER, IP_ADDRESS, SUBNET") }).passthrough())
+    .array(zod_1.z.object({ type: zod_1.z.string().describe("Item type, e.g. PORT_NUMBER, IP_ADDRESS, SUBNET") }).loose())
     .min(1)
     .describe("Non-empty array of tagged item objects, e.g. [{type:'PORT_NUMBER', value:443}]");
-function registerTrafficMatchingTools(server, client, readOnly = false) {
+function registerTrafficMatchingTools(server, client, readOnly = false, wan = wan_exposure_js_1.DEFAULT_WAN_POLICY) {
     server.registerTool("unifi_list_traffic_matching_lists", {
         description: "List traffic matching lists at a site — named collections of ports or IPs reused in firewall/ACL rules. Returns: id, type (PORTS/IPV4_ADDRESSES/IPV6_ADDRESSES), name, items[] (tagged objects such as {type:'PORT_NUMBER', value:22} or {type:'SUBNET', value:'<cidr>'}). Use for: finding the matching-list ID to reference from a firewall policy.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -48,8 +50,8 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_traffic_matching_list", {
         description: "Get a specific traffic matching list by ID (full items array).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            trafficMatchingListId: zod_1.z.string().describe("Traffic matching list ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            trafficMatchingListId: (0, params_js_1.resourceId)().describe("Traffic matching list ID"),
         },
         outputSchema: output_schemas_js_1.trafficMatchingListOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -67,7 +69,7 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
     server.registerTool("unifi_create_traffic_matching_list", {
         description: "Create a new traffic matching list. Items are tagged objects, not strings (live-verified 11.0.83): PORTS lists take {type:'PORT_NUMBER', value:443} (the older 10.4.57 spec also lists {type:'PORT_NUMBER_RANGE', start, stop}); IPV4_ADDRESSES lists take {type:'IP_ADDRESS', value:'192.0.2.1'} or {type:'SUBNET', value:'192.0.2.0/24'} (spec also: IP_ADDRESS_RANGE {start, stop}); IPV6_ADDRESSES lists take IP_ADDRESS or SUBNET. Idempotency: not safe to retry — re-running creates a duplicate list.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             type: zod_1.z
                 .enum(["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"])
                 .describe("List type"),
@@ -78,7 +80,7 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.trafficMatchingListOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.trafficMatchingListOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
     }, async ({ siteId, type, name, items, dryRun }) => {
         try {
@@ -95,8 +97,8 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
     server.registerTool("unifi_update_traffic_matching_list", {
         description: "Replace a traffic matching list (full PUT — type, name and the complete items array are all required; read the current list with unifi_get_traffic_matching_list first). Items are tagged objects, not strings (live-verified 11.0.83): PORTS lists take {type:'PORT_NUMBER', value:443} (the older 10.4.57 spec also lists {type:'PORT_NUMBER_RANGE', start, stop}); IPV4_ADDRESSES lists take {type:'IP_ADDRESS', value:'192.0.2.1'} or {type:'SUBNET', value:'192.0.2.0/24'} (spec also: IP_ADDRESS_RANGE {start, stop}); IPV6_ADDRESSES lists take IP_ADDRESS or SUBNET.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            trafficMatchingListId: zod_1.z.string().describe("Traffic matching list ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            trafficMatchingListId: (0, params_js_1.resourceId)().describe("Traffic matching list ID"),
             type: zod_1.z
                 .enum(["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"])
                 .describe("List type"),
@@ -107,11 +109,14 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.trafficMatchingListOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.trafficMatchingListOutputSchema),
         annotations: safety_js_1.WRITE,
     }, async ({ siteId, trafficMatchingListId, type, name, items, dryRun }) => {
         try {
             const body = { type, name, items };
+            const exposure = await new wan_exposure_js_1.WanExposure(client, wan, siteId).matchingList(trafficMatchingListId);
+            if (exposure)
+                return (0, wan_exposure_js_1.wanRefusal)(exposure, "PUT", `/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`);
             if (dryRun)
                 return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`, body);
             const data = await client.put(`/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`, body);
@@ -124,12 +129,9 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
     server.registerTool("unifi_delete_traffic_matching_list", {
         description: "DESTRUCTIVE: Delete a traffic matching list",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            trafficMatchingListId: zod_1.z.string().describe("Traffic matching list ID"),
-            confirm: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Must be true to execute this destructive action"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            trafficMatchingListId: (0, params_js_1.resourceId)().describe("Traffic matching list ID"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -137,12 +139,12 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, trafficMatchingListId, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the traffic matching list");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will delete the traffic matching list");
         if (guard)
             return guard;
         try {
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`, {});
+                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`);
             const data = await client.delete(`/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`);
             return (0, responses_js_1.formatSuccess)(data);
         }

package/dist/tools/wifi.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerWifiTools = registerWifiTools;
+const node_util_1 = require("node:util");
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 const query_js_1 = require("../utils/query.js");
@@ -8,6 +9,7 @@ const safety_js_1 = require("../utils/safety.js");
 const full_put_js_1 = require("../utils/full-put.js");
 const secrets_js_1 = require("../utils/secrets.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+const params_js_1 = require("../utils/params.js");
 // Request-body fields per broadcast type, from the 11.0.83 POST/PUT schemas.
 // IOT_OPTIMIZED accepts a strict subset of STANDARD.
 const IOT_OPTIMIZED_FIELDS = [
@@ -126,6 +128,41 @@ function checkBody(body, updates) {
         throw new Error(`Missing required fields for type ${String(body.type)}: ${missing.join(", ")}`);
     }
 }
+function securityType(ssid) {
+    const security = ssid.securityConfiguration;
+    return security !== null && typeof security === "object" && "type" in security ? security.type : undefined;
+}
+function isOpen(ssid) {
+    const type = securityType(ssid);
+    return typeof type === "string" && type.toUpperCase() === "OPEN";
+}
+// On an open SSID, these decide who can join and what joining reaches.
+const OPEN_ACCESS_FIELDS = ["network", "hotspotConfiguration", "clientIsolationEnabled", "clientFilteringPolicy"];
+/**
+ * What a WiFi write would open, if anything. before is undefined on create.
+ * An open SSID lets anyone in range join, so switching one on, or changing
+ * what it leads to or how joining is gated, counts as well as the security
+ * type itself.
+ */
+function wifiOpening(before, after) {
+    if (before === undefined)
+        return isOpen(after) ? "This creates an open SSID with no encryption" : undefined;
+    const [from, to] = [securityType(before), securityType(after)];
+    if (!(0, node_util_1.isDeepStrictEqual)(from, to))
+        return `This changes the SSID's security from ${String(from)} to ${String(to)}`;
+    if (!isOpen(after) || after.enabled === false)
+        return undefined;
+    if (before.enabled === false)
+        return "This enables an open SSID with no encryption";
+    const changed = OPEN_ACCESS_FIELDS.filter((field) => !(0, node_util_1.isDeepStrictEqual)(before[field], after[field]));
+    return changed.length > 0
+        ? `This changes who can join an open SSID, or what joining reaches (${changed.join(", ")})`
+        : undefined;
+}
+const confirmSecurity = zod_1.z
+    .boolean()
+    .optional()
+    .describe("Set true to confirm creating or enabling an open SSID, changing an SSID's security type, or changing an open SSID's network, captive portal (hotspotConfiguration), client isolation or client filtering; not needed with dryRun: true");
 const includeSecrets = zod_1.z
     .boolean()
     .optional()
@@ -135,20 +172,20 @@ function registerWifiTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_wifi", {
         description: `List all WiFi broadcasts (SSIDs) at a site. Returns (sparse list view, live-verified on 11.0.83): id, name (SSID), type (STANDARD/IOT_OPTIMIZED), enabled, metadata.origin, network reference (absent on PPSK SSIDs), securityConfiguration.type, broadcastingFrequenciesGHz, hotspotConfiguration (empty object when set). Booleans such as hideName/bandSteeringEnabled/clientIsolationEnabled, the full security configuration and optional configs are only returned by unifi_get_wifi. ${readRedaction} Use for: SSID inventory. For per-AP radio state (channel, txPower), use unifi_get_device on the AP.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -170,8 +207,8 @@ function registerWifiTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_wifi", {
         description: `Get full configuration for a WiFi broadcast (SSID). Returns the list fields plus the booleans (hideName, clientIsolationEnabled, uapsdEnabled, multicastToUnicastConversionEnabled, bandSteeringEnabled, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName, channel2gLockedTo6, dtimPeriod2gLockedTo3), the full securityConfiguration (type, pmfMode, fastRoamingEnabled, saeConfiguration, presharedKeys[] on PPSK SSIDs, …), and optional configs when configured (omitted otherwise): clientFilteringPolicy, blackoutScheduleConfiguration, hotspotConfiguration, mdnsProxyConfiguration, handoffSuggestionsConfiguration, dtimPeriodByFrequencyGHzOverride, broadcastingDeviceFilter, mloEnabled. ${readRedaction}`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            wifiBroadcastId: (0, params_js_1.resourceId)().describe("WiFi Broadcast ID"),
             includeSecrets,
         },
         outputSchema: output_schemas_js_1.getWifiOutputSchema,
@@ -190,7 +227,7 @@ function registerWifiTools(server, client, readOnly = false) {
     server.registerTool("unifi_create_wifi", {
         description: `Create a new WiFi network (SSID). Required for both types: type, name, enabled, securityConfiguration, multicastToUnicastConversionEnabled, clientIsolationEnabled, hideName, uapsdEnabled, channel2gLockedTo6, dtimPeriod2gLockedTo3. STANDARD additionally requires broadcastingFrequenciesGHz, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName; fields marked "STANDARD only" are rejected for IOT_OPTIMIZED (per 11.0.83 docs). The response echo has passphrases redacted. Idempotency: not safe to retry — re-running creates a duplicate SSID.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             ...wifiFields,
             name: zod_1.z.string().min(1).describe("SSID name"),
             enabled: zod_1.z.boolean().describe("Enable the WiFi network"),
@@ -204,22 +241,27 @@ function registerWifiTools(server, client, readOnly = false) {
             uapsdEnabled: zod_1.z.boolean().describe("Enable Unscheduled Automatic Power Save Delivery"),
             channel2gLockedTo6: zod_1.z.boolean().describe("Lock 2.4GHz channel to 6 on all broadcasting devices"),
             dtimPeriod2gLockedTo3: zod_1.z.boolean().describe("Lock 2.4GHz DTIM period to 3"),
+            confirm: confirmSecurity,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.getWifiOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.getWifiOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
-    }, async ({ siteId, dryRun, ...fields }) => {
+    }, async ({ siteId, confirm, dryRun, ...fields }) => {
         try {
             const body = toBodyFields(fields);
             checkBody(body, body);
+            const opening = wifiOpening(undefined, body);
+            const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
+            if (guard)
+                return guard;
             if ((0, secrets_js_1.containsRedacted)(body)) {
                 throw new Error(`securityConfiguration contains "${secrets_js_1.REDACTED}" — a new SSID needs the real passphrase`);
             }
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/wifi/broadcasts`, (0, secrets_js_1.redactSecrets)(body));
+                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/wifi/broadcasts`, (0, secrets_js_1.redactSecrets)(body), opening);
             const data = await client.post(`/sites/${siteId}/wifi/broadcasts`, body);
             return (0, responses_js_1.formatSuccess)((0, secrets_js_1.redactSecrets)(data), { structured: true });
         }
@@ -228,30 +270,37 @@ function registerWifiTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_wifi", {
-        description: `Update an existing WiFi network. Pass only the fields to change. The API's PUT replaces the whole SSID (11.0.83 documents 14 required fields for STANDARD, 10 for IOT_OPTIMIZED), so this tool reads the current SSID, keeps every documented body field, overlays your changes and sends the full body — omitted fields keep their current values instead of being reset. Pass null to clear an optional config (e.g. broadcastingDeviceFilter: null broadcasts from all APs). Passphrases are kept unless you send a new one; "${secrets_js_1.REDACTED}" values are treated as "keep". dryRun shows the merged body (secrets redacted).`,
+        description: `Update an existing WiFi network. Pass only the fields to change. The API's PUT replaces the whole SSID and requires every documented required field, so this tool reads the current SSID, keeps every documented body field, overlays your changes and sends the full body — omitted fields keep their current values instead of being reset. Pass null to clear an optional config (e.g. broadcastingDeviceFilter: null broadcasts from all APs). Top-level objects are replaced whole: to change one security setting, start from the securityConfiguration unifi_get_wifi returns and edit it, since a partial object drops the passphrase or presharedKeys it omits. Passphrases are kept if you omit securityConfiguration or echo its "${secrets_js_1.REDACTED}" values; send a new one to change it. dryRun shows the merged body (secrets redacted).`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            wifiBroadcastId: (0, params_js_1.resourceId)().describe("WiFi Broadcast ID"),
             ...wifiFields,
+            confirm: confirmSecurity,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("Preview the merged PUT body without executing it (still reads the current SSID)"),
         },
-        outputSchema: output_schemas_js_1.getWifiOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.getWifiOutputSchema),
         annotations: safety_js_1.WRITE,
-    }, async ({ siteId, wifiBroadcastId, dryRun, ...fields }) => {
+    }, async ({ siteId, wifiBroadcastId, confirm, dryRun, ...fields }) => {
         try {
             const path = `/sites/${siteId}/wifi/broadcasts/${wifiBroadcastId}`;
-            const current = (0, full_put_js_1.asObject)(await client.get(path), "the current WiFi broadcast");
-            const updates = (0, secrets_js_1.restoreRedacted)(toBodyFields(fields), current);
-            const { allowed } = fieldsForType(updates.type ?? current.type);
-            const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
-            checkBody(body, updates);
-            if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", path, (0, secrets_js_1.redactSecrets)(body));
-            const data = await client.put(path, body);
-            return (0, responses_js_1.formatSuccess)((0, secrets_js_1.redactSecrets)(data), { structured: true });
+            return await (0, full_put_js_1.withResourceLock)(path, async () => {
+                const current = (0, full_put_js_1.asObject)(await client.get(path), "the current WiFi broadcast");
+                const updates = (0, secrets_js_1.restoreRedacted)(toBodyFields(fields), current);
+                const { allowed } = fieldsForType(updates.type ?? current.type);
+                const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
+                checkBody(body, updates);
+                const opening = wifiOpening(current, body);
+                const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
+                if (guard)
+                    return guard;
+                if (dryRun)
+                    return (0, safety_js_1.formatDryRun)("PUT", path, (0, secrets_js_1.redactSecrets)(body), opening);
+                const data = await client.put(path, body);
+                return (0, responses_js_1.formatSuccess)((0, secrets_js_1.redactSecrets)(data), { structured: true });
+            });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
@@ -260,17 +309,14 @@ function registerWifiTools(server, client, readOnly = false) {
     server.registerTool("unifi_delete_wifi", {
         description: "DESTRUCTIVE: Delete a WiFi network — all clients on this SSID will be disconnected",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            wifiBroadcastId: (0, params_js_1.resourceId)().describe("WiFi Broadcast ID"),
             force: zod_1.z
                 .boolean()
                 .optional()
                 .default(false)
                 .describe("Force delete (default: false)"),
-            confirm: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Must be true to execute this destructive action"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -278,7 +324,7 @@ function registerWifiTools(server, client, readOnly = false) {
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, wifiBroadcastId, force, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the WiFi network and disconnect all clients on this SSID");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will delete the WiFi network and disconnect all clients on this SSID");
         if (guard)
             return guard;
         try {

package/dist/utils/full-put.d.ts

@@ -1,8 +1,8 @@
 /**
  * Read-merge-write support for UniFi's full-replacement PUT endpoints.
  *
- * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies)
- * replace the whole resource: required fields must all be present, and some
+ * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies,
+ * ACL rules, DNS policies) replace the whole resource: required fields must all be present, and some
  * optional fields carry meaning when omitted (a missing `dhcpGuarding`
  * disables DHCP guarding; a missing `reportFlowEnabled` reverts to true). A
  * sparse body therefore either fails or silently resets settings.
@@ -21,3 +21,12 @@ export declare function unsupportedFields(updates: JsonObject, allowedFields: re
 export declare function missingFields(body: JsonObject, requiredFields: readonly string[]): string[];
 /** Copy only the defined entries, so optional inputs the caller skipped are not sent. */
 export declare function definedEntries(values: JsonObject): JsonObject;
+/**
+ * Run one read-merge-write cycle at a time per resource. Agents often split
+ * "rename X and enable logging" into parallel calls; unserialised, both read
+ * the old resource and the second PUT silently reverts the first change.
+ * The queue is per process and keyed on the exact path string, so every
+ * writer of a resource (including the firewall-policy PATCH) must lock the
+ * same path.
+ */
+export declare function withResourceLock<T>(path: string, fn: () => Promise<T>): Promise<T>;

package/dist/utils/full-put.js

@@ -2,8 +2,8 @@
 /**
  * Read-merge-write support for UniFi's full-replacement PUT endpoints.
  *
- * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies)
- * replace the whole resource: required fields must all be present, and some
+ * Several Integration API PUTs (WiFi broadcasts, networks, firewall policies,
+ * ACL rules, DNS policies) replace the whole resource: required fields must all be present, and some
  * optional fields carry meaning when omitted (a missing `dhcpGuarding`
  * disables DHCP guarding; a missing `reportFlowEnabled` reverts to true). A
  * sparse body therefore either fails or silently resets settings.
@@ -19,6 +19,7 @@ exports.mergeForPut = mergeForPut;
 exports.unsupportedFields = unsupportedFields;
 exports.missingFields = missingFields;
 exports.definedEntries = definedEntries;
+exports.withResourceLock = withResourceLock;
 function asObject(value, what) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`Expected ${what} to be a JSON object`);
@@ -49,3 +50,25 @@ function missingFields(body, requiredFields) {
 function definedEntries(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
+const resourceQueues = new Map();
+/**
+ * Run one read-merge-write cycle at a time per resource. Agents often split
+ * "rename X and enable logging" into parallel calls; unserialised, both read
+ * the old resource and the second PUT silently reverts the first change.
+ * The queue is per process and keyed on the exact path string, so every
+ * writer of a resource (including the firewall-policy PATCH) must lock the
+ * same path.
+ */
+async function withResourceLock(path, fn) {
+    const previous = resourceQueues.get(path) ?? Promise.resolve();
+    const run = previous.then(fn);
+    const settled = run.then(() => undefined, () => undefined);
+    resourceQueues.set(path, settled);
+    try {
+        return await run;
+    }
+    finally {
+        if (resourceQueues.get(path) === settled)
+            resourceQueues.delete(path);
+    }
+}

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

@@ -1,14 +1,33 @@
 /**
- * Output schemas for high-value read tools (loose strategy: every non-key
- * field optional, every nested object uses .passthrough() to allow
+ * Output schemas for every read tool, and for write tools whose response
+ * echoes the resource (loose strategy: every non-key
+ * field optional, every nested object uses .loose() to allow
  * firmware/hardware-specific fields to flow through unchanged).
  *
  * Verified against UniFi Network API 11.0.83. Where the docs collapse
  * nested arrays/objects (e.g. interfaces.ports[], radios[]), the schema
- * uses passthrough records so the contract doesn't lock to fields we
- * haven't verified.
+ * uses loose records so the contract doesn't lock to fields we
+ * haven't verified. Tools register these raw shapes, and registerAllTools()
+ * publishes each as a loose object (src/tools/index.ts), so fields a schema
+ * does not list never fail client-side validation.
  */
 import { z } from "zod";
+/**
+ * The outputSchema to publish for a tool: always a loose object, whether the
+ * tool passed a raw shape or a Zod object (the SDK accepts both). Wrapping a
+ * Zod object in z.looseObject() would build a broken schema that makes
+ * tools/list throw for every tool.
+ */
+export declare function looseOutput(schema: z.ZodRawShape | z.ZodObject): z.ZodObject;
+export declare function writeResult<T extends z.ZodRawShape>(shape: T): { -readonly [k in keyof { -readonly [P in keyof T]: T[P]; }]: z.ZodOptional<{ -readonly [P in keyof T]: T[P]; }[k]>; } & {
+    readonly dryRun: z.ZodOptional<z.ZodLiteral<true>>;
+    readonly wouldExecute: z.ZodOptional<z.ZodObject<{
+        method: z.ZodString;
+        path: z.ZodString;
+        body: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>;
+    readonly confirmationRequired: z.ZodOptional<z.ZodString>;
+};
 export declare const getInfoOutputSchema: {
     applicationVersion: z.ZodOptional<z.ZodString>;
 };
@@ -709,6 +728,9 @@ export declare const listClientHistoryOutputSchema: {
         status: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
     readonly count: z.ZodNumber;
+    readonly totalCount: z.ZodNumber;
+    readonly limit: z.ZodNumber;
+    readonly truncated: z.ZodBoolean;
     readonly withinHours: z.ZodNumber;
     readonly coverage: z.ZodString;
 };