@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

package/dist/mcp/handlers/workflow/modify.js

@@ -0,0 +1,456 @@
+/**
+ * Workflow Modify Handler
+ *
+ * Handles brownfield workflow modifications via STRUCTURED OPERATIONS.
+ *
+ * CRITICAL: This handler does NOT parse natural language.
+ * The Agent (LLM) builds structured operations and passes them here.
+ *
+ * See: src/mcp/AGENTS.md for anti-patterns to avoid.
+ */
+import { detectWorkflowIssues, suggestWorkflowFixes } from "../../../sdk/knowledge.js";
+import { sanitizeWorkflowForDeploy } from "./utils.js";
+import { ensureSchemaRegistry } from "../../../sdk/workflow-validator.js";
+// ─────────────────────────────────────────────────────────────────────────
+// Action Building Helpers (use ActionRegistry for metadata)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Get action metadata from registry.
+ * Falls back to defaults if action not found.
+ */
+function getActionMetadata(actionType, registry) {
+    // Try to get from registry first
+    if (registry?.isLoaded()) {
+        const action = registry.getAction(actionType);
+        if (action) {
+            return {
+                namespaces: ["actions", "emainternal"], // Standard namespace
+                version: action.version,
+                apiName: actionType,
+            };
+        }
+    }
+    // Fallback defaults (registry should have these, but just in case)
+    return {
+        namespaces: ["actions", "emainternal"],
+        version: "v0",
+        apiName: actionType,
+    };
+}
+/**
+ * Build an input binding for a workflow action.
+ */
+function buildInputBinding(config) {
+    switch (config.type) {
+        case "action_output":
+            return {
+                actionOutput: {
+                    actionName: config.actionName,
+                    output: config.output,
+                },
+                autoDetectedBinding: false,
+            };
+        case "inline_string":
+            return {
+                inline: { wellKnown: { stringValue: config.value } },
+                autoDetectedBinding: false,
+            };
+        case "inline_number":
+            return {
+                inline: { number: config.value },
+                autoDetectedBinding: false,
+            };
+        case "llm_inferred":
+        default:
+            return { llmInferred: {} };
+    }
+}
+/**
+ * Build a complete workflow action structure from InsertNodeConfig.
+ */
+function buildWorkflowAction(config, registry) {
+    const nodeName = config.node_name || `${config.action_type}_${Date.now()}`;
+    const metadata = getActionMetadata(config.action_type, registry);
+    const action = {
+        name: nodeName,
+        action: {
+            name: {
+                namespaces: metadata.namespaces,
+                name: metadata.apiName,
+            },
+            version: metadata.version,
+        },
+        inputs: {},
+        displaySettings: {
+            displayName: config.display_name,
+            description: config.description || "",
+            coordinates: { x: 1200, y: 400 },
+        },
+        typeArguments: {},
+        tools: [],
+        disableHumanInteraction: false,
+    };
+    // Build inputs from config
+    if (config.inputs) {
+        const inputs = {};
+        for (const [inputName, binding] of Object.entries(config.inputs)) {
+            inputs[inputName] = buildInputBinding(binding);
+        }
+        action.inputs = inputs;
+    }
+    // Build runIf condition if provided
+    if (config.runIf) {
+        const operatorMap = { eq: 1, neq: 2 };
+        action.runIf = {
+            lhs: {
+                actionOutput: {
+                    actionName: config.runIf.sourceAction,
+                    output: config.runIf.sourceOutput,
+                },
+                autoDetectedBinding: false,
+            },
+            operator: operatorMap[config.runIf.operator] || 1,
+            rhs: {
+                inline: { enumValue: config.runIf.value },
+                autoDetectedBinding: false,
+            },
+        };
+    }
+    return action;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Operation Executors
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Execute an insert operation.
+ */
+function executeInsert(actions, op, registry, result) {
+    const config = op.insert;
+    if (!config) {
+        result.changesApplied.push("Insert failed: no configuration provided");
+        return;
+    }
+    if (!config.action_type || !config.display_name) {
+        result.changesApplied.push("Insert failed: action_type and display_name required");
+        return;
+    }
+    // Build the new action
+    const newAction = buildWorkflowAction(config, registry);
+    const newNodeName = String(newAction.name);
+    // Add to actions array
+    actions.push(newAction);
+    result.nodesAdded.push(newNodeName);
+    result.changesApplied.push(`Inserted node "${newNodeName}" (${config.display_name})`);
+    // Handle insert_before: modify downstream node
+    if (config.insert_before) {
+        const targetNode = actions.find(a => String(a.name || "").toLowerCase() === config.insert_before.toLowerCase());
+        if (!targetNode) {
+            result.changesApplied.push(`Warning: target node "${config.insert_before}" not found for downstream modification`);
+            return;
+        }
+        // Option 1: Add runIf to downstream node
+        if (config.add_runif_to_downstream && config.new_node_output) {
+            const operatorMap = { eq: 1, neq: 2 };
+            targetNode.runIf = {
+                lhs: {
+                    actionOutput: {
+                        actionName: newNodeName,
+                        output: config.new_node_output,
+                    },
+                    autoDetectedBinding: false,
+                },
+                operator: operatorMap["eq"],
+                rhs: {
+                    inline: { enumValue: "HITL Success" },
+                    autoDetectedBinding: false,
+                },
+            };
+            result.nodesModified.push(String(targetNode.name));
+            result.changesApplied.push(`Added runIf to ${targetNode.name}: waits for ${newNodeName}.${config.new_node_output}`);
+        }
+    }
+}
+/**
+ * Execute a remove operation.
+ */
+function executeRemove(actions, op, result) {
+    const removeConfig = op.remove;
+    if (!removeConfig?.nodes?.length) {
+        result.changesApplied.push("Remove failed: no nodes specified");
+        return;
+    }
+    for (const nodeName of removeConfig.nodes) {
+        const index = actions.findIndex(a => String(a.name || "") === nodeName);
+        if (index >= 0) {
+            actions.splice(index, 1);
+            result.nodesRemoved.push(nodeName);
+            result.changesApplied.push(`Removed node: ${nodeName}`);
+        }
+        else {
+            result.changesApplied.push(`Warning: node "${nodeName}" not found`);
+        }
+    }
+}
+/**
+ * Execute a rewire operation.
+ */
+function executeRewire(actions, op, result) {
+    const rewireConfig = op.rewire;
+    if (!rewireConfig) {
+        result.changesApplied.push("Rewire failed: no configuration provided");
+        return;
+    }
+    const { target_node, target_input, source_node, source_output } = rewireConfig;
+    // Find target node
+    const targetAction = actions.find(a => String(a.name || "").toLowerCase() === target_node.toLowerCase());
+    if (!targetAction) {
+        result.changesApplied.push(`Rewire failed: target node "${target_node}" not found`);
+        return;
+    }
+    // Update the input binding
+    const inputs = (targetAction.inputs || {});
+    inputs[target_input] = {
+        actionOutput: {
+            actionName: source_node,
+            output: source_output,
+        },
+        autoDetectedBinding: false,
+    };
+    targetAction.inputs = inputs;
+    result.nodesModified.push(target_node);
+    result.connectionsChanged.push(`${source_node}.${source_output} → ${target_node}.${target_input}`);
+    result.changesApplied.push(`Rewired ${target_node}.${target_input} to use ${source_node}.${source_output}`);
+}
+/**
+ * Execute a config update operation.
+ */
+function executeConfigUpdate(workflow, op, result) {
+    const configUpdates = op.config;
+    if (!configUpdates) {
+        result.changesApplied.push("Config update failed: no configuration provided");
+        return;
+    }
+    // Config updates are typically applied to proto_config, not workflow_def
+    // Store them for the caller to apply
+    result.changesApplied.push(`Config updates prepared: ${Object.keys(configUpdates).join(", ")}`);
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Main Operation Applier
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Apply structured modification operations to a workflow.
+ *
+ * IMPORTANT: This function executes STRUCTURED operations.
+ * It does NOT parse natural language - that's the Agent's job.
+ */
+function applyWorkflowModifications(existingWorkflow, operations, registry) {
+    // Deep copy workflow
+    const workflow = JSON.parse(JSON.stringify(existingWorkflow));
+    const actions = (workflow.actions || []);
+    const result = {
+        workflow,
+        changesApplied: [],
+        nodesAdded: [],
+        nodesRemoved: [],
+        nodesModified: [],
+        connectionsChanged: [],
+    };
+    for (const op of operations) {
+        switch (op.type) {
+            case "insert":
+                executeInsert(actions, op, registry, result);
+                break;
+            case "remove":
+                executeRemove(actions, op, result);
+                break;
+            case "rewire":
+                executeRewire(actions, op, result);
+                break;
+            case "update_config":
+                executeConfigUpdate(workflow, op, result);
+                break;
+            case "consolidate":
+                // Consolidation (merging multiple nodes into one) is a multi-step operation
+                // that requires the Agent to use multiple operations instead:
+                // 1. Add the new consolidated node (insert)
+                // 2. Rewire connections to use the new node (rewire)
+                // 3. Remove the old nodes (remove)
+                // Mark as not executed - Agent should break this down
+                result.changesApplied.push("SKIPPED: consolidate not supported as a single operation. " +
+                    "Use insert + rewire + remove operations instead.");
+                break;
+            default:
+                result.changesApplied.push(`Unknown operation type: ${op.type}`);
+        }
+    }
+    workflow.actions = actions;
+    result.workflow = workflow;
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Main Handler
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Handle workflow modify/extend mode.
+ *
+ * This handler accepts STRUCTURED OPERATIONS from the Agent.
+ * It does NOT parse natural language input.
+ *
+ * @param args.persona_id - The persona to modify
+ * @param args.operations - Array of structured ModificationOperation
+ * @param args.preview - If true, return preview without deploying
+ */
+export async function handleWorkflowModify(args, client) {
+    const personaId = args.persona_id || args.id;
+    if (!personaId) {
+        return {
+            error: "persona_id required",
+            hint: "Specify the persona to modify: persona_id='<id>'",
+        };
+    }
+    // Get operations from args
+    const operations = args.operations;
+    const preview = Boolean(args.preview);
+    // If no structured operations provided, return guidance
+    if (!operations || operations.length === 0) {
+        // Fetch persona for context
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona "${personaId}" not found` };
+        }
+        const workflow = persona.workflow_def;
+        if (!workflow) {
+            return { error: "Persona has no workflow_def" };
+        }
+        const actions = (workflow.actions || []);
+        // Run analysis to give Agent context
+        const issues = detectWorkflowIssues(workflow);
+        const suggestions = suggestWorkflowFixes(issues);
+        // Load schema registry for action catalog
+        const schemaRegistry = await ensureSchemaRegistry(client);
+        const availableActions = schemaRegistry.isLoaded()
+            ? schemaRegistry.getAllActions().map(a => ({ name: a.name, category: a.category, description: a.description }))
+            : [];
+        return {
+            message: "No operations provided. Returning workflow context for Agent to build operations.",
+            persona_id: personaId,
+            persona_name: persona.name,
+            // Current workflow state
+            current_nodes: actions.map(a => ({
+                name: a.name,
+                display_name: a.displaySettings?.displayName,
+                action_type: a.action?.name?.name,
+            })),
+            // Analysis
+            issues: issues.map(i => ({ severity: i.severity, type: i.type, node: i.node, reason: i.reason })),
+            suggestions,
+            // Available actions from registry
+            available_actions: availableActions.slice(0, 20), // Top 20 for context
+            // Guidance for Agent
+            _tip: "Build ModificationOperation[] and pass as 'operations' parameter",
+            _next_step: "Use the current_nodes and available_actions to build structured operations",
+            // Example operation structures
+            example_operations: {
+                insert_hitl: {
+                    type: "insert",
+                    insert: {
+                        action_type: "hitl",
+                        display_name: "Approval Required",
+                        insert_before: "target_node_name",
+                        add_runif_to_downstream: true,
+                        new_node_output: "hitl_status_HITL Success",
+                    },
+                },
+                remove_nodes: {
+                    type: "remove",
+                    remove: { nodes: ["node_to_remove"] },
+                },
+                rewire: {
+                    type: "rewire",
+                    rewire: {
+                        target_node: "downstream_node",
+                        target_input: "query",
+                        source_node: "upstream_node",
+                        source_output: "response",
+                    },
+                },
+            },
+        };
+    }
+    // Fetch persona
+    const persona = await client.getPersonaById(personaId);
+    if (!persona) {
+        return { error: `Persona "${personaId}" not found` };
+    }
+    const workflow = persona.workflow_def;
+    if (!workflow) {
+        return { error: "Persona has no workflow_def to modify" };
+    }
+    // Load schema registry for action metadata
+    const schemaRegistry = await ensureSchemaRegistry(client);
+    // Apply the structured operations
+    const result = applyWorkflowModifications(workflow, operations, schemaRegistry);
+    // Sanitize before deploy
+    const sanitized = sanitizeWorkflowForDeploy(result.workflow);
+    // Run validation
+    const postIssues = detectWorkflowIssues(sanitized);
+    const errors = postIssues.filter(i => i.severity === "critical");
+    if (preview) {
+        return {
+            preview: true,
+            persona_id: personaId,
+            persona_name: persona.name,
+            // What would change
+            changes_applied: result.changesApplied,
+            nodes_added: result.nodesAdded,
+            nodes_removed: result.nodesRemoved,
+            nodes_modified: result.nodesModified,
+            connections_changed: result.connectionsChanged,
+            // Validation
+            validation_errors: errors.map(e => e.reason || e.type),
+            validation_warnings: postIssues.filter(i => i.severity === "warning").map(w => w.reason || w.type),
+            // The modified workflow
+            modified_workflow: sanitized,
+            _tip: errors.length > 0
+                ? "Fix validation errors before deploying"
+                : "Preview looks good. Call without preview=true to deploy",
+        };
+    }
+    // Deploy if validation passes
+    if (errors.length > 0) {
+        return {
+            error: "Validation failed - cannot deploy",
+            validation_errors: errors.map(e => e.reason || e.type),
+            changes_attempted: result.changesApplied,
+            _tip: "Fix validation errors and try again",
+        };
+    }
+    // Deploy the workflow
+    try {
+        await client.updateAiEmployee({
+            persona_id: personaId,
+            workflow: sanitized,
+        });
+        return {
+            success: true,
+            persona_id: personaId,
+            persona_name: persona.name,
+            changes_applied: result.changesApplied,
+            nodes_added: result.nodesAdded,
+            nodes_removed: result.nodesRemoved,
+            nodes_modified: result.nodesModified,
+            connections_changed: result.connectionsChanged,
+            _tip: "Workflow updated successfully",
+        };
+    }
+    catch (error) {
+        return {
+            error: `Deploy failed: ${error instanceof Error ? error.message : String(error)}`,
+            changes_attempted: result.changesApplied,
+        };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────
+export { applyWorkflowModifications, buildWorkflowAction, buildInputBinding };

package/dist/mcp/handlers/workflow/optimize.js

@@ -0,0 +1,136 @@
+/**
+ * Workflow Optimize Handler
+ *
+ * Detects and fixes workflow issues.
+ */
+import { detectWorkflowIssues, suggestWorkflowFixes } from "../../../sdk/knowledge.js";
+/**
+ * Apply simple workflow fixes for auto_fixable issues
+ * Handles orphan removal with cascading dependency cleanup
+ */
+function applySimpleFixes(workflow, issues) {
+    // Deep clone to avoid mutating original
+    const fixed = JSON.parse(JSON.stringify(workflow));
+    // Get nodes array from workflow (handle different structures)
+    const getNodes = (w) => {
+        if (Array.isArray(w.nodes))
+            return w.nodes;
+        const wd = w.workflow_def;
+        if (wd && Array.isArray(wd.nodes))
+            return wd.nodes;
+        return undefined;
+    };
+    const nodes = getNodes(fixed);
+    if (!nodes)
+        return fixed;
+    // Collect all orphan node IDs to remove
+    const nodesToRemove = new Set();
+    for (const issue of issues) {
+        if (issue.type === "orphan" && issue.auto_fixable && issue.node) {
+            nodesToRemove.add(issue.node);
+        }
+    }
+    if (nodesToRemove.size === 0)
+        return fixed;
+    // Step 1: Remove orphan nodes
+    const filteredNodes = nodes.filter(n => {
+        const nodeId = n.id;
+        return nodeId && !nodesToRemove.has(nodeId);
+    });
+    // Step 2: Clean up dangling references in remaining nodes
+    for (const node of filteredNodes) {
+        const incomingEdges = node.incoming_edges;
+        if (incomingEdges && Array.isArray(incomingEdges)) {
+            // Filter out edges that reference removed nodes
+            node.incoming_edges = incomingEdges.filter(edge => {
+                const sourceNodeId = edge.source_node_id;
+                return sourceNodeId && !nodesToRemove.has(sourceNodeId);
+            });
+        }
+        // Also clean up inputBindings if they exist (different workflow format)
+        const inputBindings = node.inputBindings;
+        if (inputBindings && Array.isArray(inputBindings)) {
+            node.inputBindings = inputBindings.filter(binding => {
+                const actionOutput = binding.actionOutput;
+                const actionName = actionOutput?.actionName;
+                return !actionName || !nodesToRemove.has(actionName);
+            });
+        }
+    }
+    // Update nodes in the workflow
+    if (Array.isArray(fixed.nodes)) {
+        fixed.nodes = filteredNodes;
+    }
+    else {
+        const wd = fixed.workflow_def;
+        if (wd) {
+            wd.nodes = filteredNodes;
+        }
+    }
+    return fixed;
+}
+/**
+ * Handle workflow optimize mode
+ */
+export async function handleWorkflowOptimize(args, client) {
+    const personaId = args.persona_id;
+    const preview = args.preview !== false;
+    if (!personaId) {
+        return { error: "persona_id required for optimize mode" };
+    }
+    const persona = await client.getPersonaById(personaId);
+    if (!persona) {
+        return { error: `Persona not found: ${personaId}` };
+    }
+    const existingWorkflow = persona.workflow_def;
+    if (!existingWorkflow) {
+        return {
+            error: `Persona "${persona.name}" has no workflow to optimize`,
+            hint: "Use mode='generate' to create a workflow first",
+        };
+    }
+    // Analyze and detect issues
+    const issues = detectWorkflowIssues(existingWorkflow);
+    const fixes = suggestWorkflowFixes(issues);
+    if (issues.length === 0) {
+        return {
+            mode: "optimize",
+            status: "✅ No issues found",
+            persona_id: personaId,
+            persona_name: persona.name,
+            workflow_healthy: true,
+        };
+    }
+    // Apply fixes
+    const fixedWorkflow = applySimpleFixes(existingWorkflow, issues);
+    const result = {
+        mode: "optimize",
+        status: preview ? "preview" : "deployed",
+        persona_id: personaId,
+        persona_name: persona.name,
+        issues_found: issues.length,
+        issues: issues.map(i => ({
+            type: i.type,
+            severity: i.severity,
+            reason: i.reason,
+        })),
+        suggested_fixes: fixes,
+        fixed_workflow: fixedWorkflow,
+    };
+    // If preview=false, deploy the fixed workflow
+    if (!preview) {
+        await client.updateAiEmployee({
+            persona_id: personaId,
+            workflow: fixedWorkflow,
+            proto_config: args.proto_config || persona.proto_config,
+        });
+        result.deployed = true;
+    }
+    else {
+        result.next_steps = [
+            "Review the suggested fixes and fixed_workflow",
+            `Deploy with: workflow(mode="optimize", persona_id="${personaId}", preview=false)`,
+        ];
+    }
+    return result;
+}

package/dist/mcp/handlers/workflow/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for workflow handlers
+ */
+export {};

package/dist/mcp/handlers/workflow/utils.js

@@ -0,0 +1,30 @@
+/**
+ * Shared utilities for workflow handlers
+ */
+/**
+ * Sanitize workflow for deployment
+ * Removes internal-only fields, validates structure
+ */
+export function sanitizeWorkflowForDeploy(workflow) {
+    const sanitized = { ...workflow };
+    // Remove internal fields that shouldn't be sent to API
+    delete sanitized._internal;
+    delete sanitized._metadata;
+    delete sanitized._debug;
+    // Ensure actions array exists
+    if (!sanitized.actions) {
+        sanitized.actions = [];
+    }
+    // Validate and clean actions
+    const actions = sanitized.actions;
+    sanitized.actions = actions.filter(a => {
+        // Must have name
+        if (!a.name || typeof a.name !== "string")
+            return false;
+        // Must have id
+        if (!a.id && !a.name)
+            return false;
+        return true;
+    });
+    return sanitized;
+}