@enfyra/mcp-server 0.1.31 → 0.1.32

package/README.md

@@ -242,6 +242,7 @@ Without a target flag, interactive mode asks which client to configure. Non-inte
 | `ENFYRA_APP_URL` | App/admin URL used by setup | `http://localhost:3000` |
 | `ENFYRA_API_URL` | Runtime API base written into MCP client config | Generated by setup |
 | `ENFYRA_API_TOKEN` | Programmatic token from the Enfyra admin UI `/me` | Required |
+| `ENFYRA_MCP_TOOLSET` | Tool visibility mode: `guided` for curated default tools, or `full` for every low-level escape hatch | `guided` |
 
 For normal apps and demos, enter the app/admin URL such as `http://localhost:3000` or `https://demo.enfyra.io`. Treat the direct Enfyra backend host as private infrastructure unless you are debugging Enfyra core/server internals.
 
@@ -280,13 +281,13 @@ The MCP server includes safety guards for LLM callers:
 - 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.
 - `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`, `reorder_menus`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
+- Platform operation tools such as `api_endpoint_workflow`, `extension_workflow`, `search_admin_extensions`, `debug_field_exposure`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `plan_flow_steps`, fixed-type flow step tools, `ensure_menu`, `reorder_menus`, `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`.
 
 ## Query Notes
 
-Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata. Every list/query call must pass either `limit` for a bounded page or `all: true` for a complete list. When a caller needs every matching row, pass `all: true` to `query_table`, `get_all_routes`, or `get_all_tables`; the tool should not choose an arbitrary page size like 30 or 50.
+Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata. Every broad list/query call must pass either `limit` for a bounded page or `all: true` for a complete list. Locator searches on `get_all_routes` and `get_all_tables` may omit `limit` when `search` is provided; they return a small bounded lookup window. When a caller needs every matching row, pass `all: true` to `query_table`, `get_all_routes`, or `get_all_tables`; the tool should not choose an arbitrary page size like 30 or 50.
 
 ## Enfyra URL Pattern
 
@@ -318,7 +319,7 @@ Do not create custom login/logout/me routes that manually set Enfyra token cooki
 
 ## Tool Summary
 
-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`.
+By default, the MCP server starts with `ENFYRA_MCP_TOOLSET=guided`, a curated tool surface optimized for weaker LLMs and one-shot success. It exposes workflow routing, focused discovery, runtime zone search, schema tools, query/CRUD envelopes, row-scope pre-hooks, focused extension patching, operation-level route/permission/extension/flow/websocket tools, validation, and narrow verification tools. Set `ENFYRA_MCP_TOOLSET=full` only for expert debugging or compatibility work that needs low-level escape hatches such as raw route construction, cache reloads, method metadata, broad metadata reads, or raw log file reads.
 
 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/dist/lib/mcp-instructions.d.ts

@@ -3,4 +3,8 @@ export declare function buildGraphqlUrls(apiBaseUrl: any): {
     graphqlHttpUrl: string;
     graphqlSchemaUrl: string;
 };
-export declare function buildMcpServerInstructions(apiBaseUrl: any): string;
+type McpInstructionOptions = {
+    toolsetSummary?: string | null;
+};
+export declare function buildMcpServerInstructions(apiBaseUrl: any, options?: McpInstructionOptions): string;
+export {};

package/dist/lib/mcp-instructions.js

@@ -6,37 +6,39 @@ export function buildGraphqlUrls(apiBaseUrl) {
         graphqlSchemaUrl: `${base}/graphql-schema`,
     };
 }
-export function buildMcpServerInstructions(apiBaseUrl) {
+export function buildMcpServerInstructions(apiBaseUrl, options = {}) {
     const base = String(apiBaseUrl || '').replace(/\/$/, '');
     const { graphqlHttpUrl, graphqlSchemaUrl } = buildGraphqlUrls(apiBaseUrl);
+    const toolsetSummary = options?.toolsetSummary || null;
     return [
         '## Enfyra MCP',
         '',
         `API base for this session: \`${base}\`.`,
         `GraphQL endpoints: \`${graphqlHttpUrl}\` and \`${graphqlSchemaUrl}\`.`,
