@owine/unifi-network-mcp 2.14.2 → 3.0.0

package/dist/tools/hotspot.js

@@ -6,26 +6,28 @@ 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 VOUCHER_BATCH_WITHOUT_CONFIRM = 10;
 function registerHotspotTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_vouchers", {
         description: "List hotspot/guest-portal vouchers at a site. Returns: id, code, name, createdAt, activatedAt (when first guest used it), expiresAt, timeLimitMinutes, dataUsageLimitMBytes, rxRateLimitKbps, txRateLimitKbps, authorizedGuestLimit, authorizedGuestCount, expired. Use filter like 'expired.eq(true)' to bulk-find stale vouchers.",
         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()
                 .default(0)
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(1000)
                 .optional()
-                .default(100)
-                .describe("Number of records to return (default: 100, max: 1000)"),
+                .default(25)
+                .describe("Number of records to return"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -46,8 +48,8 @@ function registerHotspotTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_voucher", {
         description: "Get a specific hotspot voucher by ID (same fields as the list entry).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            voucherId: zod_1.z.string().describe("Voucher ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            voucherId: (0, params_js_1.resourceId)().describe("Voucher ID"),
         },
         outputSchema: output_schemas_js_1.voucherOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -63,9 +65,9 @@ function registerHotspotTools(server, client, readOnly = false) {
     if (readOnly)
         return;
     server.registerTool("unifi_create_voucher", {
-        description: "Create one or more hotspot vouchers (use count for batch creation, up to 1000 at once). Returns: array of created vouchers with their generated codes. Idempotency: not safe to retry — each call mints fresh codes.",
+        description: `Create one or more hotspot vouchers (use count for batch creation; more than ${VOUCHER_BATCH_WITHOUT_CONFIRM} at once needs confirm: true). Returns: vouchers[] — the created vouchers with their generated codes. Idempotency: not safe to retry — each call mints fresh codes.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             name: zod_1.z
                 .string()
                 .describe("Voucher note/name (duplicated across all generated vouchers)"),
@@ -110,21 +112,30 @@ function registerHotspotTools(server, client, readOnly = false) {
                 .max(100000)
                 .optional()
                 .describe("Upload rate limit in kbps (2-100000)"),
+            confirm: zod_1.z
+                .boolean()
+                .optional()
+                .describe(`Set true to confirm creating more than ${VOUCHER_BATCH_WITHOUT_CONFIRM} vouchers at once; not needed with dryRun: true`),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.createVouchersOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.createVouchersOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
-    }, async ({ siteId, name, timeLimitMinutes, count, authorizedGuestLimit, dataUsageLimitMBytes, rxRateLimitKbps, txRateLimitKbps, dryRun, }) => {
+    }, async ({ siteId, name, timeLimitMinutes, count, authorizedGuestLimit, dataUsageLimitMBytes, rxRateLimitKbps, txRateLimitKbps, confirm, dryRun, }) => {
+        // Each voucher is a guest credential; a large batch is a lot of access
+        // to hand out on one unchecked call.
+        const opening = count > VOUCHER_BATCH_WITHOUT_CONFIRM ? `This creates ${count} guest access codes` : undefined;
+        const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
+        if (guard)
+            return guard;
         try {
             const body = {
                 name,
                 timeLimitMinutes,
+                count,
             };
-            if (count !== undefined)
-                body.count = count;
             if (authorizedGuestLimit !== undefined)
                 body.authorizedGuestLimit = authorizedGuestLimit;
             if (dataUsageLimitMBytes !== undefined)
@@ -134,7 +145,7 @@ function registerHotspotTools(server, client, readOnly = false) {
             if (txRateLimitKbps !== undefined)
                 body.txRateLimitKbps = txRateLimitKbps;
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/hotspot/vouchers`, body);
+                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/hotspot/vouchers`, body, opening);
             const data = await client.post(`/sites/${siteId}/hotspot/vouchers`, body);
             return (0, responses_js_1.formatSuccess)(data, { structured: true });
         }
@@ -145,12 +156,9 @@ function registerHotspotTools(server, client, readOnly = false) {
     server.registerTool("unifi_delete_voucher", {
         description: "DESTRUCTIVE: Delete a hotspot voucher. Returns: vouchersDeleted (count of vouchers removed).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            voucherId: zod_1.z.string().describe("Voucher 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"),
+            voucherId: (0, params_js_1.resourceId)().describe("Voucher ID"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -158,7 +166,7 @@ function registerHotspotTools(server, client, readOnly = false) {
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, voucherId, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will permanently delete the voucher");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will permanently delete the voucher");
         if (guard)
             return guard;
         try {
@@ -173,16 +181,15 @@ function registerHotspotTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_bulk_delete_vouchers", {
-        description: "DESTRUCTIVE: Bulk delete hotspot vouchers based on filter criteria. Returns: vouchersDeleted (count of vouchers removed).",
+        description: "DESTRUCTIVE: Bulk delete hotspot vouchers matching a filter. The dry run shows only the request, not which vouchers match: call unifi_list_vouchers with the same filter first. Returns: vouchersDeleted (count of vouchers removed).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             filter: zod_1.z
                 .string()
-                .describe("Required filter expression (e.g., 'expired.eq(true)', name.like('guest*'))"),
-            confirm: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Must be true to execute this destructive action"),
+                .trim()
+                .min(1)
+                .describe("Required filter expression, e.g. expired.eq(true) or name.like('guest*')"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -191,7 +198,7 @@ function registerHotspotTools(server, client, readOnly = false) {
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, filter, confirm, dryRun }) => {
         try {
-            const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete all vouchers matching the filter");
+            const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will delete all vouchers matching the filter");
             if (guard)
                 return guard;
             const query = (0, query_js_1.buildQuery)({ filter });

package/dist/tools/index.d.ts

@@ -1,3 +1,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { NetworkClient } from "../client.js";
-export declare function registerAllTools(server: McpServer, client: NetworkClient, readOnly?: boolean): void;
+import { type WanPolicy } from "../utils/wan-exposure.js";
+import type { WriteLog } from "../write-log.js";
+export interface ToolOptions {
+    /** The write tools to register (UNIFI_NETWORK_WRITE_TOOLS); undefined registers them all. */
+    writeTools?: readonly string[];
+    /** WAN-exposure refusals (UNIFI_NETWORK_ALLOW_WAN_EXPOSURE, UNIFI_NETWORK_WAN_ZONE_IDS); on by default. */
+    wan?: WanPolicy;
+    /** UNIFI_NETWORK_WRITE_LOG; every write tool call appends a line. */
+    writeLog?: WriteLog;
+}
+export declare function registerAllTools(server: McpServer, client: NetworkClient, readOnly?: boolean, options?: ToolOptions): void;
+/** "unifi_list_mc_lag_domains" → "List MC-LAG domains". */
+export declare function toolTitle(name: string): string;

package/dist/tools/index.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAllTools = registerAllTools;
+exports.toolTitle = toolTitle;
+const client_js_1 = require("../client.js");
+const output_schemas_js_1 = require("../utils/output-schemas.js");
+const write_tools_js_1 = require("../write-tools.js");
+const wan_exposure_js_1 = require("../utils/wan-exposure.js");
 const system_js_1 = require("./system.js");
 const sites_js_1 = require("./sites.js");
 const devices_js_1 = require("./devices.js");
@@ -15,19 +20,73 @@ const dns_policies_js_1 = require("./dns-policies.js");
 const traffic_matching_js_1 = require("./traffic-matching.js");
 const switching_js_1 = require("./switching.js");
 const supporting_js_1 = require("./supporting.js");
-function registerAllTools(server, client, readOnly = false) {
+function registerAllTools(server, client, readOnly = false, options = {}) {
+    server = instrumentTools(server, options);
+    const wan = options.wan ?? wan_exposure_js_1.DEFAULT_WAN_POLICY;
     (0, system_js_1.registerSystemTools)(server, client);
     (0, sites_js_1.registerSiteTools)(server, client);
     (0, devices_js_1.registerDeviceTools)(server, client, readOnly);
     (0, clients_js_1.registerClientTools)(server, client, readOnly);
     (0, client_history_js_1.registerClientHistoryTools)(server, client);
-    (0, networks_js_1.registerNetworkTools)(server, client, readOnly);
+    (0, networks_js_1.registerNetworkTools)(server, client, readOnly, wan);
     (0, wifi_js_1.registerWifiTools)(server, client, readOnly);
     (0, hotspot_js_1.registerHotspotTools)(server, client, readOnly);
-    (0, firewall_js_1.registerFirewallTools)(server, client, readOnly);
+    (0, firewall_js_1.registerFirewallTools)(server, client, readOnly, wan);
     (0, acl_js_1.registerAclTools)(server, client, readOnly);
     (0, dns_policies_js_1.registerDnsPolicyTools)(server, client, readOnly);
-    (0, traffic_matching_js_1.registerTrafficMatchingTools)(server, client, readOnly);
+    (0, traffic_matching_js_1.registerTrafficMatchingTools)(server, client, readOnly, wan);
     (0, switching_js_1.registerSwitchingTools)(server, client);
     (0, supporting_js_1.registerSupportingTools)(server, client);
 }
+/**
+ * A view of server that applies these rules to every tool it registers, so no
+ * tool module can forget them:
+ *
+ * - Handlers run with their call's abort signal in scope, so NetworkClient
+ *   aborts the controller request when the MCP client cancels the call. The
+ *   SDK passes that signal in `extra`, the handler's last argument.
+ * - Each tool gets a human-readable title derived from its name.
+ * - A write tool the operator did not enable (UNIFI_NETWORK_WRITE_TOOLS) is
+ *   not registered at all. A write tool missing from WRITE_TOOL_GROUPS, or a
+ *   read tool listed there, is a bug: registration throws.
+ * - With a write log, every write tool call is recorded in it.
+ * - The outputSchema is published as a loose object. The SDK client validates
+ *   structuredContent against the published JSON Schema, and tools pass the
+ *   controller's response through; a raw shape publishes
+ *   additionalProperties: false, so the first field a firmware update added
+ *   would make the tool fail for every client that validates.
+ */
+function instrumentTools(server, { writeTools, writeLog }) {
+    const registerTool = (name, config, handler) => {
+        const write = config.annotations?.readOnlyHint === false;
+        if (write !== write_tools_js_1.WRITE_TOOLS.includes(name)) {
+            throw new Error(`${name} is ${write ? "a write tool missing from" : "a read tool listed in"} WRITE_TOOL_GROUPS (src/write-tools.ts)`);
+        }
+        if (write && writeTools !== undefined && !writeTools.includes(name))
+            return undefined;
+        return server.registerTool(name, {
+            ...config,
+            title: config.title ?? toolTitle(name),
+            ...(config.outputSchema ? { outputSchema: (0, output_schemas_js_1.looseOutput)(config.outputSchema) } : {}),
+        }, ((...args) => {
+            const extra = args.at(-1);
+            const signal = extra?.signal instanceof AbortSignal ? extra.signal : undefined;
+            const run = () => (0, client_js_1.withCallSignal)(signal, () => handler(...args));
+            return write && writeLog ? writeLog.record(name, args[0], run) : run();
+        }));
+    };
+    return new Proxy(server, {
+        get: (target, prop, receiver) => prop === "registerTool" ? registerTool : Reflect.get(target, prop, receiver),
+    });
+}
+// Words in tool names that read wrongly in plain sentence case.
+const TITLE_WORDS = {
+    acl: "ACL", dns: "DNS", dpi: "DPI", vpn: "VPN", radius: "RADIUS",
+    wifi: "WiFi", wan: "WAN", wans: "WANs", lag: "LAG", lags: "LAGs", mc: "MC",
+};
+/** "unifi_list_mc_lag_domains" → "List MC-LAG domains". */
+function toolTitle(name) {
+    const words = name.replace(/^unifi_/, "").split("_").map((word) => TITLE_WORDS[word] ?? word);
+    const title = words.join(" ").replace("MC LAG", "MC-LAG");
+    return title.charAt(0).toUpperCase() + title.slice(1);
+}

package/dist/tools/networks.d.ts

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

package/dist/tools/networks.js

@@ -5,29 +5,127 @@ const zod_1 = require("zod");
 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 full_put_js_1 = require("../utils/full-put.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
-function registerNetworkTools(server, client, readOnly = false) {
+const params_js_1 = require("../utils/params.js");
+const wan_exposure_js_1 = require("../utils/wan-exposure.js");
+// Request-body fields per management type, from the 11.0.83 POST/PUT schemas.
+const COMMON_FIELDS = ["management", "name", "enabled", "vlanId", "dhcpGuarding"];
+const COMMON_REQUIRED = ["management", "name", "enabled", "vlanId"];
+const NETWORK_VARIANTS = {
+    UNMANAGED: { allowed: COMMON_FIELDS, required: COMMON_REQUIRED },
+    GATEWAY: {
+        allowed: [
+            ...COMMON_FIELDS,
+            "isolationEnabled",
+            "cellularBackupEnabled",
+            "zoneId",
+            "internetAccessEnabled",
+            "mdnsForwardingEnabled",
+            "ipv4Configuration",
+            "ipv6Configuration",
+        ],
+        required: [
+            ...COMMON_REQUIRED,
+            "isolationEnabled",
+            "cellularBackupEnabled",
+            "internetAccessEnabled",
+            "ipv4Configuration",
+        ],
+    },
+    SWITCH: {
+        allowed: [
+            ...COMMON_FIELDS,
+            "isolationEnabled",
+            "cellularBackupEnabled",
+            "deviceId",
+            "ipv4Configuration",
+        ],
+        required: [
+            ...COMMON_REQUIRED,
+            "isolationEnabled",
+            "cellularBackupEnabled",
+            "deviceId",
+            "ipv4Configuration",
+        ],
+    },
+};
+const NETWORK_VARIANTS_DOC = "all types take name, enabled, vlanId, optional dhcpGuarding (omitted or null = disabled). GATEWAY (routed by the UniFi gateway) also requires isolationEnabled, cellularBackupEnabled, internetAccessEnabled, ipv4Configuration (gateway-managed subnet + DHCP), optional zoneId, mdnsForwardingEnabled, ipv6Configuration. SWITCH (routed by an L3 switch) also requires isolationEnabled, cellularBackupEnabled, deviceId (the L3 switch), ipv4Configuration (switch-managed).";
+function fieldsForManagement(management) {
+    if (management === "UNMANAGED" || management === "GATEWAY" || management === "SWITCH") {
+        return NETWORK_VARIANTS[management];
+    }
+    throw new Error(`Unsupported network management type: ${String(management)}`);
+}
+function checkNetworkBody(body, updates) {
+    const { allowed, required } = fieldsForManagement(body.management);
+    const rejected = (0, full_put_js_1.unsupportedFields)(updates, allowed);
+    if (rejected.length > 0) {
+        throw new Error(`Fields not accepted for management ${String(body.management)}: ${rejected.join(", ")}`);
+    }
+    const missing = (0, full_put_js_1.missingFields)(body, required);
+    if (missing.length > 0) {
+        throw new Error(`Missing required fields for management ${String(body.management)}: ${missing.join(", ")}`);
+    }
+}
+const config = (description) => zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).describe(description);
+// Every body field as an optional input. Create tightens the common fields to
+// required; update keeps them optional and fills gaps from the current network.
+const networkFields = {
+    name: zod_1.z.string().optional().describe("Network name"),
+    management: zod_1.z
+        .enum(["UNMANAGED", "GATEWAY", "SWITCH"])
+        .optional()
+        .describe("Network management type"),
+    enabled: zod_1.z.boolean().optional().describe("Enable the network"),
+    vlanId: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(4009)
+        .optional()
+        .describe("VLAN ID (1 for the default network, 2-4009 for additional networks)"),
+    dhcpGuarding: config("DHCP Guarding settings (trustedDhcpServerIpAddresses). Omitted or null = disabled.")
+        .nullable()
+        .optional(),
+    isolationEnabled: zod_1.z.boolean().optional().describe("Isolate this network from all other networks. GATEWAY/SWITCH."),
+    cellularBackupEnabled: zod_1.z.boolean().optional().describe("Allow cellular data when WAN connection(s) are down. GATEWAY/SWITCH."),
+    internetAccessEnabled: zod_1.z.boolean().optional().describe("Allow internet access for devices on this network. GATEWAY only."),
+    mdnsForwardingEnabled: zod_1.z
+        .boolean()
+        .nullable()
+        .optional()
+        .describe("Participate in mDNS forwarding; null = use the site mDNS default. GATEWAY only."),
+    zoneId: (0, params_js_1.resourceId)().optional().describe("Firewall zone ID for this network. GATEWAY only."),
+    deviceId: (0, params_js_1.resourceId)().optional().describe("ID of the L3 switching capable device that manages this network. SWITCH only."),
+    ipv4Configuration: config("IPv4 configuration (hostIpAddress, prefixLength, dhcpConfiguration, …) — copy the shape from unifi_get_network. GATEWAY/SWITCH.")
+        .optional(),
+    ipv6Configuration: config("IPv6 configuration (interfaceType, clientAddressAssignment, routerAdvertisement, …); omitted or null = IPv6 not configured. GATEWAY only.")
+        .nullable()
+        .optional(),
+};
+function registerNetworkTools(server, client, readOnly = false, wan = wan_exposure_js_1.DEFAULT_WAN_POLICY) {
     server.registerTool("unifi_list_networks", {
-        description: "List all networks (VLANs/LAN segments) at a site. Returns: id, name, management (UNMANAGED/GATEWAY/SWITCH), enabled, vlanId, default (true for the default network), zoneId (the firewall zone the network sits in), dhcpGuarding, metadata.origin. NOTE: the list view is sparse — for subnet/DHCP/NTP detail (ipv4Configuration/ipv6Configuration), call unifi_get_network on a specific id. Use for: VLAN inventory; pair with unifi_get_network_references to find what consumes a network.",
+        description: "List all networks (VLANs/LAN segments) at a site. Returns: id, name, management (UNMANAGED/GATEWAY/SWITCH), enabled, vlanId, default (true for the default network), zoneId (the firewall zone the network sits in), dhcpGuarding (only present when enabled), metadata.origin (+ metadata.configurable on the system-defined default network). NOTE: the list view is sparse — for subnet/DHCP/NTP detail (ipv4Configuration/ipv6Configuration), call unifi_get_network on a specific id. Use for: VLAN inventory; pair with unifi_get_network_references to find what consumes a network.",
         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()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. vlanId.eq(20)"),
         },
         outputSchema: output_schemas_js_1.listNetworksOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -42,10 +140,10 @@ function registerNetworkTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_network", {
-        description: "Get a network/VLAN by ID. Returns the list fields PLUS (live-verified) isolationEnabled, internetAccessEnabled, mdnsForwardingEnabled, cellularBackupEnabled, a full ipv4Configuration object (autoScaleEnabled, hostIpAddress, prefixLength, dhcpConfiguration with mode/ipAddressRange/leaseTimeSeconds/domainName/pingConflictDetectionEnabled/ntpServerIpAddresses), and an ipv6Configuration object (interfaceType, clientAddressAssignment, routerAdvertisement, hostIpAddress, prefixLength). NOTE: subnet/DHCP detail appears here at get-by-id but NOT in unifi_list_networks (sparse list view).",
+        description: "Get a network/VLAN by ID. Returns the list fields PLUS (live-verified) isolationEnabled, internetAccessEnabled, mdnsForwardingEnabled, cellularBackupEnabled, a full ipv4Configuration object (autoScaleEnabled, hostIpAddress, prefixLength, dhcpConfiguration with mode/ipAddressRange/leaseTimeSeconds/domainName/pingConflictDetectionEnabled/ntpServerIpAddresses — which may contain empty-string entries), and an ipv6Configuration object when IPv6 is configured (interfaceType, clientAddressAssignment, routerAdvertisement, hostIpAddress, prefixLength). NOTE: subnet/DHCP detail appears here at get-by-id but NOT in unifi_list_networks (sparse list view).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            networkId: zod_1.z.string().describe("Network ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            networkId: (0, params_js_1.resourceId)().describe("Network ID"),
         },
         outputSchema: output_schemas_js_1.networkOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -59,10 +157,10 @@ function registerNetworkTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_network_references", {
-        description: "Get all objects that reference this network (WiFi broadcasts, firewall zones, etc.). Returns: { referenceResources: [...] }. Use before deleting a network to find dependencies that need to be re-pointed or removed.",
+        description: "Get all objects that reference this network. Returns: { referenceResources: [{ resourceType (e.g. WIFI), referenceCount, references: [{ referenceId }] }] }. Use before deleting a network to find dependencies that need to be re-pointed or removed. NOTE: on 11.0.83 the controller returns HTTP 500 (api.unexpected-error) for many networks — observed on the default network and on networks used by PPSK keys. On a 500, fall back to unifi_list_wifi + unifi_get_wifi (network.networkId and securityConfiguration.presharedKeys[].network.networkId) and unifi_list_firewall_zones (networkIds).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            networkId: zod_1.z.string().describe("Network ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            networkId: (0, params_js_1.resourceId)().describe("Network ID"),
         },
         outputSchema: output_schemas_js_1.getNetworkReferencesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -78,9 +176,10 @@ function registerNetworkTools(server, client, readOnly = false) {
     if (readOnly)
         return;
     server.registerTool("unifi_create_network", {
-        description: "Create a new VLAN/network. management=GATEWAY means routed via UDM/UXG; SWITCH means VLAN-only; UNMANAGED means external. Idempotency: not safe to retry — re-running creates duplicates.",
+        description: `Create a new VLAN/network. The body depends on management (per 11.0.83 docs): ${NETWORK_VARIANTS_DOC} Idempotency: not safe to retry — re-running creates duplicates.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            ...networkFields,
             name: zod_1.z.string().describe("Network name"),
             management: zod_1.z
                 .enum(["UNMANAGED", "GATEWAY", "SWITCH"])
@@ -92,22 +191,22 @@ function registerNetworkTools(server, client, readOnly = false) {
                 .min(1)
                 .max(4009)
                 .describe("VLAN ID (1 for default, 2+ for additional)"),
-            dhcpGuarding: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("DHCP Guarding settings (trustedDhcpServerIpAddresses)"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.networkOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.networkOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
-    }, async ({ siteId, name, management, enabled, vlanId, dhcpGuarding, dryRun }) => {
+    }, async ({ siteId, dryRun, ...fields }) => {
         try {
-            const body = { name, management, enabled, vlanId };
-            if (dhcpGuarding !== undefined)
-                body.dhcpGuarding = dhcpGuarding;
+            const body = (0, full_put_js_1.definedEntries)(fields);
+            checkNetworkBody(body, body);
+            if (typeof body.zoneId === "string") {
+                const exposure = await new wan_exposure_js_1.WanExposure(client, wan, siteId).networkZone(body.zoneId);
+                if (exposure)
+                    return (0, wan_exposure_js_1.wanRefusal)(exposure, "POST", `/sites/${siteId}/networks`);
+            }
             if (dryRun)
                 return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/networks`, body);
             const data = await client.post(`/sites/${siteId}/networks`, body);
@@ -118,41 +217,39 @@ function registerNetworkTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_network", {
-        description: "Update an existing network",
+        description: `Update an existing network. Pass only the fields to change. The API's PUT replaces the whole network — omitting dhcpGuarding disables DHCP guarding, and GATEWAY networks must resend their full ipv4Configuration — so this tool reads the current network, keeps every documented body field for its management type, overlays your changes and sends the full body. Pass null to clear an optional field (e.g. ipv6Configuration: null removes IPv6). Nested objects such as ipv4Configuration are replaced whole, not deep-merged: read them with unifi_get_network and send the complete object. Variants: ${NETWORK_VARIANTS_DOC} dryRun shows the merged body.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            networkId: zod_1.z.string().describe("Network ID"),
-            name: zod_1.z.string().describe("Network name"),
-            management: zod_1.z
-                .enum(["UNMANAGED", "GATEWAY", "SWITCH"])
-                .describe("Network management type"),
-            enabled: zod_1.z.boolean().describe("Enable the network"),
-            vlanId: zod_1.z
-                .number()
-                .int()
-                .min(1)
-                .max(4009)
-                .describe("VLAN ID (1-4009)"),
-            dhcpGuarding: zod_1.z
-                .record(zod_1.z.string(), zod_1.z.unknown())
-                .optional()
-                .describe("DHCP Guarding settings (trustedDhcpServerIpAddresses)"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            networkId: (0, params_js_1.resourceId)().describe("Network ID"),
+            ...networkFields,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
-                .describe("Preview this action without executing it"),
+                .describe("Preview the merged PUT body without executing it (still reads the current network)"),
         },
-        outputSchema: output_schemas_js_1.networkOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.networkOutputSchema),
         annotations: safety_js_1.WRITE,
-    }, async ({ siteId, networkId, name, management, enabled, vlanId, dhcpGuarding, dryRun }) => {
+    }, async ({ siteId, networkId, dryRun, ...fields }) => {
         try {
-            const body = { name, management, enabled, vlanId };
-            if (dhcpGuarding !== undefined)
-                body.dhcpGuarding = dhcpGuarding;
-            if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/networks/${networkId}`, body);
-            const data = await client.put(`/sites/${siteId}/networks/${networkId}`, body);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            const path = `/sites/${siteId}/networks/${networkId}`;
+            return await (0, full_put_js_1.withResourceLock)(path, async () => {
+                const current = (0, full_put_js_1.asObject)(await client.get(path), "the current network");
+                const updates = (0, full_put_js_1.definedEntries)(fields);
+                const { allowed } = fieldsForManagement(updates.management ?? current.management);
+                const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
+                checkNetworkBody(body, updates);
+                const currentZoneId = typeof current.zoneId === "string" ? current.zoneId : undefined;
+                // Zone IDs are compared without case, as the WAN check compares them.
+                if (typeof body.zoneId === "string" && body.zoneId.toLowerCase() !== currentZoneId?.toLowerCase()) {
+                    const exposure = await new wan_exposure_js_1.WanExposure(client, wan, siteId).networkZone(body.zoneId, currentZoneId);
+                    if (exposure)
+                        return (0, wan_exposure_js_1.wanRefusal)(exposure, "PUT", path);
+                }
+                if (dryRun)
+                    return (0, safety_js_1.formatDryRun)("PUT", path, body);
+                const data = await client.put(path, body);
+                return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
@@ -161,17 +258,14 @@ function registerNetworkTools(server, client, readOnly = false) {
     server.registerTool("unifi_delete_network", {
         description: "DESTRUCTIVE: Delete a network — all clients on this network will be disconnected",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            networkId: zod_1.z.string().describe("Network ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            networkId: (0, params_js_1.resourceId)().describe("Network 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()
@@ -179,7 +273,7 @@ function registerNetworkTools(server, client, readOnly = false) {
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, networkId, force, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the network and disconnect all clients on it");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will delete the network and disconnect all clients on it");
         if (guard)
             return guard;
         try {

package/dist/tools/sites.js

@@ -15,18 +15,18 @@ function registerSiteTools(server, client) {
                 .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()
-                .describe("Filter expression (e.g., name.like('office*'))"),
+                .describe("Filter expression. Filterable: id, internalReference, name — eq/ne/in/notIn only (like is rejected). Example: name.eq('Default')"),
         },
         outputSchema: output_schemas_js_1.listSitesOutputSchema,
         annotations: safety_js_1.READ_ONLY,