@enfyra/mcp-server 0.1.7 → 0.1.9

package/README.md

@@ -244,6 +244,8 @@ Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate
 - files and storage
 - Enfyra admin extensions
 
+Use `discover_enfyra_workflows` when an LLM knows the goal but may not know the right Enfyra tool path. It returns progressive-disclosure workflow matches with first tools, required acknowledgements, verification tools, relevant example categories, and `avoidTools` boundaries that prevent near-correct but unsafe tool choices.
+
 Use `get_enfyra_required_knowledge` before asking an LLM to mutate metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or Enfyra extension code. It returns global rules plus acknowledgement keys that write tools verify before saving. Dynamic server code also requires the dynamic-code acknowledgement key, and extension code also requires the extension acknowledgement key.
 
 ## Runtime Safety
@@ -262,7 +264,8 @@ The MCP server includes safety guards for LLM callers:
 - Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
 - Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
 - Custom route tools reject `mainTableId` unless the route is the canonical table route.
-- Platform operation tools such as `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `choose_flow_step_tool`, fixed-type flow step tools, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
+- `discover_enfyra_workflows` maps task intent to workflow surfaces before the agent loads detailed examples or guesses between similar tools.
+- Platform operation tools such as `api_endpoint_workflow`, `extension_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `choose_flow_step_tool`, fixed-type flow step tools, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
 - Schema changes are serialized.
 - Destructive deletes return a preview before requiring `confirm=true`.
 
@@ -300,7 +303,7 @@ Do not create custom login/logout/me routes that manually set Enfyra token cooki
 
 ## Tool Summary
 
-The MCP server exposes tools for metadata discovery, required knowledge, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, `get_enfyra_api_context`, and `get_enfyra_required_knowledge`.
+The MCP server exposes tools for workflow routing, metadata discovery, required knowledge, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, `get_enfyra_api_context`, and `get_enfyra_required_knowledge`.
 
 Routes have two separate controls. `isEnabled` controls runtime registration: disabled routes return `404`. Use `enable_route` and `disable_route` for this lifecycle. `publicMethods` controls anonymous access for enabled routes; use `public_route_methods` and `private_route_methods` for that access boundary.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-instructions.js

@@ -25,13 +25,14 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Work Flow',
     '- For a quick target/base sanity check, call `get_enfyra_api_context`; do not call broad discovery just to confirm which instance this MCP is connected to.',
+    '- When the task intent is clear but the right tool path is not, call `discover_enfyra_workflows` with the intent, risk, and optional surface. Use `detail: "plan"` before writes to get firstTools, required acknowledgements, verify tools, and avoidTools.',
     '- Discover before deciding. For architecture/capability questions call `discover_enfyra_system`; for DB/pk/runtime/cache context call `discover_runtime_context`; for filters/deep/sort/relation query shape call `discover_query_capabilities`. Run broad discovery tools sequentially, not in parallel.',
     '- Inspect narrowly. Use `inspect_table`, `inspect_route`, and `inspect_feature` for the table/route/feature being changed instead of loading broad metadata.',
     '- Load examples only when needed. Use `get_enfyra_examples` by category. Before extension UI, call `get_extension_theme_contract`; call `get_theme_class_reference` for exact eapp/Nuxt UI theme classes.',
     '- For server scripts, call `discover_script_contexts` before writing or reviewing handler/hook/flow/websocket/GraphQL logic.',
     '- Before mutating metadata, schema, routes, permissions, menus, packages, cache state, dynamic code, or extension UI, call `get_enfyra_required_knowledge`, read the global rules, and pass `globalRulesAckKey` into write tools. Dynamic server code also requires `dynamicCodeAckKey`; extension code also requires `extensionAckKey`.',
     '- With non-root API tokens, call `get_permission_profile` before relying on admin helper tools or when debugging 403s. MCP admin helpers require ordinary route permissions for static admin routes such as `/admin/script/validate`, `/admin/test/run`, `/admin/flow/trigger/:id`, and `/admin/reload/*`.',
-    '- Prefer the most specific business operation tool over raw metadata CRUD: `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `add_route_methods`, `public_route_methods`, `set_table_graphql`, guard/permission/rule tools, websocket tools, flow tools, and `ensure_page_extension`/menu tools.',
+    '- Prefer the most specific business operation tool over raw metadata CRUD. `discover_enfyra_workflows` provides the current operation-tool map and negative-routing avoidTools.',
     '- Before saving standalone dynamic script or extension code, call `validate_dynamic_script` or `validate_extension_code` unless the chosen ensure/update tool already validates the code.',
     '- For existing script-backed records, use `trace_metadata_usage` then `get_script_source`; edit with `patch_script_source` or `update_script_source` so source is hash-checked and validated.',
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',

package/src/lib/platform-operation-tools.js

@@ -873,6 +873,18 @@ function sourceMatches(existingHandler, sourceCode, scriptLanguage, timeout) {
   return true;
 }
 
+function extensionMatches(existingExtension, opts, menuId) {
+  if (!existingExtension) return false;
+  if (String(existingExtension.type || '') !== String(opts.type || 'page')) return false;
+  if (String(existingExtension.code ?? '') !== String(opts.code ?? '')) return false;
+  if (opts.description !== undefined && String(existingExtension.description || '') !== String(opts.description || '')) return false;
+  if (opts.isEnabled !== undefined && Boolean(existingExtension.isEnabled) !== Boolean(opts.isEnabled)) return false;
+  if (opts.version !== undefined && String(existingExtension.version || '') !== String(opts.version)) return false;
+  if ((opts.type || 'page') === 'page' && menuId && String(refId(existingExtension.menu)) !== String(menuId)) return false;
+  if ((opts.type || 'page') !== 'page' && refId(existingExtension.menu)) return false;
+  return true;
+}
+
 function step(status, id, title, detail = {}) {
   return { id, title, status, ...detail };
 }