+        ...(toolsetSummary ? ['', toolsetSummary] : []),
         '',
         '### 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 and follow `primaryPath` in order; do not choose from the flat tool list first.',
         '- 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`, `inspect_feature`, and DB-backed runtime zone tools for the table/route/feature/surface being changed instead of loading broad metadata.',
-        '- For DB-backed artifacts, use `search_runtime_zone`: search first, then inspect with `nextInspect.input`.',
+        '- For admin UI/menu/extensions use `search_admin_extensions`; for other DB-backed artifacts use `search_runtime_zone`: search then inspect with `nextInspect.input`.',
         '- 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/code/extensions, call `get_enfyra_required_knowledge`; pass `globalRulesAckKey`, plus `dynamicCodeAckKey` or `extensionAckKey` where required.',
+        '- Before mutating metadata/schema/routes/permissions/menus/packages/cache/code/extensions, call `get_enfyra_required_knowledge` and pass `globalRulesAckKey` plus required code/extension ack keys.',
         '- With non-root API tokens, call `get_permission_profile` before admin helper tools or 403 debugging.',
         '- 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 code, call `validate_dynamic_script` or `/admin/script/validate` unless the write tool validates. For extensions, prefer atomic save tools; use `validate_extension_code` only for validation-only checks.',
+        '- Before saving standalone dynamic script code, call `validate_dynamic_script` or `/admin/script/validate` unless the write tool validates. For extensions, prefer atomic save tools.',
         '- Extension SFCs must use auto-injected components directly in templates, such as `<UButton>`, and must not call `resolveComponent()` for Nuxt UI/eApp components.',
         '- 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.',
         '',
         '### Core Contracts',
         '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. If rows are columnar, read values by matching `columns[index]` to `rows[n][index]`; do not guess row keys.',
-        '- `query_table`, `get_all_routes`, and `get_all_tables` need `limit` or `all:true`; do not invent arbitrary limits.',
+        '- `query_table` needs `limit` or `all:true`; do not invent arbitrary limits. `get_all_routes`/`get_all_tables` omit limit with `search`.',
         '- Read tools are minimal by default. Pass explicit `fields`; inspect metadata before guessing. Field exclusion mode: `fields=-compiledCode`; `fields=id,-compiledCode` means all readable fields except `compiledCode`.',
-        '- Mutations return ids/status by default. Re-read with explicit `fields` only when saved shape matters.',
-        '- Mutation tools are plural-only. Pass native JSON arrays, using one-item arrays for single writes; tools preflight arrays and run sequentially.',
+        '- Mutations return ids/status. Re-read with explicit `fields` only when saved shape matters.',
+        '- Mutation tools are plural-only: pass native JSON arrays, using one-item arrays for single writes.',
         '- For schema creation, do not declare `id`, `_id`, `createdAt`, or `updatedAt`; Enfyra manages them. `create_tables` strips them and reports `skippedAutoColumns`; `create_columns` rejects them.',
         '- Relation-based indexes/uniques must reference relation `propertyName` values that exist on the same table. Put the owning relations in the same `create_tables` item for one-pass creation, or add relation-based uniques later with `update_tables` after relations exist.',
         '- Fields in `uniques`, including composite groups like `["event","attendee"]`, must not also appear in `indexes`; uniques already index them. `create_tables` preflights the whole batch.',
@@ -55,9 +57,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
         '- Relation filters use relation propertyName values, not physical FK-shaped names: use `{ incident: { id: { _eq: id } } }`, not `{ incidentId: { _eq: id } }`.',
         '- `query_table` accepts native object `filter`, `deep`, and `aggregate`; always pass `limit` or `all:true`. Deep keys are relation names; MCP auto-adds missing top-level deep fields. Deep options: `fields`, `filter`, `sort`, `limit`, `page`, `deep`; never `_fields`.',
         '- For counts, prefer `count_records` or `meta=filterCount/totalCount`. Do not guess `_sum`/`_count`; call `discover_query_capabilities` before `aggregate`.',
