@owine/unifi-network-mcp 2.14.2 → 2.15.0

package/README.md

@@ -76,12 +76,14 @@ This server provides layered safety controls for responsible operation:
 - **Destructive tool warnings** — Tools that delete or irreversibly modify resources have descriptions prefixed with `DESTRUCTIVE:` to clearly signal risk
 - **Confirmation parameter** — Every tool marked `DESTRUCTIVE:` (all 10 of them, including `unifi_remove_device` and `unifi_bulk_delete_vouchers`) requires an explicit `confirm: true` parameter for the call to succeed
 - **Dry-run support** — All 33 write tools accept an optional `dryRun: true` parameter that returns a preview of the HTTP request (method, path, body) without making any changes
+- **Safe partial updates** — The UniFi PUT endpoints for WiFi broadcasts, networks, firewall policies and DNS policies replace the whole resource, and some fields reset when omitted (a missing `dhcpGuarding` disables DHCP guarding). Their update tools read the current resource, keep every documented body field, and overlay only what you pass, so a one-field change never resets the rest. Pass `null` to clear an optional field. The dry-run preview shows the merged body (the read still happens)
+- **Secret redaction** — WiFi passphrases (including per-VLAN PPSK keys) are returned as `[REDACTED]` unless the caller passes `includeSecrets: true` to `unifi_list_wifi` / `unifi_get_wifi`. Write-tool echoes and dry-run previews are always redacted, and an update that echoes back `[REDACTED]` keeps the stored passphrase
 
 ## Structured Output
 
 60 of the 76 tools (all 43 read tools, plus the 17 write tools whose API responses return the affected resource) declare an MCP `outputSchema` and return `structuredContent` alongside the usual text content. Clients that understand structured output get typed, machine-readable results instead of parsing JSON out of a text blob.
 
-The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi Network API 10.6.106. They deliberately use a **loose strategy**: every non-key field is optional and nested objects use `.passthrough()`, so firmware- and hardware-specific fields flow through unchanged rather than being stripped or triggering a validation error. This keeps the contract stable across console versions and hardware models.
+The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi Network API 11.0.83. They deliberately use a **loose strategy**: every non-key field is optional and nested objects use `.passthrough()`, so firmware- and hardware-specific fields flow through unchanged rather than being stripped or triggering a validation error. This keeps the contract stable across console versions and hardware models.
 
 ## Tools (76 total)
 
@@ -127,17 +129,17 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_list_networks` | List all networks at a site |
 | `unifi_get_network` | Get a specific network by ID |
 | `unifi_get_network_references` | Get references to a network (WiFi, firewall zones, etc.) |
-| `unifi_create_network` | Create a new network |
-| `unifi_update_network` | Update an existing network |
+| `unifi_create_network` | Create a new network (UNMANAGED, GATEWAY or SWITCH body) |
+| `unifi_update_network` | Update an existing network — partial changes are merged into the full PUT body |
 | `unifi_delete_network` | **DESTRUCTIVE:** Delete a network — disconnects all clients |
 
 ### WiFi (5)
 | Tool | Description |
 |---|---|
-| `unifi_list_wifi` | List all WiFi broadcasts (SSIDs) at a site |
-| `unifi_get_wifi` | Get a specific WiFi network by ID |
+| `unifi_list_wifi` | List all WiFi broadcasts (SSIDs) at a site (passphrases redacted by default) |
+| `unifi_get_wifi` | Get a specific WiFi network by ID (passphrases redacted unless `includeSecrets: true`) |
 | `unifi_create_wifi` | Create a new WiFi network (SSID) |
-| `unifi_update_wifi` | Update an existing WiFi network |
+| `unifi_update_wifi` | Update an existing WiFi network — partial changes are merged into the full PUT body |
 | `unifi_delete_wifi` | **DESTRUCTIVE:** Delete a WiFi network — disconnects all clients |
 
 ### Hotspot Vouchers (5)
@@ -160,8 +162,8 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_list_firewall_policies` | List all firewall policies at a site |
 | `unifi_get_firewall_policy` | Get a specific firewall policy by ID |
 | `unifi_create_firewall_policy` | Create a new firewall policy |
-| `unifi_update_firewall_policy` | Update a firewall policy |
-| `unifi_patch_firewall_policy` | Partially update a firewall policy (e.g. toggle logging) |
+| `unifi_update_firewall_policy` | Update a firewall policy — partial changes are merged into the full PUT body |
+| `unifi_patch_firewall_policy` | Partially update a firewall policy (toggle logging or Insights flow reporting) |
 | `unifi_delete_firewall_policy` | **DESTRUCTIVE:** Delete a firewall policy |
 | `unifi_get_firewall_policy_ordering` | Get user-defined firewall policy ordering for a zone pair |
 | `unifi_reorder_firewall_policies` | Reorder user-defined firewall policies for a zone pair |
