@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

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

@@ -5,6 +5,7 @@
  * - get: Return workflow data + schema for LLM to generate/modify
  * - deploy: Deploy LLM-generated workflow_def
  * - validate: Validate a workflow_def before deploying
+ * - optimize: Structural graph optimization
  *
  * THE LLM DOES ALL THE THINKING. MCP provides data and executes.
  *
@@ -13,7 +14,7 @@
  * - generate: Had MCP generating workflow - LLM should generate full workflow_def
  *
  * DEPRECATED (kept for backwards compat, but not exposed):
- * - analyze, optimize, compare: LLM can do this by fetching rules and comparing
+ * - analyze, compare: LLM can do this by fetching rules and comparing
  */
 import { generateSchema } from "../../domain/generation-schema.js";
 import { fingerprintPersona } from "../../../sync.js";
@@ -21,18 +22,13 @@ import { fingerprintPersona } from "../../../sync.js";
 export * from "./types.js";
 // Re-export utilities  
 export * from "./utils.js";
-// Import internal handlers (not exposed as tool modes, but used internally)
-import { handleWorkflowAnalyze } from "./analyze.js";
-import { handleWorkflowCompare } from "./compare.js";
+// Import internal handlers
 import { handleWorkflowOptimize } from "./optimize.js";
 import { handleWorkflowDeploy } from "./deploy.js";
 import { handleWorkflowValidate } from "./validate.js";
 // Re-export for internal use (persona handler routes to these)
-export { handleWorkflowAnalyze } from "./analyze.js";
-export { handleWorkflowCompare } from "./compare.js";
 export { handleWorkflowOptimize } from "./optimize.js";
 export { handleWorkflowDeploy } from "./deploy.js";
-export { handleWorkflowGenerate } from "./generate.js";
 // NOTE: modify.ts REMOVED - violated LLM-driven architecture
 // The correct flow is: workflow(mode="get") → LLM modifies → workflow(mode="deploy")
 // Fallback deprecated actions - ONLY used when API unavailable