-        '- If REST exposes `isPublished=false` fields via fields/deep, treat it as a core issue; confirm with `test_rest_endpoint` and do not hide it in frontend code.',
+        '- If REST exposes `isPublished=false` fields via fields/deep, use `debug_field_exposure`; treat confirmed leaks as core issues, not UI/hook fixes.',
         '- Script source is `sourceCode`; `compiledCode` is generated and may differ textually because macros expand. Do not warn about source/compiled mismatch unless validation or runtime behavior proves the compiled artifact is stale.',
-        '- For user/domain errors use `@THROW`, not `throw new Error(...)`. Numeric helpers are raw HTTP messages, e.g. `@THROW404("Project not found")`; details must be an object/array, e.g. `@THROW404("Project not found", { id })`. Use `@THROW.notFound(...)`/`@THROW.duplicate(...)` only for Enfyra-formatted semantic messages.',
+        '- For user/domain errors use `@THROW`, not `throw new Error(...)`. Numeric helpers are raw HTTP messages; details must be an object/array. Semantic helpers: `notFound(resource, identifier)`, `duplicate(resource, field, value)`.',
         '- Destructive operations are preview-first. Do not pass `confirm=true` until the user explicitly approves.',
         '- Treat permission and security as the first design step for any route, handler, flow, extension, or data surface.',
         '- Admin UI `usePermissions()` and backend RoleGuard use route permissions; use `audit_route_access`/`ensure_route_access`.',

