@coffeerunhobby/mcp-ha-connect 1.3.0 → 1.3.4

package/src/config.ts

@@ -55,6 +55,10 @@ const envSchema = z
     logFormat: z.enum(['plain', 'json', 'gcp-json']).optional().default('plain'),
     useHttp: createBooleanStringSchema(false),
     stateful: createBooleanStringSchema(false),
+    // Tool registration strategy. `eager` (default) registers every typed tool;
+    // `graph` registers the Omada resource-graph reads (omada_browse/omada_read)
+    // plus typed writes, shrinking the tool-schema budget for low-context models.
+    toolRegistrationMode: z.enum(['eager', 'graph']).optional().default('eager'),
 
     // MCP Server HTTP Configuration
     httpPort: numericStringSchema,
@@ -200,6 +204,7 @@ export interface EnvironmentConfig {
   logFormat: 'plain' | 'json' | 'gcp-json';
   useHttp: boolean;
   stateful: boolean;
+  toolRegistrationMode: 'eager' | 'graph';
 
   // MCP Server HTTP Configuration
   httpPort?: number;
@@ -269,6 +274,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     logFormat: env.MCP_SERVER_LOG_FORMAT,
     useHttp: env.MCP_SERVER_USE_HTTP,
     stateful: env.MCP_SERVER_STATEFUL,
+    toolRegistrationMode: env.MCP_TOOL_REGISTRATION_MODE,
 
     // MCP Server HTTP Configuration
     httpPort: env.MCP_HTTP_PORT,
@@ -362,6 +368,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): EnvironmentCon
     logFormat: parsed.data.logFormat,
     useHttp: parsed.data.useHttp,
     stateful: parsed.data.stateful,
+    toolRegistrationMode: parsed.data.toolRegistrationMode,
 
     // MCP Server HTTP Configuration
     httpPort,

package/src/index.ts

@@ -9,6 +9,7 @@ import { loadConfig } from './config.js';
 import { HaClient } from './haClient/index.js';
 import { LocalAIClient } from './localAI/index.js';
 import { OmadaClient } from './omadaClient/index.js';
+import { checkConfiguredSite } from './omadaClient/site.js';
 import { startHttpServer } from './server/http.js';
 import { startStdioServer } from './server/stdio.js';
 import { initLogger, logger } from './utils/logger.js';
