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

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

@@ -1,43 +1,228 @@
 /**
- * Workflow Handler - Unified greenfield/brownfield operations
+ * Workflow Handler
  *
- * Modes:
- * - generate: Create new workflow from input
- * - modify/extend: Transform existing workflow
- * - analyze: Return current state + issues
- * - deploy: Deploy workflow to persona
- * - compare: Compare two workflow versions
- * - compile: Compile WorkflowSpec to workflow_def
- * - optimize: Auto-fix issues
+ * PUBLIC TOOL MODES (workflow tool):
+ * - get: Return workflow data + schema for LLM to generate/modify
+ * - deploy: Deploy LLM-generated workflow_def
  *
- * Note: During extraction, individual mode handlers are being moved here.
- * Until complete, delegates to handlers-consolidated.ts.
+ * INTERNAL MODES (called from persona tool, not exposed):
+ * - modify: Used internally by persona(method="update", input="...")
+ * - generate: Used internally for workflow generation
+ * - analyze: Used internally for workflow analysis
+ * - optimize: Used internally for auto-fix
+ * - compare: Used internally for comparison
+ *
+ * THE LLM DOES ALL THE THINKING. MCP provides data and executes.
  */
+import { generateSchema } from "../../../sdk/generation-schema.js";
 // Re-export types
 export * from "./types.js";
-// Re-export utilities
+// Re-export utilities  
 export * from "./utils.js";
-// Import mode handlers
+// Import internal handlers (not exposed as tool modes, but used internally)
 import { handleWorkflowAnalyze } from "./analyze.js";
 import { handleWorkflowCompare } from "./compare.js";
-import { handleWorkflowCompile } from "./compile.js";
 import { handleWorkflowOptimize } from "./optimize.js";
 import { handleWorkflowDeploy } from "./deploy.js";
 import { handleWorkflowGenerate } from "./generate.js";
 import { handleWorkflowModify } from "./modify.js";
-// Re-export mode handlers
+// Re-export for internal use (persona handler routes to these)
 export { handleWorkflowAnalyze } from "./analyze.js";
 export { handleWorkflowCompare } from "./compare.js";
-export { handleWorkflowCompile } from "./compile.js";
 export { handleWorkflowOptimize } from "./optimize.js";
 export { handleWorkflowDeploy } from "./deploy.js";
 export { handleWorkflowGenerate } from "./generate.js";
 export { handleWorkflowModify } from "./modify.js";
 export { applyWorkflowModifications, buildWorkflowAction, buildInputBinding, } from "./modify.js";
