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

package/dist/mcp/handlers/persona/create.js

@@ -128,13 +128,48 @@ export async function handleCreate(args, client, getTemplateId) {
     }
     // For persona cloning, default include_data to true
     const effectiveIncludeData = sourcePersonaId ? (includeData ?? true) : false;
-    const result = await client.createAiEmployee({
-        name,
-        description: args.description,
-        template_id: templateId,
-        source_persona_id: sourcePersonaId,
-        clone_data: effectiveIncludeData,
-    });
+    let result;
+    try {
+        result = await client.createAiEmployee({
+            name,
+            description: args.description,
+            template_id: templateId,
+            source_persona_id: sourcePersonaId,
+            clone_data: effectiveIncludeData,
+        });
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        const personaType = args.type;
+        // Provide recovery guidance based on persona type
+        const recovery = {};
+        if (personaType === "voice" || templateId?.includes("voice") || templateId?.includes("001e")) {
+            recovery.option_1 = "Fetch gold template: ema://templates/voice-ai/workflow-def";
+            recovery.option_2 = "Fetch config template: ema://templates/voice-ai/proto-config";
+            recovery.option_3 = "See complete guide: ema://templates/voice-ai/complete";
+        }
+        else if (personaType === "chat") {
+            recovery.option_1 = "Use catalog(type='templates') to list available templates";
+            recovery.option_2 = "Try template(config='chat') for config structure";
+        }
+        else if (personaType === "dashboard") {
+            recovery.option_1 = "Use catalog(type='templates') to list available templates";
+            recovery.option_2 = "Try template(config='dashboard') for config structure";
+        }
+        else {
+            recovery.option_1 = "Use catalog(type='templates') to list available templates";
+            recovery.option_2 = "Specify explicit template ID with from='<template-id>'";
+        }
+        recovery.fallback = "Fetch ema://templates/voice-ai/complete for step-by-step recovery guide";
+        return {
+            error: `create_ai_employee failed`,
+            details: errorMsg,
+            environment: client.env?.name || "unknown",
+            recovery,
+            _tip: "If template creation fails, use gold templates from ema://templates/{type}/workflow-def as fallback.",
+            _warning: "NEVER clone a random existing persona. Use gold templates instead.",
+        };
+    }
     const newPersonaId = result.persona_id ?? result.id;
     if (!newPersonaId) {
         return { error: "Failed to create persona: no ID returned from API" };
@@ -145,21 +180,15 @@ export async function handleCreate(args, client, getTemplateId) {
     let workflowError;
     if (workflowDef && newPersonaId) {
         try {
-            // Get the newly created persona to get its proto_config and existing workflow name
+            // Get the newly created persona to get its proto_config
             const newPersona = await client.getPersonaById(newPersonaId);
             const protoConfig = (newPersona?.proto_config ?? {});
-            const existingWorkflow = (newPersona?.workflow_def ?? newPersona?.workflow);
-            // CRITICAL: Copy the workflowName from the template-created workflow
-            // The API rejects updates if the workflow name doesn't match
-            const existingWfName = existingWorkflow?.workflowName;
-            const workflowForDeploy = JSON.parse(JSON.stringify(workflowDef));
-            if (existingWfName?.name) {
-                // Set/overwrite the workflowName to match the existing one
-                workflowForDeploy.workflowName = existingWfName;
-            }
+            // NOTE: The SDK's updateAiEmployee() handles workflowName namespace automatically.
+            // It will copy from existing workflow if present, or generate a valid namespace if not.
+            // No need to manually manipulate workflowName here.
             await client.updateAiEmployee({
                 persona_id: newPersonaId,
-                workflow: workflowForDeploy,
+                workflow: workflowDef,
                 proto_config: protoConfig, // Required: API needs proto_config alongside workflow
             });
             workflowApplied = true;
@@ -192,6 +221,7 @@ export async function handleCreate(args, client, getTemplateId) {
                 sourcePersonaType,
                 dashboardCloneResult,
                 actionsError: validation.errors.join("; "),
+                createdFromTemplate: fromType === "template",
             });
         }
         // Build execution context
@@ -214,6 +244,7 @@ export async function handleCreate(args, client, getTemplateId) {
             sourcePersonaType,
             // Don't include dashboardCloneResult - actions handle data operations
             actionsResult,
+            createdFromTemplate: fromType === "template",
         });
     }
     // ═══════════════════════════════════════════════════════════════════════════
