@ema.co/mcp-toolkit 1.5.1 → 1.5.2

package/dist/sdk/workflow-generator.js

@@ -18,18 +18,38 @@ const ACTION_NAMESPACES = {
     document_trigger: ["triggers", "emainternal"],
     chat_categorizer: ["routing", "emainternal"],
     text_categorizer: ["routing", "emainternal"],
-    search: ["search", "emainternal"],
-    live_web_search: ["search", "emainternal"],
-    respond_with_sources: ["generation", "emainternal"],
-    call_llm: ["generation", "emainternal"],
-    fixed_response: ["generation", "emainternal"],
-    external_action_caller: ["external", "emainternal"],
-    general_hitl: ["collaboration", "emainternal"],
-    send_email_agent: ["external", "emainternal"],
-    conversation_to_search_query: ["search", "emainternal"],
-    entity_extraction: ["entity", "emainternal"],
-    combine_search_results: ["search", "emainternal"],
-    response_validator: ["validation", "emainternal"],
+    search: ["actions", "emainternal"], // Must be "actions" not "search"
+    live_web_search: ["actions", "emainternal"],
+    respond_with_sources: ["actions", "emainternal"], // Must be "actions" not "generation"
+    call_llm: ["actions", "emainternal"],
+    fixed_response: ["actions", "emainternal"],
+    external_action_caller: ["actions", "emainternal"],
+    general_hitl: ["actions", "emainternal"],
+    send_email_agent: ["actions", "emainternal"],
+    conversation_to_search_query: ["actions", "emainternal"],
+    entity_extraction: ["actions", "emainternal"],
+    combine_search_results: ["actions", "emainternal"],
+    response_validator: ["actions", "emainternal"],
+};
+// Version mapping for actions
+const ACTION_VERSIONS = {
+    chat_trigger: "v1",
+    voice_trigger: "v1",
+    document_trigger: "v1",
+    chat_categorizer: "v1",
+    text_categorizer: "v1",
+    search: "v2",
+    live_web_search: "v1",
+    respond_with_sources: "v1",
+    call_llm: "v1",
+    fixed_response: "v1",
+    external_action_caller: "v1",
+    general_hitl: "v1",
+    send_email_agent: "v1",
+    conversation_to_search_query: "v1",
+    entity_extraction: "v1",
+    combine_search_results: "v1",
+    response_validator: "v1",
 };
 const OPERATOR_MAP = {
     eq: 1,
@@ -93,31 +113,42 @@ export function compileWorkflow(spec) {
         workflowName: {
             name: {
                 namespaces: ["ema", "workflows"],
-                name: spec.name.toLowerCase().replace(/\s+/g, "_"),
+                name: spec.name.toLowerCase().replace(/\s+/g, "_").slice(0, 50), // Limit name length
             },
         },
         actions,
+        enumTypes: validEnumTypes.length > 0 ? validEnumTypes : [], // Always include, even if empty
+        workflowInputs: {},
         results,
+        namedResults: {},
+        displayName: spec.name,
+        description: spec.description || "",
+        namedResultsEditable: false,
+        namedResultsEnabled: false,
     };
-    // Only add enumTypes if there are valid ones
-    if (validEnumTypes.length > 0) {
-        workflowDef.enumTypes = validEnumTypes;
-    }
     // Build proto_config
     const protoConfig = buildProtoConfig(spec);
     return { workflow_def: workflowDef, proto_config: protoConfig };
 }
 function buildAction(node, enumTypeName) {
-    const namespaces = ACTION_NAMESPACES[node.actionType] ?? ["custom", "emainternal"];
+    const namespaces = ACTION_NAMESPACES[node.actionType] ?? ["actions", "emainternal"];
+    const version = ACTION_VERSIONS[node.actionType] ?? "v1";
     const action = {
         // CRITICAL: Use "name" not "actionName" - this is the node identifier in the workflow
         name: node.id,
-        actionDisplayName: node.displayName,
-        actionDescription: node.description ?? "",
         action: {
             name: { namespaces, name: node.actionType },
+            version,
         },
         inputs: {},
+        displaySettings: {
+            displayName: node.displayName ?? "",
+            description: node.description ?? "",
+            coordinates: { x: 800, y: 200 }, // Default position
+            showConfig: 0,
+        },
+        typeArguments: {},
+        tools: [],
         disableHumanInteraction: node.disableHitl ?? false,
     };
     // Build inputs
@@ -219,17 +250,80 @@ function buildInputBinding(binding) {
 }
 function buildProtoConfig(spec) {
     const projectType = spec.personaType === "voice" ? 5 : spec.personaType === "chat" ? 4 : 2;
+    // Widget format expected by Ema API:
+    // { name: "widgetName", type: <type_id>, widgetName: { ...config... } }
+    // The config is stored under a key matching the widget's name
     const widgets = [
-        { widget_type_id: 6, widget_name: "fusionModel", widget_config: { selectedModels: ["gpt-4.1"] } },
-        { widget_type_id: 8, widget_name: "dataProtection", widget_config: { enabled: true } },
+        {
+            name: "fusionModel",
+            type: 6,
+            fusionModel: { selectedModels: ["gpt-4.1"] }
+        },
+        {
+            name: "dataProtection",
+            type: 8,
+            dataProtection: { enabled: true }
+        },
     ];
     if (spec.personaType === "voice") {
-        widgets.push({ widget_type_id: 38, widget_name: "voiceSettings", widget_config: { languageHints: ["en-US"], voiceModel: "default" } }, { widget_type_id: 39, widget_name: "conversationSettings", widget_config: {} }, { widget_type_id: 43, widget_name: "vadSettings", widget_config: { turnTimeout: 5, silenceEndCallTimeout: 30, maxConversationDuration: 300 } });
+        // Build voice settings from spec.voiceConfig with sensible defaults
+        const vc = spec.voiceConfig ?? {};
+        const defaultIdentity = `You are ${spec.name}. ${spec.description}`;
+        widgets.push({
+            name: "voiceSettings",
+            type: 38,
+            voiceSettings: {
+                languageHints: vc.languageHints ?? ["en-US"],
+                voiceModel: "default"
+            }
+        }, {
+            name: "conversationSettings",
+            type: 39,
+            conversationSettings: {
+                welcomeMessage: vc.welcomeMessage ?? `Hello, this is ${spec.name}. How can I help you today?`,
+                identityAndPurpose: vc.identityAndPurpose ?? defaultIdentity,
+                takeActionInstructions: vc.takeActionInstructions ?? "Take appropriate actions based on the user's request. Always confirm before making changes.",
+                hangupInstructions: vc.hangupInstructions ?? "End the call politely when the user's request is complete or they ask to hang up.",
+                transferCallInstructions: vc.transferInstructions ?? "",
+                speechCharacteristics: vc.speechCharacteristics ?? "Professional, friendly, and helpful",
+                systemPrompt: vc.systemPrompt ?? "",
+                waitMessage: vc.waitMessage ?? "One moment please while I look that up...",
+            }
+        }, {
+            name: "vadSettings",
+            type: 43,
+            vadSettings: {
+                turnTimeout: 5,
+                silenceEndCallTimeout: 30,
+                maxConversationDuration: 300
+            }
+        });
     }
     if (spec.personaType === "chat") {
-        widgets.push({ widget_type_id: 28, widget_name: "chatbotSdkConfig", widget_config: { name: spec.name, theme: { primaryColor: "#0066cc" }, allowedDomains: ["*"] } }, { widget_type_id: 33, widget_name: "feedbackMessage", widget_config: { message: { question: "Was this response helpful?" }, feedbackFrequency: "always" } });
+        // Build chat settings from spec.chatConfig with sensible defaults
+        const cc = spec.chatConfig ?? {};
+        widgets.push({
+            name: "chatbotSdkConfig",
+            type: 28,
+            chatbotSdkConfig: {
+                name: cc.name ?? spec.name,
+                theme: { primaryColor: cc.primaryColor ?? "#0066cc" },
+                allowedDomains: cc.allowedDomains ?? ["*"]
+            }
+        }, {
+            name: "feedbackMessage",
+            type: 33,
+            feedbackMessage: {
+                message: { question: cc.feedbackQuestion ?? "Was this response helpful?" },
+                feedbackFrequency: "always"
+            }
+        });
     }
-    widgets.push({ widget_type_id: 3, widget_name: "fileUpload", widget_config: { useChunking: true } });
+    widgets.push({
+        name: "fileUpload",
+        type: 3,
+        fileUpload: { useChunking: true }
+    });
     return {
         project_type: projectType,
         name: spec.name,

package/dist/sdk/workflow-intent.js

@@ -1433,12 +1433,21 @@ export function intentToSpec(intent) {
         nodeId: respondId,
         output: searchId ? "response_with_sources" : "response_with_sources",
     });
+    // Build voiceConfig from intent.voice_config
+    const voiceConfig = intent.persona_type === "voice" ? {
+        welcomeMessage: intent.voice_config?.welcome_message,
+        identityAndPurpose: intent.voice_config?.identity ?? intent.description,
+        hangupInstructions: intent.voice_config?.hangup_instructions,
+        // Additional fields can be extracted from intent description in the future
+    } : undefined;
     return {
         name: intent.name,
         description: intent.description,
         personaType: intent.persona_type,
         nodes,
         resultMappings,
+        ...(voiceConfig && { voiceConfig }),
+        ...(intent.persona_type === "chat" && { chatConfig: { name: intent.name } }),
     };
 }
 export function parseInput(input) {

package/docs/mcp-tools-guide.md

@@ -30,19 +30,29 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_workflow`).
 
 ### Create a new AI Employee (greenfield)
 
+**Architecture**: Creates persona from template, configures settings. Template provides valid workflow.
+
 1. **Requirements**: `template(questions=true)` (and `template(questions=true, category="Voice")` for voice)
 2. **Pick agents/pattern**: `action(suggest="<use case>")`
-3. **Get the pattern**: `template(pattern="<pattern>")`
-4. **Generate workflow** (preview by default):
+3. **Create and configure in one step**:
    ```typescript
-   workflow(input="<requirements>", type="chat|voice|dashboard")
+   workflow(
+     input="<description of what it does>",
+     name="My AI Employee",
+     type="voice|chat|dashboard",
+     preview=false
+   )
    ```
-5. **Create persona** (if needed): `persona(mode="create", name="...", type="chat|voice|dashboard")`
-6. **Deploy** (preview=false):
+   This creates the persona from template and configures proto_config (voice settings, welcome message, etc.)
+
+4. **Customize workflow** (if needed - AFTER creation):
    ```typescript
-   workflow(input="<requirements>", persona_id="<id>", preview=false)
+   workflow(persona_id="<id>", input="add search node before responding")
    ```
-7. **Review**: `workflow(mode="analyze", persona_id="...")`
+
+5. **Review**: `workflow(persona_id="<id>")` to analyze
+
+**Key insight**: Don't try to generate and deploy a custom workflow in greenfield. Create from template first, then modify.
 
 ### Extend an existing AI Employee (brownfield)
 
@@ -129,10 +139,11 @@ persona(id="My Bot", mode="version_policy", auto_on_deploy=true)
 
 All modification modes default to `preview=true` for safety. Use `preview=false` to deploy.
 
-- **Generate (greenfield)**: Create new workflow
+- **Create (greenfield)**: Create new persona from template with configured settings
   ```typescript
-  workflow(input="IT helpdesk with KB search")                    // Preview
-  workflow(input="...", persona_id="abc", preview=false)          // Generate AND deploy
+  workflow(input="IT helpdesk chatbot", name="IT Helper", type="chat", preview=false)
+  // Creates persona from template, configures proto_config
+  // Template workflow is preserved - customize later via modify
   ```
 
 - **Extend (brownfield)**: Modify existing workflow with natural language
@@ -299,12 +310,13 @@ The MCP automatically condenses long prompts via `condensePromptForAutobuilder()
 
 ## Workflow Generation Strategy
 
-| Approach | When to Use | Notes |
-|----------|-------------|-------|
-| **Local compilation** | Simple/medium workflows | `workflow(mode="compile", ...)` - reliable, fast |
-| **Auto Builder** | Complex/exploratory workflows | Requires concise prompts (<2500 chars) |
+| Scenario | Approach | How |
+|----------|----------|-----|
+| **New persona** (greenfield) | Create from template | `workflow(input="...", name="...", type="...", preview=false)` |
+| **Modify existing** (brownfield) | LLM-native transform | `workflow(persona_id="...", input="add X")` |
+| **Complex workflows** | Auto Builder | May time out with long prompts (>2500 chars) |
 
-Prefer local compilation for deterministic results. Use `use_autobuilder=false` flag when generating workflows.
+**DO NOT** try to compile custom workflows for new personas. The template provides a valid workflow structure - customize it after creation via brownfield/modify mode.
 
 ## Legacy tools (migration only)
 

package/docs/test-persona-creation.md

@@ -0,0 +1,196 @@
+# Persona Creation Test Guide
+
+This guide tests the workflow tool's ability to create and configure AI Employees (personas).
+
+## Architecture
+
+### Greenfield (New Personas)
+1. **Create** persona from template (provides valid workflow structure)
+2. **Fetch** the created persona (get template's structure)
+3. **Update** proto_config only (voice settings, welcome message, etc.)
+4. **Customize workflow later** via modify mode if needed
+
+### Brownfield (Existing Personas)
+1. **Fetch** existing persona and workflow
+2. **Decompile** workflow_def → WorkflowSpec (typed representation)
+3. **Transform** spec based on user intent (LLM-native)
+4. **Compile** back to workflow_def
+5. **Update** persona with transformed workflow
+
+## Prerequisites
+
+1. **Rebuild the code**: 
+   ```bash
+   cd /path/to/ema-mcp-toolkit
+   npm run build
+   ```
+
+2. **Restart the MCP server** (Cursor caches code):
+   - `Cmd+Shift+P` → "Developer: Reload Window"
+
+3. Access to Ema dev environment
+
+---
+
+## Test Cases
+
+### Test 1: Create Voice AI Employee (Greenfield)
+
+**Goal:** Create a new Voice AI persona from template with configured settings.
+
+**Command:**
+```
+workflow(
+  input="Voice AI sales development representative for Ema. Handles discovery calls, qualifies prospects, explains value propositions.",
+  name="SP-TEST-VOICE-GREENFIELD",
+  type="voice",
+  preview=false,
+  env="dev"
+)
+```
+
+**Expected Result:**
+- `status: "deployed"`
+- `deployed_to.created: true`
+- `deployed_to.persona_id` returned
+- `next_steps` explains how to customize workflow
+
+**Verify:**
+```
+persona(id="<persona_id>", include_workflow=true, env="dev")
+```
+
+**Check:**
+- [ ] Persona exists with correct name
+- [ ] `proto_config.widgets` contains `conversationSettings` with:
+  - [ ] `welcomeMessage` - generated greeting
+  - [ ] `identityAndPurpose` - from description
+- [ ] `workflow_def` has template workflow (trigger node + possibly more from template)
+
+---
+
+### Test 2: Create Chat AI Employee (Greenfield)
+
+**Command:**
+```
+workflow(
+  input="IT helpdesk chatbot that answers employee questions about password resets, VPN setup, and software installation.",
+  name="SP-TEST-CHAT-GREENFIELD",
+  type="chat",
+  preview=false,
+  env="dev"
+)
+```
+
+**Expected Result:**
+- `status: "deployed"`
+- `deployed_to.created: true`
+
+**Verify:**
+```
+persona(id="<persona_id>", include_workflow=true, env="dev")
+```
+
+---
+
+### Test 3: Modify Existing Workflow (Brownfield)
+
+**Prerequisites:** Create a persona first (Test 1 or 2).
+
+**Goal:** Add functionality to an existing persona's workflow.
+
+**Command:**
+```
+workflow(
+  persona_id="<persona_id_from_test_1>",
+  input="add a search node that queries the knowledge base before responding",
+  preview=true,
+  env="dev"
+)
+```
+
+**Expected Result:**
+- `mode: "modify"`
+- Shows proposed changes
+- `modified_workflow` with new nodes
+
+**Deploy the changes:**
+```
+workflow(
+  persona_id="<persona_id>",
+  input="add a search node that queries the knowledge base before responding",
+  preview=false,
+  env="dev"
+)
+```
+
+---
+
+### Test 4: Analyze Workflow
+
+**Command:**
+```
+workflow(persona_id="<persona_id>", env="dev")
+```
+
+**Expected Result:**
+- `mode: "analyze"`
+- `issues` array (may be empty if healthy)
+- `metrics` with node_count, edge_count
+
+---
+
+### Test 5: Preview Only (No Deploy)
+
+**Goal:** Verify preview mode returns workflow without deploying.
+
+**Command:**
+```
+workflow(
+  input="Customer support voice AI that handles billing inquiries",
+  type="voice"
+)
+```
+
+**Expected Result:**
+- `status: "preview"`
+- `workflow_def` returned
+- `proto_config` with voice settings populated
+- NO persona created
+
+---
+
+## Cleanup
+
+After testing, delete test personas via the Ema UI or leave them for inspection.
+
+Test persona names:
+- SP-TEST-VOICE-GREENFIELD
+- SP-TEST-CHAT-GREENFIELD
+
+---
+
+## Troubleshooting
+
+### "Internal Server Error"
+- Usually means workflow format is wrong
+- Check if MCP server has latest code (restart Cursor)
+
+### "Widget name is empty"
+- Old code issue - restart MCP server
+
+### "Workflow name does not match"
+- Old code tried to replace workflow - now we don't touch workflow in greenfield
+
+### proto_config not updated
+- Check that greenfield flow only updates proto_config, not workflow
+- Widget merging should preserve template structure
+
+---
+
+## Key Code Locations
+
+- **Greenfield flow**: `src/mcp/handlers-consolidated.ts` (search for "GREENFIELD")
+- **Brownfield/modify flow**: `src/mcp/handlers-consolidated.ts` (search for "modify")
+- **Workflow transformer**: `src/sdk/workflow-transformer.ts` (decompile/compile)
+- **Proto config generation**: `src/sdk/workflow-generator.ts` (buildProtoConfig)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",

package/resources/templates/demo-scenarios/README.md

@@ -0,0 +1,63 @@
+# Demo Scenarios
+
+Pre-built demo data scenarios for reliable AI Employee demonstrations.
+
+## Available Scenarios
+
+| Scenario | Use Case | Persona Types |
+|----------|----------|---------------|
+| `sales-sdr` | Sales Development Representative | Voice, Chat |
+| `support-tier1` | Customer Support Tier 1 | Voice, Chat |
+| `hr-assistant` | HR Policy & Benefits Assistant | Chat, Voice |
+
+## Usage
+
+Generate a demo kit:
+
+```
+demo(mode="kit", persona_id="...", scenario="sales-sdr")
+```
+
+Validate demo readiness:
+
+```
+demo(mode="validate_kit", persona_id="...")
+```
+
+## What's Generated
+
+Each demo kit includes:
+
+1. **KB Documents** - Markdown files for the knowledge base with demo-ready data
+2. **Demo Script** - Questions to ask with expected answers
+3. **Fixed Response Fallbacks** - Workflow nodes for guaranteed responses
+4. **Validation Queries** - Test queries to verify before the demo
+
+## Customization
+
+Add custom Q&A pairs:
+
+```
+demo(mode="kit", persona_id="...", scenario="sales-sdr", custom_qa=[
+  {"question": "Tell me about feature X", "answer": "Feature X does..."}
+])
+```
+
+## Creating Custom Scenarios
+
+Create a JSON file in this directory with the following structure:
+
+```json
+{
+  "id": "my-scenario",
+  "name": "My Custom Scenario",
+  "description": "Description",
+  "persona_types": ["voice", "chat"],
+  "tags": ["tag1", "tag2"],
+  "intents": [...],
+  "entities": [...],
+  "qa_pairs": [...]
+}
+```
+
+See existing scenarios for complete examples.