@owine/unifi-network-mcp 2.15.0 → 3.0.0

package/dist/tools/devices.js

@@ -6,26 +6,27 @@ 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");
 // Adopt echoes the adopted device — reuse the device detail schema.
 const adoptDeviceOutputSchema = output_schemas_js_1.getDeviceOutputSchema;
 function registerDeviceTools(server, client, readOnly = false) {
     server.registerTool("unifi_list_devices", {
         description: "List all adopted devices (gateways, switches, APs) at a site. Returns: id, name, model, macAddress, ipAddress, state (ONLINE/OFFLINE/etc), supported, firmwareVersion, firmwareUpdatable, features[] (capability tags, e.g. ['switching'] or ['accessPoint']), interfaces[] (e.g. ['ports'] or ['radios']). NOTE: features/interfaces are string arrays here; unifi_get_device expands them into objects. Use for: device inventory; pair with unifi_get_device for full config (port table, radios) and unifi_get_device_statistics for live metrics.",
         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: name (supports like), model, state, macAddress, ipAddress, firmwareVersion, supported, firmwareUpdatable, features/interfaces (sets: contains/containsAny/containsAll). like is rejected on model. Example: features.contains('accessPoint')"),
         },
         outputSchema: output_schemas_js_1.listDevicesOutputSchema,
@@ -43,8 +44,8 @@ function registerDeviceTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_device", {
         description: "Get full configuration for a device. Returns (in addition to list fields): adoptedAt, provisionedAt, configurationId, uplink.deviceId (absent on the ISP modem), features (object keyed by capability: switching {lags[]} / accessPoint {}), interfaces.ports[] for switches, gateways and modems ({idx, state, connector, maxSpeedMbps, speedMbps (may be omitted on DOWN ports), poe:{standard, type, enabled, state} on PoE ports only}), interfaces.radios[] for APs ({wlanStandard, frequencyGHz, channelWidthMHz, channel}). Some devices (e.g. 5G modems) return empty features/interfaces objects. NOTE: in the LIST endpoint, features/interfaces are capability-tag string arrays instead. Use for: switch port layout/PoE state, AP radio config, uplink topology. For live throughput/CPU/memory, use unifi_get_device_statistics.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            deviceId: zod_1.z.string().describe("Device ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            deviceId: (0, params_js_1.resourceId)().describe("Device ID"),
         },
         outputSchema: output_schemas_js_1.getDeviceOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -60,8 +61,8 @@ 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; absent on e.g. the ISP modem), interfaces.radios[] for APs ({frequencyGHz, txRetriesPct}; interfaces is {} for non-AP devices). NOTE: verified against 11.0.83 — the Integration API does NOT expose per-switch-port byte/error/PoE-power counters here; port-level live stats are unavailable. Use for: device health and AP radio metrics. For config (channel, power, port assignment), use unifi_get_device.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            deviceId: zod_1.z.string().describe("Device ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            deviceId: (0, params_js_1.resourceId)().describe("Device ID"),
         },
         outputSchema: output_schemas_js_1.getDeviceStatisticsOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -82,14 +83,14 @@ function registerDeviceTools(server, client, readOnly = false) {
                 .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, e.g. model.eq('U7 Pro')"),
         },
         outputSchema: output_schemas_js_1.listPendingDevicesOutputSchema,
