@enfyra/mcp-server 0.1.32 → 0.1.34

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

@@ -1037,6 +1037,113 @@ function planFlowSteps(steps) {
         };
     });
 }
+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';
@@ -1772,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.'),
@@ -1801,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.'),
@@ -2020,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.'),
@@ -2167,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.'),