@ema.co/mcp-toolkit 1.5.2 → 1.7.0

package/dist/mcp/tools-consolidated.js

@@ -42,142 +42,189 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "env",
-            description: "List available Ema environments. Shows which is default.",
+            description: "List available Ema environments and toolkit info. Returns environments (with default marker) and toolkit name/version.",
             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
 
-**Update**:
-  persona(id="abc-123", mode="update", name="Renamed")
+**Simple** (Q&A, search + respond): Deploys directly → \`status: "success"\`
 
-**Compare**:
-  persona(id="abc-123", mode="compare", compare_to="def-456")
+**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
 
-**Templates** (list available templates):
-  persona(templates=true)
+For complex workflows, send the prompt to an LLM and deploy:
+  \`persona(workflow_def=<llm_response>, ...)\`
 
-**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)`,
+## Key Rules
+
+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."
                 },
                 workflow: {
                     type: "object",
-                    description: "Workflow definition to set (for update)"
+                    description: "Direct workflow JSON (advanced). Usually auto-generated."
                 },
-                // 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_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 and dashboard rows (auto-enables persona for dashboard cloning)" },
+                sanitize: { type: "boolean", description: "Sanitize/obfuscate PII and sensitive data (for demo environments)" },
+                sanitize_examples: { type: "array", items: { type: "string" }, description: "Additional items to treat as sensitive (e.g., company names)" },
+                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: `Create, modify, analyze, or deploy AI Employee workflows.
-
-## Creating a NEW AI Employee (Greenfield)
-
-Creates persona from template, configures settings. Template provides valid workflow structure.
-
-  workflow(input="Voice AI for sales development", name="My Sales SDR", type="voice", preview=false)
-
-Returns: { deployed_to: { persona_id, created: true }, next_steps: [...] }
-
-To customize the workflow AFTER creation, use modify mode with the persona_id.
+            description: `⚠️ DEPRECATED: Use \`persona()\` instead. This tool routes to persona.
 
-## Modifying an EXISTING AI Employee (Brownfield)
+## Migration Guide
 
-Uses LLM-native workflow transformation. Fetches existing workflow, transforms it, deploys.
+OLD (deprecated):
+  workflow(input="...", type="voice", name="Bot", preview=false)
+  workflow(persona_id="abc", input="add HITL")
 
-  workflow(persona_id="abc-123", input="add HITL approval before sending emails")
-  workflow(persona_id="abc-123", input="add a new Sales intent category", preview=false)
+NEW (use this):
+  persona(input="...", type="voice", name="Bot", preview=false)
+  persona(id="abc", input="add HITL")
 
-## Analyzing a Workflow
-
-  workflow(persona_id="abc-123")  # Returns issues, connections, metrics
-  workflow(persona_id="abc-123", optimize=true, preview=false)  # Auto-fix and deploy
-
-## Key Rules
-
-1. **preview=true (default)**: Safe - returns result without deploying
-2. **preview=false**: Deploys changes to Ema platform  
-3. **Greenfield creates from template** - then modify workflow separately if needed
-4. **Brownfield transforms existing** - uses decompile → transform → compile`,
+The \`persona\` tool now handles everything: create, modify, analyze, list.
+This \`workflow\` tool still works but shows a deprecation warning.`,
             inputSchema: withEnv({
                 // === REQUIRED for creating/modifying ===
                 input: {
@@ -296,23 +343,24 @@ Uses LLM-native workflow transformation. Fetches existing workflow, transforms i
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "template",
-            description: `Get workflow patterns, widget references, and configuration templates.
+            description: `Get qualifying questions and reference patterns.
 
-**Workflow patterns**:
-  template(pattern="intent-routing")
-  template(patterns=true)
-  template(patterns=true, type="voice")
+## 🎯 PRIMARY USE: Get Questions to Ask User
 
-**Widget reference**:
-  template(widgets="voice")
-  template(widgets="chat")
+**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
 
-**Persona config template**:
-  template(config="voice")  # Voice AI settings template
+Returns structured questions about: type, intents, data sources, actions, approvals, etc.
+Ask the user these questions, then put answers into ONE workflow() call.
 
-**Qualifying questions** (for requirements gathering):
-  template(questions=true)
-  template(questions=true, category="Voice")`,
+## Reference (understand options, not for manual building)
+
+  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: {
@@ -381,12 +429,20 @@ Uses LLM-native workflow transformation. Fetches existing workflow, transforms i
 
 **Attach data source to workflow node**:
   knowledge(persona_id="abc", mode="attach", node_name="knowledge_search_1")
-  knowledge(persona_id="abc", mode="attach", node_name="knowledge_search_1", widget_name="fileUpload")`,
+  knowledge(persona_id="abc", mode="attach", node_name="knowledge_search_1", widget_name="fileUpload")
+
+**Dashboard rows** (for Dashboard personas):
+  knowledge(persona_id="abc", mode="dashboard_rows")
+  knowledge(persona_id="abc", mode="dashboard_rows", limit=10)
+
+**Clone dashboard data** (copy rows from source to target):
+  knowledge(persona_id="target", mode="dashboard_clone", source_persona_id="source")
+  knowledge(persona_id="target", mode="dashboard_clone", source_persona_id="source", sanitize=true)`,
             inputSchema: withEnv({
                 persona_id: { type: "string", description: "AI Employee ID (required)" },
                 mode: {
                     type: "string",
-                    enum: ["list", "aggregates", "upload", "delete", "status", "toggle", "attach"],
+                    enum: ["list", "aggregates", "upload", "delete", "status", "toggle", "attach", "dashboard_rows", "dashboard_clone"],
                     description: "Operation. Default: 'list'"
                 },
                 // List flags
@@ -402,6 +458,10 @@ Uses LLM-native workflow transformation. Fetches existing workflow, transforms i
                 enabled: { type: "boolean", description: "Enable/disable embedding" },
                 // Attach flags
                 node_name: { type: "string", description: "Workflow node name to attach data source to (e.g., 'knowledge_search_1')" },
+                // Dashboard clone flags
+                source_persona_id: { type: "string", description: "Source persona ID for dashboard clone" },
+                sanitize: { type: "boolean", description: "Sanitize/obfuscate data during clone" },
+                sanitize_examples: { type: "array", items: { type: "string" }, description: "Additional sensitive items to sanitize" },
             }, ["persona_id"]),
         },
         // ═══════════════════════════════════════════════════════════════════════

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;
+}