@enfyra/mcp-server 0.1.31 → 0.1.33

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,137 @@ 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 normalizeFlowWorkflowStep(step, index) {
+    const input = typeof step === 'string' ? { intent: step } : (step || {});
+    const intent = String(input.intent || input.name || input.key || `Step ${index + 1}`);
+    const recommended = chooseFlowStepTool(input.type || intent);
+    const type = String(input.type || recommended.type || 'script');
+    const guidance = FLOW_STEP_TOOL_GUIDANCE.find((item) => item.type === type);
+    if (!guidance) {
+        throw new Error(`steps[${index}].type must be one of ${FLOW_STEP_TOOL_GUIDANCE.map((item) => item.type).join(', ')}.`);
+    }
+    const key = String(input.key || intent)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 64) || `step_${index + 1}`;
+    return {
+        index,
+        key,
+        name: input.name || intent,
+        intent,
+        type,
+        order: input.order ?? index * 10,
+        config: input.config ?? guidance.config ?? {},
+        sourceCode: input.sourceCode ?? guidance.sourceCode,
+        scriptLanguage: input.scriptLanguage || 'javascript',
+        timeout: input.timeout,
+        isEnabled: input.isEnabled ?? true,
+        chosenByIntent: !input.type,
+        recommendedTool: guidance.tool,
+    };
+}
+async function runFlowWorkflow(apiUrl, opts) {
+    const steps = parseJsonArrayArg('steps', opts.steps, []);
+    const plan = steps.map(normalizeFlowWorkflowStep);
+    const hasDynamicCode = plan.some((step) => ['script', 'condition'].includes(step.type) && step.sourceCode);
+    const triggerType = opts.triggerType || 'manual';
+    const flowInput = {
+        name: opts.name,
+        triggerType,
+        triggerConfig: triggerType === 'schedule' ? opts.triggerConfig : (opts.triggerConfig ?? {}),
+        timeout: opts.timeout,
+        maxExecutions: opts.maxExecutions,
+        isEnabled: opts.isEnabled,
+        description: opts.description,
+        globalRulesAckKey: opts.globalRulesAckKey,
+    };
+    if (!opts.apply) {
+        return {
+            action: 'flow_workflow_planned',
+            flow: {
+                name: opts.name,
+                triggerType,
+            },
+            stepCount: plan.length,
+            plan,
+            requiredAckParams: ['globalRulesAckKey', ...(hasDynamicCode ? ['knowledgeAckKey'] : [])],
+            nextSteps: [
+                'Review the plan. Prefer fixed step types; script is only for logic not covered by query/create/update/delete/http/sleep/trigger/log/condition.',
+                'Call flow_workflow again with apply=true and the required ack params to create/update the flow and steps sequentially.',
+                'Use test_flow_step for script, condition, or high-risk steps before triggering the flow.',
+            ],
+        };
+    }
+    if (!opts.name)
+        throw new Error('name is required.');
+    assertGlobalRulesAck(opts.globalRulesAckKey);
+    if (hasDynamicCode)
+        assertDynamicCodeKnowledgeAck(opts.knowledgeAckKey);
+    const flowResult = await ensureFlow(apiUrl, flowInput);
+    const flowId = flowResult.flow.id;
+    const operations = [];
+    for (const step of plan) {
+        const result = await ensureFlowStep(apiUrl, {
+            flowName: undefined,
+            flowId,
+            key: step.key,
+            type: step.type,
+            order: step.order,
+            config: step.config,
+            sourceCode: step.sourceCode,
+            scriptLanguage: step.scriptLanguage,
+            timeout: step.timeout,
+            isEnabled: step.isEnabled,
+            globalRulesAckKey: opts.globalRulesAckKey,
+            knowledgeAckKey: opts.knowledgeAckKey,
+        });
+        operations.push({
+            index: step.index,
+            key: step.key,
+            type: step.type,
+            result,
+        });
+    }
+    return {
+        action: 'flow_workflow_applied',
+        flow: flowResult.flow,
+        flowResult,
+        stepCount: plan.length,
+        plan,
+        operations,
+        sequential: true,
+        nextSteps: [
+            'Use test_flow_step for script, condition, or high-risk steps before triggering the flow.',
+            'Use trigger_flow only after saved behavior is verified.',
+        ],
+    };
+}
 function normalizeEndpointAccess(anonymousAccess, makePublic) {
     if (makePublic !== undefined)
         return makePublic ? 'public' : 'private';
@@ -1087,6 +1283,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 +1296,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 +1706,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 +1751,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.'),
@@ -1657,7 +1879,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     ].join(' '), {
         path: z.string().describe('Custom route path, e.g. /sum. Must not be a full URL.'),
         method: z.string().describe('HTTP method for the handler, e.g. GET or POST.'),
-        sourceCode: z.string().describe('Handler sourceCode. Use macros such as @QUERY, @BODY, @THROW400, @REPOS, @USER and #table_name. Do not send compiledCode. Do not use @REPOS.secure.<table>; use @REPOS.main for route main table or #table_name/@REPOS.table_name with explicit fields/auth checks.'),
+        sourceCode: z.string().describe('Handler sourceCode. Use macros such as @QUERY, @BODY, @THROW400, @REPOS, @USER and #table_name. Repository calls are async: use `const result = await #table.find(...)` and read rows from `result.data || []`. Do not send compiledCode. Do not use @REPOS.secure.<table>; use @REPOS.main for route main table or #table_name/@REPOS.table_name with explicit fields/auth checks.'),
         scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language.'),
         anonymousAccess: z.enum(['public', 'private']).optional().default('private').describe('public adds the method to publicMethods; private removes this method from publicMethods.'),
         public: z.boolean().optional().describe('Compatibility alias for anonymousAccess. true means public, false means private.'),
@@ -1686,7 +1908,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     ].join(' '), {
         path: z.string().describe('Custom route path, e.g. /sum. Must not be a full URL.'),
         method: z.string().describe('HTTP method for the handler, e.g. GET or POST.'),
-        sourceCode: z.string().describe('Handler sourceCode. Use macros such as @QUERY, @BODY, @THROW400, @REPOS, @USER and #table_name. Do not send compiledCode. Do not use @REPOS.secure.<table>; use @REPOS.main for route main table or #table_name/@REPOS.table_name with explicit fields/auth checks.'),
+        sourceCode: z.string().describe('Handler sourceCode. Use macros such as @QUERY, @BODY, @THROW400, @REPOS, @USER and #table_name. Repository calls are async: use `const result = await #table.find(...)` and read rows from `result.data || []`. Do not send compiledCode. Do not use @REPOS.secure.<table>; use @REPOS.main for route main table or #table_name/@REPOS.table_name with explicit fields/auth checks.'),
         scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language.'),
         public: z.boolean().optional().default(false).describe('When true, the method is added to publicMethods for anonymous access.'),
         description: z.string().optional().describe('Route description.'),
@@ -1905,7 +2127,78 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
             reload,
         });
     });