@@ -235,6 +266,7 @@ export async function handleCreate(args, client, getTemplateId) {
             workflowError,
             sourcePersonaType,
             dashboardCloneResult,
+            createdFromTemplate: fromType === "template",
         });
     }
     return buildCreateResult({
@@ -245,6 +277,7 @@ export async function handleCreate(args, client, getTemplateId) {
         workflowError,
         sourcePersonaType,
         dashboardCloneResult,
+        createdFromTemplate: fromType === "template",
     });
 }
 /**
@@ -270,6 +303,18 @@ function buildCreateResult(opts) {
     if (opts.sourcePersonaType) {
         result.source_persona_type = opts.sourcePersonaType;
     }
+    // ── CRITICAL GUIDANCE: Template workflows are minimal starters ──
+    // This is where LLMs often go wrong - they create from template and think they're done
+    if (opts.createdFromTemplate && !opts.workflowApplied) {
+        result._warning = "PERSONA CREATED BUT WORKFLOW IS INCOMPLETE. Template workflows are minimal starters (just trigger→respond).";
+        result._required_next_steps = [
+            "1. BUILD WORKFLOW: Add intent categorization, search nodes, response handling",
+            `2. If uploading docs: Workflow MUST have search/v2 node or documents will NOT be used`,
+            `3. Get current workflow: workflow(mode='get', persona_id='${opts.newPersonaId}')`,
+            `4. Deploy complete workflow: workflow(mode='deploy', persona_id='${opts.newPersonaId}', workflow_def={...})`,
+        ];
+        result._common_mistake = "Creating from template, uploading docs, and declaring 'done' WITHOUT building the workflow. The deploy will now BLOCK this pattern.";
+    }
     if (opts.dashboardCloneResult) {
         result.dashboard_data_clone = opts.dashboardCloneResult;
     }

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

@@ -5,18 +5,20 @@
  * instead of a giant switch statement. Each mode is in its own file
  * for better testability and maintainability.
  *
- * All standard persona modes are now extracted:
- * - get: Fetch single persona
+ * Persona modes:
+ * - get: Fetch single persona (LLM then analyzes the data)
  * - list: List all personas
  * - templates: List available templates
- * - compare: Compare two personas
  * - sanitize: Sanitize persona data
  * - update: Update persona config
  * - delete: Delete persona (with confirmation)
  * - create/clone: Create new persona from template or clone existing
- * - analyze: Analyze persona for issues
  * - intent: Direct Intent Architect invocation for qualification
  *
+ * REMOVED (LLM does these):
+ * - analyze: LLM analyzes data from 'get'
+ * - compare: LLM compares data from two 'get' calls
+ *
  * Version management modes extracted to version.ts:
  * - snapshot/version_create, history/version_list, version_get
  * - version_compare, restore/version_restore, version_policy
@@ -25,29 +27,27 @@
 import { handleGet } from "./get.js";
 import { handleList } from "./list.js";
 import { handleTemplates } from "./templates.js";
-import { handleCompare } from "./compare.js";
 import { handleSanitize } from "./sanitize.js";
 import { handleUpdate } from "./update.js";
 import { handleDelete } from "./delete.js";
 import { handleCreate } from "./create.js";
-import { handleAnalyze } from "./analyze.js";
 import { handleIntent } from "./intent.js";
 /**
  * Dispatch table for persona modes
  *
  * Note: create/clone handlers require getTemplateId callback as extra param
+ *
+ * REMOVED analyze/compare - LLM does analysis/comparison
  */
 export const PERSONA_MODE_HANDLERS = {
     get: handleGet,
     list: handleList,
     templates: handleTemplates,
-    compare: handleCompare,
     sanitize: handleSanitize,
     update: handleUpdate,
     delete: handleDelete,
     create: handleCreate,
     clone: handleCreate, // Clone uses same handler as create
-    analyze: handleAnalyze,
     intent: handleIntent,
 };
 /**
@@ -66,12 +66,11 @@ export function getPersonaModeHandler(mode) {
 export { handleGet } from "./get.js";
 export { handleList } from "./list.js";
 export { handleTemplates } from "./templates.js";
-export { handleCompare } from "./compare.js";
 export { handleSanitize } from "./sanitize.js";
 export { handleUpdate } from "./update.js";
 export { handleDelete } from "./delete.js";
 export { handleCreate } from "./create.js";
-export { handleAnalyze } from "./analyze.js";
 export { handleIntent } from "./intent.js";
+// REMOVED: handleCompare, handleAnalyze - LLM does analysis/comparison
 // Version management
 export { handleVersion, isVersionMode } from "./version.js";

package/dist/mcp/handlers/persona/update.js

@@ -12,6 +12,7 @@
  * routes to handleWorkflow BEFORE reaching this handler. See handlePersona()
  * in handlers-consolidated.ts.
  */