@@ -1183,6 +1195,189 @@ async function runApiEndpointWorkflow(apiUrl, opts) {
   };
 }
 
+async function resolveExtensionWorkflowState(apiUrl, opts) {
+  const type = opts.type || 'page';
+  if (type === 'page' && opts.menuId && (opts.menuLabel || opts.menuPath)) {
+    throw new Error('Provide menuId or menuLabel/menuPath for page extension workflow, not both.');
+  }
+  if (type !== 'page' && (opts.menuId || opts.menuLabel || opts.menuPath)) {
+    throw new Error('Menu fields are only valid for page extensions.');
+  }
+  const validation = await validateExtensionCode(apiUrl, opts.code, opts.name);
+  const existingExtension = await findRecord(apiUrl, 'enfyra_extension', { name: { _eq: opts.name } }, 'id,_id,name,type,menu.id,description,isEnabled,version,code');
+  let menu = null;
+  if (type === 'page' && opts.menuId) {
+    menu = await findRecord(apiUrl, 'enfyra_menu', { id: { _eq: opts.menuId } }, 'id,_id,label,path,type,order,isEnabled');
+    if (!menu) throw new Error(`Menu not found: ${opts.menuId}`);
+  } else if (type === 'page' && (opts.menuPath || opts.menuLabel)) {
+    const normalizedPath = opts.menuPath ? normalizeRestPath(opts.menuPath) : undefined;
+    menu = normalizedPath
+      ? await findRecord(apiUrl, 'enfyra_menu', { path: { _eq: normalizedPath } }, 'id,_id,label,path,type,order,isEnabled')
+      : await findRecord(apiUrl, 'enfyra_menu', { label: { _eq: opts.menuLabel } }, 'id,_id,label,path,type,order,isEnabled');
+  }
+
+  const menuId = opts.menuId || getId(menu);
+  const steps = [];
+  steps.push(step('completed', 'validate_extension', 'Validate extension code', { validation }));
+  if (type === 'page') {
+    if (menuId) {
+      const menuNeedsUpdate = Boolean(menu && (
+        (opts.menuLabel !== undefined && menu.label !== opts.menuLabel)
+        || (opts.menuPath !== undefined && menu.path !== normalizeRestPath(opts.menuPath))
+        || (opts.menuType !== undefined && menu.type !== opts.menuType)
+        || (opts.menuOrder !== undefined && Number(menu.order || 0) !== Number(opts.menuOrder))
+        || (opts.menuIsEnabled !== undefined && Boolean(menu.isEnabled) !== Boolean(opts.menuIsEnabled))
+      ));
+      steps.push(step(menuNeedsUpdate ? 'pending' : 'completed', 'ensure_menu', 'Ensure page menu', {
+        menuId,
+        menu: menu ? { id: getId(menu), label: menu.label, path: menu.path } : { id: menuId },
+      }));
+    } else if (opts.menuLabel) {
+      steps.push(step('pending', 'ensure_menu', 'Create page menu', {
+        reason: 'No existing menu matched; ensure_menu will create it.',
+      }));
+    } else {
+      steps.push(step('blocked', 'ensure_menu', 'Create or select page menu', {
+        reason: 'Page extensions require menuId or menuLabel. Provide menuId for an existing menu or menuLabel/menuPath to create/update one.',
+      }));
+    }
+  }
+
+  const effectiveMenuId = type === 'page' ? menuId : undefined;
+  const saveStatus = steps.some((item) => ['blocked', 'waiting'].includes(item.status))
+    ? 'waiting'
+    : extensionMatches(existingExtension, { ...opts, type }, effectiveMenuId)
+      ? 'completed'
+      : 'pending';
+  steps.push(step(saveStatus, 'save_extension', `Ensure ${type} extension`, {
+    extensionId: getId(existingExtension),
+    currentType: existingExtension?.type || null,
+    desiredType: type,
+    menuId: effectiveMenuId || null,
+    reason: saveStatus === 'waiting' ? 'Menu must exist before saving page extension.' : undefined,
+  }));
+
+  const firstRunnable = steps.find((item) => item.status === 'pending') || null;
+  const blocked = steps.find((item) => item.status === 'blocked') || null;
+  return {
+    extension: {
+      name: opts.name,
+      type,
+      id: getId(existingExtension),
+      menuId: effectiveMenuId || null,
+    },
+    validation,
+    existingExtension: existingExtension ? {
+      id: getId(existingExtension),
+      name: existingExtension.name,
+      type: existingExtension.type,
+      menuId: refId(existingExtension.menu) || null,
+    } : null,
+    menu: menu ? { id: getId(menu), label: menu.label, path: menu.path } : null,
+    steps,
+    firstRunnable,
+    blocked,
+    nextSteps: blocked
+      ? [{ tool: 'extension_workflow', input: { name: opts.name, type }, reason: blocked.reason }]
+      : firstRunnable
+        ? [{
+          tool: 'extension_workflow',
+          input: { name: opts.name, type, apply: true, stepId: firstRunnable.id },
+          stepId: firstRunnable.id,
+          requiresKnowledgeAck: 'globalRulesAckKey and extensionAckKey from get_enfyra_required_knowledge',
+        }]
+        : [],
+  };
+}
+
+async function applyExtensionWorkflowStep(apiUrl, state, opts, stepId) {
+  const selectedStep = stepId
+    ? state.steps.find((item) => item.id === stepId)
+    : state.firstRunnable;
+  if (!selectedStep) return { action: 'noop', reason: 'No runnable step remains.' };
+  if (selectedStep.status !== 'pending') {
+    throw new Error(`Step "${selectedStep.id}" is ${selectedStep.status}, not pending.`);
+  }
+
+  const type = opts.type || 'page';
+  if (selectedStep.id === 'ensure_menu') {
+    if (type !== 'page') throw new Error('ensure_menu step is only valid for page extensions.');
+    if (!opts.menuLabel && !opts.menuId) throw new Error('menuLabel or menuId is required for ensure_menu.');
+    return {
+      action: 'menu_ensured',
+      menu: await ensureMenu(apiUrl, {
+        label: opts.menuLabel || state.menu?.label || opts.name,
+        path: opts.menuPath || state.menu?.path,
+        icon: opts.menuIcon,
+        type: opts.menuType,
+        order: opts.menuOrder,
+        permission: opts.menuPermission,
+        description: opts.menuDescription,
+        isEnabled: opts.menuIsEnabled,
+        globalRulesAckKey: opts.globalRulesAckKey,
+      }),
+    };
+  }
+
+  if (selectedStep.id === 'save_extension') {
+    let menuId = opts.menuId || state.extension.menuId;
+    if (type === 'page' && !menuId) {
+      const freshState = await resolveExtensionWorkflowState(apiUrl, opts);
+      menuId = freshState.extension.menuId;
+    }
+    if (type === 'page' && !menuId) throw new Error('Page extension menu is missing. Apply ensure_menu first.');
+    return {
+      action: `${type}_extension_ensured`,
+      extension: await ensureExtension(apiUrl, {
+        name: opts.name,
+        type,
+        code: opts.code,
+        menuId,
+        description: opts.description,
+        isEnabled: opts.isEnabled,
+        version: opts.version,
+        globalRulesAckKey: opts.globalRulesAckKey,
+        extensionKnowledgeAckKey: opts.extensionKnowledgeAckKey,
+      }),
+    };
+  }
+
+  throw new Error(`Unsupported extension workflow step: ${selectedStep.id}`);
+}
+
+async function runExtensionWorkflow(apiUrl, opts) {
+  let state = await resolveExtensionWorkflowState(apiUrl, opts);
+  const operations = [];
+  if (opts.apply || opts.applyAll) {
+    assertGlobalRulesAck(opts.globalRulesAckKey);
+    assertExtensionKnowledgeAck(opts.extensionKnowledgeAckKey);
+    const maxSteps = opts.applyAll ? 5 : 1;
+    for (let i = 0; i < maxSteps; i += 1) {
+      if (state.blocked || !state.firstRunnable) break;
+      operations.push(await applyExtensionWorkflowStep(apiUrl, state, opts, opts.stepId));
+      if (!opts.applyAll) break;
+      state = await resolveExtensionWorkflowState(apiUrl, opts);
+    }
+  }
+  const latestState = operations.length ? await resolveExtensionWorkflowState(apiUrl, opts) : state;
+  return {
+    action: operations.length ? 'extension_workflow_advanced' : 'extension_workflow_planned',
+    extension: latestState.extension,
+    validation: latestState.validation,
+    menu: latestState.menu,
+    existingExtension: latestState.existingExtension,
+    steps: latestState.steps,
+    operations,
+    complete: latestState.steps.every((item) => ['completed', 'skipped'].includes(item.status)),
+    nextSteps: latestState.nextSteps,
+    guidance: [
+      'Call get_extension_theme_contract before generating or reviewing extension UI.',
+      'For menu/account-panel notifications, use counts only when the signal source already owns an exact count; otherwise use a dot/chip for new attention.',
+      'Do not fetch destination domain lists solely to decorate the shell; destination pages own domain fetching after click.',
+    ],
+  };
+}
+
 export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
   server.tool(
     'validate_dynamic_script',
@@ -1236,6 +1431,40 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     async () => jsonText(getThemeClassReference()),
   );
 
