@ema.co/mcp-toolkit 2026.1.24 → 2026.1.26-3

package/dist/sdk/generated/template-fallbacks.js

@@ -0,0 +1,123 @@
+/**
+ * Auto-generated fallback templates from proto definitions.
+ *
+ * These are used ONLY when the API is unavailable.
+ * The API templates (getPersonaTemplates()) are the source of truth.
+ *
+ * Generated at: 2026-01-25T21:51:05.018Z
+ *
+ * DO NOT EDIT MANUALLY - regenerate with: npm run generate:templates
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Voice AI persona config template (fallback).
+ *
+ * Fields derived from proto definitions:
+ * - VoicebotConversationSettingsWidget
+ * - VoicebotVoiceSettingsWidget
+ * - VoicebotCallSettingsWidget
+ * - VoicebotVADSettingsWidget
+ * - VoicebotDataStorageSettingsWidget
+ */
+export const VOICE_TEMPLATE_FALLBACK = {
+    "conversationSettings": {
+        "name": "{AI Name}",
+        "welcomeMessage": "Hello, thank you for calling {Company}. This is {AI Name}. How can I help you today?",
+        "speechCharacteristics": "Keep tone friendly and concise. Use brief pauses between sentences.",
+        "identityAndPurpose": "You are {AI Name}, an AI assistant for {Company}. Your responsibilities: 1) {Task 1} 2) {Task 2}",
+        "hangupInstructions": "End the call when: The caller explicitly says goodbye, or confirms they have no more questions.",
+        "takeActionInstructions": "</Case 1>\\n{Action Name}\\n\\nTrigger When: {Condition}\\n\\nIntent for tool call: \"{Intent}\"\\n\\nRequired parameters: { \"{param}\": \"\" }\\n</Case 1>",
+        "systemPrompt": "Tool Calling Instructions: Always collect required parameters before calling tools. Confirm with caller before executing.",
+        "waitMessage": "One moment while I look that up for you...",
+        "formFillingInstructions": "When collecting information, ask one question at a time. Confirm values before proceeding.",
+        "transferCallInstructions": "Transfer when: The caller explicitly requests a human agent, or the issue is beyond AI capabilities."
+    },
+    "voiceSettings": {
+        "languageHints": [
+            "en-US"
+        ],
+        "voiceModel": "default"
+    },
+    "callSettings": {
+        "enableCallForwarding": false,
+        "callForwardingNumber": "",
+        "enableSpamCallPrevention": true,
+        "enableDisconnectCall": false
+    },
+    "vadSettings": {
+        "turnTimeout": 3,
+        "silenceEndCallTimeout": 30,
+        "maxConversationDuration": 600
+    },
+    "dataStorageSettings": {
+        "storeAudioRecording": true,
+        "storeTranscripts": true,
+        "storeAgentTranscript": true
+    }
+};
+/**
+ * Field documentation for LLM consumption.
+ * Use this when generating prompts about config structure.
+ */
+export const VOICE_TEMPLATE_FIELD_DOCS = `
+## Voice AI Persona Configuration Fields
+
+### Conversation Settings
+  - name: Name for the Voicebot Agent that will be spoken
+  - welcomeMessage: Message spoken when call connects
+  - speechCharacteristics: Instructions on how voicebot should speak
+  - identityAndPurpose: What the voicebot is for and tools it has access to
+  - hangupInstructions: When to end the call
+  - takeActionInstructions: Instructions on what actions takeAction can perform
+  - systemPrompt: Instructions on how to respond to user, handle tools
+  - waitMessage: Message when tool is taking time to execute
+  - formFillingInstructions: How to collect form data conversationally
+  - transferCallInstructions: When to transfer to human agent
+
+### Voice Settings
+  - languageHints: BCP47 language codes for speech recognition
+  - voiceModel: Voice model ID
+
+### Call Settings
+  - enableCallForwarding: Enable call forwarding
+  - callForwardingNumber: Number to forward calls to
+  - enableSpamCallPrevention: Enable spam call prevention
+  - enableDisconnectCall: Enable disconnect call
+
+### VAD Settings
+  - turnTimeout: Seconds to wait for caller to finish speaking
+  - silenceEndCallTimeout: Seconds of silence before ending call
+  - maxConversationDuration: Maximum call length in seconds
+
+### Data Storage Settings
+  - storeAudioRecording: Store audio recordings
+  - storeTranscripts: Store call transcripts
+  - storeAgentTranscript: Store agent transcript
+`;
+/**
+ * Get template fallback by type.
+ * Returns undefined if type is not supported.
+ */
+export function getTemplateFallback(type) {
+    switch (type) {
+        case "voice":
+            return { ...VOICE_TEMPLATE_FALLBACK };
+        case "chat":
+            // TODO: Generate from chat proto definitions
+            return undefined;
+        case "dashboard":
+            // TODO: Generate from dashboard proto definitions
+            return undefined;
+    }
+}
+/**
+ * Get field documentation by type.
+ */
+export function getTemplateFieldDocs(type) {
+    switch (type) {
+        case "voice":
+            return VOICE_TEMPLATE_FIELD_DOCS;
+        default:
+            return undefined;
+    }
+}

