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

package/dist/mcp/tools.js

@@ -76,8 +76,8 @@ ${LIMITATIONS.map(l => `- ${l}`).join("\n")}
 ## Data Operations (sub-resource, requires id)
 - \`persona(id="abc", data={method:"list"})\` - list data items
 - \`persona(id="abc", data={method:"stats"})\` - get file counts by status (total, pending, success, failed)
-- \`persona(id="abc", data={method:"upload", path:"/file.pdf"})\` - upload file
-- \`persona(id="abc", data={method:"upload", items:[{...}]})\` - upload LLM-generated content
+- \`persona(id="abc", data={method:"upload", path:"/file.pdf"})\` - upload file to knowledge base
+- \`persona(id="abc", data={method:"upload", items:[{...}]})\` - create dashboard rows with data
 - \`persona(id="abc", data={method:"copy", from:"source-id"})\` - copy from another persona
 - \`persona(id="abc", data={method:"copy", from:"src", sanitize:true})\` - copy with PII masking
 - \`persona(id="abc", data={method:"replicate", from:"source-id"})\` - replicate by reference (no copy, fast)
@@ -88,7 +88,20 @@ ${LIMITATIONS.map(l => `- ${l}`).join("\n")}
 - \`persona(id="abc", data={method:"regenerate", document_id:"doc-123", project_id:"proj-456", selection:"intro", query:"make it shorter"})\` - modify document section
 - \`persona(id="abc", data={method:"replace", document_id:"doc-123", project_id:"proj-456", content:"new content"})\` - replace entire document content
 
-Note: For documents, \`replace\` is full content replacement (no partial update). For dashboard fixed inputs, use upload with existing row context.
+### Dashboard Row Upload with Files
+Create dashboard rows with file attachments (triggers workflow execution):
+\`\`\`
+persona(id="abc", data={
+  method: "upload",
+  items: [{
+    "Input Document": { file: "/path/to/invoice.pdf" },
+    "Customer Name": "Acme Corp"
+  }]
+})
+\`\`\`
+Item values support: strings, numbers, booleans, file attachments ({ file: "path" }), or inline documents ({ contents: "...", mime_type: "..." }).
+
+Note: \`path\` uploads to knowledge base (Chat personas). \`items\` creates dashboard rows (Dashboard personas).
 
 ## Action Composition (post-operation actions)
 Use \`actions\` array for multi-step operations instead of flag parameters.
@@ -127,8 +140,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 +210,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",
@@ -229,11 +237,17 @@ persona(
                             },
                             wait: { type: "boolean", description: "Wait for replication to complete (for method=replicate, default: true)" },
                             // upload params
-                            path: { type: "string", description: "File path to upload (for method=upload)" },
-                            content: {
+                            path: { type: "string", description: "File path to upload to knowledge base (for method=upload)" },
+                            items: {
                                 type: "array",
                                 items: { type: "object" },
-                                description: "Content array - LLM-generated (for method=upload)"
+                                description: "Dashboard rows to create. Each object maps column names to values. Values can be: strings, numbers, booleans, file attachments { file: '/path' }, or inline docs { contents: '...', mime_type: '...' }"
+                            },
+                            // widget_name - for targeting specific widgets in upload or filtering stats
+                            // Especially important for Document Generation personas with multiple upload widgets
+                            widget_name: {
+                                type: "string",
+                                description: "Target widget for upload OR filter for stats. For Document Proposal Manager: 'upload' (Content Repository), 'upload1' (Service Line Docs), 'upload2' (Style Guide). Default: 'fileUpload'. See catalog(type='widgets') for reference."
                             },
                             // delete params
                             file_id: { type: "string", description: "File/item ID to delete (for method=delete)" },
@@ -241,8 +255,6 @@ persona(
                             enabled: { type: "boolean", description: "Enable/disable embeddings (for method=embed)" },
                             // search params
                             query: { type: "string", description: "Search query (for method=search)" },
-                            // stats params
-                            widget_name: { type: "string", description: "Filter by widget name (for method=stats)" },
                         },
                         required: ["method"],
                     },
@@ -359,76 +371,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.
+            description: `Get workflow data or deploy LLM-generated workflows.
 
