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

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.
@@ -224,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)" },
@@ -236,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"],
                     },

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";

package/dist/sdk/guidance.js

@@ -71,30 +71,55 @@ await persona({ id: "abc", update: { workflow_spec: spec } }); // Then deploy`,
   { name: "Fallback", description: "Anything else" }  // Required!
 ]`,
     },
+    {
+        id: "data-sources-before-search",
+        level: "critical",
+        category: "workflow",
+        title: "Upload Data Sources Before Search",
+        applies: "When creating workflows with search/RAG nodes",
+        description: "Workflows with search/v2 nodes require data sources (documents) to be uploaded to the persona. " +
+            "Without documents, search returns empty results and RAG is useless.",
+        do: "1. Upload documents: persona(id='...', data={method:'upload', path:'/path/to/doc.pdf'})\n" +
+            "2. Check status: persona(id='...', data={method:'stats'}) → verify 'success' count > 0\n" +
+            "3. Then deploy workflow with search node",
+        dont: "Deploy search-based workflows before uploading any documents to the knowledge base.",
+        example: `// Upload documents first
+await persona({ id: "abc", data: { method: "upload", path: "/docs/product-faq.pdf" } });
+await persona({ id: "abc", data: { method: "upload", path: "/docs/pricing.pdf" } });
+
+// Check they're indexed
+const stats = await persona({ id: "abc", data: { method: "stats" } });
+// stats.success should be > 0
+
+// Then deploy workflow with search
+await workflow({ mode: "deploy", persona_id: "abc", workflow_def: workflowWithSearch });`,
+        antiExample: `// BAD: Deploy search workflow with no documents
+await workflow({ mode: "deploy", persona_id: "abc", workflow_def: workflowWithSearch });
+// Search will return empty results!`,
+        related: ["analyze-before-modify"],
+    },
     {
         id: "workflow-modification-scope",
         level: "critical",
         category: "workflow",
         title: "Structure vs Content Changes",
         applies: "When modifying workflows",
-        description: "workflow(mode='modify') only supports STRUCTURAL changes (add/remove nodes, rewire connections). " +
+        description: "persona(method='update', input='...') only supports STRUCTURAL changes (add/remove nodes, rewire connections). " +
             "CONTENT changes (fixed_response data, call_llm prompts) require manual workflow_def editing.",
-        do: "For content changes: 1) Get workflow with persona(include_workflow=true), " +
+        do: "For content changes: 1) Get workflow with persona(method='get', id='...'), " +
             "2) Edit the node's stringValue in the JSON, 3) Deploy with workflow(mode='deploy', workflow_def={...})",
-        dont: "Use workflow(mode='modify') for content changes - it will silently return 0 changes.",
-        example: `// STRUCTURAL change (supported via structured operations)
-persona({ mode: "modify", id: "abc", operations: [
-  { type: "insert", insert: { action_type: "hitl", insert_before: "send_email" }}
-]})
+        dont: "Use update with input for content changes - it will silently return 0 changes.",
+        example: `// STRUCTURAL change (supported via update + input)
+persona({ method: "update", id: "abc", input: "add HITL before send_email" })
 
 // CONTENT change (requires manual edit)
-const p = await persona({ id: "abc", include_workflow: true });
+const p = await persona({ method: "get", id: "abc" });
 const wf = p.workflow_def;
 // Find and edit the fixed_response node's inputs.data.stringValue
 wf.actions[2].inputs.data.stringValue = JSON.stringify(newData);
 await workflow({ mode: "deploy", persona_id: "abc", workflow_def: wf });`,
-        antiExample: `// This will silently fail - content change via modify
-persona({ mode: "modify", id: "abc", operations: [...] })  // for content changes`,
+        antiExample: `// This will silently fail - content change via update
+persona({ method: "update", id: "abc", input: "change the welcome message" })  // for content changes`,
         related: ["workflow-spec-not-def", "llm-driven-modifications"],
     },
     {
@@ -103,15 +128,16 @@ persona({ mode: "modify", id: "abc", operations: [...] })  // for content change
         category: "workflow",
         title: "LLM-Driven Workflow Modifications",
         applies: "When modifying workflows structurally",
-        description: "The MCP does NOT parse natural language for modifications. YOU (the Agent/LLM) must build structured operations. " +
-            "Call persona(mode='modify') first to get workflow context, then build operations array.",
-        do: "1) Get context: persona(mode='modify', id='...') returns current_nodes, available_actions, example_operations. " +
-            "2) Build structured operations array. 3) Execute: persona(mode='modify', id='...', operations=[...])",
-        dont: "Pass natural language strings expecting MCP to parse them into operations.",
-        example: `// Step 1: Get context (returns current_nodes, available_actions, examples)
-const ctx = await persona({ mode: "modify", id: "abc" });
-
-// Step 2: YOU build structured operations based on user intent
+        description: "Use persona(method='update', input='...') for incremental changes. The MCP routes this to the workflow modify handler. " +
+            "For structured operations, use persona(method='update', operations=[...]).",
+        do: "1) Analyze workflow: persona(method='analyze', id='...') returns workflow_spec and issues. " +
+            "2) Make changes: persona(method='update', id='...', input='add HITL before email') " +
+            "3) Or use structured operations: persona(method='update', id='...', operations=[...])",
+        dont: "Expect operations to work without understanding the current workflow structure first.",
+        example: `// Option 1: Natural language input (routed to modify handler)
+await persona({ method: "update", id: "abc", input: "add HITL approval before send_email" });
+
+// Option 2: Structured operations
 const operations = [
   { 
     type: "insert",
@@ -123,12 +149,10 @@ const operations = [
     }
   }
 ];
-
-// Step 3: Execute
-await persona({ mode: "modify", id: "abc", operations });`,
-        antiExample: `// DON'T: Pass natural language expecting MCP to understand it
-await persona({ mode: "modify", id: "abc", input: "add approval before email" })
-// The MCP will NOT parse this - it returns context instead`,
+await persona({ method: "update", id: "abc", operations });`,
+        antiExample: `// DON'T: Try to modify without analyzing first
+await persona({ method: "update", id: "abc", operations: [...] })
+// Always analyze the workflow first to understand structure`,
         related: ["workflow-modification-scope", "analyze-before-modify"],
     },
     // ─────────────────────────────────────────────────────────────────────────
