@ema.co/mcp-toolkit 2026.1.26 → 2026.1.27-1

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

@@ -4,35 +4,30 @@
  * 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;
-    // Categories list
+    // Categories list - API-first with catalog fallback
     if (args.categories) {
+        try {
+            const actions = await client.listActions();
+            const apiCategories = [...new Set(actions.map(a => a.category).filter(Boolean))];
+            if (apiCategories.length > 0) {
+                return { categories: apiCategories, count: apiCategories.length, source: "api" };
+            }
+        }
+        catch {
+            // Fallback to catalog
+        }
         const categories = [...new Set(Object.values(AGENT_CATALOG).map(a => a.category))];
-        return { categories, count: categories.length };
+        return { categories, count: categories.length, source: "catalog" };
     }
     // Suggest for use case
     if (args.suggest) {
@@ -112,6 +107,7 @@ export async function handleAction(args, client) {
                     ...a,
                     documentation: a.name ? getAgentByName(a.name) : undefined,
                 })),
+                source: "api",
             };
         }
         return {
@@ -122,6 +118,7 @@ export async function handleAction(args, client) {
                 category: a.category,
                 enabled: a.enabled,
             })),
+            source: "api",
         };
     }
     catch (e) {

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

@@ -138,6 +138,8 @@ export async function handleData(args, client, readFile) {
             // Upload file or LLM-generated content (dashboard rows)
             const filePath = (dataArgs?.path ?? dataArgs?.file ?? args.file);
             const items = dataArgs?.items;
+            // Widget name for targeting specific upload widgets (especially for Document Generation personas)
+            const widgetName = (dataArgs?.widget_name ?? args.widget_name);
             if (filePath) {
                 // File upload - use provided readFile or fall back to fs
                 try {
@@ -151,11 +153,14 @@ export async function handleData(args, client, readFile) {
                     }
                     const path = await import("path");
                     const filename = path.basename(filePath);
-                    const result = await client.uploadDataSource(personaId, fileContent, filename);
+                    const result = await client.uploadDataSource(personaId, fileContent, filename, {
+                        widgetName: widgetName, // Pass through widget_name for doc gen personas
+                    });
                     return {
                         method: "upload",
                         persona_id: personaId,
                         path: filePath,
+                        widget_name: widgetName ?? "fileUpload",
                         ...result,
                     };
                 }
@@ -164,14 +169,74 @@ export async function handleData(args, client, readFile) {
                 }
             }
             else if (items && items.length > 0) {
-                // Dashboard row upload (LLM-generated content)
+                // Dashboard row upload (LLM-generated content or file attachments)
                 try {
                     const results = [];
+                    const path = await import("path");
+                    const fs = await import("fs/promises");
                     for (const item of items) {
-                        // Convert item to DashboardInput format (name + string_value)
-                        const inputs = Object.entries(item).map(([key, value]) => ({
-                            name: key,
-                            string_value: typeof value === "string" ? value : JSON.stringify(value),
+                        // Convert item to DashboardInput format
+                        // Supports: string_value, number_value, boolean_value, document_value
+                        const inputs = await Promise.all(Object.entries(item).map(async ([key, value]) => {
+                            // File attachment: { file: "/path/to/file.pdf" } or { file_path: "..." }
+                            if (typeof value === "object" && value !== null && ("file" in value || "file_path" in value)) {
+                                const filePath = value.file ?? value.file_path;
+                                if (typeof filePath === "string") {
+                                    let fileContent;
+                                    if (readFile) {
+                                        fileContent = await readFile(filePath);
+                                    }
+                                    else {
+                                        fileContent = await fs.readFile(filePath);
+                                    }
+                                    const filename = path.basename(filePath);
+                                    const ext = path.extname(filePath).toLowerCase();
+                                    const mimeTypes = {
+                                        ".pdf": "application/pdf",
+                                        ".json": "application/json",
+                                        ".txt": "text/plain",
+                                        ".csv": "text/csv",
+                                        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                                        ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                                    };
+                                    return {
+                                        name: key,
+                                        document_value: [{
+                                                name: filename,
+                                                contents: fileContent.toString("base64"),
+                                                is_base64_encoded: true,
+                                                mime_type: mimeTypes[ext] ?? "application/octet-stream",
+                                            }],
+                                    };
+                                }
+                            }
+                            // Inline document: { contents: "...", mime_type: "..." }
+                            if (typeof value === "object" && value !== null && "contents" in value) {
+                                const doc = value;
+                                return {
+                                    name: key,
+                                    document_value: [{
+                                            name: doc.name ?? `${key}.txt`,
+                                            contents: typeof doc.contents === "string" && doc.is_base64_encoded
+                                                ? doc.contents
+                                                : Buffer.from(String(doc.contents)).toString("base64"),
+                                            is_base64_encoded: true,
+                                            mime_type: doc.mime_type ?? "text/plain",
+                                        }],
+                                };
+                            }
+                            // Primitive values
+                            if (typeof value === "number") {
+                                return { name: key, number_value: value };
+                            }
+                            if (typeof value === "boolean") {
+                                return { name: key, boolean_value: value };
+                            }
+                            // Default: string value
+                            return {
+                                name: key,
+                                string_value: typeof value === "string" ? value : JSON.stringify(value),
+                            };
                         }));
                         const result = await client.uploadAndRunDashboardRow(personaId, inputs);
                         results.push(result);
@@ -181,6 +246,7 @@ export async function handleData(args, client, readFile) {
                         persona_id: personaId,
                         uploaded_rows: results.length,
                         row_ids: results.map(r => r.row_id),
+                        _tip: "Dashboard rows created with file attachments trigger workflow execution automatically",
                     };
                 }
                 catch (error) {

package/dist/mcp/handlers/deprecation.js

@@ -0,0 +1,50 @@
+/**
+ * Deprecation Tracking - Single Source of Truth
+ *
+ * Centralized deprecation warnings for parameter names.
+ * Used by all handlers to ensure consistent messaging.
+ */
+/**
+ * Deprecated parameter mappings
+ *
+ * Key: old parameter name
+ * Value: { newName, removeVersion }
+ */
+export const DEPRECATED_PARAMS = {
+    identifier: { newName: "id", removeVersion: "2.0.0" },
+    clone_from: { newName: "from", removeVersion: "2.0.0" },
+    template_id: { newName: "from", removeVersion: "2.0.0" },
+    clone_data: { newName: "include_data", removeVersion: "2.0.0" },
+};
+/**
+ * Check args for deprecated params and return warnings.
+ */
+export function checkDeprecatedParams(args) {
+    const warnings = [];
+    for (const [oldName, { newName, removeVersion }] of Object.entries(DEPRECATED_PARAMS)) {
+        if (args[oldName] !== undefined) {
+            warnings.push(`'${oldName}' is deprecated, use '${newName}' instead (will be removed in v${removeVersion})`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Add deprecation warnings to a result object.
+ */
+export function addDeprecationWarnings(result, warnings) {
+    if (warnings.length > 0) {
+        return { ...result, _deprecation_warnings: warnings };
+    }
+    return result;
+}
+/**
+ * Log and return deprecation warnings for an args object.
+ * Call this at the start of handlers that accept deprecated params.
+ */
+export function handleDeprecatedParams(args, context) {
+    const warnings = checkDeprecatedParams(args);
+    for (const warning of warnings) {
+        console.warn(`[${context}] Deprecation: ${warning}`);
+    }
+    return warnings;
+}

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

@@ -25,9 +25,9 @@ export async function handleEnv(_args, getEnvironments, toolkit) {
         getting_started: {
             workflow: [
                 "1. List personas: persona(method=\"list\")",
-                "2. Get details: persona(method=\"get\", id=\"...\")",
-                "3. Analyze before modifying: persona(method=\"get\", id=\"...\", analyze=true)",
-                "4. Preview before deploying: persona(method=\"update\", id=\"...\", preview=true, ...)",
+                "2. Get workflow data: workflow(mode=\"get\", persona_id=\"...\")",
+                "3. Analyze workflow: Fetch ema://rules/anti-patterns and check workflow_def against rules",
+                "4. Preview before deploying: workflow(mode=\"deploy\", persona_id=\"...\", workflow_def={...}, preview=true)",
             ],
             critical_rules: criticalRules,
             resources: [

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

@@ -1,247 +1,54 @@
 /**
- * Knowledge Handler
+ * Knowledge Handler - DEPRECATED
  *
- * Manages data sources (files, embeddings, dashboard rows) for personas.
- * Note: This is deprecated in favor of the 'data' tool.
+ * This handler is deprecated. Use the 'data' tool instead.
+ * All calls are routed to handleData with a deprecation warning.
  */
-import { hasExtractedDataHandler, getDataModeHandler, } from "../data/index.js";
+import { handleData } from "../data/index.js";
 /**
- * Handle knowledge tool requests - manage data sources for personas
+ * Mode mapping from knowledge tool to data tool
+ */
+const MODE_MAPPING = {
+    list: "list",
+    aggregates: "stats",
+    upload: "upload",
+    delete: "delete",
+    status: "embedding",
+    toggle: "embedding",
+    attach: "attach",
+    dashboard_rows: "dashboard_rows",
+    dashboard_clone: "copy",
+    dashboard_generate: "generate",
+};
+/**
+ * Handle knowledge tool requests
  *
- * @deprecated Use data() tool instead
+ * @deprecated Use data() tool instead. This handler routes to handleData.
  */
-export async function handleKnowledge(args, client, readFile, opts) {
-    const personaId = args.persona_id;
+export async function handleKnowledge(args, client, readFile) {
+    console.warn("[knowledge] DEPRECATED: Use data() tool instead");
     const mode = args.mode || "list";
-    const includeWarning = opts?.includeDeprecationWarning ?? true;
-    // Deprecation warning (added to response when called directly)
-    const deprecationWarning = includeWarning ? {
-        _deprecation: {
-            message: "The 'knowledge' tool is deprecated. Please use 'data' tool instead.",
-            migration: {
-                "knowledge(mode='list')": "data(mode='list')",
-                "knowledge(mode='upload')": "data(mode='upload')",
-                "knowledge(mode='delete')": "data(mode='delete')",
-                "knowledge(mode='status')": "data(mode='embedding')",
-                "knowledge(mode='toggle')": "data(mode='embedding', enabled=...)",
-            },
-        },
-    } : {};
-    // Helper to wrap result with deprecation warning
-    const withWarning = (result) => {
-        if (typeof result === 'object' && result !== null) {
-            return { ...deprecationWarning, ...result };
-        }
-        return result;
+    const mappedMode = MODE_MAPPING[mode] || mode;
+    // Route to data handler
+    const dataArgs = {
+        ...args,
+        mode: mappedMode,
     };
-    switch (mode) {
-        case "list": {
-            const page = args.page;
-            const limit = args.limit;
-            const widgetName = args.widget_name;
-            const result = await client.listDataSourceFiles(personaId, { page, limit, widgetName });
-            return withWarning({
-                persona_id: personaId,
-                widget_name: result.widgetName,
-                files: result.files,
-                count: result.files.length,
-                pagination: result.pagination,
-            });
-        }
-        case "aggregates": {
-            const widgetName = args.widget_name;
-            const agg = await client.getDataSourceAggregates(personaId, widgetName);
-            return withWarning({
-                persona_id: personaId,
-                widget_name: agg.widgetName,
-                total_files: agg.total,
-                by_status: {
-                    pending: agg.pending,
-                    success: agg.success,
-                    failed: agg.failed,
-                },
-            });
-        }
-        case "upload": {
-            const filePath = args.file;
-            if (!filePath) {
-                return withWarning({ error: "file path required for upload" });
-            }
-            const content = await readFile(filePath);
-            const filename = filePath.split("/").pop() || "file";
-            const result = await client.uploadDataSource(personaId, content, filename, { tags: args.tags });
-            return withWarning({ success: true, ...result });
-        }
-        case "delete": {
-            const fileId = args.file_id;
-            if (!fileId) {
-                return withWarning({ error: "file_id required for delete" });
-            }
-            const result = await client.deleteDataSource(personaId, fileId);
-            return withWarning(result);
-        }
-        case "status": {
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                return withWarning({ error: `Persona not found: ${personaId}` });
-            }
-            return withWarning({
-                persona_id: personaId,
-                embedding_enabled: persona.embedding_enabled,
-            });
-        }
-        case "toggle": {
-            if (args.enabled === undefined) {
-                return withWarning({ error: "enabled flag required for toggle" });
-            }
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                return withWarning({ error: `Persona not found: ${personaId}` });
-            }
-            // IMPORTANT: The Ema API requires workflow to be sent along with proto_config
-            // for proto_config changes to persist. This matches what the UI does.
-            await client.updateAiEmployee({
-                persona_id: personaId,
-                embedding_enabled: args.enabled,
-                proto_config: persona.proto_config,
-                workflow: persona.workflow_def,
-            });
-            return withWarning({
-                success: true,
-                persona_id: personaId,
-                embedding_enabled: args.enabled,
-            });
-        }
-        case "attach": {
-            // Attach a data source widget to a workflow node's datastore_configs input
-            const nodeName = args.node_name;
-            const widgetName = args.widget_name || "fileUpload";
-            if (!nodeName) {
-                return withWarning({ error: "node_name required (e.g., 'knowledge_search_1')" });
-            }
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                return withWarning({ error: `Persona not found: ${personaId}` });
-            }
-            const workflowDef = persona.workflow_def;
-            if (!workflowDef) {
-                return withWarning({ error: "Persona has no workflow_def" });
-            }
-            const actions = workflowDef.actions;
-            if (!actions) {
-                return withWarning({ error: "Workflow has no actions" });
-            }
-            // Find the target node
-            const nodeIndex = actions.findIndex(a => a.name === nodeName);
-            if (nodeIndex < 0) {
-                const availableNodes = actions.map(a => a.name).filter(Boolean);
-                return withWarning({
-                    error: `Node '${nodeName}' not found`,
-                    available_nodes: availableNodes,
-                });
-            }
-            const node = actions[nodeIndex];
-            const inputs = (node.inputs || {});
-            // Build the datastore_configs binding with multiBinding
-            const datastoreBinding = {
-                multiBinding: {
-                    elements: [
-                        {
-                            widgetConfig: { widgetName },
-                            autoDetectedBinding: false,
-                        },
-                    ],
-                },
-                autoDetectedBinding: false,
-            };
-            // Update the node's inputs
-            inputs.datastore_configs = datastoreBinding;
-            node.inputs = inputs;
-            actions[nodeIndex] = node;
-            workflowDef.actions = actions;
-            // Update the persona with the modified workflow
-            await client.updateAiEmployee({
-                persona_id: personaId,
-                proto_config: persona.proto_config,
-                workflow: workflowDef,
-            });
-            return withWarning({
-                success: true,
-                persona_id: personaId,
-                node_name: nodeName,
-                widget_name: widgetName,
-                message: `Data source '${widgetName}' attached to node '${nodeName}'`,
-            });
-        }
-        case "dashboard_rows": {
-            // Get rows from a dashboard persona
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                return withWarning({ error: `Persona not found: ${personaId}` });
-            }
-            const dashboardId = persona.workflow_dashboard_id;
-            if (!dashboardId) {
-                return withWarning({
-                    error: "This persona has no dashboard. Use dashboard_rows only for Dashboard-type AI Employees.",
-                    hint: "Check that the persona has trigger_type=DASHBOARD",
-                });
-            }
-            const limit = args.limit ?? 100;
-            const result = await client.getDashboardRows(dashboardId, personaId, { limit });
-            // Return schema and rows in a structured format
-            return withWarning({
-                persona_id: personaId,
-                dashboard_id: dashboardId,
-                dashboard_name: result.dashboardName,
-                total_rows: result.totalCount,
-                schema: {
-                    input_columns: result.schema.columns.filter(c => c.isInput),
-                    output_columns: result.schema.columns.filter(c => !c.isInput),
-                },
-                rows: result.rows.map(row => ({
-                    id: row.id,
-                    state: row.state,
-                    created_at: row.dashboardRowMetadata.createdAt,
-                    input_values: row.columnValues
-                        .filter(cv => result.schema.columns.find(c => c.columnId === cv.columnId)?.isInput)
-                        .map(cv => ({
-                        column: result.schema.columns.find(c => c.columnId === cv.columnId)?.name ?? cv.columnId,
-                        value: cv.value.stringValue ?? cv.value.documentCellValue?.documentValues?.[0]?.name ?? cv.value.arrayValue?.arrayValues?.[0]?.stringValue ?? "(complex)",
-                    })),
-                })),
-            });
-        }
-        case "dashboard_clone": {
-            // Delegated to extracted handler
-            if (hasExtractedDataHandler("dashboard_clone")) {
-                const handler = getDataModeHandler("dashboard_clone");
-                // Map args to extracted handler format
-                const cloneArgs = {
-                    id: personaId,
-                    clone_dashboard_from: args.source_persona_id,
-                    clone_limit: args.limit ?? 100,
-                    sanitize: args.sanitize,
-                    sanitize_examples: args.sanitize_examples,
-                };
-                return withWarning(await handler(cloneArgs, client));
-            }
-            return withWarning({ error: "dashboard_clone handler not found" });
-        }
-        case "dashboard_generate": {
-            // Delegated to extracted handler
-            if (hasExtractedDataHandler("dashboard_generate")) {
-                const handler = getDataModeHandler("dashboard_generate");
-                // Map args to extracted handler format
-                const generateArgs = {
-                    id: personaId,
-                    dashboard_generate: args.count ?? args.dashboard_generate ?? 5,
-                    dashboard_template: args.template ?? args.dashboard_template,
-                };
-                return withWarning(await handler(generateArgs, client));
-            }
-            return withWarning({ error: "dashboard_generate handler not found" });
-        }
-        default:
-            return withWarning({ error: `Unknown mode: ${mode}` });
+    // Map old param names to new
+    if (args.file)
+        dataArgs.file_path = args.file;
+    if (args.source_persona_id)
+        dataArgs.from = args.source_persona_id;
+    const result = await handleData(dataArgs, client, readFile);
+    // Add deprecation warning to result
+    if (typeof result === "object" && result !== null) {
+        return {
+            _deprecation: {
+                message: "The 'knowledge' tool is deprecated. Use 'data' tool instead.",
+                migration: `data(method="${mappedMode}", ...)`,
+            },
+            ...result,
+        };
     }
+    return result;
 }

package/dist/mcp/handlers/persona/create.js

@@ -128,13 +128,48 @@ export async function handleCreate(args, client, getTemplateId) {
     }
     // For persona cloning, default include_data to true
     const effectiveIncludeData = sourcePersonaId ? (includeData ?? true) : false;
-    const result = await client.createAiEmployee({
-        name,
-        description: args.description,
-        template_id: templateId,
-        source_persona_id: sourcePersonaId,
-        clone_data: effectiveIncludeData,
-    });
+    let result;
+    try {
+        result = await client.createAiEmployee({
+            name,
+            description: args.description,
+            template_id: templateId,
+            source_persona_id: sourcePersonaId,
+            clone_data: effectiveIncludeData,
+        });
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        const personaType = args.type;
+        // Provide recovery guidance based on persona type
+        const recovery = {};
+        if (personaType === "voice" || templateId?.includes("voice") || templateId?.includes("001e")) {
+            recovery.option_1 = "Fetch gold template: ema://templates/voice-ai/workflow-def";
+            recovery.option_2 = "Fetch config template: ema://templates/voice-ai/proto-config";
+            recovery.option_3 = "See complete guide: ema://templates/voice-ai/complete";
+        }
+        else if (personaType === "chat") {
+            recovery.option_1 = "Use catalog(type='templates') to list available templates";
+            recovery.option_2 = "Try template(config='chat') for config structure";
+        }
+        else if (personaType === "dashboard") {
+            recovery.option_1 = "Use catalog(type='templates') to list available templates";
+            recovery.option_2 = "Try template(config='dashboard') for config structure";
+        }
+        else {
+            recovery.option_1 = "Use catalog(type='templates') to list available templates";
+            recovery.option_2 = "Specify explicit template ID with from='<template-id>'";
+        }
+        recovery.fallback = "Fetch ema://templates/voice-ai/complete for step-by-step recovery guide";
+        return {
+            error: `create_ai_employee failed`,
+            details: errorMsg,
+            environment: client.env?.name || "unknown",
+            recovery,
+            _tip: "If template creation fails, use gold templates from ema://templates/{type}/workflow-def as fallback.",
+            _warning: "NEVER clone a random existing persona. Use gold templates instead.",
+        };
+    }
     const newPersonaId = result.persona_id ?? result.id;
     if (!newPersonaId) {
         return { error: "Failed to create persona: no ID returned from API" };
@@ -145,21 +180,15 @@ export async function handleCreate(args, client, getTemplateId) {
     let workflowError;
     if (workflowDef && newPersonaId) {
         try {
-            // Get the newly created persona to get its proto_config and existing workflow name
+            // Get the newly created persona to get its proto_config
             const newPersona = await client.getPersonaById(newPersonaId);
             const protoConfig = (newPersona?.proto_config ?? {});
-            const existingWorkflow = (newPersona?.workflow_def ?? newPersona?.workflow);
-            // CRITICAL: Copy the workflowName from the template-created workflow
-            // The API rejects updates if the workflow name doesn't match
-            const existingWfName = existingWorkflow?.workflowName;
-            const workflowForDeploy = JSON.parse(JSON.stringify(workflowDef));
-            if (existingWfName?.name) {
-                // Set/overwrite the workflowName to match the existing one
-                workflowForDeploy.workflowName = existingWfName;
-            }
+            // NOTE: The SDK's updateAiEmployee() handles workflowName namespace automatically.
+            // It will copy from existing workflow if present, or generate a valid namespace if not.
+            // No need to manually manipulate workflowName here.
             await client.updateAiEmployee({
                 persona_id: newPersonaId,
-                workflow: workflowForDeploy,
+                workflow: workflowDef,
                 proto_config: protoConfig, // Required: API needs proto_config alongside workflow
             });
             workflowApplied = true;