@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.4.0

package/.env.example

@@ -117,7 +117,7 @@ MCP_HTTP_ALLOWED_ORIGINS=127.0.0.1,localhost,http://mcpserver.10.0.0.18.nip.io:3
 # usually different addresses. Loopback/bind host:port is always added for you.
 # Any Host header not listed here is rejected with 403.
 # Example (LAN IP + public domain):
-# MCP_HTTP_ALLOWED_HOSTS=192.168.0.18:3000,mcp.example.com
+# MCP_HTTP_ALLOWED_HOSTS=10.0.0.18:3000,mcp.example.com
 
 # -----------------------------------------------------------------------------
 # Rate Limiting (only when MCP_SERVER_USE_HTTP=true)

package/README.md

@@ -160,7 +160,7 @@ Known limit: cancellations and answers are kept in memory. After a restart, some
 | `listCalendars` | List all calendar entities |
 | `getCalendarEvents` | Get events from one or all calendars |
 
-### Omada Network Tools (32)
+### Omada Network Tools (49)
 
 #### Site Tools
 
@@ -208,6 +208,28 @@ Known limit: cancellations and answers are kept in memory. After a restart, some
 | `omada_cyclePoePort` | Power-cycle PoE switch ports (remote-reboots APs/cameras) |
 | `omada_setSsidEnabled` | Turn an SSID (e.g. guest WiFi) on or off by name |
 
+#### Client Diagnosis and MAC Groups
+
+| Tool | Description |
+|------|-------------|
+| `omada_diagnoseClient` | Explain why a device (by MAC) can't get on: block state, MAC groups and the SSID allow/deny lists using them, site MAC filter, IP-MAC binding, DHCP reservation, and for ADMIN callers the audit log (detects an orphaned block). Read-only |
+| `omada_listMacGroups` | List MAC groups with their entries and which SSIDs use them as allow or deny lists (graph mode: `omada_read /profiles/mac-groups`) |
+| `omada_setMacGroupEntry` | Add a MAC to a MAC group, or rename its entry (needs `CONFIGURE`) |
+| `omada_removeMacGroupEntry` | Remove a MAC from a MAC group (needs `CONFIGURE`) |
+
+#### Access Control (schedules, groups, gateway ACLs)
+
+Lets the controller enforce a schedule itself (e.g. a curfew) instead of a daily block/unblock loop. All writes need `CONFIGURE`.
+
+| Tool | Description |
+|------|-------------|
+| `omada_listAccessControl` | Time ranges (readable windows), IP groups and gateway ACL rules with names and schedules (graph mode: `omada_read` `/profiles/time-range`, `/profiles/ip-groups`, `/network/acls/gateway`) |
+| `omada_createTimeRange` / `omada_updateTimeRange` / `omada_deleteTimeRange` | Weekly schedules in quarter hours, e.g. `{days:["mon","tue"], start:"14:30", end:"19:00"}`; `invertWindows` turns allowed hours into the blocked ones. Delete is refused while a rule uses it |
+| `omada_createGroup` / `omada_deleteGroup` | IP groups (ACL sources/destinations) and MAC groups (SSID allow/deny lists); delete is refused for built-in groups and groups in use |
+| `omada_setDhcpReservation` / `omada_removeDhcpReservation` | Fixed IP for a device (so an ACL can match it); refuses an address reserved for another device |
+| `omada_createGatewayAcl` / `omada_updateGatewayAcl` / `omada_deleteGatewayAcl` / `omada_moveGatewayAcl` | Gateway (router) LAN-to-internet rules: allow/deny a source (IP group, LAN network or SSID), optionally only during a time range; covers wired and Wi-Fi |
+| `omada_setSsidMacFilter` | Turn an SSID's MAC filter on (MAC group as allow or deny list) or off; reports and refuses to disconnect connected clients unless `allowLockout`; `dryRun` previews |
+
 #### Security Tools
 
 | Tool | Description |
@@ -417,7 +439,7 @@ Clients only see the tools they may use: `tools/list` is filtered by the caller'
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `OMADA_PLUGIN_ENABLED` | `false` | Enable Omada plugin |
-| `OMADA_BASE_URL` | - | Omada controller URL (e.g., `https://192.168.0.1:8043`) |
+| `OMADA_BASE_URL` | - | Omada controller URL (e.g., `https://10.0.0.1:8043`) |
 | `OMADA_CLIENT_ID` | - | OAuth2 client ID from Omada controller |
 | `OMADA_CLIENT_SECRET` | - | OAuth2 client secret from Omada controller |
 | `OMADA_OMADAC_ID` | - | Omada controller ID |

