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

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

@@ -0,0 +1,107 @@
+/**
+ * Generation Templates for data(method="generate")
+ *
+ * Built-in templates for document/data generation via the Document Generation API.
+ * Used by data(method="generate", from="...").
+ */
+export const GENERATION_TEMPLATES = {
+    // Reference data
+    "countries": {
+        description: "ISO 3166-1 countries with code and name",
+        category: "reference",
+        prompt: "Generate a JSON array of {count} ISO 3166-1 countries with fields: code (2-letter), name. Format: {format}",
+    },
+    "industries": {
+        description: "NAICS industry classifications",
+        category: "reference",
+        prompt: "Generate a JSON array of {count} NAICS industry classifications with fields: code, name, description. Format: {format}",
+    },
+    "currencies": {
+        description: "ISO 4217 currencies",
+        category: "reference",
+        prompt: "Generate a JSON array of {count} ISO 4217 currencies with fields: code (3-letter), name, symbol. Format: {format}",
+    },
+    // Demo kits
+    "demo-sales-sdr": {
+        description: "Sales SDR demo kit with prospects, products, and Q&A",
+        category: "demo",
+        prompt: `Generate a comprehensive sales demo kit in {format} format containing:
+1. {count} realistic B2B prospect profiles (company name, contact, role, pain points, budget)
+2. 3-5 product entries with features and pricing
+3. 10 common sales objections with responses
+4. Sample discovery call script`,
+    },
+    "demo-support": {
+        description: "Customer support demo kit with customers, FAQs, and tickets",
+        category: "demo",
+        prompt: `Generate a customer support demo kit in {format} format containing:
+1. {count} customer profiles (name, company, subscription tier, history)
+2. 10 frequently asked questions with detailed answers
+3. 5 sample support tickets with resolutions
+4. Escalation guidelines`,
+    },
+    "demo-hr": {
+        description: "HR assistant demo kit with employees, policies, and benefits",
+        category: "demo",
+        prompt: `Generate an HR demo kit in {format} format containing:
+1. {count} employee profiles (name, department, role, start date)
+2. 5 company policies (PTO, remote work, expenses)
+3. 3 benefits descriptions (health, 401k, equity)
+4. Onboarding checklist`,
+    },
+    // Entity templates
+    "customer": {
+        description: "B2B customer profile",
+        category: "entity",
+        prompt: `Generate {count} realistic B2B customer profiles in {format} format with fields:
+- company_name, industry, size (employees), annual_revenue
+- primary_contact (name, title, email, phone)
+- pain_points (array of 2-3 business challenges)
+- current_solutions (what they use today)
+- budget_range, decision_timeline`,
+    },
+    "product": {
+        description: "Product catalog entry with pricing",
+        category: "entity",
+        prompt: `Generate {count} product catalog entries in {format} format with fields:
+- name, sku, category
+- description (2-3 sentences)
+- features (array of 3-5 key features)
+- pricing (base_price, currency, billing_period)
+- availability (in_stock, lead_time)`,
+    },
+    "faq": {
+        description: "FAQ entries",
+        category: "entity",
+        prompt: `Generate {count} FAQ entries in {format} format with fields:
+- question (clear, specific question)
+- answer (comprehensive answer, 2-4 sentences)
+- category (e.g., billing, technical, getting-started)
+- related_questions (array of 2-3 related question titles)`,
+    },
+    "employee": {
+        description: "Employee profile for HR systems",
+        category: "entity",
+        prompt: `Generate {count} employee profiles in {format} format with fields:
+- name, email, employee_id
+- department, title, manager
+- start_date, location (office or remote)
+- skills (array), certifications (array)`,
+    },
+};
+/**
+ * Get a generation template by name
+ */
+export function getGenerationTemplate(name) {
+    return GENERATION_TEMPLATES[name];
+}
+/**
+ * List all available generation templates
+ */
+export function listGenerationTemplates() {
+    return Object.entries(GENERATION_TEMPLATES).map(([name, t]) => ({
+        name,
+        description: t.description,
+        category: t.category,
+    }));
+}

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

@@ -13,6 +13,7 @@ export async function handleEnv(_args, getEnvironments, toolkit) {
     const criticalRules = GUIDANCE_RULES
         .filter(r => r.level === "critical")
         .map(r => `• ${r.title}: ${r.do}`);
+    const defaultEnv = envs.find(e => e.isDefault)?.name || envs[0]?.name || "demo";
     return {
         environments: envs.map(e => ({
             name: e.name,
@@ -23,10 +24,10 @@ export async function handleEnv(_args, getEnvironments, toolkit) {
         // Onboarding guidance for new sessions
         getting_started: {
             workflow: [
-                "1. List personas: persona()",
-                "2. Get details: persona(id='...')",
-                "3. Analyze before modifying: persona(id='...', analyze=true)",
-                "4. Preview before deploying: update with preview=true",
+                "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, ...)",
             ],
             critical_rules: criticalRules,
             resources: [
@@ -40,5 +41,8 @@ export async function handleEnv(_args, getEnvironments, toolkit) {
                 "workflow_review - Analyze workflow health",
             ],
         },
+        // Consistent guidance format
+        _tip: `Start by listing personas: persona(method="list", env="${defaultEnv}")`,
+        _next_step: `persona(method="list", env="${defaultEnv}")`,
     };
 }

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

@@ -145,21 +145,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;

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

@@ -17,7 +17,9 @@
  * - analyze: Analyze persona for issues
  * - intent: Direct Intent Architect invocation for qualification
  *
- * Version management modes (version_*) remain in handlers-consolidated.ts.
+ * Version management modes extracted to version.ts:
+ * - snapshot/version_create, history/version_list, version_get
+ * - version_compare, restore/version_restore, version_policy
  */
 // Import mode handlers
 import { handleGet } from "./get.js";
@@ -71,3 +73,5 @@ export { handleDelete } from "./delete.js";
 export { handleCreate } from "./create.js";
 export { handleAnalyze } from "./analyze.js";
 export { handleIntent } from "./intent.js";
+// Version management
+export { handleVersion, isVersionMode } from "./version.js";