@owine/unifi-network-mcp 2.15.0 → 3.1.0

package/dist/tools/acl.js

@@ -1,29 +1,72 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAclTools = registerAclTools;
+const node_util_1 = require("node:util");
 const zod_1 = require("zod");
 const responses_js_1 = require("../utils/responses.js");
 const query_js_1 = require("../utils/query.js");
 const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+const params_js_1 = require("../utils/params.js");
+const full_put_js_1 = require("../utils/full-put.js");
+// PUT body fields per the 11.0.83 docs. index is deprecated (and read-only in
+// practice), so it stays out of the body even though GET returns it.
+const ACL_RULE_FIELDS = [
+    "type", "enabled", "name", "description", "action",
+    "enforcingDeviceFilter", "sourceFilter", "destinationFilter", "protocolFilter",
+];
+const ACL_RULE_REQUIRED = ["type", "enabled", "name", "action"];
+// The fields that decide which traffic a rule applies to.
+const ACL_MATCH_FIELDS = [
+    "type", "enforcingDeviceFilter", "sourceFilter", "destinationFilter", "protocolFilter",
+];
+// Shaped per rule type (IPV4 or MAC), so a type change does not keep them.
+const ACL_TYPE_FIELDS = ["sourceFilter", "destinationFilter", "protocolFilter"];
+/**
+ * What an ACL rule write would open, if anything. before is undefined on
+ * create. Changing what an enabled rule matches counts whatever its action:
+ * widening an ALLOW and narrowing a BLOCK both let more through, and which
+ * of the two a filter change does cannot be told from here.
+ */
+function aclOpening(before, after) {
+    if (before === undefined) {
+        return after.action === "ALLOW" ? "This creates an ACL rule that ALLOWs traffic" : undefined;
+    }
+    if (after.action === "ALLOW" && before.action !== "ALLOW")
+        return "This changes the ACL rule's action to ALLOW";
+    if (after.enabled === false) {
+        return before.enabled !== false && before.action === "BLOCK" ? "This disables an ACL rule that blocks traffic" : undefined;
+    }
+    if (before.enabled === false) {
+        return after.action === "ALLOW" ? "This enables an ACL rule that ALLOWs traffic" : undefined;
+    }
+    const changed = ACL_MATCH_FIELDS.filter((field) => !(0, node_util_1.isDeepStrictEqual)(before[field], after[field]));
+    return changed.length > 0
+        ? `This changes what an enabled ACL rule matches (${changed.join(", ")}), which can let more traffic through`
+        : undefined;
+}
+const confirmOpening = zod_1.z
+    .boolean()
+    .optional()
+    .describe("Set true to confirm a change that can let traffic through: an ALLOW action, enabling an ALLOW rule, disabling a BLOCK rule, or changing what an enabled rule matches; not needed with dryRun: true");
 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, 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"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z
                 .string()
                 .optional()
