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

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":

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', ...)"
 }
 \`\`\`
 
@@ -338,15 +333,19 @@ Environment: ${args.env || "demo"}
 
 Follow this review workflow using the consolidated tools:
 
-### Step 1: Fetch Persona + Workflow
-Call \`persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")\` to fetch the full workflow_def.
+### Step 1: Fetch Workflow Data
+Call \`workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` to get the workflow_def, schema, and examples.
 
-### Step 2: Analyze (Issues + Connections + Fixes + Metrics)
-Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}")\`.
+### Step 2: Analyze (YOU do this)
+Review the workflow_def for:
+- Missing WORKFLOW_OUTPUT (required for activation)
+- Missing Fallback category in categorizers
+- Type mismatches between connected nodes
+- Orphan nodes not connected to output
 
-### Step 3: (Optional) Preview Auto-Fixes
-If issues are found and you want a one-click preview of fixes:
-Call \`workflow(mode="optimize", persona_id="${args.persona_id}", preview=true, env="${args.env || "demo"}")\`.
+### Step 3: Propose Fixes
+If issues are found, generate a corrected workflow_def and deploy:
+Call \`workflow(mode="deploy", persona_id="${args.persona_id}", workflow_def={...}, env="${args.env || "demo"}")\`.
 
 ## Output Format
 
@@ -456,9 +455,9 @@ ${args.symptoms.toLowerCase().includes("hitl") || args.symptoms.toLowerCase().in
 ` : ""}
 ${args.symptoms.toLowerCase().includes("type") || args.symptoms.toLowerCase().includes("mismatch") ? `
 **Type Compatibility Issues:**
-- Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}", include=["connections"])\` for an edge-by-edge type check
+- Call \`workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` and analyze the workflow_def
+- Check wellKnownType compatibility between connected nodes
 - Common issues: chat_conversation → search (should be user_query)
-- Check wellKnownType compatibility
 ` : ""}
 ${args.symptoms.toLowerCase().includes("loop") || args.symptoms.toLowerCase().includes("infinite") || args.symptoms.toLowerCase().includes("hang") ? `
 **Loop/Hang Issues:**
@@ -467,8 +466,8 @@ ${args.symptoms.toLowerCase().includes("loop") || args.symptoms.toLowerCase().in
 - Verify workflow has proper termination paths
 ` : ""}
 
-### Step 4: Run Issue Detection
-Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` to find issues, connections, suggested fixes, and metrics.
+### Step 4: Review Workflow
+Call \`workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` and analyze the workflow_def for issues.
 
 ### Step 5: Propose Fix
 Based on findings, provide specific fix with before/after configuration.
@@ -642,13 +641,15 @@ Call in parallel:
 - \`persona(id="${args.persona_id_1}", include_workflow=true, env="${args.env_1 || "demo"}")\`
 - \`persona(id="${args.persona_id_2}", include_workflow=true, env="${args.env_2 || args.env_1 || "demo"}")\`
 
-### Step 2: Compare
-Call \`persona(id="${args.persona_id_1}", mode="compare", compare_to="${args.persona_id_2}", env="${args.env_1 || "demo"}", compare_env="${args.env_2 || args.env_1 || "demo"}")\`.
+### Step 2: Get Both Personas
+Call \`persona(method="get", id="${args.persona_id_1}", include_workflow=true, env="${args.env_1 || "demo"}")\`
+Call \`persona(method="get", id="${args.persona_id_2}", include_workflow=true, env="${args.env_2 || args.env_1 || "demo"}")\`
 
-### Step 3: Compare Workflows (if both have workflows)
-If both personas are in the same environment, call:
-\`workflow(mode="compare", persona_id="${args.persona_id_1}", compare_to="${args.persona_id_2}", env="${args.env_1 || "demo"}")\`
-to see structural differences.
+### Step 3: Compare (YOU do this)
+Compare the two workflow_def structures:
+- Node differences (added/removed/renamed)
+- Connection differences
+- Configuration differences
 
 ## Output Format
 
@@ -754,8 +755,9 @@ ${args.action === "snapshot" ? `
 1. List versions first to see available:
    \`persona(id="${args.persona_id}", mode="version_list", env="${args.env || "demo"}")\`
 
-2. Compare two versions:
-   \`persona(id="${args.persona_id}", mode="version_compare", v1="${args.version || "v1"}", v2="latest", env="${args.env || "demo"}")\`
+2. Get two versions and compare (YOU compare the results):
+   \`persona(id="${args.persona_id}", mode="version_get", version="${args.version || "v1"}", env="${args.env || "demo"}")\`
+   \`persona(id="${args.persona_id}", mode="version_get", version="latest", env="${args.env || "demo"}")\`
 
 3. Present changes:
    - Fields that changed
@@ -937,7 +939,7 @@ Provide examples of common tasks:
 2. **Search for specific persona**: \`persona(query="support", status="active", env="demo")\`
 3. **Get full persona details**: \`persona(id="xxx", include_workflow=true, env="demo")\`
 4. **Sync a persona**: \`sync(id="my-bot", source="demo", target="dev")\`
-5. **Analyze workflow**: \`workflow(mode="analyze", persona_id="xxx", env="demo")\`
+5. **Get workflow data**: \`workflow(mode="get", persona_id="xxx", env="demo")\` (you analyze the result)
 
 ## Output Format
 
@@ -1027,6 +1029,15 @@ ${args.intents ? `**Intents**: ${args.intents}` : ""}
 
 ## Instructions
 
+### Step 0: Check Deprecated Actions (DO THIS FIRST)
+Fetch \`ema://rules/deprecated-actions-summary\` to know which actions to AVOID.
+
+**Key deprecated actions to avoid:**
+- search/v0 → use search/v2 (requires datastore_configs)
+- respond_with_sources → use respond_for_external_actions
+- call_llm/v0 → use call_llm/v2
+- web_search/v0 → use live_web_search or ai_web_search
+
 ### Step 1: Get Templates
 Get templates from API or use generated fallbacks:
 - \`template(config="voice")\` - Voice AI persona configuration (API-first with fallback)
@@ -1061,10 +1072,12 @@ ${args.name.toLowerCase().replace(/\s+/g, "-")}/
 └── proto-config.json      # Full API config
 \`\`\`
 
+**IMPORTANT**: Only use non-deprecated actions from Step 0.
+
 ### Step 6: Validate
 Call \`reference(validate_prompt=<generated_prompt>)\` to verify the prompt.
 
-Now begin by reading the resources, then proceed with generation.`,
+Now begin by reading the deprecated actions, then proceed with generation.`,
                 },
             },
         ],
@@ -1107,6 +1120,15 @@ ${args.data_sources ? `**Data Sources**: ${args.data_sources}` : ""}
 
 ## Instructions
 
+### Step 0: Check Deprecated Actions (DO THIS FIRST)
+Fetch \`ema://rules/deprecated-actions-summary\` to know which actions to AVOID.
+
+**Key deprecated actions to avoid:**
+- search/v0 → use search/v2 (requires datastore_configs)
+- respond_with_sources → use respond_for_external_actions
+- call_llm/v0 → use call_llm/v2
+- web_search/v0 → use live_web_search or ai_web_search
+
 ### Step 1: Get Templates
 Get templates from API or use generated fallbacks:
 - \`template(config="chat")\` - Chat AI persona configuration (API-first with fallback)
@@ -1130,6 +1152,8 @@ Call \`reference(guidance="conversation-vs-query")\` to understand:
 ### Step 5: Generate Output
 Using the templates from Step 1 and guidance from Steps 3-4, generate:
 
+**IMPORTANT**: Only use non-deprecated actions from Step 0.
+
 **Folder structure:**
 \`\`\`
 ${args.name.toLowerCase().replace(/\s+/g, "-")}/
@@ -1183,6 +1207,16 @@ Now begin by reading the resources, then proceed with generation.`,
 **Type**: ${args.type}
 **Description**: ${args.description}
 
+## Step 0: Check Deprecated Actions (DO THIS FIRST)
+
+Fetch \`ema://rules/deprecated-actions-summary\` to see which actions to AVOID.
+
+Common deprecated actions:
+- search/v0 → use search/v2 (requires datastore_configs)
+- respond_with_sources → use respond_for_external_actions
+- call_llm/v0 → use call_llm/v2
+- web_search/v0 → use live_web_search or ai_web_search
+
 ## Step 1: Preview the workflow
 
 \`\`\`
@@ -1193,6 +1227,7 @@ workflow(
 \`\`\`
 
 This returns workflow_def and proto_config. Review them before deploying.
+**Check for any deprecated actions in the generated workflow.**
 
 ## Step 2: Deploy when ready
 
@@ -1213,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.
 ` : ""}`,
@@ -1349,8 +1385,7 @@ ${args.workflow_def ? `**Workflow Definition**: Provided inline` : ""}
 ${args.persona_id ? `First, fetch the workflow:
 \`persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")\`
 
-Then analyze it using:
-\`workflow(persona_id="${args.persona_id}", mode="analyze", env="${args.env || "demo"}")\`
+Then review the workflow_def for issues (missing WORKFLOW_OUTPUT, type mismatches, etc.).
 ` : ""}
 
 ## Required Analysis Sections
