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

package/dist/mcp/{tools-v2.js → tools.js}

@@ -19,7 +19,7 @@ import { generateInputDescription, SUPPORTED_OPERATIONS, LIMITATIONS } from "./w
 /**
  * Generate the v2 tool set
  */
-export function generateToolsV2(envNames, defaultEnv) {
+export function generateTools(envNames, defaultEnv) {
     const envDescription = envNames.length > 0
         ? `Environment: ${envNames.join(", ")}. Default: ${defaultEnv}`
         : "Environment name";
@@ -127,8 +127,8 @@ persona(
                     // === EXPLICIT METHOD (required) ===
                     method: {
                         type: "string",
-                        enum: ["list", "get", "create", "update", "delete", "analyze", "sanitize", "schema", "snapshot", "history", "restore", "compare"],
-                        description: "Operation to perform (required unless using data sub-resource)"
+                        enum: ["list", "get", "create", "update", "delete", "sanitize", "schema", "snapshot", "history", "restore"],
+                        description: "Operation to perform. LLM does analysis/comparison - use 'get' to retrieve data, then reason about it."
                     },
                     // === Identity ===
                     id: {
@@ -197,11 +197,6 @@ persona(
                         type: "string",
                         description: "Version to restore, e.g. 'v3' (for method=restore)"
                     },
-                    // === Compare params (for method=compare) ===
-                    to: {
-                        type: "string",
-                        description: "Persona ID or snapshot to compare to (for method=compare)"
-                    },
                     // === Data sub-resource ===
                     data: {
                         type: "object",
@@ -359,76 +354,47 @@ persona(
             },
         },
         // ═══════════════════════════════════════════════════════════════════════════
-        // 3. WORKFLOW - Complex workflow generation (separate from persona modifications)
+        // 3. WORKFLOW - Data retrieval and deployment ONLY (LLM does all thinking)
         // ═══════════════════════════════════════════════════════════════════════════
         {
             name: "workflow",
-            description: `Generate, analyze, or compile complex multi-node workflows.
-
-Use this for COMPLEX workflows (categorizers, multi-path routing, entity extraction chains).
-For SIMPLE modifications to existing personas, use persona(method="update", input="...") instead.
-
-## Generate (from requirements)
-- \`workflow(mode="generate", input="Voice AI for support with routing")\` - new workflow
-- \`workflow(mode="generate", input="...", persona_id="abc")\` - with widget context from existing persona
-- Returns \`llm_prompt\` for complex workflows - includes available widgets if persona_id provided
-- Returns \`available_widgets\` array showing what widget names to use in bindings
+            description: `Get workflow data or deploy LLM-generated workflows.
 
-## Analyze (existing workflow)
-- \`workflow(mode="analyze", persona_id="abc")\` - detect issues, get WorkflowSpec
+**MCP provides data. LLM does the thinking.**
 
-## Compile (spec to def)
-- \`workflow(mode="compile", workflow_spec={...})\` - convert WorkflowSpec to workflow_def
+## Get (return data for LLM to work with)
+- \`workflow(mode="get", persona_id="abc")\` - returns workflow_def, schema, patterns, widgets
+- LLM analyzes, compares, and generates workflows using this data
 
-## Deploy (to persona)
-- \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - apply workflow to persona
+## Deploy (execute LLM's result)
+- \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - deploy LLM-generated workflow
 
-**Workflow for complex creation:**
-1. \`workflow(mode="generate", input="...", persona_id="abc")\` → get llm_prompt + available_widgets
-2. Use LLM to generate WorkflowSpec (use widget names from available_widgets)
-3. \`workflow(mode="compile", workflow_spec={...})\` → get workflow_def
-4. \`persona(method="update", id="abc", workflow_def={...})\` → deploy
-
-**IMPORTANT**: Workflows reference widgets by name (widgetName). Pass persona_id to get available widget names.`,
+**Workflow for creation:**
+1. \`workflow(mode="get", persona_id="abc")\` → get schema, patterns, current workflow
+2. LLM generates workflow_def (LLM does the work)
+3. \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` → MCP deploys`,
             inputSchema: {
                 type: "object",
                 properties: {
                     mode: {
                         type: "string",
-                        enum: ["generate", "analyze", "compile", "deploy", "optimize"],
-                        description: "Operation to perform",
-                    },
-                    input: {
-                        type: "string",
-                        description: "Natural language requirements (for mode=generate)",
+                        enum: ["get", "deploy"],
+                        description: "get = return data for LLM, deploy = execute LLM's workflow_def",
                     },
                     persona_id: {
                         type: "string",
-                        description: "Persona ID (for mode=analyze, deploy, optimize)",
-                    },
-                    workflow_spec: {
-                        type: "object",
-                        description: "WorkflowSpec object (for mode=compile)",
+                        description: "Persona ID (required)",
                     },
                     workflow_def: {
                         type: "object",
-                        description: "workflow_def JSON (for mode=deploy)",
-                    },
-                    type: {
-                        type: "string",
-                        enum: ["voice", "chat", "dashboard"],
-                        description: "Persona type (for mode=generate)",
-                    },
-                    preview: {
-                        type: "boolean",
-                        description: "Preview without deploying (default: true)",
+                        description: "workflow_def JSON (for mode=deploy) - LLM generates this",
                     },
                     env: {
                         type: "string",
                         description: envDescription,
                     },
                 },
-                required: ["mode"],
+                required: ["mode", "persona_id"],
             },
         },
         // ═══════════════════════════════════════════════════════════════════════════

package/dist/mcp/workflow-operations.js

@@ -4,7 +4,7 @@
  * This file defines supported workflow modification operations.
  * Used by:
  * - analyzeModificationRequest() in handlers-consolidated.ts
- * - Tool descriptions in tools-v2.ts
+ * - Tool descriptions in tools.ts
  * - Tests to verify capabilities
  *
  * Add new operations here, and they'll automatically appear in tool docs.
@@ -64,7 +64,7 @@ export const ALTERNATIVES = {
 };
 /**
  * Generate tool description for the `input` parameter.
- * Called by tools-v2.ts to ensure description matches actual capabilities.
+ * Called by tools.ts to ensure description matches actual capabilities.
  */
 export function generateInputDescription() {
     const ops = SUPPORTED_OPERATIONS.map(op => op.example).join("', '");

package/dist/sdk/client-adapter.js

@@ -1,34 +1,80 @@
 /**
- * EmaClientAdapter - Adapter providing legacy EmaClient interface over EmaClientV2
+ * EmaClientAdapter - Drop-in replacement for legacy EmaClient using EmaClientV2
  *
- * This adapter enables parity testing between the old hand-written EmaClient
- * and the new auto-generated EmaClientV2. It wraps EmaClientV2 and exposes
- * the same interface as EmaClient for seamless comparison.
+ * This adapter provides full compatibility with the legacy EmaClient interface
+ * while using the new auto-generated EmaClientV2 under the hood.
  *
  * Usage:
  * ```typescript
- * const adapter = new EmaClientAdapter({
+ * // Replace: import { EmaClient } from './client.js';
+ * // With:    import { EmaClientAdapter as EmaClient } from './client-adapter.js';
+ *
+ * const client = new EmaClientAdapter({
  *   name: 'dev',
  *   baseUrl: 'https://api.dev.ema.co',
  *   bearerToken: 'xxx',
  * });
  *
  * // Same API as EmaClient
- * const personas = await adapter.getPersonasForTenant();
+ * const personas = await client.getPersonasForTenant();
  * ```
  */
 import { EmaClientV2 } from './ema-client.js';
 /**
  * Adapter that wraps EmaClientV2 with the legacy EmaClient interface.
  *
- * This enables parity testing between the old and new client implementations.
+ * This is a drop-in replacement for EmaClient.
  */
 export class EmaClientAdapter {
     client;
     env;
-    constructor(env) {
+    tokenRefreshConfig;
+    refreshIntervalId;
+    constructor(env, opts) {
         this.env = env;
         this.client = new EmaClientV2(env);
+        this.tokenRefreshConfig = opts?.tokenRefresh;
+        // Start background refresh if configured
+        if (this.tokenRefreshConfig?.backgroundRefresh !== false && this.tokenRefreshConfig?.refreshCallback) {
+            this.startBackgroundRefresh();
+        }
+    }
+    /** Start background token refresh */
+    startBackgroundRefresh() {
+        const intervalMs = this.tokenRefreshConfig?.refreshIntervalMs ?? 50 * 60 * 1000; // 50 minutes default
+        this.refreshIntervalId = setInterval(async () => {
+            try {
+                await this.refreshToken();
+            }
+            catch (e) {
+                console.error('[EmaClientAdapter] Background token refresh failed:', e);
+            }
+        }, intervalMs);
+    }
+    /** Stop background token refresh */
+    stopBackgroundRefresh() {
+        if (this.refreshIntervalId) {
+            clearInterval(this.refreshIntervalId);
+            this.refreshIntervalId = undefined;
+        }
+    }
+    /** Manually trigger token refresh */
+    async refreshToken() {
+        if (!this.tokenRefreshConfig?.refreshCallback) {
+            return false;
+        }
+        try {
+            const newToken = await this.tokenRefreshConfig.refreshCallback();
+            this.updateToken(newToken);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Access the underlying EmaClientV2 for advanced use */
+    get v2Client() {
+        return this.client;
     }
     /**
      * Get the environment name
@@ -54,28 +100,23 @@ export class EmaClientAdapter {
     updateToken(newToken) {
         this.client.updateToken(newToken);
     }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Persona Operations (delegated to EmaClientV2)
-    // ─────────────────────────────────────────────────────────────────────────────
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Persona Operations
+    // ═══════════════════════════════════════════════════════════════════════════
     /**
      * List all personas for the current tenant
      */
     async getPersonasForTenant() {
         const personas = await this.client.listPersonas();
-        // Map generated PersonaDto to legacy PersonaDTO interface
         return personas.map(p => this.mapToLegacyPersona(p));
     }
-    /**
-     * Alias for getPersonasForTenant
-     */
+    /** Alias for getPersonasForTenant */
     async getAiEmployeesForTenant() {
         return this.getPersonasForTenant();
     }
     /**
      * Get a single persona by ID
-     *
-     * Returns null for non-existent personas (matching legacy EmaClient behavior).
-     * The API may return 404 or 422 for invalid IDs - both are treated as "not found".
+     * Returns null for non-existent personas.
      */
     async getPersonaById(personaId) {
         try {
@@ -85,7 +126,6 @@ export class EmaClientAdapter {
             return this.mapToLegacyPersona(persona);
         }
         catch (error) {
-            // Handle 404 (not found) and 422 (invalid ID format) as null
             if (error instanceof Error) {
                 const apiError = error;
                 if (apiError.statusCode === 404 || apiError.statusCode === 422) {
@@ -95,26 +135,220 @@ export class EmaClientAdapter {
             throw error;
         }
     }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Template Operations (delegated to EmaClientV2)
-    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a new AI Employee
+     */
+    async createAiEmployee(req) {
+        // persona_template_id is required by the API
+        const templateId = req.persona_template_id ?? req.template_id;
+        if (!templateId) {
+            throw new Error('persona_template_id or template_id is required');
+        }
+        const result = await this.client.createAiEmployee({
+            name: req.name,
+            persona_template_id: templateId,
+            description: req.description,
+        });
+        return {
+            persona_id: result.persona_id ?? '',
+            success: !!result.persona_id,
+        };
+    }
+    /**
+     * Update an existing AI Employee
+     */
+    async updateAiEmployee(req) {
+        const result = await this.client.updateAiEmployee({
+            persona_id: req.persona_id,
+            workflow: req.workflow,
+            proto_config: req.proto_config,
+            name: req.name,
+            description: req.description,
+        });
+        return result;
+    }
+    /**
+     * Delete a persona
+     */
+    async deletePersona(personaId) {
+        return this.client.deletePersona(personaId);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Template Operations
+    // ═══════════════════════════════════════════════════════════════════════════
     /**
      * List all persona templates
      */
     async getPersonaTemplates() {
         const templates = await this.client.listPersonaTemplates();
-        // Map generated PersonaTemplateDto to legacy PersonaTemplateDTO interface
         return templates.map(t => this.mapToLegacyTemplate(t));
     }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Private Helper Methods
-    // ─────────────────────────────────────────────────────────────────────────────
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Action Operations
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * List all available actions
+     */
+    async listActions() {
+        const response = await this.client.listActions();
+        // Map gRPC ActionType to ActionDTO
+        return (response.actions ?? []).map(a => {
+            const typeName = a.typeName;
+            const name = typeName?.name?.name ?? '';
+            return {
+                id: name,
+                name: name,
+                displayName: a.displayName ?? name,
+                description: a.description ?? '',
+                category: String(a.category ?? ''),
+                typeName: typeName,
+                // inputs/outputs are complex proto maps - keep as raw for now
+                inputs: a.inputs,
+                outputs: a.outputs,
+            };
+        });
+    }
+    /** Alias for listActions */
+    async listAgents() {
+        return this.listActions();
+    }
+    /**
+     * List actions used in a specific workflow
+     */
+    async listActionsFromWorkflow(workflowId) {
+        const response = await this.client.listActionsFromWorkflow(workflowId);
+        // Map ActionType[] to string[] of action names
+        return (response.actions ?? []).map(a => {
+            const typeName = a.typeName;
+            return typeName?.name?.name ?? '';
+        }).filter(Boolean);
+    }
+    /** Alias for listActionsFromWorkflow */
+    async listAgentsFromWorkflow(workflowId) {
+        return this.listActionsFromWorkflow(workflowId);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Dashboard Operations
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get dashboard schema
+     */
+    async getDashboardSchema(personaId, _dashboardId) {
+        const response = await this.client.getDashboardSchema();
+        // Extract columns from proto response
+        const schema = response;
+        return {
+            columns: schema.schema?.columns ?? [],
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Data Source Operations
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Upload a data source file
+     */
+    async uploadDataSource(personaId, fileContent, filename, opts) {
+        return this.client.uploadDataSource(personaId, fileContent, filename, opts);
+    }
+    /**
+     * Delete a data source file
+     */
+    async deleteDataSource(personaId, fileId) {
+        return this.client.deleteDataSource(personaId, fileId);
+    }
+    /**
+     * List data source files
+     */
+    async listDataSourceFiles(personaId, opts) {
+        const response = await this.client.listDataSourceFiles(personaId, opts);
+        // Map proto ContentNode to simplified file object
+        const nodes = response.nodes ?? [];
+        return {
+            files: nodes.map(n => ({
+                id: n.id ?? '',
+                name: n.name ?? '',
+                size: n.size ?? 0,
+                uploadedAt: n.createdAt ?? '',
+            })),
+        };
+    }
+    /**
+     * Get data source aggregates
+     */
+    async getDataSourceAggregates(personaId, widgetName) {
+        const response = await this.client.getDataSourceAggregates(personaId, widgetName);
+        // Map proto aggregates
+        const agg = response;
+        const aggregates = agg.aggregates ?? [];
+        let total = 0, processed = 0, failed = 0;
+        for (const a of aggregates) {
+            total += a.count ?? 0;
+            if (a.status === 'processed' || a.status === 'PROCESSED')
+                processed += a.count ?? 0;
+            if (a.status === 'failed' || a.status === 'FAILED')
+                failed += a.count ?? 0;
+        }
+        return { total, processed, failed };
+    }
+    /**
+     * Replicate data between personas
+     */
+    async replicateData(sourcePersonaId, targetPersonaId, widgetMappings) {
+        const response = await this.client.replicateData(sourcePersonaId, targetPersonaId, widgetMappings);
+        const rep = response;
+        return { requestId: rep.requestId ?? '' };
+    }
+    /**
+     * Get replication status
+     */
+    async getReplicationStatus(requestId, _personaId) {
+        const response = await this.client.getReplicationStatus(requestId);
+        const rep = response;
+        const statusMap = {
+            0: 'unknown',
+            1: 'in_progress',
+            2: 'completed',
+            3: 'failed',
+        };
+        return {
+            status: statusMap[rep.status ?? 0] ?? 'unknown',
+            progress: rep.progress,
+            failedReason: rep.failedReason,
+        };
+    }
+    /**
+     * Wait for replication to complete
+     */
+    async waitForReplication(requestId, personaId, opts) {
+        return this.client.waitForReplication(requestId, personaId, opts);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Sync Metadata Operations
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get sync metadata from a persona
+     */
+    getSyncMetadata(persona) {
+        // Sync metadata is stored in custom_metadata
+        const customMeta = persona.custom_metadata;
+        if (!customMeta)
+            return null;
+        const syncData = customMeta['ema_mcp_sync'];
+        if (!syncData || typeof syncData !== 'object')
+            return null;
+        return syncData;
+    }
+    /**
+     * Check if persona was synced from another environment
+     */
+    isSyncedPersona(persona) {
+        return this.getSyncMetadata(persona) !== null;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Private Helpers
+    // ═══════════════════════════════════════════════════════════════════════════
     /**
      * Map generated PersonaDto to legacy PersonaDTO interface
-     *
-     * The generated type has nullable fields (string | null | undefined)
-     * while the legacy type expects (string | undefined). This method
-     * normalizes null to undefined for compatibility.
      */
     mapToLegacyPersona(p) {
         return {
@@ -122,10 +356,10 @@ export class EmaClientAdapter {
             name: this.nullToUndefined(p.name),
             description: this.nullToUndefined(p.description),
             template_id: this.nullToUndefined(p.template_id),
-            templateId: this.nullToUndefined(p.template_id), // legacy alias
+            templateId: this.nullToUndefined(p.template_id),
             workflow_id: this.nullToUndefined(p.workflow_id),
             workflow_def: p.workflow_def,
-            workflow: p.workflow_def, // legacy alias
+            workflow: p.workflow_def,
             workflow_interface: p.workflow_interface,
             proto_config: p.proto_config,
             status: this.nullToUndefined(p.status),
@@ -137,6 +371,7 @@ export class EmaClientAdapter {
             workflow_dashboard_id: this.nullToUndefined(p.workflow_dashboard_id),
             persona_interaction_type: this.nullToUndefined(p.persona_interaction_type),
             embedding_enabled: p.embedding_enabled,
+            custom_metadata: p.custom_metadata,
         };
     }
     /**

package/dist/sdk/client.js

@@ -393,27 +393,43 @@ export class EmaClient {
             const existingPersona = await this.getPersonaById(req.persona_id);
             const existingWorkflow = existingPersona?.workflow_def;
             const existingWfName = existingWorkflow?.workflowName;
+            // Deep clone workflow for modifications
+            const fixedWorkflow = JSON.parse(JSON.stringify(req.workflow));
             if (existingWfName?.name) {
-                // Deep clone workflow and fix the namespace
-                const fixedWorkflow = JSON.parse(JSON.stringify(req.workflow));
+                // Copy namespace from existing workflow
                 fixedWorkflow.workflowName = existingWfName;
-                // Also fix results format if needed - API expects "<actionName>.<outputName>" keys
-                const results = fixedWorkflow.results;
-                if (results) {
-                    const fixedResults = {};
-                    for (const [key, value] of Object.entries(results)) {
-                        if (value.actionName && value.outputName) {
-                            const correctKey = `${value.actionName}.${value.outputName}`;
-                            fixedResults[correctKey] = value;
-                        }
-                    }
-                    fixedWorkflow.results = fixedResults;
+                if (opts?.verbose || process.env.EMA_DEBUG) {
+                    console.error("[EmaClient] Copied workflow namespace from existing:", existingWfName.name);
                 }
-                finalReq = { ...req, workflow: fixedWorkflow };
+            }
+            else {
+                // CRITICAL FIX: Generate a valid namespace for personas without existing workflows.
+                // The API requires workflowName to match the persona's namespace format.
+                // Format: ["ema", "personas", "<persona_id>"] with name "workflow"
+                const generatedWfName = {
+                    name: {
+                        namespaces: ["ema", "personas", req.persona_id],
+                        name: "workflow",
+                    },
+                };
+                fixedWorkflow.workflowName = generatedWfName;
                 if (opts?.verbose || process.env.EMA_DEBUG) {
-                    console.error("[EmaClient] Fixed workflow namespace:", existingWfName.name);
+                    console.error("[EmaClient] Generated workflow namespace for new persona:", generatedWfName.name);
                 }
             }
+            // Also fix results format if needed - API expects "<actionName>.<outputName>" keys
+            const results = fixedWorkflow.results;
+            if (results) {
+                const fixedResults = {};
+                for (const [key, value] of Object.entries(results)) {
+                    if (value.actionName && value.outputName) {
+                        const correctKey = `${value.actionName}.${value.outputName}`;
+                        fixedResults[correctKey] = value;
+                    }
+                }
+                fixedWorkflow.results = fixedResults;
+            }
+            finalReq = { ...req, workflow: fixedWorkflow };
         }
         // Debug logging for troubleshooting
         if (opts?.verbose || process.env.EMA_DEBUG) {
@@ -534,10 +550,23 @@ export class EmaClient {
         });
         if (!resp.ok) {
             const body = await resp.text();
+            // Try to extract error details from response
+            let errorDetail = "";
+            try {
+                const parsed = JSON.parse(body);
+                errorDetail = parsed.error || parsed.message || parsed.detail || "";
+            }
+            catch {
+                errorDetail = body.slice(0, 200);
+            }
+            // Build informative error message
+            const message = errorDetail
+                ? `create_ai_employee failed (${this.env.name}): ${errorDetail}`
+                : `create_ai_employee failed (${this.env.name}) - status ${resp.status}`;
             throw new EmaApiError({
                 statusCode: resp.status,
                 body,
-                message: `create_ai_employee failed (${this.env.name})`,
+                message,
             });
         }
         return (await resp.json());