@@ -44,8 +87,8 @@ function registerAclTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_acl_rule", {
         description: "Get a specific ACL rule by ID (full match criteria and action).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            aclRuleId: zod_1.z.string().describe("ACL rule ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            aclRuleId: (0, params_js_1.resourceId)().describe("ACL rule ID"),
         },
         outputSchema: output_schemas_js_1.aclRuleOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -61,7 +104,7 @@ function registerAclTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_acl_rule_ordering", {
         description: "Get the evaluation order of user-defined ACL rules. Returns: orderedAclRuleIds[] — rules are evaluated in list order.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
         },
         outputSchema: output_schemas_js_1.aclRuleOrderingOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -79,7 +122,7 @@ function registerAclTools(server, client, readOnly = false) {
     server.registerTool("unifi_create_acl_rule", {
         description: "Create a new ACL rule",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             type: zod_1.z.enum(["IPV4", "MAC"]).describe("Rule type"),
             name: zod_1.z.string().describe("Rule name"),
             enabled: zod_1.z.boolean().describe("Enable the rule"),
@@ -91,7 +134,7 @@ function registerAclTools(server, client, readOnly = false) {
             protocolFilter: zod_1.z
                 .array(zod_1.z.enum(["TCP", "UDP"]))
                 .optional()
-                .describe("Protocols this ACL rule will be applied to (TCP, UDP). When null, applies to all protocols"),
+                .describe("Protocols this ACL rule will be applied to (TCP, UDP). Omit to apply to all protocols"),
             sourceFilter: zod_1.z
                 .unknown()
                 .optional()
@@ -104,14 +147,19 @@ function registerAclTools(server, client, readOnly = false) {
                 .unknown()
                 .optional()
                 .describe("Device filter object (with a type discriminator) selecting the switch-capable devices that enforce the rule. When null/omitted, the rule is provisioned to all switches on the site"),
+            confirm: confirmOpening,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.aclRuleOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.aclRuleOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
-    }, async ({ siteId, type, name, enabled, action, description, protocolFilter, sourceFilter, destinationFilter, enforcingDeviceFilter, dryRun }) => {
+    }, async ({ siteId, type, name, enabled, action, description, protocolFilter, sourceFilter, destinationFilter, enforcingDeviceFilter, confirm, dryRun }) => {
+        const opening = aclOpening(undefined, { action });
+        const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
+        if (guard)
+            return guard;
         try {
             const body = { type, name, enabled, action };
             if (description !== undefined)
@@ -125,7 +173,7 @@ function registerAclTools(server, client, readOnly = false) {
             if (enforcingDeviceFilter !== undefined)
                 body.enforcingDeviceFilter = enforcingDeviceFilter;
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/acl-rules`, body);
+                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/acl-rules`, body, opening);
             const data = await client.post(`/sites/${siteId}/acl-rules`, body);
             return (0, responses_js_1.formatSuccess)(data, { structured: true });
         }
@@ -134,20 +182,22 @@ function registerAclTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_update_acl_rule", {
-        description: "Update an ACL rule",
+        description: "Update an ACL rule. Pass only the fields to change. The API's PUT replaces the whole rule, and an omitted filter means \"all\" (all protocols, sources, destinations or switches), so this tool reads the current rule, overlays your fields and sends the full body. Filters are replaced whole; null clears one. Changing type drops the current source, destination and protocol filters, which are shaped per type, so pass the new type's filters with it. dryRun shows the merged body.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            aclRuleId: zod_1.z.string().describe("ACL rule ID"),
-            type: zod_1.z.enum(["IPV4", "MAC"]).describe("ACL rule type"),
-            name: zod_1.z.string().describe("ACL rule name"),
-            enabled: zod_1.z.boolean().describe("Whether the rule is enabled"),
-            action: zod_1.z.enum(["ALLOW", "BLOCK"]).describe("Rule action"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            aclRuleId: (0, params_js_1.resourceId)().describe("ACL rule ID"),
+            type: zod_1.z.enum(["IPV4", "MAC"]).optional().describe("ACL rule type"),
+            name: zod_1.z.string().min(1).optional().describe("ACL rule name"),
+            enabled: zod_1.z.boolean().optional().describe("Whether the rule is enabled"),
+            action: zod_1.z.enum(["ALLOW", "BLOCK"]).optional().describe("Rule action"),
             description: zod_1.z
                 .string()
+                .nullable()
                 .optional()
-                .describe("Rule description"),
+                .describe("Rule description; null clears it"),
             protocolFilter: zod_1.z
                 .array(zod_1.z.enum(["TCP", "UDP"]))
+                .nullable()
                 .optional()
                 .describe("Protocols this ACL rule will be applied to (TCP, UDP). When null, applies to all protocols"),
             sourceFilter: zod_1.z
@@ -162,30 +212,39 @@ function registerAclTools(server, client, readOnly = false) {
                 .unknown()
                 .optional()
                 .describe("Device filter object (with a type discriminator) selecting the switch-capable devices that enforce the rule. When null/omitted, the rule is provisioned to all switches on the site"),
+            confirm: confirmOpening,
             dryRun: zod_1.z
                 .boolean()
                 .optional()
-                .describe("Preview this action without executing it"),
+                .describe("Preview the merged PUT body without executing it (still reads the current rule)"),
         },
-        outputSchema: output_schemas_js_1.aclRuleOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.aclRuleOutputSchema),
         annotations: safety_js_1.WRITE,
-    }, async ({ siteId, aclRuleId, type, name, enabled, action, description, protocolFilter, sourceFilter, destinationFilter, enforcingDeviceFilter, dryRun }) => {
+    }, async ({ siteId, aclRuleId, confirm, dryRun, ...fields }) => {
         try {
-            const body = { type, name, enabled, action };
-            if (description !== undefined)
-                body.description = description;
-            if (protocolFilter !== undefined)
-                body.protocolFilter = protocolFilter;
-            if (sourceFilter !== undefined)
-                body.sourceFilter = sourceFilter;
-            if (destinationFilter !== undefined)
-                body.destinationFilter = destinationFilter;
-            if (enforcingDeviceFilter !== undefined)
-                body.enforcingDeviceFilter = enforcingDeviceFilter;
-            if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/acl-rules/${aclRuleId}`, body);
-            const data = await client.put(`/sites/${siteId}/acl-rules/${aclRuleId}`, body);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            const path = `/sites/${siteId}/acl-rules/${aclRuleId}`;
+            return await (0, full_put_js_1.withResourceLock)(path, async () => {
+                const current = (0, full_put_js_1.asObject)(await client.get(path), "the current ACL rule");
+                const updates = (0, full_put_js_1.definedEntries)(fields);
+                // A new type starts its filters afresh: the old type's would send
+                // a rule that mixes both shapes. Filters not given mean "all".
+                const base = updates.type !== undefined && updates.type !== current.type
+                    ? Object.fromEntries(Object.entries(current).filter(([field]) => !ACL_TYPE_FIELDS.includes(field)))
+                    : current;
+                const body = (0, full_put_js_1.mergeForPut)(base, updates, ACL_RULE_FIELDS);
+                const missing = (0, full_put_js_1.missingFields)(body, ACL_RULE_REQUIRED);
+                if (missing.length > 0) {
+                    throw new Error(`Missing required fields: ${missing.join(", ")}`);
+                }
+                const opening = aclOpening(current, body);
+                const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
+                if (guard)
+                    return guard;
+                if (dryRun)
+                    return (0, safety_js_1.formatDryRun)("PUT", path, body, opening);
+                const data = await client.put(path, body);
+                return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            });
         }
         catch (err) {
             return (0, responses_js_1.formatError)(err);
@@ -194,12 +253,9 @@ function registerAclTools(server, client, readOnly = false) {
     server.registerTool("unifi_delete_acl_rule", {
         description: "DESTRUCTIVE: Delete an ACL rule",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            aclRuleId: zod_1.z.string().describe("ACL rule ID"),
-            confirm: zod_1.z
-                .boolean()
-                .optional()
-                .describe("Must be true to execute this destructive action"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            aclRuleId: (0, params_js_1.resourceId)().describe("ACL rule ID"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -207,12 +263,12 @@ function registerAclTools(server, client, readOnly = false) {
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, aclRuleId, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the ACL rule");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will delete the ACL rule");
         if (guard)
             return guard;
         try {
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/acl-rules/${aclRuleId}`, {});
+                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/acl-rules/${aclRuleId}`);
             const data = await client.delete(`/sites/${siteId}/acl-rules/${aclRuleId}`);
             return (0, responses_js_1.formatSuccess)(data);
         }
@@ -221,24 +277,41 @@ function registerAclTools(server, client, readOnly = false) {
         }
     });
     server.registerTool("unifi_reorder_acl_rules", {
-        description: "Reorder user-defined ACL rules",
+        description: "Reorder user-defined ACL rules. Rules are evaluated in list order, so moving an ALLOW ahead of a BLOCK it used to follow lets that traffic through; such a reorder needs confirm. Reads the current order and the rules it moves past one another, on a dry run too.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             orderedAclRuleIds: zod_1.z
                 .array(zod_1.z.string())
                 .describe("Ordered ACL rule IDs"),
+            confirm: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Set true to confirm a reorder that moves an ALLOW rule ahead of a BLOCK rule it used to follow; not needed with dryRun: true"),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
                 .describe("Preview this action without executing it"),
         },
         annotations: safety_js_1.WRITE,
-    }, async ({ siteId, orderedAclRuleIds, dryRun }) => {
+    }, async ({ siteId, orderedAclRuleIds, confirm, dryRun }) => {
         try {
+            const path = `/sites/${siteId}/acl-rules/ordering`;
             const body = { orderedAclRuleIds };
+            const current = (0, full_put_js_1.asObject)(await client.get(path), "the current ACL rule ordering");
+            const before = Array.isArray(current.orderedAclRuleIds) ? current.orderedAclRuleIds.filter((id) => typeof id === "string") : [];
+            const opens = await (0, safety_js_1.reorderOpens)(before, orderedAclRuleIds, async (id) => {
+                const rule = (0, full_put_js_1.asObject)(await client.get(`/sites/${siteId}/acl-rules/${id}`), "an ACL rule");
+                // A disabled rule neither lets anything through nor blocks it.
+                const active = rule.enabled !== false;
+                return { letsThrough: active && rule.action === "ALLOW", blocks: active && rule.action === "BLOCK" };
+            });
+            const opening = opens ? "This moves an ALLOW rule ahead of a BLOCK rule it used to follow" : undefined;
+            const guard = (0, safety_js_1.requireConfirmationIf)(opening, confirm, dryRun);
+            if (guard)
+                return guard;
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/acl-rules/ordering`, body);
-            const data = await client.put(`/sites/${siteId}/acl-rules/ordering`, body);
+                return (0, safety_js_1.formatDryRun)("PUT", path, body, opening);
+            const data = await client.put(path, body);
             return (0, responses_js_1.formatSuccess)(data);
         }
         catch (err) {

package/dist/tools/classic.d.ts

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

package/dist/tools/classic.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerClassicTools = registerClassicTools;
+const responses_js_1 = require("../utils/responses.js");
+const safety_js_1 = require("../utils/safety.js");
+const params_js_1 = require("../utils/params.js");
+const pick_js_1 = require("../utils/pick.js");
+const output_schemas_js_1 = require("../utils/output-schemas.js");
+const CLASSIC_IDS = "IDs are the classic controller's _id values, which differ from Integration API IDs: do not pass one to an Integration API tool, or the reverse.";
+const ruleset = (rule) => (typeof rule.ruleset === "string" ? rule.ruleset : "");
+// A number or a numeric string, depending on the controller version.
+function ruleIndex(rule) {
+    const index = Number.parseFloat(String(rule.rule_index));
+    return Number.isNaN(index) ? Number.MAX_SAFE_INTEGER : index;
+}
+/** The order legacy rules are evaluated in; a rule with no usable index goes last in its ruleset. */
+function byEvaluationOrder(a, b) {
+    return ruleset(a).localeCompare(ruleset(b)) || ruleIndex(a) - ruleIndex(b);
+}
+function registerClassicTools(server, client) {
+    const list = (collection, row, order) => {
+        const fields = Object.keys(row.shape);
+        return async ({ siteReference }) => {
+            try {
+                const { data: rows } = output_schemas_js_1.ClassicEnvelope.parse(await client.getClassic(siteReference, collection));
+                const data = rows.map((record) => row.strip().parse((0, pick_js_1.pick)(record, fields)));
+                if (order)
+                    data.sort(order);
+                return (0, responses_js_1.formatSuccess)({ data, count: data.length, siteReference }, { structured: true });
+            }
+            catch (err) {
+                return (0, responses_js_1.formatError)(err);
+            }
+        };
+    };
+    server.registerTool("unifi_list_classic_networks", {
+        description: `List the site's networks from the classic controller API (rest/networkconf), whole and unpaged. Use it to resolve the classic network IDs legacy firewall rules reference; for everything else prefer unifi_list_networks. ${CLASSIC_IDS} Rows carry only the fields in the output schema; credentials are never returned.`,
+        inputSchema: { siteReference: (0, params_js_1.siteReference)() },
+        outputSchema: output_schemas_js_1.listClassicNetworksOutputSchema,
+        annotations: safety_js_1.READ_ONLY,
+    }, list("networkconf", output_schemas_js_1.ClassicNetwork));
+    server.registerTool("unifi_list_firewall_groups", {
+        description: `List the site's firewall groups (address, IPv6 address and port groups) from the classic controller API (rest/firewallgroup), whole and unpaged. Legacy firewall rules reference these by ID. ${CLASSIC_IDS}`,
+        inputSchema: { siteReference: (0, params_js_1.siteReference)() },
+        outputSchema: output_schemas_js_1.listFirewallGroupsOutputSchema,
+        annotations: safety_js_1.READ_ONLY,
+    }, list("firewallgroup", output_schemas_js_1.ClassicFirewallGroup));
+    server.registerTool("unifi_list_legacy_firewall_rules", {
+        description: `List the site's legacy firewall rules (WAN_IN, LAN_IN, GUEST_LOCAL and the other rulesets) from the classic controller API (rest/firewallrule), whole and unpaged. On a site that uses the zone-based firewall these rules may not be enforced; its rules are the policies unifi_list_firewall_policies returns. ${CLASSIC_IDS} Rules reference networks by unifi_list_classic_networks IDs and groups by unifi_list_firewall_groups IDs. Sorted by ruleset, then rule_index, the order they are evaluated in.`,
+        inputSchema: { siteReference: (0, params_js_1.siteReference)() },
+        outputSchema: output_schemas_js_1.listLegacyFirewallRulesOutputSchema,
+        annotations: safety_js_1.READ_ONLY,
+    }, list("firewallrule", output_schemas_js_1.LegacyFirewallRule, byEvaluationOrder));
+}

package/dist/tools/client-history.js

@@ -4,32 +4,40 @@ 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 params_js_1 = require("../utils/params.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");
+const siteReference = (0, params_js_1.siteReference)();
 function registerClientHistoryTools(server, client) {
     server.registerTool("unifi_list_client_history", {
-        description: "List historical/offline client inventory using the controller v2 API. Returns OFFLINE clients only — currently connected clients are excluded, so merge with unifi_list_clients for a full inventory. Includes names, MACs, first_seen and last_seen epoch seconds when available. This is inventory, not session history; use unifi_list_client_sessions for past connections. Requires controller history API-key support; errors never mean zero activity. Retention depends on the controller.",
-        inputSchema: { siteReference, withinHours: zod_1.z.number().int().min(1).max(8760).default(168).describe("Lookback in hours, up to one year; does not extend controller retention") },
+        description: `List historical/offline client inventory using the controller v2 API. Returns OFFLINE clients only — currently connected clients are excluded, so merge with unifi_list_clients for a full inventory. Includes names, MACs, first_seen and last_seen epoch seconds when available. This is inventory, not session history; use unifi_list_client_sessions for past connections. Requires controller history API-key support; errors never mean zero activity. Retention depends on the controller. Returns the most recently seen clients first, up to limit, with totalCount; truncated: true means less recently seen clients were left out, so raise limit (narrowing withinHours drops those same clients). Rows carry only ${Object.keys(output_schemas_js_1.HistoryClient.shape).join(", ")}.`,
+        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"),
+            limit: zod_1.z.number().int().min(1).max(500).default(100).describe("Maximum clients, most recently seen first"),
+        },
         outputSchema: output_schemas_js_1.listClientHistoryOutputSchema,
         annotations: safety_js_1.READ_ONLY,
-    }, async ({ siteReference, withinHours }) => {
+    }, async ({ siteReference, withinHours, limit }) => {
         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 });
+            // The controller returns every client in the window with no paging, so
+            // bound the result here: an unbounded inventory can run to megabytes.
+            const all = zod_1.z.array(output_schemas_js_1.HistoryClient).parse(await client.getClientHistory(siteReference, withinHours));
+            all.sort((a, b) => (b.last_seen ?? 0) - (a.last_seen ?? 0));
+            const data = all.slice(0, limit).map((row) => output_schemas_js_1.HistoryClient.strip().parse(row));
+            return (0, responses_js_1.formatSuccess)({ data, count: data.length, totalCount: all.length, limit, truncated: all.length > limit, 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.",
+        description: "Read retained past client connections, including disconnected clients, from the controller stat/session query endpoint. POST here only reads statistics. Rows carry only _id, mac, hostname, is_wired, 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.",
         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"),
+            limit: zod_1.z.number().int().min(1).max(1000).default(100).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,
@@ -49,10 +57,12 @@ function registerClientHistoryTools(server, client) {
                 seen.add(row._id);
                 deduped.push(row);
             }
-            const data = deduped.slice(0, limit);
-            const mayBeTruncated = deduped.length >= limit;
+            const data = deduped.slice(0, limit).map((row) => output_schemas_js_1.ClientSession.strip().parse(row));
+            // Judge truncation by the page the controller sent: duplicates removed
+            // above say nothing about whether more sessions exist past it.
+            const mayBeTruncated = rows.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 });
+                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

@@ -6,24 +6,25 @@ const responses_js_1 = require("../utils/responses.js");
 const query_js_1 = require("../utils/query.js");
 const safety_js_1 = require("../utils/safety.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+const params_js_1 = require("../utils/params.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 (may be absent), connectedAt, uplinkDeviceId (the switch/AP they're attached to), access.type. NOTE: verified against 11.0.83 (WIRED/WIRELESS; VPN/TELEPORT not live-verified) — the Integration API client schema is minimal and identical across those types; it does NOT expose signal strength, channel, or per-port binding. Use for: who's online right now. Disconnected/historical clients are NOT in the Integration API; use unifi_list_client_history and unifi_list_client_sessions for controller-retained records.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             offset: zod_1.z
                 .number()
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of records to skip (default: 0)"),
+                .describe("Number of records to skip"),
             limit: zod_1.z
                 .number()
                 .int()
                 .min(0)
                 .max(200)
                 .optional()
-                .describe("Number of records to return (default: 25, max: 200)"),
+                .describe("Number of records to return (API default: 25)"),
             filter: zod_1.z.string().optional().describe("Filter expression. Filterable: id, type, macAddress, ipAddress, connectedAt (timestamp), access.type, access.authorized (boolean). NOT filterable: name, uplinkDeviceId. Example: type.eq('WIRELESS')"),
         },
         outputSchema: output_schemas_js_1.listClientsOutputSchema,
@@ -41,8 +42,8 @@ function registerClientTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_client", {
         description: "Get a specific connected client by ID. Returns same shape as unifi_list_clients entries.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            clientId: zod_1.z.string().describe("Client ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            clientId: (0, params_js_1.resourceId)().describe("Client ID"),
         },
         outputSchema: output_schemas_js_1.getClientOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -60,8 +61,8 @@ function registerClientTools(server, client, readOnly = false) {
     server.registerTool("unifi_authorize_guest", {
         description: "Authorize a guest client through a captive-portal hotspot. Optional limits override hotspot defaults. Returns (per 11.0.83 docs, not live-verified): action, grantedAuthorization and revokedAuthorization objects (authorizedAt, authorizationMethod, expiresAt, dataUsageLimitMBytes, rxRateLimitKbps, txRateLimitKbps, usage). Idempotency: not safe to retry — re-authorizing extends the session.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            clientId: zod_1.z.string().describe("Client ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            clientId: (0, params_js_1.resourceId)().describe("Client ID"),
             timeLimitMinutes: zod_1.z
                 .number()
                 .int()
@@ -118,8 +119,8 @@ function registerClientTools(server, client, readOnly = false) {
     server.registerTool("unifi_unauthorize_guest", {
         description: "Revoke guest authorization; the client returns to the captive portal on next request. Returns (per docs; the UNAUTHORIZE response sample is not rendered in 11.0.83 and not live-verified): action plus a revokedAuthorization object. Idempotent.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            clientId: zod_1.z.string().describe("Client ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            clientId: (0, params_js_1.resourceId)().describe("Client ID"),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },
         annotations: safety_js_1.WRITE,