package/dist/lib/mcp-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-instructions.js","sourceRoot":"","sources":["../../src/lib/mcp-instructions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,UAAU;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,UAAU;QACjC,gBAAgB,EAAE,GAAG,IAAI,iBAAiB;KAC3C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,UAAU;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAE1E,OAAO;QACL,eAAe;QACf,EAAE;QACF,gCAAgC,IAAI,KAAK;QACzC,wBAAwB,cAAc,YAAY,gBAAgB,KAAK;QACvE,EAAE;QACF,eAAe;QACf,6JAA6J;QAC7J,kQAAkQ;QAClQ,2SAA2S;QAC3S,oMAAoM;QACpM,4GAA4G;QAC5G,2MAA2M;QAC3M,8HAA8H;QAC9H,0NAA0N;QAC1N,uGAAuG;QACvG,iLAAiL;QACjL,sPAAsP;QACtP,oKAAoK;QACpK,+LAA+L;QAC/L,wJAAwJ;QACxJ,EAAE;QACF,oBAAoB;QACpB,4KAA4K;QAC5K,qHAAqH;QACrH,yNAAyN;QACzN,yGAAyG;QACzG,kJAAkJ;QAClJ,mMAAmM;QACnM,+QAA+Q;QAC/Q,2LAA2L;QAC3L,oLAAoL;QACpL,yJAAyJ;QACzJ,6NAA6N;QAC7N,+LAA+L;QAC/L,qKAAqK;QACrK,2NAA2N;QAC3N,4HAA4H;QAC5H,yMAAyM;QACzM,mMAAmM;QACnM,8QAA8Q;QAC9Q,iRAAiR;QACjR,2KAA2K;QAC3K,gKAAgK;QAChK,4QAA4Q;QAC5Q,6JAA6J;QAC7J,gKAAgK;QAChK,sOAAsO;QACtO,kUAAkU;QAClU,4GAA4G;QAC5G,oHAAoH;QACpH,4HAA4H;QAC5H,yKAAyK;QACzK,yMAAyM;QACzM,EAAE;QACF,6BAA6B;QAC7B,4NAA4N;QAC5N,uMAAuM;QACvM,sMAAsM;QACtM,EAAE;QACF,4BAA4B;QAC5B,qQAAqQ;QACrQ,wKAAwK;QACxK,qKAAqK;QACrK,+PAA+P;QAC/P,EAAE;QACF,yBAAyB;QACzB,kNAAkN;QAClN,oNAAoN;QACpN,6VAA6V;QAC7V,EAAE;QACF,uIAAuI;KACxI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"mcp-instructions.js","sourceRoot":"","sources":["../../src/lib/mcp-instructions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,UAAU;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,UAAU;QACjC,gBAAgB,EAAE,GAAG,IAAI,iBAAiB;KAC3C,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,0BAA0B,CAAC,UAAU,EAAE,UAAiC,EAAE;IACxF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1E,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IAEvD,OAAO;QACL,eAAe;QACf,EAAE;QACF,gCAAgC,IAAI,KAAK;QACzC,wBAAwB,cAAc,YAAY,gBAAgB,KAAK;QACvE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,EAAE;QACF,eAAe;QACf,6JAA6J;QAC7J,kQAAkQ;QAClQ,2SAA2S;QAC3S,oMAAoM;QACpM,sKAAsK;QACtK,2MAA2M;QAC3M,8HAA8H;QAC9H,qMAAqM;QACrM,uGAAuG;QACvG,iLAAiL;QACjL,uLAAuL;QACvL,oKAAoK;QACpK,+LAA+L;QAC/L,wJAAwJ;QACxJ,EAAE;QACF,oBAAoB;QACpB,4KAA4K;QAC5K,0IAA0I;QAC1I,yNAAyN;QACzN,8FAA8F;QAC9F,qGAAqG;QACrG,mMAAmM;QACnM,+QAA+Q;QAC/Q,2LAA2L;QAC3L,oLAAoL;QACpL,yJAAyJ;QACzJ,6NAA6N;QAC7N,+LAA+L;QAC/L,qKAAqK;QACrK,2NAA2N;QAC3N,4HAA4H;QAC5H,yMAAyM;QACzM,mMAAmM;QACnM,8QAA8Q;QAC9Q,iRAAiR;QACjR,2KAA2K;QAC3K,gKAAgK;QAChK,4QAA4Q;QAC5Q,6JAA6J;QAC7J,oJAAoJ;QACpJ,sOAAsO;QACtO,qOAAqO;QACrO,4GAA4G;QAC5G,oHAAoH;QACpH,4HAA4H;QAC5H,yKAAyK;QACzK,yMAAyM;QACzM,EAAE;QACF,6BAA6B;QAC7B,4NAA4N;QAC5N,uMAAuM;QACvM,sMAAsM;QACtM,EAAE;QACF,4BAA4B;QAC5B,qQAAqQ;QACrQ,wKAAwK;QACxK,qKAAqK;QACrK,+PAA+P;QAC/P,EAAE;QACF,yBAAyB;QACzB,kNAAkN;QAClN,oNAAoN;QACpN,6VAA6V;QAC7V,EAAE;QACF,uIAAuI;KACxI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { createHash } from 'node:crypto';
 import { fetchAPI } from './fetch.js';
 import { validatePortableScriptSource, validateScriptSourceIfPresent } from './mutation-guards.js';
 import { assertDynamicCodeKnowledgeAck, assertDynamicCodeKnowledgeAckIf, assertExtensionKnowledgeAck, assertGlobalRulesAck, dynamicCodeKnowledgeAckParam, extensionKnowledgeAckParam, globalRulesAckParam, } from './required-knowledge.js';
@@ -646,6 +647,70 @@ async function updateExtensionCode(apiUrl, { id, name, code, description, isEnab
         validation,
     };
 }
+function sha256Text(value) {
+    return createHash('sha256').update(String(value ?? '')).digest('hex');
+}
+async function patchExtensionCode(apiUrl, { id, name, search, replace, expectedSha256, apply, description, isEnabled, version, globalRulesAckKey, extensionKnowledgeAckKey, }) {
+    assertGlobalRulesAck(globalRulesAckKey);
+    assertExtensionKnowledgeAck(extensionKnowledgeAckKey);
+    if (!id && !name)
+        throw new Error('Provide id or name to patch an existing extension.');
+    if (!search)
+        throw new Error('search must be a non-empty exact code fragment.');
+    const existing = id
+        ? await findRecord(apiUrl, 'enfyra_extension', { id: { _eq: id } }, 'id,_id,name,type,menu.id,code')
+        : await findRecord(apiUrl, 'enfyra_extension', { name: { _eq: name } }, 'id,_id,name,type,menu.id,code');
+    if (!existing)
+        throw new Error(`Extension not found: ${id || name}`);
+    const extensionId = getId(existing);
+    const currentCode = String(existing.code ?? '');
+    const currentSha256 = sha256Text(currentCode);
+    if (expectedSha256 && expectedSha256 !== currentSha256) {
+        throw new Error(`Extension code hash mismatch. Expected ${expectedSha256}, got ${currentSha256}. Re-read the extension before patching.`);
+    }
+    const occurrences = currentCode.split(search).length - 1;
+    if (occurrences !== 1) {
+        throw new Error(`Expected search fragment to occur exactly once; found ${occurrences}. Use a more specific fragment or update_extension_code for a full replacement.`);
+    }
+    const nextCode = currentCode.replace(search, replace);
+    const nextSha256 = sha256Text(nextCode);
+    const preview = {
+        action: apply ? 'extension_code_patch_applied' : 'extension_code_patch_previewed',
+        id: extensionId,
+        name: existing.name || name || null,
+        type: existing.type || null,
+        currentSha256,
+        nextSha256,
+        currentLength: currentCode.length,
+        nextLength: nextCode.length,
+        occurrences,
+        apply: Boolean(apply),
+    };
+    if (!apply) {
+        return {
+            ...preview,
+            nextStep: {
+                tool: 'patch_extension_code',
+                input: { id: extensionId, expectedSha256: currentSha256, search, replace, apply: true },
+            },
+        };
+    }
+    const result = await updateExtensionCode(apiUrl, {
+        id: extensionId,
+        name: undefined,
+        code: nextCode,
+        description,
+        isEnabled,
+        version,
+        globalRulesAckKey,
+        extensionKnowledgeAckKey,
+    });
+    return {
+        ...preview,
+        result,
+        validation: result.validation,
+    };
+}
 function normalizeMetadataTables(metadata) {
     const tables = metadata?.data?.tables || metadata?.tables || metadata?.data || [];
     return Array.isArray(tables) ? tables : Object.values(tables || {});
@@ -948,6 +1013,30 @@ function chooseFlowStepTool(intent) {
         return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'query');
     return FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === 'script');
 }