@@ -109,14 +110,14 @@ function registerDeviceTools(server, client, readOnly = false) {
     server.registerTool("unifi_adopt_device", {
         description: "Adopt a pending device into a site by MAC address. The device must already appear in unifi_list_pending_devices. Idempotency: not safe to retry — re-adopting may error or duplicate.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             macAddress: zod_1.z.string().describe("MAC address of the device"),
             // 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,
+        outputSchema: (0, output_schemas_js_1.writeResult)(adoptDeviceOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
     }, async ({ siteId, macAddress, ignoreDeviceLimit, dryRun }) => {
         const body = {
@@ -136,18 +137,18 @@ function registerDeviceTools(server, client, readOnly = false) {
     server.registerTool("unifi_remove_device", {
         description: "DESTRUCTIVE: Remove (unadopt) a device from a site. If the device is online, it will be reset to factory defaults",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            deviceId: zod_1.z.string().describe("Device 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"),
+            deviceId: (0, params_js_1.resourceId)().describe("Device ID"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, deviceId, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will remove the device from the site. If the device is online, it will be reset to factory defaults");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will remove the device from the site. If the device is online, it will be reset to factory defaults");
         if (guard)
             return guard;
         if (dryRun)
-            return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/devices/${deviceId}`, {});
+            return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/devices/${deviceId}`);
         try {
             const data = await client.delete(`/sites/${siteId}/devices/${deviceId}`);
             return (0, responses_js_1.formatSuccess)(data);
@@ -159,8 +160,8 @@ function registerDeviceTools(server, client, readOnly = false) {
     server.registerTool("unifi_restart_device", {
         description: "Restart (reboot) a device. The device will be unreachable for ~1–3 minutes. Not idempotent: each call triggers a fresh reboot.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            deviceId: zod_1.z.string().describe("Device ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            deviceId: (0, params_js_1.resourceId)().describe("Device ID"),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
@@ -179,8 +180,8 @@ function registerDeviceTools(server, client, readOnly = false) {
     server.registerTool("unifi_power_cycle_port", {
         description: "Power-cycle PoE on a specific switch port (briefly drops then restores power). portIdx is the port number (1-based) as shown in unifi_get_device interfaces.ports[].idx. Use for: rebooting a PoE-powered camera/AP without touching the device.",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            deviceId: zod_1.z.string().describe("Device ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            deviceId: (0, params_js_1.resourceId)().describe("Device ID"),
             portIdx: zod_1.z.number().int().min(1).describe("Port index number (1-based)"),
             dryRun: zod_1.z.boolean().optional().describe("Preview this action without executing it"),
         },

package/dist/tools/dns-policies.js

@@ -7,6 +7,7 @@ const query_js_1 = require("../utils/query.js");
 const safety_js_1 = require("../utils/safety.js");
 const full_put_js_1 = require("../utils/full-put.js");
 const output_schemas_js_1 = require("../utils/output-schemas.js");
+const params_js_1 = require("../utils/params.js");
 // Type-specific request-body fields, from the 11.0.83 POST/PUT schemas (every
 // type also takes type, enabled, domain). MX/TXT/SRV/FORWARD_DOMAIN have no TTL.
 const DNS_TYPE_FIELDS = {
@@ -83,20 +84,20 @@ 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, metadata.origin, plus type-specific fields: A ipv4Address+ttlSeconds; AAAA ipv6Address+ttlSeconds; CNAME targetDomain+ttlSeconds; MX mailServerDomain+priority; TXT text; SRV serverDomain/service/protocol/port/priority/weight; FORWARD_DOMAIN ipAddress (per 11.0.83 response samples).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            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()
@@ -117,8 +118,8 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
     server.registerTool("unifi_get_dns_policy", {
         description: "Get a specific DNS policy by ID (same fields as the list entry).",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            dnsPolicyId: zod_1.z.string().describe("DNS policy ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            dnsPolicyId: (0, params_js_1.resourceId)().describe("DNS policy ID"),
         },
         outputSchema: output_schemas_js_1.dnsPolicyOutputSchema,
         annotations: safety_js_1.READ_ONLY,
@@ -136,7 +137,7 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
     server.registerTool("unifi_create_dns_policy", {
         description: `Create a new DNS policy. Every type takes type, enabled, domain; the rest depends on type (per 11.0.83 docs): ${DNS_TYPES_DOC} Fields belonging to other types are rejected. Idempotency: not safe to retry — re-running creates a duplicate record.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
             ...dnsFields,
             type: dnsType,
             enabled: zod_1.z.boolean().describe("Whether the DNS policy is enabled"),
@@ -146,7 +147,7 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
                 .optional()
                 .describe("Preview this action without executing it"),
         },
-        outputSchema: output_schemas_js_1.dnsPolicyOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.dnsPolicyOutputSchema),
         annotations: safety_js_1.WRITE_NOT_IDEMPOTENT,
     }, async ({ siteId, dryRun, ...fields }) => {
         try {
@@ -164,8 +165,8 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
     server.registerTool("unifi_update_dns_policy", {
         description: `Update a DNS policy. Pass only the fields to change. The API's PUT replaces the whole policy, so this tool reads the current policy, keeps the documented fields for the (possibly new) type, overlays your changes and sends the full body. Changing type drops the old type's fields, so supply the new type's required fields: ${DNS_TYPES_DOC} dryRun shows the merged body.`,
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            dnsPolicyId: zod_1.z.string().describe("DNS policy ID"),
+            siteId: (0, params_js_1.resourceId)().describe("Site ID"),
+            dnsPolicyId: (0, params_js_1.resourceId)().describe("DNS policy ID"),
             ...dnsFields,
             type: dnsType.optional(),
             enabled: zod_1.z.boolean().optional().describe("Whether the DNS policy is enabled"),
@@ -175,20 +176,22 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
                 .optional()
                 .describe("Preview the merged PUT body without executing it (still reads the current policy)"),
         },
-        outputSchema: output_schemas_js_1.dnsPolicyOutputSchema,
+        outputSchema: (0, output_schemas_js_1.writeResult)(output_schemas_js_1.dnsPolicyOutputSchema),
         annotations: safety_js_1.WRITE,
     }, async ({ siteId, dnsPolicyId, dryRun, ...fields }) => {
         try {
             const path = `/sites/${siteId}/dns/policies/${dnsPolicyId}`;
-            const current = (0, full_put_js_1.asObject)(await client.get(path), "the current DNS policy");
-            const updates = (0, full_put_js_1.definedEntries)(fields);
-            const { allowed } = fieldsForDnsType(updates.type ?? current.type);
-            const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
-            checkDnsBody(body, updates);
-            if (dryRun)
-                return (0, safety_js_1.formatDryRun)("PUT", path, body);
-            const data = await client.put(path, body);
-            return (0, responses_js_1.formatSuccess)(data, { structured: true });
+            return await (0, full_put_js_1.withResourceLock)(path, async () => {
+                const current = (0, full_put_js_1.asObject)(await client.get(path), "the current DNS policy");
+                const updates = (0, full_put_js_1.definedEntries)(fields);
+                const { allowed } = fieldsForDnsType(updates.type ?? current.type);
+                const body = (0, full_put_js_1.mergeForPut)(current, updates, allowed);
+                checkDnsBody(body, updates);
+                if (dryRun)
+                    return (0, safety_js_1.formatDryRun)("PUT", path, body);
+                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);
@@ -197,12 +200,9 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
     server.registerTool("unifi_delete_dns_policy", {
         description: "DESTRUCTIVE: Delete a DNS policy",
         inputSchema: {
-            siteId: zod_1.z.string().describe("Site ID"),
-            dnsPolicyId: zod_1.z.string().describe("DNS policy 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"),
+            dnsPolicyId: (0, params_js_1.resourceId)().describe("DNS policy ID"),
+            confirm: (0, safety_js_1.confirmDestructive)(),
             dryRun: zod_1.z
                 .boolean()
                 .optional()
@@ -210,12 +210,12 @@ function registerDnsPolicyTools(server, client, readOnly = false) {
         },
         annotations: safety_js_1.DESTRUCTIVE,
     }, async ({ siteId, dnsPolicyId, confirm, dryRun }) => {
-        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the DNS policy");
+        const guard = dryRun ? null : (0, safety_js_1.requireConfirmation)(confirm, "This will delete the DNS policy");
         if (guard)
             return guard;
         try {
             if (dryRun)
-                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/dns/policies/${dnsPolicyId}`, {});
+                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/dns/policies/${dnsPolicyId}`);
             const data = await client.delete(`/sites/${siteId}/dns/policies/${dnsPolicyId}`);
             return (0, responses_js_1.formatSuccess)(data);
         }

package/dist/tools/firewall.d.ts

@@ -1,3 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { NetworkClient } from "../client.js";
-export declare function registerFirewallTools(server: McpServer, client: NetworkClient, readOnly?: boolean): void;
+import { type WanPolicy } from "../utils/wan-exposure.js";
+export declare function registerFirewallTools(server: McpServer, client: NetworkClient, readOnly?: boolean, wan?: WanPolicy): void;