@owine/unifi-network-mcp 2.15.0 → 3.0.0

package/dist/client.js

@@ -1,42 +1,145 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NetworkClient = void 0;
+exports.withCallSignal = withCallSignal;
+const node_async_hooks_1 = require("node:async_hooks");
+// undici's own fetch, not the global one: Node's built-in fetch bundles an
+// older undici whose handlers the Agent from tls.ts (undici 8) rejects.
+const undici_1 = require("undici");
+const config_js_1 = require("./config.js");
+const guard_js_1 = require("./guard.js");
+const tls_js_1 = require("./tls.js");
+const write_log_js_1 = require("./write-log.js");
+// Well under undici's 300s default, so a stalled controller fails the call
+// before the MCP host gives up on it.
+const REQUEST_TIMEOUT_MS = 30_000;
+const HISTORY_TIMEOUT_MS = 25_000;
+// What undici reports when the console closed the connection under a
+// request, typically a kept-alive socket it had already timed out.
+const SOCKET_CLOSED = ["UND_ERR_SOCKET", "ECONNRESET", "EPIPE"];
+function socketClosed(err) {
+    const cause = err instanceof Error ? err.cause : undefined;
+    return cause instanceof Error && "code" in cause && typeof cause.code === "string" && SOCKET_CLOSED.includes(cause.code);
+}
+/**
+ * A request that failed in flight, worded so the model knows whether retrying
+ * is safe: a timed-out or cut-off write may already have been applied, and
+ * repeating a create would duplicate it. The timeout also covers reading the
+ * body, so this applies to the whole exchange, not only to fetch().
+ */
+function inFlightError(read, method, timeoutMs, err) {
+    const hint = read
+        ? "Retry when the console responds."
+        : `The ${method} may still have been applied; check the resource before retrying.`;
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+        return new Error(`UniFi controller did not respond within ${timeoutMs / 1000}s. ${hint}`, { cause: err });
+    }
+    if (!read && socketClosed(err)) {
+        return new Error(`The UniFi controller closed the connection during the ${method}. ${hint}`, { cause: err });
+    }
+    return err;
+}
+// The abort signal of the MCP tool call a request is made for. Without it a
+// cancelled (or abandoned) call keeps its request running, and a write lands
+// after the host has already reported the call as failed.
+const callSignal = new node_async_hooks_1.AsyncLocalStorage();
+/** Run fn so that every request it makes is aborted when signal is. */
+function withCallSignal(signal, fn) {
+    return signal ? callSignal.run(signal, fn) : fn();
+}
+const ERROR_BODY_LIMIT = 500;
+/**
+ * The useful part of an error body for the model: the API's documented
+ * message, code and request ID, or a capped excerpt of anything else (a proxy
+ * or UniFi OS HTML error page would otherwise land in the context whole).
+ */
+function describeErrorBody(text) {
+    try {
+        const body = JSON.parse(text);
+        if (body && typeof body === "object" && "message" in body && typeof body.message === "string") {
+            const details = [
+                "code" in body && typeof body.code === "string" ? body.code : undefined,
+                "requestId" in body && typeof body.requestId === "string" ? `request ${body.requestId}` : undefined,
+            ].filter((detail) => detail !== undefined);
+            const message = capped(body.message);
+            return details.length > 0 ? `${message} (${details.join("; ")})` : message;
+        }
+    }
+    catch {
+        // Not JSON: fall through to the excerpt.
+    }
+    return capped(text);
+}
+function capped(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > ERROR_BODY_LIMIT ? `${collapsed.slice(0, ERROR_BODY_LIMIT)}…` : collapsed;
+}
+function requestSignal(timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const caller = callSignal.getStore();
+    return caller ? AbortSignal.any([caller, timeout]) : timeout;
+}
 class NetworkClient {
-    baseUrl;
     headers;
     networkUrl;
+    dispatcher;
+    policy;
     constructor(config) {
         // Cloud Connector only exists behind api.ui.com. A console ID set against a
         // local controller is ignored rather than fatal: the other tools work fine
         // against that controller, and taking the whole server down helps nobody.
-        const useConnector = config.consoleId !== undefined && config.host === "api.ui.com";
+        const useConnector = config.consoleId !== undefined && (0, config_js_1.isSiteManagerHost)(config.host);
         if (config.consoleId !== undefined && !useConnector) {
             console.error(`Ignoring UNIFI_NETWORK_CONSOLE_ID: Cloud Connector requires host api.ui.com, but host is ${config.host}.`);
         }
         const consolePath = useConnector ? `/v1/connector/consoles/${config.consoleId}` : "";
         this.networkUrl = `https://${config.host}${consolePath}/proxy/network`;
-        this.baseUrl = `${this.networkUrl}/integration/v1`;
         this.headers = {
             "X-API-KEY": config.apiKey,
             "Content-Type": "application/json",
         };
-        if (!config.verifySsl) {
-            process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-        }
+        this.dispatcher = (0, tls_js_1.consoleDispatcher)(config);
+        this.policy = { readOnly: config.readOnly, ...(config.writeTools ? { writeTools: config.writeTools } : {}) };
     }
+    /**
+     * path is relative to the Integration API, as the tools pass it. The guard
+     * sees it as the canonical path under the Network application; the host and
+     * any Cloud Connector prefix are added only once it has passed.
+     */
     async request(method, path, body) {
-        const url = `${this.baseUrl}${path}`;
+        const canonical = `/integration/v1${path}`;
+        this.guard(method, canonical);
+        const url = `${this.networkUrl}${canonical}`;
+        const send = () => this.send(method, url, body).catch((err) => {
+            throw inFlightError(method === "GET", method, REQUEST_TIMEOUT_MS, err);
+        });
+        // A connection the console closed while it sat idle fails the next request
+        // on it. Nothing reached the console, and a read changes nothing anyway, so
+        // a read goes out once more on a fresh connection.
+        return method === "GET"
+            ? send().catch((err) => {
+                if (socketClosed(err))
+                    return send();
+                throw err;
+            })
+            : send();
+    }
+    async send(method, url, body) {
         const options = {
             method,
             headers: this.headers,
+            redirect: "error",
+            signal: requestSignal(REQUEST_TIMEOUT_MS),
+            dispatcher: this.dispatcher,
         };
         if (body !== undefined) {
             options.body = JSON.stringify(body);
         }
-        const response = await fetch(url, options);
+        const response = await (0, undici_1.fetch)(url, options);
+        if (method !== "GET")
+            (0, write_log_js_1.noteWriteStatus)(response.status);
         if (!response.ok) {
-            const text = await response.text();
-            throw new Error(`HTTP ${response.status}: ${text}`);
+            throw new Error(`HTTP ${response.status}: ${describeErrorBody(await response.text())}`);
         }
         const contentType = response.headers.get("content-type") ?? "";
         if (contentType.includes("application/json")) {
@@ -44,6 +147,19 @@ class NetworkClient {
         }
         return response.text();
     }
+    /** Check a request against the guard before anything is sent, and note writes for the write log. */
+    guard(method, path) {
+        try {
+            const route = (0, guard_js_1.guardRequest)(method, path, this.policy);
+            if (route.tools !== undefined)
+                (0, write_log_js_1.noteWriteRequest)(method, path);
+        }
+        catch (err) {
+            if (err instanceof guard_js_1.GuardError)
+                (0, write_log_js_1.noteRefusal)("request_guard", method, path);
+            throw err;
+        }
+    }
     async get(path) {
         return this.request("GET", path);
     }
@@ -86,11 +202,20 @@ class NetworkClient {
         }
     }
     async historyRequest(path, body) {
-        const response = await fetch(`${this.networkUrl}${path}`, {
-            method: body === undefined ? "GET" : "POST", headers: this.headers,
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-            redirect: "error", signal: AbortSignal.timeout(25000),
+        const method = body === undefined ? "GET" : "POST";
+        this.guard(method, path);
+        // Both history endpoints are reads, the POST included.
+        return this.readHistory(method, path, body).catch((err) => {
+            throw inFlightError(true, method, HISTORY_TIMEOUT_MS, err);
         });
+    }
+    async readHistory(method, path, body) {
+        const options = {
+            method, headers: this.headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            redirect: "error", signal: requestSignal(HISTORY_TIMEOUT_MS), dispatcher: this.dispatcher,
+        };
+        const response = await (0, undici_1.fetch)(`${this.networkUrl}${path}`, options);
         if (!response.ok) {
             // Drain before throwing: an unread body pins the socket until GC, so a
             // run of failures (say, a mis-scoped API key) would leak connections.
@@ -102,9 +227,10 @@ class NetworkClient {
             throw new Error("Controller history returned non-JSON data; verify controller authentication");
         }
         // Bound the body before parsing: controller session records can be large.
-        const reader = response.body?.getReader();
-        if (!reader)
+        if (response.body === null)
             throw new Error("Controller history returned no response body");
+        // undici types the body as an untyped stream; a fetch body is always bytes.
+        const reader = response.body.getReader();
         const chunks = [];
         let bytes = 0;
         try {

package/dist/config.d.ts

@@ -1,10 +1,21 @@
 import { z } from "zod";
+/**
+ * Whether host is api.ui.com however it is written: URL parsing lower-cases
+ * it and drops a port, and a trailing dot names the same host. The request
+ * goes to api.ui.com in each case, so each must get the same treatment.
+ */
+export declare function isSiteManagerHost(host: string): boolean;
 declare const configSchema: z.ZodObject<{
     host: z.ZodString;
     apiKey: z.ZodString;
     consoleId: z.ZodOptional<z.ZodString>;
     verifySsl: z.ZodDefault<z.ZodBoolean>;
     readOnly: z.ZodDefault<z.ZodBoolean>;
+    writeTools: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>>;
+    allowWanExposure: z.ZodOptional<z.ZodLiteral<true>>;
+    wanZoneIds: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    writeLog: z.ZodOptional<z.ZodString>;
+    caCert: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;

package/dist/config.js

@@ -1,7 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSiteManagerHost = isSiteManagerHost;
 exports.loadConfig = loadConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const zod_1 = require("zod");
+const tls_js_1 = require("./tls.js");
+const responses_js_1 = require("./utils/responses.js");
+const write_tools_js_1 = require("./write-tools.js");
+function holdsCertificate(pem) {
+    try {
+        return (0, tls_js_1.pemCertificates)(pem).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether host is api.ui.com however it is written: URL parsing lower-cases
+ * it and drops a port, and a trailing dot names the same host. The request
+ * goes to api.ui.com in each case, so each must get the same treatment.
+ */
+function isSiteManagerHost(host) {
+    try {
+        return new URL(`https://${host}`).hostname.replace(/\.$/, "") === "api.ui.com";
+    }
+    catch {
+        return false;
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const configSchema = zod_1.z.object({
     host: zod_1.z.string().min(1).describe("UniFi Network host (IP or hostname)"),
     apiKey: zod_1.z.string().min(1).describe("UniFi Network API key"),
@@ -18,8 +46,59 @@ const configSchema = zod_1.z.object({
         .boolean()
         .default(true)
         .describe("When true, only read-only tools are registered"),
+    writeTools: zod_1.z.string()
+        .transform((value, ctx) => {
+        const { tools, unknown } = (0, write_tools_js_1.parseWriteTools)(value);
+        if (unknown.length > 0) {
+            ctx.addIssue({
+                code: "custom",
+                message: `UNIFI_NETWORK_WRITE_TOOLS names unknown write tools or groups: ${unknown.join(", ")}. Groups: ${Object.keys(write_tools_js_1.WRITE_TOOL_GROUPS).join(", ")}. Tools: ${write_tools_js_1.WRITE_TOOLS.join(", ")}. Use "none" for no write tools.`,
+            });
+            return zod_1.z.NEVER;
+        }
+        return tools;
+    })
+        .optional()
+        .describe("The write tools to register; undefined registers them all"),
+    allowWanExposure: zod_1.z
+        .literal(true)
+        .optional()
+        .describe("When true, writes that could let traffic in from the WAN fall back to the confirm flow instead of being refused"),
+    wanZoneIds: zod_1.z
+        .array(zod_1.z.string().regex(UUID, "UNIFI_NETWORK_WAN_ZONE_IDS must be a comma-separated list of firewall zone IDs (UUIDs)"))
+        .transform((ids) => ids.map((id) => id.toLowerCase()))
+        .optional()
+        .describe("Firewall zone IDs to treat as the WAN, in addition to the system-defined External zone"),
+    writeLog: zod_1.z.string()
+        .refine(node_path_1.isAbsolute, "UNIFI_NETWORK_WRITE_LOG must be an absolute path (MCP hosts do not expand ~)")
+        .optional()
+        .describe("JSON Lines file every write tool call is appended to"),
+    caCert: zod_1.z.string()
+        .refine(holdsCertificate, "UNIFI_NETWORK_CA_CERT must name a PEM file containing a certificate")
+        .optional()
+        .describe("PEM certificate(s) to trust for the console, e.g. its own self-signed certificate"),
+}).refine((config) => config.verifySsl || config.caCert === undefined, {
+    path: ["caCert"],
+    message: "UNIFI_NETWORK_CA_CERT pins a certificate to verify against; it cannot be combined with UNIFI_NETWORK_VERIFY_SSL=false",
+}).refine((config) => config.verifySsl || !isSiteManagerHost(config.host), {
+    // Opting out of verification is for local consoles with self-signed
+    // certificates. A Site Manager key reaches every console on the account
+    // and crosses the internet, so it never goes out unverified.
+    path: ["verifySsl"],
+    message: "TLS verification cannot be disabled for api.ui.com; unset UNIFI_NETWORK_VERIFY_SSL",
 });
 function loadConfig() {
+    const caCertPath = process.env.UNIFI_NETWORK_CA_CERT;
+    let caCert;
+    if (caCertPath) {
+        try {
+            caCert = (0, node_fs_1.readFileSync)(caCertPath, "utf8");
+        }
+        catch (err) {
+            console.error(`Configuration error: cannot read UNIFI_NETWORK_CA_CERT (${caCertPath}): ${(0, responses_js_1.errorMessage)(err)}`);
+            process.exit(1);
+        }
+    }
     const result = configSchema.safeParse({
         host: process.env.UNIFI_NETWORK_HOST,
         apiKey: process.env.UNIFI_NETWORK_API_KEY,
@@ -27,10 +106,30 @@ function loadConfig() {
             ? { consoleId: process.env.UNIFI_NETWORK_CONSOLE_ID } : {}),
         verifySsl: process.env.UNIFI_NETWORK_VERIFY_SSL?.toLowerCase() !== "false",
         readOnly: process.env.UNIFI_NETWORK_READ_ONLY?.toLowerCase() !== "false",
+        ...(caCert !== undefined ? { caCert } : {}),
+        ...(process.env.UNIFI_NETWORK_ALLOW_WAN_EXPOSURE?.toLowerCase() === "true"
+            ? { allowWanExposure: true } : {}),
+        ...(process.env.UNIFI_NETWORK_WAN_ZONE_IDS
+            ? { wanZoneIds: process.env.UNIFI_NETWORK_WAN_ZONE_IDS.split(",").map((id) => id.trim()).filter((id) => id !== "") } : {}),
+        ...(process.env.UNIFI_NETWORK_WRITE_LOG
+            ? { writeLog: process.env.UNIFI_NETWORK_WRITE_LOG } : {}),
+        ...(process.env.UNIFI_NETWORK_WRITE_TOOLS !== undefined
+            ? { writeTools: process.env.UNIFI_NETWORK_WRITE_TOOLS } : {}),
     });
     if (!result.success) {
-        console.error("Configuration error:", result.error.format());
-        process.exit(1);
+        console.error(`Configuration error:\n${zod_1.z.prettifyError(result.error)}`);
+        return process.exit(1);
+    }
+    const config = result.data;
+    if (config.readOnly && config.writeTools !== undefined) {
+        // Still validated above, so a typo shows up before writes are turned on.
+        console.error("Ignoring UNIFI_NETWORK_WRITE_TOOLS: the server is read-only, so no write tools load. Set UNIFI_NETWORK_READ_ONLY=false to use it.");
+        delete config.writeTools;
+    }
+    if (config.readOnly && config.writeLog !== undefined) {
+        // Nothing would be logged, and opening the file could stop the server.
+        console.error("Ignoring UNIFI_NETWORK_WRITE_LOG: the server is read-only, so there are no write calls to log. Set UNIFI_NETWORK_READ_ONLY=false to use it.");
+        delete config.writeLog;
     }
-    return result.data;
+    return config;
 }

package/dist/guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The request guard: every request NetworkClient makes is checked here before
+ * fetch is called, against a fixed allowlist of the endpoints the tools in
+ * src/tools/ use. Anything else is refused and nothing is sent, so a tool bug,
+ * a smuggled ID or a misled model cannot reach the rest of the console with
+ * this API key (the legacy controller API, Protect, another console behind the
+ * Cloud Connector).
+ *
+ * Paths are canonical and relative to the Network application: they start
+ * /integration/v1, /v2/api or /api/s, never with the Cloud Connector prefix,
+ * which NetworkClient adds only after the guard has passed.
+ */
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type GuardReason = "malformed" | "method" | "not_allowlisted" | "query" | "read_only" | "tool_disabled";
+export declare class GuardError extends Error {
+    readonly reason: GuardReason;
+    constructor(reason: GuardReason, message: string);
+}
+export interface Route {
+    method: Method;
+    /** Canonical path; each {id} is one ID segment. */
+    template: string;
+    /** Query parameters the endpoint may be sent; any other is refused. */
+    query?: readonly string[];
+    /** Query parameters that must be present. */
+    requiredQuery?: readonly string[];
+    /**
+     * The write tools that send this request. A route without tools is a read,
+     * allowed whatever write tools are enabled — including stat/session's POST,
+     * which only queries statistics.
+     */
+    tools?: readonly string[];
+}
+export interface GuardPolicy {
+    readOnly: boolean;
+    /** Enabled write tools; undefined enables every write tool. */
+    writeTools?: readonly string[];
+}
+/** Every request the tools make. Keep in step with src/tools/; tests/guard.test.ts sweeps every tool against it. */
+export declare const ROUTES: readonly Route[];
+/**
+ * Check one request and return the route it matched. Throws GuardError,
+ * before anything is sent, for a malformed path, an unknown endpoint, an
+ * unexpected query parameter, or a write the policy does not allow.
+ */
+export declare function guardRequest(method: string, path: string, policy: GuardPolicy): Route;

package/dist/guard.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * The request guard: every request NetworkClient makes is checked here before
+ * fetch is called, against a fixed allowlist of the endpoints the tools in
+ * src/tools/ use. Anything else is refused and nothing is sent, so a tool bug,
+ * a smuggled ID or a misled model cannot reach the rest of the console with
+ * this API key (the legacy controller API, Protect, another console behind the
+ * Cloud Connector).
+ *
+ * Paths are canonical and relative to the Network application: they start
+ * /integration/v1, /v2/api or /api/s, never with the Cloud Connector prefix,
+ * which NetworkClient adds only after the guard has passed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTES = exports.GuardError = void 0;
+exports.guardRequest = guardRequest;
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+class GuardError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(`Request refused by the request guard: ${message}`);
+        this.reason = reason;
+        this.name = "GuardError";
+    }
+}
+exports.GuardError = GuardError;
+// The charset resourceId() and the site-reference check allow. "ordering" is
+// never an ID, in any case: excluding it keeps /policies/{id} and /acl-rules/{id} from also
+// matching the ordering endpoints, which belong to other tools.
+const ID = "(?![Oo][Rr][Dd][Ee][Rr][Ii][Nn][Gg](?:/|$))[A-Za-z0-9_-]{1,64}";
+const PAGE = ["offset", "limit", "filter"];
+const ZONE_PAIR = ["sourceFirewallZoneId", "destinationFirewallZoneId"];
+const v1 = (template) => `/integration/v1${template}`;
+/** Every request the tools make. Keep in step with src/tools/; tests/guard.test.ts sweeps every tool against it. */
+exports.ROUTES = [
+    // System, sites, supporting
+    { method: "GET", template: v1("/info") },
+    { method: "GET", template: v1("/sites"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/wans"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/vpn/site-to-site-tunnels"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/vpn/servers"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/radius/profiles"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/device-tags"), query: PAGE },
+    { method: "GET", template: v1("/dpi/categories"), query: PAGE },
+    { method: "GET", template: v1("/dpi/applications"), query: PAGE },
+    { method: "GET", template: v1("/countries"), query: PAGE },
+    // Devices
+    { method: "GET", template: v1("/sites/{id}/devices"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/devices/{id}") },
+    { method: "GET", template: v1("/sites/{id}/devices/{id}/statistics/latest") },
+    { method: "GET", template: v1("/pending-devices"), query: PAGE },
+    { method: "POST", template: v1("/sites/{id}/devices"), tools: ["unifi_adopt_device"] },
+    { method: "DELETE", template: v1("/sites/{id}/devices/{id}"), tools: ["unifi_remove_device"] },
+    { method: "POST", template: v1("/sites/{id}/devices/{id}/actions"), tools: ["unifi_restart_device"] },
+    { method: "POST", template: v1("/sites/{id}/devices/{id}/interfaces/ports/{id}/actions"), tools: ["unifi_power_cycle_port"] },
+    // Clients
+    { method: "GET", template: v1("/sites/{id}/clients"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/clients/{id}") },
+    { method: "POST", template: v1("/sites/{id}/clients/{id}/actions"), tools: ["unifi_authorize_guest", "unifi_unauthorize_guest"] },
+    // Client history: controller routes outside the Integration API
+    { method: "GET", template: "/v2/api/site/{id}/clients/history", query: ["withinHours"], requiredQuery: ["withinHours"] },
+    { method: "POST", template: "/api/s/{id}/stat/session" },
+    // Networks
+    { method: "GET", template: v1("/sites/{id}/networks"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/networks/{id}") },
+    { method: "GET", template: v1("/sites/{id}/networks/{id}/references") },
+    { method: "POST", template: v1("/sites/{id}/networks"), tools: ["unifi_create_network"] },
+    { method: "PUT", template: v1("/sites/{id}/networks/{id}"), tools: ["unifi_update_network"] },
+    { method: "DELETE", template: v1("/sites/{id}/networks/{id}"), query: ["force"], tools: ["unifi_delete_network"] },
+    // WiFi
+    { method: "GET", template: v1("/sites/{id}/wifi/broadcasts"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/wifi/broadcasts/{id}") },
+    { method: "POST", template: v1("/sites/{id}/wifi/broadcasts"), tools: ["unifi_create_wifi"] },
+    { method: "PUT", template: v1("/sites/{id}/wifi/broadcasts/{id}"), tools: ["unifi_update_wifi"] },
+    { method: "DELETE", template: v1("/sites/{id}/wifi/broadcasts/{id}"), query: ["force"], tools: ["unifi_delete_wifi"] },
+    // Hotspot vouchers
+    { method: "GET", template: v1("/sites/{id}/hotspot/vouchers"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/hotspot/vouchers/{id}") },
+    { method: "POST", template: v1("/sites/{id}/hotspot/vouchers"), tools: ["unifi_create_voucher"] },
+    { method: "DELETE", template: v1("/sites/{id}/hotspot/vouchers/{id}"), tools: ["unifi_delete_voucher"] },
+    { method: "DELETE", template: v1("/sites/{id}/hotspot/vouchers"), query: ["filter"], requiredQuery: ["filter"], tools: ["unifi_bulk_delete_vouchers"] },
+    // Firewall zones and policies
+    { method: "GET", template: v1("/sites/{id}/firewall/zones"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/firewall/zones/{id}") },
+    { method: "POST", template: v1("/sites/{id}/firewall/zones"), tools: ["unifi_create_firewall_zone"] },
+    { method: "PUT", template: v1("/sites/{id}/firewall/zones/{id}"), tools: ["unifi_update_firewall_zone"] },
+    { method: "DELETE", template: v1("/sites/{id}/firewall/zones/{id}"), tools: ["unifi_delete_firewall_zone"] },
+    { method: "GET", template: v1("/sites/{id}/firewall/policies"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/firewall/policies/{id}") },
+    { method: "GET", template: v1("/sites/{id}/firewall/policies/ordering"), query: ZONE_PAIR, requiredQuery: ZONE_PAIR },
+    { method: "POST", template: v1("/sites/{id}/firewall/policies"), tools: ["unifi_create_firewall_policy"] },
+    { method: "PUT", template: v1("/sites/{id}/firewall/policies/{id}"), tools: ["unifi_update_firewall_policy"] },
+    { method: "PATCH", template: v1("/sites/{id}/firewall/policies/{id}"), tools: ["unifi_patch_firewall_policy"] },
+    { method: "DELETE", template: v1("/sites/{id}/firewall/policies/{id}"), tools: ["unifi_delete_firewall_policy"] },
+    { method: "PUT", template: v1("/sites/{id}/firewall/policies/ordering"), query: ZONE_PAIR, requiredQuery: ZONE_PAIR, tools: ["unifi_reorder_firewall_policies"] },
+    // ACL rules
+    { method: "GET", template: v1("/sites/{id}/acl-rules"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/acl-rules/{id}") },
+    { method: "GET", template: v1("/sites/{id}/acl-rules/ordering") },
+    { method: "POST", template: v1("/sites/{id}/acl-rules"), tools: ["unifi_create_acl_rule"] },
+    { method: "PUT", template: v1("/sites/{id}/acl-rules/{id}"), tools: ["unifi_update_acl_rule"] },
+    { method: "DELETE", template: v1("/sites/{id}/acl-rules/{id}"), tools: ["unifi_delete_acl_rule"] },
+    { method: "PUT", template: v1("/sites/{id}/acl-rules/ordering"), tools: ["unifi_reorder_acl_rules"] },
+    // Switching
+    { method: "GET", template: v1("/sites/{id}/switching/switch-stacks"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/switching/switch-stacks/{id}") },
+    { method: "GET", template: v1("/sites/{id}/switching/mc-lag-domains"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/switching/mc-lag-domains/{id}") },
+    { method: "GET", template: v1("/sites/{id}/switching/lags"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/switching/lags/{id}") },
+    // DNS policies
+    { method: "GET", template: v1("/sites/{id}/dns/policies"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/dns/policies/{id}") },
+    { method: "POST", template: v1("/sites/{id}/dns/policies"), tools: ["unifi_create_dns_policy"] },
+    { method: "PUT", template: v1("/sites/{id}/dns/policies/{id}"), tools: ["unifi_update_dns_policy"] },
+    { method: "DELETE", template: v1("/sites/{id}/dns/policies/{id}"), tools: ["unifi_delete_dns_policy"] },
+    // Traffic matching lists
+    { method: "GET", template: v1("/sites/{id}/traffic-matching-lists"), query: PAGE },
+    { method: "GET", template: v1("/sites/{id}/traffic-matching-lists/{id}") },
+    { method: "POST", template: v1("/sites/{id}/traffic-matching-lists"), tools: ["unifi_create_traffic_matching_list"] },
+    { method: "PUT", template: v1("/sites/{id}/traffic-matching-lists/{id}"), tools: ["unifi_update_traffic_matching_list"] },
+    { method: "DELETE", template: v1("/sites/{id}/traffic-matching-lists/{id}"), tools: ["unifi_delete_traffic_matching_list"] },
+];
+const COMPILED = exports.ROUTES.map((route) => ({
+    route,
+    pattern: new RegExp(`^${route.template.replaceAll("{id}", ID)}$`),
+}));
+/**
+ * Check one request and return the route it matched. Throws GuardError,
+ * before anything is sent, for a malformed path, an unknown endpoint, an
+ * unexpected query parameter, or a write the policy does not allow.
+ */
+function guardRequest(method, path, policy) {
+    if (!METHODS.includes(method)) {
+        throw new GuardError("method", `method ${JSON.stringify(method)} is not used by any tool`);
+    }
+    const queryStart = path.indexOf("?");
+    const pathname = queryStart === -1 ? path : path.slice(0, queryStart);
+    const query = queryStart === -1 ? "" : path.slice(queryStart + 1);
+    // URL parsing would fold `..`, `\` and encoded segments out of the path, and
+    // `#` truncates it; `;` carries path parameters some servers honour. The
+    // tools never need any of these in a path, so refuse rather than normalise.
+    // eslint-disable-next-line no-control-regex
+    if (/\.\.|\/\/|%|\\|;|#|[\u0000-\u001f\u007f]/.test(pathname) || /#|[\u0000-\u001f\u007f]/.test(query)) {
+        throw new GuardError("malformed", `path ${JSON.stringify(pathname)} contains a sequence no tool sends`);
+    }
+    const match = COMPILED.find(({ route, pattern }) => route.method === method && pattern.test(pathname));
+    if (!match) {
+        throw new GuardError("not_allowlisted", `${method} ${pathname} is not an endpoint any tool uses`);
+    }
+    const { route } = match;
+    const keys = [...new URLSearchParams(query).keys()];
+    const unexpected = keys.filter((key) => !(route.query ?? []).includes(key));
+    if (unexpected.length > 0) {
+        throw new GuardError("query", `${method} ${pathname} does not take ${unexpected.join(", ")}`);
+    }
+    const missing = (route.requiredQuery ?? []).filter((key) => !keys.includes(key));
+    if (missing.length > 0) {
+        throw new GuardError("query", `${method} ${pathname} needs ${missing.join(", ")}`);
+    }
+    if (route.tools !== undefined) {
+        if (policy.readOnly) {
+            throw new GuardError("read_only", `${method} ${pathname} is a write, and the server is read-only`);
+        }
+        const enabled = policy.writeTools;
+        if (enabled !== undefined && !route.tools.some((tool) => enabled.includes(tool))) {
+            throw new GuardError("tool_disabled", `${method} ${pathname} belongs to ${route.tools.join(", ")}, which UNIFI_NETWORK_WRITE_TOOLS does not enable`);
+        }
+    }
+    return route;
+}

package/dist/index.js

@@ -7,23 +7,34 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const config_js_1 = require("./config.js");
 const client_js_1 = require("./client.js");
 const index_js_1 = require("./tools/index.js");
+const instructions_js_1 = require("./instructions.js");
+const write_log_js_1 = require("./write-log.js");
 // Read at runtime rather than importing: package.json sits outside rootDir,
 // so a static import would emit dist/src/ and break the published layout.
 const { version } = (0, node_module_1.createRequire)(__filename)("../package.json");
 async function main() {
     const config = (0, config_js_1.loadConfig)();
+    const writeLog = config.writeLog === undefined ? undefined : (0, write_log_js_1.openWriteLog)(config.writeLog, config.apiKey);
     const client = new client_js_1.NetworkClient(config);
-    const server = new mcp_js_1.McpServer({
-        name: "unifi-network",
-        version,
+    const server = new mcp_js_1.McpServer({ name: "unifi-network", title: "UniFi Network", version }, { instructions: (0, instructions_js_1.serverInstructions)(config.readOnly, { writeTools: config.writeTools, allowWanExposure: config.allowWanExposure === true }) });
+    (0, index_js_1.registerAllTools)(server, client, config.readOnly, {
+        writeTools: config.writeTools,
+        wan: { allowExposure: config.allowWanExposure === true, zoneIds: config.wanZoneIds ?? [] },
+        ...(writeLog ? { writeLog } : {}),
     });
-    (0, index_js_1.registerAllTools)(server, client, config.readOnly);
     if (config.readOnly) {
         console.error("UniFi Network MCP server running on stdio (READ-ONLY mode)");
     }
+    else if (config.writeTools !== undefined) {
+        const tools = config.writeTools.length > 0 ? config.writeTools.join(", ") : "none";
+        console.error(`UniFi Network MCP server running on stdio (write tools: ${tools})`);
+    }
     else {
         console.error("UniFi Network MCP server running on stdio");
     }
+    if (!config.readOnly && config.allowWanExposure === true) {
+        console.error("WAN-exposure refusals are off (UNIFI_NETWORK_ALLOW_WAN_EXPOSURE=true): such writes only need confirm.");
+    }
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
 }

package/dist/instructions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server instructions: guidance that applies across tools. MCP hosts place
+ * these in the model's context once, so cross-tool workflow lives here rather
+ * than being restated in tool descriptions.
+ */
+export declare function serverInstructions(readOnly: boolean, { writeTools, allowWanExposure }?: {
+    writeTools?: readonly string[];
+    allowWanExposure?: boolean;
+}): string;