@coffeerunhobby/mcp-ha-connect 2.5.3 → 2.5.4-rc.1

package/README.md

@@ -86,11 +86,11 @@ high-value questions an LLM can actually answer about your network:
 > above through two tools — `omada_browse` + `omada_read` — keeping the tool-schema budget
 > small for low-context models. See the Omada tool tables below for the full eager surface.
 
-## Available Tools (112 Total)
+## Available Tools (115 Total)
 
 With every plugin on in the default eager mode: Home Assistant 38 (including the 3 owner-question tools, when
-`MCP_OWNER_QUESTIONS_ENABLED` is on), Omada 49, `net_` 23, AI 1 and `invokeAction` 1 (only with `MCP_REST_ACTIONS`).
-In graph mode the Omada reads collapse into `omada_browse` + `omada_read` (Omada 26, 89 in total).
+`MCP_OWNER_QUESTIONS_ENABLED` is on), Omada 49, `net_` 26, AI 1 and `invokeAction` 1 (only with `MCP_REST_ACTIONS`).
+In graph mode the Omada reads collapse into `omada_browse` + `omada_read` (Omada 26, 92 in total).
 
 ### Home Assistant Tools (38)
 
@@ -264,10 +264,10 @@ Lets the controller enforce a schedule itself (e.g. a curfew) instead of a daily
 | `omada_getSiteNtpStatus` | Get the site's NTP server configuration and status |
 | `omada_setSiteNtpServers` | Replace the site's NTP server list (needs `CONFIGURE`; `dryRun` previews the change) |
 
-### Vendor-neutral Network Tools (23)
+### Vendor-neutral Network Tools (26)
 
 The `net_` tools describe networks the same way for every controller vendor: one shared model, with an adapter per
-vendor (TP-Link Omada, and Ruijie / Reyee routers read-only since 2.5.0; UniFi and MikroTik are planned). Each adapter
+vendor (TP-Link Omada, and Ruijie / Reyee routers since 2.5.0; UniFi and MikroTik are planned). Each adapter
 says per feature whether it is native, built from several objects, or unsupported (`net_capabilities`), and refuses what
 it can't do instead of dropping it. With several controllers configured, every `net_` tool takes an optional
 `controller` (`omada` or `ruijie`); without it Omada answers.
@@ -294,6 +294,8 @@ one is set in the controller's web UI. Reads need `QUERY`, changes `CONFIGURE`.
 | `net_getMdnsRepeater` / `net_setMdnsRepeater` | Whether mDNS (Bonjour) discovery is repeated between networks; switch it on or off, or change the networks (e.g. so Home Assistant discovers IoT devices). Discovery only: traffic still follows the rules |
 | `net_listFirmware` | The firmware each network device runs and, when the vendor offers one, the newer version with its release notes and whether `net_upgradeFirmware` can install it |
 | `net_upgradeFirmware` | **ADMIN.** Install the version the vendor offers for a device, only from the vendor's own download server; the device restarts keeping its settings, so everything behind it is offline for a few minutes (always needs a dry run first, then `allowLockout` and its `basis`). Ruijie routers only for now; on Omada firmware is listed, upgrades stay in the controller web UI |
+| `net_listReservations` | DHCP reservations: which device (MAC) always gets which address, on which network |
+| `net_setReservation` / `net_deleteReservation` | Reserve an address for a device (create, or change its reservation) or remove its reservation. The address must be a free host address in a routed network (the one given, or the one holding it): not the gateway, network or broadcast address, not reserved for or used right now by another device. An online device moved to another address loses its connections at its next DHCP renewal, so that needs `allowLockout`; a removed reservation changes nothing until the lease runs out. On Omada the reservations of the controller and this server (`MCP_SERVER_ADDRESSES`) are never moved or removed (pinning them to the address they have is fine), and their addresses are never reserved for another device; while where either is can't be told (address unresolvable, or `MCP_SERVER_ADDRESSES` not set), no existing reservation is moved or removed. A description is kept on Omada; Ruijie keeps none (at most 300 reservations there) |
 
 On Omada, a network isolation flag (use a block rule instead), a "guest" network type, switching IPv6 on, and WPA2/WPA3
 mixed mode are not available through the API and are refused. Rules are gateway ACLs (the gateway routes between the
@@ -305,13 +307,14 @@ usually set none, and a port can't be put back on its profile's). The mDNS repea
 one gateway mDNS rule: create it once in the web UI (with the services to repeat), then change it here; access point
 mDNS rules, several rules or a one-way rule are shown as `foreign` and left to the web UI.
 
