@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/dist/mcp/tools-consolidated.js

@@ -46,204 +46,244 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
             inputSchema: { type: "object", properties: {}, required: [] },
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 2. PERSONA - AI Employee management (CRUD + compare + versioning)
+        // 2. PERSONA - Unified AI Employee management (create, modify, analyze, list)
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "persona",
-            description: `Unified AI Employee (persona) management.
+            description: `Create, modify, analyze, or list AI Employees. ONE tool for everything.
 
-**Get single** (default when id provided):
-  persona(id="IT Support Bot")
+## ⚠️ ONE CALL CREATES EVERYTHING - THEN STOP
+
+If requirements are unclear, first call \`template(questions=true)\` to get what to ask.
+Then make ONE call with all gathered info:
+
+\`\`\`
+persona(
+  input="Voice AI SDR: qualifies leads, identifies use-case, sends follow-up email",
+  type="voice",
+  name="SP - SDR Test",  // REQUIRED: The actual persona name shown in Ema
+  preview=false
+)
+\`\`\`
+
+**After success, STOP. Do NOT make follow-up calls to "fix" or "enhance".**
+
+**MCP handles internally:** template selection, config generation, widget formatting, welcome message, API calls.
+
+## CRITICAL: The \`name\` Parameter
+
+The \`name\` parameter is the **actual persona name** in the Ema platform - NOT derived from input.
+
+  ❌ name omitted → MCP parses name from input (often wrong)
+  ✅ name="SP - SDR Test" → Exact name shown in platform
+
+## Create NEW AI Employee
+
+  persona(input="<what it should do>", type="voice", name="Actual Name", preview=false)
+
+## Modify EXISTING (workflow changes)
+
+  persona(id="abc-123", input="add HITL before email", preview=false)
+
+## Update Config Only (voice settings, welcome message)
+
+  persona(id="abc-123", input="Update welcome message to: Hello!", preview=false)
+
+MCP auto-detects config vs workflow changes.
+
+## Analyze/Get
+
+  persona(id="abc-123")
   persona(id="abc-123", include_workflow=true)
 
-**List/Search** (when --all or filters used):
+## Optimize (auto-fix issues)
+
+  persona(id="abc-123", optimize=true, preview=false)
+
+## List/Search
+
   persona(all=true)
   persona(query="support", status="active")
-  persona(trigger_type="voice")
 
-**Create**:
-  persona(mode="create", name="New Bot", type="voice")
+## Simple vs Complex Workflows
+
+**Simple** (Q&A, search + respond): Deploys directly → \`status: "success"\`
 
-**Update**:
-  persona(id="abc-123", mode="update", name="Renamed")
+**Complex** (email, HITL, multi-intent): Returns \`status: "needs_llm_generation"\` with:
+- \`llm_prompt\`: System + user prompts for workflow generation
+- \`available_actions\`: Action catalog from API
+- \`hint\`: How to complete deployment
 
-**Compare**:
-  persona(id="abc-123", mode="compare", compare_to="def-456")
+For complex workflows, send the prompt to an LLM and deploy:
+  \`persona(workflow_def=<llm_response>, ...)\`
 
-**Templates** (list available templates):
-  persona(templates=true)
+## Key Rules
 
-**Version Management** (track configuration history):
-  persona(id="abc-123", mode="version_create", message="Before major update")
-  persona(id="abc-123", mode="version_list")
-  persona(id="abc-123", mode="version_get", version="v3")
-  persona(id="abc-123", mode="version_compare", v1="v2", v2="v3")
-  persona(id="abc-123", mode="version_restore", version="v2")
-  persona(id="abc-123", mode="version_policy", auto_on_deploy=true)`,
+1. **ONE CALL** - Put everything in \`input\`, explicit \`name\`, MCP handles rest
+2. **STOP after success** - Don't make follow-up "fix" calls
+3. **preview=false** - Deploys to Ema platform`,
             inputSchema: withEnv({
-                // ID (or exact name) (optional - if omitted with all=true, lists all)
+                // === IDENTITY ===
                 id: {
                     type: "string",
-                    description: "Persona ID (UUID) or exact name. Omit for list operations."
+                    description: "Persona ID (UUID) or exact name. Omit when creating new."
                 },
-                // Deprecated alias (backwards compatibility)
                 identifier: {
                     type: "string",
                     deprecated: true,
-                    description: "DEPRECATED: use id. Persona ID (UUID) or exact name.",
+                    description: "DEPRECATED: use id.",
                 },
-                // Mode (defaults to "get" if id provided, "list" if all=true)
-                mode: {
+                // === CREATE/MODIFY (the main way to use this tool) ===
+                input: {
                     type: "string",
-                    enum: ["get", "list", "create", "update", "compare", "version_create", "version_list", "version_get", "version_compare", "version_restore", "version_policy"],
-                    description: "Operation mode. Default: 'get' with id, 'list' without."
+                    description: "Natural language description. For new: 'Voice AI for sales...'. For modify: 'add HITL before email'.",
                 },
-                // List/Search flags
+                type: {
+                    type: "string",
+                    enum: ["voice", "chat", "dashboard"],
+                    description: "AI Employee type. REQUIRED for creating new."
+                },
+                name: { type: "string", description: "REQUIRED for new: The actual persona name shown in Ema platform (e.g., 'SP - SDR Test'). Don't derive from input." },
+                description: { type: "string", description: "Description of what it does." },
+                preview: {
+                    type: "boolean",
+                    description: "Default: true (safe). Set false to deploy changes."
+                },
+                // === ANALYZE/OPTIMIZE ===
+                optimize: {
+                    type: "boolean",
+                    description: "Auto-fix detected issues. Use with id.",
+                },
+                include: {
+                    type: "array",
+                    items: { type: "string", enum: ["issues", "connections", "fixes", "metrics"] },
+                    description: "What to include in analysis output.",
+                },
+                include_workflow: { type: "boolean", description: "Include full workflow_def in response" },
+                include_fingerprint: { type: "boolean", description: "Include config hash" },
+                // === LIST/SEARCH ===
                 all: { type: "boolean", description: "List all personas" },
                 query: { type: "string", description: "Search by name (partial match)" },
                 status: { type: "string", description: "Filter: 'active', 'inactive', 'draft'" },
                 trigger_type: { type: "string", description: "Filter: 'voice', 'chat', 'dashboard'" },
                 limit: { type: "number", description: "Max results (default: 50)" },
-                // Get flags
-                include_workflow: { type: "boolean", description: "Include full workflow_def" },
-                include_fingerprint: { type: "boolean", description: "Include config hash" },
-                // Create flags
-                name: { type: "string", description: "Name (for create/update)" },
-                description: { type: "string", description: "Description (for create/update)" },
-                type: {
-                    type: "string",
-                    enum: ["voice", "chat", "dashboard"],
-                    description: "Persona type (for create)"
-                },
-                template_id: { type: "string", description: "Template ID (for create)" },
-                clone_from: { type: "string", description: "Clone from persona ID (for create)" },
-                clone_data: { type: "boolean", description: "Also clone knowledge base files when using clone_from (default: false)" },
-                // Update flags
-                enabled: { type: "boolean", description: "Enable/disable (for update)" },
+                // === COMPARE ===
+                compare_to: { type: "string", description: "Second persona ID for comparison" },
+                compare_env: { type: "string", description: "Environment of compare_to persona" },
+                // === ADVANCED/OVERRIDE ===
                 proto_config: {
                     type: "object",
-                    description: "Voice/chat settings (welcomeMessage, identityAndPurpose, etc.) for update"
+                    description: "Override voice/chat settings. Usually auto-generated from input."
                 },
-                // Compare flags
-                compare_to: { type: "string", description: "Second persona ID (for compare)" },
-                compare_env: { type: "string", description: "Environment of compare_to persona" },
-                // Templates flag
+                workflow: {
+                    type: "object",
+                    description: "Direct workflow JSON (advanced). Usually auto-generated."
+                },
+                workflow_def: {
+                    type: "object",
+                    description: "Alias for workflow (backwards compatibility)."
+                },
+                template_id: { type: "string", description: "Specific template ID (usually auto-selected)" },
+                clone_from: { type: "string", description: "Clone from existing persona ID" },
+                clone_data: { type: "boolean", description: "Also clone knowledge base files" },
+                enabled: { type: "boolean", description: "Enable/disable persona" },
+                // === TEMPLATES ===
                 templates: { type: "boolean", description: "List available templates" },
-                // Version management flags
-                version: { type: "string", description: "Version identifier (e.g., 'v3', 'latest', or UUID)" },
-                v1: { type: "string", description: "First version for comparison (version_compare mode)" },
-                v2: { type: "string", description: "Second version for comparison (version_compare mode)" },
-                message: { type: "string", description: "Version message/description (version_create mode)" },
-                auto_on_deploy: { type: "boolean", description: "Auto-create version on deploy (version_policy mode)" },
-                auto_on_sync: { type: "boolean", description: "Auto-create version on sync (version_policy mode)" },
-                max_versions: { type: "number", description: "Max versions to keep (version_policy mode)" },
+                // === VERSION MANAGEMENT ===
+                mode: {
+                    type: "string",
+                    enum: ["version_create", "version_list", "version_get", "version_compare", "version_restore", "version_policy"],
+                    description: "Version management mode. Only needed for version operations."
+                },
+                version: { type: "string", description: "Version identifier (e.g., 'v3', 'latest')" },
+                v1: { type: "string", description: "First version for comparison" },
+                v2: { type: "string", description: "Second version for comparison" },
+                message: { type: "string", description: "Version message/description" },
+                auto_on_deploy: { type: "boolean", description: "Auto-create version on deploy" },
+                auto_on_sync: { type: "boolean", description: "Auto-create version on sync" },
+                max_versions: { type: "number", description: "Max versions to keep" },
             }),
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 3. WORKFLOW - Unified workflow operations (greenfield & brownfield)
+        // 3. WORKFLOW - DEPRECATED: Use persona() instead
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "workflow",
-            description: `Unified workflow operations. Automatically detects greenfield vs brownfield.
-
-**Greenfield** (NEW workflow - no persona_id):
-  workflow(input="IT helpdesk with KB search")
-  workflow(input="customer support bot", preview=false)  # Generate AND deploy to new persona
-
-**Brownfield** (MODIFY existing - persona_id + input):
-  workflow(persona_id="abc", input="add HITL before email")
-  workflow(persona_id="abc", input="consolidate the 6 custom agents into one unified agent")
-  workflow(persona_id="abc", input="remove the orphan nodes")
-  workflow(persona_id="abc", input="replace the email LLM nodes with entity_extraction")
-  workflow(persona_id="abc", input="...", preview=false)  # Modify AND deploy
+            description: `⚠️ DEPRECATED: Use \`persona()\` instead. This tool routes to persona.
 
-**Analyze** (inspect - persona_id only, no input):
-  workflow(persona_id="abc-123")
-  workflow(persona_id="abc-123", include=["issues", "fixes"])
+## Migration Guide
 
-**Optimize** (auto-fix issues):
-  workflow(persona_id="abc", optimize=true)
-  workflow(persona_id="abc", optimize=true, preview=false)  # Fix AND deploy
+OLD (deprecated):
+  workflow(input="...", type="voice", name="Bot", preview=false)
+  workflow(persona_id="abc", input="add HITL")
 
-**Compare**:
-  workflow(persona_id="abc", compare_to="def")
+NEW (use this):
+  persona(input="...", type="voice", name="Bot", preview=false)
+  persona(id="abc", input="add HITL")
 
-**Generate extraction schema from metadata**:
-  workflow(mode="extraction_schema", metadata_file="/path/to/metadata.json")
-  workflow(mode="extraction_schema", metadata_json={...})
-
-## Key Concepts
-
-- **preview=true** (default): Returns result without deploying. Safe for exploration.
-- **preview=false**: Deploys the result.
-- **Mode is auto-detected**: No need to specify mode - just provide what you have.
-- **Complex changes supported**: Consolidate, remove, replace, rewire nodes.
-- **Dynamic schema generation**: Parse JSON metadata to generate extraction schemas automatically.`,
+The \`persona\` tool now handles everything: create, modify, analyze, list.
+This \`workflow\` tool still works but shows a deprecation warning.`,
             inputSchema: withEnv({
-                // Input - natural language description of what you want
+                // === REQUIRED for creating/modifying ===
                 input: {
-                    anyOf: [
-                        { type: "string", description: "Natural language description" },
-                        { type: "object", description: "Workflow intent/spec object" },
-                    ],
-                    description: "What you want: 'IT helpdesk bot' (greenfield) or 'consolidate agents into one' (brownfield with persona_id)",
+                    type: "string",
+                    description: "Natural language description of what you want. Examples: 'Voice AI for sales development' (new) or 'add HITL before emails' (modify existing)",
                 },
-                // Target persona (if provided = brownfield, if not = greenfield)
+                // === REQUIRED for modifying existing ===
                 persona_id: {
                     type: "string",
-                    description: "Existing persona to modify. If provided with input = brownfield modification."
+                    description: "ID of existing persona to modify or analyze. Omit for creating new personas."
                 },
-                // Preview vs Deploy (default: preview=true for safety)
+                // === REQUIRED for new Voice/Chat/Dashboard ===
+                type: {
+                    type: "string",
+                    enum: ["voice", "chat", "dashboard"],
+                    description: "REQUIRED for new personas. Type of AI Employee to create."
+                },
+                // === Control deployment ===
                 preview: {
                     type: "boolean",
-                    description: "Preview changes without deploying. Default: true. Set false to deploy."
+                    description: "Default: true (safe). Set false to deploy changes to Ema platform."
+                },
+                // === For new personas (greenfield with preview=false) ===
+                name: {
+                    type: "string",
+                    description: "Name for the new persona. Required when creating with preview=false."
+                },
+                description: {
+                    type: "string",
+                    description: "Description of what the persona does."
                 },
-                // Optimize flag - auto-fix detected issues
+                // === Voice/Chat settings (auto-generated, but can override) ===
+                proto_config: {
+                    type: "object",
+                    description: "Voice/chat settings. Auto-generated from input. Override specific settings like welcomeMessage, identityAndPurpose."
+                },
+                // === For analysis/optimization ===
                 optimize: {
                     type: "boolean",
-                    description: "Auto-fix detected issues in the workflow. Use with persona_id.",
+                    description: "Auto-fix detected issues. Use with persona_id.",
                 },
-                // Compare target
-                compare_to: { type: "string", description: "Second persona ID for comparison" },
-                // Analyze options
                 include: {
                     type: "array",
                     items: { type: "string", enum: ["issues", "connections", "fixes", "metrics"] },
-                    description: "What to include in analysis. Default: all.",
+                    description: "What to include in analysis output.",
                 },
-                // Persona type (for greenfield)
-                type: {
-                    type: "string",
-                    enum: ["voice", "chat", "dashboard"],
-                    description: "Persona type for new workflows (default: chat)"
-                },
-                // Direct workflow input (for analysis)
+                // === Advanced/Legacy ===
                 workflow_def: {
                     type: "object",
-                    description: "Workflow JSON for analysis (alternative to persona_id)"
+                    description: "Direct workflow JSON (advanced). Usually auto-generated from input."
                 },
-                // Proto config override
-                proto_config: { type: "object", description: "Persona config override (voice settings, etc.)" },
-                // Legacy mode support (for backwards compatibility)
+                compare_to: { type: "string", description: "Second persona ID for comparison" },
                 mode: {
                     type: "string",
                     enum: ["generate", "extend", "optimize", "analyze", "compare", "compile", "extraction_schema"],
-                    description: "DEPRECATED: Mode is auto-detected. Use explicitly for compile or extraction_schema mode."
-                },
-                // Extraction schema generation (dynamic, no hardcoding)
-                metadata_file: {
-                    type: "string",
-                    description: "Path to JSON metadata file for extraction schema generation"
+                    description: "Usually auto-detected. Only specify for extraction_schema or compile modes."
                 },
-                metadata_json: {
-                    type: "object",
-                    description: "JSON metadata object (alternative to metadata_file) - dynamically parsed to generate extraction fields"
-                },
-                // Compile mode inputs (explicit node spec)
-                name: { type: "string", description: "Workflow name (for compile mode)" },
-                description: { type: "string", description: "Workflow description (for compile mode)" },
-                nodes: { type: "array", description: "Node definitions (for compile mode)" },
-                result_mappings: { type: "array", description: "Output mappings (for compile mode)" },
+                metadata_file: { type: "string", description: "For extraction_schema mode: path to JSON metadata" },
+                metadata_json: { type: "object", description: "For extraction_schema mode: inline JSON metadata" },
+                nodes: { type: "array", description: "For compile mode: node definitions" },
+                result_mappings: { type: "array", description: "For compile mode: output mappings" },
             }),
         },
         // ═══════════════════════════════════════════════════════════════════════
