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

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/prompts.js

@@ -28,12 +28,12 @@ const PROMPTS = {
                 },
                 {
                     name: "context",
-                    description: "Context type: 'greenfield' (new workflow), 'brownfield' (extend existing), 'optimize' (improve existing)",
+                    description: "Context type: 'greenfield' (new workflow), 'brownfield' (extend existing)",
                     required: false,
                 },
                 {
                     name: "persona_id",
-                    description: "Existing persona ID if brownfield/optimize context",
+                    description: "Existing persona ID if brownfield context",
                     required: false,
                 },
             ],
@@ -53,10 +53,12 @@ ${args.persona_id ? `**Existing Persona**: ${args.persona_id}` : ""}
 
 ### Step 1: Parse the Request
 Identify what the user is asking for:
-- **Action Type**: Create new / Extend existing / Optimize / Analyze
+- **Action Type**: Create new / Extend existing
 - **Scope**: Single intent / Multi-intent / Full workflow
 - **Specificity**: Vague / Partially specified / Detailed
 
+Note: For analysis/optimization, use \`workflow(mode="get")\` then analyze with \`ema://rules/*\` resources.
+
 ### Step 2: Check for Required Information
 
 #### For ALL requests, verify:
@@ -92,13 +94,6 @@ For external side-effect actions (send_email, create_ticket, update_record):
 | **Data Dependencies** | ✓/✗ | What existing data to use? |
 | **Impact Assessment** | ✓/✗ | What might break? |
 
-#### For OPTIMIZE:
-| Dimension | Status | Missing Info |
-|-----------|--------|--------------|
-| **Problem Areas** | ✓/✗ | What's not working? |
-| **Performance Goals** | ✓/✗ | Speed, accuracy, cost? |
-| **Constraints** | ✓/✗ | What can't change? |
-
 ### Step 3: Identify Ambiguities
 
 Look for:
@@ -159,7 +154,7 @@ Based on analysis, output ONE of:
   "confidence": "high|medium",
   "summary": "Brief summary of understood requirements",
   "inferred_defaults": ["List any assumptions made"],
-  "next_action": "workflow(mode='generate'|'extend'|'optimize', ...)"
+  "next_action": "workflow(mode='get'|'deploy', ...)"
 }
 \`\`\`
 
@@ -1253,7 +1248,8 @@ ${args.type === "voice" ? `
 The generated proto_config includes voice settings:
 - welcomeMessage: Generated greeting
 - identityAndPurpose: Generated from description
-- takeActionInstructions, hangupInstructions: Sensible defaults
+- takeActionInstructions: Auto-generated from workflow tools (if tools specified)
+- hangupInstructions: Sensible defaults
 
 These are set automatically but can be customized via proto_config override.
 ` : ""}`,
@@ -1660,11 +1656,12 @@ Verify:
 - [ ] All new nodes properly linked
 - [ ] Existing functionality preserved
 
-### Step 4.2: Preview Changes
-\`workflow(persona_id="${args.persona_id}", mode="optimize", preview=true)\`
+### Step 4.2: Validate with Rules
+Fetch \`ema://rules/anti-patterns\` and verify no issues.
 
 ### Step 4.3: Deploy
-\`workflow(persona_id="${args.persona_id}", mode="deploy", workflow_def=<extended_workflow>)\`
+\`workflow(persona_id="${args.persona_id}", mode="deploy", workflow_def=<extended_workflow>, preview=true)\`
+Then without preview to commit.
 
 ## Extension Patterns
 

package/dist/mcp/resources.js

@@ -32,6 +32,7 @@ const __dirname = dirname(__filename);
 // Import knowledge catalogs for dynamic resources
 import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG, ALL_DEPRECATED_ACTIONS, DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT, WORKFLOW_ENABLING_CONSTRAINTS, MINIMUM_VIABLE_WORKFLOWS, } from "../sdk/knowledge.js";
 import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "../sdk/validation-rules.js";
+import { STRUCTURAL_INVARIANTS } from "../sdk/structural-rules.js";
 import { EmaClient } from "../sdk/client.js";
 import { APISchemaRegistry } from "../sdk/workflow-validator.js";
 import { loadConfigFromJsonEnv, loadConfigOptional, resolveBearerToken, getEnvByName, getMasterEnv, } from "../sdk/config.js";
@@ -208,6 +209,13 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async () => JSON.stringify(OPTIMIZATION_RULES, null, 2),
     },
+    {
+        uri: "ema://rules/structural-invariants",
+        name: "rules/structural-invariants",
+        description: "Structural invariants: hard constraints that workflows must satisfy (no cycles, reachability, etc.)",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(STRUCTURAL_INVARIANTS, null, 2),
+    },
     // Deprecated Actions - API-first with fallback
     {
         uri: "ema://rules/deprecated-actions",