@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

package/dist/mcp/handlers/workflow/adapter.js

@@ -0,0 +1,174 @@
+/**
+ * Workflow V2 Adapter
+ *
+ * Handles file-path resolution for large workflow_def payloads, fingerprint-based
+ * stale-state protection, pre-deploy snapshots, and mode routing to handleWorkflow.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { fingerprintPersona } from "../../../sync.js";
+import { createVersionStorage } from "../../../sync/version-storage.js";
+import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { handleWorkflow } from "./index.js";
+export async function handleWorkflowAdapter(args, createClient, getDefaultEnvName) {
+    const normalizedArgs = { ...(args ?? {}) };
+    const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
+    let workflowDef = normalizedArgs.workflow_def;
+    const workflowDefPath = normalizedArgs.workflow_def_path;
+    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
+    const baseFingerprint = normalizedArgs.base_fingerprint;
+    const force = normalizedArgs.force;
+    // Resolve workflow_def from file when workflow_def_path is provided (large payloads).
+    // Also handle the common agent mistake: passing {"workflow_def_path": "/path"} as workflow_def.
+    let effectivePath = workflowDefPath;
+    if (mode === "deploy" && workflowDef && !effectivePath) {
+        const keys = Object.keys(workflowDef);
+        if (keys.length === 1 && keys[0] === "workflow_def_path" && typeof workflowDef.workflow_def_path === "string") {
+            effectivePath = workflowDef.workflow_def_path;
+            workflowDef = undefined;
+        }
+    }
+    if (mode === "deploy" && !workflowDef && effectivePath) {
+        try {
+            const path = await import("path");
+            if (!path.isAbsolute(effectivePath)) {
+                return { error: "workflow_def_path must be an absolute path on the MCP server host", path: effectivePath };
+            }
+            if (!effectivePath.toLowerCase().endsWith(".json")) {
+                return { error: "workflow_def_path must point to a .json file", path: effectivePath };
+            }
+            const fs = await import("fs/promises");
+            const stat = await fs.stat(effectivePath);
+            const MAX_WORKFLOW_DEF_BYTES = 1024 * 1024; // 1MB
+            if (stat.size > MAX_WORKFLOW_DEF_BYTES) {
+                return { error: `workflow_def_path file too large (${stat.size} bytes)`, max_bytes: MAX_WORKFLOW_DEF_BYTES, path: effectivePath };
+            }
+            const raw = await fs.readFile(effectivePath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                workflowDef = parsed;
+            }
+            else {
+                return { error: "workflow_def_path must point to a JSON object", path: effectivePath };
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { error: `Failed to read workflow_def from path: ${msg}`, path: effectivePath };
+        }
+    }
+    const client = createClient(normalizedArgs.env);
+    switch (mode) {
+        case "get": {
+            return handleWorkflow({
+                mode: "get",
+                persona_id: personaId,
+                env: normalizedArgs.env,
+            }, client, () => undefined);
+        }
+        case "validate": {
+            return handleWorkflow({
+                mode: "validate",
+                persona_id: personaId,
+                workflow_def: normalizedArgs.workflow_def,
+                workflow_spec: normalizedArgs.workflow_spec,
+                validation_type: normalizedArgs.validation_type,
+                max_paths: normalizedArgs.max_paths,
+                timeout_ms: normalizedArgs.timeout_ms,
+                env: normalizedArgs.env,
+            }, client, () => undefined);
+        }
+        case "deploy": {
+            if (!personaId) {
+                return { error: 'persona_id is required for workflow(mode="deploy")' };
+            }
+            const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
+            let versionCreated;
+            try {
+                const personaBefore = await client.getPersonaById(personaId);
+                if (!personaBefore) {
+                    return { error: `Persona not found: ${personaId}` };
+                }
+                const currentFp = fingerprintPersona(personaBefore);
+                if (!force && !baseFingerprint) {
+                    return {
+                        error: "base_fingerprint is required for workflow deploy (stale-state protection)",
+                        persona_id: personaId,
+                        current_fingerprint: currentFp,
+                        hint: "Run workflow(mode='get', persona_id='...') immediately before deploying and pass fingerprint as base_fingerprint. Use force=true only for emergency overrides.",
+                    };
+                }
+                if (!force && baseFingerprint && baseFingerprint !== currentFp) {
+                    return {
+                        error: "Persona changed since you last fetched it (fingerprint mismatch)",
+                        persona_id: personaId,
+                        base_fingerprint: baseFingerprint,
+                        current_fingerprint: currentFp,
+                        hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. Use force=true only if you intend to overwrite out-of-band changes.",
+                    };
+                }
+                const storage = createVersionStorage(process.cwd());
+                const engine = createVersionPolicyEngine(storage);
+                const snap = engine.forceCreateVersion(personaBefore, {
+                    environment: targetEnv,
+                    tenant_id: targetEnv,
+                    message: "Pre-deploy snapshot",
+                    created_by: "mcp-toolkit",
+                });
+                if (!snap.created || !snap.version) {
+                    if (!force) {
+                        return {
+                            error: "Failed to create pre-deploy snapshot (required before deploy)",
+                            persona_id: personaId,
+                            details: snap.reason,
+                            hint: "Fix snapshotting (workspace storage) or retry with force=true for emergency override.",
+                        };
+                    }
+                }
+                else {
+                    versionCreated = { id: snap.version.id, version_name: snap.version.version_name };
+                }
+            }
+            catch (snapshotErr) {
+                if (!force) {
+                    return {
+                        error: "Failed to create pre-deploy snapshot (required before deploy)",
+                        persona_id: personaId,
+                        hint: "Retry after fixing local workspace write access, or use force=true for emergency override.",
+                    };
+                }
+            }
+            const deployResult = await handleWorkflow({
+                mode: "deploy",
+                persona_id: personaId,
+                workflow_def: workflowDef,
+                proto_config: normalizedArgs.proto_config,
+                env: normalizedArgs.env,
+                force: force,
+                strict_validation: normalizedArgs.strict_validation,
+            }, client, () => undefined);
+            if (versionCreated && deployResult && typeof deployResult === "object") {
+                deployResult.version_snapshot = versionCreated;
+            }
+            return deployResult;
+        }
+        case "analyze":
+        case "compare":
+        case "compile":
+        case "optimize":
+        case "generate": {
+            return {
+                error: `Mode "${mode}" removed - LLM does this thinking`,
+                hint: "Use workflow(mode='get') to fetch data, then analyze/generate in your reasoning. Deploy with workflow(mode='deploy').",
+                valid_modes: ["get", "validate", "deploy"],
+            };
+        }
+        default: {
+            return {
+                error: `Mode required. Valid modes: get, validate, deploy`,
+                hint: "workflow(mode='get') returns data for LLM. workflow(mode='validate') validates specs. workflow(mode='deploy') executes LLM's workflow_def.",
+                example: `workflow(mode="get", persona_id="...")`,
+            };
+        }
+    }
+}

package/dist/mcp/handlers/workflow/fix.js

@@ -42,18 +42,17 @@ export function summarizeWorkflow(workflowDef) {
     if (nodeNames.length > 0) {
         lines.push(`\nNodes: ${nodeNames.slice(0, 20).join(", ")}${nodeNames.length > 20 ? "..." : ""}`);
     }
-    // TODO: This uses keyword matching to detect workflow features.
-    // Consider using ActionRegistry metadata instead for consistency with LLM-driven architecture.
-    // Current approach is acceptable for Auto Builder descriptions but could be improved.
-    // Check for categorizer (indicates intent routing)
-    const hasCategorizer = Array.from(actionTypes.keys()).some(t => t.includes("categorizer"));
-    if (hasCategorizer) {
-        lines.push("\nThis workflow uses intent-based routing with a categorizer.");
-    }
-    // Check for HITL
-    const hasHitl = Array.from(actionTypes.keys()).some(t => t.includes("hitl") || t.includes("general_hitl"));
-    if (hasHitl) {
-        lines.push("This workflow includes human-in-the-loop approval steps.");
+    const FEATURE_INDICATORS = {
+        categorizer: "This workflow uses intent-based routing with a categorizer.",
+        hitl: "This workflow includes human-in-the-loop approval steps.",
+        general_hitl: "This workflow includes human-in-the-loop approval steps.",
+        entity_extraction: "This workflow extracts structured data from documents.",
+        search: "This workflow searches a knowledge base.",
+    };
+    for (const [actionType, description] of Object.entries(FEATURE_INDICATORS)) {
+        if (actionTypes.has(actionType)) {
+            lines.push(`\n${description}`);
+        }
     }
     // Include raw workflow JSON for Auto Builder to parse
     lines.push("\n--- Full workflow_def JSON ---");

package/dist/mcp/handlers/workflow/index.js

@@ -22,18 +22,13 @@ import { fingerprintPersona } from "../../../sync.js";
 export * from "./types.js";
 // Re-export utilities  
 export * from "./utils.js";
-// Import internal handlers (not exposed as tool modes, but used internally)
-import { handleWorkflowAnalyze } from "./analyze.js";
-import { handleWorkflowCompare } from "./compare.js";
+// Import internal handlers
 import { handleWorkflowOptimize } from "./optimize.js";
 import { handleWorkflowDeploy } from "./deploy.js";
 import { handleWorkflowValidate } from "./validate.js";
 // Re-export for internal use (persona handler routes to these)
-export { handleWorkflowAnalyze } from "./analyze.js";
-export { handleWorkflowCompare } from "./compare.js";
 export { handleWorkflowOptimize } from "./optimize.js";
 export { handleWorkflowDeploy } from "./deploy.js";
-export { handleWorkflowGenerate } from "./generate.js";
 // NOTE: modify.ts REMOVED - violated LLM-driven architecture
 // The correct flow is: workflow(mode="get") → LLM modifies → workflow(mode="deploy")
 // Fallback deprecated actions - ONLY used when API unavailable
@@ -265,13 +260,17 @@ export async function handleWorkflow(args, client, _getTemplateId) {
             _tip: "The LLM generates the full workflow_def. MCP just deploys it.",
         };
     }
-    // DEPRECATED: analyze, compare - LLM can do this directly
-    // Kept for backwards compat but may be removed
-    if (mode === "analyze") {
-        return handleWorkflowAnalyze(args, client);
-    }
-    if (mode === "compare") {
-        return handleWorkflowCompare(args, client);
+    // REMOVED: analyze, compare - LLM does this by fetching rules and comparing
+    if (mode === "analyze" || mode === "compare") {
+        return {
+            error: `Mode "${mode}" has been removed.`,
+            reason: "LLM can do analysis/comparison by fetching ema://rules/* and reasoning about workflow_def.",
+            correct_flow: [
+                "1. workflow(mode='get', persona_id='...') - get current workflow_def",
+                "2. Fetch ema://rules/anti-patterns and ema://rules/structural-invariants",
+                "3. LLM analyzes/compares the data",
+            ],
+        };
     }
     // Auto-detect: only deploy if workflow_def provided
     if (personaId && workflowDef) {
@@ -288,30 +287,3 @@ export async function handleWorkflow(args, client, _getTemplateId) {
         hint: "MCP provides data (get), validates (validate), optimizes (optimize), and executes (deploy). LLM does all thinking.",
     };
 }
-/**
- * Check if a workflow mode has been extracted
- */
-export function hasExtractedWorkflowHandler(mode) {
-    // PUBLIC: get, deploy, validate, optimize
-    // DEPRECATED (kept for compat): analyze, compare
-    // REMOVED: modify, extend, generate (violated LLM-driven architecture)
-    const extractedModes = ["get", "deploy", "validate", "analyze", "optimize", "compare"];
-    return extractedModes.includes(mode);
-}
-/**
- * Get handler for a specific workflow mode
- */
-export function getWorkflowModeHandler(mode) {
-    switch (mode) {
-        case "get":
-        case "deploy":
-        case "validate":
-        case "analyze":
-        case "optimize":
-        case "compare":
-            return handleWorkflow;
-        // REMOVED: modify, extend, generate
-        default:
-            return undefined;
-    }
-}

package/dist/mcp/handlers/workflow/validation.js

@@ -706,7 +706,7 @@ export function validateExternalActionCallerTools(workflowDef) {
 // ═══════════════════════════════════════════════════════════════════════════
 // LOOP DETECTION VALIDATION
 // ═══════════════════════════════════════════════════════════════════════════
-import { detectLoops } from "../../domain/workflow-execution-analyzer.js";
+import { detectLoops } from "../../domain/loop-detection.js";
 /**
  * Validate that workflow has no circular dependencies.
  * Circular references cause infinite execution loops.