@@ -240,14 +264,14 @@ export const TOOL_GUIDANCE = {
                 example: 'persona(id="abc", analyze=true)',
             },
             {
-                name: "Get modify context",
-                description: "Get current_nodes, available_actions for building operations",
-                example: 'persona(mode="modify", id="abc")',
+                name: "Update with input",
+                description: "Incremental workflow changes via natural language",
+                example: 'persona(method="update", id="abc", input="add HITL before email")',
             },
             {
-                name: "Execute modify",
+                name: "Update with operations",
                 description: "Apply structured operations (insert/remove/rewire)",
-                example: 'persona(mode="modify", id="abc", operations=[...])',
+                example: 'persona(method="update", id="abc", operations=[...])',
             },
             {
                 name: "Create",
@@ -406,12 +430,11 @@ ${critical.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 ${important.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 
 ## LLM-Driven Architecture (CRITICAL)
-The MCP does NOT parse natural language for workflow modifications.
-**YOU (the Agent) must build structured operations:**
+Use \`persona(method="update", input="...")\` for workflow modifications:
 
-1. Get context: \`persona(mode="modify", id="...")\` → returns current_nodes, available_actions
-2. Build operations array based on user intent
-3. Execute: \`persona(mode="modify", id="...", operations=[...])\`
+1. Analyze: \`persona(method="analyze", id="...")\` → returns workflow_spec, issues
+2. Update with natural language: \`persona(method="update", id="...", input="add HITL before email")\`
+3. Or use structured operations: \`persona(method="update", id="...", operations=[...])\`
 
 Example operations: insert, remove, rewire, update_config
 

package/dist/sdk/index.js

@@ -27,8 +27,8 @@ AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM
 PROJECT_TYPES, 
 // Helper Functions
 getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
-// Workflow Analysis Functions
-parseWorkflowDef, detectWorkflowIssues, validateWorkflowConnections, analyzeWorkflow, suggestWorkflowFixes, 
+// Workflow Data Functions (LLM does analysis with rules)
+parseWorkflowDef, validateWorkflowConnections, 
 // Validation Rules (Single Source of Truth)
 VALIDATION_INPUT_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES, findInputSourceRule, findAntiPatternByIssueType, generateMarkdownDocumentation, exportRulesAsJSON, } from "./knowledge.js";
 // Workflow Compiler (Template-driven workflow generation)
@@ -57,8 +57,9 @@ export { VersionStorage, createVersionStorage, } from "./version-storage.js";
 export { VersionPolicyEngine, createVersionPolicyEngine, } from "./version-policy.js";
 // Workflow Execution Analyzer (Loop, multiple responder, redundant classifier detection)
 export { analyzeExecutionFlow, detectLoops, detectMultipleResponders, detectRedundantClassifiers, analyzeDataFlow, findDeadCodePaths, generateASCIIFlow, } from "./workflow-execution-analyzer.js";
-// Workflow Fixer (Auto-fix including multiple responder issues)
-export { autoFixWorkflow, suggestFixes, } from "./workflow-fixer.js";
+// Workflow Fixer - REMOVED
+// autoFixWorkflow, suggestFixes removed as part of "MCP = data, LLM = logic" refactor
+// LLM now applies rules from ema://rules/* and proposes fixes
 // Intent Architect (WHY + WHAT, not HOW - with progressive enhancement)
 // NOTE: intent-decomposition.ts and intent-decomposition-v2.ts were removed as part of consolidation.
 // All intent processing now goes through the Intent Architect module.
@@ -86,12 +87,12 @@ runIntentArchitect, } from "./intent-architect.js";
 export { analyzeOptimizations, summarizeOptimizationReport, } from "./workflow-optimizer.js";
 // Workflow Tracer (Flow visualization & path analysis)
 export { traceWorkflow, generateDetailedTrace, formatFlowTrace, formatDetailedTrace, } from "./workflow-tracer.js";
-// Quality Gates (Pre-deploy validation)
-export { runQualityGates, canDeploy, getQualityGates, formatQualityReport, } from "./quality-gates.js";
+// Quality Gates (Pre-deploy validation) - DEPRECATED, minimal implementation
+export { runQualityGates, formatQualityReport, isDeploymentAllowed, getBlockingIssues, QUALITY_GATES, } from "./quality-gates.js";
 // Structural Rules (LLM validation context)
 export { STRUCTURAL_RULES_FOR_LLM, STRUCTURAL_INVARIANTS, EXECUTION_RULES, COMMON_STRUCTURAL_MISTAKES, getAllStructuralRules, getInvariantById, getCriticalInvariants, } from "./structural-rules.js";
 // Action Schema Parser (Parse ema_backend/grpc definitions)
-export { parseTextproto, parseActionDirectory, loadDocumentation, generateSchemaBundle, isTypeCompatible as isSchemaTypeCompatible, TYPE_COMPATIBILITY, } from "./action-schema-parser.js";
+export { parseTextproto, parseActionDirectory, loadDocumentation, generateSchemaBundle, isTypeCompatible as isSchemaTypeCompatible, SCHEMA_TYPE_COMPATIBILITY, } from "./action-schema-parser.js";
 // Workflow Merge (Brownfield workflow comparison, merging, validation)
 export { compareWorkflows, mergeWorkflows, validateMergedWorkflow, } from "./workflow-merge.js";
 // Auto Builder Prompt Generation