+import { PROJECT_TYPES } from "../../../sdk/knowledge.js";
 import { resolvePersona, validateWidgetsForApi } from "../utils.js";
 /**
  * Apply WorkflowSpec changes to an existing workflow_def.
@@ -174,7 +175,8 @@ function applySpecToWorkflow(spec, existingWorkflow) {
  * Handle persona(mode="update") - update persona config or workflow
  *
  * @param args.id - Persona ID or name (required)
- * @param args.proto_config - Proto config changes (smart merged with widgets)
+ * @param args.config - Config changes with widgets (preferred, smart merged)
+ * @param args.proto_config - Alias for config (internal, for backwards compatibility)
  * @param args.workflow - Optional raw workflow_def to set
  * @param args.workflow_spec - Optional WorkflowSpec (agent-built) - will be compiled
  * @param args.preview - If true, return changes without deploying (default: false)
@@ -199,10 +201,11 @@ export async function handleUpdate(args, client) {
         : undefined;
     // Determine persona type from projectSettings.projectType
     const projectSettings = existingProtoConfig.projectSettings;
-    const isVoice = projectSettings?.projectType === 5;
+    const isVoice = projectSettings?.projectType === PROJECT_TYPES.voice;
     // Build merged proto_config with smart widget-level merging
+    // Accept both 'config' (tool schema) and 'proto_config' (internal) for compatibility
     let mergedProtoConfig = { ...existingProtoConfig };
-    const newProtoConfig = args.proto_config;
+    const newProtoConfig = (args.config ?? args.proto_config);
     const updatedWidgets = [];
     if (newProtoConfig) {
         // If proto_config has widgets, do smart widget-level merge

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

@@ -34,10 +34,22 @@ export async function handleReference(args, context) {
     if (type === "actions") {
         const client = context?.client;
         const id = args.id;
-        // Categories list
+        // Categories list - API-first with catalog fallback
         if (args.categories) {
+            if (client) {
+                try {
+                    const actions = await client.listActions();
+                    const apiCategories = [...new Set(actions.map(a => a.category).filter(Boolean))];
+                    if (apiCategories.length > 0) {
+                        return { categories: apiCategories, count: apiCategories.length, source: "api" };
+                    }
+                }
+                catch {
+                    // Fallback to catalog
+                }
+            }
             const categories = [...new Set(Object.values(AGENT_CATALOG).map(a => a.category))];
-            return { categories, count: categories.length };
+            return { categories, count: categories.length, source: "catalog" };
         }
         // Suggest for use case
         if (args.suggest) {
@@ -114,6 +126,7 @@ export async function handleReference(args, context) {
                         category: a.category,
                         enabled: a.enabled,
                     })),
+                    source: "api",
                 };
             }
             catch {

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

@@ -4,28 +4,13 @@
  * Handles cross-environment synchronization of personas.
  */
 import { resolvePersona } from "../utils.js";