@@ -228,8 +224,8 @@ async function handleWorkflowGet(args, client) {
 /**
  * Main workflow handler with mode-based dispatch
  *
- * PUBLIC modes: get, deploy
- * INTERNAL modes: modify, generate, analyze, optimize, compare (called from persona tool)
+ * PUBLIC modes: get, deploy, validate, optimize
+ * INTERNAL modes: modify, generate, analyze, compare (called from persona tool)
  */
 export async function handleWorkflow(args, client, _getTemplateId) {
     const personaId = args.persona_id;
@@ -246,6 +242,9 @@ export async function handleWorkflow(args, client, _getTemplateId) {
     if (mode === "validate") {
         return handleWorkflowValidate(args, client);
     }
+    if (mode === "optimize") {
+        return handleWorkflowOptimize(args, client);
+    }
     // REMOVED: modify, generate modes violated LLM-driven architecture
     // MCP was doing LLM work (parsing operations, generating workflows)
     // Correct flow: LLM generates full workflow_def → workflow(mode="deploy")
@@ -261,16 +260,17 @@ export async function handleWorkflow(args, client, _getTemplateId) {
             _tip: "The LLM generates the full workflow_def. MCP just deploys it.",
         };
     }
-    // DEPRECATED: analyze, optimize, compare - LLM can do this directly
-    // Kept for backwards compat but may be removed
-    if (mode === "analyze") {
-        return handleWorkflowAnalyze(args, client);
-    }
-    if (mode === "optimize") {
-        return handleWorkflowOptimize(args, client);
-    }
-    if (mode === "compare") {
-        return handleWorkflowCompare(args, client);
+    // REMOVED: analyze, compare - LLM does this by fetching rules and comparing
+    if (mode === "analyze" || mode === "compare") {
+        return {
+            error: `Mode "${mode}" has been removed.`,
+            reason: "LLM can do analysis/comparison by fetching ema://rules/* and reasoning about workflow_def.",
+            correct_flow: [
+                "1. workflow(mode='get', persona_id='...') - get current workflow_def",
+                "2. Fetch ema://rules/anti-patterns and ema://rules/structural-invariants",
+                "3. LLM analyzes/compares the data",
+            ],
+        };
     }
     // Auto-detect: only deploy if workflow_def provided
     if (personaId && workflowDef) {
@@ -283,18 +283,17 @@ export async function handleWorkflow(args, client, _getTemplateId) {
     // Invalid mode
     return {
         error: `Invalid or missing mode: ${mode}`,
-        public_modes: ["get", "deploy", "validate"],
-        hint: "MCP provides data (get), validates (validate), and executes (deploy). LLM does all thinking.",
+        public_modes: ["get", "deploy", "validate", "optimize"],
+        hint: "MCP provides data (get), validates (validate), optimizes (optimize), and executes (deploy). LLM does all thinking.",
     };
 }
 /**
  * Check if a workflow mode has been extracted
  */
 export function hasExtractedWorkflowHandler(mode) {
-    // PUBLIC: get, deploy, validate
-    // DEPRECATED (kept for compat): analyze, optimize, compare
-    // REMOVED: modify, extend, generate (violated LLM-driven architecture)
-    const extractedModes = ["get", "deploy", "validate", "analyze", "optimize", "compare"];
+    // PUBLIC: get, deploy, validate, optimize
+    // REMOVED: modify, extend, generate, analyze, compare
+    const extractedModes = ["get", "deploy", "validate", "optimize"];
     return extractedModes.includes(mode);
 }
 /**
@@ -305,11 +304,9 @@ export function getWorkflowModeHandler(mode) {
         case "get":
         case "deploy":
         case "validate":
-        case "analyze":
         case "optimize":
-        case "compare":
             return handleWorkflow;
-        // REMOVED: modify, extend, generate
+        // REMOVED: modify, extend, generate, analyze, compare
         default:
             return undefined;
     }

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

@@ -1,50 +1,90 @@
 /**
  * Workflow Optimize Handler
  *
- * 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")
+ * Structural graph optimization using the workflow-graph-optimizer.
+ * Accepts persona_id (fetches workflow) OR workflow_def (direct optimization).
+ * Returns optimized workflow_def + report. Does NOT auto-deploy.
  */
+import { optimizeWorkflow } from "../../domain/workflow-graph-optimizer.js";
 /**
- * Handle workflow optimize mode
+ * Handle workflow(mode="optimize") - structural graph optimization
  *
- * NOW DEPRECATED - Returns guidance for LLM to do the analysis.
+ * Follows the same parameter extraction pattern as handleWorkflowValidate:
+ * - persona_id → fetch workflow from persona
+ * - workflow_def → optimize directly
+ * - auto_apply (default true) → apply safe auto-transforms
+ * - max_passes (default 5) → convergence limit
  */
 export async function handleWorkflowOptimize(args, client) {
     const personaId = args.persona_id;
-    if (!personaId) {
-        return { error: "persona_id required for optimize mode" };
+    const workflowDef = args.workflow_def;
+    const autoApply = args.auto_apply ?? true;
+    const maxPasses = args.max_passes ?? 5;
+    // Get workflow to optimize
+    let workflowToOptimize = null;
+    let personaName;
+    if (workflowDef) {
+        // Use provided workflow_def directly
+        workflowToOptimize = workflowDef;
     }
-    const persona = await client.getPersonaById(personaId);
-    if (!persona) {
-        return { error: `Persona not found: ${personaId}` };
+    else if (personaId) {
+        // Get workflow from persona
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        personaName = persona.name;
+        const personaWorkflowDef = persona.workflow_def;
+        if (!personaWorkflowDef) {
+            return {
+                error: `Persona "${persona.name}" has no workflow to optimize`,
+                _tip: "Deploy a workflow first, then optimize it",
+            };
+        }
+        workflowToOptimize = personaWorkflowDef;
     }
-    const existingWorkflow = persona.workflow_def;
-    if (!existingWorkflow) {
+    else {
         return {
-            error: `Persona "${persona.name}" has no workflow to optimize`,
-            hint: "Use mode='generate' to create a workflow first",
+            error: "Either persona_id or workflow_def required for optimize mode",
         };
     }
-    // Return the workflow and guidance for LLM to do the analysis
-    return {
+    if (!workflowToOptimize) {
+        return { error: "Could not extract workflow for optimization" };
+    }
+    // Run the graph optimizer
+    const result = optimizeWorkflow(workflowToOptimize, {
+        autoApply,
+        maxPasses,
+    });
+    // Format response
+    const response = {
         mode: "optimize",
-        status: "DEPRECATED - Use LLM analysis instead",
-        persona_id: personaId,
-        persona_name: persona.name,
-        // 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={...})",
-        ],
+        ...(personaId && { persona_id: personaId }),
+        ...(personaName && { persona_name: personaName }),
+        // Core result
+        modified: result.modified,
+        workflow_def: result.workflowDef,
+        // What was done
+        applied_transforms: result.appliedTransforms.length > 0
+            ? result.appliedTransforms
+            : undefined,
+        // What the LLM should review
+        advisories: result.advisories.length > 0
+            ? result.advisories
+            : undefined,
+        // Before/after metrics
+        metrics: result.metrics,
+        // Post-optimization validation
+        validation: result.validation,
+        // Guidance
+        _tip: result.modified
+            ? "Optimization applied transforms. Review the changes, then deploy with: workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={...})"
+            : result.advisories.length > 0
+                ? "No auto-transforms applied, but advisories found. Review them and modify the workflow_def manually if needed."
+                : "Workflow is already optimal. No changes needed.",
+        _next_step: result.modified
+            ? "workflow(mode='get', persona_id='...') to get fresh fingerprint, then workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={optimized_workflow_def})"
+            : undefined,
     };
+    return response;
 }

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

@@ -706,7 +706,7 @@ export function validateExternalActionCallerTools(workflowDef) {
 // ═══════════════════════════════════════════════════════════════════════════
 // LOOP DETECTION VALIDATION
 // ═══════════════════════════════════════════════════════════════════════════
-import { detectLoops } from "../../domain/workflow-execution-analyzer.js";
+import { detectLoops } from "../../domain/loop-detection.js";
 /**
  * Validate that workflow has no circular dependencies.
  * Circular references cause infinite execution loops.

package/dist/mcp/knowledge-types.js

@@ -0,0 +1,7 @@
+/**
+ * Ema Platform Knowledge Base — Type Definitions
+ *
+ * All type definitions/interfaces/enums used across knowledge modules.
+ * Split from knowledge.ts for focused module organization.
+ */
+export {};