+  server.tool(
+    'extension_workflow',
+    [
+      'Step-by-step workflow for creating or updating Enfyra admin page, global, or widget extensions.',
+      'Use this when an LLM is building extension UI, menu shell notifications, account panel entries, or page/menu wiring and should follow live nextSteps instead of guessing raw enfyra_extension mutations.',
+      'With apply=false it validates code, reads live menu/extension state, and returns pending steps.',
+      'With apply=true it applies exactly the next pending step. With applyAll=true it advances all currently safe pending steps.',
+      'Call get_extension_theme_contract before generating or reviewing UI.',
+    ].join(' '),
+    {
+      name: z.string().describe('Extension unique name.'),
+      type: z.enum(['page', 'global', 'widget']).optional().default('page').describe('Extension type. Page extensions need a menu. Global extensions are for shell-wide registration.'),
+      code: z.string().describe('Vue SFC extension code.'),
+      menuId: z.union([z.string(), z.number()]).optional().describe('Existing menu id for a page extension. Provide this or menuLabel/menuPath.'),
+      menuLabel: z.string().optional().describe('Menu label to create or update for a page extension when menuId is not provided.'),
+      menuPath: z.string().optional().describe('Admin app route path for the page menu, e.g. /cloud/support.'),
+      menuIcon: z.string().optional().describe('Optional menu icon name.'),
+      menuType: z.enum(['Menu', 'Dropdown Menu']).optional().describe('Menu type. Omit to preserve an existing menu value or use the platform default for a new menu.'),
+      menuOrder: z.number().optional().describe('Menu display order. Omit to preserve an existing menu value or use the platform default for a new menu.'),
+      menuPermission: z.string().optional().describe('Optional menu permission JSON object.'),
+      menuDescription: z.string().optional().describe('Optional menu admin note.'),
+      menuIsEnabled: z.boolean().optional().describe('Enable the menu. Omit to preserve an existing menu value or use the platform default for a new menu.'),
+      description: z.string().optional().describe('Extension description.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable extension.'),
+      version: z.string().optional().default('1.0.0').describe('Extension version.'),
+      apply: z.boolean().optional().default(false).describe('false returns plan only; true applies exactly the next pending step.'),
+      applyAll: z.boolean().optional().default(false).describe('true applies all safe pending steps in order. Prefer apply=true for production changes.'),
+      stepId: z.string().optional().describe('Optional pending step id to apply. Omit to apply the next pending step.'),
+      globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when apply/applyAll mutates metadata. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
+      extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required when apply/applyAll saves extension code. Use extensionAckKey from get_enfyra_required_knowledge.'),
+    },
+    async (input) => jsonText(await runExtensionWorkflow(ENFYRA_API_URL, input)),
+  );
+
   server.tool(
     'set_table_graphql',
     'Business operation: enable or disable GraphQL for one table through enfyra_graphql, then reload GraphQL. REST route methods do not control GraphQL.',

package/src/lib/tool-routing.js

@@ -0,0 +1,582 @@
+export const WORKFLOW_SURFACES = [
+  'api-endpoint',
+  'extension',
+  'schema',
+  'record-data',
+  'dynamic-script',
+  'route-access',
+  'guards-permissions-rules',
+  'flow',
+  'websocket',
+  'graphql',
+  'package',
+  'cache',
+  'logs-debug',
+  'auth-context',
+];
+
+const ALL_DETAILS = ['summary', 'plan', 'full'];
+
+export const TOOL_WORKFLOWS = [
+  {
+    key: 'api-endpoint',
+    title: 'Custom REST endpoint with handler',
+    useWhen: [
+      'Creating or changing a custom API path with handler behavior.',
+      'Changing public/private method access on a custom endpoint.',
+      'Adding route permissions for endpoint access.',
+    ],
+    keywords: ['endpoint', 'api', 'route handler', 'handler', 'webhook', 'custom route', 'rest path'],
+    firstTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'inspect_route'],
+    inspectTools: ['inspect_route', 'get_all_routes', 'trace_metadata_usage'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['api_endpoint_workflow', 'create_api_endpoint', 'enable_route', 'public_route_methods', 'private_route_methods', 'ensure_route_access'],
+    verifyTools: ['test_rest_endpoint', 'run_admin_test'],
+    avoidTools: [
+      {
+        tool: 'create_route',
+        when: 'a handler-backed endpoint or route permission plan is needed',
+        useInstead: 'api_endpoint_workflow',
+        reason: 'The workflow validates source, reads live route/handler/access state, applies one safe step at a time, and returns nextSteps.',
+      },
+      {
+        tool: 'create_table',
+        when: 'the user asked for custom behavior at an API path',
+        useInstead: 'api_endpoint_workflow',
+        reason: 'Tables create persisted data models; custom route handlers own behavior endpoints.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey when saving handler source'],
+    exampleCategories: ['handlers-hooks', 'permissions-rls'],
+    nextStepTemplate: [
+      'Inspect the route or run api_endpoint_workflow with apply=false.',
+      'Read required knowledge before apply/applyAll.',
+      'Apply one pending step or use applyAll only when the plan is fully understood.',
+      'Verify the endpoint with test_rest_endpoint or run_admin_test.',
+    ],
+  },
+  {
+    key: 'extension',
+    title: 'Admin extension, menu, shell notification, or account panel UI',
+    useWhen: [
+      'Creating or changing Enfyra admin page/widget/global extensions.',
+      'Adding menu entries, menu notification dots/counts, account panel rows, or shell actions.',
+      'Reviewing extension UI theme/layout/component usage.',
+    ],
+    keywords: ['extension', 'menu', 'account panel', 'notification', 'chip', 'badge', 'sidebar', 'shell', 'page ui', 'widget'],
+    firstTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'inspect_feature'],
+    inspectTools: ['inspect_feature', 'trace_metadata_usage', 'get_script_source'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'get_theme_class_reference'],
+    writeTools: ['extension_workflow', 'ensure_menu', 'ensure_page_extension', 'ensure_global_extension', 'ensure_widget_extension'],
+    verifyTools: ['validate_extension_code', 'inspect_feature'],
+    avoidTools: [
+      {
+        tool: 'create_record/update_record on enfyra_extension',
+        when: 'creating or changing extension code',
+        useInstead: 'extension_workflow, ensure_page_extension, ensure_global_extension, or ensure_widget_extension',
+        reason: 'Workflow and ensure tools validate extension code and preserve extension/menu contracts before saving.',
+      },
+      {
+        tool: 'query_table on destination domain lists',
+        when: 'decorating menu/account panel notifications',
+        useInstead: 'notification summary/realtime shell signal plus destination-page fetch on click',
+        reason: 'Shell notifications should not fetch messages, tickets, orders, or jobs lists solely for a badge.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'extensionAckKey when saving extension code'],
+    exampleCategories: ['extensions'],
+    nextStepTemplate: [
+      'Call get_extension_theme_contract before writing or reviewing UI.',
+      'Inspect the existing menu/extension/global shell registration.',
+      'Use extension_workflow with apply=false when page/menu wiring or shell notification behavior needs multiple steps.',
+      'Choose count only when the source already owns an exact count; choose dot/chip for new-attention signals.',
+      'Validate extension code or use an ensure_*_extension tool that validates before saving.',
+    ],
+  },
+  {
+    key: 'schema',
+    title: 'Table, column, relation, validation, or schema metadata change',
+    useWhen: [
+      'Creating or changing tables, columns, relations, indexes, or validation metadata.',
+      'Designing relation direction or inverse relation exposure.',
+      'Changing GraphQL/table schema flags alongside metadata.',
+    ],
+    keywords: ['schema', 'table', 'column', 'relation', 'field', 'index', 'validation', 'inverse'],
+    firstTools: ['get_enfyra_required_knowledge', 'inspect_table', 'get_all_tables'],
+    inspectTools: ['inspect_table', 'get_table_metadata', 'get_all_tables'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'get_enfyra_examples'],
+    writeTools: ['create_table', 'update_table', 'delete_table', 'create_column', 'update_column', 'delete_column', 'create_relation', 'delete_relation', 'ensure_column_rule'],
+    verifyTools: ['inspect_table', 'get_table_metadata'],
+    avoidTools: [
+      {
+        tool: 'create_record/update_record on enfyra_column or enfyra_relation',
+        when: 'changing schema metadata',
+        useInstead: 'table/column/relation schema tools',
+        reason: 'Schema tools resolve table ids, preserve relation contracts, and reject physical FK names.',
+      },
+      {
+        tool: 'manual inversePropertyName',
+        when: 'there is no concrete response/UI/deep-query/aggregate need for reverse traversal',
+        useInstead: 'owning relation only',
+        reason: 'Relation design stays minimal unless the reverse field is actually used.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey'],
+    exampleCategories: ['schema-relations'],
+    nextStepTemplate: [
+      'Inspect the existing table and relations.',
+      'Decide owner relation and whether an inverse is actually needed.',
+      'Apply schema tool changes with globalRulesAckKey.',
+      'Re-inspect metadata instead of assuming the saved shape.',
+    ],
+  },
+  {
+    key: 'record-data',
+    title: 'Route-backed table data query or CRUD',
+    useWhen: [
+      'Reading or mutating normal route-backed records.',
+      'Counting records or finding one row by filter.',
+      'Testing filters, fields, deep relations, pagination, or aggregate query shape.',
+    ],
+    keywords: ['record', 'crud', 'query', 'count', 'filter', 'aggregate', 'deep', 'sort', 'pagination'],
+    firstTools: ['inspect_table', 'discover_query_capabilities'],
+    inspectTools: ['inspect_table', 'get_table_metadata', 'discover_query_capabilities'],
+    knowledgeTools: ['get_enfyra_required_knowledge for writes'],
+    writeTools: ['create_record', 'update_record', 'delete_record'],
+    verifyTools: ['find_one_record', 'query_table', 'count_records'],
+    avoidTools: [
+      {
+        tool: 'query_table without limit or all=true',
+        when: 'listing records',
+        useInstead: 'query_table with a bounded limit or all=true for intentional complete reads',
+        reason: 'List/query tools require explicit paging intent.',
+      },
+      {
+        tool: 'generic CRUD on internal/no-route system tables',
+        when: 'changing schema, sessions, columns, or other no-route internals',
+        useInstead: 'specific schema/platform tools',
+        reason: 'Generic CRUD is for route-backed tables only.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for writes', 'dynamicCodeAckKey for script-backed sourceCode writes', 'extensionAckKey for extension code writes'],
+    exampleCategories: ['queries-deep'],
+    nextStepTemplate: [
+      'Inspect table metadata and choose fields explicitly.',
+      'Use bounded pagination or all=true deliberately.',
+      'For writes, read required knowledge and use metadata-backed field names only.',
+      'Re-read with explicit fields after mutation when saved shape matters.',
+    ],
+  },
+  {
+    key: 'dynamic-script',
+    title: 'Dynamic server code: handlers, hooks, scripts, or source patches',
+    useWhen: [
+      'Writing or reviewing handler, hook, flow step, websocket, GraphQL, or bootstrap sourceCode.',
+      'Editing an existing script-backed metadata record.',
+      'Debugging macro, repository, or validation behavior.',
+    ],
+    keywords: ['sourcecode', 'script', 'hook', 'pre hook', 'post hook', 'compiledcode', 'macro', 'repos', 'bootstrap'],
+    firstTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'trace_metadata_usage'],
+    inspectTools: ['trace_metadata_usage', 'get_script_source', 'discover_script_contexts'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['patch_script_source', 'update_script_source', 'create_handler', 'create_pre_hook', 'create_post_hook', 'api_endpoint_workflow'],
+    verifyTools: ['validate_dynamic_script', 'run_admin_test', 'test_rest_endpoint', 'test_flow_step'],
+    avoidTools: [
+      {
+        tool: 'update_record with compiledCode',
+        when: 'editing dynamic scripts',
+        useInstead: 'patch_script_source or update_script_source with sourceCode',
+        reason: 'compiledCode is generated and may differ because macros expand.',
+      },
+      {
+        tool: 'throw new Error for intentional user/domain failures',
+        when: 'writing generated dynamic server code',
+        useInstead: '@THROW400-style macros or native $ctx.$throw helpers',
+        reason: 'Intentional domain errors should use the platform error contract.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey'],
+    exampleCategories: ['handlers-hooks'],
+    nextStepTemplate: [
+      'Discover script context macros for the surface.',
+      'Read existing source through trace_metadata_usage/get_script_source when patching.',
+      'Validate source before save unless the chosen write tool already validates.',
+      'Verify behavior with the route/test runner that matches the script surface.',
+    ],
+  },
+  {
+    key: 'route-access',
+    title: 'Authenticated route access and public/private method state',
+    useWhen: [
+      'Debugging 403/401 route access.',
+      'Granting role/user access to a route method.',
+      'Changing publicMethods or availableMethods.',
+    ],
+    keywords: ['permission', '403', '401', 'role', 'route access', 'public method', 'private method', 'available method'],
+    firstTools: ['get_permission_profile', 'inspect_route', 'audit_route_access'],
+    inspectTools: ['get_permission_profile', 'inspect_route', 'audit_route_access'],
+    knowledgeTools: ['get_enfyra_required_knowledge'],
+    writeTools: ['ensure_route_access', 'add_route_methods', 'replace_route_methods', 'remove_route_methods', 'public_route_methods', 'private_route_methods', 'enable_route', 'disable_route'],
+    verifyTools: ['audit_route_access', 'test_rest_endpoint'],
+    avoidTools: [
+      {
+        tool: 'raw enfyra_route_permission CRUD',
+        when: 'granting route access',
+        useInstead: 'ensure_route_access',
+        reason: 'The operation tool resolves roles/methods and merges existing method grants safely.',
+      },
+      {
+        tool: 'public_route_methods',
+        when: 'the desired behavior is authenticated user access',
+        useInstead: 'ensure_route_access',
+        reason: 'publicMethods grants anonymous access; route permissions grant authenticated access.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for writes'],
+    exampleCategories: ['permissions-rls'],
+    nextStepTemplate: [
+      'Inspect route and permission profile before changing access.',
+      'Decide anonymous publicMethods versus authenticated route permission.',
+      'Use route operation tools instead of raw permission CRUD.',
+      'Audit and test the route after the change.',
+    ],
+  },
+  {
+    key: 'guards-permissions-rules',
+    title: 'Guards, field permissions, and column validation rules',
+    useWhen: [
+      'Adding route guards, guard rules, field permissions, or column rules.',
+      'Restricting field read/write behavior.',
+      'Adding body validation rules at metadata level.',
+    ],
+    keywords: ['guard', 'field permission', 'column rule', 'validation rule', 'rule', 'rls'],
+    firstTools: ['get_enfyra_required_knowledge', 'inspect_table', 'inspect_route'],
+    inspectTools: ['inspect_table', 'inspect_route', 'discover_query_capabilities'],
+    knowledgeTools: ['get_enfyra_required_knowledge'],
+    writeTools: ['ensure_guard', 'ensure_field_permission', 'ensure_column_rule'],
+    verifyTools: ['test_rest_endpoint', 'query_table', 'run_admin_test'],
+    avoidTools: [
+      {
+        tool: 'raw create_record on guard/rule tables',
+        when: 'a dedicated ensure_* operation exists',
+        useInstead: 'ensure_guard, ensure_field_permission, or ensure_column_rule',
+        reason: 'Ensure tools resolve ids and preserve the current rule contract.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey'],
+    exampleCategories: ['permissions-rls', 'schema-relations'],
+    nextStepTemplate: [
+      'Inspect the target table/route and decide the security boundary first.',
+      'Use the specific ensure_* operation for the rule surface.',
+      'Verify with the route/query behavior the rule is meant to protect.',
+    ],
+  },
+  {
+    key: 'flow',
+    title: 'Flow, scheduled/manual flow, or flow step',
+    useWhen: [
+      'Creating or changing manual/scheduled flows.',
+      'Choosing or writing a flow step.',
+      'Testing or triggering a flow.',
+    ],
+    keywords: ['flow', 'scheduled', 'manual flow', 'flow step', 'trigger flow', 'workflow'],
+    firstTools: ['get_enfyra_required_knowledge', 'choose_flow_step_tool', 'discover_script_contexts'],
+    inspectTools: ['inspect_feature', 'query_table'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['ensure_manual_flow', 'ensure_scheduled_flow', 'ensure_query_flow_step', 'ensure_create_flow_step', 'ensure_update_flow_step', 'ensure_delete_flow_step', 'ensure_http_flow_step', 'ensure_sleep_flow_step', 'ensure_trigger_flow_step', 'ensure_log_flow_step', 'ensure_condition_flow_step', 'ensure_script_flow_step'],
+    verifyTools: ['test_flow_step', 'run_admin_test', 'trigger_flow'],
+    avoidTools: [
+      {
+        tool: 'ensure_script_flow_step',
+        when: 'a fixed query/create/update/delete/http/sleep/trigger/log step can express the operation',
+        useInstead: 'choose_flow_step_tool then the fixed-type ensure_*_flow_step',
+        reason: 'Atomic step types are easier to inspect, test, and maintain than oversized scripts.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey for script or condition source'],
+    exampleCategories: ['flows'],
+    nextStepTemplate: [
+      'Use choose_flow_step_tool before mutating when step type is unclear.',
+      'Prefer fixed-type flow step tools over script steps.',
+      'Validate/test script or condition steps before relying on the flow.',
+      'Trigger manually only after the saved steps are verified.',
+    ],
+  },
+  {
+    key: 'websocket',
+    title: 'Socket.IO gateway or websocket event',
+    useWhen: [
+      'Creating or changing websocket gateways/events.',
+      'Writing websocket handler source.',
+      'Testing websocket event logic.',
+    ],
+    keywords: ['websocket', 'socket', 'socket.io', 'gateway', 'realtime', 'room'],
+    firstTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'inspect_feature'],
+    inspectTools: ['inspect_feature', 'discover_script_contexts'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['ensure_websocket_gateway', 'ensure_websocket_event'],
+    verifyTools: ['run_admin_test'],
+    avoidTools: [
+      {
+        tool: 'raw CRUD on enfyra_websocket_event',
+        when: 'saving websocket event source',
+        useInstead: 'ensure_websocket_event',
+        reason: 'The operation tool validates script source and preserves gateway/event linkage.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey when saving event source'],
+    exampleCategories: ['websocket'],
+    nextStepTemplate: [
+      'Discover websocket script context before writing source.',
+      'Ensure gateway first, then event.',
+      'Use run_admin_test for event/connection scripts where possible.',
+    ],
+  },
+  {
+    key: 'graphql',
+    title: 'GraphQL enablement and query surface',
+    useWhen: [
+      'Enabling/disabling GraphQL for a table.',
+      'Checking GraphQL endpoint/schema behavior.',
+      'Clarifying REST route methods versus GraphQL table exposure.',
+    ],
+    keywords: ['graphql', 'gql', 'schema endpoint'],
+    firstTools: ['discover_enfyra_system', 'inspect_table'],
+    inspectTools: ['discover_enfyra_system', 'inspect_table'],
+    knowledgeTools: ['get_enfyra_required_knowledge for writes'],
+    writeTools: ['set_table_graphql', 'update_table'],
+    verifyTools: ['reload_graphql', 'discover_enfyra_system'],
+    avoidTools: [
+      {
+        tool: 'public_route_methods',
+        when: 'trying to expose GraphQL table data',
+        useInstead: 'set_table_graphql plus GraphQL auth planning',
+        reason: 'REST publicMethods do not make GraphQL table data anonymous.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for writes'],
+    exampleCategories: ['queries-deep'],
+    nextStepTemplate: [
+      'Inspect the table and GraphQL enablement state.',
+      'Use set_table_graphql for enablement changes.',
+      'Remember GraphQL table data requires Bearer auth even when REST is public.',
+    ],
+  },
+  {
+    key: 'package',
+    title: 'Runtime package install or package-backed extension/script support',
+    useWhen: [
+      'Installing npm packages for dynamic code or extension runtime use.',
+      'Checking package availability before using getPackages in extensions.',
+    ],
+    keywords: ['package', 'npm', 'install', 'dependency', 'getpackages'],
+    firstTools: ['search_npm', 'get_enfyra_required_knowledge'],
+    inspectTools: ['search_npm', 'query_table'],
+    knowledgeTools: ['get_enfyra_required_knowledge'],
+    writeTools: ['install_package'],
+    verifyTools: ['query_table'],
+    avoidTools: [
+      {
+        tool: 'raw create_record on enfyra_package',
+        when: 'installing packages',
+        useInstead: 'install_package',
+        reason: 'The package tool resolves package metadata and avoids duplicate package records.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey'],
+    exampleCategories: ['extensions', 'handlers-hooks'],
+    nextStepTemplate: [
+      'Search package metadata first.',
+      'Install with install_package and globalRulesAckKey.',
+      'Use getPackages inside extension runtime code rather than static imports.',
+    ],
+  },
+  {
+    key: 'cache',
+    title: 'Cache reload or stale metadata/runtime diagnosis',
+    useWhen: [
+      'Diagnosing stale routes, metadata, GraphQL, or full runtime cache.',
+      'Manually reloading only after natural partial reload appears stale.',
+    ],
+    keywords: ['cache', 'reload', 'stale', 'refresh metadata', 'reload routes'],
+    firstTools: ['inspect_table', 'inspect_route', 'get_enfyra_api_context'],
+    inspectTools: ['inspect_table', 'inspect_route', 'get_enfyra_api_context'],
+    knowledgeTools: ['get_enfyra_required_knowledge for manual reloads'],
+    writeTools: ['reload_metadata', 'reload_routes', 'reload_graphql', 'reload_all'],
+    verifyTools: ['inspect_table', 'inspect_route', 'discover_enfyra_system'],
+    avoidTools: [
+      {
+        tool: 'manual reload tools',
+        when: 'a successful metadata mutation already triggered natural partial reload and no stale evidence exists',
+        useInstead: 'verify behavior first with inspect/test tools',
+        reason: 'Manual reloads should be evidence-driven, not reflexive.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for manual reload tools'],
+    exampleCategories: [],
+    nextStepTemplate: [
+      'Verify stale behavior with narrow inspect/test tools.',
+      'Choose the narrowest reload surface if stale evidence exists.',
+      'Re-verify the same narrow behavior after reload.',
+    ],
+  },
+  {
+    key: 'logs-debug',
+    title: 'Logs, runtime diagnostics, and test runner debugging',
+    useWhen: [
+      'Reading app/error logs.',
+      'Searching logs for route, flow, websocket, or dynamic script failures.',
+      'Running admin tests for supported runtime surfaces.',
+    ],
+    keywords: ['log', 'debug', 'error', 'trace', 'tail', 'diagnostic', 'test runner'],
+    firstTools: ['get_log_files', 'search_logs'],
+    inspectTools: ['get_log_files', 'get_log_content', 'tail_log', 'search_logs'],
+    knowledgeTools: [],
+    writeTools: [],
+    verifyTools: ['run_admin_test', 'test_flow_step', 'test_rest_endpoint'],
+    avoidTools: [
+      {
+        tool: 'broad metadata discovery',
+        when: 'the problem is a concrete runtime error with known log text',
+        useInstead: 'search_logs or tail_log',
+        reason: 'Log tools are narrower and cheaper for runtime debugging.',
+      },
+    ],
+    requiredAck: [],
+    exampleCategories: [],
+    nextStepTemplate: [
+      'Search or tail the narrowest log first.',
+      'Use the matching test tool to reproduce once the failing surface is known.',
+      'Patch only after the failing step is identified.',
+    ],
+  },
+  {
+    key: 'auth-context',
+    title: 'MCP target, auth token, current user, and permission profile',
+    useWhen: [
+      'Confirming which Enfyra instance MCP is connected to.',
+      'Debugging API-token exchange or current MCP user permissions.',
+      'Checking whether non-root tokens can call admin helper routes.',
+    ],
+    keywords: ['auth', 'token', 'current user', 'permission profile', 'target', 'api base', '403', 'exchange'],
+    firstTools: ['get_enfyra_api_context', 'get_current_user', 'get_permission_profile'],
+    inspectTools: ['get_enfyra_api_context', 'get_current_user', 'get_permission_profile'],
+    knowledgeTools: [],
+    writeTools: ['login'],
+    verifyTools: ['get_current_user', 'get_permission_profile'],
+    avoidTools: [
+      {
+        tool: 'discover_enfyra_system',
+        when: 'only confirming the connected API base',
+        useInstead: 'get_enfyra_api_context',
+        reason: 'Target sanity checks should be cheap and should not load broad metadata.',
+      },
+    ],
+    requiredAck: [],
+    exampleCategories: ['ssr-app-auth', 'oauth-setup'],
+    nextStepTemplate: [
+      'Use get_enfyra_api_context for target sanity checks.',
+      'Use get_permission_profile before assuming admin helper route access with non-root tokens.',
+      'Use login only when an interactive credential login is explicitly needed.',
+    ],
+  },
+];
+
+function compactWorkflow(workflow) {
+  return {
+    key: workflow.key,
+    title: workflow.title,
+    useWhen: workflow.useWhen,
+  };
+}
+
+function planWorkflow(workflow) {
+  return {
+    ...compactWorkflow(workflow),
+    firstTools: workflow.firstTools,
+    inspectTools: workflow.inspectTools,
+    knowledgeTools: workflow.knowledgeTools,
+    writeTools: workflow.writeTools,
+    verifyTools: workflow.verifyTools,
+    requiredAck: workflow.requiredAck,
+    exampleCategories: workflow.exampleCategories,
+    nextSteps: workflow.nextStepTemplate,
+    avoidTools: workflow.avoidTools,
+  };
+}
+
+function fullWorkflow(workflow) {
+  return {
+    ...planWorkflow(workflow),
+    keywords: workflow.keywords,
+  };
+}
+
+function normalize(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function scoreWorkflow(workflow, { intent, surface, risk }) {
+  let score = 0;
+  const text = normalize(intent);
+  if (surface && workflow.key === surface) score += 20;
+  if (surface && workflow.key.includes(surface)) score += 8;
+  if (text) {
+    for (const keyword of workflow.keywords || []) {
+      if (text.includes(keyword)) score += 4;
+    }
+    for (const phrase of workflow.useWhen || []) {
+      const words = normalize(phrase).split(/\W+/).filter((word) => word.length > 3);
+      if (words.some((word) => text.includes(word))) score += 1;
+    }
+  }
+  if (risk === 'debug' && workflow.key === 'logs-debug') score += 6;
+  if (risk === 'write' && workflow.writeTools.length) score += 2;
+  if (risk === 'destructive' && workflow.avoidTools.some((item) => normalize(item.when).includes('delete'))) score += 2;
+  return score;
+}
+
+export function listWorkflowSurfaces() {
+  return TOOL_WORKFLOWS.map(compactWorkflow);
+}
+
+export function discoverWorkflowRoutes({
+  intent = '',
+  surface,
+  risk = 'unknown',
+  detail = 'summary',
+  limit = 5,
+} = {}) {
+  const normalizedSurface = surface ? normalize(surface) : undefined;
+  const normalizedDetail = ALL_DETAILS.includes(detail) ? detail : 'summary';
+  const normalizedRisk = normalize(risk) || 'unknown';
+  const formatter = normalizedDetail === 'full'
+    ? fullWorkflow
+    : normalizedDetail === 'plan'
+      ? planWorkflow
+      : compactWorkflow;
+  const scored = TOOL_WORKFLOWS
+    .map((workflow) => ({ workflow, score: scoreWorkflow(workflow, { intent, surface: normalizedSurface, risk: normalizedRisk }) }))
+    .filter((item) => !normalizedSurface || item.workflow.key === normalizedSurface || item.score > 0)
+    .sort((a, b) => b.score - a.score || a.workflow.key.localeCompare(b.workflow.key));
+  const selected = (scored.length ? scored : TOOL_WORKFLOWS.map((workflow) => ({ workflow, score: 0 })))
+    .slice(0, Math.max(1, Math.min(Number(limit) || 5, 10)));
+  return {
+    action: 'enfyra_workflows_discovered',
+    intent: intent || null,
+    requestedSurface: surface || null,
+    risk: normalizedRisk,
+    detail: normalizedDetail,
+    matchedWorkflowCount: scored.length,
+    workflows: selected.map((item) => ({
+      score: item.score,
+      ...formatter(item.workflow),
+    })),
+    surfaces: normalizedDetail === 'summary' ? WORKFLOW_SURFACES : undefined,
+    guidance: [
+      'Use this as progressive disclosure: pick the closest workflow, then call its firstTools instead of loading every Enfyra tool/example.',
+      'For writes, call get_enfyra_required_knowledge and pass the returned acknowledgement keys into write tools.',
+      'Treat avoidTools as negative routing boundaries; they prevent near-correct tool choices from crossing the wrong platform contract.',
+    ],
+  };
+}

package/src/mcp-server-entry.mjs

@@ -20,6 +20,7 @@ import { exchangeApiToken, refreshAccessToken, getValidToken, resetTokens, getTo
 import { fetchAPI, validateFilter, validateTableName } from './lib/fetch.js';
 import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instructions.js';
 import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
+import { WORKFLOW_SURFACES, discoverWorkflowRoutes } from './lib/tool-routing.js';
 import { registerTableTools } from './lib/table-tools.js';
 import { registerPlatformOperationTools } from './lib/platform-operation-tools.js';
 import { parseRecordData, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
@@ -860,6 +861,23 @@ server.tool(
   },
 );
 
+server.tool(
+  'discover_enfyra_workflows',
+  [
+    'Progressive-disclosure router for the Enfyra MCP tool surface.',
+    'Call this when the task intent is clear but the right Enfyra tool path is not.',
+    'Returns matched workflows, first tools, required acknowledgement keys, verification tools, and avoidTools negative-routing boundaries.',
+  ].join(' '),
+  {
+    intent: z.string().optional().describe('Plain-language task goal, e.g. "add a menu chip when support tickets arrive".'),
+    surface: z.enum(WORKFLOW_SURFACES).optional().describe('Known surface when the caller can classify the task. Omit to infer from intent.'),
+    risk: z.enum(['read', 'write', 'destructive', 'debug', 'unknown']).optional().default('unknown').describe('Highest expected operation risk.'),
+    detail: z.enum(['summary', 'plan', 'full']).optional().default('summary').describe('summary lists candidate workflows; plan adds tool sequence and avoidTools; full also includes matching keywords.'),
+    limit: z.number().int().positive().max(10).optional().default(5).describe('Maximum workflows to return.'),
+  },
+  async (input) => jsonContent(discoverWorkflowRoutes(input)),
+);
+
 server.tool(
   'discover_enfyra_system',
   [