+// Fallback deprecated actions - ONLY used when API unavailable
+// Source: ema/ema_backend/grpc/workflow_actions/registered_actions.py (synced 2026-01-26)
+// Exported for use by deploy handler
+export const DEPRECATED_ACTIONS_FALLBACK = {
+    "search/v0": { replacement: "search/v2", notes: "v2 requires datastore_configs input" },
+    "web_search/v0": { replacement: "live_web_search or ai_web_search", notes: "Split into two specialized actions" },
+    "call_llm/v0": { replacement: "call_llm/v2" },
+    "human_collaboration/v0": { replacement: "general_hitl" },
+    "fixed_response/v0": { replacement: "fixed_response/v1" },
+    "custom_agent/v0": { replacement: "custom_agent/v1" },
+    "json_mapper/v0": { replacement: "json_mapper/v1" },
+    "text_categorizer/v0": { replacement: "text_categorizer/v1" },
+    "respond_with_sources/v0": { replacement: "respond_for_external_actions", notes: "Handles tool results better" },
+};
+/**
+ * Get deprecated actions from API (with fallback)
+ * Returns map of action/version -> replacement info
+ */
+async function getDeprecatedActions(client) {
+    try {
+        const actions = await client.listActions();
+        const deprecated = {};
+        for (const action of actions) {
+            if (action.deprecated) {
+                // Use action name as key (API doesn't include version in deprecated flag)
+                deprecated[action.id] = {
+                    notes: "Deprecated - check catalog for current version",
+                };
+            }
+        }
+        // Merge with fallback to get replacement info
+        for (const [key, info] of Object.entries(DEPRECATED_ACTIONS_FALLBACK)) {
+            const actionName = key.split("/")[0];
+            if (deprecated[actionName] || !deprecated[key]) {
+                deprecated[key] = { ...info, ...deprecated[key] };
+            }
+        }
+        return { deprecated, source: "api" };
+    }
+    catch {
+        // API unavailable, use fallback
+        return { deprecated: DEPRECATED_ACTIONS_FALLBACK, source: "fallback" };
+    }
+}
+/**
+ * Check if workflow uses deprecated actions
+ * Exported for use by deploy handler
+ */
+export function checkWorkflowDeprecations(workflowDef, deprecatedActions) {
+    if (!workflowDef)
+        return [];
+    const warnings = [];
+    const actions = (workflowDef.actions ?? []);
+    for (const action of actions) {
+        const actionName = action.action?.name?.name;
+        const version = action.action?.name?.version || "v0";
+        if (!actionName)
+            continue;
+        const key = `${actionName}/${version}`;
+        const deprecation = deprecatedActions[key] || deprecatedActions[actionName];
+        if (deprecation) {
+            warnings.push({
+                action: action.name,
+                version,
+                replacement: deprecation.replacement,
+                notes: deprecation.notes,
+                severity: "warning",
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Handle workflow(mode="get") - return data + schema + guidance for LLM
+ *
+ * Returns:
+ * - Current workflow_def (if exists)
+ * - Deprecation warnings for current workflow
+ * - Generation schema (agents, types, constraints)
+ * - Requirements and guidance (NOT hardcoded templates)
+ * - Available widgets
+ *
+ * LLM uses this to generate or modify workflow_def
+ */
+async function handleWorkflowGet(args, client) {
+    const personaId = args.persona_id;
+    if (!personaId) {
+        return { error: "persona_id required" };
+    }
+    const persona = await client.getPersonaById(personaId);
+    if (!persona) {
+        return { error: `Persona not found: ${personaId}` };
+    }
+    const protoConfig = persona.proto_config;
+    const widgets = (protoConfig?.widgets ?? []);
+    const workflowDef = persona.workflow_def;
+    // Extract available widget names for LLM
+    const availableWidgets = widgets
+        .filter(w => typeof w.name === "string")
+        .map(w => ({
+        name: w.name,
+        type: w.type,
+    }));
+    // Get generation schema for LLM
+    const schema = generateSchema();
+    // Get deprecated actions (API-first, with fallback)
+    const { deprecated: deprecatedActions, source: deprecationSource } = await getDeprecatedActions(client);
+    // Check if current workflow uses deprecated actions
+    const deprecationWarnings = checkWorkflowDeprecations(workflowDef, deprecatedActions);
+    // Build response
+    const result = {
+        persona_id: persona.id,
+        persona_name: persona.name,
+        persona_type: persona.type,
+        workflow_def: workflowDef ?? null,
+        available_widgets: availableWidgets,
+        // Deprecation warnings (severity: warning)
+        deprecation_warnings: deprecationWarnings.length > 0 ? deprecationWarnings : undefined,
+        deprecated_actions_source: deprecationWarnings.length > 0 ? deprecationSource : undefined,
+        // Schema for LLM to generate valid workflow_def
+        generation_schema: {
+            agents: schema.agents,
+            constraints: schema.constraints,
+            input_rules: schema.inputRules,
+        },
+        // HARD REQUIREMENTS (must be satisfied)
+        hard_requirements: {
+            workflow_output: {
+                rule: "Every workflow MUST have results.WORKFLOW_OUTPUT mapped to a final action output",
+                format: '{ "results": { "WORKFLOW_OUTPUT": { "actionName": "...", "outputName": "..." } } }',
+                failure: "Persona cannot be activated without this",
+            },
+            workflow_name: {
+                rule: "workflowName must be ['ema', 'personas', '<persona_id>']",
+                format: '{ "workflowName": ["ema", "personas", "actual-persona-id"] }',
+            },
+            action_structure: {
+                rule: "Each action needs: name (unique ID), action.name (namespaces, name, version), action.inputs",
+                namespaces: "Most actions use ['actions', 'emainternal'], triggers use ['triggers', 'emainternal']",
+            },
+            no_deprecated_actions: deprecationWarnings.length > 0 ? {
+                rule: "Update deprecated actions before deploying",
+                warnings: deprecationWarnings,
+            } : undefined,
+        },
+        // GUIDANCE (best practices, not hard requirements)
+        guidance: {
+            flow_pattern: "trigger → categorizer (optional) → processing → response → WORKFLOW_OUTPUT",
+            categorizer: "For multi-intent workflows, use chat_categorizer early with a Fallback category",
+            fallback: "Every categorizer MUST have a Fallback category for unmatched intents",
+            hitl: "For actions with side effects (email, external calls), consider general_hitl for approval",
+            search: "Use search/v2 with datastore_configs. Wire query from trigger output.",
+        },
+        // LLM-driven analysis pattern: MCP provides data, LLM does the thinking
+        _next_steps: deprecationWarnings.length > 0
+            ? [
+                "WARNING: Workflow uses deprecated actions. Update them first:",
+                ...deprecationWarnings.map(w => `  - ${w.action}: ${w.replacement || "check catalog for replacement"}`),
+                "",
+                "To analyze workflow health:",
+                "1. Fetch ema://rules/anti-patterns",
+                "2. Fetch ema://rules/structural-invariants",
+                "3. Check workflow_def nodes against the rules",
+                "4. Report issues YOU find (MCP does not pre-compute)",
+                "",
+                "Then deploy with: workflow(mode='deploy', persona_id='...', workflow_def={...})",
+            ]
+            : [
+                "To analyze workflow health:",
+                "1. Fetch ema://rules/anti-patterns",
+                "2. Fetch ema://rules/structural-invariants",
+                "3. Check workflow_def nodes against the rules",
+                "4. Report issues YOU find (MCP does not pre-compute)",
+                "",
+                "Generate or modify workflow_def based on requirements above",
+                "Deploy with: workflow(mode='deploy', persona_id='...', workflow_def={...})",
+            ],
+    };
+    // Include deprecated actions reference if there are warnings or on request
+    if (deprecationWarnings.length > 0 || args.include_deprecated) {
+        result.deprecated_actions_reference = deprecatedActions;
+    }
+    return result;
+}
 /**
  * Main workflow handler with mode-based dispatch
  *
- * Routes to the appropriate extracted handler based on effective mode.
+ * PUBLIC modes: get, deploy
+ * INTERNAL modes: modify, generate, analyze, optimize, compare (called from persona tool)
  */
 export async function handleWorkflow(args, client, getTemplateId) {
     const personaId = args.persona_id;
@@ -46,90 +231,78 @@ export async function handleWorkflow(args, client, getTemplateId) {
     const optimize = args.optimize;
     const compareTo = args.compare_to;
     const operations = args.operations;
-    // Smart mode detection - user doesn't need to specify
-    let effectiveMode;
-    if (args.mode === "compile") {
-        effectiveMode = "compile";
-    }
-    else if (compareTo) {
-        effectiveMode = "compare";
-    }
-    else if (optimize && personaId) {
-        effectiveMode = "optimize";
-    }
-    else if (personaId && workflowDef) {
-        effectiveMode = "deploy";
-    }
-    else if (personaId && (input || operations)) {
-        // Modify mode: either natural language input OR structured operations
-        effectiveMode = "modify";
-    }
-    else if (input && !personaId) {
-        effectiveMode = "generate";
-    }
-    else if (personaId || workflowDef || args.include) {
-        effectiveMode = "analyze";
-    }
-    else {
-        effectiveMode = "analyze";
-    }
-    // Explicit mode support
-    const legacyMode = args.mode;
-    if (legacyMode === "extend")
-        effectiveMode = "modify";
-    if (legacyMode === "modify")
-        effectiveMode = "modify";
-    if (legacyMode === "deploy")
-        effectiveMode = "deploy";
-    // Route to extracted handler
-    switch (effectiveMode) {
-        case "generate":
-            return handleWorkflowGenerate(args, client, getTemplateId);
-        case "modify":
-        case "extend":
-            return handleWorkflowModify(args, client);
-        case "analyze":
-            return handleWorkflowAnalyze(args, client);
-        case "deploy":
-            return handleWorkflowDeploy(args, client);
-        case "compare":
-            return handleWorkflowCompare(args, client);
-        case "compile":
-            return handleWorkflowCompile(args, client);
-        case "optimize":
-            return handleWorkflowOptimize(args, client);
-        default:
-            return { error: `Unknown mode: ${effectiveMode}` };
+    // Explicit mode takes priority
+    const mode = args.mode;
+    // PUBLIC MODES (from workflow tool)
+    if (mode === "get") {
+        return handleWorkflowGet(args, client);
+    }
+    if (mode === "deploy") {
+        return handleWorkflowDeploy(args, client);
+    }
+    // INTERNAL MODES (called from persona tool, not workflow tool)
+    if (mode === "modify" || mode === "extend") {
+        return handleWorkflowModify(args, client);
+    }
+    if (mode === "generate") {
+        return handleWorkflowGenerate(args, client, getTemplateId);
+    }
+    if (mode === "analyze") {
+        return handleWorkflowAnalyze(args, client);
+    }
+    if (mode === "optimize") {
+        return handleWorkflowOptimize(args, client);
+    }
+    if (mode === "compare") {
+        return handleWorkflowCompare(args, client);
+    }
+    // Auto-detect mode (for backwards compatibility with internal routing)
+    if (compareTo) {
+        return handleWorkflowCompare(args, client);
+    }
+    if (optimize && personaId) {
+        return handleWorkflowOptimize(args, client);
+    }
+    if (personaId && workflowDef) {
+        return handleWorkflowDeploy(args, client);
     }
+    if (personaId && (input || operations)) {
+        return handleWorkflowModify(args, client);
+    }
+    if (input && !personaId) {
+        return handleWorkflowGenerate(args, client, getTemplateId);
+    }
+    if (personaId) {
+        return handleWorkflowAnalyze(args, client);
+    }
+    // Invalid mode
+    return {
+        error: `Invalid or missing mode: ${mode}`,
+        public_modes: ["get", "deploy"],
+        hint: "MCP provides data (get) and executes (deploy). LLM does all thinking.",
+    };
 }
 /**
  * Check if a workflow mode has been extracted
  */
 export function hasExtractedWorkflowHandler(mode) {
-    const extractedModes = ["analyze", "compare", "compile", "optimize", "deploy", "generate", "modify", "extend"];
+    const extractedModes = ["get", "deploy", "modify", "extend", "generate", "analyze", "optimize", "compare"];
     return extractedModes.includes(mode);
 }
 /**
  * Get handler for a specific workflow mode
- * Note: generate handler has a different signature (requires getTemplateId)
  */
 export function getWorkflowModeHandler(mode) {
     switch (mode) {
-        case "analyze":
-            return handleWorkflowAnalyze;
-        case "compare":
-            return handleWorkflowCompare;
-        case "compile":
-            return handleWorkflowCompile;
-        case "optimize":
-            return handleWorkflowOptimize;
+        case "get":
         case "deploy":
-            return handleWorkflowDeploy;
-        case "generate":
-            return handleWorkflowGenerate;
         case "modify":
         case "extend":
-            return handleWorkflowModify;
+        case "generate":
+        case "analyze":
+        case "optimize":
+        case "compare":
+            return handleWorkflow;
         default:
             return undefined;
     }

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

@@ -8,7 +8,6 @@
  *
  * 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";
 // ─────────────────────────────────────────────────────────────────────────
@@ -323,9 +322,6 @@ 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()
@@ -335,20 +331,21 @@ export async function handleWorkflowModify(args, client) {
             message: "No operations provided. Returning workflow context for Agent to build operations.",
             persona_id: personaId,
             persona_name: persona.name,
-            // Current workflow state
+            // 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: [
+                "1. Review current_nodes and available_actions above",
+                "2. Fetch ema://rules/anti-patterns to check for issues",
+                "3. Build ModificationOperation[] based on your analysis",
+                "4. Pass operations as 'operations' parameter",
+            ],
             // Example operation structures
             example_operations: {
                 insert_hitl: {
@@ -392,9 +389,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,23 +400,9 @@ 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",
-        };
-    }
-    // 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",
+            _tip: "Preview complete. Use ema://rules/anti-patterns to check for issues. Call without preview=true to deploy.",
         };
     }
     // Deploy the workflow

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;
 }