-On a Ruijie / Reyee router (2.5.0, read-only, mapped on a RG-EG105G-V3 with ReyeeOS 2.324) the `net_` list tools show
+On a Ruijie / Reyee router (2.5.0, mapped on a RG-EG105G-V3 with ReyeeOS 2.324) the `net_` list tools show
 its LAN networks, the devices it sees on its LAN right now (named by their address lease), DHCP reservations, its
 ports (the WAN port as the protected uplink) and its access-control rules; rules the model can't say faithfully (a
 source "anywhere", source ports, IPv6, user groups, schedules, only some connection states, an interface restriction the
 model can't carry, ports for TCP or UDP only) are shown as `foreign`.
-Every change but a firmware upgrade (2.5.1: the version the router itself is offered, the same as its page's Online
-Upgrade) is refused for now: reservations and rules come next, then networks. It talks to the router's local web
+It changes DHCP reservations (2.5.4, the same calls as its page) and the firmware (2.5.1: the version the router itself
+is offered, the same as its page's Online Upgrade); every other change is refused for now: rules come next, then
+networks. It talks to the router's local web
 API with its admin password; use `https://` with `RUIJIE_CERT_SHA256` (the router's own login page hides the password
 with a key that is shipped in the page, so only HTTPS really protects it, and the router's self-signed certificate is
 best pinned: the RG-EG105G-V3 ships OpenSSL's sample identity, valid until 2122, likely the same on every unit). A refused login is never retried, because wrong passwords lock

package/dist/net/adapters/omada.d.ts

@@ -86,6 +86,9 @@ export declare class OmadaNetworkController implements NetworkController {
      */
     private buildPortAssign;
     private buildMdnsSet;
+    private buildReservation;
+    /** The device's reservation as the controller has it now (undefined: none; 'unread': the read failed). */
+    private readBack;
     plan(change: Change): Promise<Plan>;
     apply(plan: Plan, options?: {
         allowLockout?: boolean;

package/dist/net/adapters/omada.js

@@ -23,6 +23,7 @@ import { inSubnet, ipToNumber } from '../../utils/ipv4.js';
 import { redactSecrets } from '../../utils/redact.js';
 import { NetError, } from '../model.js';
 import { MAX_NETWORK_NAME, MAX_WIFI_NAME, checkBands, checkDhcp, checkGateway, checkName, checkNetworkUnique, checkVlan } from '../validate.js';
+import { checkReservationDelete, checkReservationSet } from '../reservations.js';
 import { GROUP_TYPE, controllerPath, controllerRisk, draftAsAcl, draftRule, isOwnedGroup, newRuleKey, ownedGroupName, resolve, ruleKey, tagged, toRule, } from './omadaRules.js';
 import { MDNS_GATEWAY, TAGS, cutOff, describeNetworks, linkPorts, toMdns, toPortNetworks, toPortProfile } from './omadaPorts.js';
 const PSEUDO_WLAN_ID = 'gateway';
@@ -299,10 +300,7 @@ export class OmadaNetworkController {
         return (await this.snapshot()).clients;
     }
     async listReservations() {
-        const rows = await this.client.accessControl.listDhcpReservations(this.options.siteId);
-        return rows
-            .filter((r) => typeof r.ip === 'string')
-            .map((r) => ({ mac: formatMac(r.mac), ip: String(r.ip), network: { id: r.netId }, ...(r.description ? { description: String(r.description) } : {}) }));
+        return toReservations(await this.client.accessControl.listDhcpReservations(this.options.siteId));
     }
     async listPortProfiles() {
         return (await this.client.networkConfig.listPortProfiles(this.options.siteId)).map(toPortProfile);
@@ -608,6 +606,107 @@ export class OmadaNetworkController {
             },
         };
     }
+    // ---- DHCP reservations (the checks every vendor shares are in ../reservations.ts) -------------
+    async buildReservation(change, snap) {
+        const raw = await this.client.accessControl.listDhcpReservations(snap.siteId);
+        const world = { networks: snap.networks, reservations: toReservations(raw), clients: snap.clients };
+        const rawOf = (mac) => raw.find((r) => normalizeMac(r.mac) === normalizeMac(mac));
+        // The controller's and this server's own reservations are never moved or removed; while where
+        // either is can't be told, no existing reservation is (like ports with devices on them).
+        const guard = (mac, ips) => {
+            const at = (addresses) => Array.isArray(addresses) && ips.some((ip) => ip !== undefined && addresses.includes(ipToNumber(ip)));
+            const who = at(this.controllerAddresses) ? 'the controller' : at(this.serverAddresses) ? 'this server' : undefined;
+            if (who)
+                throw new NetError('PROTECTED', `${mac} is ${who}: its address is never moved or released through the tools`);
+            const blind = !this.options.controllerHost
+                ? "the controller's address isn't known"
+                : this.controllerAddresses === 'unknown'
+                    ? "the controller's address can't be resolved"
+                    : this.serverAddresses === 'unknown'
+                        ? "this server's address can't be resolved"
+                        : this.serverAddresses === 'unset'
+                            ? "this server's address isn't configured (MCP_SERVER_ADDRESSES)"
+                            : undefined;
+            if (blind)
+                throw new NetError('PROTECTED', `${blind}, so its reservation can't be told apart: existing reservations are not moved or removed (a new one, or pinning a device to the address it has, still works)`);
+        };
+        const online = (mac) => snap.clients.find((c) => c.online && normalizeMac(c.mac) === normalizeMac(mac));
+        const extra = { reservations: raw.map(canonical) };
+        if (change.op === 'delete') {
+            const checked = checkReservationDelete(change.mac, world);
+            guard(checked.mac, [checked.current.ip, online(checked.mac)?.ip]);
+            const target = formatMac(rawOf(checked.mac).mac);
+            return {
+                steps: [{ ...checked.step, object: 'omada.dhcpReservation' }],
+                effects: checked.effects,
+                wouldLockOut: [],
+                reads: { networks: true },
+                extra,
+                execute: async (s) => {
+                    await this.client.networkConfig.deleteDhcpReservation(target, s.siteId);
+                    const after = await this.readBack(s.siteId, checked.mac);
+                    if (after === 'unread')
+                        return { applied: true, owned: [], warnings: [UNREAD] };
+                    if (after)
+                        throw new NetError('CONFLICT', `The controller accepted the removal but still shows a reservation for ${checked.mac}; check it with net_listReservations.`);
+                    return { applied: true, owned: [] };
+                },
+            };
+        }
+        const checked = checkReservationSet(change.value, world, { descriptions: true });
+        const device = online(checked.mac);
+        // Their address is theirs: reserved for anyone else, that device could take it at its next DHCP request.
+        const target = ipToNumber(checked.ip);
+        for (const [who, addresses] of [['the controller', this.controllerAddresses], ['this server', this.serverAddresses]]) {
+            if (Array.isArray(addresses) && addresses.includes(target) && device?.ip !== checked.ip) {
+                throw new NetError('PROTECTED', `${checked.ip} is ${who}'s address; it can't be reserved for another device`);
+            }
+        }
+        // Pinning such a device to the address it has is fine; moving it is not.
+        if ((checked.current && checked.current.ip !== checked.ip) || (device?.ip !== undefined && device.ip !== checked.ip))
+            guard(checked.mac, [checked.current?.ip, device?.ip]);
+        const before = rawOf(checked.mac);
+        const body = {
+            netId: checked.network.id,
+            mac: checked.mac,
+            ip: checked.ip,
+            description: checked.description || undefined,
+            status: true,
+            options: before?.options ?? [],
+        };
+        return {
+            steps: [{ ...checked.step, object: 'omada.dhcpReservation' }],
+            effects: checked.effects,
+            wouldLockOut: checked.wouldLockOut,
+            reads: { networks: true },
+            // The devices it moves, with the address the dry run saw them at: one elsewhere by now is a CONFLICT.
+            extra: { ...extra, moving: checked.wouldLockOut.map((c) => `${normalizeMac(c.mac)}@${c.ip ?? ''}`).sort() },
+            execute: async (s) => {
+                if (before)
+                    await this.client.networkConfig.updateDhcpReservation(formatMac(before.mac), body, s.siteId);
+                else
+                    await this.client.networkConfig.createDhcpReservation(body, s.siteId);
+                const after = await this.readBack(s.siteId, checked.mac);
+                if (after === 'unread')
+                    return { applied: true, owned: [], warnings: [UNREAD] };
+                if (!after || after.ip !== checked.ip || !('id' in after.network) || after.network.id !== checked.network.id || after.description !== checked.description) {
+                    throw new NetError('CONFLICT', `The controller accepted the reservation but shows something else for ${checked.mac} now; check it with net_listReservations.`);
+                }
+                return { applied: true, object: after, owned: [] };
+            },
+        };
+    }
+    /** The device's reservation as the controller has it now (undefined: none; 'unread': the read failed). */
+    async readBack(siteId, mac) {
+        let rows;
+        try {
+            rows = await this.client.accessControl.listDhcpReservations(siteId);
+        }
+        catch {
+            return 'unread';
+        }
+        return toReservations(rows).find((r) => normalizeMac(r.mac) === normalizeMac(mac));
+    }
     // ---- plan / apply ------------------------------------------------------------------
     async plan(change) {
         return await this.planWith(change, await this.snapshot());
@@ -672,6 +771,8 @@ export class OmadaNetworkController {
                 throw unsupported('creating or deleting port profiles here (do it in the controller web UI)', 'ports.profiles');
             case 'mdnsRepeater':
                 return await this.buildMdnsSet(change.enabled, change.networks, snap);
+            case 'reservation':
+                return await this.buildReservation(change, snap);
             case 'firmware':
                 // The Open API can (start-online-upgrade), but it isn't live-tested here yet.
                 throw new NetError('UNSUPPORTED', 'Upgrading Omada firmware through the net_ tools is not available yet; use the controller web UI (Devices > upgrade).', { capability: 'firmware' });
@@ -686,7 +787,7 @@ export class OmadaNetworkController {
                     return this.buildRuleMove(change.ref, change.position, snap);
                 break;
             default:
-                throw notYet(`${change.kind} changes`, change.kind === 'group' ? 'a later release (use omada_createGroup / omada_deleteGroup)' : 'a later release (use omada_setDhcpReservation)');
+                throw notYet(`${change.kind} changes`, 'a later release (use omada_createGroup / omada_deleteGroup)');
         }
         throw new NetError('INVALID', 'This change is not supported');
     }
@@ -1708,6 +1809,13 @@ function describeNetworkChanges(current, next) {
  * rules are sets (ids of networks, services...), so the same state listed in another order
  * fingerprints the same.
  */
+const UNREAD = 'The reservation change was accepted, but reading it back failed; check it with net_listReservations.';
+/** Controller reservations in the model (entries without an address are left out). */
+function toReservations(rows) {
+    return rows
+        .filter((r) => typeof r.ip === 'string')
+        .map((r) => ({ mac: formatMac(r.mac), ip: String(r.ip), network: { id: r.netId }, ...(r.description ? { description: String(r.description) } : {}) }));
+}
 function canonical(value) {
     if (Array.isArray(value)) {
         return value