-## 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
+**MCP provides data. LLM does the thinking.**
 
-## Analyze (existing workflow)
-- \`workflow(mode="analyze", persona_id="abc")\` - detect issues, get WorkflowSpec
+## 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
 
-## Compile (spec to def)
-- \`workflow(mode="compile", workflow_spec={...})\` - convert WorkflowSpec to workflow_def
+## Deploy (execute LLM's result)
+- \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - deploy LLM-generated workflow
 
-## Deploy (to persona)
-- \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - apply workflow to persona
-
-**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/sdk/action-schema-parser.js

@@ -343,10 +343,16 @@ export function generateSchemaBundle(config) {
 // Type Compatibility Matrix
 // ============================================================================
 /**
- * Type compatibility rules for workflow validation
+ * Schema validation type compatibility - maps well-known types to compatible input names.
+ * Used by isTypeCompatible() for workflow validation.
+ *
+ * NOTE: This is SEPARATE from knowledge.ts TYPE_COMPATIBILITY which is user-facing documentation.
+ * This focuses on input NAME matching for schema validation.
+ *
+ * Canonical type documentation: src/sdk/knowledge.ts → TYPE_COMPATIBILITY
  */
-export const TYPE_COMPATIBILITY = {
-    // What inputs can accept each type
+export const SCHEMA_TYPE_COMPATIBILITY = {
+    // What input names can accept each type
     WELL_KNOWN_TYPE_CHAT_CONVERSATION: ["conversation", "chat_conversation"],
     WELL_KNOWN_TYPE_TEXT_WITH_SOURCES: ["query", "text", "user_query", "input"],
     WELL_KNOWN_TYPE_SEARCH_RESULT: ["search_results", "results"],
@@ -368,8 +374,8 @@ export function isTypeCompatible(sourceType, targetType, targetInputName) {
     if (targetInputName?.startsWith("named_inputs"))
         return true;
     // Check explicit compatibility
-    if (sourceType && TYPE_COMPATIBILITY[sourceType]) {
-        const compatible = TYPE_COMPATIBILITY[sourceType];
+    if (sourceType && SCHEMA_TYPE_COMPATIBILITY[sourceType]) {
+        const compatible = SCHEMA_TYPE_COMPATIBILITY[sourceType];
         if (compatible.includes("*"))
             return true;
         if (targetInputName && compatible.some((c) => targetInputName.includes(c)))

package/dist/sdk/client.js

@@ -17,7 +17,7 @@
  * const client = new EmaClientV2(env);
  * ```
  *
- * See docs/lessons-learned.md for migration guidance.
+ * See .ctx/docs/lessons-learned.md for migration guidance.
  */
 import { GrpcClient } from "./grpc-client.js";
 import { toJson } from "@bufbuild/protobuf";
