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

package/README.md

@@ -221,9 +221,17 @@ environments:
 persona(input="IT helpdesk with KB search", type="chat", name="IT Support", preview=false)
 ```
 
-**Modify existing AI Employee:**
+**Modify existing AI Employee (LLM-Driven):**
 ```typescript
-persona(id="abc-123", input="add HITL before email, add compliance intent", preview=false)
+// Step 1: Get workflow context
+persona(mode="modify", id="abc-123")
+// Returns: current_nodes, available_actions, example_operations
+
+// Step 2: Build and execute structured operations
+persona(mode="modify", id="abc-123", operations=[
+  { type: "insert", insert: { action_type: "hitl", insert_before: "send_email" }},
+  { type: "remove", remove: { nodes: ["unused_node"] }}
+], preview=true)
 ```
 
 **Fix issues automatically:**

package/dist/mcp/handlers/action/index.js

@@ -4,28 +4,13 @@
  * Provides action/agent lookup, filtering, and documentation.
  */
 import { AGENT_CATALOG, getAgentByName, suggestAgentsForUseCase, } from "../../../sdk/knowledge.js";
-// Deprecated param mappings for backwards compatibility
-const DEPRECATED_PARAMS = {
-    identifier: { newName: "id", message: "'identifier' is deprecated, use 'id' instead (will be removed in v2.0.0)" },
-};
-function checkDeprecatedParams(args) {
-    const warnings = [];
-    for (const [oldName, info] of Object.entries(DEPRECATED_PARAMS)) {
-        if (args[oldName] !== undefined) {
-            warnings.push(info.message);
-        }
-    }
-    return warnings;
-}
+import { handleDeprecatedParams } from "../deprecation.js";
 /**
  * Handle action tool requests - list, get, filter, and search actions
  */
 export async function handleAction(args, client) {
-    // Check for deprecated params and log warnings
-    const deprecationWarnings = checkDeprecatedParams(args);
-    for (const warning of deprecationWarnings) {
-        console.warn(`[action] Deprecation: ${warning}`);
-    }
+    // Check for deprecated params
+    handleDeprecatedParams(args, "action");
     const id = args.id;
     const identifier = args.identifier; // deprecated alias for 'id'
     const idOrName = id ?? identifier;

package/dist/mcp/handlers/data/index.js

@@ -1,48 +1,117 @@
 /**
  * Data Handler - Operations on persona data (knowledge base, dashboard rows)
  *
- * All operations require explicit `method` parameter:
+ * Supports both `method` (V2) and `mode` (legacy) parameters.
+ *
+ * Available methods:
  * - list: List data sources
  * - stats: Get file counts by status
+ * - templates: List/get generation templates
+ * - generate: Generate content via Document Generation API
+ * - get: Get file contents by ID
  * - copy: Copy data from another persona (with optional sanitization)
  * - replicate: Fast copy by S3 reference (no file transfer)
  * - upload: Upload data source (file path or LLM-generated content)
  * - delete: Delete data source
- * - search: Search knowledge base (via workflow)
+ * - embedding: Check/toggle embedding status (delegates to knowledge)
  * - refresh: Rerun workflow for existing dashboard rows
  * - regenerate: Modify document section with new query
  * - replace: Replace entire document content (full replacement, not partial)
+ * - sanitize: Sanitize data items for a persona
  *
- * Note: Embeddings enabled by default on upload - no toggle API
  * Note: Schema is now at persona level: persona(method="schema", id="...")
- * Note: Document delete not available in API - use replace with empty or regenerate
- * Note: For dashboard fixed inputs, use upload with row context (not replace)
  */
 import { errorResult } from "../types.js";
 // Import handlers
 import { handleDashboardClone } from "./dashboard-clone.js";
+// Import generation templates
+import { GENERATION_TEMPLATES, listGenerationTemplates, getGenerationTemplate } from "./templates.js";
 /**
  * Main data handler with method-based dispatch
+ *
+ * @param args - Handler arguments
+ * @param client - Ema API client
+ * @param readFile - Optional file reader function (for compatibility)
  */
-export async function handleData(args, client) {
+export async function handleData(args, client, readFile) {
     const personaId = args.persona_id;
-    if (!personaId) {
+    // Get method from data object or top-level (support both 'method' and 'mode')
+    const dataArgs = args.data;
+    const method = (dataArgs?.method ??
+        dataArgs?.mode ??
+        args.method ??
+        args.mode);
+    // Templates mode doesn't require persona_id
+    if (!personaId && method !== "templates") {
         return errorResult("Data operations require persona_id");
     }
-    // Get method from data object or top-level
-    const dataArgs = args.data;
-    const method = (dataArgs?.method ?? args.method);
+    // Mode inference when method is omitted
     if (!method) {
-        return {
-            error: "Data operations require explicit method parameter",
-            hint: "Valid methods: list, stats, copy, replicate, upload, delete, search, embed, refresh, regenerate, replace",
-        };
+        return inferMethodAndClarify(args, dataArgs);
     }
     switch (method) {
+        // ─────────────────────────────────────────────────────────────────────────
+        // Templates - list or get generation templates
+        // ─────────────────────────────────────────────────────────────────────────
+        case "templates": {
+            const templateName = (dataArgs?.template ?? dataArgs?.name ?? args.template);
+            if (templateName) {
+                const template = getGenerationTemplate(templateName);
+                if (!template) {
+                    return {
+                        error: `Template not found: ${templateName}`,
+                        available: Object.keys(GENERATION_TEMPLATES),
+                    };
+                }
+                return {
+                    method: "templates",
+                    name: templateName,
+                    ...template,
+                };
+            }
+            // List all templates
+            return {
+                method: "templates",
+                templates: listGenerationTemplates(),
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Generate - create new content via Document Generation API
+        // ─────────────────────────────────────────────────────────────────────────
+        case "generate": {
+            if (!personaId) {
+                return errorResult("persona_id is required for generate method");
+            }
+            return handleDataGenerate(personaId, dataArgs ?? args, client);
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Get - retrieve file contents by ID
+        // ─────────────────────────────────────────────────────────────────────────
+        case "get": {
+            if (!personaId) {
+                return errorResult("persona_id is required for get method");
+            }
+            const fileId = (dataArgs?.file_id ?? dataArgs?.id ?? args.file_id);
+            if (!fileId) {
+                return errorResult("data.get requires file_id parameter");
+            }
+            return handleDataGet(personaId, fileId, client);
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Embedding - check/toggle embedding status (delegates to knowledge)
+        // ─────────────────────────────────────────────────────────────────────────
+        case "embedding":
+        case "embed": {
+            if (!personaId) {
+                return errorResult("persona_id is required for embedding method");
+            }
+            const enabled = dataArgs?.enabled;
+            return handleDataEmbedding(personaId, enabled, client);
+        }
         case "list":
             return handleDataList(personaId, client);
         case "stats":
-            return handleDataStats(personaId, dataArgs?.widget_name, client);
+            return handleDataStats(personaId, (dataArgs?.widget_name ?? args.widget_name), client);
         case "copy": {
             const sourceId = (dataArgs?.from ?? args.source_persona_id);
             if (!sourceId) {
@@ -64,17 +133,23 @@ export async function handleData(args, client) {
         case "sanitize":
             return handleDataSanitize(personaId, dataArgs?.examples, dataArgs?.apply, client);
         case "replicate":
-            return handleDataReplicate(personaId, (dataArgs?.from ?? args.source_persona_id), dataArgs?.widget_mappings, dataArgs?.wait, client);
+            return handleDataReplicate(personaId, (dataArgs?.from ?? args.from ?? args.source_persona_id), (dataArgs?.widget_mappings ?? args.widget_mappings), (dataArgs?.wait ?? args.wait), client);
         case "upload": {
             // Upload file or LLM-generated content (dashboard rows)
-            const filePath = dataArgs?.path;
+            const filePath = (dataArgs?.path ?? dataArgs?.file ?? args.file);
             const items = dataArgs?.items;
             if (filePath) {
-                // File upload - need to read file first
+                // File upload - use provided readFile or fall back to fs
                 try {
-                    const fs = await import("fs/promises");
+                    let fileContent;
+                    if (readFile) {
+                        fileContent = await readFile(filePath);
+                    }
+                    else {
+                        const fs = await import("fs/promises");
+                        fileContent = await fs.readFile(filePath);
+                    }
                     const path = await import("path");
-                    const fileContent = await fs.readFile(filePath);
                     const filename = path.basename(filePath);
                     const result = await client.uploadDataSource(personaId, fileContent, filename);
                     return {
@@ -118,7 +193,7 @@ export async function handleData(args, client) {
         }
         case "delete": {
             // Delete data source file
-            const fileId = (dataArgs?.file_id ?? dataArgs?.id);
+            const fileId = (dataArgs?.file_id ?? dataArgs?.id ?? args.file_id);
             if (!fileId) {
                 return { error: "data.delete requires file_id or id parameter" };
             }
@@ -147,7 +222,6 @@ export async function handleData(args, client) {
                 hint: "Search is performed via the persona's workflow, not direct API",
             };
         }
-        // Note: Embeddings are enabled by default when uploading files - no toggle API
         case "refresh": {
             // Generic refresh - currently supports dashboard rows
             // Could extend to documents (re-generate), KB files (re-embed), etc.
@@ -233,7 +307,7 @@ export async function handleData(args, client) {
         default:
             return {
                 error: `Unknown data method: ${method}`,
-                hint: "Valid methods: list, stats, copy, replicate, upload, delete, search, embed, refresh, regenerate, replace",
+                hint: "Valid methods: list, stats, templates, generate, get, copy, replicate, upload, delete, embedding, refresh, regenerate, replace, sanitize",
             };
     }
 }
@@ -261,15 +335,24 @@ async function handleDataList(personaId, client) {
  */
 async function handleDataStats(personaId, widgetName, client) {
     try {
-        const stats = await client.getDataSourceAggregates(personaId, widgetName ?? "fileUpload");
+        // Pass widget_name to API if provided, otherwise let API return default
+        const stats = await client.getDataSourceAggregates(personaId, widgetName);
         return {
             method: "stats",
             persona_id: personaId,
-            ...stats,
+            widget_name: stats.widgetName ?? widgetName ?? "all",
+            total: stats.total,
+            pending: stats.pending,
+            success: stats.success,
+            failed: stats.failed,
+            _tip: "Use data(method='list') to see individual files",
         };
     }
     catch (error) {
-        return { error: `Failed to get data stats: ${error instanceof Error ? error.message : String(error)}` };
+        return {
+            error: `Failed to get data stats: ${error instanceof Error ? error.message : String(error)}`,
+            persona_id: personaId,
+        };
     }
 }
 /**
@@ -322,31 +405,110 @@ async function handleDataSanitize(personaId, examples, apply, client) {
 }
 /**
  * Fast replication by S3 reference (no file transfer)
+ *
+ * Behavior matches the monolith handleData mode=replicate:
+ * - Default: waits for replication to complete
+ * - Can skip waiting with wait=false
+ * - Validates widget_mappings format
  */
-async function handleDataReplicate(targetPersonaId, sourcePersonaId, widgetMappings, wait, client) {
+async function handleDataReplicate(targetPersonaId, sourcePersonaId, widgetMappingsRaw, wait, client) {
     if (!sourcePersonaId) {
-        return { error: "data.replicate requires 'from' parameter (source persona ID)" };
+        return {
+            error: "from is required for replicate mode (source persona ID)",
+            hint: "Use data(method='replicate', from='source-persona-id') to copy data by reference",
+        };
+    }
+    // Parse and validate widget mappings if provided
+    let widgetMappings;
+    if (widgetMappingsRaw !== undefined) {
+        // Validate that widget_mappings is an array
+        if (!Array.isArray(widgetMappingsRaw)) {
+            return {
+                error: "widget_mappings must be an array",
+                hint: "Use widget_mappings=[{source_widget: 'kb', target_widget: 'kb'}]",
+            };
+        }
+        // Validate each mapping has at least source_widget
+        try {
+            widgetMappings = widgetMappingsRaw.map((m, i) => {
+                if (typeof m !== "object" || m === null) {
+                    throw new Error(`widget_mappings[${i}] must be an object`);
+                }
+                const mapping = m;
+                const sourceWidget = mapping.source_widget ?? mapping.sourceWidget;
+                if (!sourceWidget || typeof sourceWidget !== "string") {
+                    throw new Error(`widget_mappings[${i}].source_widget is required`);
+                }
+                return {
+                    sourceWidget,
+                    targetWidget: mapping.target_widget ?? mapping.targetWidget,
+                };
+            });
+        }
+        catch (validationErr) {
+            return {
+                error: `Invalid widget_mappings: ${validationErr.message}`,
+                hint: "Each mapping must have source_widget (string). target_widget is optional.",
+            };
+        }
+    }
+    else {
+        // Default: replicate knowledge_base
+        widgetMappings = [{ sourceWidget: "knowledge_base" }];
     }
+    const shouldWait = wait !== false; // Default to true
     try {
-        // Default widget mappings if not provided
-        const mappings = widgetMappings?.map(m => ({
-            sourceWidget: m.source_widget,
-            targetWidget: m.target_widget ?? m.source_widget,
-        })) ?? [
-            { sourceWidget: "fileUpload", targetWidget: "fileUpload" },
-            { sourceWidget: "kb", targetWidget: "kb" },
-        ];
-        const result = await client.replicateData({ type: "persona", id: sourcePersonaId }, { type: "persona", id: targetPersonaId }, mappings);
+        // Call replicateData - copies S3 references, not actual files
+        const result = await client.replicateData({ type: "persona", id: sourcePersonaId }, { type: "persona", id: targetPersonaId }, widgetMappings);
+        // If wait=true (default), poll for completion
+        if (shouldWait && result.results.length > 0) {
+            const requestIds = result.results.map((r) => r.requestId).filter(Boolean);
+            const statuses = [];
+            for (const requestId of requestIds) {
+                try {
+                    const status = await client.waitForReplication(requestId, targetPersonaId, {
+                        timeoutMs: 60_000,
+                        pollIntervalMs: 1_000,
+                    });
+                    statuses.push({ requestId, status: status.status, failedReason: status.failedReason });
+                }
+                catch (pollErr) {
+                    statuses.push({ requestId, status: "timeout", failedReason: String(pollErr) });
+                }
+            }
+            const allCompleted = statuses.every(s => s.status === "completed");
+            const anyFailed = statuses.some(s => s.status === "failed");
+            return {
+                success: allCompleted,
+                source_persona_id: sourcePersonaId,
+                target_persona_id: targetPersonaId,
+                replication_results: result.results,
+                final_statuses: statuses,
+                message: allCompleted
+                    ? "Data replicated successfully (by reference, no files copied)"
+                    : anyFailed
+                        ? "Some replications failed"
+                        : "Replication completed with warnings",
+                _tip: "Replication copies S3 references - much faster than downloading and re-uploading files",
+            };
+        }
+        // If wait=false, return immediately with request IDs
         return {
-            method: "replicate",
+            success: true,
             source_persona_id: sourcePersonaId,
             target_persona_id: targetPersonaId,
-            ...result,
-            note: "Replication initiated. S3 references copied (no file transfer).",
+            replication_results: result.results,
+            message: "Replication initiated (async)",
+            _tip: "Use getReplicationStatus with request IDs to check progress",
         };
     }
     catch (error) {
-        return { error: `Failed to replicate data: ${error instanceof Error ? error.message : String(error)}` };
+        return {
+            error: `Replication failed: ${error.message}`,
+            source_persona_id: sourcePersonaId,
+            target_persona_id: targetPersonaId,
+            hint: "Ensure both personas exist and have compatible data structures",
+        };
     }
 }
 /**
@@ -367,6 +529,188 @@ async function handleDashboardRefresh(personaId, rowId, client) {
         return { error: `Failed to refresh dashboard row: ${error instanceof Error ? error.message : String(error)}` };
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Method inference and clarification when method is omitted
+// ─────────────────────────────────────────────────────────────────────────────
+function inferMethodAndClarify(args, dataArgs) {
+    // Try to infer from params if unambiguous
+    if ((args.file || dataArgs?.path) && !args.file_id && !dataArgs?.file_id) {
+        // Has file path but no file_id → likely wants upload
+        return {
+            status: "clarification_needed",
+            message: "What operation would you like to perform?",
+            inferred: "upload",
+            hint: "You provided a file path. Did you mean method='upload'?",
+            options: ["upload", "list", "generate", "embedding"],
+        };
+    }
+    if ((args.file_id || dataArgs?.file_id) && (args.input || dataArgs?.input)) {
+        // Has file_id and input → likely wants regenerate
+        return {
+            status: "clarification_needed",
+            message: "What operation would you like to perform?",
+            inferred: "regenerate",
+            hint: "You provided file_id and input. Did you mean method='regenerate'?",
+            options: ["regenerate", "replace", "delete", "get"],
+        };
+    }
+    if (args.input || dataArgs?.input || args.from || dataArgs?.from) {
+        // Has input or from → likely wants generate
+        return {
+            status: "clarification_needed",
+            message: "What operation would you like to perform?",
+            inferred: "generate",
+            hint: "You provided input/from. Did you mean method='generate'?",
+            options: ["generate", "list"],
+        };
+    }
+    if (args.template || dataArgs?.template) {
+        // Wants a specific template
+        return {
+            status: "clarification_needed",
+            message: "What operation would you like to perform?",
+            inferred: "templates",
+            hint: "You provided template name. Did you mean method='templates'?",
+            options: ["templates"],
+        };
+    }
+    // Default clarification
+    return {
+        status: "clarification_needed",
+        message: "What operation would you like to perform?",
+        options: ["list", "upload", "generate", "templates", "get", "delete", "copy", "replicate", "embedding", "sanitize", "refresh", "regenerate", "replace"],
+        hint: "Specify method='...' for direct execution. Example: data(persona_id='abc', method='list')",
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Generate - create new content via Document Generation API
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleDataGenerate(personaId, dataArgs, client) {
+    const from = dataArgs.from;
+    const input = dataArgs.input;
+    const count = dataArgs.count ?? 1;
+    const format = dataArgs.format ?? "markdown";
+    const data = dataArgs.data;
+    if (!from && !input) {
+        return {
+            error: "Either 'from' (template name) or 'input' (natural language) is required for generate method",
+            available_templates: Object.keys(GENERATION_TEMPLATES),
+        };
+    }
+    // Build instructions from template or input
+    let instructions;
+    if (from) {
+        const template = getGenerationTemplate(from);
+        if (!template) {
+            return {
+                error: `Template not found: ${from}`,
+                available: Object.keys(GENERATION_TEMPLATES),
+            };
+        }
+        // Build instructions from template
+        instructions = template.prompt
+            .replace("{count}", String(count))
+            .replace("{format}", format);
+        if (data) {
+            // Inject additional context
+            instructions += `\n\nAdditional context: ${JSON.stringify(data)}`;
+        }
+    }
+    else {
+        instructions = input;
+        if (count > 1) {
+            instructions = `Generate ${count} items: ${instructions}`;
+        }
+        instructions += `\n\nOutput format: ${format}`;
+    }
+    // Call Document Generation API
+    try {
+        const result = await client.generateDocument(personaId, instructions, {
+            timeoutMs: 120_000,
+            pollIntervalMs: 2_000,
+        });
+        return {
+            method: "generate",
+            persona_id: personaId,
+            template: from,
+            count,
+            format,
+            generated: result,
+            _tip: "Content generated via Document Generation API. Upload as data source if needed.",
+        };
+    }
+    catch (error) {
+        return { error: `Failed to generate content: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Get - retrieve file contents by ID
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleDataGet(personaId, fileId, client) {
+    try {
+        // Get file info first
+        const files = await client.listDataSourceFiles(personaId);
+        const file = files.files.find(f => f.id === fileId || f.filename === fileId);
+        if (!file) {
+            return {
+                error: `File not found: ${fileId}`,
+                hint: "Use data(method='list') to see available files",
+            };
+        }
+        // Note: Actual file content retrieval depends on file type and API capabilities
+        // For now, return file metadata
+        return {
+            method: "get",
+            persona_id: personaId,
+            file_id: fileId,
+            file: file,
+            note: "File metadata returned. Full content retrieval depends on file type.",
+        };
+    }
+    catch (error) {
+        return { error: `Failed to get file: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Embedding - check/toggle embedding status
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleDataEmbedding(personaId, enabled, client) {
+    try {
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        if (enabled !== undefined) {
+            // Toggle embedding
+            // IMPORTANT: The Ema API requires workflow to be sent along with proto_config
+            // for proto_config changes to persist
+            await client.updateAiEmployee({
+                persona_id: personaId,
+                embedding_enabled: enabled,
+                proto_config: persona.proto_config,
+                workflow: persona.workflow_def,
+            });
+            return {
+                method: "embedding",
+                persona_id: personaId,
+                enabled,
+                previous_enabled: persona.embedding_enabled,
+                success: true,
+            };
+        }
+        else {
+            // Get status
+            return {
+                method: "embedding",
+                persona_id: personaId,
+                embedding_enabled: persona.embedding_enabled,
+            };
+        }
+    }
+    catch (error) {
+        return { error: `Failed to manage embedding: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
 // Legacy exports for backwards compatibility
 export const DATA_MODE_HANDLERS = {
     dashboard_clone: handleDashboardClone,