@ema.co/mcp-toolkit 1.7.0 → 1.7.1

package/dist/mcp/handlers-consolidated.js

@@ -194,10 +194,18 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
                 try {
                     sourcePersona = await resolvePersona(client, cloneFrom);
                     if (sourcePersona) {
-                        const protoConfig = sourcePersona.proto_config;
-                        const projectSettings = protoConfig?.projectSettings;
-                        const projectType = projectSettings?.projectType;
-                        sourcePersonaType = projectType === 5 ? "voice" : projectType === 4 ? "chat" : projectType === 2 ? "dashboard" : undefined;
+                        // Use trigger_type (root level) for reliable persona type detection
+                        // trigger_type: 0=chat, 1=voice, 2=dashboard
+                        const triggerType = sourcePersona.trigger_type;
+                        if (triggerType === 1) {
+                            sourcePersonaType = "voice";
+                        }
+                        else if (triggerType === 2) {
+                            sourcePersonaType = "dashboard";
+                        }
+                        else if (triggerType === 0) {
+                            sourcePersonaType = "chat";
+                        }
                         sourceDashboardId = sourcePersona.workflow_dashboard_id;
                     }
                 }
@@ -241,17 +249,35 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
                         if (shouldSanitize) {
                             sanitizationSession = new SanitizationSession();
                         }
+                        // Track document inputs that couldn't be cloned (require manual re-upload)
+                        const allSkippedDocuments = [];
                         for (const row of sourceRows.rows) {
                             try {
                                 // Build inputs from row's input column values
                                 const inputs = [];
+                                const rowSkippedDocs = [];
                                 for (const inputCol of inputColumns) {
                                     const colValue = row.columnValues.find(cv => cv.columnId === inputCol.columnId);
                                     if (!colValue)
                                         continue;
                                     // Handle different column types
                                     if (inputCol.columnType === "COLUMN_TYPE_DOCUMENT") {
-                                        // Skip document columns for now
+                                        // Document inputs can't be auto-cloned (no download API for original files)
+                                        // Track them for manual re-upload notification
+                                        const docValues = colValue.value.documentCellValue?.documentValues ?? [];
+                                        for (const doc of docValues) {
+                                            if (!doc.deleted) {
+                                                rowSkippedDocs.push({
+                                                    name: inputCol.name,
+                                                    original_filename: doc.name
+                                                });
+                                                allSkippedDocuments.push({
+                                                    column: inputCol.name,
+                                                    filename: doc.name,
+                                                    contentNodeId: doc.contentNodeId,
+                                                });
+                                            }
+                                        }
                                         continue;
                                     }
                                     else if (inputCol.columnType === "COLUMN_TYPE_STRING") {
@@ -288,27 +314,74 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
                                             inputs.push({ name: inputCol.name, string_value: value });
                                         }
                                     }
+                                    // Note: COLUMN_TYPE_NUMBER and COLUMN_TYPE_BOOLEAN are not currently
+                                    // parsed from the dashboard rows protobuf response, so they're skipped
                                 }
+                                // If we have inputs (even if some docs were skipped), try to clone
                                 if (inputs.length === 0) {
-                                    results.push({ source_row_id: row.id, status: "skipped", error: "No clonable input values" });
+                                    // Check if we had document-only inputs
+                                    if (rowSkippedDocs.length > 0) {
+                                        results.push({
+                                            source_row_id: row.id,
+                                            status: "skipped",
+                                            error: "Document-only inputs require manual re-upload",
+                                            skipped_documents: rowSkippedDocs,
+                                        });
+                                    }
+                                    else {
+                                        results.push({ source_row_id: row.id, status: "skipped", error: "No clonable input values" });
+                                    }
                                     continue;
                                 }
                                 // Upload the row to target dashboard
                                 const uploadResult = await client.uploadAndRunDashboardRow(newPersonaId, inputs);
-                                results.push({ source_row_id: row.id, target_row_id: uploadResult.row_id, status: "cloned" });
+                                const rowResult = {
+                                    source_row_id: row.id,
+                                    target_row_id: uploadResult.row_id,
+                                    status: rowSkippedDocs.length > 0 ? "partial" : "cloned",
+                                };
+                                if (rowSkippedDocs.length > 0) {
+                                    rowResult.skipped_documents = rowSkippedDocs;
+                                }
+                                results.push(rowResult);
                             }
                             catch (err) {
                                 results.push({ source_row_id: row.id, status: "error", error: err instanceof Error ? err.message : String(err) });
                             }
                         }
