@owine/unifi-network-mcp 2.6.0 → 2.7.0

package/dist/utils/output-schemas.js

@@ -0,0 +1,507 @@
+"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;
+/**
+ * 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.4.55. 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.
+ */
+const zod_1 = require("zod");
+const Metadata = zod_1.z
+    .object({ origin: zod_1.z.string().optional() })
+    .passthrough();
+const PaginationFields = {
+    offset: zod_1.z.number().int().optional(),
+    limit: zod_1.z.number().int().optional(),
+    count: zod_1.z.number().int().optional(),
+    totalCount: zod_1.z.number().int().optional(),
+};
+// Shared device identity fields. NOTE: the list endpoint returns
+// `features` and `interfaces` as string arrays (capability tags, e.g.
+// ["switching"], ["ports"]); the get-by-id endpoint expands them into
+// objects. Hence two distinct schemas below.
+const DeviceCommon = {
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    model: zod_1.z.string().optional(),
+    macAddress: zod_1.z.string().optional(),
+    ipAddress: zod_1.z.string().optional(),
+    state: zod_1.z.string().optional(),
+    supported: zod_1.z.boolean().optional(),
+    firmwareVersion: zod_1.z.string().optional(),
+    firmwareUpdatable: zod_1.z.boolean().optional(),
+};
+const DeviceListItem = zod_1.z
+    .object({
+    ...DeviceCommon,
+    adoptedAt: zod_1.z.string().optional(),
+    features: zod_1.z.array(zod_1.z.string()).optional(),
+    interfaces: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough();
+const DevicePort = zod_1.z
+    .object({
+    idx: zod_1.z.number(),
+    name: zod_1.z.string().optional(),
+    state: zod_1.z.string().optional(),
+    connector: zod_1.z.string().optional(),
+    maxSpeedMbps: zod_1.z.number().optional(),
+    speedMbps: zod_1.z.number().optional(),
+    poe: zod_1.z
+        .object({
+        standard: zod_1.z.string().optional(),
+        type: zod_1.z.number().optional(),
+        enabled: zod_1.z.boolean().optional(),
+        state: zod_1.z.string().optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const DeviceRadio = zod_1.z
+    .object({
+    wlanStandard: zod_1.z.string().optional(),
+    frequencyGHz: zod_1.z.number().optional(),
+    channelWidthMHz: zod_1.z.number().optional(),
+    channel: zod_1.z.number().optional(),
+})
+    .passthrough();
+const DeviceDetail = zod_1.z
+    .object({
+    ...DeviceCommon,
+    adoptedAt: zod_1.z.string().optional(),
+    provisionedAt: zod_1.z.string().optional(),
+    configurationId: zod_1.z.string().optional(),
+    uplink: zod_1.z
+        .object({ deviceId: zod_1.z.string().optional() })
+        .passthrough()
+        .optional(),
+    // Detail view: object keyed by capability (switching/accessPoint).
+    features: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    interfaces: zod_1.z
+        .object({
+        ports: zod_1.z.array(DevicePort).optional(),
+        radios: zod_1.z.array(DeviceRadio).optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const DeviceStatistics = zod_1.z
+    .object({
+    uptimeSec: zod_1.z.number().optional(),
+    lastHeartbeatAt: zod_1.z.string().optional(),
+    nextHeartbeatAt: zod_1.z.string().optional(),
+    loadAverage1Min: zod_1.z.number().optional(),
+    loadAverage5Min: zod_1.z.number().optional(),
+    loadAverage15Min: zod_1.z.number().optional(),
+    cpuUtilizationPct: zod_1.z.number().optional(),
+    memoryUtilizationPct: zod_1.z.number().optional(),
+    uplink: zod_1.z
+        .object({
+        txRateBps: zod_1.z.number().optional(),
+        rxRateBps: zod_1.z.number().optional(),
+    })
+        .passthrough()
+        .optional(),
+    interfaces: zod_1.z
+        .object({
+        radios: zod_1.z
+            .array(zod_1.z
+            .object({
+            frequencyGHz: zod_1.z.number().optional(),
+            txRetriesPct: zod_1.z.number().optional(),
+        })
+            .passthrough())
+            .optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const Client = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    type: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    macAddress: zod_1.z.string().optional(),
+    ipAddress: zod_1.z.string().optional(),
+    connectedAt: zod_1.z.string().optional(),
+    uplinkDeviceId: zod_1.z.string().optional(),
+    access: zod_1.z
+        .object({ type: zod_1.z.string().optional() })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const WifiBroadcast = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    type: zod_1.z.string().optional(),
+    // Nested shapes not live-verified — z.unknown() avoids over-asserting
+    // object-vs-array (the SDK enforces outputSchema and a wrong type
+    // makes the tool hard-fail, not just mislead).
+    broadcastingFrequenciesGHz: zod_1.z.array(zod_1.z.unknown()).optional(),
+    securityConfiguration: zod_1.z.unknown().optional(),
+    hideName: zod_1.z.boolean().optional(),
+    bandSteeringEnabled: zod_1.z.boolean().optional(),
+    mloEnabled: zod_1.z.boolean().optional(),
+    network: zod_1.z.unknown().optional(),
+    broadcastingDeviceFilter: zod_1.z.unknown().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const ApplicationInfo = zod_1.z
+    .object({
+    // Live-verified (10.4.55): only applicationVersion is returned.
+    applicationVersion: zod_1.z.string().optional(),
+})
+    .passthrough();
+const Site = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    internalReference: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+})
+    .passthrough();
+const Network = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    management: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    vlanId: zod_1.z.number().int().optional(),
+    default: zod_1.z.boolean().optional(),
+    zoneId: zod_1.z.string().optional(),
+    isolationEnabled: zod_1.z.boolean().optional(),
+    internetAccessEnabled: zod_1.z.boolean().optional(),
+    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.
+    ipv4Configuration: zod_1.z.unknown().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const NetworkReferences = zod_1.z
+    .object({
+    referenceResources: zod_1.z.array(zod_1.z.unknown()).optional(),
+})
+    .passthrough();
+const Voucher = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    code: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    createdAt: zod_1.z.string().optional(),
+    activatedAt: zod_1.z.string().optional(),
+    expiresAt: zod_1.z.string().optional(),
+    timeLimitMinutes: zod_1.z.number().optional(),
+    dataUsageLimitMBytes: zod_1.z.number().optional(),
+    rxRateLimitKbps: zod_1.z.number().optional(),
+    txRateLimitKbps: zod_1.z.number().optional(),
+    authorizedGuestLimit: zod_1.z.number().optional(),
+    authorizedGuestCount: zod_1.z.number().optional(),
+    expired: zod_1.z.boolean().optional(),
+})
+    .passthrough();
+const FirewallZone = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    networkIds: zod_1.z.array(zod_1.z.string()).optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const FirewallPolicy = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    // connectionStateFilter is live-verified to be an ARRAY, not an
+    // object — the rest are not live-verified, so leave all loose.
+    action: zod_1.z.unknown().optional(),
+    source: zod_1.z.unknown().optional(),
+    destination: zod_1.z.unknown().optional(),
+    ipProtocolScope: zod_1.z.unknown().optional(),
+    connectionStateFilter: zod_1.z.unknown().optional(),
+    ipsecFilter: zod_1.z.unknown().optional(),
+    schedule: zod_1.z.unknown().optional(),
+    loggingEnabled: zod_1.z.boolean().optional(),
+    index: zod_1.z.number().optional(),
+    description: zod_1.z.string().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const FirewallPolicyOrdering = zod_1.z
+    .object({
+    orderedFirewallPolicyIds: zod_1.z
+        .object({
+        beforeSystemDefined: zod_1.z.array(zod_1.z.string()).optional(),
+        afterSystemDefined: zod_1.z.array(zod_1.z.string()).optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const AclRule = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    type: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    action: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    protocolFilter: zod_1.z.array(zod_1.z.string()).optional(),
+    sourceFilter: zod_1.z.unknown().optional(),
+    destinationFilter: zod_1.z.unknown().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const AclRuleOrdering = zod_1.z
+    .object({
+    orderedAclRuleIds: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough();
+const SwitchStack = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    members: zod_1.z.array(zod_1.z.unknown()).optional(),
+    lags: zod_1.z.array(zod_1.z.unknown()).optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const McLagDomain = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    peers: zod_1.z.array(zod_1.z.unknown()).optional(),
+    lags: zod_1.z.array(zod_1.z.unknown()).optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const Lag = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    type: zod_1.z.string().optional(),
+    members: zod_1.z
+        .array(zod_1.z
+        .object({
+        deviceId: zod_1.z.string().optional(),
+        portIdxs: zod_1.z.array(zod_1.z.number()).optional(),
+    })
+        .passthrough())
+        .optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const DnsPolicy = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    type: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    domain: zod_1.z.string().optional(),
+    ipv4Address: zod_1.z.string().optional(),
+    ttlSeconds: zod_1.z.number().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+const TrafficMatchingList = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    type: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    items: zod_1.z.array(zod_1.z.unknown()).optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+// Verified against the live Integration API (10.4.55). The WAN and
+// site-to-site-tunnel list rows are intentionally minimal in the API.
+const Wan = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+})
+    .passthrough();
+const VpnServer = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    type: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+// No tunnels present in the verification environment — keep loose.
+const VpnTunnel = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+})
+    .passthrough();
+const RadiusProfile = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    metadata: Metadata.optional(),
+})
+    .passthrough();
+// No tags present in the verification environment — documented shape.
+const DeviceTag = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    deviceIds: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough();
+// DPI category/application ids are NUMERIC (verified live).
+const DpiCategory = zod_1.z
+    .object({
+    id: zod_1.z.number(),
+    name: zod_1.z.string().optional(),
+})
+    .passthrough();
+const DpiApplication = zod_1.z
+    .object({
+    id: zod_1.z.number(),
+    name: zod_1.z.string().optional(),
+})
+    .passthrough();
+// Countries key on `code` (ISO alpha-2), NOT `id` (verified live).
+const Country = zod_1.z
+    .object({
+    code: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+})
+    .passthrough();
+// No pending devices in the verification environment — keep loose.
+const PendingDevice = zod_1.z
+    .object({
+    macAddress: zod_1.z.string().optional(),
+    model: zod_1.z.string().optional(),
+    ipAddress: zod_1.z.string().optional(),
+    firmwareVersion: zod_1.z.string().optional(),
+})
+    .passthrough();
+exports.getInfoOutputSchema = ApplicationInfo.shape;
+exports.listSitesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Site),
+};
+exports.networkOutputSchema = Network.shape;
+exports.listNetworksOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Network),
+};
+exports.getNetworkReferencesOutputSchema = NetworkReferences.shape;
+exports.voucherOutputSchema = Voucher.shape;
+exports.listVouchersOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Voucher),
+};
+exports.createVouchersOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Voucher),
+};
+exports.firewallZoneOutputSchema = FirewallZone.shape;
+exports.listFirewallZonesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(FirewallZone),
+};
+exports.firewallPolicyOutputSchema = FirewallPolicy.shape;
+exports.listFirewallPoliciesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(FirewallPolicy),
+};
+exports.firewallPolicyOrderingOutputSchema = FirewallPolicyOrdering.shape;
+exports.aclRuleOutputSchema = AclRule.shape;
+exports.listAclRulesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(AclRule),
+};
+exports.aclRuleOrderingOutputSchema = AclRuleOrdering.shape;
+exports.switchStackOutputSchema = SwitchStack.shape;
+exports.listSwitchStacksOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(SwitchStack),
+};
+exports.mcLagDomainOutputSchema = McLagDomain.shape;
+exports.listMcLagDomainsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(McLagDomain),
+};
+exports.lagOutputSchema = Lag.shape;
+exports.listLagsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Lag),
+};
+exports.dnsPolicyOutputSchema = DnsPolicy.shape;
+exports.listDnsPoliciesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(DnsPolicy),
+};
+exports.trafficMatchingListOutputSchema = TrafficMatchingList.shape;
+exports.listTrafficMatchingListsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(TrafficMatchingList),
+};
+exports.listDevicesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(DeviceListItem),
+};
+exports.getDeviceOutputSchema = DeviceDetail.shape;
+exports.getDeviceStatisticsOutputSchema = DeviceStatistics.shape;
+exports.listClientsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Client),
+};
+exports.getClientOutputSchema = Client.shape;
+exports.listWifiOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(WifiBroadcast),
+};
+exports.getWifiOutputSchema = WifiBroadcast.shape;
+exports.listWansOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Wan),
+};
+exports.listVpnServersOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(VpnServer),
+};
+exports.listVpnTunnelsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(VpnTunnel),
+};
+exports.listRadiusProfilesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(RadiusProfile),
+};
+exports.listDeviceTagsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(DeviceTag),
+};
+exports.listDpiCategoriesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(DpiCategory),
+};
+exports.listDpiApplicationsOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(DpiApplication),
+};
+exports.listCountriesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(Country),
+};
+exports.listPendingDevicesOutputSchema = {
+    ...PaginationFields,
+    data: zod_1.z.array(PendingDevice),
+};