+function planFlowSteps(steps) {
+    const items = Array.isArray(steps) ? steps : [];
+    return items.map((step, index) => {
+        const intent = typeof step === 'string' ? step : step?.intent;
+        const key = typeof step === 'object' && step?.key ? String(step.key) : `step_${index + 1}`;
+        const recommendation = chooseFlowStepTool(intent);
+        return {
+            order: index + 1,
+            key,
+            intent,
+            tool: recommendation.tool,
+            type: recommendation.type,
+            suggestedInput: {
+                key,
+                name: typeof step === 'object' && step?.name ? step.name : key.replace(/_/g, ' '),
+                order: index + 1,
+                ...(recommendation.config ? { config: recommendation.config } : {}),
+                ...(recommendation.sourceCode ? { sourceCode: recommendation.sourceCode } : {}),
+                ...(recommendation.condition ? { condition: recommendation.condition } : {}),
+            },
+            reason: recommendation.when,
+        };
+    });
+}
 function normalizeEndpointAccess(anonymousAccess, makePublic) {
     if (makePublic !== undefined)
         return makePublic ? 'public' : 'private';
@@ -1087,6 +1176,12 @@ async function resolveApiEndpointWorkflowState(apiUrl, opts) {
     }
     const firstRunnable = steps.find((item) => item.status === 'pending') || null;
     const blocked = steps.find((item) => item.status === 'blocked') || null;
+    const pendingAckParams = firstRunnable
+        ? [
+            'globalRulesAckKey',
+            ...(firstRunnable.id === 'save_handler' ? ['knowledgeAckKey'] : []),
+        ]
+        : [];
     const nextSteps = blocked
         ? [{ tool: 'api_endpoint_workflow', input: { path: normalizedPath, method: methodName, overwrite: true }, reason: blocked.reason }]
         : firstRunnable
@@ -1094,7 +1189,10 @@ async function resolveApiEndpointWorkflowState(apiUrl, opts) {
                     tool: 'api_endpoint_workflow',
                     input: { path: normalizedPath, method: methodName, apply: true },
                     stepId: firstRunnable.id,
-                    requiresKnowledgeAck: firstRunnable.id === 'save_handler' ? 'dynamicCodeAckKey from get_enfyra_required_knowledge' : undefined,
+                    requiredAckParams: pendingAckParams,
+                    requiresKnowledgeAck: pendingAckParams.length
+                        ? `Pass ${pendingAckParams.join(' and ')} from get_enfyra_required_knowledge when applying this step.`
+                        : undefined,
                 }]
             : [];
     return {
@@ -1501,6 +1599,23 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         globalRulesAckKey: globalRulesAckParam(z),
         extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     }, async (input) => jsonText(await updateExtensionCode(ENFYRA_API_URL, input)));
