@owine/unifi-network-mcp 2.14.2 → 2.15.0

package/dist/tools/networks.js

@@ -5,10 +5,106 @@ 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");
+// 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: zod_1.z.string().optional().describe("Firewall zone ID for this network. GATEWAY only."),
+    deviceId: zod_1.z.string().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) {
     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"),
             offset: zod_1.z
@@ -27,7 +123,7 @@ function registerNetworkTools(server, client, readOnly = false) {
             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,7 +138,7 @@ 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"),
@@ -59,7 +155,7 @@ 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"),
@@ -78,9 +174,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"),
+            ...networkFields,
             name: zod_1.z.string().describe("Network name"),
             management: zod_1.z
                 .enum(["UNMANAGED", "GATEWAY", "SWITCH"])
@@ -92,10 +189,6 @@ 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()
@@ -103,11 +196,10 @@ function registerNetworkTools(server, client, readOnly = false) {
         },
         outputSchema: 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 (dryRun)
                 return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/networks`, body);
             const data = await client.post(`/sites/${siteId}/networks`, body);
@@ -118,40 +210,29 @@ 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)"),
+            ...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,
         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;
+            const path = `/sites/${siteId}/networks/${networkId}`;
+            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);
             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, 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) {

package/dist/tools/sites.js

@@ -26,7 +26,7 @@ function registerSiteTools(server, client) {
             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,

package/dist/tools/supporting.js

@@ -8,7 +8,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
 function registerSupportingTools(server, client) {
     server.registerTool("unifi_list_wans", {
-        description: "List WAN interface definitions at a site. Returns: id, name only (verified against 10.6.106 — the Integration API exposes no live link status or throughput rates here). Use for: WAN inventory, multi-WAN topology.",
+        description: "List WAN interface definitions at a site. Returns: id, name only (verified against 11.0.83 — the Integration API exposes no live link status or throughput rates here). Use for: WAN inventory, multi-WAN topology.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -38,7 +38,7 @@ function registerSupportingTools(server, client) {
         }
     });
     server.registerTool("unifi_list_vpn_tunnels", {
-        description: "List site-to-site VPN tunnels (IPsec, WireGuard, OpenVPN site-to-site) at a site. Returns: tunnel definitions per row (per-row schema not rendered in 10.6.106 docs — call to inspect). For roaming client VPN servers, see unifi_list_vpn_servers.",
+        description: "List site-to-site VPN tunnels (IPsec, WireGuard, OpenVPN site-to-site) at a site. Returns: tunnel definitions per row (per-row schema not rendered in 11.0.83 docs and no tunnels to sample live; the older 10.4.57 spec lists id, type (IPSEC/OPENVPN/WIREGUARD), name, metadata.origin/source — call to inspect). For roaming client VPN servers, see unifi_list_vpn_servers.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -57,7 +57,7 @@ function registerSupportingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. metadata.source.isNull()"),
         },
         outputSchema: output_schemas_js_1.listVpnTunnelsOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -72,7 +72,7 @@ function registerSupportingTools(server, client) {
         }
     });
     server.registerTool("unifi_list_vpn_servers", {
-        description: "List VPN servers (roaming/client-access VPNs: WireGuard, OpenVPN, L2TP, Teleport) at a site. Returns: id, type (e.g. WIREGUARD, UID), name, enabled, metadata.origin.",
+        description: "List VPN servers (roaming/client-access VPNs) at a site. Returns: id, type (L2TP, OPENVPN, PPTP, UID, WIREGUARD), name, enabled, metadata.origin.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -91,7 +91,7 @@ function registerSupportingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. type.eq('WIREGUARD')"),
         },
         outputSchema: output_schemas_js_1.listVpnServersOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -125,7 +125,7 @@ function registerSupportingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. name.eq('Default')"),
         },
         outputSchema: output_schemas_js_1.listRadiusProfilesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -140,7 +140,7 @@ function registerSupportingTools(server, client) {
         }
     });
     server.registerTool("unifi_list_device_tags", {
-        description: "List device tags at a site. Tags group APs/switches for selective WiFi broadcast (via broadcastingDeviceFilter on a WiFi network). Returns: id, name, deviceIds[].",
+        description: "List device tags at a site. Tags group APs/switches for selective WiFi broadcast (via broadcastingDeviceFilter on a WiFi network). Returns: id, name, deviceIds[], metadata.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -192,7 +192,7 @@ function registerSupportingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. name.like('Stream*') or id.eq(3). NOTE: totalCount ignores the filter here — page by count"),
         },
         outputSchema: output_schemas_js_1.listDpiCategoriesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -225,7 +225,7 @@ function registerSupportingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. name.like('Net*') or id.eq(3). NOTE: totalCount ignores the filter here — page by count"),
         },
         outputSchema: output_schemas_js_1.listDpiApplicationsOutputSchema,
         annotations: safety_js_1.READ_ONLY,

package/dist/tools/switching.js

@@ -8,7 +8,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.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 10.6.106 docs — call unifi_get_switch_stack to inspect. Use for: identifying stacked switches; individual member configs/stats still come from unifi_get_device.",
+        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"),
             offset: zod_1.z
@@ -27,7 +27,7 @@ function registerSwitchingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. name.like('Core*') or metadata.origin.eq('USER_DEFINED'). Device filters (members.deviceId, units.deviceId) are rejected on 11.0.83"),
         },
         outputSchema: output_schemas_js_1.listSwitchStacksOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -59,7 +59,7 @@ 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[], lags[] (LAGs spanning the domain), metadata.origin.",
+        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"),
             offset: zod_1.z
@@ -78,7 +78,7 @@ function registerSwitchingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. peers.deviceId.contains('<deviceId>')"),
         },
         outputSchema: output_schemas_js_1.listMcLagDomainsOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -110,7 +110,7 @@ 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[], metadata.origin.",
+        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"),
             offset: zod_1.z
@@ -129,7 +129,7 @@ function registerSwitchingTools(server, client) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. type.eq('LOCAL'), members.deviceId.contains('<deviceId>'), switchStackId.isNull()"),
         },
         outputSchema: output_schemas_js_1.listLagsOutputSchema,
         annotations: safety_js_1.READ_ONLY,

package/dist/tools/traffic-matching.js

@@ -6,9 +6,13 @@ 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 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())
+    .min(1)
+    .describe("Non-empty array of tagged item objects, e.g. [{type:'PORT_NUMBER', value:443}]");
 function registerTrafficMatchingTools(server, client, readOnly = false) {
     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[]. Use for: finding the matching-list ID to reference from a firewall policy.",
+        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"),
             offset: zod_1.z
@@ -27,7 +31,7 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression. Only id and name are filterable (type is rejected with HTTP 400). Example: name.like('Web*'). NOTE: totalCount ignores the filter here — page by count"),
         },
         outputSchema: output_schemas_js_1.listTrafficMatchingListsOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -61,17 +65,14 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
     if (readOnly)
         return;
     server.registerTool("unifi_create_traffic_matching_list", {
-        description: "Create a new 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"),
             type: zod_1.z
                 .enum(["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"])
                 .describe("List type"),
             name: zod_1.z.string().min(1).describe("List name"),
-            items: zod_1.z
-                .array(zod_1.z.unknown())
-                .min(1)
-                .describe("List items (ports or IP addresses)"),
+            items: matchingItems,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -92,7 +93,7 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_traffic_matching_list", {
-        description: "Update a 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"),
@@ -100,7 +101,7 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
                 .enum(["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"])
                 .describe("List type"),
             name: zod_1.z.string().min(1).describe("List name"),
-            items: zod_1.z.array(zod_1.z.unknown()).min(1).describe("List items"),
+            items: matchingItems,
             dryRun: zod_1.z
                 .boolean()
                 .optional()