package/dist/sdk/guidance.js

@@ -82,8 +82,10 @@ await persona({ id: "abc", update: { workflow_spec: spec } }); // Then deploy`,
         do: "For content changes: 1) Get workflow with persona(include_workflow=true), " +
             "2) Edit the node's stringValue in the JSON, 3) Deploy with workflow(mode='deploy', workflow_def={...})",
         dont: "Use workflow(mode='modify') for content changes - it will silently return 0 changes.",
-        example: `// STRUCTURAL change (supported)
-workflow({ mode: "modify", persona_id: "abc", input: "Add HITL before email" })
+        example: `// STRUCTURAL change (supported via structured operations)
+persona({ mode: "modify", id: "abc", operations: [
+  { type: "insert", insert: { action_type: "hitl", insert_before: "send_email" }}
+]})
 
 // CONTENT change (requires manual edit)
 const p = await persona({ id: "abc", include_workflow: true });
@@ -92,8 +94,42 @@ const wf = p.workflow_def;
 wf.actions[2].inputs.data.stringValue = JSON.stringify(newData);
 await workflow({ mode: "deploy", persona_id: "abc", workflow_def: wf });`,
         antiExample: `// This will silently fail - content change via modify
-workflow({ mode: "modify", persona_id: "abc", input: "Change customer data to commission data" })`,
-        related: ["workflow-spec-not-def"],
+persona({ mode: "modify", id: "abc", operations: [...] })  // for content changes`,
+        related: ["workflow-spec-not-def", "llm-driven-modifications"],
+    },
+    {
+        id: "llm-driven-modifications",
+        level: "critical",
+        category: "workflow",
+        title: "LLM-Driven Workflow Modifications",
+        applies: "When modifying workflows structurally",
+        description: "The MCP does NOT parse natural language for modifications. YOU (the Agent/LLM) must build structured operations. " +
+            "Call persona(mode='modify') first to get workflow context, then build operations array.",
+        do: "1) Get context: persona(mode='modify', id='...') returns current_nodes, available_actions, example_operations. " +
+            "2) Build structured operations array. 3) Execute: persona(mode='modify', id='...', operations=[...])",
+        dont: "Pass natural language strings expecting MCP to parse them into operations.",
+        example: `// Step 1: Get context (returns current_nodes, available_actions, examples)
+const ctx = await persona({ mode: "modify", id: "abc" });
+
+// Step 2: YOU build structured operations based on user intent
+const operations = [
+  { 
+    type: "insert",
+    insert: { 
+      action_type: "hitl",
+      display_name: "Email Approval",
+      insert_before: "send_email_node",
+      add_runif_to_downstream: true
+    }
+  }
+];
+
+// Step 3: Execute
+await persona({ mode: "modify", id: "abc", operations });`,
+        antiExample: `// DON'T: Pass natural language expecting MCP to understand it
+await persona({ mode: "modify", id: "abc", input: "add approval before email" })
+// The MCP will NOT parse this - it returns context instead`,
+        related: ["workflow-modification-scope", "analyze-before-modify"],
     },
     // ─────────────────────────────────────────────────────────────────────────
     // Important: Should Follow
@@ -162,7 +198,7 @@ const details = await persona({ id: list.personas[0].id });`,
         example: `// Useful resources:
 // ema://catalog/agents-summary - Action catalog
 // ema://rules/anti-patterns - Common mistakes
-// ema://templates/voice-ai/config - Voice AI template
+// ema://catalog/persona-templates - Live API templates
 // ema://docs/usage-guide - Comprehensive guide`,
     },
     // ─────────────────────────────────────────────────────────────────────────
