@owine/unifi-network-mcp 2.15.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,25 +1,50 @@
 # UniFi Network MCP Server
 
-An MCP (Model Context Protocol) server that exposes the UniFi Network Integration API as tools for Claude Code and other MCP clients. Provides 76 tools for managing sites, devices, clients, networks, WiFi, firewalls, ACLs, switching, DNS policies, hotspot vouchers, VPNs, and more.
+An MCP (Model Context Protocol) server that exposes the UniFi Network Integration API as tools for Claude and other MCP clients: sites, devices, clients, networks, WiFi, firewalls, ACLs, switching, DNS policies, hotspot vouchers, VPNs, and more.
 
 ## Prerequisites
 
-- Node.js 22.13+ or 24 (see `engines` in `package.json`)
+- Node.js in the range `engines.node` in `package.json` allows
 - A UniFi Network console with the Integration API enabled
-- An API key generated from your UniFi Network console
+- An API key generated from your UniFi Network console (see [Choosing an API key](#choosing-an-api-key))
 
 ## Setup
 
-### Quick start (npx)
+### Quick start (Claude Code)
 
 Add to Claude Code with a single command — no clone or build needed:
 
 ```bash
-claude mcp add-json unifi-network '{"command":"npx","args":["-y","@owine/unifi-network-mcp@latest"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key","UNIFI_NETWORK_VERIFY_SSL":"false"}}' -s user
+claude mcp add-json unifi-network '{"command":"npx","args":["-y","@owine/unifi-network-mcp@latest"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key"}}' -s user
 ```
 
 Use `-s user` for global availability across all projects, or `-s project` for the current project only.
 
+`@latest` runs the newest release every time the server starts, including a new major version. To take fixes but choose when to make breaking upgrades, pin the major version instead (for example `@owine/unifi-network-mcp@3`).
+
+### Claude Desktop
+
+Add the server to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "unifi-network": {
+      "command": "npx",
+      "args": ["-y", "@owine/unifi-network-mcp@latest"],
+      "env": {
+        "UNIFI_NETWORK_HOST": "192.168.1.1",
+        "UNIFI_NETWORK_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Manual configuration (Claude Code)
+
+Alternatively, add the same `"unifi-network"` entry to your `~/.claude.json` under the top-level `"mcpServers"` key.
+
 ### From source
 
 If you prefer to build locally, this project uses pnpm via Corepack — use `pnpm install`, not `npm install`, which ignores `pnpm-lock.yaml` and resolves different dependency versions:
@@ -35,21 +60,92 @@ pnpm run build
 Then add to Claude Code:
 
 ```bash
-claude mcp add-json unifi-network '{"command":"node","args":["/path/to/unifi-network-mcp/dist/index.js"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key","UNIFI_NETWORK_VERIFY_SSL":"false"}}' -s user
+claude mcp add-json unifi-network '{"command":"node","args":["/path/to/unifi-network-mcp/dist/index.js"],"env":{"UNIFI_NETWORK_HOST":"192.168.1.1","UNIFI_NETWORK_API_KEY":"your-api-key"}}' -s user
 ```
 
 ### Environment Variables
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `UNIFI_NETWORK_HOST` | Yes | — | IP or hostname of your UniFi Network console |
+| `UNIFI_NETWORK_HOST` | Yes | — | IP or hostname of your UniFi Network console, without `https://` |
 | `UNIFI_NETWORK_API_KEY` | Yes | — | API key from Network integration settings |
-| `UNIFI_NETWORK_VERIFY_SSL` | No | `true` | Set to `false` to skip TLS certificate verification (needed for self-signed certs) |
+| `UNIFI_NETWORK_CA_CERT` | No | — | Absolute path to a PEM file with the console's certificate, to verify a self-signed console without turning verification off (see below) |
+| `UNIFI_NETWORK_VERIFY_SSL` | No | `true` | Set to `false` to skip TLS certificate verification. Not allowed with `api.ui.com` or together with `UNIFI_NETWORK_CA_CERT` |
 | `UNIFI_NETWORK_READ_ONLY` | No | `true` | Set to `false` to enable write/mutating tools (read-only by default) |
+| `UNIFI_NETWORK_CONSOLE_ID` | No | — | Cloud Connector console ID; used only when `UNIFI_NETWORK_HOST` is `api.ui.com` (see [Cloud Connector](#cloud-connector)) |
+| `UNIFI_NETWORK_WRITE_TOOLS` | No | all write tools | Comma-separated write tool names and/or groups (`devices`, `clients`, `networks`, `wifi`, `hotspot`, `firewall`, `acl`, `dns-policies`, `traffic-matching`) to load; `none` or empty loads none. Unknown names stop the server. Ignored, with a warning, while read-only (see [Limiting write mode](#limiting-write-mode)) |
+| `UNIFI_NETWORK_ALLOW_WAN_EXPOSURE` | No | `false` | Set to `true` to stop refusing writes that could let traffic in from the WAN; they then only need `confirm: true` |
+| `UNIFI_NETWORK_WAN_ZONE_IDS` | No | — | Comma-separated firewall zone IDs (UUIDs) to treat as the WAN, in addition to the system-defined zone named `External`. Recommended when writes are on |
+| `UNIFI_NETWORK_WRITE_LOG` | No | — | Absolute path of a JSON Lines file that every write tool call is appended to. Created `0600` (parent directories `0700`); the server will not start if it is a symlink or writable by others. Ignored, with a warning, while read-only |
+
+UniFi consoles ship with a self-signed certificate, so against a local console the first call usually fails with a certificate error. The safe fix is to trust that one certificate: save it and point `UNIFI_NETWORK_CA_CERT` at the file.
+
+```bash
+openssl s_client -connect 192.168.1.1:443 </dev/null 2>/dev/null | openssl x509 > ~/.config/unifi-console.pem
+```
+
+Set `UNIFI_NETWORK_CA_CERT` to the file's absolute path (for example `/home/you/.config/unifi-console.pem`); MCP hosts do not expand `~` in `env`. The server then accepts that exact certificate even though it is issued to a name like `unifi.local` rather than the IP you connect to, and whether it is self-signed or issued by a private CA; any other certificate must chain to the file or to a publicly trusted CA and match the hostname. Pinning does not lift a certificate's validity dates. Check the fingerprint (`openssl x509 -in ~/.config/unifi-console.pem -noout -fingerprint -sha256`) against the console's if the network between you is not trusted. If the console later generates a new certificate, save it again.
+
+Setting `UNIFI_NETWORK_VERIFY_SSL=false` instead turns off certificate checks for this server's connections to the console: anyone who can intercept that traffic can then read the API key. Only do this on a network you trust.
+
+Behind an HTTP(S) proxy, set `NODE_USE_ENV_PROXY=1` along with `HTTPS_PROXY` (and `NO_PROXY` for anything to reach directly), as for Node's own `fetch`; the console's certificate is still verified through the proxy.
 
-### Manual Configuration
+### Choosing an API key
 
-Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` key:
+The key carries the rights of the admin who created it, and this server is driven by a model that reads data other people control (client hostnames, device names). Create the key as a dedicated admin with the least role that covers your use: for the default read-only mode, a **View Only** admin, so nothing can be changed even if a tool were misused. Use a full-access admin only when you set `UNIFI_NETWORK_READ_ONLY=false`, and then also read [Limiting write mode](#limiting-write-mode).
+
+### Cloud Connector
+
+To use a Site Manager API key with a console, set `UNIFI_NETWORK_HOST=api.ui.com` and `UNIFI_NETWORK_CONSOLE_ID` to its console ID. The existing `UNIFI_NETWORK_API_KEY` supplies the key. This works for current Integration API tools and the controller history routes when permitted by the console/key. Cloud Connector requires eligible console ownership/access and firmware 5.0.3 or later. TLS verification stays on: the server refuses to start with `UNIFI_NETWORK_VERIFY_SSL=false` and `api.ui.com`.
+
+References: [official Cloud Connector API](https://developer.ui.com/site-manager/v1.0.0) and the [Art-of-WiFi controller client](https://github.com/Art-of-WiFi/UniFi-API-client/blob/master/src/Client.php), whose session queries use epoch seconds.
+
+## Upgrading from 2.x
+
+3.0 tightens several defaults. Most setups need no change; check these:
+
+- **Cloud Connector with `UNIFI_NETWORK_VERIFY_SSL=false`**: the server now refuses to start with `UNIFI_NETWORK_HOST=api.ui.com` and verification off. Unset `UNIFI_NETWORK_VERIFY_SSL`.
+- **Writes that open access need `confirm: true`**: creating, enabling or switching a firewall policy or ACL rule to ALLOW, disabling a blocking policy or rule, changing what an enabled policy or rule matches, a reorder that moves an ALLOW ahead of a BLOCK, creating or enabling an open SSID or changing its network, captive portal, client isolation or client filtering, changing an SSID's security type, and creating a large batch of vouchers. Without it the tool returns an error naming the change, and the agent can ask you before re-invoking. A dry run of such a change says why in `confirmationRequired`.
+- **IDs must be IDs**: ID inputs accept only letters, digits, `-` and `_` (pass the IDs that list and get tools return).
+- **Smaller default results**: `unifi_list_client_sessions` and `unifi_list_vouchers` return fewer rows by default, and `unifi_list_client_history` now returns at most `limit` clients, most recently seen first, with `totalCount` and `truncated`; pass `limit` for more. Rows from both history tools carry only the fields their tool descriptions list.
+- **Compact text output**: tool results are compact JSON rather than indented; `structuredContent` is unchanged.
+
+- **Writes that could let traffic in from the WAN are refused**: with writes enabled, a firewall policy that allows traffic from the External zone, a change to that zone or to which networks are in it, putting a network in a zone such a policy targets, a reorder of its policies, or an edit to a traffic matching list such a policy uses now fails even with `confirm: true` (see [WAN-exposure refusals](#wan-exposure-refusals)). Set `UNIFI_NETWORK_ALLOW_WAN_EXPOSURE=true` to go back to needing only `confirm`.
+- **Only the endpoints the tools use**: every request is checked against an allowlist before it is sent. No tool behaves differently; anything else is refused.
+
+One rule is relaxed: a `dryRun: true` preview of a destructive tool no longer needs `confirm`.
+
+## Safety Features
+
+This server provides layered safety controls for responsible operation:
+
+- **Tool annotations** — Every tool declares `readOnlyHint`, `destructiveHint` and `openWorldHint`, and every write tool `idempotentHint`, so MCP clients (like Claude Code) can make informed confirmation decisions
+- **Server instructions** — On connect the server gives the MCP host a short usage guide for the model (get a `siteId` first, page with `offset`/`limit`, preview writes with `dryRun`, ask before passing `confirm`), matched to read-only or read-write mode
+- **Read-only mode** — Enabled by default. Only read operations (list, get) are registered. Set `UNIFI_NETWORK_READ_ONLY=false` to enable write/mutating tools
+- **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:` (including `unifi_remove_device` and `unifi_bulk_delete_vouchers`) requires an explicit `confirm: true` parameter for the call to succeed. A `dryRun: true` preview does not need it, since it changes nothing
+- **Confirmation for changes that open access** — Some routine write tools ask for `confirm: true` only when a particular change can let traffic or guests in: a firewall policy or ACL rule that ALLOWs traffic (created, switched on, or switched to ALLOW), disabling a policy or rule that blocks, changing what an enabled policy or rule matches (widening an ALLOW and narrowing a BLOCK both let more through), a reorder that moves an ALLOW ahead of a BLOCK it used to follow, creating or switching on an open SSID or changing an open SSID's network, captive portal, client isolation or client filtering, changing an SSID's security type, and creating a large batch of vouchers (`unifi_create_voucher`'s `confirm` parameter states the threshold). Each is judged on the resource as the change would leave it, so the update, patch and reorder tools read it first. Without it the call returns an error naming the change; a dry run never needs it, and reports the reason in `confirmationRequired`
+- **Dry-run support** — Every write tool accepts 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, ACL rules 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 the top-level fields you pass, so omitted fields keep their current values. A field you pass replaces the current one whole — nested objects such as `ipv4Configuration`, `securityConfiguration` or a policy's `source` are not deep-merged, so start from what the get tool returns. Pass `null` to clear an optional field. Parallel updates to one resource run one at a time. 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
+- **Request allowlist** — Every request the server makes, reads included, is checked before it is sent against a fixed list of the methods and paths the tools use. Anything else, such as a path with `..` or encoded characters, another application on the console, or a write the server is not set up to make, is refused and never reaches the console
+- **Operator limits for write mode** — `UNIFI_NETWORK_WRITE_TOOLS` loads only the write tools you name, writes that could let traffic in from the WAN are refused outright, and `UNIFI_NETWORK_WRITE_LOG` keeps a record of every write call. See [Limiting write mode](#limiting-write-mode)
+
+## Limiting write mode
+
+An agent with write access reads data that other people control: client hostnames, device names, SSIDs, notes on vouchers. Any of it can be written to look like an instruction, and a model can be misled by it. `dryRun` and `confirm` help when the model behaves, but they are inputs the model itself supplies. The settings below are yours: they hold whatever the model is told, because the server enforces them before anything reaches the console.
+
+### Turning writes on
+
+1. **Use a dedicated, least-privilege key.** Create a separate admin for the agent, limited to the Network application and to the sites it should manage, and generate the key as that admin. Do not reuse your own key.
+2. **Enable writes**: set `UNIFI_NETWORK_READ_ONLY=false`.
+3. **Load only the write tools the job needs**: set `UNIFI_NETWORK_WRITE_TOOLS`, for example `unifi_create_voucher,unifi_delete_voucher` for a front desk, or `wifi` for SSID changes. Other write tools are not registered, so the agent never sees them, and the request allowlist refuses their requests as well.
+4. **Keep the WAN-exposure refusals on**: leave `UNIFI_NETWORK_ALLOW_WAN_EXPOSURE` unset.
+5. **Name your WAN zone**: set `UNIFI_NETWORK_WAN_ZONE_IDS` to the ID of each site's External zone. While the server is still read-only, ask the agent to run `unifi_list_firewall_zones` for each site and copy the `id` of the External zone (system-defined, `metadata.origin` `SYSTEM_DEFINED`). Without the list the server recognises that zone by its name, which can be changed.
+6. **Turn on the write log and watch it**: set `UNIFI_NETWORK_WRITE_LOG` to an absolute path, for example `/home/you/.local/state/unifi-mcp/writes.jsonl`, and look at it after a session (`tail -f` works).
+7. **Try changes with `dryRun: true` first**: ask the agent to preview a change, check the request, then let it run.
+
+A Claude Desktop entry with all of this set:
 
 ```json
 {
@@ -59,45 +155,76 @@ Alternatively, add to your `~/.claude.json` under the top-level `"mcpServers"` k
       "args": ["-y", "@owine/unifi-network-mcp@latest"],
       "env": {
         "UNIFI_NETWORK_HOST": "192.168.1.1",
-        "UNIFI_NETWORK_API_KEY": "your-api-key",
-        "UNIFI_NETWORK_VERIFY_SSL": "false"
+        "UNIFI_NETWORK_API_KEY": "key-of-the-agent-admin",
+        "UNIFI_NETWORK_CA_CERT": "/home/you/.config/unifi-console.pem",
+        "UNIFI_NETWORK_READ_ONLY": "false",
+        "UNIFI_NETWORK_WRITE_TOOLS": "unifi_create_voucher,unifi_delete_voucher,wifi",
+        "UNIFI_NETWORK_WAN_ZONE_IDS": "6f1c2a52-3b6d-4a8e-9a0b-2d5e8f7c1a90",
+        "UNIFI_NETWORK_WRITE_LOG": "/home/you/.local/state/unifi-mcp/writes.jsonl"
       }
     }
   }
 }
 ```
 
-## Safety Features
+### Write tool limits
 
-This server provides layered safety controls for responsible operation:
+`UNIFI_NETWORK_WRITE_TOOLS` takes write tool names from the [Tools](#tools) tables and group names, which match the tool modules: `devices`, `clients`, `networks`, `wifi`, `hotspot`, `firewall`, `acl`, `dns-policies`, `traffic-matching`. Unset, every write tool loads, as before. `none` or an empty value loads none, leaving a read-only tool set while the request allowlist still refuses writes. An unknown name stops the server with a configuration error listing the valid names. Read tools are never affected. The server instructions tell the model which write tools are available.
 
-- **Tool annotations** — Every tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint` so MCP clients (like Claude Code) can make informed confirmation decisions
-- **Read-only mode** — Enabled by default. Only read operations (list, get) are registered. Set `UNIFI_NETWORK_READ_ONLY=false` to enable write/mutating tools
-- **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
+### WAN-exposure refusals
+
+With writes enabled, the server refuses these changes, whatever `confirm` says, and sends nothing:
+
+- creating, updating or patching a firewall policy so that it allows traffic (any action but `BLOCK` or `REJECT`) from the WAN zone. A policy whose `connectionStateFilter` lists only `ESTABLISHED` and/or `RELATED` is exempt, since it only lets return traffic back in; a missing or empty filter matches every state, so it is not. An update is judged on the full body after merging, and a patch on the policy as the patch would leave it (a patch that only turns logging or flow reporting on or off, or disables the policy, is not checked)
+- changing the WAN zone (its name or networks), deleting it, or moving networks out of it into another zone
+- creating or updating a network so that it is in the WAN zone, or moving a network out of it
+- putting a network in a zone that a policy allowing traffic from the WAN targets (creating or updating a network with that `zoneId`, or adding networks to that zone), since the network becomes reachable from the WAN without any policy changing. This holds even when the policy's destination `trafficFilter` narrows it to particular hosts, as the server cannot tell whether those hosts are on the network being moved
+- reordering the policies for traffic from the WAN zone, which could put an allow ahead of a block
+- updating a traffic matching list that a policy allowing traffic from the WAN uses, since the list decides what that policy lets in
+
+Blocking traffic from the WAN, and allowing traffic from inside to the WAN, are not affected. A dry run runs the same check and reports the refusal. ACL rules are not checked: they are enforced by switches between LAN hosts and have no zone, so they cannot let WAN traffic past the gateway firewall. The Integration API has no port-forwarding endpoint.
+
+The Integration API marks zones only as system- or user-defined, and zone names can be changed, so a zone counts as the WAN when its ID is in `UNIFI_NETWORK_WAN_ZONE_IDS`, or when it is system-defined and named `External` (in any case). Set the ID list: a renamed External zone is otherwise missed. To check a change the server lists the site's firewall zones (and, for a matching list or a network put in a zone, its policies). If that fails, or the change names a zone that is not in the list, the write is refused rather than allowed unchecked.
+
+A refused call returns:
+
+```text
+Refused: the policy would ALLOW traffic from the External zone, which is the WAN. This server does not make changes that could let traffic in from the WAN, and confirm does not override this; if the change is intended, make it in the UniFi console.
+```
+
+If you do want the agent to make such changes, `UNIFI_NETWORK_ALLOW_WAN_EXPOSURE=true` turns the refusals off; those changes then need `confirm: true` like other changes that open access.
+
+### Write log
+
+With `UNIFI_NETWORK_WRITE_LOG` set, each write tool call appends one line, including dry runs and refused calls. Read tools are not logged.
+
+```json
+{"ts":"2026-10-19T00:12:46.170Z","tsLocal":"2026-10-18T20:12:46.170-04:00","tool":"unifi_create_firewall_policy","args":{"siteId":"5f3a9c1e-2b7d-4e8f-9a6b-0c1d2e3f4a5b","policy":{"name":"SSH in","enabled":true,"action":{"type":"ALLOW"},"source":{"zoneId":"6f1c2a52-3b6d-4a8e-9a0b-2d5e8f7c1a90"},"destination":{"zoneId":"0b6d9c1e-58a4-4f43-8e0f-1c2d3e4f5a6b"}},"confirm":true},"method":"POST","path":"/integration/v1/sites/5f3a9c1e-2b7d-4e8f-9a6b-0c1d2e3f4a5b/firewall/policies","dryRun":false,"outcome":"refused","reason":"wan_exposure","durationMs":29}
+```
+
+`outcome` is `ok` (with the HTTP `status`), `dry_run`, `refused` (with a `reason`: `request_guard`, `wan_exposure` or `confirmation_required`) or `error` (with the HTTP `status` when the console answered). `path` is the path under the Network application, without host, console ID or query string; `method` and `path` are `null` when the call stopped before choosing a request. Arguments are redacted: WiFi passphrases (including each `presharedKeys[]` entry's, which keeps its network), and any field named, in any case, `passphrase`, `password`, `secret`, `sharedSecret`, `radiusSecret`, their legacy `x_` forms, `apiKey`, `api_key`, `apiToken`, `token`, `accessToken`, `refreshToken`, `authToken`, `privateKey`, `private_key` or `presharedKey`. The list is in `src/write-log.ts`. The API key and the console's response bodies are never written.
+
+The file is created with mode `0600`, and missing parent directories with `0700`. The server refuses to start if the path is a symlink, not a regular file, has other hard links, or is writable by group or others. On Windows, where Node reports every writable file as mode `0666` and cannot open without following symlinks, only the symlink and regular-file checks apply: restrict the file with its ACL (for example, keep it in your user profile). If a line cannot be written (a full disk, say), the tool call still completes and the server reports the problem once on stderr.
 
 ## 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.
+Every read tool, and every write tool whose API response returns the affected resource, declares an MCP `outputSchema` and returns `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. A `dryRun: true` call returns its preview, `{"dryRun": true, "wouldExecute": {"method", "path", "body"}}`, the same way. Other write tools (deletes, device and guest actions, reorders) return the API response as text only.
 
-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.
+The schemas live in `src/utils/output-schemas.ts`. They deliberately use a **loose strategy**: every non-key field is optional and objects accept fields the schema does not list, 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)
+## Tools
 
-### System (1)
+### System
 | Tool | Description |
 |---|---|
 | `unifi_get_info` | Get UniFi Network application info — returns `applicationVersion` only |
 
-### Sites (1)
+### Sites
 | Tool | Description |
 |---|---|
 | `unifi_list_sites` | List all sites available to the API key |
 
-### Devices (8)
+### Devices
 | Tool | Description |
 |---|---|
 | `unifi_list_devices` | List all adopted devices at a site |
@@ -109,7 +236,7 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_restart_device` | Restart a device |
 | `unifi_power_cycle_port` | Power cycle a specific port (PoE restart) |
 
-### Clients (4)
+### Clients
 | Tool | Description |
 |---|---|
 | `unifi_list_clients` | List all connected clients (wired, wireless, VPN) at a site |
@@ -117,13 +244,13 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_authorize_guest` | Authorize a guest client on a hotspot network |
 | `unifi_unauthorize_guest` | Unauthorize a guest client |
 
-### Client history (2)
+### Client history
 | Tool | Description |
 |---|---|
 | `unifi_list_client_history` | Historical/offline client inventory and first/last seen times |
 | `unifi_list_client_sessions` | Retained connection sessions, duration, byte counters and roaming records |
 
-### Networks (6)
+### Networks
 | Tool | Description |
 |---|---|
 | `unifi_list_networks` | List all networks at a site |
@@ -133,7 +260,7 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `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)
+### WiFi
 | Tool | Description |
 |---|---|
 | `unifi_list_wifi` | List all WiFi broadcasts (SSIDs) at a site (passphrases redacted by default) |
@@ -142,7 +269,7 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `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)
+### Hotspot Vouchers
 | Tool | Description |
 |---|---|
 | `unifi_list_vouchers` | List all hotspot vouchers at a site |
@@ -151,13 +278,13 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_delete_voucher` | **DESTRUCTIVE:** Delete a hotspot voucher |
 | `unifi_bulk_delete_vouchers` | **DESTRUCTIVE:** Bulk delete vouchers matching a filter |
 
-### Firewall Zones & Policies (13)
+### Firewall Zones & Policies
 | Tool | Description |
 |---|---|
 | `unifi_list_firewall_zones` | List all firewall zones at a site |
 | `unifi_get_firewall_zone` | Get a specific firewall zone by ID |
 | `unifi_create_firewall_zone` | Create a new custom firewall zone |
-| `unifi_update_firewall_zone` | Update a firewall zone |
+| `unifi_update_firewall_zone` | Replace a firewall zone's name and network list (send every network ID to keep) |
 | `unifi_delete_firewall_zone` | **DESTRUCTIVE:** Delete a custom firewall zone |
 | `unifi_list_firewall_policies` | List all firewall policies at a site |
 | `unifi_get_firewall_policy` | Get a specific firewall policy by ID |
@@ -168,18 +295,18 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `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 |
 
-### ACL Rules (7)
+### ACL Rules
 | Tool | Description |
 |---|---|
 | `unifi_list_acl_rules` | List all ACL rules at a site |
 | `unifi_get_acl_rule` | Get a specific ACL rule by ID |
 | `unifi_get_acl_rule_ordering` | Get user-defined ACL rule ordering |
 | `unifi_create_acl_rule` | Create a new ACL rule |
-| `unifi_update_acl_rule` | Update an ACL rule |
+| `unifi_update_acl_rule` | Update an ACL rule — partial changes are merged into the full PUT body |
 | `unifi_delete_acl_rule` | **DESTRUCTIVE:** Delete an ACL rule |
 | `unifi_reorder_acl_rules` | Reorder user-defined ACL rules |
 
-### Switching (6)
+### Switching
 | Tool | Description |
 |---|---|
 | `unifi_list_switch_stacks` | List all Switch Stacks at a site |
@@ -189,7 +316,7 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_list_lags` | List all LAGs (Link Aggregation Groups) at a site |
 | `unifi_get_lag` | Get details of a specific LAG |
 
-### DNS Policies (5)
+### DNS Policies
 | Tool | Description |
 |---|---|
 | `unifi_list_dns_policies` | List all DNS policies at a site |
@@ -198,16 +325,16 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `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)
+### Traffic Matching
 | Tool | Description |
 |---|---|
 | `unifi_list_traffic_matching_lists` | List all traffic matching lists (port groups, IP groups) |
 | `unifi_get_traffic_matching_list` | Get a specific traffic matching list by ID |
 | `unifi_create_traffic_matching_list` | Create a new traffic matching list |
-| `unifi_update_traffic_matching_list` | Update a traffic matching list |
+| `unifi_update_traffic_matching_list` | Replace a traffic matching list (send the full items array) |
 | `unifi_delete_traffic_matching_list` | **DESTRUCTIVE:** Delete a traffic matching list |
 
-### Supporting (8)
+### Supporting
 | Tool | Description |
 |---|---|
 | `unifi_list_wans` | List all WAN interfaces at a site |
@@ -219,18 +346,63 @@ The schemas live in `src/utils/output-schemas.ts` and are verified against UniFi
 | `unifi_list_dpi_applications` | List all DPI applications for traffic identification |
 | `unifi_list_countries` | List all countries/regions for geo-based rules |
 
+## Retained client connections
+
+The Integration API only lists connected clients. The two history tools use the controller APIs instead: GET `/proxy/network/v2/api/site/{siteReference}/clients/history` and POST `/proxy/network/api/s/{siteReference}/stat/session`. The POST is a statistics query and does not change the network. Both tools remain available in read-only mode.
+
+Use `internalReference` from `unifi_list_sites` (often `default`), not its UUID. Session queries require `start` and `end` in Unix **seconds**, with a maximum 31-day window. The controller ignores `_start`/offset on this endpoint. A full result sets `mayBeTruncated=true`; split the time window or filter by MAC and query again. Overlap split boundaries and deduplicate session IDs. A result below the requested limit means the query was not capped, not that all dates were retained.
+
+```json
+{"siteReference":"default","start":1789272000,"end":1789876800}
+```
+
+`unifi_list_client_history` lists offline clients only, most recently seen first, up to `limit`, with `totalCount`. `truncated: true` means less recently seen clients were left out; raise `limit` (narrowing `withinHours` drops those same clients).
+
+Rows keep the controller's field names (`assoc_time`, `duration`, `rx_bytes`, `tx_bytes`, `roaming_sessions`, …) but carry only the fields each tool's description lists. RX/TX are the controller's counters, not relabeled client download/upload. Inventory is separate from session history. Retention varies; a non-truncated result does not prove all requested dates were retained, and ongoing sessions may not be present. Neither association nor traffic counters establish end-to-end Internet success.
+
+These controller routes are not part of the published Integration API contract. Their availability and API-key permissions vary by controller version. Unsupported, unauthorized, HTML login, legacy `meta.rc` error and malformed responses fail explicitly instead of becoming an empty history. History requests are time-limited, reject redirects, and refuse oversized responses. No browser cookies are required where API-key access is supported.
+
+## Troubleshooting
+
+Configuration errors go to the MCP host's server log and the server exits. Tool errors reach the agent as results starting with `Error:`.
+
+| Message | Cause and fix |
+|---|---|
+| `Configuration error:` naming `host` or `apiKey` | `UNIFI_NETWORK_HOST` or `UNIFI_NETWORK_API_KEY` is missing from the server's `env`. |
+| `cannot read UNIFI_NETWORK_CA_CERT (…)` | The path does not exist for the server. Use an absolute path; `~` and `$HOME` are not expanded in an MCP config. |
+| `UNIFI_NETWORK_CA_CERT must name a PEM file containing a certificate` | The file has no `BEGIN CERTIFICATE` block; re-run the `openssl` command above. |
+| `…cannot be combined with UNIFI_NETWORK_VERIFY_SSL=false` or `TLS verification cannot be disabled for api.ui.com` | Unset `UNIFI_NETWORK_VERIFY_SSL`. |
+| `Ignoring UNIFI_NETWORK_CONSOLE_ID` (log line) | The console ID only applies with `UNIFI_NETWORK_HOST=api.ui.com`. |
+| `fetch failed (DEPTH_ZERO_SELF_SIGNED_CERT)` or another certificate code | The console's certificate did not verify. Save it to `UNIFI_NETWORK_CA_CERT`; if you already did, the console has a new certificate, so save it again. |
+| `fetch failed (ECONNREFUSED)`, `(ENOTFOUND)` or a connect timeout | Wrong or unreachable host. `UNIFI_NETWORK_HOST` is a bare IP or hostname, without `https://`. |
+| `HTTP 401` / `HTTP 403` | The key is wrong or revoked, or its admin lacks the rights (a View Only key cannot write). |
+| `HTTP 404` | A wrong `siteId` or resource ID, or an endpoint this Network version lacks (check `unifi_get_info`). |
+| `UniFi controller did not respond within …` | The console is slow. For a write, check whether it was applied before retrying. |
+| `This action requires explicit confirmation: …` | Expected: the change needs `confirm: true`, and the agent should ask you first. |
+| `Use an ID returned by a list or get tool` | The agent passed a name or malformed ID. |
+| `Request refused by the request guard: …` | The server would only send a request on its allowlist; this one was not, or belongs to a write tool `UNIFI_NETWORK_WRITE_TOOLS` does not enable. Nothing was sent. If a tool you did not modify hits this, please open an issue. |
+| `Refused: … which is the WAN` | Expected: the change could let traffic in from the WAN, and `confirm` does not override it. Make it in the UniFi console (see [WAN-exposure refusals](#wan-exposure-refusals)). |
+| `Refused: the firewall zones could not be read …` or `… is not one of this site's firewall zones` | The WAN check could not run, so the write was refused. Check the key can read the site's firewall zones, and that the zone ID is right. |
+| `UNIFI_NETWORK_WRITE_TOOLS names unknown write tools or groups: …` | A typo or a read tool's name. The message lists the valid names. |
+| A write tool is missing, or `Tool … not found` | `UNIFI_NETWORK_WRITE_TOOLS` does not name it or its group. |
+| `cannot use UNIFI_NETWORK_WRITE_LOG (…)` | The path is a symlink, not a regular file, hard-linked elsewhere, or writable by others (`chmod 600` it), or its directory cannot be created. |
+| No write tools listed | Read-only is the default. Set `UNIFI_NETWORK_READ_ONLY=false` (only `false` counts; any other value stays read-only) and restart the host. If it is set, check `UNIFI_NETWORK_WRITE_TOOLS` is not `none` or empty. |
+| `Controller history returned HTTP …`, `non-JSON data` or `an empty body` | This console or key cannot use the history routes (see [Retained client connections](#retained-client-connections)). It is not an empty history. |
+| `Use the site's internalReference …` | History tools take `internalReference` (often `default`) from `unifi_list_sites`, not the UUID. |
+
 ## Development
 
 ```bash
-pnpm install           # Install dependencies
-pnpm run build         # Compile TypeScript
-pnpm start             # Run the server
-pnpm run typecheck     # Type-check without emitting
-pnpm run lint          # ESLint
-pnpm run lint:fix      # ESLint with auto-fix
-pnpm test              # Run all tests (vitest)
-pnpm run test:watch    # Run tests in watch mode
-pnpm run test:coverage # Run tests with coverage
+pnpm install            # Install dependencies
+pnpm run build          # Compile TypeScript
+pnpm start              # Run the server
+pnpm run typecheck      # Type-check src/ and tests
+pnpm run lint           # ESLint
+pnpm run lint:fix       # ESLint with auto-fix
+pnpm test               # Run all tests (vitest)
+pnpm run test:watch     # Run tests in watch mode
+pnpm run test:coverage  # Run tests with coverage
+pnpm run test:package   # Build, pack and smoke-test the published package
 ```
 
 ### Commit conventions
@@ -239,37 +411,18 @@ This project uses [conventional commits](https://www.conventionalcommits.org/) a
 
 - `feat: ...` — new feature (minor version bump)
 - `fix: ...` — bug fix (patch version bump)
+- `deps: ...` — dependency update (patch version bump)
 - `feat!: ...` or `BREAKING CHANGE:` footer — breaking change (major version bump)
 - `chore:`, `docs:`, `ci:`, etc. — no version bump
 
 On push to `main`, release-please opens a Release PR that bumps the version and updates `CHANGELOG.md`. Merging that PR publishes to npm automatically.
 
-To override the version number, add `Release-As: x.x.x` in the commit body:
+To override the version number, add `Release-As: x.y.z` in the commit body:
 
 ```bash
-git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"
+git commit --allow-empty -m "chore: release x.y.z" -m "Release-As: x.y.z"
 ```
 
 ## License
 
-MIT
-
-## Retained client connections
-
-The Integration API only lists connected clients. The two history tools use the controller APIs instead: GET `/proxy/network/v2/api/site/{siteReference}/clients/history` and POST `/proxy/network/api/s/{siteReference}/stat/session`. The POST is a statistics query and does not change the network. Both tools remain available in read-only mode.
-
-Use `internalReference` from `unifi_list_sites` (often `default`), not its UUID. Session queries require `start` and `end` in Unix **seconds**, with a maximum 31-day window. The controller ignores `_start`/offset on this endpoint. A full result sets `mayBeTruncated=true`; split the time window or filter by MAC and query again. Overlap split boundaries and deduplicate session IDs. A result below the requested limit means the query was not capped, not that all dates were retained.
-
-```json
-{"siteReference":"default","start":1789272000,"end":1789876800,"limit":1000}
-```
-
-Results preserve controller field names, including `assoc_time`, `duration`, `rx_bytes`, `tx_bytes` and `roaming_sessions`. RX/TX are the controller's counters, not relabeled client download/upload. Inventory is separate from session history. Retention varies; a non-truncated result does not prove all requested dates were retained, and ongoing sessions may not be present. Neither association nor traffic counters establish end-to-end Internet success. The `is_guest` flag does not establish device ownership.
-
-These controller routes are not part of the published Integration API contract. Their availability and API-key permissions vary by controller version. Unsupported, unauthorized, HTML login, legacy `meta.rc` error and malformed responses fail explicitly instead of becoming an empty history. History requests have a 25-second timeout, reject redirects, and cap responses at 10 MB. No browser cookies are required where API-key access is supported.
-
-### Cloud Connector
-
-To use a Site Manager API key with a console, set `UNIFI_NETWORK_HOST=api.ui.com` and `UNIFI_NETWORK_CONSOLE_ID` to its console ID. The existing `UNIFI_NETWORK_API_KEY` supplies the key. This works for current Integration API tools and the controller history routes when permitted by the console/key. Cloud Connector requires eligible console ownership/access and firmware 5.0.3 or later. Keep TLS verification enabled.
-
-References: [official Cloud Connector API](https://developer.ui.com/site-manager/v1.0.0) and the [Art-of-WiFi controller client](https://github.com/Art-of-WiFi/UniFi-API-client/blob/master/src/Client.php), whose session queries use epoch seconds.
+MIT — see [LICENSE](LICENSE).

package/dist/client.d.ts

@@ -1,10 +1,21 @@
 import { Config } from "./config.js";
+/** Run fn so that every request it makes is aborted when signal is. */
+export declare function withCallSignal<T>(signal: AbortSignal | undefined, fn: () => T): T;
 export declare class NetworkClient {
-    private baseUrl;
     private headers;
     private networkUrl;
+    private dispatcher;
+    private policy;
     constructor(config: Config);
+    /**
+     * path is relative to the Integration API, as the tools pass it. The guard
+     * sees it as the canonical path under the Network application; the host and
+     * any Cloud Connector prefix are added only once it has passed.
+     */
     private request;
+    private send;
+    /** Check a request against the guard before anything is sent, and note writes for the write log. */
+    private guard;
     get(path: string): Promise<unknown>;
     post(path: string, body?: unknown): Promise<unknown>;
     put(path: string, body: unknown): Promise<unknown>;
@@ -20,4 +31,5 @@ export declare class NetworkClient {
     }): Promise<unknown>;
     private validateSiteReference;
     private historyRequest;
+    private readHistory;
 }