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

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

@@ -0,0 +1,234 @@
+/**
+ * Version Management Handlers
+ *
+ * Provides local version tracking for personas (snapshot, history, restore).
+ * Versions are stored in the local workspace, not on the Ema platform.
+ */
+import { createVersionStorage } from "../../../sdk/version-storage.js";
+import { createVersionPolicyEngine } from "../../../sdk/version-policy.js";
+/**
+ * Check if a mode is a version management mode.
+ */
+export function isVersionMode(mode) {
+    return [
+        "snapshot",
+        "history",
+        "restore",
+        "version_create",
+        "version_list",
+        "version_get",
+        "version_compare",
+        "version_restore",
+        "version_policy",
+    ].includes(mode);
+}
+/**
+ * Handle version management operations.
+ *
+ * @param mode - The version mode (snapshot, history, restore, version_*)
+ * @param args - Handler arguments including id, version, message, etc.
+ * @param client - Ema client for fetching personas
+ * @param persona - Resolved persona (pre-fetched)
+ * @param versionContext - Workspace and environment context
+ */
+export async function handleVersion(mode, args, client, persona, versionContext) {
+    const storage = createVersionStorage(versionContext.workspaceRoot);
+    const engine = createVersionPolicyEngine(storage);
+    switch (mode) {
+        // ─────────────────────────────────────────────────────────────────────────
+        // snapshot / version_create - Create a new version snapshot
+        // ─────────────────────────────────────────────────────────────────────────
+        case "snapshot":
+        case "version_create": {
+            // Fetch full persona with workflow
+            const fullPersona = await client.getPersonaById(persona.id);
+            if (!fullPersona) {
+                return { error: `Could not fetch full persona: ${persona.id}` };
+            }
+            const result = engine.forceCreateVersion(fullPersona, {
+                environment: versionContext.environment,
+                tenant_id: versionContext.tenant_id,
+                message: args.message,
+                created_by: "mcp-toolkit",
+            });
+            if (!result.created || !result.version) {
+                return { error: result.reason };
+            }
+            return {
+                success: true,
+                version: {
+                    id: result.version.id,
+                    version_number: result.version.version_number,
+                    version_name: result.version.version_name,
+                    content_hash: result.version.content_hash,
+                    created_at: result.version.created_at,
+                    message: result.version.message,
+                },
+                changes_from_parent: result.changes_from_parent,
+                versions_pruned: result.versions_pruned,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // history / version_list - List version history
+        // ─────────────────────────────────────────────────────────────────────────
+        case "history":
+        case "version_list": {
+            const versions = engine.listVersions(persona.id, {
+                limit: args.limit,
+            });
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                versions,
+                count: versions.length,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // version_get - Get a specific version
+        // ─────────────────────────────────────────────────────────────────────────
+        case "version_get": {
+            const versionId = args.version ?? "latest";
+            const version = engine.getVersion(persona.id, versionId);
+            if (!version) {
+                return { error: `Version not found: ${versionId}` };
+            }
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                version: {
+                    id: version.id,
+                    version_number: version.version_number,
+                    version_name: version.version_name,
+                    content_hash: version.content_hash,
+                    created_at: version.created_at,
+                    created_by: version.created_by,
+                    trigger: version.trigger,
+                    message: version.message,
+                    changes_summary: version.changes_summary,
+                },
+                snapshot: {
+                    display_name: version.snapshot.display_name,
+                    description: version.snapshot.description,
+                    workflow_id: version.snapshot.workflow_id,
+                    trigger_type: version.snapshot.trigger_type,
+                    embedding_enabled: version.snapshot.embedding_enabled,
+                    has_workflow: !!version.snapshot.workflow_definition,
+                    has_proto_config: !!version.snapshot.proto_config,
+                },
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // version_compare - Compare two versions
+        // ─────────────────────────────────────────────────────────────────────────
+        case "version_compare": {
+            const v1 = args.v1;
+            const v2 = args.v2;
+            if (!v1 || !v2) {
+                return { error: "v1 and v2 required for version_compare mode" };
+            }
+            const result = engine.compareVersions(persona.id, v1, v2);
+            if (!result.success) {
+                return { error: result.error };
+            }
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                comparison: {
+                    v1: result.diff?.v1,
+                    v2: result.diff?.v2,
+                    identical: result.diff?.identical,
+                    changed_fields: result.diff?.changed_fields,
+                    workflow_diff: result.diff?.workflow_diff,
+                },
+                summary: result.summary,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // restore / version_restore - Restore to a previous version
+        // ─────────────────────────────────────────────────────────────────────────
+        case "restore":
+        case "version_restore": {
+            const versionId = args.version;
+            if (!versionId) {
+                return { error: "version required for restore mode" };
+            }
+            const restoreData = engine.getRestoreData(persona.id, versionId);
+            if (!restoreData.success || !restoreData.restore_payload) {
+                return { error: restoreData.error ?? "Failed to get restore data" };
+            }
+            // Create a version snapshot before restoring (audit trail)
+            const fullPersona = await client.getPersonaById(persona.id);
+            if (fullPersona) {
+                engine.forceCreateVersion(fullPersona, {
+                    environment: versionContext.environment,
+                    tenant_id: versionContext.tenant_id,
+                    message: `Before restore to ${restoreData.version?.version_name}`,
+                    created_by: "mcp-toolkit",
+                });
+            }
+            // Apply the restore
+            const payload = restoreData.restore_payload;
+            await client.updateAiEmployee({
+                persona_id: payload.persona_id,
+                name: payload.name,
+                description: payload.description,
+                proto_config: payload.proto_config,
+                workflow: payload.workflow ?? undefined,
+                welcome_messages: payload.welcome_messages ?? undefined,
+                embedding_enabled: payload.embedding_enabled ?? undefined,
+            });
+            // Create post-restore version
+            const restoredPersona = await client.getPersonaById(persona.id);
+            if (restoredPersona) {
+                engine.forceCreateVersion(restoredPersona, {
+                    environment: versionContext.environment,
+                    tenant_id: versionContext.tenant_id,
+                    message: `Restored to ${restoreData.version?.version_name}`,
+                    created_by: "mcp-toolkit",
+                });
+            }
+            return {
+                success: true,
+                persona_id: persona.id,
+                restored_to: {
+                    version_id: restoreData.version?.id,
+                    version_name: restoreData.version?.version_name,
+                    version_number: restoreData.version?.version_number,
+                },
+                message: `Persona restored to ${restoreData.version?.version_name}`,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // version_policy - Get or update version policy
+        // ─────────────────────────────────────────────────────────────────────────
+        case "version_policy": {
+            // Check if we're updating or just getting
+            const hasUpdates = args.auto_on_deploy !== undefined ||
+                args.auto_on_sync !== undefined ||
+                args.max_versions !== undefined;
+            if (hasUpdates) {
+                const updated = engine.updatePolicy(persona.id, {
+                    auto_version_on_deploy: args.auto_on_deploy,
+                    auto_version_on_sync: args.auto_on_sync,
+                    max_versions: args.max_versions,
+                });
+                return {
+                    success: true,
+                    persona_id: persona.id,
+                    persona_name: persona.name,
+                    policy: updated,
+                    message: "Policy updated",
+                };
+            }
+            // Just get current policy
+            const policy = engine.getPolicy(persona.id);
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                policy,
+            };
+        }
+        default:
+            return { error: `Unknown version mode: ${mode}` };
+    }
+}

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/template/index.js

@@ -2,10 +2,15 @@
  * Template Handler
  *
  * Provides workflow patterns, widget references, config templates, and qualifying questions.
+ *
+ * Config templates follow API-first pattern:
+ * 1. Try to get from API (getPersonaTemplates)
+ * 2. Fall back to generated templates from proto definitions
  */
-import { WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, VOICE_PERSONA_TEMPLATE, getWidgetsForPersonaType, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, } from "../../../sdk/knowledge.js";
+import { WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, getWidgetsForPersonaType, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, } from "../../../sdk/knowledge.js";
+import { getTemplateFallback, getTemplateFieldDocs } from "../../../sdk/generated/template-fallbacks.js";
 /**
- * Handle template tool requests
+ * Handle template tool requests (sync operations only)
  */
 export function handleTemplate(args) {
     // Get specific pattern
@@ -38,14 +43,6 @@ export function handleTemplate(args) {
         const widgets = getWidgetsForPersonaType(args.widgets);
         return { type: args.widgets, widgets };
     }
-    // Config template
-    if (args.config) {
-        if (args.config === "voice") {
-            return VOICE_PERSONA_TEMPLATE;
-        }
-        // Add chat/dashboard templates here
-        return { type: args.config, template: {} };
-    }
     // Qualifying questions
     if (args.questions) {
         let questions = QUALIFYING_QUESTIONS;
@@ -57,5 +54,73 @@ export function handleTemplate(args) {
         }
         return { questions, count: questions.length };
     }
+    // Config template - use async handler for API-first approach
+    if (args.config) {
+        // For sync handler, return fallback with note to use async version
+        const type = args.config;
+        const fallback = getTemplateFallback(type);
+        const docs = getTemplateFieldDocs(type);
+        if (fallback) {
+            return {
+                type,
+                template: fallback,
+                field_docs: docs,
+                _source: "fallback",
+                _note: "This is a generated fallback. For live templates, use handleTemplateAsync with client.",
+            };
+        }
+        return { error: `No template available for type: ${args.config}` };
+    }
     return { error: "Specify pattern, patterns=true, widgets, config, or questions=true" };
 }
+/**
+ * Handle template tool requests with API access (async).
+ * Uses API-first approach with generated fallback.
+ */
+export async function handleTemplateAsync(args, client) {
+    // Config template - API first with fallback
+    if (args.config) {
+        const type = args.config;
+        // Map type to API trigger_type
+        const triggerTypeMap = {
+            voice: "VOICEBOT_AI_EMPLOYEE",
+            chat: "CHATBOT",
+            dashboard: "DOCUMENT_TRIGGER",
+        };
+        const targetTriggerType = triggerTypeMap[type];
+        try {
+            // Try API first
+            const templates = await client.getPersonaTemplates();
+            const template = templates.find(t => t.trigger_type === targetTriggerType ||
+                t.name?.toLowerCase().includes(type));
+            if (template?.proto_config) {
+                return {
+                    type,
+                    template: template.proto_config,
+                    template_id: template.id,
+                    template_name: template.name,
+                    _source: "api",
+                };
+            }
+        }
+        catch (err) {
+            // API failed, fall through to fallback
+            console.warn(`Failed to fetch templates from API: ${err}`);
+        }
+        // Fall back to generated template
+        const fallback = getTemplateFallback(type);
+        const docs = getTemplateFieldDocs(type);
+        if (fallback) {
+            return {
+                type,
+                template: fallback,
+                field_docs: docs,
+                _source: "fallback",
+                _note: "API templates unavailable, using generated fallback from proto definitions.",
+            };
+        }
+        return { error: `No template available for type: ${args.config}` };
+    }
+    // For non-config operations, use sync handler
+    return handleTemplate(args);
+}

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

@@ -0,0 +1,171 @@
+/**
+ * Workflow Analyze Handler
+ *
+ * Analyzes workflow structure, detects issues, and provides metrics.
+ *
+ * Features:
+ * - Issue detection (critical, warning, info)
+ * - Connection validation
+ * - Metrics calculation
+ * - Execution flow analysis (loops, dead code, multiple responders)
+ * - Auto-fix support
+ */
+import { detectWorkflowIssues, suggestWorkflowFixes, validateWorkflowConnections } from "../../../sdk/knowledge.js";
+import { autoFixWorkflow } from "../../../sdk/workflow-fixer.js";
+import { analyzeExecutionFlow, generateASCIIFlow } from "../../../sdk/workflow-execution-analyzer.js";
+/**
+ * Calculate workflow metrics
+ */
+function calculateMetrics(workflow) {
+    const actions = workflow.actions;
+    if (!actions)
+        return { node_count: 0, connection_count: 0 };
+    // Count connections
+    let connectionCount = 0;
+    for (const action of actions) {
+        const inputs = action.inputs;
+        if (inputs) {
+            connectionCount += Object.keys(inputs).length;
+        }
+    }
+    // Check for HITL
+    const hasHitl = actions.some(a => {
+        const name = a.name?.toLowerCase() ?? "";
+        return name.includes("hitl") || name.includes("human");
+    });
+    // Get trigger type
+    const trigger = workflow.trigger;
+    const triggerType = trigger?.trigger_type;
+    return {
+        node_count: actions.length,
+        connection_count: connectionCount,
+        has_hitl: hasHitl,
+        trigger_type: triggerType,
+    };
+}
+/**
+ * Handle workflow analyze mode
+ */
+export async function handleWorkflowAnalyze(args, client) {
+    const personaId = args.persona_id;
+    let workflow = args.workflow_def;
+    let persona = null;
+    // Get workflow from persona if not provided
+    if (personaId && !workflow) {
+        const fetchedPersona = await client.getPersonaById(personaId);
+        if (!fetchedPersona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        persona = fetchedPersona;
+        workflow = fetchedPersona.workflow_def;
+    }
+    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"];
+    const result = {
+        mode: "analyze",
+        persona_id: personaId,
+        persona_name: persona?.name,
+        environment: "demo",
+    };
+    // 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;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Workflow Compare Handler
+ *
+ * Compares two workflow versions to identify differences.
+ */
+/**
+ * Compare two workflows and return differences
+ */
+function compareWorkflows(workflow1, workflow2) {
+    const differences = [];
+    if (!workflow1 && !workflow2)
+        return differences;
+    if (!workflow1) {
+        differences.push({ type: "added", path: "workflow", new_value: "entire workflow" });
+        return differences;
+    }
+    if (!workflow2) {
+        differences.push({ type: "removed", path: "workflow", old_value: "entire workflow" });
+        return differences;
+    }
+    // Compare actions
+    const actions1 = workflow1.actions || [];
+    const actions2 = workflow2.actions || [];
+    const actionIds1 = new Set(actions1.map(a => (a.id ?? a.name)));
+    const actionIds2 = new Set(actions2.map(a => (a.id ?? a.name)));
+    // Find added/removed actions
+    for (const id of actionIds2) {
+        if (!actionIds1.has(id)) {
+            differences.push({ type: "added", path: `actions.${id}`, new_value: id });
+        }
+    }
+    for (const id of actionIds1) {
+        if (!actionIds2.has(id)) {
+            differences.push({ type: "removed", path: `actions.${id}`, old_value: id });
+        }
+    }
+    // Node count change
+    if (actions1.length !== actions2.length) {
+        differences.push({
+            type: "changed",
+            path: "actions.length",
+            old_value: actions1.length,
+            new_value: actions2.length,
+        });
+    }
+    return differences;
+}
+/**
+ * Handle workflow compare mode
+ */
+export async function handleWorkflowCompare(args, client) {
+    const personaId = args.persona_id;
+    const compareTo = args.compare_to;
+    if (!personaId || !compareTo) {
+        return { error: "persona_id and compare_to required for compare mode" };
+    }
+    const persona1 = await client.getPersonaById(personaId);
+    const persona2 = await client.getPersonaById(compareTo);
+    if (!persona1 || !persona2) {
+        return { error: "One or both personas not found" };
+    }
+    const workflow1 = persona1.workflow_def;
+    const workflow2 = persona2.workflow_def;
+    return {
+        mode: "compare",
+        persona_1: { id: persona1.id, name: persona1.name },
+        persona_2: { id: persona2.id, name: persona2.name },
+        differences: compareWorkflows(workflow1, workflow2),
+    };
+}