@@ -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());
@@ -764,8 +793,10 @@ export class EmaClient {
      * Get data source aggregates (file counts by status).
      *
      * Uses typed gRPC client for proto-based calls.
+     * Falls back to counting files from listDataSourceFiles if aggregates API returns zeros.
      */
     async getDataSourceAggregates(personaId, widgetName = "fileUpload") {
+        // Try aggregates API first
         try {
             const response = await this.grpcClient.getContentNodeAggregates(personaId, widgetName);
             // Find the aggregate for the requested widget
@@ -774,16 +805,41 @@ export class EmaClient {
             const pending = counts?.pending ?? 0;
             const success = counts?.success ?? 0;
             const failed = counts?.failed ?? 0;
-            return {
-                total: pending + success + failed,
-                pending,
-                success,
-                failed,
-                widgetName,
-            };
+            const total = pending + success + failed;
+            // If we got data, return it
+            if (total > 0) {
+                return { total, pending, success, failed, widgetName };
+            }
+        }
+        catch {
+            // Aggregates API failed, fall through to fallback
+        }
+        // FALLBACK: Count files directly from listDataSourceFiles
+        // This handles cases where aggregates API returns zeros but files exist
+        try {
+            const result = await this.listDataSourceFiles(personaId, { widgetName });
+            const files = result.files;
+            if (files.length > 0) {
+                let pending = 0;
+                let success = 0;
+                let failed = 0;
+                for (const file of files) {
+                    const status = (file.status ?? "").toLowerCase();
+                    if (status === "success" || status === "completed" || status === "indexed") {
+                        success++;
+                    }
+                    else if (status === "failed" || status === "error") {
+                        failed++;
+                    }
+                    else {
+                        pending++; // pending, processing, or unknown
+                    }
+                }
+                return { total: files.length, pending, success, failed, widgetName };
+            }
         }
         catch {
-            // Fall through to return empty
+            // Fallback also failed
         }
         return { total: 0, pending: 0, success: 0, failed: 0, widgetName };
     }

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,

package/dist/sdk/generated/deprecated-actions.js

@@ -0,0 +1,171 @@
+/**
+ * Auto-generated deprecated actions list from ema repository.
+ *
+ * PRIMARY SOURCE: API via client.listActions() where deprecated === true
+ * This file is FALLBACK only when API is unavailable.
+ *
+ * Generated at: 2026-01-26T00:00:00.000Z
+ * Source: manual (pending first GH Actions sync)
+ *
+ * DO NOT EDIT MANUALLY - regenerate with: npm run generate:deprecated-actions
+ */
+/**
+ * Deprecated actions with known replacements.
+ * Use the replacement action instead.
+ */
+export const DEPRECATED_ACTIONS_WITH_REPLACEMENT = [
+    {
+        action: "search",
+        version: "v0",
+        replacement: "search",
+        replacementVersion: "v2",
+        migrationNotes: "v2 requires datastore_configs input (mandatory)",
+        source: "registered_actions.py",
+    },
+    {
+        action: "web_search",
+        version: "v0",
+        replacement: "live_web_search or ai_web_search",
+        migrationNotes: "Split into two specialized actions",
+        source: "registered_actions.py",
+    },
+    {
+        action: "call_llm",
+        version: "v0",
+        replacement: "call_llm",
+        replacementVersion: "v2",
+        migrationNotes: "v2 uses meta_respond_v2",
+        source: "registered_actions.py",
+    },
+    {
+        action: "combine_external_action_and_search_results",
+        version: "v0",
+        replacement: "respond_for_external_actions",
+        migrationNotes: "Migration in progress",
+        source: "registered_actions.py",
+    },
+    {
+        action: "human_collaboration",
+        version: "v0",
+        replacement: "general_hitl",
+        migrationNotes: "More flexible HITL patterns",
+        source: "registered_actions.py",
+    },
+    {
+        action: "fixed_response",
+        version: "v0",
+        replacement: "fixed_response",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "custom_agent",
+        version: "v0",
+        replacement: "custom_agent",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "json_mapper",
+        version: "v0",
+        replacement: "json_mapper",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "rule_validation_with_documents",
+        version: "v0",
+        replacement: "rule_validation_with_documents",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "text_categorizer",
+        version: "v0",
+        replacement: "text_categorizer",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "respond_with_sources",
+        version: "v0",
+        replacement: "respond_for_external_actions",
+        migrationNotes: "Better tool result handling",
+        source: "registered_actions.py",
+    },
+];
+/**
+ * Deprecated actions without documented replacements.
+ * These are typically internal actions or superseded functionality.
+ */
+export const DEPRECATED_ACTIONS_NO_REPLACEMENT = [
+    { action: "meta_respond", version: "all", environment: "all", migrationNotes: "Internal LLM response - do not use directly", source: "system_agents" },
+    { action: "meta_respond_v2", version: "all", environment: "all", migrationNotes: "Internal LLM response - do not use directly", source: "system_agents" },
+    { action: "ticket_respond_with_sources", version: "all", environment: "all", source: "system_agents" },
+    { action: "text_with_sources_translation", version: "all", environment: "all", source: "system_agents" },
+    { action: "document_categorizer", version: "all", environment: "all", source: "system_agents" },
+    { action: "document_metasearch", version: "all", environment: "all", source: "system_agents" },
+    { action: "combine_search_results", version: "all", environment: "all", source: "system_agents" },
+    { action: "combine_text_with_sources", version: "all", environment: "all", source: "system_agents" },
+    { action: "develop_outline", version: "all", environment: "all", source: "system_agents" },
+    { action: "generate_document_using_outline", version: "all", environment: "all", source: "system_agents" },
+    { action: "write_document", version: "all", environment: "all", source: "system_agents" },
+    { action: "external_action_caller_v1", version: "all", environment: "dev", migrationNotes: "Use external_action_caller v0", source: "system_agents" },
+    { action: "ticket_thread_sink", version: "all", environment: "dev", source: "system_agents" },
+    { action: "call_llm_v1", version: "all", environment: "all", migrationNotes: "Use call_llm v2", source: "system_agents" },
+];
+/**
+ * All deprecated actions combined.
+ */
+export const ALL_DEPRECATED_ACTIONS = [
+    ...DEPRECATED_ACTIONS_WITH_REPLACEMENT,
+    ...DEPRECATED_ACTIONS_NO_REPLACEMENT,
+];
+/**
+ * Deprecated agent types (legacy).
+ */
+export const DEPRECATED_AGENT_TYPES = [
+    "VISUALIZE_DATA",
+    "VISUALIZE_DATA_FOLLOWUP",
+    "PARSE_DELIMITED_FILES",
+    "GITHUB_DEMO",
+    "GITHUB_FOLLOWUP",
+    "RULES_VALIDATOR_AGENT",
+    "SUBJECT_RULE_VALIDATOR_AGENT",
+    "PRIOR_AUTHORISATION_AGENT",
+    "CHATBOT_AGENT",
+    "DEMO_PROPOSAL_MANAGEMENT_AGENT",
+    "GENERALISED_RULE_VALIDATION_AGENT",
+];
+/**
+ * Quick lookup map: "action/version" -> replacement info
+ */
+export const DEPRECATED_ACTIONS_MAP = {
+    "search/v0": { replacement: "search/v2", notes: "v2 requires datastore_configs input (mandatory)" },
+    "web_search/v0": { replacement: "live_web_search or ai_web_search", notes: "Split into two specialized actions" },
+    "call_llm/v0": { replacement: "call_llm/v2", notes: "v2 uses meta_respond_v2" },
+    "combine_external_action_and_search_results/v0": { replacement: "respond_for_external_actions", notes: "Migration in progress" },
+    "human_collaboration/v0": { replacement: "general_hitl", notes: "More flexible HITL patterns" },
+    "fixed_response/v0": { replacement: "fixed_response/v1" },
+    "custom_agent/v0": { replacement: "custom_agent/v1" },
+    "json_mapper/v0": { replacement: "json_mapper/v1" },
+    "rule_validation_with_documents/v0": { replacement: "rule_validation_with_documents/v1" },
+    "text_categorizer/v0": { replacement: "text_categorizer/v1" },
+    "respond_with_sources/v0": { replacement: "respond_for_external_actions", notes: "Better tool result handling" },
+    "meta_respond/all": { notes: "Internal LLM response - do not use directly" },
+    "meta_respond_v2/all": { notes: "Internal LLM response - do not use directly" },
+    "external_action_caller_v1/all": { notes: "Use external_action_caller v0" },
+    "call_llm_v1/all": { notes: "Use call_llm v2" },
+};
+/**
+ * Check if an action is deprecated.
+ */
+export function isActionDeprecated(actionName, version = "v0") {
+    return `${actionName}/${version}` in DEPRECATED_ACTIONS_MAP;
+}
+/**
+ * Get replacement for a deprecated action.
+ */
+export function getActionReplacement(actionName, version = "v0") {
+    return DEPRECATED_ACTIONS_MAP[`${actionName}/${version}`];
+}