@@ -1506,10 +1541,11 @@ Proceed to Phase 1.
 
 ### Step 1.1: Fetch and Analyze
 \`\`\`
-persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")
-workflow(persona_id="${args.persona_id}", mode="analyze", env="${args.env || "demo"}")
+workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")
 \`\`\`
 
+Review the workflow_def for issues (missing WORKFLOW_OUTPUT, type mismatches, orphan nodes).
+
 ### Step 1.2: Document Existing Logic
 Before making changes, document:
 - **Current intents**: List all categories and their handlers
@@ -1611,8 +1647,8 @@ workflow(
 
 ## Phase 4: Validate & Deploy
 
-### Step 4.1: Analyze Changes
-\`workflow(persona_id="${args.persona_id}", mode="analyze")\`
+### Step 4.1: Review Changes
+\`workflow(mode="get", persona_id="${args.persona_id}")\` and verify the workflow_def is correct.
 
 Verify:
 - [ ] No type mismatches
@@ -1620,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
 
@@ -1709,10 +1746,11 @@ Provide:
 ## Step 1: Fetch Workflow Data
 
 \`\`\`
-persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")
-workflow(persona_id="${args.persona_id}", mode="analyze", env="${args.env || "demo"}")
+workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")
 \`\`\`
 
+Review the workflow_def for issues (missing WORKFLOW_OUTPUT, type mismatches, orphan nodes).
+
 ## Step 2: Intent Analysis Framework
 
 ### Business Intent Layer