@@ -301,23 +341,24 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "template",
-            description: `Get workflow patterns, widget references, and configuration templates.
+            description: `Get qualifying questions and reference patterns.
+
+## 🎯 PRIMARY USE: Get Questions to Ask User
 
-**Workflow patterns**:
-  template(pattern="intent-routing")
-  template(patterns=true)
-  template(patterns=true, type="voice")
+**Before creating an AI Employee, call this to get what to ask:**
+  template(questions=true)                    // All qualifying questions
+  template(questions=true, category="Voice")  // Voice-specific questions
 
-**Widget reference**:
-  template(widgets="voice")
-  template(widgets="chat")
+Returns structured questions about: type, intents, data sources, actions, approvals, etc.
+Ask the user these questions, then put answers into ONE workflow() call.
 
-**Persona config template**:
-  template(config="voice")  # Voice AI settings template
+## Reference (understand options, not for manual building)
 
-**Qualifying questions** (for requirements gathering):
-  template(questions=true)
-  template(questions=true, category="Voice")`,
+  template(pattern="intent-routing")  // See pattern structure
+  template(patterns=true)             // List available patterns
+  template(widgets="voice")           // Widget reference
+
+⚠️ Do NOT copy/paste configs from these - MCP generates them internally.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -536,7 +577,17 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "demo",
-            description: `Manage demo data for RAG knowledge bases.
+            description: `Manage demo data and generate demo kits for reliable demonstrations.
+
+**Generate demo kit** (complete demo package for a persona):
+  demo(mode="kit", persona_id="...", scenario="sales-sdr")
+  demo(mode="kit", persona_id="...", scenario="support-tier1", custom_qa=[{q:"...", a:"..."}])
+
+**Validate demo readiness**:
+  demo(mode="validate_kit", persona_id="...")
+
+**List available scenarios**:
+  demo(mode="scenarios")
 
 **Consolidate** (join JSON → Markdown):
   demo(mode="consolidate", source="./data", output="./kb", entity="customer", primary="customers.json")
@@ -547,16 +598,27 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
 **Validate document**:
   demo(mode="validate", file="./kb/customer-acme.md")
 
-**Get template**:
+**Get entity template**:
   demo(mode="template", entity="customer")`,
             inputSchema: {
                 type: "object",
                 properties: {
                     mode: {
                         type: "string",
-                        enum: ["consolidate", "generate", "validate", "template"],
+                        enum: ["kit", "validate_kit", "scenarios", "consolidate", "generate", "validate", "template"],
                         description: "Operation"
                     },
+                    // Kit generation flags
+                    persona_id: { type: "string", description: "Persona ID for kit generation" },
+                    scenario: {
+                        type: "string",
+                        enum: ["sales-sdr", "support-tier1", "hr-assistant"],
+                        description: "Demo scenario template"
+                    },
+                    custom_qa: {
+                        type: "array",
+                        description: "Custom Q&A pairs [{question, answer}]"
+                    },
                     // Consolidate flags
                     source: { type: "string", description: "Source directory" },
                     output: { type: "string", description: "Output directory" },
@@ -568,7 +630,7 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
                     // Entity type
                     entity: {
                         type: "string",
-                        enum: ["customer", "product", "employee", "scenario", "reference"],
+                        enum: ["customer", "product", "employee", "faq", "policy", "benefit", "company"],
                         description: "Entity type"
                     },
                     // Generate flags

package/dist/sdk/action-registry.js

@@ -0,0 +1,128 @@
+/**
+ * Action Registry - Helpers for extracting action metadata from API
+ *
+ * Uses existing client.listActions() - no duplicate caching needed.
+ * Just provides helpers to extract version/namespace from raw API response.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers to extract version/namespace from raw API response
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract action name, version, and namespaces from raw API response.
+ */
+export function parseActionDefinition(action) {
+    // API returns typeName.name.namespaces and typeName.version
+    const raw = action;
+    const typeName = raw.typeName;
+    if (!typeName?.name?.name)
+        return null;
+    return {
+        name: typeName.name.name,
+        version: typeName.version ?? "v0",
+        namespaces: typeName.name.namespaces ?? ["actions", "emainternal"],
+    };
+}
+/**
+ * Extract template info from raw API response.
+ */
+export function parseTemplateDefinition(template) {
+    if (!template.id || !template.name)
+        return null;
+    const raw = template;
+    return {
+        id: template.id,
+        name: template.name,
+        triggerType: raw.trigger_type ?? 1,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry Class (lightweight, uses client directly)
+// ─────────────────────────────────────────────────────────────────────────────
+export class ActionRegistry {
+    actions = new Map();
+    templates = new Map();
+    templatesByType = new Map();
+    loaded = false;
+    /**
+     * Load from raw API data.
+     * Call client.listActions() and client.getPersonaTemplates() externally
+     * and pass the results here.
+     */
+    loadFromData(actions, templates) {
+        this.actions.clear();
+        this.templates.clear();
+        this.templatesByType.clear();
+        for (const action of actions) {
+            const def = parseActionDefinition(action);
+            if (def) {
+                this.actions.set(def.name, def);
+            }
+        }
+        for (const template of templates) {
+            const def = parseTemplateDefinition(template);
+            if (def) {
+                this.templates.set(def.id, def);
+                // First template of each trigger type wins
+                if (!this.templatesByType.has(def.triggerType)) {
+                    this.templatesByType.set(def.triggerType, def);
+                }
+            }
+        }
+        this.loaded = true;
+    }
+    /**
+     * Get action version. Falls back to "v0".
+     */
+    getVersion(actionName) {
+        return this.actions.get(actionName)?.version ?? "v0";
+    }
+    /**
+     * Get action namespaces. Falls back to ["actions", "emainternal"].
+     */
+    getNamespaces(actionName) {
+        return this.actions.get(actionName)?.namespaces ?? ["actions", "emainternal"];
+    }
+    /**
+     * Get action definition.
+     */
+    getAction(actionName) {
+        return this.actions.get(actionName);
+    }
+    /**
+     * Get template by ID.
+     */
+    getTemplate(id) {
+        return this.templates.get(id);
+    }
+    /**
+     * Get template for persona type.
+     * Trigger types: 1=CHAT, 2=DASHBOARD, 4=VOICE
+     */
+    getTemplateForType(type) {
+        const triggerTypes = {
+            voice: 4,
+            chat: 1,
+            dashboard: 2,
+        };
+        return this.templatesByType.get(triggerTypes[type]);
+    }
+    isLoaded() {
+        return this.loaded;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory function (loads from API)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create and load action registry from API.
+ * Uses client methods directly - no caching here (resources.ts handles that for MCP).
+ */
+export async function ensureActionRegistry(client) {
+    const registry = new ActionRegistry();
+    const [actions, templates] = await Promise.all([
+        client.listActions().catch(() => []),
+        client.getPersonaTemplates().catch(() => []),
+    ]);
+    registry.loadFromData(actions, templates);
+    return registry;
+}