@@ -186,7 +222,7 @@ persona({ id: "abc", env: "prod" })  // production`,
 export const TOOL_GUIDANCE = {
     persona: {
         toolName: "persona",
-        quickTip: "Use analyze=true before modifying. Use preview=true before deploying.",
+        quickTip: "Use analyze=true before modifying. Use preview=true before deploying. Build structured operations for modify.",
         operations: [
             {
                 name: "List all",
@@ -204,9 +240,14 @@ export const TOOL_GUIDANCE = {
                 example: 'persona(id="abc", analyze=true)',
             },
             {
-                name: "Update",
-                description: "Modify workflow using workflow_spec",
-                example: 'persona(id="abc", update={workflow_spec: {...}})',
+                name: "Get modify context",
+                description: "Get current_nodes, available_actions for building operations",
+                example: 'persona(mode="modify", id="abc")',
+            },
+            {
+                name: "Execute modify",
+                description: "Apply structured operations (insert/remove/rewire)",
+                example: 'persona(mode="modify", id="abc", operations=[...])',
             },
             {
                 name: "Create",
@@ -218,11 +259,13 @@ export const TOOL_GUIDANCE = {
             list: "Get details: persona(id='<id>')",
             get: "Analyze: persona(id='...', analyze=true)",
             analyze: "Review issues, build workflow_spec, then update",
-            update: "Verify: persona(id='...') to confirm changes",
+            modify_context: "Build operations array, then execute with operations=[...]",
+            modify_execute: "Verify: persona(id='...') to confirm changes",
             create: "Configure: persona(id='<new_id>', update={...})",
         },
         commonMistakes: [
-            "Modifying without analyzing first",
+            "Passing natural language to modify mode (MCP doesn't parse NL)",
+            "Modifying without getting context first",
             "Deploying without preview",
             "Using raw workflow_def instead of workflow_spec",
             "Forgetting Fallback in categorizers",
@@ -231,6 +274,7 @@ export const TOOL_GUIDANCE = {
             "analyze-before-modify",
             "preview-before-deploy",
             "workflow-spec-not-def",
+            "llm-driven-modifications",
         ],
     },
     catalog: {
@@ -361,6 +405,16 @@ ${critical.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 ## Important
 ${important.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 
+## LLM-Driven Architecture (CRITICAL)
+The MCP does NOT parse natural language for workflow modifications.
+**YOU (the Agent) must build structured operations:**
+
+1. Get context: \`persona(mode="modify", id="...")\` → returns current_nodes, available_actions
+2. Build operations array based on user intent
+3. Execute: \`persona(mode="modify", id="...", operations=[...])\`
+
+Example operations: insert, remove, rewire, update_config
+
 ## Resources
 - \`ema://docs/usage-guide\` - Complete guide
 - \`ema://catalog/agents-summary\` - Action catalog

package/dist/sdk/index.js

@@ -22,7 +22,9 @@ export { StateStore } from "./state.js";
 // Auto Builder Knowledge Base
 export { 
 // Catalogs & References
-AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, 
+AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, 
+// VOICE_PERSONA_TEMPLATE removed - use getTemplateFallback("voice") from generated/template-fallbacks.ts
+PROJECT_TYPES, 
 // Helper Functions
 getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
 // Workflow Analysis Functions

package/dist/sdk/knowledge.js

@@ -920,90 +920,15 @@ export const QUALIFYING_QUESTIONS = [
     { category: "Guardrails", question: "Are there compliance requirements? (regulations, policies)", whyItMatters: "May need response_validator or compliance_document_analyzer", required: false },
 ];
 // ─────────────────────────────────────────────────────────────────────────────
-// Voice AI Templates
+// Voice AI Templates - REMOVED
+// ─────────────────────────────────────────────────────────────────────────────
+// VOICE_PERSONA_TEMPLATE has been removed.
+// Use the API-first approach instead:
+// 1. client.getPersonaTemplates() - source of truth from API
+// 2. getTemplateFallback("voice") from src/sdk/generated/template-fallbacks.ts
+// 
+// See: scripts/generate-templates.ts for how fallbacks are generated from protos.
 // ─────────────────────────────────────────────────────────────────────────────
-export const VOICE_PERSONA_TEMPLATE = {
-    welcomeMessage: "Hello, thank you for calling {Company}. This is {AI Name}. How can I help you today?",
-    identityAndPurpose: `You are {AI Name}, a Voice AI assistant for {Company}.
-
-Primary responsibility: {Main purpose}
-
-Your responsibilities:
-1. {Responsibility 1}
-2. {Responsibility 2}
-3. {Responsibility 3}
-
-Rules:
-- {Rule 1}
-- {Rule 2}
-- Always be professional and helpful
-- Never provide information you're not certain about`,
-    takeActionInstructions: `</Case 1>
-{Action 1 Name}
-
-Trigger When:
-{Condition that triggers this action}
-
-Intent for tool call: "{Tool Intent Name}"
-
-Required parameters:
-{ "{param1}": "", "{param2}": "" }
-</Case 1>
-
-</Case 2>
-{Action 2 Name}
-
-Trigger When:
-{Condition that triggers this action}
-
-Intent for tool call: "{Tool Intent Name}"
-
-Required parameters:
-{ "{param1}": "" }
-</Case 2>`,
-    hangupInstructions: `End the call when:
-- The caller explicitly says goodbye or asks to hang up
-- The caller confirms they have no more questions
-- {Additional hangup conditions}
-
-Before ending:
-- Confirm all issues are resolved
-- Offer any follow-up information
-- Thank the caller`,
-    transferCallInstructions: `Transfer the call when:
-- The caller explicitly requests a human agent
-- The issue is beyond AI capabilities
-- {Complex scenario requiring human}
-
-Before transferring:
-- Inform the caller you're transferring them
-- Summarize the issue for the human agent`,
-    speechCharacteristics: `**Conversational Style:**
-- Keep responses brief (2-3 sentences per turn)
-- Use warm, professional tone
-- Speak clearly at moderate pace
-
-**Natural Speech:**
-- Use brief pauses between sentences
-- Acknowledge with 'I understand', 'Of course', 'Certainly'
-- Avoid robotic language
-
-**TTS Pronunciation Rules:**
-- Spell out IDs: 'A-B-C-1-2-3'
-- Pause between numbers: 'Your code is... 1... 2... 3... 4'
-- {Domain-specific pronunciation rules}`,
-    systemPrompt: `Tool Calling Instructions:
-
-1. Always collect ALL required parameters before calling a tool
-2. Confirm parameter values with the caller before executing
-3. Wait for tool response before calling another tool
-4. NEVER mention tool names to the user
-5. NEVER guess parameter values - always ask
-6. Use plain language: "Let me look that up" not "Calling the API"
-7. Handle delays with wait message: "One moment while I check..."
-8. Handle errors gracefully, offer alternatives`,
-    waitMessage: "One moment while I look that up for you...",
-};
 // ─────────────────────────────────────────────────────────────────────────────
 // Common Mistakes & Debugging
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2592,13 +2517,18 @@ function detectUnusedCategories(nodes, workflowDef) {
     const categorizers = nodes.filter(n => n.action_name === "chat_categorizer" ||
         n.action_name === "intent_classifier");
     for (const categorizer of categorizers) {
-        // Find the enumType for this categorizer
-        const enumTypeName = categorizer.id + "_enumType";
+        // Find the enumType for this categorizer using typeArguments reference (robust)
+        // The action's typeArguments.categories.enumType points to the correct enumType
+        const categorizerAction = actions.find(a => a.name === categorizer.id);
+        const typeArgs = categorizerAction?.typeArguments;
+        const enumTypeRefName = typeArgs?.categories?.enumType?.name?.name;
         const enumType = enumTypes.find(e => {
             const name = e.name;
             const innerName = name?.name;
             const nameStr = String(innerName?.name ?? name?.name ?? "");
-            return nameStr.includes(categorizer.id) || nameStr.includes("enumType");
+            // Match by typeArguments reference (preferred) or by categorizer ID (fallback)
+            // DO NOT use generic "enumType" fallback - that causes cross-categorizer pollution
+            return (enumTypeRefName && nameStr === enumTypeRefName) || nameStr.includes(categorizer.id);
         });
         if (!enumType)
             continue;

package/dist/sdk/workflow-intent.js

@@ -528,7 +528,25 @@ const PERSONA_TYPE_PATTERNS = [
     { pattern: /voice|call|phone/i, type: "voice" },
     { pattern: /document|batch|upload/i, type: "dashboard" },
 ];
+/**
+ * @deprecated Use LLM-based intent extraction instead of regex parsing.
+ *
+ * This function uses regex patterns to parse natural language, which is an
+ * anti-pattern. The LLM (Agent) should understand user intent naturally
+ * and provide structured data directly.
+ *
+ * For greenfield workflow generation, consider using:
+ * - Intent Architect for complex requirements analysis
+ * - Direct structured input (WorkflowSpec) from the Agent
+ *
+ * This function is retained for backward compatibility but should not be
+ * used in new code paths.
+ *
+ * @see src/mcp/AGENTS.md for the LLM-driven architecture guidelines
+ */
 export function parseNaturalLanguage(text) {
+    console.warn("[DEPRECATED] parseNaturalLanguage() uses regex parsing which is an anti-pattern. " +
+        "Consider using LLM-based intent extraction or structured input instead.");
     // Detect persona type (default: chat)
     let personaType = "chat";
     for (const { pattern, type } of PERSONA_TYPE_PATTERNS) {
@@ -1457,11 +1475,20 @@ export function intentToSpec(intent) {
         ...(intent.persona_type === "chat" && { chatConfig: { name: intent.name } }),
     };
 }
+/**
+ * Parse input and extract workflow intent.
+ *
+ * Note: The "natural_language" path uses deprecated regex-based parsing.
+ * For new code, prefer providing structured input (partial_spec or full_spec)
+ * directly from the Agent, which understands user intent naturally.
+ */
 export function parseInput(input) {
     const inputType = detectInputType(input);
     let intent;
     switch (inputType) {
         case "natural_language":
+            // DEPRECATED: This path uses regex-based parsing.
+            // Prefer structured input from the Agent instead.
             intent = parseNaturalLanguage(String(input));
             break;
         case "partial_spec":