@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

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

@@ -287,27 +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
-    // REMOVED: modify, extend, generate, analyze, compare
-    const extractedModes = ["get", "deploy", "validate", "optimize"];
-    return extractedModes.includes(mode);
-}
-/**
- * Get handler for a specific workflow mode
- */
-export function getWorkflowModeHandler(mode) {
-    switch (mode) {
-        case "get":
-        case "deploy":
-        case "validate":
-        case "optimize":
-            return handleWorkflow;
-        // REMOVED: modify, extend, generate, analyze, compare
-        default:
-            return undefined;
-    }
-}