-// Deprecated param mappings for backwards compatibility
-const DEPRECATED_PARAMS = {
-    identifier: { newName: "id", message: "'identifier' is deprecated, use 'id' instead (will be removed in v2.0.0)" },
-};
-function checkDeprecatedParams(args) {
-    const warnings = [];
-    for (const [oldName, info] of Object.entries(DEPRECATED_PARAMS)) {
-        if (args[oldName] !== undefined) {
-            warnings.push(info.message);
-        }
-    }
-    return warnings;
-}
+import { handleDeprecatedParams } from "../deprecation.js";
 /**
  * Handle sync tool requests - sync personas across environments
  */
 export async function handleSync(args, createClient, getSyncOptions) {
-    // Check for deprecated params and log warnings
-    const deprecationWarnings = checkDeprecatedParams(args);
-    for (const warning of deprecationWarnings) {
-        console.warn(`[sync] Deprecation: ${warning}`);
-    }
+    // Check for deprecated params
+    handleDeprecatedParams(args, "sync");
     const mode = args.mode || "run";
     const id = args.id;
     const identifier = args.identifier; // deprecated alias for 'id'

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

@@ -1,20 +1,21 @@
 /**
  * Workflow Analyze Handler
  *
- * Analyzes workflow structure, detects issues, and provides metrics.
+ * Returns workflow DATA for LLM to analyze using rules from ema://rules/*.
  *
- * Features:
- * - Issue detection (critical, warning, info)
- * - Connection validation
- * - Metrics calculation
- * - Execution flow analysis (loops, dead code, multiple responders)
- * - Auto-fix support
+ * IMPORTANT: This handler does NOT pre-compute issues or fixes.
+ * The LLM applies ANTI_PATTERNS, INPUT_SOURCE_RULES, and OPTIMIZATION_RULES
+ * to reason about the workflow.
+ *
+ * Returns:
+ * - workflow_def: The raw workflow structure
+ * - connections: Type information for each edge
+ * - metrics: Basic counts (nodes, edges, etc.)
+ * - rules_hint: Pointer to ema://rules/* for analysis guidance
  */
-import { detectWorkflowIssues, suggestWorkflowFixes, validateWorkflowConnections } from "../../../sdk/knowledge.js";
-import { autoFixWorkflow } from "../../../sdk/workflow-fixer.js";
-import { analyzeExecutionFlow, generateASCIIFlow } from "../../../sdk/workflow-execution-analyzer.js";
+import { validateWorkflowConnections, parseWorkflowDef } from "../../../sdk/knowledge.js";
 /**
- * Calculate workflow metrics
+ * Calculate workflow metrics (pure data, no analysis)
  */
 function calculateMetrics(workflow) {
     const actions = workflow.actions;
@@ -36,15 +37,24 @@ function calculateMetrics(workflow) {
     // Get trigger type
     const trigger = workflow.trigger;
     const triggerType = trigger?.trigger_type;
+    // Check for categorizer
+    const hasCategorizer = actions.some(a => {
+        const name = a.name?.toLowerCase() ?? "";
+        const action = a.action?.name?.name;
+        return name.includes("categorizer") || action?.includes("categorizer");
+    });
     return {
         node_count: actions.length,
         connection_count: connectionCount,
         has_hitl: hasHitl,
+        has_categorizer: hasCategorizer,
         trigger_type: triggerType,
     };
 }
 /**
  * Handle workflow analyze mode
+ *
+ * Returns DATA for LLM to analyze - does NOT pre-compute issues.
  */
 export async function handleWorkflowAnalyze(args, client) {
     const personaId = args.persona_id;
@@ -62,110 +72,48 @@ export async function handleWorkflowAnalyze(args, client) {
     if (!workflow) {
         return { error: "No workflow to analyze. Provide workflow_def or persona_id." };
     }
-    // Determine what to include
-    const include = args.include || ["issues", "connections", "fixes", "metrics"];
+    // Parse workflow to simpler structure
+    const nodes = parseWorkflowDef(workflow);
+    // Get connection type information
+    const connections = validateWorkflowConnections(workflow);
+    // Calculate metrics
+    const metrics = calculateMetrics(workflow);
     const result = {
         mode: "analyze",
         persona_id: personaId,
         persona_name: persona?.name,
-        environment: "demo",
+        // RAW DATA for LLM to analyze
+        workflow_def: workflow,
+        node_count: nodes.length,
+        nodes: nodes.map(n => ({
+            id: n.id,
+            action: n.action_name,
+            display_name: n.display_name,
+            inputs: n.incoming_edges?.map(e => `${e.source_node_id}.${e.source_output}`),
+        })),
+        // Type information for connections
+        connections: connections.map(c => ({
+            edge: c.edge_id,
+            source_type: c.source_type,
+            target_type: c.target_type,
+            compatible: c.compatible,
+            note: c.note,
+        })),
+        // Basic metrics
+        metrics,
+        // Tell LLM where to find analysis rules
+        _next_steps: [
+            "1. Fetch ema://rules/anti-patterns",
+            "2. Fetch ema://rules/structural-invariants",
+            "3. Check each node against the rules",
+            "4. Report issues YOU find (MCP does not pre-compute)",
+        ],
     };
-    // Issues and fixes
-    if (include.includes("issues") || include.includes("fixes")) {
-        const issues = detectWorkflowIssues(workflow);
-        if (include.includes("issues")) {
-            result.issues = issues;
-        }
-        if (include.includes("fixes")) {
-            result.fixes = suggestWorkflowFixes(issues);
-        }
-        result.issue_summary = {
-            total: issues.length,
-            critical: issues.filter((i) => i.severity === "critical").length,
-            warning: issues.filter((i) => i.severity === "warning").length,
-            info: issues.filter((i) => i.severity === "info").length,
-        };
-        result.validation_passed = issues.filter((i) => i.severity === "critical").length === 0;
-    }
-    // Connection validation
-    if (include.includes("connections")) {
-        result.connections = validateWorkflowConnections(workflow);
-    }
-    // Metrics
-    if (include.includes("metrics")) {
-        result.metrics = calculateMetrics(workflow);
-    }
-    // Execution flow analysis
-    if (include.includes("execution_flow")) {
-        const execAnalysis = analyzeExecutionFlow(workflow);
-        result.execution_flow = {
-            summary: execAnalysis.summary,
-            loops: execAnalysis.loops,
-            multiple_responder_issues: execAnalysis.multipleResponderIssues,
-            redundant_classifiers: execAnalysis.redundantClassifiers,
-            data_flow_issues: execAnalysis.dataFlowIssues,
-            dead_code_paths: execAnalysis.deadCodePaths,
-        };
-        // Include ASCII visualization if requested
-        if (args.visualize) {
-            result.execution_flow_ascii = generateASCIIFlow(execAnalysis);
-        }
-        // Add specific warnings for triple response risk
-        if (execAnalysis.summary.mayRepeatResponses) {
-            result.triple_response_warning = "⚠️ This workflow may cause duplicate/triple responses due to ungated parallel responders";
-        }
-    }
     if (persona) {
         result.persona = {
             id: persona.id,
             name: persona.name
         };
     }
-    // Calculate optimization guidance
-    const issues = result.issues;
-    const criticalCount = issues?.filter(i => i.severity === "critical").length ?? 0;
-    const warningCount = issues?.filter(i => i.severity === "warning").length ?? 0;
-    // AUTO-FIX: If fix=true, apply fixes and deploy
-    if (args.fix && personaId && persona && workflow) {
-        const fixResult = autoFixWorkflow(workflow);
-        result.fixes_applied = fixResult.fixesApplied;
-        result.fixes_warnings = fixResult.warnings;
-        if (fixResult.fixesApplied.length > 0 && fixResult.success) {
-            // Deploy the fixed workflow
-            try {
-                const fixedWorkflow = fixResult.workflowDef;
-                await client.updateAiEmployee({
-                    persona_id: personaId,
-                    workflow: fixedWorkflow,
-                    proto_config: persona.proto_config,
-                });
-                result.fix_status = "deployed";
-                result.fixes_deployed = fixResult.fixesApplied.length;
-                result.status = `✅ Applied ${fixResult.fixesApplied.length} fixes and deployed`;
-            }
-            catch (deployErr) {
-                result.fix_status = "failed";
-                result.fix_error = deployErr instanceof Error ? deployErr.message : String(deployErr);
-                result.status = `⚠️ Fixes applied but deploy failed: ${result.fix_error}`;
-            }
-        }
-        else if (fixResult.fixesApplied.length === 0) {
-            result.fix_status = "no_fixes_needed";
-            result.status = "✅ No auto-fixable issues found";
-        }
-        else {
-            result.fix_status = "failed";
-            result.status = "⚠️ Fix generation failed";
-        }
-        return result;
-    }
-    // Provide optimization suggestion
-    if (criticalCount > 0 || warningCount > 0) {
-        result.optimization_suggestion = `This workflow has ${criticalCount} critical and ${warningCount} warning issues. ` +
-            `Use workflow(persona_id="${personaId ?? 'ID'}", optimize=true) to auto-fix.`;
-    }
-    else {
-        result.status = "✅ Workflow is healthy - no issues detected";
-    }
     return result;
 }