-                        const clonedCount = results.filter(r => r.status === "cloned").length;
+                        const clonedCount = results.filter(r => r.status === "cloned" || r.status === "partial").length;
                         dashboardCloneResult = {
                             source_rows: sourceRows.rows.length,
                             cloned_rows: clonedCount,
+                            partial_rows: results.filter(r => r.status === "partial").length,
                             skipped_rows: results.filter(r => r.status === "skipped").length,
                             error_rows: results.filter(r => r.status === "error").length,
                             sanitization_applied: !!shouldSanitize,
+                            // Debug info for troubleshooting
+                            _debug: {
+                                total_count_from_api: sourceRows.totalCount,
+                                schema_columns_count: sourceRows.schema.columns.length,
+                                input_columns_count: inputColumns.length,
+                                schema_columns: sourceRows.schema.columns.map(c => ({
+                                    id: c.columnId,
+                                    name: c.name,
+                                    type: c.columnType,
+                                    isInput: c.isInput,
+                                })),
+                                first_row_id: sourceRows.rows[0]?.id?.substring(0, 100),
+                                first_row_state: sourceRows.rows[0]?.state,
+                                first_row_column_values_count: sourceRows.rows[0]?.columnValues?.length,
+                                results_detail: results,
+                            },
                         };
+                        // Include document upload notice if any documents were skipped
+                        if (allSkippedDocuments.length > 0) {
+                            dashboardCloneResult.documents_require_manual_upload = {
+                                count: allSkippedDocuments.length,
+                                files: allSkippedDocuments.slice(0, 10), // Limit to first 10 for readability
+                                note: "Document inputs cannot be auto-cloned. Re-upload original files to the cloned dashboard.",
+                            };
+                        }
                     }
                     else {
                         dashboardCloneResult = { source_rows: 0, cloned_rows: 0, message: "Source dashboard was empty" };
@@ -318,18 +391,27 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
                     dashboardCloneResult = { error: `Dashboard clone failed: ${err instanceof Error ? err.message : String(err)}` };
                 }
             }
-            // Handle sanitization for non-dashboard personas
+            // Handle workflow sanitization for ALL persona types (including dashboard)
+            // Dashboard rows are sanitized during clone loop above, but workflow still needs sanitization
             const shouldSanitize = args.sanitize;
