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

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