@ema.co/mcp-toolkit 2026.1.26 → 2026.1.27-10

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

@@ -8,9 +8,9 @@
  *
  * 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";
+import { hasKnowledgeSearchNodes } from "./deploy.js";
 // ─────────────────────────────────────────────────────────────────────────
 // Action Building Helpers (use ActionRegistry for metadata)
 // ─────────────────────────────────────────────────────────────────────────
@@ -312,6 +312,8 @@ export async function handleWorkflowModify(args, client) {
     const operations = args.operations;
     const preview = Boolean(args.preview);
     // If no structured operations provided, return guidance
+    // NOTE: This handler does NOT parse natural language - Agent must build operations
+    const userInput = args.input;
     if (!operations || operations.length === 0) {
         // Fetch persona for context
         const persona = await client.getPersonaById(personaId);
@@ -323,32 +325,38 @@ export async function handleWorkflowModify(args, client) {
             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.",
+            message: userInput
+                ? `You provided input="${userInput}". This handler requires STRUCTURED operations, not natural language. Build operations from the context below.`
+                : "No operations provided. Returning workflow context for Agent to build operations.",
             persona_id: personaId,
             persona_name: persona.name,
-            // Current workflow state
+            // If user provided input, remind them to convert to operations
+            ...(userInput && {
+                _warning: "IMPORTANT: The 'input' parameter is for providing context to the Agent, not for direct execution. The Agent must convert this into structured 'operations'.",
+                user_intent: userInput,
+            }),
+            // Current workflow state (DATA for Agent)
             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",
+            _next_steps: [
+                userInput
+                    ? `1. Interpret the user intent: "${userInput}"`
+                    : "1. Review current_nodes and available_actions above",
+                "2. Build ModificationOperation[] based on your analysis",
+                "3. Call again with operations=[{type:'insert'|'remove'|'rewire', ...}]",
+            ],
             // Example operation structures
             example_operations: {
                 insert_hitl: {
@@ -392,9 +400,6 @@ export async function handleWorkflowModify(args, client) {
     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,
@@ -406,30 +411,68 @@ export async function handleWorkflowModify(args, client) {
             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
+            // The modified workflow (LLM should analyze with ema://rules/*)
             modified_workflow: sanitized,
-            _tip: errors.length > 0
-                ? "Fix validation errors before deploying"
-                : "Preview looks good. Call without preview=true to deploy",
+            _tip: "Preview complete. Use ema://rules/anti-patterns to check for issues. Call without preview=true to deploy.",
         };
     }
-    // Deploy if validation passes
-    if (errors.length > 0) {
+    // VALIDATION: Check search nodes vs data sources consistency
+    // Same validation as deploy.ts to prevent deploying workflows that won't use uploaded documents
+    const hasSearchNodes = hasKnowledgeSearchNodes(sanitized);
+    let dataSourceStats;
+    try {
+        dataSourceStats = await client.getDataSourceAggregates(personaId);
+    }
+    catch {
+        // If we can't check stats, continue but log
+        console.error(`[modify] Could not verify data sources for ${personaId}`);
+    }
+    // VALIDATION: If persona has indexed data sources but workflow has NO search nodes → BLOCK
+    if (!hasSearchNodes && dataSourceStats && dataSourceStats.success > 0) {
         return {
-            error: "Validation failed - cannot deploy",
-            validation_errors: errors.map(e => e.reason || e.type),
+            error: "DEPLOYMENT BLOCKED: Persona has indexed knowledge files but workflow has no search nodes. The uploaded documents will NEVER be used.",
+            validation_failed: "data_sources_require_search_nodes",
+            current_state: {
+                search_nodes_detected: false,
+                data_sources_total: dataSourceStats.total,
+                data_sources_indexed: dataSourceStats.success,
+            },
+            changes_attempted: result.changesApplied,
+            _fix: [
+                "Your workflow needs a search node to query the uploaded documents.",
+                "Add a search/v2 node to your operations:",
+                "operations=[{type:'insert', insert:{action_type:'search/v2', display_name:'Knowledge Search'}}]",
+            ],
+        };
+    }
+    // VALIDATION: If workflow has search nodes but no indexed data sources → BLOCK
+    if (hasSearchNodes && dataSourceStats && dataSourceStats.success === 0) {
+        return {
+            error: "DEPLOYMENT BLOCKED: Workflow contains search nodes but no data sources have been indexed.",
+            validation_failed: "search_nodes_require_indexed_data",
+            current_state: {
+                search_nodes_detected: true,
+                data_sources_total: dataSourceStats.total,
+                data_sources_indexed: 0,
+            },
             changes_attempted: result.changesApplied,
-            _tip: "Fix validation errors and try again",
+            _fix: [
+                "Upload and index documents first:",
+                "1. persona(id='...', data={method:'upload', path:'/path/to/doc'})",
+                "2. persona(id='...', data={method:'stats'}) → wait for success > 0",
+                "3. Then retry the workflow modification",
+            ],
         };
     }
     // Deploy the workflow
+    // CRITICAL: Must include proto_config alongside workflow for changes to persist
+    // Always use the FULL existing proto_config from the persona
+    const existingProtoConfig = (persona.proto_config ?? {});
     try {
         await client.updateAiEmployee({
             persona_id: personaId,
             workflow: sanitized,
+            proto_config: existingProtoConfig,
         });
         return {
             success: true,

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

@@ -1,80 +1,22 @@
 /**
  * Workflow Optimize Handler
  *
- * Detects and fixes workflow issues.
+ * DEPRECATED: This handler returned pre-computed fixes which violates
+ * the "MCP = data, LLM = logic" principle.
+ *
+ * The LLM should:
+ * 1. Get workflow with workflow(mode="get")
+ * 2. Fetch rules from ema://rules/anti-patterns
+ * 3. Apply rules and propose fixes
+ * 4. Deploy via workflow(mode="deploy")
  */
-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
+ *
+ * NOW DEPRECATED - Returns guidance for LLM to do the analysis.
  */
 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" };
     }
@@ -89,48 +31,20 @@ export async function handleWorkflowOptimize(args, client) {
             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 = {
+    // Return the workflow and guidance for LLM to do the analysis
+    return {
         mode: "optimize",
-        status: preview ? "preview" : "deployed",
+        status: "DEPRECATED - Use LLM analysis instead",
         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,
+        // Return the workflow for LLM to analyze
+        workflow_def: existingWorkflow,
+        _next_steps: [
+            "1. Use workflow(mode='get') to get workflow data",
+            "2. Fetch ema://rules/anti-patterns",
+            "3. Apply rules to find issues (LLM does this, not MCP)",
+            "4. Modify workflow based on analysis",
+            "5. Deploy via workflow(mode='deploy', workflow_def={...})",
+        ],
     };
-    // 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/utils.js

@@ -1,30 +1,6 @@
 /**
  * Shared utilities for workflow handlers
  */
-/**
- * Get the type/category of an action node
- */
-export function getActionType(action) {
-    const name = action.name;
-    if (!name)
-        return "unknown";
-    // Categorize by action name patterns
-    if (name.includes("hitl") || name.includes("human"))
-        return "hitl";
-    if (name.includes("email") || name.includes("send"))
-        return "communication";
-    if (name.includes("search") || name.includes("retrieve"))
-        return "retrieval";
-    if (name.includes("classify") || name.includes("categorize"))
-        return "classification";
-    if (name.includes("generate") || name.includes("compose"))
-        return "generation";
-    if (name.includes("output") || name === "WORKFLOW_OUTPUT")
-        return "output";
-    if (name.includes("input") || name === "WORKFLOW_INPUT")
-        return "input";
-    return "processing";
-}
 /**
  * Sanitize workflow for deployment
  * Removes internal-only fields, validates structure
@@ -52,81 +28,3 @@ export function sanitizeWorkflowForDeploy(workflow) {
     });
     return sanitized;
 }
-/**
- * Check if a node has a path to the output
- */
-export function checkNodeHasPath(nodeId, connections, outputNodeId, visited = new Set()) {
-    if (nodeId === outputNodeId)
-        return true;
-    if (visited.has(nodeId))
-        return false;
-    visited.add(nodeId);
-    const outgoing = connections.filter(c => c.from === nodeId);
-    for (const conn of outgoing) {
-        if (checkNodeHasPath(conn.to, connections, outputNodeId, visited)) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Find orphan nodes (nodes with no path to output)
- */
-export function findOrphanNodes(workflow) {
-    const actions = workflow.actions;
-    if (!actions || actions.length === 0)
-        return [];
-    // Find output node
-    const outputNode = actions.find(a => a.name?.includes("OUTPUT") ||
-        a.id?.includes("OUTPUT"));
-    if (!outputNode) {
-        // No output node - can't determine orphans
-        return [];
-    }
-    const outputId = (outputNode.id ?? outputNode.name);
-    // Build connection list
-    const connections = [];
-    for (const action of actions) {
-        const inputs = action.inputs;
-        if (inputs) {
-            const actionId = (action.id ?? action.name);
-            for (const [_key, value] of Object.entries(inputs)) {
-                if (typeof value === "string" && value.includes(".")) {
-                    const sourceAction = value.split(".")[0];
-                    connections.push({ from: sourceAction, to: actionId });
-                }
-            }
-        }
-    }
-    // Find orphans
-    const orphans = [];
-    for (const action of actions) {
-        const actionId = (action.id ?? action.name);
-        const actionName = action.name;
-        if (actionId === outputId)
-            continue; // Skip output node
-        if (!checkNodeHasPath(actionId, connections, outputId)) {
-            orphans.push({
-                id: actionId,
-                name: actionName,
-                reason: "No path to output node",
-            });
-        }
-    }
-    return orphans;
-}
-/**
- * Extract enum type name from a value
- */
-export function extractEnumTypeName(value) {
-    if (typeof value === "object" && value !== null) {
-        const obj = value;
-        if (typeof obj.name === "string")
-            return obj.name;
-        if (typeof obj.type === "string")
-            return obj.type;
-    }
-    if (typeof value === "string")
-        return value;
-    return undefined;
-}

package/dist/mcp/handlers-consolidated.js

@@ -28,37 +28,8 @@ import { handleWorkflow as handleWorkflowExtracted } from "./handlers/workflow/i
 // ─────────────────────────────────────────────────────────────────────────────
 // isValidWidget and sanitizeWidgets imported from ../sdk/proto-config.js
 // validateWidgetsForApi imported from handlers/utils.ts
-// ─────────────────────────────────────────────────────────────────────────────
-// Deprecation tracking - helps users migrate to new param names
-// ─────────────────────────────────────────────────────────────────────────────
-const DEPRECATED_PARAMS = {
-    identifier: { newName: "id", removeVersion: "2.0.0" },
-    clone_from: { newName: "from", removeVersion: "2.0.0" },
-    template_id: { newName: "from", removeVersion: "2.0.0" },
-    clone_data: { newName: "include_data", removeVersion: "2.0.0" },
-};
-/**
- * Check for deprecated params and collect warnings.
- * Returns array of warning messages for deprecated params that were used.
- */
-function checkDeprecatedParams(args) {
-    const warnings = [];
-    for (const [oldName, { newName, removeVersion }] of Object.entries(DEPRECATED_PARAMS)) {
-        if (args[oldName] !== undefined) {
-            warnings.push(`'${oldName}' is deprecated, use '${newName}' instead (will be removed in v${removeVersion})`);
-        }
-    }
-    return warnings;
-}
-/**
- * Add deprecation warnings to response if any deprecated params were used.
- */
-function addDeprecationWarnings(result, warnings) {
-    if (warnings.length > 0) {
-        return { ...result, _deprecation_warnings: warnings };
-    }
-    return result;
-}
+// Deprecation tracking - single source of truth
+import { checkDeprecatedParams, addDeprecationWarnings } from "./handlers/deprecation.js";
 // Template utilities imported from handlers/utils.ts:
 // - normalizeTriggerType
 // - getTemplates
@@ -229,8 +200,8 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
             return {
                 error: "Explicit method required",
                 message: "You provided a persona id/name. What operation would you like to perform?",
-                valid_methods: ["get", "update", "delete", "analyze", "sanitize", "snapshot", "history", "restore", "compare"],
-                hint: "Specify method='get' to fetch, method='update' to modify",
+                valid_methods: ["get", "update", "delete", "sanitize", "snapshot", "history", "restore"],
+                hint: "LLM does analysis/comparison. Use method='get' to fetch data, then reason about it.",
                 example: `persona(method="get", id="${idOrName}")`,
             };
         }
@@ -316,16 +287,22 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
                 return { error: `Failed to get schema: ${error instanceof Error ? error.message : String(error)}` };
             }
         }
-        // Compare, clone, create, analyze - all handled by extracted handlers
-        case "compare":
+        // Clone and create - handled by extracted handlers
         case "clone":
-        case "create":
-        case "analyze": {
+        case "create": {
             // These modes have been extracted to handlers/persona/*.ts
             // - create.ts: handleCreate (~410 lines)
-            // - analyze.ts: handleAnalyze (~195 lines)
             return { error: `Mode "${effectiveMode}" should be handled by extracted handler` };
         }
+        // Analyze and compare - LLM does this, not MCP
+        case "analyze":
+        case "compare": {
+            return {
+                error: `Method "${effectiveMode}" removed - LLM does analysis/comparison`,
+                hint: "Use method='get' to fetch persona data, then do your own analysis/comparison.",
+                example: `persona(method="get", id="...", include_workflow=true)`,
+            };
+        }
         // ─────────────── Version Management Modes ───────────────
         // Extracted to handlers/persona/version.ts
         case "snapshot":