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

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) {

package/dist/sdk/ema-client.js

@@ -166,6 +166,17 @@ export class EmaClientV2 {
                 // Copy namespace from existing workflow
                 workflow = { ...workflow, workflowName: existingWfName };
             }
+            else {
+                // Generate a valid namespace for personas without existing workflows
+                // Format: ["ema", "personas", "<persona_id>"] with name "workflow"
+                const generatedWfName = {
+                    name: {
+                        namespaces: ["ema", "personas", personaId],
+                        name: "workflow",
+                    },
+                };
+                workflow = { ...workflow, workflowName: generatedWfName };
+            }
         }
         const result = await api.updatePersona({
             client: this.restClient,
@@ -287,6 +298,178 @@ export class EmaClientV2 {
         const personas = await this.listPersonas();
         return personas.filter(p => this.getSyncMetadata(p) !== null);
     }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // File Upload/Delete - REST API (not yet in OpenAPI spec)
+    // These are hand-written until the OpenAPI spec is updated
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Upload a file to an AI Employee's knowledge base.
+     * API endpoint: POST /api/v2/upload/files (multipart/form-data)
+     */
+    async uploadDataSource(personaId, fileContent, filename, opts) {
+        const widgetName = opts?.widgetName ?? "fileUpload";
+        const tags = opts?.tags ?? widgetName;
+        const mimeType = opts?.mimeType ?? this.detectMimeType(filename);
+        // Build multipart form data manually
+        const boundary = `----EmaUploadBoundary${Date.now()}`;
+        const parts = [];
+        // persona_id field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="persona_id"\r\n\r\n${personaId}`);
+        // widget_name field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="widget_name"\r\n\r\n${widgetName}`);
+        // tags field (required by API, defaults to widget_name)
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="tags"\r\n\r\n${tags}`);
+        // Build the file part
+        const filePart = [
+            `--${boundary}`,
+            `Content-Disposition: form-data; name="file"; filename="${filename}"`,
+            `Content-Type: ${mimeType}`,
+            "",
+            "", // Content will be appended as binary
+        ].join("\r\n");
+        // Combine everything
+        const headerBuffer = Buffer.from(parts.join("\r\n") + "\r\n" + filePart);
+        const fileBuffer = Buffer.isBuffer(fileContent) ? fileContent : Buffer.from(fileContent);
+        const footerBuffer = Buffer.from(`\r\n--${boundary}--\r\n`);
+        const bodyBuffer = Buffer.concat([headerBuffer, fileBuffer, footerBuffer]);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 60_000);
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                    "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                    "X-Persona-Id": personaId,
+                },
+                body: bodyBuffer,
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `uploadDataSource failed (${this.env.name})`,
+                });
+            }
+            const result = await resp.json();
+            return {
+                fileId: result.file_id ?? result.id ?? "",
+                status: result.status ?? "uploaded",
+                filename: filename,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Delete a data source file from an AI Employee's knowledge base.
+     * API endpoint: DELETE /api/v2/upload/files/{file_id}
+     */
+    async deleteDataSource(personaId, fileId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files/${fileId}?persona_id=${personaId}`, {
+                method: "DELETE",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                    "X-Persona-Id": personaId,
+                },
+                signal: controller.signal,
+            });
+            if (!resp.ok && resp.status !== 404) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `deleteDataSource failed (${this.env.name})`,
+                });
+            }
+            return { success: true, fileId };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Delete a persona
+     * API endpoint: DELETE /api/personas/{persona_id}
+     */
+    async deletePersona(personaId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/personas/${personaId}`, {
+                method: "DELETE",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                },
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `deletePersona failed (${this.env.name})`,
+                });
+            }
+            return { success: true };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Wait for data replication to complete (polling helper)
+     */
+    async waitForReplication(requestId, personaId, opts) {
+        const timeout = opts?.timeoutMs ?? 60_000;
+        const interval = opts?.pollIntervalMs ?? 2_000;
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const result = await this.getReplicationStatus(requestId);
+            if (result.status === 2 /* COMPLETED */) {
+                return { status: "completed" };
+            }
+            if (result.status === 3 /* FAILED */) {
+                return {
+                    status: "failed",
+                    failedReason: result.failedReason || "Unknown error"
+                };
+            }
+            await new Promise(resolve => setTimeout(resolve, interval));
+        }
+        return { status: "timeout" };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Detect MIME type from filename extension */
+    detectMimeType(filename) {
+        const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+        const mimeTypes = {
+            'pdf': 'application/pdf',
+            'txt': 'text/plain',
+            'csv': 'text/csv',
+            'json': 'application/json',
+            'xml': 'application/xml',
+            'html': 'text/html',
+            'md': 'text/markdown',
+            'doc': 'application/msword',
+            'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            'xls': 'application/vnd.ms-excel',
+            'xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+            'png': 'image/png',
+            'jpg': 'image/jpeg',
+            'jpeg': 'image/jpeg',
+            'gif': 'image/gif',
+        };
+        return mimeTypes[ext] ?? 'application/octet-stream';
+    }
 }
 // Default export for convenience
 export default EmaClientV2;