@@ -71,7 +72,18 @@ async function main(): Promise<void> {
 
           // Test Omada connection by listing sites
           const sites = await omadaClient.listSites();
-          logger.info('Connected to Omada controller', { siteCount: sites.length });
+
+          // Omada is the source of truth: a configured OMADA_SITE_ID that isn't
+          // on the controller is a deployment bug (drifted site id), not a
+          // transient outage. Fail the Omada plugin loudly — HA and AI keep
+          // working — instead of silently scoping every read to a dead site.
+          const siteError = checkConfiguredSite(config.siteId, sites);
+          if (siteError) {
+            logger.error(`Omada plugin disabled - invalid OMADA_SITE_ID. ${siteError}`);
+            omadaClient = undefined;
+          } else {
+            logger.info('Connected to Omada controller', { siteCount: sites.length });
+          }
         } catch (error) {
           logger.warn('Omada controller not available - Omada tools will be disabled', {
             error: error instanceof Error ? error.message : String(error),
@@ -115,7 +127,12 @@ async function main(): Promise<void> {
     if (config.useHttp) {
       await startHttpServer({ haClient, omadaClient, aiClient, config });
     } else {
-      await startStdioServer({ haClient, omadaClient, aiClient });
+      await startStdioServer({
+        haClient,
+        omadaClient,
+        aiClient,
+        toolRegistrationMode: config.toolRegistrationMode,
+      });
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/src/omadaClient/index.ts

@@ -9,6 +9,7 @@ import type {
     GetThreatListOptions,
     ListClientsPastConnectionsOptions,
     OmadaClientInfo,
+    OmadaApiResponse,
     OmadaDeviceInfo,
     OmadaDeviceStats,
     OmadaSiteSummary,
@@ -204,6 +205,70 @@ export class OmadaClient {
         return await this.request.request<T>(config);
     }
 
+    /**
+     * Read an arbitrary Omada resource described by a path template.
+     *
+     * This is the single client primitive behind the resource-graph `omada_read`
+     * tool: "many endpoints, zero new client methods". A path template may contain
+     * `{placeholder}` segments (each substituted from `siteId`/`pathParams` and
+     * URL-encoded), and may be site-scoped (the common case) or controller-global.
+     *
+     * Pagination is deliberately SINGLE-page: for paginated resources it forwards
+     * one page/pageSize to a single GET rather than walking every page (no giant
+     * payloads). It returns the unwrapped `result` (errorCode !== 0 throws via
+     * `ensureSuccess`).
+     *
+     * @param options.pathTemplate  e.g. '/sites/{siteId}/gateways/{gatewayMac}/wan-status'
+     * @param options.siteScoped    when true (default) `{siteId}` is resolved from siteId/default
+     * @param options.paginated     when true, page/pageSize are sent as query params
+     * @param options.pathParams    values for non-site `{placeholder}` segments
+     * @param options.query         extra query parameters
+     */
+    public async readResource(options: {
+        pathTemplate: string;
+        siteScoped?: boolean;
+        paginated?: boolean;
+        siteId?: string;
+        pathParams?: Record<string, string>;
+        query?: Record<string, unknown>;
+        page?: number;
+        pageSize?: number;
+    }): Promise<unknown> {
+        const {
+            pathTemplate,
+            siteScoped = true,
+            paginated = false,
+            siteId,
+            pathParams = {},
+            query = {},
+            page,
+            pageSize,
+        } = options;
+
+        const substitutions: Record<string, string> = { ...pathParams };
+        if (siteScoped || pathTemplate.includes('{siteId}')) {
+            substitutions.siteId = this.siteOps.resolveSiteId(siteId);
+        }
+
+        const relativePath = pathTemplate.replace(/\{(\w+)\}/g, (_match, key: string) => {
+            const value = substitutions[key];
+            if (value === undefined || value === '') {
+                throw new Error(`Missing required path parameter '${key}' for resource '${pathTemplate}'`);
+            }
+            return encodeURIComponent(value);
+        });
+
+        const effectiveQuery: Record<string, unknown> = { ...query };
+        if (paginated) {
+            effectiveQuery.page = page ?? 1;
+            effectiveQuery.pageSize = pageSize ?? 50;
+        }
+
+        const fullPath = this.buildOmadaPath(relativePath);
+        const response = await this.request.get<OmadaApiResponse<unknown>>(fullPath, effectiveQuery);
+        return this.request.ensureSuccess(response);
+    }
+
     /**
      * Build a full Omada API path from a relative path.
      * @param relativePath - The relative path to append to the base API path

package/src/omadaClient/request.ts

@@ -156,8 +156,21 @@ export class RequestHandler {
                     url: config.url,
                     status: response.status,
                     statusText: response.statusText,
+                    errorCode,
+                    message: errorMsg,
                 });
-                throw new Error(`Omada API request failed: ${response.status} ${response.statusText}`);
+                // Surface the controller's own structured errorCode/msg when present
+                // (safe diagnostic data — the controller's description, not an internal
+                // hostname/header) so a rejected request explains itself instead of
+                // collapsing to a bare HTTP status like "400 ".
+                const parts = [`${response.status} ${response.statusText}`.trim()];
+                if (errorMsg) {
+                    parts.push(`- ${errorMsg}`);
+                }
+                if (errorCode !== undefined && errorCode !== 0) {
+                    parts.push(`(errorCode ${errorCode})`);
+                }
+                throw new Error(`Omada API request failed: ${parts.join(' ')}`);
             }
 
             return responseData;

package/src/omadaClient/site.ts

@@ -2,6 +2,35 @@ import type { OmadaSiteSummary } from '../types/index.js';
 
 import type { RequestHandler } from './request.js';
 
+/**
+ * Validate a configured default site (`OMADA_SITE_ID`) against the controller's
+ * live site list.
+ *
+ * The Omada controller is the source of truth; `OMADA_SITE_ID` is only a
+ * selector/filter against it. A value that isn't on the controller is a
+ * deployment/configuration bug (e.g. the site id drifted after a controller
+ * migration, exactly like `OMADA_OMADAC_ID` does) — not a transient outage. If
+ * left unvalidated it silently scopes every site-scoped read to a dead site and
+ * surfaces later as a mysterious "user does not have permissions to access this
+ * site" error.
+ *
+ * @returns an actionable error message if `OMADA_SITE_ID` is set but absent from
+ *   `sites`; `null` if it is unset (no default) or valid.
+ */
+export function checkConfiguredSite(
+    configuredSiteId: string | undefined,
+    sites: OmadaSiteSummary[]
+): string | null {
+    if (!configuredSiteId) {
+        return null;
+    }
+    if (sites.some((s) => s.siteId === configuredSiteId)) {
+        return null;
+    }
+    const available = sites.map((s) => `${s.name} (${s.siteId})`).join(', ') || '(controller returned no sites)';
+    return `OMADA_SITE_ID="${configuredSiteId}" was not found on the controller. Set OMADA_SITE_ID to one of: ${available}.`;
+}
+
 /**
  * Site-related operations for the Omada API.
  */

package/src/permissions/index.ts

@@ -38,17 +38,36 @@ export interface PermissionsConfig {
   defaultRole?: RoleName;
 }
 
+/**
+ * Resolve a role name to its permission mask, case-insensitively.
+ *
+ * Config (and JSON) commonly use lowercase role names ("operator") while the
+ * `Role` map is keyed uppercase ("OPERATOR"). Normalize here so BOTH the per-user
+ * role and the `defaultRole` fall-back resolve consistently. An unknown/undefined
+ * name fails closed to `Role.NONE` (never `undefined`, which downstream coerces to
+ * a zero mask anyway but is easy to mishandle).
+ */
+function resolveRoleName(name: string | undefined): number {
+  if (!name) {
+    return Role.NONE;
+  }
+  const key = name.toUpperCase() as RoleName;
+  return Role[key] ?? Role.NONE;
+}
+
 /**
  * Get permission mask for a user by their JWT sub claim
  */
 export function getUserPermissions(sub: string | undefined, config: PermissionsConfig): number {
+  const fallback = resolveRoleName(config.defaultRole);
+
   if (!sub) {
-    return config.defaultRole ? Role[config.defaultRole] : Role.NONE;
+    return fallback;
   }
 
   const user = config.users.find((u) => u.sub === sub);
   if (!user) {
-    return config.defaultRole ? Role[config.defaultRole] : Role.NONE;
+    return fallback;
   }
 
   // Direct mask takes precedence over role
@@ -56,9 +75,7 @@ export function getUserPermissions(sub: string | undefined, config: PermissionsC
     return user.mask;
   }
 
-  // Convert role to uppercase for lookup (config may have lowercase)
-  const roleKey = user.role?.toUpperCase() as RoleName | undefined;
-  return roleKey && Role[roleKey] !== undefined ? Role[roleKey] : Role.NONE;
+  return resolveRoleName(user.role);
 }
 
 /**

package/src/server/common.ts

@@ -8,6 +8,7 @@ import type { HaClient } from '../haClient/index.js';
 import type { LocalAIClient } from '../localAI/index.js';
 import type { OmadaClient } from '../omadaClient/index.js';
 import { registerAllTools } from '../tools/index.js';
+import type { OmadaRegistrationMode } from '../tools/omada/index.js';
 import { registerAllResources } from '../resources/index.js';
 import { generateInstructions } from './instructions.js';
 import { logger } from '../utils/logger.js';
@@ -17,10 +18,12 @@ export interface CreateServerOptions {
   haClient?: HaClient;
   omadaClient?: OmadaClient;
   aiClient?: LocalAIClient;
+  /** Tool registration strategy for the Omada plugin (default 'eager'). */
+  toolRegistrationMode?: OmadaRegistrationMode;
 }
 
 export function createServer(options: CreateServerOptions): McpServer {
-  const { haClient, omadaClient, aiClient } = options;
+  const { haClient, omadaClient, aiClient, toolRegistrationMode } = options;
   logger.debug('Creating MCP server instance');
 
   // Generate instructions based on enabled plugins
@@ -48,6 +51,7 @@ export function createServer(options: CreateServerOptions): McpServer {
     haClient,
     omadaClient,
     aiClient,
+    toolRegistrationMode,
   });
 
   // Register Home Assistant resources (if HA client provided)

package/src/server/stdio.ts

@@ -9,12 +9,15 @@ import type { LocalAIClient } from '../localAI/index.js';
 import type { OmadaClient } from '../omadaClient/index.js';
 import { logger } from '../utils/logger.js';
 import { setLocalFullTrust } from '../tools/common.js';
+import type { OmadaRegistrationMode } from '../tools/omada/index.js';
 import { createServer } from './common.js';
 
 export interface StdioServerOptions {
   haClient?: HaClient;
   omadaClient?: OmadaClient;
   aiClient?: LocalAIClient;
+  /** Tool registration strategy for the Omada plugin (default 'eager'). */
+  toolRegistrationMode?: OmadaRegistrationMode;
 }
 
 export async function startStdioServer(options: StdioServerOptions): Promise<void> {

package/src/server/stream.ts

@@ -94,7 +94,12 @@ export function buildTransportSecurityOptions(config: EnvironmentConfig): Transp
  */
 export function createStreamTransport(options: StreamTransportOptions): StreamTransportState {
   const { haClient, omadaClient, aiClient, config } = options;
-  const mcpServer = createServer({ haClient, omadaClient, aiClient });
+  const mcpServer = createServer({
+    haClient,
+    omadaClient,
+    aiClient,
+    toolRegistrationMode: config.toolRegistrationMode,
+  });
 
   const enableStatefulSessions = config.stateful;
   const sessionIdGenerator = enableStatefulSessions ? () => randomUUID() : undefined;

package/src/tools/common.ts

@@ -36,6 +36,21 @@ export function setLocalFullTrust(enabled: boolean): void {
  */
 export type ToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
 
+/**
+ * Resolve the caller's permission mask from the MCP SDK auth context.
+ *
+ * L3: fail closed when the mask is absent — only the trusted-local stdio path
+ * (setLocalFullTrust) grants full permissions (0xFF) without an explicit mask.
+ * HTTP requests always carry a mask (bearer-derived, or 0xFF for loopback `none`).
+ *
+ * Exposed so tools that gate per-resource (e.g. the Omada resource-graph
+ * `omada_read`/`omada_browse`) can apply the same extraction + fail-closed
+ * semantics as `wrapToolHandler`, instead of re-reading `authInfo` ad hoc.
+ */
+export function getCallerPermissions(extra: ToolExtra): number {
+  return (extra.authInfo?.extra?.permissions as number | undefined) ?? (localFullTrust ? 0xFF : 0);
+}
+
 /**
  * Convert any value to a CallToolResult
  */
@@ -76,8 +91,7 @@ export function wrapToolHandler<T>(
     // Extract permissions from MCP SDK authInfo.extra.permissions.
     // L3: fail closed when the mask is absent — only the trusted-local stdio path
     // (setLocalFullTrust) grants full permissions without an explicit mask.
-    const userPermissions =
-      (extra.authInfo?.extra?.permissions as number | undefined) ?? (localFullTrust ? 0xFF : 0);
+    const userPermissions = getCallerPermissions(extra);
 
     // Check permissions if required
     if (requiredPermission !== undefined && !hasPermission(userPermissions, requiredPermission)) {

package/src/tools/index.ts

@@ -10,7 +10,7 @@ import { logger } from '../utils/logger.js';
 
 // Tool registration functions by domain
 import { registerHomeAssistantTools } from './homeassistant/index.js';
-import { registerOmadaTools } from './omada/index.js';
+import { registerOmadaTools, type OmadaRegistrationMode } from './omada/index.js';
 import { registerAITools } from './ai/index.js';
 
 export interface RegisterToolsOptions {
@@ -18,13 +18,15 @@ export interface RegisterToolsOptions {
   haClient?: HaClient;
   omadaClient?: OmadaClient;
   aiClient?: LocalAIClient;
+  /** Tool registration strategy for the Omada plugin (default 'eager'). */
+  toolRegistrationMode?: OmadaRegistrationMode;
 }
 
 /**
  * Register all available tools based on configured clients
  */
 export function registerAllTools(options: RegisterToolsOptions): void {
-  const { server, haClient, omadaClient, aiClient } = options;
+  const { server, haClient, omadaClient, aiClient, toolRegistrationMode } = options;
   logger.debug('Registering all tools');
 
   let totalTools = 0;
@@ -37,7 +39,7 @@ export function registerAllTools(options: RegisterToolsOptions): void {
 
   // Omada tools (if client provided)
   if (omadaClient) {
-    const omadaToolCount = registerOmadaTools(server, omadaClient);
+    const omadaToolCount = registerOmadaTools(server, omadaClient, toolRegistrationMode);
     totalTools += omadaToolCount;
   }
 

package/src/tools/omada/graph.ts

@@ -0,0 +1,162 @@
+/**
+ * Omada resource-graph tools: `omada_browse` + `omada_read`.
+ *
+ * These two tools replace dozens of per-endpoint getters when
+ * `MCP_TOOL_REGISTRATION_MODE=graph`. The model navigates a discoverable
+ * namespace (browse → read) instead of selecting from a flat list of ~25 tool
+ * schemas, which keeps the tool-schema budget small for low-context models while
+ * still exposing every read endpoint.
+ *
+ * Authorization mirrors `wrapToolHandler`:
+ *  - `omada_browse` requires QUERY to use, and additionally filters the children
+ *    it advertises by the caller's mask (so sensitive subtrees stay invisible).
+ *  - `omada_read` declares NO static tool permission; instead it enforces the
+ *    per-path permission from the manifest, so each path can require a different
+ *    bit. Unknown / container / under-privileged paths fail closed.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { OmadaClient } from '../../omadaClient/index.js';
+import { hasPermission, getPermissionNames } from '../../permissions/index.js';
+import { toToolResult, wrapToolHandler, getCallerPermissions, Permission, type ToolExtra } from '../common.js';
+import { childrenOf, getResourceNode, normalizePath, type ReadArgs, type ResourceNode } from './namespace.js';
+
+/** Compact, model-friendly metadata for a node (used in browse output). */
+function nodeSummary(node: ResourceNode): Record<string, unknown> {
+  return {
+    path: node.path,
+    kind: node.kind,
+    permission: getPermissionNames(node.permission).join(',') || 'NONE',
+    description: node.description,
+    readable: node.fetch !== undefined,
+    ...(node.estimatedSize ? { estimatedSize: node.estimatedSize } : {}),
+    ...(node.paginated ? { supportsPagination: true, defaultPageSize: node.defaultPageSize ?? 50 } : {}),
+    ...(node.params && node.params.length > 0 ? { params: node.params } : {}),
+  };
+}
+
+const browseSchema = z.object({
+  path: z
+    .string()
+    .default('/')
+    .describe('Resource path to explore (default "/"). e.g. "/", "/gateway", "/wifi", "/network".'),
+});
+
+const readSchema = z.object({
+  path: z.string().describe('Resource path discovered via omada_browse, e.g. "/gateway/wan", "/clients", "/events".'),
+  siteId: z.string().min(1).optional().describe('Site ID (optional; uses the default site if not set).'),
+  id: z.string().min(1).optional().describe('Look up a single member of a collection by id/MAC (where supported).'),
+  params: z
+    .record(z.string())
+    .optional()
+    .describe('Path parameters some resources require (see omada_browse "params"), e.g. {"gatewayMac":"AA-BB-CC-DD-EE-FF"}.'),
+  page: z.number().int().min(1).optional().describe('Page number for paginated resources (e.g. "/events").'),
+  pageSize: z.number().int().min(1).max(200).optional().describe('Page size for paginated resources (max 200).'),
+});
+
+/**
+ * Register the resource-graph tools. Returns the number of tools registered (2).
+ */
+export function registerOmadaGraphTools(server: McpServer, client: OmadaClient): number {
+  server.registerTool(
+    'omada_browse',
+    {
+      description:
+        'Discover the Omada network resource graph. Returns the children and metadata at a path (resource TYPES, not ' +
+        'instances — no MAC enumeration), so navigate from "/" downward, then call omada_read at a readable node to fetch ' +
+        'data. This replaces dozens of individual getters with one discoverable namespace.',
+      inputSchema: browseSchema.shape,
+    },
+    wrapToolHandler(
+      'omada_browse',
+      async ({ path }: z.infer<typeof browseSchema>, extra: ToolExtra): Promise<ReturnType<typeof toToolResult>> => {
+        const norm = normalizePath(path);
+        const node = getResourceNode(norm);
+        if (!node) {
+          return toToolResult(
+            { error: 'Unknown path', message: `No Omada resource at '${norm}'. Start at '/' and browse downward.` },
+            true
+          );
+        }
+        const mask = getCallerPermissions(extra);
+        const children = childrenOf(norm)
+          .filter((child) => hasPermission(mask, child.permission))
+          .map(nodeSummary);
+        return toToolResult({
+          path: norm,
+          kind: node.kind,
+          description: node.description,
+          readable: node.fetch !== undefined,
+          ...(node.params && node.params.length > 0 ? { params: node.params } : {}),
+          ...(node.paginated ? { supportsPagination: true, defaultPageSize: node.defaultPageSize ?? 50 } : {}),
+          children,
+        });
+      },
+      Permission.QUERY
+    )
+  );
+
+  server.registerTool(
+    'omada_read',
+    {
+      description:
+        'Read data from an Omada resource path discovered via omada_browse. Handles single resources (e.g. "/gateway/wan"), ' +
+        'collections (e.g. "/clients", optionally id=<MAC> for one member), and paginated logs (e.g. "/events" with ' +
+        'page/pageSize). Authorization is enforced per-path.',
+      inputSchema: readSchema.shape,
+    },
+    // No static permission: each path declares its own, enforced below (fail-closed).
+    wrapToolHandler(
+      'omada_read',
+      async (args: z.infer<typeof readSchema>, extra: ToolExtra): Promise<ReturnType<typeof toToolResult>> => {
+        const norm = normalizePath(args.path);
+        const node = getResourceNode(norm);
+        if (!node) {
+          return toToolResult(
+            { error: 'Unknown path', message: `No Omada resource at '${norm}'. Use omada_browse to discover valid paths.` },
+            true
+          );
+        }
+        if (!node.fetch) {
+          return toToolResult(
+            { error: 'Not readable', message: `'${norm}' is a container. Use omada_browse to list its children.` },
+            true
+          );
+        }
+
+        const mask = getCallerPermissions(extra);
+        if (!hasPermission(mask, node.permission)) {
+          const required = getPermissionNames(node.permission);
+          const has = getPermissionNames(mask);
+          return toToolResult(
+            { error: 'Permission denied', message: `Reading '${norm}' requires permission: ${required.join(', ')}`, required, has },
+            true
+          );
+        }
+
+        // Validate required path parameters before touching the controller.
+        const missing = (node.params ?? [])
+          .filter((p) => p.required && !args.params?.[p.name])
+          .map((p) => p.name);
+        if (missing.length > 0) {
+          return toToolResult(
+            { error: 'Missing parameters', message: `'${norm}' requires: ${missing.join(', ')}. Pass them in "params".`, missing },
+            true
+          );
+        }
+
+        const readArgs: ReadArgs = {
+          siteId: args.siteId,
+          id: args.id,
+          params: args.params,
+          page: args.page,
+          pageSize: args.pageSize,
+        };
+        return toToolResult(await node.fetch(client, readArgs));
+      }
+    )
+  );
+
+  return 2;
+}

package/src/tools/omada/index.ts

@@ -7,6 +7,7 @@ import type { OmadaClient } from '../../omadaClient/index.js';
 import { logger } from '../../utils/logger.js';
 
 import { registerBlockClientTool } from './blockClient.js';
+import { registerOmadaGraphTools } from './graph.js';
 import { registerDisableClientRateLimitTool } from './disableClientRateLimit.js';
 import { registerGetClientTool } from './getClient.js';
 import { registerGetDeviceTool } from './getDevice.js';
@@ -33,8 +34,25 @@ import { registerSetClientRateLimitTool } from './setClientRateLimit.js';
 import { registerSetClientRateLimitProfileTool } from './setClientRateLimitProfile.js';
 import { registerUnblockClientTool } from './unblockClient.js';
 
-export function registerOmadaTools(server: McpServer, client: OmadaClient): number {
-  logger.debug('Registering Omada tools');
+/**
+ * Tool registration strategy for the Omada plugin.
+ *  - `eager` (default): register every typed Omada tool (~25). Backwards-compatible.
+ *  - `graph`: register only the resource-graph reads (`omada_browse` + `omada_read`)
+ *    plus the typed write/action tools. Keeps the tool-schema budget small for
+ *    low-context models while still exposing every read endpoint via the namespace.
+ */
+export type OmadaRegistrationMode = 'eager' | 'graph';
+
+export function registerOmadaTools(
+  server: McpServer,
+  client: OmadaClient,
+  mode: OmadaRegistrationMode = 'eager'
+): number {
+  if (mode === 'graph') {
+    return registerOmadaToolsGraph(server, client);
+  }
+
+  logger.debug('Registering Omada tools', { mode });
   let toolCount = 0;
 
   // Site tools
@@ -84,6 +102,33 @@ export function registerOmadaTools(server: McpServer, client: OmadaClient): numb
   registerGetFirewallSettingTool(server, client);
   toolCount += 8;
 
-  logger.info('Omada tools registered', { toolCount });
+  logger.info('Omada tools registered', { mode, toolCount });
+  return toolCount;
+}
+
+/**
+ * Graph mode: resource-graph reads + typed writes/actions only.
+ *
+ * Reads collapse into `omada_browse` + `omada_read` (see ./graph.ts and
+ * ./namespace.ts). Writes stay as individual, explicitly permission-gated tools —
+ * they mutate real network state, so each keeps its own narrow schema and RBAC
+ * (CONTROL) rather than being funneled through a generic verb.
+ */
+function registerOmadaToolsGraph(server: McpServer, client: OmadaClient): number {
+  logger.debug('Registering Omada tools', { mode: 'graph' });
+  let toolCount = 0;
+
+  // Resource-graph reads (browse + read)
+  toolCount += registerOmadaGraphTools(server, client);
+
+  // Typed write / action tools (unchanged, individually permission-gated)
+  registerSetClientRateLimitTool(server, client);
+  registerSetClientRateLimitProfileTool(server, client);
+  registerDisableClientRateLimitTool(server, client);
+  registerBlockClientTool(server, client);
+  registerUnblockClientTool(server, client);
+  toolCount += 5;
+
+  logger.info('Omada tools registered', { mode: 'graph', toolCount });
   return toolCount;
 }