@owine/unifi-network-mcp 2.15.0 → 3.1.0

package/dist/write-log.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WriteLog = void 0;
+exports.noteWriteRequest = noteWriteRequest;
+exports.noteWriteStatus = noteWriteStatus;
+exports.noteRefusal = noteRefusal;
+exports.localTimestamp = localTimestamp;
+exports.openWriteLog = openWriteLog;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const responses_js_1 = require("./utils/responses.js");
+const secrets_js_1 = require("./utils/secrets.js");
+const currentCall = new node_async_hooks_1.AsyncLocalStorage();
+const withoutQuery = (path) => path.split("?")[0];
+/** NetworkClient: a write request passed the guard and is about to be sent. */
+function noteWriteRequest(method, path) {
+    const call = currentCall.getStore();
+    if (call)
+        call.request = { method, path: withoutQuery(path) };
+}
+/** NetworkClient: the controller answered the write request. */
+function noteWriteStatus(status) {
+    const request = currentCall.getStore()?.request;
+    if (request)
+        request.status = status;
+}
+/** A check refused the call; the first refusal is the one logged. */
+function noteRefusal(reason, method, path) {
+    const call = currentCall.getStore();
+    if (call && !call.refusal)
+        call.refusal = { reason, method, ...(path === undefined ? {} : { path: withoutQuery(path) }) };
+}
+/**
+ * Field names, compared without case, whose value is redacted whatever it
+ * is. Names are matched exactly, not by substring, so containers such as
+ * presharedKeys keep their network IDs (redactSecrets masks the passphrase
+ * in each entry) and fields like keyId stay readable. The list: the names
+ * redactSecrets knows from WiFi and RADIUS bodies, their legacy-API x_
+ * forms, and the usual names of credentials and key material a firewall
+ * policy record (or a mistaken argument) could carry.
+ */
+const SECRET_FIELDS = new Set([
+    "passphrase", "password", "secret", "sharedSecret", "radiusSecret",
+    "x_passphrase", "x_password", "x_secret", "x_shared_secret",
+    "apiKey", "api_key", "apiToken", "token", "accessToken", "refreshToken", "authToken",
+    "privateKey", "private_key", "presharedKey",
+].map((name) => name.toLowerCase()));
+function redactArgs(value) {
+    if (Array.isArray(value))
+        return value.map(redactArgs);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, SECRET_FIELDS.has(key.toLowerCase()) ? secrets_js_1.REDACTED : redactArgs(entry)]));
+}
+/** "2026-10-18T21:04:05.123+02:00": the local time with its offset. */
+function localTimestamp(date) {
+    const pad = (n, width = 2) => String(Math.abs(n)).padStart(width, "0");
+    const offset = -date.getTimezoneOffset();
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}` +
+        `${offset < 0 ? "-" : "+"}${pad(Math.trunc(offset / 60))}:${pad(offset % 60)}`;
+}
+class WriteLog {
+    sink;
+    apiKey;
+    failed = false;
+    /** sink appends one line; it may throw, and a failure is reported once and never breaks the call. */
+    constructor(sink, apiKey) {
+        this.sink = sink;
+        this.apiKey = apiKey;
+    }
+    /**
+     * Open path for appending, creating it 0600 (and its directory 0700) if
+     * needed. Throws for a symlink, anything but a regular file, or a file
+     * others can write to, which could be truncated or filled with lies.
+     *
+     * On Windows, Node reports every writable file as mode 0666 and a link
+     * count that says nothing about access, and O_NOFOLLOW does not exist, so
+     * only the symlink and regular-file checks apply there: the file's ACL is
+     * the operator's to set.
+     */
+    static open(path, apiKey) {
+        const windows = process.platform === "win32";
+        let existing;
+        try {
+            existing = (0, node_fs_1.lstatSync)(path);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        if (existing?.isSymbolicLink())
+            throw new Error("it is a symlink; point it at the file itself");
+        if (existing === undefined)
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        // O_NOFOLLOW closes the gap between the check above and the open.
+        const noFollow = windows ? 0 : node_fs_1.constants.O_NOFOLLOW;
+        const fd = (0, node_fs_1.openSync)(path, node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_APPEND | node_fs_1.constants.O_CREAT | noFollow, 0o600);
+        const stats = (0, node_fs_1.fstatSync)(fd);
+        const problem = !stats.isFile() ? "it is not a regular file"
+            : windows ? undefined
+                : stats.nlink > 1 ? "it has other hard links, so lines could land in another file"
+                    : (stats.mode & 0o022) !== 0 ? `it is group- or world-writable (mode ${(stats.mode & 0o777).toString(8)}); chmod 600 it`
+                        : undefined;
+        if (problem !== undefined) {
+            (0, node_fs_1.closeSync)(fd);
+            throw new Error(problem);
+        }
+        return new WriteLog((line) => { (0, node_fs_1.writeSync)(fd, line); }, apiKey);
+    }
+    /** Run one write tool call and append its line. */
+    async record(tool, input, run) {
+        const started = new Date();
+        const call = {};
+        let result;
+        try {
+            result = await currentCall.run(call, run);
+            return result;
+        }
+        finally {
+            this.append(this.entry(tool, input, call, result, started));
+        }
+    }
+    entry(tool, input, call, result, started) {
+        const dryRun = input !== null && typeof input === "object" && "dryRun" in input && input.dryRun === true;
+        const preview = result?.structuredContent?.dryRun === true ? result.structuredContent.wouldExecute : undefined;
+        const base = {
+            ts: started.toISOString(),
+            tsLocal: localTimestamp(started),
+            tool,
+            args: redactArgs((0, secrets_js_1.redactSecrets)(input)),
+            method: null,
+            path: null,
+            dryRun,
+        };
+        const durationMs = Date.now() - started.getTime();
+        if (call.refusal) {
+            const { reason, method, path } = call.refusal;
+            return { ...base, method: method ?? null, path: path ?? null, outcome: "refused", reason, durationMs };
+        }
+        if (preview) {
+            const method = typeof preview.method === "string" ? preview.method : null;
+            const path = typeof preview.path === "string" ? withoutQuery(`/integration/v1${preview.path}`) : null;
+            return { ...base, method, path, outcome: "dry_run", durationMs };
+        }
+        const request = call.request;
+        const status = request?.status === undefined ? {} : { status: request.status };
+        const where = request ? { method: request.method, path: request.path } : {};
+        return { ...base, ...where, outcome: result === undefined || result.isError ? "error" : "ok", ...status, durationMs };
+    }
+    append(entry) {
+        try {
+            let line = JSON.stringify(entry);
+            // Arguments are the model's; if it ever pasted the key into one, keep it out.
+            if (this.apiKey.length >= 8)
+                line = line.replaceAll(this.apiKey, secrets_js_1.REDACTED);
+            this.sink(`${line}\n`);
+        }
+        catch (err) {
+            if (this.failed)
+                return;
+            this.failed = true;
+            console.error(`UNIFI_NETWORK_WRITE_LOG: cannot write the log (${(0, responses_js_1.errorMessage)(err)}); tool calls continue, but are not being logged.`);
+        }
+    }
+}
+exports.WriteLog = WriteLog;
+/** Open the write log at startup, or exit with a configuration error. */
+function openWriteLog(path, apiKey) {
+    try {
+        return WriteLog.open(path, apiKey);
+    }
+    catch (err) {
+        console.error(`Configuration error: cannot use UNIFI_NETWORK_WRITE_LOG (${path}): ${(0, responses_js_1.errorMessage)(err)}`);
+        return process.exit(1);
+    }
+}

package/dist/write-tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Every write tool, grouped by the module in src/tools/ that registers it.
+ * UNIFI_NETWORK_WRITE_TOOLS names tools or groups from here, and
+ * registerAllTools() refuses to register a write tool that is missing, so the
+ * list cannot fall behind the code.
+ */
+export declare const WRITE_TOOL_GROUPS: {
+    readonly devices: readonly ["unifi_adopt_device", "unifi_remove_device", "unifi_restart_device", "unifi_power_cycle_port"];
+    readonly clients: readonly ["unifi_authorize_guest", "unifi_unauthorize_guest"];
+    readonly networks: readonly ["unifi_create_network", "unifi_update_network", "unifi_delete_network"];
+    readonly wifi: readonly ["unifi_create_wifi", "unifi_update_wifi", "unifi_delete_wifi"];
+    readonly hotspot: readonly ["unifi_create_voucher", "unifi_delete_voucher", "unifi_bulk_delete_vouchers"];
+    readonly firewall: readonly ["unifi_create_firewall_zone", "unifi_update_firewall_zone", "unifi_delete_firewall_zone", "unifi_create_firewall_policy", "unifi_update_firewall_policy", "unifi_patch_firewall_policy", "unifi_delete_firewall_policy", "unifi_reorder_firewall_policies"];
+    readonly acl: readonly ["unifi_create_acl_rule", "unifi_update_acl_rule", "unifi_delete_acl_rule", "unifi_reorder_acl_rules"];
+    readonly "dns-policies": readonly ["unifi_create_dns_policy", "unifi_update_dns_policy", "unifi_delete_dns_policy"];
+    readonly "traffic-matching": readonly ["unifi_create_traffic_matching_list", "unifi_update_traffic_matching_list", "unifi_delete_traffic_matching_list"];
+};
+export declare const WRITE_TOOLS: readonly string[];
+/**
+ * The write tools a UNIFI_NETWORK_WRITE_TOOLS value enables, in catalog
+ * order: a comma-separated list of tool and group names, or "" / "none" for
+ * none. Names that are neither come back in unknown.
+ */
+export declare function parseWriteTools(value: string): {
+    tools: string[];
+    unknown: string[];
+};

package/dist/write-tools.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRITE_TOOLS = exports.WRITE_TOOL_GROUPS = void 0;
+exports.parseWriteTools = parseWriteTools;
+/**
+ * Every write tool, grouped by the module in src/tools/ that registers it.
+ * UNIFI_NETWORK_WRITE_TOOLS names tools or groups from here, and
+ * registerAllTools() refuses to register a write tool that is missing, so the
+ * list cannot fall behind the code.
+ */
+exports.WRITE_TOOL_GROUPS = {
+    devices: ["unifi_adopt_device", "unifi_remove_device", "unifi_restart_device", "unifi_power_cycle_port"],
+    clients: ["unifi_authorize_guest", "unifi_unauthorize_guest"],
+    networks: ["unifi_create_network", "unifi_update_network", "unifi_delete_network"],
+    wifi: ["unifi_create_wifi", "unifi_update_wifi", "unifi_delete_wifi"],
+    hotspot: ["unifi_create_voucher", "unifi_delete_voucher", "unifi_bulk_delete_vouchers"],
+    firewall: [
+        "unifi_create_firewall_zone", "unifi_update_firewall_zone", "unifi_delete_firewall_zone",
+        "unifi_create_firewall_policy", "unifi_update_firewall_policy", "unifi_patch_firewall_policy",
+        "unifi_delete_firewall_policy", "unifi_reorder_firewall_policies",
+    ],
+    acl: ["unifi_create_acl_rule", "unifi_update_acl_rule", "unifi_delete_acl_rule", "unifi_reorder_acl_rules"],
+    "dns-policies": ["unifi_create_dns_policy", "unifi_update_dns_policy", "unifi_delete_dns_policy"],
+    "traffic-matching": [
+        "unifi_create_traffic_matching_list", "unifi_update_traffic_matching_list", "unifi_delete_traffic_matching_list",
+    ],
+};
+exports.WRITE_TOOLS = Object.values(exports.WRITE_TOOL_GROUPS).flat();
+const GROUPS = exports.WRITE_TOOL_GROUPS;
+/**
+ * The write tools a UNIFI_NETWORK_WRITE_TOOLS value enables, in catalog
+ * order: a comma-separated list of tool and group names, or "" / "none" for
+ * none. Names that are neither come back in unknown.
+ */
+function parseWriteTools(value) {
+    const names = value.split(",").map((name) => name.trim()).filter((name) => name !== "");
+    if (names.length === 1 && names[0].toLowerCase() === "none")
+        return { tools: [], unknown: [] };
+    const enabled = new Set();
+    const unknown = [];
+    for (const name of names) {
+        const tools = Object.hasOwn(GROUPS, name) ? GROUPS[name] : exports.WRITE_TOOLS.includes(name) ? [name] : undefined;
+        if (tools === undefined)
+            unknown.push(name);
+        else
+            for (const tool of tools)
+                enabled.add(tool);
+    }
+    return { tools: exports.WRITE_TOOLS.filter((tool) => enabled.has(tool)), unknown };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@owine/unifi-network-mcp",
-  "version": "2.15.0",
-  "description": "MCP server for the UniFi Network API",
+  "version": "3.1.0",
+  "description": "MCP server exposing the UniFi Network Integration API as tools for Claude and other MCP clients",
   "main": "dist/index.js",
   "bin": {
     "unifi-network-mcp": "dist/index.js"
@@ -12,17 +12,18 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "test:package": "pnpm run build && sh scripts/smoke-package.sh"
   },
   "engines": {
-    "node": "^22.13.0 || ^24.0.0"
+    "node": "^22.19.0 || ^24.0.0 || ^26.0.0"
   },
-  "packageManager": "pnpm@12.11.2",
+  "packageManager": "pnpm@12.16.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/owine/unifi-network-mcp.git"
@@ -32,23 +33,26 @@
     "network",
     "mcp",
     "model-context-protocol",
-    "ubiquiti"
+    "ubiquiti",
+    "unifi-network",
+    "mcp-server"
   ],
   "author": "owine",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "zod": "4.6.5"
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "undici": "8.12.3",
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.19.2",
+    "@types/node": "26.6.6",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "5.0.3",
-    "eslint": "10.12.0",
-    "lefthook": "2.2.1",
+    "@vitest/coverage-v8": "5.0.5",
+    "eslint": "10.14.0",
+    "lefthook": "2.2.2",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.71.1",
-    "vitest": "5.0.3"
+    "typescript-eslint": "8.72.1",
+    "vitest": "5.0.5"
   }
 }