@owine/unifi-network-mcp 0.9.0

package/dist/tools/traffic-matching.d.ts

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

package/dist/tools/traffic-matching.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTrafficMatchingTools = registerTrafficMatchingTools;
+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");
+function registerTrafficMatchingTools(server, client, readOnly = false) {
+    server.tool("unifi_list_traffic_matching_lists", "List all traffic matching lists at a site (port groups, IP groups)", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        offset: zod_1.z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Number of records to skip (default: 0)"),
+        limit: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Number of records to return (default: 25, max: 200)"),
+        filter: zod_1.z
+            .string()
+            .optional()
+            .describe("Filter expression"),
+    }, safety_js_1.READ_ONLY, async ({ siteId, offset, limit, filter }) => {
+        try {
+            const query = (0, query_js_1.buildQuery)({ offset, limit, filter });
+            const data = await client.get(`/sites/${siteId}/traffic-matching-lists${query}`);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.tool("unifi_get_traffic_matching_list", "Get a specific traffic matching list by ID", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        trafficMatchingListId: zod_1.z.string().describe("Traffic matching list ID"),
+    }, safety_js_1.READ_ONLY, async ({ siteId, trafficMatchingListId }) => {
+        try {
+            const data = await client.get(`/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    if (readOnly)
+        return;
+    server.tool("unifi_create_traffic_matching_list", "Create a new traffic matching list", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        type: zod_1.z
+            .enum(["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"])
+            .describe("List type"),
+        name: zod_1.z.string().describe("List name"),
+        items: zod_1.z
+            .array(zod_1.z.unknown())
+            .describe("List items (ports or IP addresses)"),
+        dryRun: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Preview this action without executing it"),
+    }, safety_js_1.WRITE_NOT_IDEMPOTENT, async ({ siteId, type, name, items, dryRun }) => {
+        try {
+            const body = { type, name, items };
+            if (dryRun)
+                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/traffic-matching-lists`, body);
+            const data = await client.post(`/sites/${siteId}/traffic-matching-lists`, body);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.tool("unifi_update_traffic_matching_list", "Update a traffic matching list", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        trafficMatchingListId: zod_1.z.string().describe("Traffic matching list ID"),
+        type: zod_1.z
+            .enum(["PORTS", "IPV4_ADDRESSES", "IPV6_ADDRESSES"])
+            .describe("List type"),
+        name: zod_1.z.string().describe("List name"),
+        items: zod_1.z.array(zod_1.z.unknown()).describe("List items"),
+        dryRun: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Preview this action without executing it"),
+    }, safety_js_1.WRITE, async ({ siteId, trafficMatchingListId, type, name, items, dryRun }) => {
+        try {
+            const body = { type, name, items };
+            if (dryRun)
+                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`, body);
+            const data = await client.put(`/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`, body);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.tool("unifi_delete_traffic_matching_list", "DESTRUCTIVE: Delete a traffic matching list", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        trafficMatchingListId: zod_1.z.string().describe("Traffic matching list ID"),
+        confirm: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Must be true to execute this destructive action"),
+        dryRun: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Preview this action without executing it"),
+    }, safety_js_1.DESTRUCTIVE, async ({ siteId, trafficMatchingListId, confirm, dryRun }) => {
+        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the traffic matching list");
+        if (guard)
+            return guard;
+        try {
+            if (dryRun)
+                return (0, safety_js_1.formatDryRun)("DELETE", `/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`, {});
+            const data = await client.delete(`/sites/${siteId}/traffic-matching-lists/${trafficMatchingListId}`);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+}

package/dist/tools/wifi.d.ts

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

package/dist/tools/wifi.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWifiTools = registerWifiTools;
+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");
+function registerWifiTools(server, client, readOnly = false) {
+    server.tool("unifi_list_wifi", "List all WiFi broadcasts (SSIDs) at a site", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        offset: zod_1.z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Number of records to skip (default: 0)"),
+        limit: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Number of records to return (default: 25, max: 200)"),
+        filter: zod_1.z
+            .string()
+            .optional()
+            .describe("Filter expression"),
+    }, safety_js_1.READ_ONLY, async ({ siteId, offset, limit, filter }) => {
+        try {
+            const query = (0, query_js_1.buildQuery)({ offset, limit, filter });
+            const data = await client.get(`/sites/${siteId}/wifi${query}`);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.tool("unifi_get_wifi", "Get a specific WiFi network by ID", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+    }, safety_js_1.READ_ONLY, async ({ siteId, wifiBroadcastId }) => {
+        try {
+            const data = await client.get(`/sites/${siteId}/wifi/${wifiBroadcastId}`);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    if (readOnly)
+        return;
+    server.tool("unifi_create_wifi", "Create a new WiFi network (SSID)", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        name: zod_1.z.string().describe("SSID name"),
+        enabled: zod_1.z.boolean().describe("Enable the WiFi network"),
+        type: zod_1.z.enum(["STANDARD"]).describe("WiFi type"),
+        broadcastingFrequenciesGHz: zod_1.z
+            .array(zod_1.z.string())
+            .describe("Frequencies: 2.4, 5, 6"),
+        dryRun: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Preview this action without executing it"),
+    }, safety_js_1.WRITE_NOT_IDEMPOTENT, async ({ siteId, name, enabled, type, broadcastingFrequenciesGHz, dryRun, }) => {
+        try {
+            const body = {
+                name,
+                enabled,
+                type,
+                broadcastingFrequenciesGHz: broadcastingFrequenciesGHz.map(Number),
+            };
+            if (dryRun)
+                return (0, safety_js_1.formatDryRun)("POST", `/sites/${siteId}/wifi`, body);
+            const data = await client.post(`/sites/${siteId}/wifi`, body);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.tool("unifi_update_wifi", "Update an existing WiFi network", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+        name: zod_1.z.string().optional().describe("SSID name"),
+        enabled: zod_1.z.boolean().optional().describe("Enable the WiFi network"),
+        dryRun: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Preview this action without executing it"),
+    }, safety_js_1.WRITE, async ({ siteId, wifiBroadcastId, name, enabled, dryRun }) => {
+        try {
+            const body = {};
+            if (name !== undefined)
+                body.name = name;
+            if (enabled !== undefined)
+                body.enabled = enabled;
+            if (dryRun)
+                return (0, safety_js_1.formatDryRun)("PUT", `/sites/${siteId}/wifi/${wifiBroadcastId}`, body);
+            const data = await client.put(`/sites/${siteId}/wifi/${wifiBroadcastId}`, body);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+    server.tool("unifi_delete_wifi", "DESTRUCTIVE: Delete a WiFi network — all clients on this SSID will be disconnected", {
+        siteId: zod_1.z.string().describe("Site ID"),
+        wifiBroadcastId: zod_1.z.string().describe("WiFi Broadcast ID"),
+        force: zod_1.z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Force delete (default: false)"),
+        confirm: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Must be true to execute this destructive action"),
+        dryRun: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Preview this action without executing it"),
+    }, safety_js_1.DESTRUCTIVE, async ({ siteId, wifiBroadcastId, force, confirm, dryRun }) => {
+        const guard = (0, safety_js_1.requireConfirmation)(confirm, "This will delete the WiFi network and disconnect all clients on this SSID");
+        if (guard)
+            return guard;
+        try {
+            let path = `/sites/${siteId}/wifi/${wifiBroadcastId}`;
+            if (force) {
+                path += "?force=true";
+            }
+            if (dryRun)
+                return (0, safety_js_1.formatDryRun)("DELETE", path);
+            const data = await client.delete(path);
+            return (0, responses_js_1.formatSuccess)(data);
+        }
+        catch (err) {
+            return (0, responses_js_1.formatError)(err);
+        }
+    });
+}

package/dist/utils/query.d.ts

@@ -0,0 +1,5 @@
+export declare function buildQuery(params: {
+    offset?: number;
+    limit?: number;
+    filter?: string;
+}): string;

package/dist/utils/query.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildQuery = buildQuery;
+function buildQuery(params) {
+    const searchParams = new URLSearchParams();
+    if (params.offset !== undefined)
+        searchParams.set("offset", String(params.offset));
+    if (params.limit !== undefined)
+        searchParams.set("limit", String(params.limit));
+    if (params.filter !== undefined)
+        searchParams.set("filter", params.filter);
+    const qs = searchParams.toString();
+    return qs ? `?${qs}` : "";
+}

package/dist/utils/responses.d.ts

@@ -0,0 +1,13 @@
+export declare function formatSuccess(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function formatError(err: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/utils/responses.js

@@ -0,0 +1,18 @@
+"use strict";
+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 formatError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}

package/dist/utils/safety.d.ts

@@ -0,0 +1,18 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+export declare const READ_ONLY: ToolAnnotations;
+export declare const WRITE: ToolAnnotations;
+export declare const WRITE_NOT_IDEMPOTENT: ToolAnnotations;
+export declare const DESTRUCTIVE: ToolAnnotations;
+export declare function formatDryRun(method: string, path: string, body?: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function requireConfirmation(confirm: boolean | undefined, action: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | null;

package/dist/utils/safety.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESTRUCTIVE = exports.WRITE_NOT_IDEMPOTENT = exports.WRITE = exports.READ_ONLY = void 0;
+exports.formatDryRun = formatDryRun;
+exports.requireConfirmation = requireConfirmation;
+exports.READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+};
+exports.WRITE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+exports.WRITE_NOT_IDEMPOTENT = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+};
+exports.DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+};
+function formatDryRun(method, path, body) {
+    const preview = {
+        dryRun: true,
+        wouldExecute: { method, path, ...(body !== undefined ? { body } : {}) },
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(preview, null, 2) }],
+    };
+}
+function requireConfirmation(confirm, action) {
+    if (confirm !== true) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `This action requires explicit confirmation: ${action}. Re-invoke with confirm: true to proceed.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@owine/unifi-network-mcp",
+  "version": "0.9.0",
+  "description": "MCP server for the UniFi Network API",
+  "main": "dist/index.js",
+  "bin": {
+    "unifi-network-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/owine/unifi-network-mcp.git"
+  },
+  "keywords": [
+    "unifi",
+    "network",
+    "mcp",
+    "model-context-protocol",
+    "ubiquiti"
+  ],
+  "author": "owine",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.2",
+    "@types/node": "24.10.13",
+    "eslint": "9.39.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.55.0",
+    "vitest": "4.0.18"
+  }
+}