@owine/unifi-network-mcp 2.12.0 → 2.14.0

package/README.md

@@ -1,6 +1,6 @@
 # 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 74 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 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.
 
 ## Prerequisites
 
@@ -79,11 +79,11 @@ This server provides layered safety controls for responsible operation:
 
 ## Structured Output
 
-58 of the 74 tools (all 41 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.
+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.5.43. 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 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.
 
-## Tools (74 total)
+## Tools (76 total)
 
 ### System (1)
 | Tool | Description |
@@ -115,6 +115,12 @@ 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)
+| 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)
 | Tool | Description |
 |---|---|
@@ -245,3 +251,23 @@ git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"
 ## 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.

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { Config } from "./config.js";
 export declare class NetworkClient {
     private baseUrl;
     private headers;
+    private networkUrl;
     constructor(config: Config);
     private request;
     get(path: string): Promise<unknown>;
@@ -9,4 +10,14 @@ export declare class NetworkClient {
     put(path: string, body: unknown): Promise<unknown>;
     patch(path: string, body: unknown): Promise<unknown>;
     delete(path: string): Promise<unknown>;
+    /** These controller endpoints are read queries, including stat/session's POST. */
+    getClientHistory(siteReference: string, withinHours: number): Promise<unknown>;
+    getClientSessions(siteReference: string, query: {
+        start: number;
+        end: number;
+        limit: number;
+        mac?: string;
+    }): Promise<unknown>;
+    private validateSiteReference;
+    private historyRequest;
 }

package/dist/client.js

@@ -4,8 +4,18 @@ exports.NetworkClient = void 0;
 class NetworkClient {
     baseUrl;
     headers;
+    networkUrl;
     constructor(config) {
-        this.baseUrl = `https://${config.host}/proxy/network/integration/v1`;
+        // Cloud Connector only exists behind api.ui.com. A console ID set against a
+        // local controller is ignored rather than fatal: the other tools work fine
+        // against that controller, and taking the whole server down helps nobody.
+        const useConnector = config.consoleId !== undefined && config.host === "api.ui.com";
+        if (config.consoleId !== undefined && !useConnector) {
+            console.error(`Ignoring UNIFI_NETWORK_CONSOLE_ID: Cloud Connector requires host api.ui.com, but host is ${config.host}.`);
+        }
+        const consolePath = useConnector ? `/v1/connector/consoles/${config.consoleId}` : "";
+        this.networkUrl = `https://${config.host}${consolePath}/proxy/network`;
+        this.baseUrl = `${this.networkUrl}/integration/v1`;
         this.headers = {
             "X-API-KEY": config.apiKey,
             "Content-Type": "application/json",
@@ -49,5 +59,84 @@ class NetworkClient {
     async delete(path) {
         return this.request("DELETE", path);
     }
+    /** These controller endpoints are read queries, including stat/session's POST. */
+    async getClientHistory(siteReference, withinHours) {
+        this.validateSiteReference(siteReference);
+        if (!Number.isInteger(withinHours) || withinHours < 1 || withinHours > 8760) {
+            throw new Error("withinHours must be an integer from 1 to 8760");
+        }
+        return this.historyRequest(`/v2/api/site/${siteReference}/clients/history?withinHours=${withinHours}`);
+    }
+    async getClientSessions(siteReference, query) {
+        this.validateSiteReference(siteReference);
+        const { start, end, limit, mac } = query;
+        if (![start, end, limit].every(Number.isSafeInteger) || start < 0 || end > 4102444800 ||
+            end <= start || end - start > 31 * 86400 || limit < 1 || limit > 1000 ||
+            (mac !== undefined && !/^([\da-f]{2}:){5}[\da-f]{2}$/i.test(mac))) {
+            throw new Error("Invalid session query: use epoch seconds, an increasing window of at most 31 days, a valid limit and MAC");
+        }
+        return this.historyRequest(`/api/s/${siteReference}/stat/session`, {
+            type: "all", start, end, _limit: limit, _sort: "-assoc_time",
+            ...(mac ? { mac: mac.toLowerCase() } : {}),
+        });
+    }
+    validateSiteReference(siteReference) {
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(siteReference)) {
+            throw new Error("Use the site's internalReference from unifi_list_sites (for example default)");
+        }
+    }
+    async historyRequest(path, body) {
+        const response = await fetch(`${this.networkUrl}${path}`, {
+            method: body === undefined ? "GET" : "POST", headers: this.headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            redirect: "error", signal: AbortSignal.timeout(25000),
+        });
+        if (!response.ok) {
+            // Drain before throwing: an unread body pins the socket until GC, so a
+            // run of failures (say, a mis-scoped API key) would leak connections.
+            await response.body?.cancel();
+            throw new Error(`Controller history returned HTTP ${response.status}; verify API-key access and controller support. This is not an empty history result.`);
+        }
+        if (!response.headers.get("content-type")?.includes("application/json")) {
+            await response.body?.cancel();
+            throw new Error("Controller history returned non-JSON data; verify controller authentication");
+        }
+        // Bound the body before parsing: controller session records can be large.
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error("Controller history returned no response body");
+        const chunks = [];
+        let bytes = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                bytes += value.length;
+                if (bytes > 10000000) {
+                    await reader.cancel();
+                    throw new Error("Controller history exceeds 10 MB; reduce the page size or time window");
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const text = Buffer.concat(chunks).toString("utf8");
+        if (text.trim() === "") {
+            // A bare JSON.parse would surface "Unexpected end of JSON input", which
+            // reads as a broken tool rather than an unusable controller response.
+            throw new Error("Controller history returned an empty body; verify controller support. This is not an empty history result.");
+        }
+        const result = JSON.parse(text);
+        if (result && typeof result === "object" && "meta" in result) {
+            const meta = result.meta;
+            if (meta && typeof meta === "object" && "rc" in meta && meta.rc !== "ok") {
+                throw new Error("Controller rejected the history query (meta.rc is not ok)");
+            }
+        }
+        return result;
+    }
 }
 exports.NetworkClient = NetworkClient;

package/dist/config.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 declare const configSchema: z.ZodObject<{
     host: z.ZodString;
     apiKey: z.ZodString;
+    consoleId: z.ZodOptional<z.ZodString>;
     verifySsl: z.ZodDefault<z.ZodBoolean>;
     readOnly: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;

package/dist/config.js

@@ -5,6 +5,11 @@ const zod_1 = require("zod");
 const configSchema = zod_1.z.object({
     host: zod_1.z.string().min(1).describe("UniFi Network host (IP or hostname)"),
     apiKey: zod_1.z.string().min(1).describe("UniFi Network API key"),
+    // Console/host IDs are hex, UUID- or colon-shaped depending on vintage, so
+    // hyphens and underscores are allowed; the charset still excludes anything
+    // that could escape the URL path segment it is interpolated into.
+    consoleId: zod_1.z.string().regex(/^[A-Za-z0-9:_-]{1,128}$/).optional()
+        .describe("Optional Cloud Connector console ID; only used when host is api.ui.com"),
     verifySsl: zod_1.z
         .boolean()
         .default(true)
@@ -18,6 +23,8 @@ function loadConfig() {
     const result = configSchema.safeParse({
         host: process.env.UNIFI_NETWORK_HOST,
         apiKey: process.env.UNIFI_NETWORK_API_KEY,
+        ...(process.env.UNIFI_NETWORK_CONSOLE_ID
+            ? { consoleId: process.env.UNIFI_NETWORK_CONSOLE_ID } : {}),
         verifySsl: process.env.UNIFI_NETWORK_VERIFY_SSL?.toLowerCase() !== "false",
         readOnly: process.env.UNIFI_NETWORK_READ_ONLY?.toLowerCase() !== "false",
     });

package/dist/tools/acl.js

@@ -8,7 +8,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
 function registerAclTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_acl_rules", {
-        description: "List ACL rules (switch/AP-level access control lists, distinct from zone-based firewall policies) at a site. Returns: id, type (IPV4/MAC), name, enabled, action (ALLOW/BLOCK), description, protocolFilter, source/destination matchers. ACLs apply earlier in the path than firewall policies.",
+        description: "List ACL rules (switch/AP-level access control lists, distinct from zone-based firewall policies) at a site. Returns: id, type (IPV4/MAC), name, enabled, action (ALLOW/BLOCK), description, protocolFilter, sourceFilter/destinationFilter matchers, enforcingDeviceFilter (which devices apply the rule), index (evaluation order — read-only; change it with unifi_reorder_acl_rules), metadata.origin. ACLs apply earlier in the path than firewall policies.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -20,7 +20,7 @@ function registerAclTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),

package/dist/tools/client-history.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { NetworkClient } from "../client.js";
+export declare function registerClientHistoryTools(server: McpServer, client: NetworkClient): void;

package/dist/tools/client-history.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerClientHistoryTools = registerClientHistoryTools;
+const zod_1 = require("zod");
+const responses_js_1 = require("../utils/responses.js");
+const safety_js_1 = require("../utils/safety.js");
+const output_schemas_js_1 = require("../utils/output-schemas.js");
+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.",
+        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,
+    }, async ({ siteReference, withinHours }) => {
+        try {
+            const data = zod_1.z.array(output_schemas_js_1.HistoryClient).parse(await client.getClientHistory(siteReference, withinHours));
+            return (0, responses_js_1.formatSuccess)({ data, count: data.length, withinHours, coverage: "Historical client inventory returned by the controller; not a complete session log." }, { structured: true });
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.registerTool("unifi_list_client_sessions", {
+        description: "Read retained past client connections, including disconnected clients, from the controller stat/session query endpoint. POST here only reads statistics. Returns controller session IDs, MACs, assoc_time (epoch seconds), duration (seconds), rx_bytes/tx_bytes (controller perspective), and roaming_sessions when available. Use an explicit UTC epoch-second window (max 31 days). If mayBeTruncated is true, split the time window (overlap boundaries and deduplicate IDs) or filter by MAC. The controller ignores offset pagination. Records reflect controller retention and may omit ongoing sessions. Wi-Fi association/bytes do not establish end-to-end Internet success. Do not interpret controller is_guest as proof of a person's identity or ownership.",
+        inputSchema: {
+            siteReference,
+            start: zod_1.z.number().int().min(0).max(4102444800).describe("Start Unix epoch seconds, not milliseconds"),
+            end: zod_1.z.number().int().min(1).max(4102444800).describe("End Unix epoch seconds; after start and at most 31 days later"),
+            mac: zod_1.z.string().regex(/^([\da-f]{2}:){5}[\da-f]{2}$/i).optional().describe("Optional client MAC address"),
+            limit: zod_1.z.number().int().min(1).max(1000).default(1000).describe("Maximum records; a full result requires a narrower window or MAC filter"),
+        },
+        outputSchema: output_schemas_js_1.listClientSessionsOutputSchema,
+        annotations: safety_js_1.READ_ONLY,
+    }, async ({ siteReference, start, end, limit, mac }) => {
+        try {
+            if (end <= start || end - start > 31 * 86400)
+                throw new Error("Use an increasing time window of at most 31 days");
+            const { data: rows } = output_schemas_js_1.ClientSessionEnvelope.parse(await client.getClientSessions(siteReference, { start, end, limit, mac }));
+            // The controller honours neither _start nor _limit reliably, and can
+            // repeat a session ID across roaming records. Normalise instead of
+            // rejecting: a usable page is better than an error with no data.
+            const seen = new Set();
+            const deduped = [];
+            for (const row of rows) {
+                if (seen.has(row._id))
+                    continue;
+                seen.add(row._id);
+                deduped.push(row);
+            }
+            const data = deduped.slice(0, limit);
+            const mayBeTruncated = deduped.length >= limit;
+            return (0, responses_js_1.formatSuccess)({ data, count: data.length, limit, mayBeTruncated, start, end,
+                coverage: "Retained controller sessions; A non-truncated response does not prove retention coverage or include every ongoing connection." }, { structured: true });
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+}

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, connectedAt, uplinkDeviceId (the switch/AP they're attached to), access.type. NOTE: verified against 10.5.43 — 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.",
+        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.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -20,7 +20,7 @@ function registerClientTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -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. 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 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.",
         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. Idempotent.",
+        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.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             clientId: zod_1.z.string().describe("Client ID"),

package/dist/tools/devices.js

@@ -22,7 +22,7 @@ function registerDeviceTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -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, 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): 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.",
         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.5.43 — 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), 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.",
         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.5.43 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 10.6.106 docs). Use for: discovering new devices on the network before calling unifi_adopt_device.",
         inputSchema: {
             offset: zod_1.z
                 .number()
@@ -86,7 +86,7 @@ function registerDeviceTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -111,7 +111,9 @@ function registerDeviceTools(server, client, readOnly = false) {
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             macAddress: zod_1.z.string().describe("MAC address of the device"),
-            ignoreDeviceLimit: zod_1.z.boolean().optional().describe("Ignore device limit when adopting (default: false)"),
+            // Required by the API; kept optional here and defaulted to false below
+            // so callers need not pass it explicitly.
+            ignoreDeviceLimit: zod_1.z.boolean().optional().describe("Ignore device limit when adopting (required by the API; sent as false when omitted)"),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },
         outputSchema: adoptDeviceOutputSchema,

package/dist/tools/dns-policies.js

@@ -8,7 +8,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
 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.",
+        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.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -20,7 +20,7 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),

package/dist/tools/firewall.js

@@ -20,7 +20,7 @@ function registerFirewallTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -71,7 +71,7 @@ function registerFirewallTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -270,7 +270,7 @@ function registerFirewallTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_patch_firewall_policy", {
-        description: "Partially update a firewall policy without resending all fields. Common use: toggle loggingEnabled or enabled. Idempotent for fields supplied.",
+        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.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             firewallPolicyId: zod_1.z.string().describe("Firewall policy ID"),

package/dist/tools/hotspot.js

@@ -21,7 +21,7 @@ function registerHotspotTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(1000)
                 .optional()
                 .default(100)
@@ -143,7 +143,7 @@ function registerHotspotTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_delete_voucher", {
-        description: "DESTRUCTIVE: Delete a hotspot voucher",
+        description: "DESTRUCTIVE: Delete a hotspot voucher. Returns: vouchersDeleted (count of vouchers removed).",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             voucherId: zod_1.z.string().describe("Voucher ID"),
@@ -173,12 +173,12 @@ function registerHotspotTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_bulk_delete_vouchers", {
-        description: "DESTRUCTIVE: Bulk delete hotspot vouchers based on filter criteria",
+        description: "DESTRUCTIVE: Bulk delete hotspot vouchers based on filter criteria. Returns: vouchersDeleted (count of vouchers removed).",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             filter: zod_1.z
                 .string()
-                .describe("Required filter expression (e.g., 'expired.eq(true)', 'name.like(guest*)')"),
+                .describe("Required filter expression (e.g., 'expired.eq(true)', name.like('guest*'))"),
             confirm: zod_1.z
                 .boolean()
                 .optional()

package/dist/tools/index.js

@@ -5,6 +5,7 @@ const system_js_1 = require("./system.js");
 const sites_js_1 = require("./sites.js");
 const devices_js_1 = require("./devices.js");
 const clients_js_1 = require("./clients.js");
+const client_history_js_1 = require("./client-history.js");
 const networks_js_1 = require("./networks.js");
 const wifi_js_1 = require("./wifi.js");
 const hotspot_js_1 = require("./hotspot.js");
@@ -19,6 +20,7 @@ function registerAllTools(server, client, readOnly = false) {
     (0, sites_js_1.registerSiteTools)(server, client);
     (0, devices_js_1.registerDeviceTools)(server, client, readOnly);
     (0, clients_js_1.registerClientTools)(server, client, readOnly);
+    (0, client_history_js_1.registerClientHistoryTools)(server, client);
     (0, networks_js_1.registerNetworkTools)(server, client, readOnly);
     (0, wifi_js_1.registerWifiTools)(server, client, readOnly);
     (0, hotspot_js_1.registerHotspotTools)(server, client, readOnly);

package/dist/tools/networks.js

@@ -8,7 +8,7 @@ const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
 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), dhcpGuarding, metadata.origin. NOTE: the list view is sparse — for subnet/DHCP/NTP detail (ipv4Configuration), 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, 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.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -20,7 +20,7 @@ function registerNetworkTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -42,7 +42,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) zoneId, isolationEnabled, internetAccessEnabled, mdnsForwardingEnabled, cellularBackupEnabled, and a full ipv4Configuration object (hostIpAddress, prefixLength, dhcpConfiguration with ipAddressRange/leaseTimeSeconds/domainName/ntpServerIpAddresses). 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), 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).",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             networkId: zod_1.z.string().describe("Network ID"),

package/dist/tools/sites.js

@@ -19,14 +19,14 @@ function registerSiteTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression (e.g., 'name.like(office*)')"),
+                .describe("Filter expression (e.g., name.like('office*'))"),
         },
         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.5.43 — 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 10.6.106 — 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
@@ -20,7 +20,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -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.5.43 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 10.6.106 docs — 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
@@ -50,7 +50,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -84,7 +84,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -118,7 +118,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -152,7 +152,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -185,7 +185,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -218,7 +218,7 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -251,14 +251,14 @@ function registerSupportingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
             filter: zod_1.z
                 .string()
                 .optional()
-                .describe("Filter expression (e.g., 'name.like(United*)')"),
+                .describe("Filter expression (e.g., name.like('United*'))"),
         },
         outputSchema: output_schemas_js_1.listCountriesOutputSchema,
         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, name, members[], lags[] (LAGs spanning the stack), metadata.origin. 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 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.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             offset: zod_1.z
@@ -20,7 +20,7 @@ function registerSwitchingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -42,7 +42,7 @@ function registerSwitchingTools(server, client) {
         }
     });
     server.registerTool("unifi_get_switch_stack", {
-        description: "Get full details of a Switch Stack including all members and stacking topology. Returns the same fields as the list response but for a single stack.",
+        description: "Get full details of a Switch Stack including all units and stacking topology. Returns the same fields as the list response but for a single stack: id, deviceId, name, units[] (named `members` before 10.6.106), lags[], metadata.origin.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             switchStackId: zod_1.z.string().describe("Switch Stack ID"),
@@ -71,7 +71,7 @@ function registerSwitchingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -122,7 +122,7 @@ function registerSwitchingTools(server, client) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),

package/dist/tools/system.js

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

package/dist/tools/traffic-matching.js

@@ -20,7 +20,7 @@ function registerTrafficMatchingTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),

package/dist/tools/wifi.js

@@ -20,7 +20,7 @@ function registerWifiTools(server, client, readOnly = false) {
             limit: zod_1.z
                 .number()
                 .int()
-                .min(1)
+                .min(0)
                 .max(200)
                 .optional()
                 .describe("Number of records to return (default: 25, max: 200)"),
@@ -68,8 +68,8 @@ function registerWifiTools(server, client, readOnly = false) {
             enabled: zod_1.z.boolean().describe("Enable the WiFi network"),
             type: zod_1.z.enum(["STANDARD", "IOT_OPTIMIZED"]).describe("WiFi type"),
             broadcastingFrequenciesGHz: zod_1.z
-                .array(zod_1.z.string())
-                .describe("Frequencies: 2.4, 5, 6"),
+                .array(zod_1.z.enum(["2.4", "5", "6"]))
+                .describe("Frequencies to broadcast on. Accepted as strings and sent to the API as numbers (2.4, 5, 6)."),
             securityConfiguration: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
                 .describe("Security configuration object"),
@@ -209,7 +209,7 @@ function registerWifiTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_wifi", {
-        description: "Update an existing WiFi network",
+        description: "Update an existing WiFi network. NOTE: this is a full PUT — API 10.6.106 documents 14 of these fields as required (type, name, enabled, securityConfiguration, multicastToUnicastConversionEnabled, clientIsolationEnabled, hideName, uapsdEnabled, channel2gLockedTo6, dtimPeriod2gLockedTo3, broadcastingFrequenciesGHz, arpProxyEnabled, bssTransitionEnabled, advertiseDeviceName). They are optional here for convenience, but a sparse update may be rejected by the API — read the current values with unifi_get_wifi and resend the full set if you get a 400.",
         inputSchema: {
             siteId: zod_1.z.string().describe("Site ID"),
             wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
@@ -220,9 +220,9 @@ function registerWifiTools(server, client, readOnly = false) {
                 .optional()
                 .describe("WiFi type"),
             broadcastingFrequenciesGHz: zod_1.z
-                .array(zod_1.z.string())
+                .array(zod_1.z.enum(["2.4", "5", "6"]))
                 .optional()
-                .describe("Frequencies: 2.4, 5, 6"),
+                .describe("Frequencies to broadcast on. Accepted as strings and sent to the API as numbers (2.4, 5, 6)."),
             securityConfiguration: zod_1.z
                 .record(zod_1.z.string(), zod_1.z.unknown())
                 .optional()

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

@@ -3,7 +3,7 @@
  * field optional, every nested object uses .passthrough() to allow
  * firmware/hardware-specific fields to flow through unchanged).
  *
- * Verified against UniFi Network API 10.5.43. Where the docs collapse
+ * Verified against UniFi Network API 10.6.106. Where the docs collapse
  * nested arrays/objects (e.g. interfaces.ports[], radios[]), the schema
  * uses passthrough records so the contract doesn't lock to fields we
  * haven't verified.
@@ -37,6 +37,7 @@ export declare const networkOutputSchema: {
     cellularBackupEnabled: z.ZodOptional<z.ZodBoolean>;
     dhcpGuarding: z.ZodOptional<z.ZodUnknown>;
     ipv4Configuration: z.ZodOptional<z.ZodUnknown>;
+    ipv6Configuration: z.ZodOptional<z.ZodUnknown>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
@@ -60,6 +61,7 @@ export declare const listNetworksOutputSchema: {
         cellularBackupEnabled: z.ZodOptional<z.ZodBoolean>;
         dhcpGuarding: z.ZodOptional<z.ZodUnknown>;
         ipv4Configuration: z.ZodOptional<z.ZodUnknown>;
+        ipv6Configuration: z.ZodOptional<z.ZodUnknown>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
@@ -202,6 +204,7 @@ export declare const aclRuleOutputSchema: {
     sourceFilter: z.ZodOptional<z.ZodUnknown>;
     destinationFilter: z.ZodOptional<z.ZodUnknown>;
     enforcingDeviceFilter: z.ZodOptional<z.ZodUnknown>;
+    index: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodObject<{
         origin: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
@@ -222,6 +225,7 @@ export declare const listAclRulesOutputSchema: {
         sourceFilter: z.ZodOptional<z.ZodUnknown>;
         destinationFilter: z.ZodOptional<z.ZodUnknown>;
         enforcingDeviceFilter: z.ZodOptional<z.ZodUnknown>;
+        index: z.ZodOptional<z.ZodNumber>;
         metadata: z.ZodOptional<z.ZodObject<{
             origin: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
@@ -233,6 +237,8 @@ export declare const aclRuleOrderingOutputSchema: {
 export declare const switchStackOutputSchema: {
     id: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    deviceId: z.ZodOptional<z.ZodString>;
+    units: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     members: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     lags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     metadata: z.ZodOptional<z.ZodObject<{
@@ -247,6 +253,8 @@ export declare const listSwitchStacksOutputSchema: {
     readonly data: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodOptional<z.ZodString>;
+        deviceId: z.ZodOptional<z.ZodString>;
+        units: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
         members: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
         lags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
         metadata: z.ZodOptional<z.ZodObject<{
@@ -607,3 +615,73 @@ export declare const listPendingDevicesOutputSchema: {
         firmwareVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
 };
+export declare const HistoryClient: z.ZodObject<{
+    mac: z.ZodString;
+    hostname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    first_seen: z.ZodOptional<z.ZodNumber>;
+    last_seen: z.ZodOptional<z.ZodNumber>;
+    is_wired: z.ZodOptional<z.ZodBoolean>;
+    status: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const ClientSession: z.ZodObject<{
+    _id: z.ZodString;
+    mac: z.ZodString;
+    assoc_time: z.ZodNumber;
+    duration: z.ZodOptional<z.ZodNumber>;
+    rx_bytes: z.ZodOptional<z.ZodNumber>;
+    tx_bytes: z.ZodOptional<z.ZodNumber>;
+    hostname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_wired: z.ZodOptional<z.ZodBoolean>;
+    roaming_sessions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$loose>;
+/** Envelope returned by the controller's stat/session endpoint. */
+export declare const ClientSessionEnvelope: z.ZodObject<{
+    meta: z.ZodObject<{
+        rc: z.ZodLiteral<"ok">;
+    }, z.core.$loose>;
+    data: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        mac: z.ZodString;
+        assoc_time: z.ZodNumber;
+        duration: z.ZodOptional<z.ZodNumber>;
+        rx_bytes: z.ZodOptional<z.ZodNumber>;
+        tx_bytes: z.ZodOptional<z.ZodNumber>;
+        hostname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        is_wired: z.ZodOptional<z.ZodBoolean>;
+        roaming_sessions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export declare const listClientHistoryOutputSchema: {
+    readonly data: z.ZodArray<z.ZodObject<{
+        mac: z.ZodString;
+        hostname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        first_seen: z.ZodOptional<z.ZodNumber>;
+        last_seen: z.ZodOptional<z.ZodNumber>;
+        is_wired: z.ZodOptional<z.ZodBoolean>;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    readonly count: z.ZodNumber;
+    readonly withinHours: z.ZodNumber;
+    readonly coverage: z.ZodString;
+};
+export declare const listClientSessionsOutputSchema: {
+    readonly data: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        mac: z.ZodString;
+        assoc_time: z.ZodNumber;
+        duration: z.ZodOptional<z.ZodNumber>;
+        rx_bytes: z.ZodOptional<z.ZodNumber>;
+        tx_bytes: z.ZodOptional<z.ZodNumber>;
+        hostname: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        is_wired: z.ZodOptional<z.ZodBoolean>;
+        roaming_sessions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$loose>>;
+    readonly count: z.ZodNumber;
+    readonly limit: z.ZodNumber;
+    readonly mayBeTruncated: z.ZodBoolean;
+    readonly start: z.ZodNumber;
+    readonly end: z.ZodNumber;
+    readonly coverage: z.ZodString;
+};

package/dist/utils/output-schemas.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listPendingDevicesOutputSchema = exports.listCountriesOutputSchema = exports.listDpiApplicationsOutputSchema = exports.listDpiCategoriesOutputSchema = exports.listDeviceTagsOutputSchema = exports.listRadiusProfilesOutputSchema = exports.listVpnTunnelsOutputSchema = exports.listVpnServersOutputSchema = exports.listWansOutputSchema = exports.getWifiOutputSchema = exports.listWifiOutputSchema = exports.getClientOutputSchema = exports.listClientsOutputSchema = exports.getDeviceStatisticsOutputSchema = exports.getDeviceOutputSchema = exports.listDevicesOutputSchema = exports.listTrafficMatchingListsOutputSchema = exports.trafficMatchingListOutputSchema = exports.listDnsPoliciesOutputSchema = exports.dnsPolicyOutputSchema = exports.listLagsOutputSchema = exports.lagOutputSchema = exports.listMcLagDomainsOutputSchema = exports.mcLagDomainOutputSchema = exports.listSwitchStacksOutputSchema = exports.switchStackOutputSchema = exports.aclRuleOrderingOutputSchema = exports.listAclRulesOutputSchema = exports.aclRuleOutputSchema = exports.firewallPolicyOrderingOutputSchema = exports.listFirewallPoliciesOutputSchema = exports.firewallPolicyOutputSchema = exports.listFirewallZonesOutputSchema = exports.firewallZoneOutputSchema = exports.createVouchersOutputSchema = exports.listVouchersOutputSchema = exports.voucherOutputSchema = exports.getNetworkReferencesOutputSchema = exports.listNetworksOutputSchema = exports.networkOutputSchema = exports.listSitesOutputSchema = exports.getInfoOutputSchema = void 0;
+exports.listClientSessionsOutputSchema = exports.listClientHistoryOutputSchema = exports.ClientSessionEnvelope = exports.ClientSession = exports.HistoryClient = exports.listPendingDevicesOutputSchema = exports.listCountriesOutputSchema = exports.listDpiApplicationsOutputSchema = exports.listDpiCategoriesOutputSchema = exports.listDeviceTagsOutputSchema = exports.listRadiusProfilesOutputSchema = exports.listVpnTunnelsOutputSchema = exports.listVpnServersOutputSchema = exports.listWansOutputSchema = exports.getWifiOutputSchema = exports.listWifiOutputSchema = exports.getClientOutputSchema = exports.listClientsOutputSchema = exports.getDeviceStatisticsOutputSchema = exports.getDeviceOutputSchema = exports.listDevicesOutputSchema = exports.listTrafficMatchingListsOutputSchema = exports.trafficMatchingListOutputSchema = exports.listDnsPoliciesOutputSchema = exports.dnsPolicyOutputSchema = exports.listLagsOutputSchema = exports.lagOutputSchema = exports.listMcLagDomainsOutputSchema = exports.mcLagDomainOutputSchema = exports.listSwitchStacksOutputSchema = exports.switchStackOutputSchema = exports.aclRuleOrderingOutputSchema = exports.listAclRulesOutputSchema = exports.aclRuleOutputSchema = exports.firewallPolicyOrderingOutputSchema = exports.listFirewallPoliciesOutputSchema = exports.firewallPolicyOutputSchema = exports.listFirewallZonesOutputSchema = exports.firewallZoneOutputSchema = exports.createVouchersOutputSchema = exports.listVouchersOutputSchema = exports.voucherOutputSchema = exports.getNetworkReferencesOutputSchema = exports.listNetworksOutputSchema = exports.networkOutputSchema = exports.listSitesOutputSchema = exports.getInfoOutputSchema = void 0;
 /**
  * Output schemas for high-value read tools (loose strategy: every non-key
  * field optional, every nested object uses .passthrough() to allow
  * firmware/hardware-specific fields to flow through unchanged).
  *
- * Verified against UniFi Network API 10.5.43. Where the docs collapse
+ * Verified against UniFi Network API 10.6.106. Where the docs collapse
  * nested arrays/objects (e.g. interfaces.ports[], radios[]), the schema
  * uses passthrough records so the contract doesn't lock to fields we
  * haven't verified.
@@ -160,7 +160,7 @@ const WifiBroadcast = zod_1.z
     .passthrough();
 const ApplicationInfo = zod_1.z
     .object({
-    // Live-verified (10.5.43): only applicationVersion is returned.
+    // Live-verified (10.6.106): only applicationVersion is returned.
     applicationVersion: zod_1.z.string().optional(),
 })
     .passthrough();
@@ -185,8 +185,9 @@ const Network = zod_1.z
     mdnsForwardingEnabled: zod_1.z.boolean().optional(),
     cellularBackupEnabled: zod_1.z.boolean().optional(),
     dhcpGuarding: zod_1.z.unknown().optional(),
-    // get-by-id only (absent in list view); nested shape left loose.
+    // get-by-id only (absent in list view); nested shapes left loose.
     ipv4Configuration: zod_1.z.unknown().optional(),
+    ipv6Configuration: zod_1.z.unknown().optional(),
     metadata: Metadata.optional(),
 })
     .passthrough();
@@ -263,6 +264,9 @@ const AclRule = zod_1.z
     sourceFilter: zod_1.z.unknown().optional(),
     destinationFilter: zod_1.z.unknown().optional(),
     enforcingDeviceFilter: zod_1.z.unknown().optional(),
+    // Read-only in the response. Deprecated as a *request* field — ordering
+    // is set via the dedicated reorder endpoint, so no write tool accepts it.
+    index: zod_1.z.number().int().optional(),
     metadata: Metadata.optional(),
 })
     .passthrough();
@@ -275,6 +279,12 @@ const SwitchStack = zod_1.z
     .object({
     id: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    // The stack's primary device. Added in 10.6.106.
+    deviceId: zod_1.z.string().optional(),
+    // Renamed from `members` in 10.6.106 (was `members` through 10.4.57).
+    // `members` stays declared so responses from older consoles still
+    // describe themselves; both are optional, so either shape validates.
+    units: zod_1.z.array(zod_1.z.unknown()).optional(),
     members: zod_1.z.array(zod_1.z.unknown()).optional(),
     lags: zod_1.z.array(zod_1.z.unknown()).optional(),
     metadata: Metadata.optional(),
@@ -324,7 +334,7 @@ const TrafficMatchingList = zod_1.z
     metadata: Metadata.optional(),
 })
     .passthrough();
-// Verified against the live Integration API (10.5.43). The WAN and
+// Verified against the live Integration API (10.6.106). The WAN and
 // site-to-site-tunnel list rows are intentionally minimal in the API.
 const Wan = zod_1.z
     .object({
@@ -509,3 +519,50 @@ exports.listPendingDevicesOutputSchema = {
     ...PaginationFields,
     data: zod_1.z.array(PendingDevice),
 };
+// Controller history endpoints (v2 clients/history and stat/session) are not
+// part of the Integration API, so these follow the same loose strategy against
+// the controller's own response shape: only the identity fields are required.
+exports.HistoryClient = zod_1.z
+    .object({
+    mac: zod_1.z.string(),
+    hostname: zod_1.z.string().nullish(),
+    display_name: zod_1.z.string().nullish(),
+    first_seen: zod_1.z.number().optional(),
+    last_seen: zod_1.z.number().optional(),
+    is_wired: zod_1.z.boolean().optional(),
+    status: zod_1.z.string().optional(),
+})
+    .passthrough();
+exports.ClientSession = zod_1.z
+    .object({
+    _id: zod_1.z.string(),
+    mac: zod_1.z.string(),
+    assoc_time: zod_1.z.number(),
+    duration: zod_1.z.number().optional(),
+    rx_bytes: zod_1.z.number().optional(),
+    tx_bytes: zod_1.z.number().optional(),
+    hostname: zod_1.z.string().nullish(),
+    is_wired: zod_1.z.boolean().optional(),
+    roaming_sessions: zod_1.z.array(zod_1.z.unknown()).optional(),
+})
+    .passthrough();
+/** Envelope returned by the controller's stat/session endpoint. */
+exports.ClientSessionEnvelope = zod_1.z.object({
+    meta: zod_1.z.object({ rc: zod_1.z.literal("ok") }).passthrough(),
+    data: zod_1.z.array(exports.ClientSession),
+});
+exports.listClientHistoryOutputSchema = {
+    data: zod_1.z.array(exports.HistoryClient),
+    count: zod_1.z.number(),
+    withinHours: zod_1.z.number(),
+    coverage: zod_1.z.string(),
+};
+exports.listClientSessionsOutputSchema = {
+    data: zod_1.z.array(exports.ClientSession),
+    count: zod_1.z.number(),
+    limit: zod_1.z.number(),
+    mayBeTruncated: zod_1.z.boolean(),
+    start: zod_1.z.number(),
+    end: zod_1.z.number(),
+    coverage: zod_1.z.string(),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-network-mcp",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "MCP server for the UniFi Network API",
   "main": "dist/index.js",
   "bin": {
@@ -22,7 +22,7 @@
   "engines": {
     "node": "^22.13.0 || ^24.0.0"
   },
-  "packageManager": "pnpm@12.3.4",
+  "packageManager": "pnpm@12.5.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/owine/unifi-network-mcp.git"
@@ -38,17 +38,17 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.13.3",
+    "@types/node": "24.13.6",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.10.0",
-    "lefthook": "2.1.12",
+    "@vitest/coverage-v8": "5.0.1",
+    "eslint": "10.11.0",
+    "lefthook": "2.1.14",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.69.0",
-    "vitest": "4.1.11"
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.1"
   }
 }