-    server.tool('ensure_guard', 'Business operation: create or update a request guard and optional guard rules. It resolves route/method ids and prevents pre_auth user-based rules.', {
+    server.tool('ensure_route_rate_limit', 'Business operation: create or update a route rate-limit guard through the Enfyra guard engine. Prefer this over pre-hooks or raw guard JSON for request throttling.', {
+        name: z.string().optional().describe('Optional guard name. Defaults to a stable name based on path, methods, and scope.'),
+        routeId: z.union([z.string(), z.number()]).optional().describe('Optional route id.'),
+        path: z.string().optional().describe('Route path to protect, e.g. /newsletter_signup.'),
+        methods: z.array(z.string()).default(['POST']).describe('HTTP method names to protect.'),
+        scope: z.enum(['ip', 'user', 'route']).default('ip').describe('Rate-limit key scope. Use ip for public/pre-auth routes, user for authenticated users, route for a shared route-wide limit.'),
+        maxRequests: z.number().int().positive().describe('Allowed request count per window.'),
+        perSeconds: z.number().int().positive().describe('Window length in seconds.'),
+        position: z.enum(['pre_auth', 'post_auth']).optional().describe('Optional override. Defaults to pre_auth for ip/route and post_auth for user.'),
+        priority: z.number().optional().default(0).describe('Lower runs earlier.'),
+        isEnabled: z.boolean().optional().default(true).describe('Enable the guard. Defaults true.'),
+        description: z.string().optional().describe('Admin note.'),
+        globalRulesAckKey: globalRulesAckParam(z),
+    }, async ({ name, routeId, path, methods, scope, maxRequests, perSeconds, position, priority, isEnabled, description, globalRulesAckKey }) => {
+        assertGlobalRulesAck(globalRulesAckKey);
+        if (path && routeId)
+            throw new Error('Provide path or routeId, not both.');
+        const resolvedPosition = position || (scope === 'user' ? 'post_auth' : 'pre_auth');
+        if (scope === 'user' && resolvedPosition === 'pre_auth') {
+            throw new Error('User-scoped rate limits require post_auth because user identity is unavailable before auth.');
+        }
+        const { route } = await resolveRoute(ENFYRA_API_URL, { path, routeId });
+        const { methodMap } = await getMethodContext(ENFYRA_API_URL);
+        const methodNames = uniqueMethodNames(methods?.length ? methods : ['POST']);
+        const ruleType = scope === 'user' ? 'rate_limit_by_user' : scope === 'route' ? 'rate_limit_by_route' : 'rate_limit_by_ip';
+        const guardName = name || `Rate limit ${scope} ${route.path} ${methodNames.join('_')}`;
+        const existing = await findRecord(ENFYRA_API_URL, 'enfyra_guard', { name: { _eq: guardName } }, 'id,_id,name');
+        const guardBody = {
+            name: guardName,
+            position: resolvedPosition,
+            combinator: 'and',
+            priority,
+            isGlobal: false,
+            isEnabled,
+            description: description || `Rate-limit ${methodNames.join(', ')} ${route.path} by ${scope}.`,
+            route: { id: getId(route) },
+            methods: resolveMethodRefs(methodMap, methodNames),
+        };
+        const guardOperation = await createOrPatch(ENFYRA_API_URL, 'enfyra_guard', existing, guardBody);
+        const guardId = guardOperation.id || getId(existing);
+        const existingRules = await fetchRecords(ENFYRA_API_URL, 'enfyra_guard_rule', { guard: { id: { _eq: guardId } } }, 'id,_id,isEnabled');
+        const disabledRules = [];
+        for (const rule of existingRules) {
+            disabledRules.push(await fetchAPI(ENFYRA_API_URL, `/enfyra_guard_rule/${encodeURIComponent(String(getId(rule)))}`, {
+                method: 'PATCH',
+                body: JSON.stringify({ isEnabled: false }),
+            }));
+        }
+        const rule = await fetchAPI(ENFYRA_API_URL, '/enfyra_guard_rule', {
+            method: 'POST',
+            body: JSON.stringify({
+                type: ruleType,
+                config: { maxRequests, perSeconds },
+                priority: 0,
+                isEnabled: true,
+                description: `${maxRequests} request${maxRequests === 1 ? '' : 's'} per ${perSeconds} seconds by ${scope}.`,
+                guard: { id: guardId },
+            }),
+        });
+        const reload = await reloadBestEffort(ENFYRA_API_URL, '/admin/reload/guards');
+        return jsonText({
+            action: 'route_rate_limit_ensured',
+            route: { id: getId(route), path: route.path },
+            methods: methodNames,
+            guard: { id: guardId, name: guardName, position: resolvedPosition, isEnabled },
+            rule: { type: ruleType, config: { maxRequests, perSeconds }, result: rule },
+            disabledRuleCount: disabledRules.length,
+            reload,
+            next: 'Call inspect_route({ path }) to confirm the guard is attached, then test behavior through the actual REST route if doing so will not consume a production rate-limit bucket.',
+        });
+    });
+    server.tool('ensure_guard', 'Advanced business operation: create or update a custom request guard tree and optional guard rules. For simple request throttling use ensure_route_rate_limit instead.', {
         name: z.string().describe('Guard name. Existing guard with this name is updated unless guardId is provided.'),
         guardId: z.union([z.string(), z.number()]).optional().describe('Optional existing guard id.'),
         position: z.enum(['pre_auth', 'post_auth']).optional().default('pre_auth').describe('Guard position.'),
@@ -2052,6 +2345,37 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         const reload = naturalPartialReload('Websocket event writes trigger the server partial reload contract; there is no dedicated websocket reload endpoint.');
         return jsonText({ action: 'websocket_event_ensured', gateway: { id: getId(gateway), path: gateway.path }, eventName, validation, operation, reload });
     });
+    server.tool('flow_workflow', [
+        'Workflow front door for creating or updating an Enfyra flow and its steps in one guided path.',
+        'Use apply=false first to plan step types from plain-language intents. Use apply=true only after reviewing the plan; the tool creates/updates the flow first, then steps sequentially.',
+        'Prefer this over choosing individual ensure_*_flow_step tools in guided mode.',
+    ].join(' '), {
+        name: z.string().describe('Flow name. Existing flow with this name is updated.'),
+        triggerType: z.enum(['manual', 'schedule']).optional().default('manual').describe('manual for API/admin/hook/child flow usage, schedule for cron/time-based flows.'),
+        triggerConfig: z.union([z.record(z.any()), z.string()]).optional().describe('Trigger config object or JSON string. Required for scheduled flows.'),
+        steps: z.array(z.union([
+            z.string(),
+            z.object({
+                key: z.string().optional().describe('Stable step key. Generated from intent when omitted.'),
+                name: z.string().optional().describe('Human label. Defaults from intent.'),
+                intent: z.string().optional().describe('Plain-language step intent. Used to choose a fixed step type when type is omitted.'),
+                type: z.enum(['query', 'create', 'update', 'delete', 'http', 'condition', 'sleep', 'trigger_flow', 'log', 'script']).optional().describe('Explicit step type. Omit to let the workflow choose from intent.'),
+                config: z.union([z.record(z.any()), z.string()]).optional().describe('Step config object or JSON string. For query/create/update/delete/http/sleep/trigger/log steps, prefer config over sourceCode.'),
+                sourceCode: z.string().optional().describe('Only for script or condition steps. Use fixed step types when possible.'),
+                scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript'),
+                order: z.number().optional().describe('Step order. Defaults to index * 10.'),
+                timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
+                isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+            }),
+        ])).min(1).max(30).describe('Ordered step intents/definitions. Keep one business operation per step.'),
+        timeout: z.number().int().positive().optional().describe('Flow timeout in ms.'),
+        maxExecutions: z.number().int().positive().optional().default(100).describe('Execution history cap.'),
+        isEnabled: z.boolean().optional().default(true).describe('Enable flow.'),
+        description: z.string().optional().describe('Admin note.'),
+        apply: z.boolean().optional().default(false).describe('false returns plan only; true applies flow and steps sequentially.'),
+        globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when apply=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
+        knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required when apply=true and any script/condition step has sourceCode.'),
+    }, async (input) => jsonText(await runFlowWorkflow(ENFYRA_API_URL, input)));
     server.tool('ensure_manual_flow', 'Business operation: create or update a manually triggered Enfyra flow. Use this when the flow is run by API, admin action, another flow, or hook.', {
         name: z.string().describe('Flow name. Existing flow with this name is updated.'),
         timeout: z.number().int().positive().optional().describe('Flow timeout in ms.'),
@@ -2103,6 +2427,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.'),