+    server.tool('patch_extension_code', [
+        'Focused operation: patch an existing Enfyra admin extension code by exact search/replace.',
+        'Use this for small UI fixes instead of rewriting the whole Vue SFC. It hash-checks the current code, validates with /enfyra_extension/preview, and saves only when apply=true.',
+        'Default apply=false returns a preview and nextStep input.',
+    ].join(' '), {
+        id: z.union([z.string(), z.number()]).optional().describe('Existing extension id. Provide id or name.'),
+        name: z.string().optional().describe('Existing extension unique name. Provide id or name.'),
+        search: z.string().describe('Exact code fragment that must occur once.'),
+        replace: z.string().describe('Replacement code fragment.'),
+        expectedSha256: z.string().optional().describe('Optional SHA-256 of current extension code from a prior inspect/read. Rejects stale patches.'),
+        apply: z.boolean().optional().default(false).describe('Preview by default. Set true to validate and save.'),
+        description: z.string().optional().describe('Optional replacement extension description. Omit to preserve.'),
+        isEnabled: z.boolean().optional().describe('Optional enabled state. Omit to preserve.'),
+        version: z.string().optional().describe('Optional extension version. Omit to preserve.'),
+        globalRulesAckKey: globalRulesAckParam(z),
+        extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
+    }, async (input) => jsonText(await patchExtensionCode(ENFYRA_API_URL, input)));
     server.tool('get_extension_theme_contract', 'Return the concise Enfyra admin extension UI/theme/security contract. Call before writing or reviewing extension UI.', {}, async () => jsonText(getExtensionThemeContract()));
     server.tool('get_theme_class_reference', [
         'Return the authoritative Enfyra theme & color class reference: class -> CSS variable -> Nuxt UI semantic color -> intent.',
@@ -1529,8 +1644,8 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         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.'),
+        apply: z.boolean().optional().default(false).describe('false returns plan only; true applies exactly the next pending step. When true, always pass globalRulesAckKey; also pass knowledgeAckKey when saving handler sourceCode.'),
+        applyAll: z.boolean().optional().default(false).describe('true applies all safe pending steps in order. Prefer apply=true for production changes. When true, always pass globalRulesAckKey and pass knowledgeAckKey if handler sourceCode may be saved.'),
         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.'),
@@ -2103,6 +2218,29 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
             ],
         });
     });
+    server.tool('plan_flow_steps', 'Dry-run helper: choose the ordered Enfyra flow step tools for a whole flow plan before mutating flow metadata.', {
+        steps: z.array(z.union([
+            z.string(),
+            z.object({
+                key: z.string().optional().describe('Stable step key. Generated when omitted.'),
+                name: z.string().optional().describe('Human label. Defaults from key.'),
+                intent: z.string().describe('Plain-language description of this step.'),
+            }),
+        ])).min(1).max(30).describe('Ordered step intents. Use this before ensure_*_flow_step calls when a flow has multiple steps.'),
+    }, async ({ steps }) => {
+        const plan = planFlowSteps(steps);
+        return jsonText({
+            action: 'flow_steps_planned',
+            stepCount: plan.length,
+            plan,
+            nextSteps: [
+                'Create or update the flow with ensure_manual_flow or ensure_scheduled_flow first.',
+                'Call each planned ensure_*_flow_step in order, adding flowName or flowId plus table/query/config details.',
+                'Use ensure_script_flow_step only for steps where the plan chose script because fixed step types are insufficient.',
+                'Use test_flow_step for script/condition/high-risk steps before triggering the full flow.',
+            ],
+        });
+    });
     server.tool('ensure_script_flow_step', 'Business operation: create or update one script flow step. Use this for JavaScript/TypeScript flow logic instead of choosing type=script manually.', {
         flowName: z.string().optional().describe('Flow name. Use flowName or flowId.'),
         flowId: z.union([z.string(), z.number()]).optional().describe('Flow id. Use flowName or flowId.'),