@coffeerunhobby/mcp-ha-connect 2.4.6 → 2.4.7

package/README.md

@@ -77,7 +77,7 @@ 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 (69 Total)
+## Available Tools (75 Total)
 
 ### Home Assistant Tools (38)
 
@@ -251,7 +251,7 @@ 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 (9)
+### Vendor-neutral Network Tools (15)
 
 The `net_` tools describe networks the same way for every controller vendor: one shared model, with an adapter per
 vendor (TP-Link Omada today; UniFi and MikroTik are planned). Each adapter says per feature whether it is native,
@@ -268,9 +268,16 @@ one is set in the controller's web UI. Reads need `QUERY`, changes `CONFIGURE`.
 | `net_createNetwork` / `net_updateNetwork` / `net_deleteNetwork` | Create or change a VLAN with its gateway and DHCP range. The network the controller is on is protected; delete is refused while a Wi-Fi network, port profile, reservation or rule uses it |
 | `net_listWifi` | Wi-Fi networks: network, bands, security, isolation, MAC filter |
 | `net_createWifi` / `net_updateWifi` / `net_deleteWifi` | Create or change an SSID on a given network (bands, WPA2/WPA3, PMF, isolation, hidden, 802.11r, MAC filter), or reset its password to a random one |
-
-On Omada, network isolation, a "guest" network type, switching IPv6 on, and WPA2/WPA3 mixed mode are not available
-through the API and are refused. Rules arrive in 2.4.7, switch ports and mDNS in 2.4.8.
+| `net_listRules` | Traffic rules in evaluation order (the first match decides); rules the model can't express are shown read-only (`foreign`, with the reason) |
+| `net_createRule` / `net_updateRule` / `net_deleteRule` / `net_moveRule` | Allow or block traffic from networks, a group or addresses to networks, a group, addresses (optionally on ports) or the internet, at a chosen position. **Stateful:** a block stops new connections, replies to connections started from the other side still pass ("block IoT → Home" lets Home still reach IoT). Addresses given in a rule become a group the rule owns and removes with it. A change after which the controller (and this server) could no longer reach the internet, in its end state or on the way there, is refused |
+| `net_listGroups` | Address groups (usable in rules) and MAC groups (Wi-Fi allow/deny lists) |
+
+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
+VLANs): LAN to LAN between your networks, LAN to WAN towards the internet. Refused with the reason: the gateway itself as
+a destination (no API option for its own addresses), one device by MAC (give its address), a Wi-Fi network as the
+source, rules that also match replies, schedules (the `omada_` time-range tools do those) and port ranges. Switch
+ports and mDNS arrive in 2.4.8.
 
 ### AI Tools (1)
 

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

@@ -1,9 +1,9 @@
 /**
  * Omada adapter for the vendor-neutral network model (src/net/model.ts).
  *
- * 2.4.5 covers networks (LAN networks / VLANs) and Wi-Fi (SSIDs). Rules, groups, switch
- * ports and mDNS arrive with 2.4.7 and 2.4.8; until then those calls fail with
- * NetError UNSUPPORTED.
+ * 2.4.5 covers networks (LAN networks / VLANs) and Wi-Fi (SSIDs); 2.4.7 rules (gateway
+ * ACLs, see omadaRules.ts) and listing groups. Switch ports and mDNS arrive with 2.4.8;
+ * until then those calls fail with NetError UNSUPPORTED.
  *
  * Omada specifics handled here:
  * - networks have no "guest" purpose and no isolation flag in the API (guest is per
@@ -14,7 +14,7 @@
  * - Omada lists every SSID again under a pseudo WLAN group "gateway" without detail.
  */
 import type { OmadaClient } from '../../omadaClient/index.js';
-import { type ApplyResult, type Capabilities, type Change, type Client, type Network, type NetworkController, type Plan, type ProtectedResources, type Reservation, type Wifi } from '../model.js';
+import { type ApplyResult, type Capabilities, type Change, type Client, type Group, type Network, type NetworkController, type Plan, type ProtectedResources, type Reservation, type Rule, type Wifi } from '../model.js';
 export interface OmadaAdapterOptions {
     siteId?: string;
     /** The controller's host name or address (host of OMADA_BASE_URL): its network is protected. */
@@ -49,8 +49,8 @@ export declare class OmadaNetworkController implements NetworkController {
     listReservations(): Promise<Reservation[]>;
     listPortProfiles(): Promise<never>;
     listPorts(): Promise<never>;
-    listRules(): Promise<never>;
-    listGroups(): Promise<never>;
+    listRules(): Promise<Rule[]>;
+    listGroups(kind?: Group['kind']): Promise<Group[]>;
     getMdnsRepeater(): Promise<never>;
     plan(change: Change): Promise<Plan>;
     apply(plan: Plan, options?: {
@@ -58,6 +58,60 @@ export declare class OmadaNetworkController implements NetworkController {
     }): Promise<ApplyResult>;
     private planWith;
     private build;
+    private ruleWorld;
+    /** The rule as the model sees it, with its raw ACL; a rule the model can't express is refused. */
+    private editableRule;
+    private checkPosition;
+    /**
+     * Refuses a change if any rule list it passes through (the end state, and the staged
+     * one where the rule is switched off) could expose some of the controller's (and this
+     * server's) internet traffic to a block that doesn't reach it today (controllerRisk).
+     * Waived only when the controller is certainly cut off already.
+     */
+    private guardController;
+    private buildRuleCreate;
+    private buildRuleUpdate;
+    private buildRuleDelete;
+    private buildRuleMove;
+    /**
+     * Existing ids for an endpoint, or the id of the group created for it. The group is
+     * tracked by its (unique) name before it is created, so a create whose answer or
+     * read-back got lost can still be found and undone.
+     */
+    private materialize;
+    /**
+     * Undoes a create that failed part-way and returns the error to throw. A create that
+     * was sent may have happened even if it reported an error: the rule is looked up by
+     * its description and removed before its groups. When that can't be confirmed, the
+     * groups stay (a live rule must never point at deleted groups) and the error says so.
+     */
+    private undoCreate;
+    /**
+     * Undoes an update that failed part-way and returns the error to throw: puts the rule
+     * back as it was (if the change may have been written) and removes the groups made
+     * for it, unless the rule might still point at them.
+     */
+    private undoUpdate;
+    /** Puts the rule order back after a move that failed (it may have happened anyway); returns the error to throw. */
+    private restoreOrder;
+    /** Deletes groups made during a failed change (found by name when the id is unknown); returns what it couldn't remove. */
+    private dropGroups;
+    /**
+     * Deletes every group a net_ rule owned that no ACL (gateway, switch or access point)
+     * references any more. Run after each successful rule change, so a cleanup that failed
+     * once is finished by the next change; a failure here is a warning, not an error (the
+     * change itself is done). Writes are serialized per site, so no rule is half-created
+     * meanwhile.
+     */
+    private sweepOwnedGroups;
+    private sortedAcls;
+    /** Moves one rule to `position` (1 = first); the others keep their order. */
+    private reorder;
+    /**
+     * The result of a change that is done: the rule as it reads back, plus warnings. A
+     * failed read-back is a warning, never an error: the change is already applied.
+     */
+    private done;
     private buildNetworkCreate;
     private buildNetworkUpdate;
     private buildNetworkDelete;