@owine/unifi-network-mcp 2.13.0 → 2.14.1

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.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/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 (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.",
+        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

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/utils/output-schemas.d.ts

@@ -615,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,6 +1,6 @@
 "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
@@ -519,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.13.0",
+  "version": "2.14.1",
   "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.4.1",
+  "packageManager": "pnpm@12.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/owine/unifi-network-mcp.git"
@@ -37,18 +37,18 @@
   "author": "owine",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "zod": "4.6.2"
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.13.4",
+    "@types/node": "24.19.0",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.10.0",
-    "lefthook": "2.1.12",
+    "@vitest/coverage-v8": "5.0.2",
+    "eslint": "10.11.0",
+    "lefthook": "2.1.14",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.70.0",
-    "vitest": "5.0.0"
+    "typescript-eslint": "8.70.1",
+    "vitest": "5.0.2"
   }
 }