-            if (shouldSanitize && newPersonaId && sourcePersonaType !== "dashboard") {
+            if (shouldSanitize && newPersonaId) {
                 const sanitizeResult = await sanitizePersonaById(client, newPersonaId, {
                     examples: args.sanitize_examples,
+                    preview: args.preview ?? false, // Use preview arg, default to false (apply)
                 });
-                return {
+                const createResult = {
                     success: true,
                     persona_id: newPersonaId,
                     name,
                     sanitization: sanitizeResult,
                 };
+                if (sourcePersonaType) {
+                    createResult.source_persona_type = sourcePersonaType;
+                }
+                if (dashboardCloneResult) {
+                    createResult.dashboard_data_clone = dashboardCloneResult;
+                }
+                return createResult;
             }
             const createResult = {
                 success: true,

package/dist/sdk/client.js

@@ -883,10 +883,6 @@ export class EmaClient {
      */
     async getDashboardRows(dashboardId, personaId, opts) {
         // Build protobuf request manually (GetDashboardRowsRequest)
-        // Field 1: dashboard_id (string)
-        // Field 2: limit (int32)
-        // Field 3: offset (int32)
-        // Field 9: get_minimal_row_values (bool)
         const limit = opts?.limit ?? 100;
         const offset = opts?.offset ?? 0;
         const getMinimal = false;
@@ -1003,6 +999,9 @@ export class EmaClient {
     }
     /**
      * Parse the protobuf GetDashboardRowsResponse message.
+     *
+     * Note: The response format varies - sometimes columns are in field 1 (as repeated Column),
+     * sometimes in field 2 as Schema { columns }. We detect and handle both cases.
      */
     parseGetDashboardRowsResponse(data) {
         const result = {
@@ -1011,6 +1010,11 @@ export class EmaClient {
             schema: { columns: [] },
             rows: [],
         };
+        // Field mapping (from protobuf analysis):
+        // Field 1 = Schema message (contains nested Column messages at subfield 1)
+        // Field 2 = Row messages (repeated)
+        // Field 3 = totalCount (varint)
+        // Field 4 = dashboardName (string)
         let pos = 0;
         const dec = new TextDecoder();
         while (pos < data.length) {
@@ -1024,14 +1028,15 @@ export class EmaClient {
                 const fieldData = data.slice(pos, pos + length);
                 pos += length;
                 if (fieldNumber === 1) {
-                    // rows (repeated Row message)
-                    const row = this.parseProtoRow(fieldData, dec);
-                    if (row)
-                        result.rows.push(row);
+                    // Schema message - parse columns from it
+                    result.schema = this.parseProtoSchemaFromField1(fieldData, dec);
                 }
                 else if (fieldNumber === 2) {
-                    // schema (Schema message)
-                    result.schema = this.parseProtoSchema(fieldData, dec);
+                    // Row message
+                    const row = this.parseProtoRow(fieldData, dec);
+                    if (row && row.id) {
+                        result.rows.push(row);
+                    }
                 }
                 else if (fieldNumber === 4) {
                     // dashboard_name (string)
@@ -1116,9 +1121,18 @@ export class EmaClient {
         return row.id ? row : null;
     }
     /**
-     * Parse Schema message from protobuf.
+     * Parse Schema message from protobuf field 1.
+     * Schema contains repeated Column messages at subfield 1.
+     *
+     * Column fields (from protobuf analysis):
+     * - Field 1 (0x0a): name (string) e.g. "Document"
+     * - Field 2 (0x10): columnType (varint) e.g. 6 = DOCUMENT
+     * - Field 4 (0x20): isInput (bool)
+     * - Field 5 (0x28): isRequired (bool)
+     * - Field 11 (0x5a): actionId (string) e.g. "workflow_input"
+     * - Field 13 (0x6a): columnId (string) e.g. "document-jghm"
      */
-    parseProtoSchema(data, dec) {
+    parseProtoSchemaFromField1(data, dec) {
         const schema = { columns: [] };
         let pos = 0;
         while (pos < data.length) {
@@ -1131,10 +1145,11 @@ export class EmaClient {
                 const fieldData = data.slice(pos, pos + length);
                 pos += length;
                 if (fieldNumber === 1) {
-                    // columns (repeated Column)
-                    const col = this.parseProtoColumn(fieldData, dec);
-                    if (col)
+                    // Column message
+                    const col = this.parseProtoColumnV2(fieldData, dec);
+                    if (col) {
                         schema.columns.push(col);
+                    }
                 }
             }
             else if (wireType === 0) {
@@ -1148,24 +1163,35 @@ export class EmaClient {
         return schema;
     }
     /**
-     * Parse Column message from protobuf.
+     * Parse Column message from protobuf (v2 - correct field mapping).
+     * Based on actual protobuf analysis:
+     * - Field 1: name (string)
+     * - Field 2: columnType (varint)
+     * - Field 4: isInput (bool)
+     * - Field 5: isRequired (bool)
+     * - Field 11: actionId (string)
+     * - Field 12: actionName (string)
+     * - Field 13: columnId (string)
      */
-    parseProtoColumn(data, dec) {
-        // Column type enum mapping
+    parseProtoColumnV2(data, dec) {
+        const col = {
+            columnId: "",
+            name: "",
+            columnType: "COLUMN_TYPE_UNSPECIFIED",
+            isInput: false,
+            actionId: "",
+            actionName: "",
+            outputFieldName: "",
+        };
         const columnTypeMap = {
             0: "COLUMN_TYPE_UNSPECIFIED",
             1: "COLUMN_TYPE_STRING",
             2: "COLUMN_TYPE_NUMBER",
             3: "COLUMN_TYPE_BOOLEAN",
             4: "COLUMN_TYPE_ARRAY",
-            5: "COLUMN_TYPE_DOCUMENT",
-        };
-        const col = {
-            columnId: "",
-            columnType: "COLUMN_TYPE_UNSPECIFIED",
-            name: "",
-            actionId: "",
-            isInput: false,
+            5: "COLUMN_TYPE_OBJECT",
+            6: "COLUMN_TYPE_DOCUMENT",
+            7: "COLUMN_TYPE_ENUM",
         };
         let pos = 0;
         while (pos < data.length) {
@@ -1177,34 +1203,44 @@ export class EmaClient {
                 pos += bytesRead;
                 const fieldData = data.slice(pos, pos + length);
                 pos += length;
+                const strValue = dec.decode(fieldData);
                 if (fieldNumber === 1) {
-                    col.columnId = dec.decode(fieldData);
+                    col.name = strValue;
                 }
-                else if (fieldNumber === 2) {
-                    col.name = dec.decode(fieldData);
+                else if (fieldNumber === 11) {
+                    col.actionId = strValue;
                 }
-                else if (fieldNumber === 5) {
-                    col.actionId = dec.decode(fieldData);
+                else if (fieldNumber === 12) {
+                    col.actionName = strValue;
                 }
-                else if (fieldNumber === 6) {
-                    col.actionName = dec.decode(fieldData);
+                else if (fieldNumber === 13) {
+                    col.columnId = strValue;
+                }
+                else if (fieldNumber === 14) {
+                    col.outputFieldName = strValue;
                 }
             }
             else if (wireType === 0) {
                 const { value, bytesRead } = this.decodeVarintAt(data, pos);
                 pos += bytesRead;
-                if (fieldNumber === 3) {
-                    col.columnType = columnTypeMap[value] ?? `COLUMN_TYPE_${value}`;
+                if (fieldNumber === 2) {
+                    col.columnType = columnTypeMap[value] ?? "COLUMN_TYPE_UNSPECIFIED";
                 }
                 else if (fieldNumber === 4) {
                     col.isInput = value === 1;
                 }
             }
             else {
-                break;
+                // Skip unknown wire types (like fixed32/64)
+                if (wireType === 5)
+                    pos += 4;
+                else if (wireType === 1)
+                    pos += 8;
+                else
+                    break;
             }
         }
-        return col.columnId ? col : null;
+        return (col.name || col.columnId) ? col : null;
     }
     /**
      * Parse ColumnValue message from protobuf.

package/docs/tool-consolidation-v2.md

@@ -0,0 +1,215 @@
+# MCP Tool Consolidation v2
+
+## Overview
+
+Consolidate from 9 tools to **5 core tools** with cleaner separation of concerns.
+
+## Final Tool Design
+
+### 1. `persona` - Manage AI Employees
+
+```typescript
+persona(
+  id?: string,                    // get specific persona
+  query?: string,                 // search by name
+  all?: boolean,                  // list all
+  
+  // Create/Clone
+  name?: string,                  // for create
+  type?: "voice" | "chat" | "dashboard",
+  input?: string,                 // natural language description
+  clone_from?: string,            // clone source persona ID
+  clone_data?: boolean,           // also clone files
+  sanitize?: boolean,             // sanitize PII during clone
+  
+  // Update
+  enabled?: boolean,              // enable/disable
+  
+  // Compare
+  compare_to?: string,            // compare two personas
+  
+  // Output control
+  include_workflow?: boolean,     // include workflow_def in response
+)
+```
+
+**Examples:**
+```
+persona(all=true)                              # list all
+persona(id="abc-123")                          # get specific
+persona(query="support")                       # search
+persona(name="My Bot", type="voice", input="...") # create
+persona(clone_from="abc", name="Clone", clone_data=true, sanitize=true)
+```
+
+---
+
+### 2. `data` - Manage Persona Data
+
+```typescript
+data(
+  persona_id: string,             // REQUIRED - data belongs to persona
+  mode?: "list" | "get" | "upload" | "delete" | "sanitize",  // default: list
+  file_id?: string,               // for get/delete specific
+  include_results?: boolean,      // for dashboard: show extracted values
+)
+```
+
+**Examples:**
+```
+data(persona_id="abc")                         # list files
+data(persona_id="abc", file_id="x")            # get file details
+data(persona_id="abc", mode="upload")          # upload (file from context)
+data(persona_id="abc", mode="delete", file_id="x")
+data(persona_id="abc", mode="sanitize")        # sanitize all data
+data(persona_id="abc", include_results=true)   # list with extraction results
+```
+
+**For dashboard personas, file listing includes:**
+```json
+{
+  "files": [{
+    "id": "file-123",
+    "name": "contract.pdf",
+    "processing": {
+      "status": "success",
+      "extracted": { "vendor": "Acme", "amount": "$50k" }
+    }
+  }]
+}
+```
+
+---
+
+### 3. `workflow` - Workflow Operations
+
+```typescript
+workflow(
+  persona_id?: string,            // target persona
+  
+  // Generate/Modify
+  input?: string,                 // natural language description
+  
+  // Analyze
+  analyze?: boolean,              // analyze current workflow
+  optimize?: boolean,             // suggest optimizations
+  
+  // Deploy
+  workflow_def?: object,          // direct workflow deployment
+  preview?: boolean,              // preview without deploying (default: true)
+)
+```
+
+**Examples:**
+```
+workflow(persona_id="abc", input="Add email notification")
+workflow(persona_id="abc", analyze=true)
+workflow(persona_id="abc", optimize=true, preview=false)
+```
+
+---
+
+### 4. `reference` - All Reference Information
+
+```typescript
+reference(
+  type?: "actions" | "templates" | "patterns" | "envs" | "concepts" | "guidance",
+  
+  // For actions
+  action_id?: string,             // get specific action
+  query?: string,                 // search
+  suggest?: string,               // suggest actions for use case
+  
+  // For guidance
+  topic?: string,                 // guidance topic
+  
+  // For concepts
+  concept?: string,               // specific concept
+  
+  // Validation helpers
+  check_types?: { source: string, target: string },
+  validate_prompt?: string,
+)
+```
+
+**Examples:**
+```
+reference(type="actions")                      # list all actions
+reference(type="actions", query="email")       # search actions
+reference(type="actions", suggest="IT helpdesk")
+reference(action_id="send_email")              # get specific action
+reference(type="templates")                    # list workflow templates
+reference(type="patterns")                     # list patterns
+reference(type="envs")                         # list environments
+reference(type="concepts")                     # list concepts
+reference(concept="HITL")                      # get specific concept
+reference(type="guidance", topic="categorizer-routing")
+```
+
+---
+
+### 5. `sync` - Environment Sync
+
+```typescript
+sync(
+  id?: string,                    // persona ID or name
+  target?: string,                // target environment
+  dry_run?: boolean,              // simulate without changes
+  
+  // Status
+  mode?: "run" | "status" | "config",
+  list_synced?: boolean,          // list all synced personas
+)
+```
+
+**Examples:**
+```
+sync(id="IT Support", target="dev")
+sync(id="abc-123", target="staging", dry_run=true)
+sync(mode="status", id="abc-123")
+sync(mode="config")
+```
+
+---
+
+## Migration Path
+
+| Old Tool | New Location |
+|----------|--------------|
+| `env` | `reference(type="envs")` |
+| `knowledge` | `data` |
+| `demo` | Removed (generate separately or future addition) |
+| `action` | `reference(type="actions")` |
+| `template` | `reference(type="templates")` / `reference(type="patterns")` |
+
+## Mental Model
+
+```
+┌─────────────────────────────────────────┐
+│              PERSONA                    │
+│  ┌─────────┐  ┌──────────┐             │
+│  │  data   │  │ workflow │             │
+│  └─────────┘  └──────────┘             │
+└─────────────────────────────────────────┘
+         │              │
+         └──────┬───────┘
+                │
+    ┌───────────▼───────────┐
+    │      reference        │  (actions, templates, guidance)
+    └───────────────────────┘
+                │
+    ┌───────────▼───────────┐
+    │        sync           │  (copy between envs)
+    └───────────────────────┘
+```
+
+## Implementation Checklist
+
+- [ ] Update `tools-consolidated.ts` with new tool definitions
+- [ ] Update `handlers-consolidated.ts` with routing logic
+- [ ] Migrate `knowledge` handlers to `data`
+- [ ] Migrate `action`, `template`, `env` to `reference`
+- [ ] Remove deprecated tools
+- [ ] Update tests
+- [ ] Update documentation
+- [ ] Add deprecation warnings for old tool names (backwards compat)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",