package/dist/utils/responses.d.ts

@@ -1,8 +1,11 @@
-export declare function formatSuccess(data: unknown): {
+export declare function formatSuccess(data: unknown, opts?: {
+    structured?: boolean;
+}): {
     content: {
         type: "text";
         text: string;
     }[];
+    structuredContent?: Record<string, unknown>;
 };
 export declare function formatError(err: unknown): {
     content: {

package/dist/utils/responses.js

@@ -2,12 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatSuccess = formatSuccess;
 exports.formatError = formatError;
-function formatSuccess(data) {
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(data, null, 2) },
-        ],
+function formatSuccess(data, opts) {
+    const result = {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
     };
+    if (opts?.structured &&
+        data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data)) {
+        result.structuredContent = data;
+    }
+    return result;
 }
 function formatError(err) {
     const message = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owine/unifi-network-mcp",
-  "version": "2.6.0",
+  "version": "2.7.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@11.1.1",
+  "packageManager": "pnpm@11.1.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/owine/unifi-network-mcp.git"
@@ -44,7 +44,7 @@
     "@eslint/js": "10.0.1",
     "@types/node": "24.12.4",
     "@vitest/coverage-v8": "4.1.6",
-    "eslint": "10.3.0",
+    "eslint": "10.4.0",
     "lefthook": "2.1.6",
     "typescript": "6.0.3",
     "typescript-eslint": "8.59.3",