@@ -192,8 +194,8 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 |---|---|
 | `unifi_list_dns_policies` | List all DNS policies at a site |
 | `unifi_get_dns_policy` | Get a specific DNS policy by ID |
-| `unifi_create_dns_policy` | Create a new DNS policy |
-| `unifi_update_dns_policy` | Update a DNS policy |
+| `unifi_create_dns_policy` | Create a DNS policy of any type (A, AAAA, CNAME, MX, TXT, SRV, FORWARD_DOMAIN) |
+| `unifi_update_dns_policy` | Update a DNS policy — partial changes are merged into the full PUT body |
 | `unifi_delete_dns_policy` | **DESTRUCTIVE:** Delete a DNS policy |
 
 ### Traffic Matching (5)

package/dist/tools/acl.js

@@ -59,7 +59,7 @@ function registerAclTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_acl_rule_ordering", {
-        description: "Get the evaluation order of user-defined ACL rules. Returns: orderedAclRuleIds[]. Rules higher in the list win.",
+        description: "Get the evaluation order of user-defined ACL rules. Returns: orderedAclRuleIds[] — rules are evaluated in list order.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
         },
@@ -103,7 +103,7 @@ function registerAclTools(server, client, readOnly = false) {
             enforcingDeviceFilter: zod_1.z
                 .unknown()
                 .optional()
-                .describe("IDs of the Switch-capable devices used to enforce the ACL rule. When null/omitted, the rule is provisioned to all switches on the site"),
+                .describe("Device filter object (with a type discriminator) selecting the switch-capable devices that enforce the rule. When null/omitted, the rule is provisioned to all switches on the site"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -161,7 +161,7 @@ function registerAclTools(server, client, readOnly = false) {
             enforcingDeviceFilter: zod_1.z
                 .unknown()
                 .optional()
-                .describe("IDs of the Switch-capable devices used to enforce the ACL rule. When null/omitted, the rule is provisioned to all switches on the site"),
+                .describe("Device filter object (with a type discriminator) selecting the switch-capable devices that enforce the rule. When null/omitted, the rule is provisioned to all switches on the site"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()

package/dist/tools/client-history.js

@@ -9,7 +9,7 @@ const siteReference = zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,64}$/)
     .describe("Site internalReference from unifi_list_sites (often default), not the Integration API UUID");
 function registerClientHistoryTools(server, client) {
     server.registerTool("unifi_list_client_history", {
-        description: "List historical/offline client inventory using the controller v2 API. Includes names, MACs, first_seen and last_seen epoch seconds when available. This is inventory, not session history; use unifi_list_client_sessions for past connections. Requires controller history API-key support; errors never mean zero activity. Retention depends on the controller.",
+        description: "List historical/offline client inventory using the controller v2 API. Returns OFFLINE clients only — currently connected clients are excluded, so merge with unifi_list_clients for a full inventory. Includes names, MACs, first_seen and last_seen epoch seconds when available. This is inventory, not session history; use unifi_list_client_sessions for past connections. Requires controller history API-key support; errors never mean zero activity. Retention depends on the controller.",
         inputSchema: { siteReference, withinHours: zod_1.z.number().int().min(1).max(8760).default(168).describe("Lookback in hours, up to one year; does not extend controller retention") },
         outputSchema: output_schemas_js_1.listClientHistoryOutputSchema,
         annotations: safety_js_1.READ_ONLY,

package/dist/tools/clients.js

@@ -8,7 +8,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
 function registerClientTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_clients", {
-        description: "List currently connected clients at a site. Returns per client: id, name, type (WIRED/WIRELESS/VPN/TELEPORT), macAddress, ipAddress (frequently absent — do not rely on it being present), connectedAt, uplinkDeviceId (the switch/AP they're attached to), access.type. NOTE: verified against 10.6.106 — the Integration API client schema is minimal and identical across types; it does NOT expose signal strength, channel, or per-port binding. Use for: who's online right now. Disconnected/historical clients are NOT in the Integration API; use unifi_list_client_history and unifi_list_client_sessions for controller-retained records.",
+        description: "List currently connected clients at a site. Returns per client: id, name, type (WIRED/WIRELESS/VPN/TELEPORT), macAddress, ipAddress (may be absent), connectedAt, uplinkDeviceId (the switch/AP they're attached to), access.type. NOTE: verified against 11.0.83 (WIRED/WIRELESS; VPN/TELEPORT not live-verified) — the Integration API client schema is minimal and identical across those types; it does NOT expose signal strength, channel, or per-port binding. Use for: who's online right now. Disconnected/historical clients are NOT in the Integration API; use unifi_list_client_history and unifi_list_client_sessions for controller-retained records.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -24,7 +24,7 @@ function registerClientTools(server, client, readOnly = false) {
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
-            filter: zod_1.z.string().optional().describe("Filter expression"),
+            filter: zod_1.z.string().optional().describe("Filter expression. Filterable: id, type, macAddress, ipAddress, connectedAt (timestamp), access.type, access.authorized (boolean). NOT filterable: name, uplinkDeviceId. Example: type.eq('WIRELESS')"),
         },
         outputSchema: output_schemas_js_1.listClientsOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -58,7 +58,7 @@ function registerClientTools(server, client, readOnly = false) {
     if (readOnly)
         return;
     server.registerTool("unifi_authorize_guest", {
-        description: "Authorize a guest client through a captive-portal hotspot. Optional limits override hotspot defaults. Returns (per 10.6.106 docs, not live-verified): action, grantedAuthorization and revokedAuthorization objects (authorizedAt, authorizationMethod, expiresAt, dataUsageLimitMBytes, rxRateLimitKbps, txRateLimitKbps, usage). Idempotency: not safe to retry — re-authorizing extends the session.",
+        description: "Authorize a guest client through a captive-portal hotspot. Optional limits override hotspot defaults. Returns (per 11.0.83 docs, not live-verified): action, grantedAuthorization and revokedAuthorization objects (authorizedAt, authorizationMethod, expiresAt, dataUsageLimitMBytes, rxRateLimitKbps, txRateLimitKbps, usage). Idempotency: not safe to retry — re-authorizing extends the session.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             clientId: zod_1.z.string().describe("Client ID"),
@@ -116,7 +116,7 @@ function registerClientTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_unauthorize_guest", {
-        description: "Revoke guest authorization; the client returns to the captive portal on next request. Returns (per 10.6.106 docs, not live-verified): action plus a revokedAuthorization object. Idempotent.",
+        description: "Revoke guest authorization; the client returns to the captive portal on next request. Returns (per docs; the UNAUTHORIZE response sample is not rendered in 11.0.83 and not live-verified): action plus a revokedAuthorization object. Idempotent.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             clientId: zod_1.z.string().describe("Client ID"),

package/dist/tools/devices.js

@@ -26,7 +26,7 @@ function registerDeviceTools(server, client, readOnly = false) {
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
-            filter: zod_1.z.string().optional().describe("Filter expression"),
+            filter: zod_1.z.string().optional().describe("Filter expression. Filterable: name (supports like), model, state, macAddress, ipAddress, firmwareVersion, supported, firmwareUpdatable, features/interfaces (sets: contains/containsAny/containsAll). like is rejected on model. Example: features.contains('accessPoint')"),
         },
         outputSchema: output_schemas_js_1.listDevicesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -41,7 +41,7 @@ function registerDeviceTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_device", {
-        description: "Get full configuration for a device. Returns (in addition to list fields): supported, firmwareUpdatable, adoptedAt, provisionedAt, configurationId, uplink.deviceId, features (object keyed by capability: switching {lags[]} / accessPoint {}), interfaces.ports[] for switches ({idx, state, connector, maxSpeedMbps, speedMbps, poe:{standard, type, enabled, state}}), interfaces.radios[] for APs ({wlanStandard, frequencyGHz, channelWidthMHz, channel}). NOTE: in the LIST endpoint, features/interfaces are capability-tag string arrays instead. Use for: switch port layout/PoE state, AP radio config, uplink topology. For live throughput/CPU/memory, use unifi_get_device_statistics.",
+        description: "Get full configuration for a device. Returns (in addition to list fields): adoptedAt, provisionedAt, configurationId, uplink.deviceId (absent on the ISP modem), features (object keyed by capability: switching {lags[]} / accessPoint {}), interfaces.ports[] for switches, gateways and modems ({idx, state, connector, maxSpeedMbps, speedMbps (may be omitted on DOWN ports), poe:{standard, type, enabled, state} on PoE ports only}), interfaces.radios[] for APs ({wlanStandard, frequencyGHz, channelWidthMHz, channel}). Some devices (e.g. 5G modems) return empty features/interfaces objects. NOTE: in the LIST endpoint, features/interfaces are capability-tag string arrays instead. Use for: switch port layout/PoE state, AP radio config, uplink topology. For live throughput/CPU/memory, use unifi_get_device_statistics.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             deviceId: zod_1.z.string().describe("Device ID"),
@@ -58,7 +58,7 @@ function registerDeviceTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_device_statistics", {
-        description: "Get latest live statistics for a device. Returns: uptimeSec, lastHeartbeatAt, nextHeartbeatAt, loadAverage1/5/15Min, cpuUtilizationPct, memoryUtilizationPct, uplink (txRateBps, rxRateBps), interfaces.radios[] for APs ({frequencyGHz, txRetriesPct}). NOTE: verified against 10.6.106 — the Integration API does NOT expose per-switch-port byte/error/PoE-power counters here; port-level live stats are unavailable. Use for: device health and AP radio metrics. For config (channel, power, port assignment), use unifi_get_device.",
+        description: "Get latest live statistics for a device. Returns: uptimeSec, lastHeartbeatAt, nextHeartbeatAt, loadAverage1/5/15Min, cpuUtilizationPct, memoryUtilizationPct, uplink (txRateBps, rxRateBps; absent on e.g. the ISP modem), interfaces.radios[] for APs ({frequencyGHz, txRetriesPct}; interfaces is {} for non-AP devices). NOTE: verified against 11.0.83 — the Integration API does NOT expose per-switch-port byte/error/PoE-power counters here; port-level live stats are unavailable. Use for: device health and AP radio metrics. For config (channel, power, port assignment), use unifi_get_device.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             deviceId: zod_1.z.string().describe("Device ID"),
@@ -75,7 +75,7 @@ function registerDeviceTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_list_pending_devices", {
-        description: "List devices pending adoption across all sites (global endpoint, not site-scoped). Returns: basic device info per pending device (macAddress, model, ipAddress, firmwareVersion, etc. — exact per-row schema is not rendered in the 10.6.106 docs). Use for: discovering new devices on the network before calling unifi_adopt_device.",
+        description: "List devices pending adoption across all sites (global endpoint, not site-scoped). Returns: basic device info per pending device (macAddress, model, ipAddress, firmwareVersion, etc. — exact per-row schema is not rendered in the 11.0.83 docs). Use for: discovering new devices on the network before calling unifi_adopt_device.",
         inputSchema: {
             offset: zod_1.z
                 .number()
@@ -90,7 +90,7 @@ function registerDeviceTools(server, client, readOnly = false) {
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
-            filter: zod_1.z.string().optional().describe("Filter expression"),
+            filter: zod_1.z.string().optional().describe("Filter expression, e.g. model.eq('U7 Pro')"),
         },
         outputSchema: output_schemas_js_1.listPendingDevicesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -157,13 +157,13 @@ function registerDeviceTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_restart_device", {
-        description: "Restart (reboot) a device. The device will be unreachable for ~1–3 minutes. Idempotent: repeated calls trigger fresh reboots.",
+        description: "Restart (reboot) a device. The device will be unreachable for ~1–3 minutes. Not idempotent: each call triggers a fresh reboot.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             deviceId: zod_1.z.string().describe("Device ID"),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },
-        annotations: safety_js_1.WRITE,
+        annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
     }, async ({ siteId, deviceId, dryRun }) => {
         const body = { action: "RESTART" };
         if (dryRun)
@@ -181,10 +181,10 @@ function registerDeviceTools(server, client, readOnly = false) {
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             deviceId: zod_1.z.string().describe("Device ID"),
-            portIdx: zod_1.z.number().int().describe("Port index number"),
+            portIdx: zod_1.z.number().int().min(1).describe("Port index number (1-based)"),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },
-        annotations: safety_js_1.WRITE,
+        annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
     }, async ({ siteId, deviceId, portIdx, dryRun }) => {
         const body = { action: "POWER_CYCLE" };
         if (dryRun)

package/dist/tools/dns-policies.js

@@ -5,10 +5,83 @@ 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");
+// Type-specific request-body fields, from the 11.0.83 POST/PUT schemas (every
+// type also takes type, enabled, domain). MX/TXT/SRV/FORWARD_DOMAIN have no TTL.
+const DNS_TYPE_FIELDS = {
+    A_RECORD: ["ipv4Address", "ttlSeconds"],
+    AAAA_RECORD: ["ipv6Address", "ttlSeconds"],
+    CNAME_RECORD: ["targetDomain", "ttlSeconds"],
+    MX_RECORD: ["mailServerDomain", "priority"],
+    TXT_RECORD: ["text"],
+    SRV_RECORD: ["serverDomain", "service", "protocol", "port", "priority", "weight"],
+    FORWARD_DOMAIN: ["ipAddress"],
+};
+const DNS_TYPES_DOC = "A_RECORD: ipv4Address, ttlSeconds (0-86400). AAAA_RECORD: ipv6Address, ttlSeconds (0-86400). CNAME_RECORD: targetDomain, ttlSeconds (0-604800). MX_RECORD: mailServerDomain, priority. TXT_RECORD: text. SRV_RECORD: serverDomain, service (e.g. _ldap), protocol (e.g. _tcp), port, priority, weight. FORWARD_DOMAIN: ipAddress (upstream DNS server). All type-specific fields are required for their type.";
+const dnsType = zod_1.z
+    .enum([
+    "A_RECORD",
+    "AAAA_RECORD",
+    "CNAME_RECORD",
+    "MX_RECORD",
+    "TXT_RECORD",
+    "SRV_RECORD",
+    "FORWARD_DOMAIN",
+])
+    .describe("DNS record type");
+function fieldsForDnsType(type) {
+    if (typeof type !== "string" || !(type in DNS_TYPE_FIELDS)) {
+        throw new Error(`Unsupported DNS policy type: ${String(type)}`);
+    }
+    const specific = DNS_TYPE_FIELDS[type];
+    return {
+        allowed: ["type", "enabled", "domain", ...specific],
+        required: ["type", "enabled", "domain", ...specific],
+    };
+}
+function checkDnsBody(body, updates) {
+    const { allowed, required } = fieldsForDnsType(body.type);
+    const rejected = (0, full_put_js_1.unsupportedFields)(updates, allowed);
+    if (rejected.length > 0) {
+        throw new Error(`Fields not accepted for type ${String(body.type)}: ${rejected.join(", ")}`);
+    }
+    const missing = (0, full_put_js_1.missingFields)(body, required);
+    if (missing.length > 0) {
+        throw new Error(`Missing required fields for type ${String(body.type)}: ${missing.join(", ")}`);
+    }
+    if ((body.type === "A_RECORD" || body.type === "AAAA_RECORD") &&
+        typeof body.ttlSeconds === "number" &&
+        body.ttlSeconds > 86400) {
+        throw new Error(`ttlSeconds for ${body.type} must be 0-86400 (604800 is the CNAME_RECORD maximum)`);
+    }
+}
+const uint16 = (description) => zod_1.z.number().int().min(0).max(65535).optional().describe(description);
+const hostname = (description) => zod_1.z.string().min(1).max(127).optional().describe(description);
+const dnsFields = {
+    ipv4Address: zod_1.z.string().optional().describe("IPv4 address. A_RECORD."),
+    ipv6Address: zod_1.z.string().optional().describe("IPv6 address. AAAA_RECORD."),
+    targetDomain: hostname("Canonical name the alias points at. CNAME_RECORD."),
+    mailServerDomain: hostname("Mail server domain. MX_RECORD."),
+    text: zod_1.z.string().min(1).max(1024).optional().describe("TXT value: up to four 255-character strings; lines containing commas must be double-quoted. TXT_RECORD."),
+    serverDomain: hostname("Domain of the server running the service. SRV_RECORD."),
+    service: zod_1.z.string().optional().describe("Service, e.g. _ldap. SRV_RECORD."),
+    protocol: zod_1.z.string().optional().describe("Protocol, e.g. _tcp. SRV_RECORD."),
+    port: uint16("Service port. SRV_RECORD."),
+    priority: uint16("Priority; lower is preferred. MX_RECORD, SRV_RECORD."),
+    weight: uint16("Relative weight among records with the same priority. SRV_RECORD."),
+    ipAddress: zod_1.z.string().optional().describe("IP address of the DNS server queries are forwarded to. FORWARD_DOMAIN."),
+    ttlSeconds: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .max(604800)
+        .optional()
+        .describe("Time to live in seconds: 0-86400 for A/AAAA_RECORD, 0-604800 for CNAME_RECORD"),
+};
 function registerDnsPolicyTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_dns_policies", {
-        description: "List DNS policies (local DNS records and forward rules served by the gateway) at a site. Returns: id, type (A_RECORD, AAAA_RECORD, CNAME_RECORD, MX_RECORD, TXT_RECORD, SRV_RECORD, FORWARD_DOMAIN), enabled, domain, ipv4Address, ttlSeconds, metadata.origin.",
+        description: "List DNS policies (local DNS records and forward rules served by the gateway) at a site. Returns: id, type (A_RECORD, AAAA_RECORD, CNAME_RECORD, MX_RECORD, TXT_RECORD, SRV_RECORD, FORWARD_DOMAIN), enabled, domain, metadata.origin, plus type-specific fields: A ipv4Address+ttlSeconds; AAAA ipv6Address+ttlSeconds; CNAME targetDomain+ttlSeconds; MX mailServerDomain+priority; TXT text; SRV serverDomain/service/protocol/port/priority/weight; FORWARD_DOMAIN ipAddress (per 11.0.83 response samples).",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -27,7 +100,7 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. type.eq('A_RECORD')"),
         },
         outputSchema: output_schemas_js_1.listDnsPoliciesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -61,29 +134,13 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
     if (readOnly)
         return;
     server.registerTool("unifi_create_dns_policy", {
-        description: "Create a new DNS policy",
+        description: `Create a new DNS policy. Every type takes type, enabled, domain; the rest depends on type (per 11.0.83 docs): ${DNS_TYPES_DOC} Fields belonging to other types are rejected. Idempotency: not safe to retry — re-running creates a duplicate record.`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
-            type: zod_1.z
-                .enum([
-                "A_RECORD",
-                "AAAA_RECORD",
-                "CNAME_RECORD",
-                "MX_RECORD",
-                "TXT_RECORD",
-                "SRV_RECORD",
-                "FORWARD_DOMAIN",
-            ])
-                .describe("DNS record type"),
+            ...dnsFields,
+            type: dnsType,
             enabled: zod_1.z.boolean().describe("Whether the DNS policy is enabled"),
             domain: zod_1.z.string().min(1).max(127).describe("Domain name"),
-            ipv4Address: zod_1.z.string().describe("IPv4 address for the record"),
-            ttlSeconds: zod_1.z
-                .number()
-                .int()
-                .min(0)
-                .max(86400)
-                .describe("Time to live in seconds"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -91,9 +148,10 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
         },
         outputSchema: output_schemas_js_1.dnsPolicyOutputSchema,
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
-    }, async ({ siteId, type, enabled, domain, ipv4Address, ttlSeconds, dryRun }) => {
+    }, async ({ siteId, dryRun, ...fields }) => {
         try {
-            const body = { type, enabled, domain, ipv4Address, ttlSeconds };
+            const body = (0, full_put_js_1.definedEntries)(fields);
+            checkDnsBody(body, body);
             if (dryRun)
                 return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/dns/policies`, body);
             const data = await client.post(`/sites/${siteId}/dns/policies`, body);
@@ -104,43 +162,32 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_dns_policy", {
-        description: "Update a DNS policy",
+        description: `Update a DNS policy. Pass only the fields to change. The API's PUT replaces the whole policy, so this tool reads the current policy, keeps the documented fields for the (possibly new) type, overlays your changes and sends the full body. Changing type drops the old type's fields, so supply the new type's required fields: ${DNS_TYPES_DOC} dryRun shows the merged body.`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             dnsPolicyId: zod_1.z.string().describe("DNS policy ID"),
-            type: zod_1.z
-                .enum([
-                "A_RECORD",
-                "AAAA_RECORD",
-                "CNAME_RECORD",
-                "MX_RECORD",
-                "TXT_RECORD",
-                "SRV_RECORD",
-                "FORWARD_DOMAIN",
-            ])
-                .describe("DNS record type"),
-            enabled: zod_1.z.boolean().describe("Whether the DNS policy is enabled"),
-            domain: zod_1.z.string().min(1).max(127).describe("Domain name"),
-            ipv4Address: zod_1.z.string().describe("IPv4 address for the record"),
-            ttlSeconds: zod_1.z
-                .number()
-                .int()
-                .min(0)
-                .max(86400)
-                .describe("Time to live in seconds"),
+            ...dnsFields,
+            type: dnsType.optional(),
+            enabled: zod_1.z.boolean().optional().describe("Whether the DNS policy is enabled"),
+            domain: zod_1.z.string().min(1).max(127).optional().describe("Domain name"),
             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 policy)"),
         },
         outputSchema: output_schemas_js_1.dnsPolicyOutputSchema,
         annotations: safety_js_1.WRITE,
-    }, async ({ siteId, dnsPolicyId, type, enabled, domain, ipv4Address, ttlSeconds, dryRun }) => {
+    }, async ({ siteId, dnsPolicyId, dryRun, ...fields }) => {
         try {
-            const body = { type, enabled, domain, ipv4Address, ttlSeconds };
+            const path = `/sites/${siteId}/dns/policies/${dnsPolicyId}`;
+            const current = (0, full_put_js_1.asObject)(await client.get(path), "the current DNS policy");
+            const updates = (0, full_put_js_1.definedEntries)(fields);
+            const { allowed } = fieldsForDnsType(updates.type ?? current.type);
+            const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
+            checkDnsBody(body, updates);
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/dns/policies/${dnsPolicyId}`, body);
-            const data = await client.put(`/sites/${siteId}/dns/policies/${dnsPolicyId}`, 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/firewall.js

@@ -5,7 +5,35 @@ 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");
+// Firewall policy request-body fields, from the 11.0.83 POST/PUT schemas.
+const FIREWALL_POLICY_FIELDS = [
+    "enabled",
+    "name",
+    "description",
+    "action",
+    "source",
+    "destination",
+    "ipProtocolScope",
+    "connectionStateFilter",
+    "ipsecFilter",
+    "loggingEnabled",
+    "reportFlowEnabled",
+    "schedule",
+];
+const FIREWALL_POLICY_REQUIRED = [
+    "enabled",
+    "name",
+    "action",
+    "source",
+    "destination",
+    "ipProtocolScope",
+    "loggingEnabled",
+];
+// Present in responses but not part of the request body.
+const FIREWALL_POLICY_READ_ONLY = ["id", "index", "metadata"];
+const FIREWALL_POLICY_BODY_DOC = "required enabled, name (non-empty), action ({type: ALLOW|BLOCK, allowReturnTraffic? on ALLOW}), source and destination ({zoneId, trafficFilter?}), ipProtocolScope ({ipVersion, protocolFilter?}), loggingEnabled; optional description, connectionStateFilter (array of NEW/INVALID/ESTABLISHED/RELATED), ipsecFilter (MATCH_ENCRYPTED/MATCH_NOT_ENCRYPTED), schedule (null = always active), reportFlowEnabled (report matches in Insights Flows; defaults to true when omitted).";
 function registerFirewallTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_firewall_zones", {
         description: "List firewall zones (groupings of networks for zone-based firewalling) at a site. Returns: id, name, networkIds[], metadata.origin (indicates system-defined vs user-defined). Use for: zone inventory; pair with unifi_list_firewall_policies to see rules between zones.",
@@ -27,7 +55,7 @@ function registerFirewallTools(server, client, readOnly = false) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. name.eq('Internal'). NOTE: totalCount ignores the filter on this endpoint (observed 11.0.83) — page by count"),
         },
         outputSchema: output_schemas_js_1.listFirewallZonesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -59,7 +87,7 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_list_firewall_policies", {
-        description: "List firewall policies (zone-based rules) at a site. Returns: id, name, enabled, action (object with type field), source/destination (zone reference + trafficFilter), ipProtocolScope, connectionStateFilter, ipsecFilter, schedule, loggingEnabled, index, description, metadata.origin. Protocols/ports are encoded inside source/destination.trafficFilter, not as top-level fields. Evaluation order within a zone pair comes from unifi_get_firewall_policy_ordering.",
+        description: "List firewall policies (zone-based rules) at a site. Returns: id, name, enabled, action (object with type field), source/destination (zone reference + trafficFilter), ipProtocolScope, connectionStateFilter, ipsecFilter, schedule, loggingEnabled, reportFlowEnabled (Insights Flows reporting; false on the predefined Allow Return Traffic and Block policies), index, description, metadata (origin SYSTEM_DEFINED/USER_DEFINED/DERIVED, configurable on system policies). action is {type: ALLOW|BLOCK, allowReturnTraffic on ALLOW}. The protocol lives in ipProtocolScope.protocolFilter (NAMED_PROTOCOL or PRESET); ports and addresses live in source/destination.trafficFilter, which is omitted when a side matches the whole zone. Unset optional fields (ipsecFilter, schedule, connectionStateFilter) are omitted, not null. Evaluation order within a zone pair comes from unifi_get_firewall_policy_ordering.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -78,7 +106,7 @@ function registerFirewallTools(server, client, readOnly = false) {
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression"),
+                .describe("Filter expression, e.g. metadata.origin.eq('USER_DEFINED') or name.eq('Allow Return Traffic'). Boolean fields (enabled, loggingEnabled, reportFlowEnabled) are not filterable"),
         },
         outputSchema: output_schemas_js_1.listFirewallPoliciesOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -93,7 +121,7 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_firewall_policy", {
-        description: "Get a firewall policy by ID with full match criteria and action.",
+        description: "Get a firewall policy by ID with full match criteria and action. Returns the same fields as a unifi_list_firewall_policies entry, including loggingEnabled and reportFlowEnabled.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             firewallPolicyId: zod_1.z.string().describe("Firewall policy ID"),
@@ -110,7 +138,7 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_get_firewall_policy_ordering", {
-        description: "Get the evaluation order of user-defined firewall policies for a specific (source zone, destination zone) pair. Returns: beforeSystemDefined[] and afterSystemDefined[] arrays of policy IDs. System-defined rules sit between these two arrays.",
+        description: "Get the evaluation order of user-defined firewall policies for a specific (source zone, destination zone) pair. Returns: orderedFirewallPolicyIds.beforeSystemDefined[] and orderedFirewallPolicyIds.afterSystemDefined[] arrays of policy IDs. System-defined rules sit between these two arrays.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             sourceFirewallZoneId: zod_1.z
@@ -219,7 +247,7 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_create_firewall_policy", {
-        description: "Create a new firewall policy",
+        description: `Create a new firewall policy. Body fields (per 11.0.83 docs): ${FIREWALL_POLICY_BODY_DOC} Copy nested shapes (trafficFilter, protocolFilter) from an existing policy via unifi_get_firewall_policy. Idempotency: not safe to retry — re-running creates a duplicate policy.`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             policy: zod_1.z
@@ -244,25 +272,37 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_firewall_policy", {
-        description: "Update a firewall policy",
+        description: `Update a firewall policy. Pass only the fields to change in policy. The API's PUT replaces the whole policy — and an omitted reportFlowEnabled reverts to true — so this tool reads the current policy, keeps every documented body field, overlays your fields and sends the full body. Top-level fields are replaced whole (e.g. send the complete source object). Read-only response fields (id, index, metadata) are ignored. Body fields: ${FIREWALL_POLICY_BODY_DOC} For just logging/flow-reporting toggles, prefer unifi_patch_firewall_policy. dryRun shows the merged body.`,
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             firewallPolicyId: zod_1.z.string().describe("Firewall policy ID"),
             policy: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Firewall policy configuration (JSON object)"),
+                .describe("Firewall policy fields to change (JSON object); null clears an optional field such as schedule"),
             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 policy)"),
         },
         outputSchema: output_schemas_js_1.firewallPolicyOutputSchema,
         annotations: safety_js_1.WRITE,
     }, async ({ siteId, firewallPolicyId, policy, dryRun }) => {
         try {
+            const path = `/sites/${siteId}/firewall/policies/${firewallPolicyId}`;
+            const updates = Object.fromEntries(Object.entries(policy).filter(([field]) => !FIREWALL_POLICY_READ_ONLY.includes(field)));
+            const rejected = (0, full_put_js_1.unsupportedFields)(updates, FIREWALL_POLICY_FIELDS);
+            if (rejected.length > 0) {
+                throw new Error(`Fields not accepted by the firewall policy PUT body: ${rejected.join(", ")}`);
+            }
+            const current = (0, full_put_js_1.asObject)(await client.get(path), "the current firewall policy");
+            const body = (0, full_put_js_1.mergeForPut)(current, updates, FIREWALL_POLICY_FIELDS);
+            const missing = (0, full_put_js_1.missingFields)(body, FIREWALL_POLICY_REQUIRED);
+            if (missing.length > 0) {
+                throw new Error(`Missing required fields: ${missing.join(", ")}`);
+            }
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/firewall/policies/${firewallPolicyId}`, policy);
-            const data = await client.put(`/sites/${siteId}/firewall/policies/${firewallPolicyId}`, policy);
+                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) {
@@ -270,13 +310,13 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_patch_firewall_policy", {
-        description: "Partially update a firewall policy without resending all fields. loggingEnabled is the only field documented as patchable in API 10.6.106; other fields may be rejected — use unifi_update_firewall_policy for a full update. Idempotent for fields supplied.",
+        description: "Partially update a firewall policy without resending all fields. loggingEnabled and reportFlowEnabled are the only fields documented as patchable in API 11.0.83 (reportFlowEnabled is ignored for the predefined Allow Return Traffic policies, which are never reported); other fields may be rejected — use unifi_update_firewall_policy for a full update. Idempotent for fields supplied.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             firewallPolicyId: zod_1.z.string().describe("Firewall policy ID"),
             policy: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
-                .describe("Partial firewall policy fields to update (e.g. { loggingEnabled: true })"),
+                .describe("Partial firewall policy fields to update (e.g. { loggingEnabled: true } or { reportFlowEnabled: false })"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()