package/dist/omadaClient/accessControl.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Controller-side access control: time-range profiles, IP/MAC group profiles,
+ * DHCP reservations, gateway ACL rules and the SSID MAC filter. These let a
+ * schedule (e.g. a curfew) be enforced by the controller itself instead of a
+ * daily block/unblock loop.
+ *
+ * Omada's create endpoints return no id, so new objects are found again by
+ * their (required unique) name or description. Deletes refuse objects that are
+ * still in use, and the SSID MAC filter refuses to lock out connected clients
+ * unless told to.
+ */
+import type { ClientOperations } from './client.js';
+import type { MacGroupOperations } from './macGroups.js';
+import type { NetworkOperations } from './network.js';
+import type { RequestHandler } from './request.js';
+import type { SiteOperations } from './site.js';
+import { type TimeRangeEntry } from './timeRange.js';
+export declare const IP_GROUP_TYPE = 0;
+/** All protocols, in Omada's ACL protocol numbering. */
+export declare const ALL_PROTOCOLS = 256;
+declare const SOURCE_TYPES: {
+    readonly network: 0;
+    readonly ipGroup: 1;
+    readonly ssid: 4;
+};
+declare const DESTINATION_TYPES: {
+    readonly network: 0;
+    readonly ipGroup: 1;
+};
+export type AclSourceType = keyof typeof SOURCE_TYPES;
+export type AclDestinationType = keyof typeof DESTINATION_TYPES;
+export interface TimeRangeProfile {
+    profileId: string;
+    name: string;
+    dayMode?: number;
+    timeList?: TimeRangeEntry[];
+    [field: string]: unknown;
+}
+export interface IpGroup {
+    groupId: string;
+    name: string;
+    buildIn?: boolean;
+    ipList?: Array<{
+        ip: string;
+        mask: number;
+        description?: string;
+    }>;
+    [field: string]: unknown;
+}
+export interface DhcpReservation {
+    netId: string;
+    mac: string;
+    ip?: string;
+    description?: string;
+    status?: boolean;
+    options?: unknown[];
+    [field: string]: unknown;
+}
+export interface GatewayAcl {
+    id: string;
+    index?: number;
+    description: string;
+    status: boolean;
+    policy: number;
+    protocols: number[];
+    sourceType: number;
+    sourceIds: string[];
+    destinationType: number;
+    destinationIds?: string[];
+    syslog?: boolean;
+    direction?: {
+        lanToWan: boolean;
+        lanToLan: boolean;
+        wanInIds: string[];
+        vpnInIds: string[];
+    };
+    stateMode?: number;
+    states?: unknown;
+    timeRangeId?: string;
+    [field: string]: unknown;
+}
+export interface GatewayAclInput {
+    description: string;
+    policy: 'allow' | 'deny';
+    source: {
+        type: AclSourceType;
+        ids: string[];
+    };
+    /** Default: the built-in IP group IPGroup_Any (everything). */
+    destination?: {
+        type: AclDestinationType;
+        ids: string[];
+    };
+    protocols?: number[];
+    /** Time-range profile (id or name) during which the rule applies; omitted = always. */
+    timeRange?: string;
+    enabled?: boolean;
+}
+export interface GatewayAclChanges {
+    description?: string;
+    policy?: 'allow' | 'deny';
+    source?: {
+        type: AclSourceType;
+        ids: string[];
+    };
+    destination?: {
+        type: AclDestinationType;
+        ids: string[];
+    };
+    protocols?: number[];
+    /** Profile id or name; null removes the schedule (rule always applies). */
+    timeRange?: string | null;
+    enabled?: boolean;
+}
+export interface SsidMacFilterChange {
+    ssid: string;
+    ssidId: string;
+    before: {
+        enabled: boolean;
+        policy?: 'allow' | 'deny';
+        group?: string;
+    };
+    after: {
+        enabled: boolean;
+        policy?: 'allow' | 'deny';
+        group?: string;
+    };
+    /** Currently connected clients of this SSID the new setting would cut off. */
+    wouldLockOut: Array<{
+        mac: string;
+        name?: string;
+    }>;
+    applied: boolean;
+}
+export declare class AccessControlOperations {
+    private readonly request;
+    private readonly site;
+    private readonly buildPath;
+    private readonly network;
+    private readonly macGroups;
+    private readonly clients;
+    constructor(request: RequestHandler, site: SiteOperations, buildPath: (path: string) => string, network: NetworkOperations, macGroups: MacGroupOperations, clients: ClientOperations);
+    createTimeRange(...a: Parameters<AccessControlOperations['createTimeRangeUnlocked']>): Promise<{
+        profileId: string;
+        name: string;
+        windows: string[];
+    }>;
+    updateTimeRange(...a: Parameters<AccessControlOperations['updateTimeRangeUnlocked']>): Promise<{
+        profileId: string;
+        name: string;
+        before: string[];
+        after: string[];
+    }>;
+    deleteTimeRange(...a: Parameters<AccessControlOperations['deleteTimeRangeUnlocked']>): Promise<{
+        profileId: string;
+        name: string;
+        deleted: boolean;
+    }>;
+    createGroup(...a: Parameters<AccessControlOperations['createGroupUnlocked']>): Promise<{
+        groupId: string;
+        name: string;
+        type: "mac" | "ip";
+        entries: {
+            ip: string;
+            mask: number;
+        }[] | {
+            name: string;
+            macAddress: string;
+        }[] | undefined;
+    }>;
+    deleteGroup(...a: Parameters<AccessControlOperations['deleteGroupUnlocked']>): Promise<{
+        groupId: string;
+        name: string;
+        type: "mac" | "ip";
+        deleted: boolean;
+    }>;
+    setDhcpReservation(...a: Parameters<AccessControlOperations['setDhcpReservationUnlocked']>): Promise<{
+        mac: string;
+        ip: string;
+        network: string;
+        action: "unchanged";
+    } | {
+        note: string;
+        previousIp?: string | undefined;
+        mac: string;
+        ip: string;
+        network: string;
+        action: "updated" | "created";
+    }>;
+    removeDhcpReservation(...a: Parameters<AccessControlOperations['removeDhcpReservationUnlocked']>): Promise<{
+        mac: string;
+        action: "not-present";
+        ip?: undefined;
+    } | {
+        mac: string;
+        ip: string | undefined;
+        action: "removed";
+    }>;
+    createGatewayAcl(...a: Parameters<AccessControlOperations['createGatewayAclUnlocked']>): Promise<{
+        id: string;
+        position: number | undefined;
+        description: string;
+        enabled: boolean;
+        policy: string;
+        source: string;
+        destination: string;
+        schedule: string | {
+            profileId: string;
+            name: string | undefined;
+            windows: string[] | undefined;
+        };
+    }>;
+    updateGatewayAcl(...a: Parameters<AccessControlOperations['updateGatewayAclUnlocked']>): Promise<{
+        id: string;
+        position: number | undefined;
+        description: string;
+        enabled: boolean;
+        policy: string;
+        source: string;
+        destination: string;
+        schedule: string | {
+            profileId: string;
+            name: string | undefined;
+            windows: string[] | undefined;
+        };
+    }>;
+    deleteGatewayAcl(...a: Parameters<AccessControlOperations['deleteGatewayAclUnlocked']>): Promise<{
+        id: string;
+        description: string;
+        deleted: boolean;
+    }>;
+    moveGatewayAcl(...a: Parameters<AccessControlOperations['moveGatewayAclUnlocked']>): Promise<{
+        order: string[];
+    }>;
+    setSsidMacFilter(...a: Parameters<AccessControlOperations['setSsidMacFilterUnlocked']>): Promise<SsidMacFilterChange>;
+    private locked;
+    private sitePath;
+    private send;
+    listTimeRanges(siteId?: string): Promise<Array<TimeRangeProfile & {
+        windows: string[];
+    }>>;
+    private createTimeRangeUnlocked;
+    private updateTimeRangeUnlocked;
+    private deleteTimeRangeUnlocked;
+    /** What references a time range: gateway and switch ACL rules, SSID WLAN schedules. */
+    private timeRangeUsers;
+    private resolveTimeRange;
+    listIpGroups(siteId?: string): Promise<IpGroup[]>;
+    /** Create an IP group (addresses as "a.b.c.d" or "a.b.c.d/n") or a MAC group. */
+    private createGroupUnlocked;
+    private deleteGroupUnlocked;
+    listDhcpReservations(siteId?: string): Promise<DhcpReservation[]>;
+    /** Reserve `ip` for a MAC (create or change). The LAN network is the one whose subnet holds the IP. */
+    private setDhcpReservationUnlocked;
+    private removeDhcpReservationUnlocked;
+    listGatewayAcls(siteId?: string): Promise<GatewayAcl[]>;
+    private createGatewayAclUnlocked;
+    private updateGatewayAclUnlocked;
+    private deleteGatewayAclUnlocked;
+    /** Move a rule to `position` (1 = evaluated first); the others keep their order. */
+    private moveGatewayAclUnlocked;
+    /** A rule with names instead of ids, for responses. */
+    describeAcl(acl: GatewayAcl, siteId?: string): Promise<{
+        id: string;
+        position: number | undefined;
+        description: string;
+        enabled: boolean;
+        policy: string;
+        source: string;
+        destination: string;
+        schedule: string | {
+            profileId: string;
+            name: string | undefined;
+            windows: string[] | undefined;
+        };
+    }>;
+    private resolveEndpoints;
+    /** Ids or names of IP groups, LAN networks or SSIDs -> ids. */
+    private resolveIds;
+    private endpointNames;
+    private timeRangeId;
+    private listSsidFilters;
+    /**
+     * Turn an SSID's MAC filter on (allow or deny list = a MAC group) or off.
+     * Reports which connected clients of that SSID the new setting would cut off,
+     * and refuses to apply then unless `allowLockout` is set. dryRun only reports.
+     */
+    private setSsidMacFilterUnlocked;
+}
+export {};