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

package/dist/mcp/server.js

@@ -27,6 +27,22 @@ const packageJsonPath = join(__dirname, "..", "..", "package.json");
 const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
 export const TOOLKIT_NAME = packageJson.name;
 export const TOOLKIT_VERSION = packageJson.version;
+// Try to read git commit for build info (optional, doesn't fail if not available)
+import { execSync } from "node:child_process";
+function getGitCommit() {
+    try {
+        const commit = execSync("git rev-parse --short HEAD", {
+            cwd: join(__dirname, "..", ".."),
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"]
+        }).trim();
+        return commit;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const TOOLKIT_COMMIT = getGitCommit();
 // Prompts, Resources, and Guidance
 import { PromptRegistry, isPromptError } from "./prompts.js";
 import { ResourceRegistry, isResourceError } from "./resources.js";
@@ -42,8 +58,8 @@ import { getToolkitRoot } from "../sdk/paths.js";
 import { SYNC_METADATA_KEY } from "../sdk/models.js";
 // Auto Builder Knowledge
 import { AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
-// Workflow Analysis
-analyzeWorkflow, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
+// Workflow Data (LLM does analysis with rules from ema://rules/*)
+validateWorkflowConnections, parseWorkflowDef, } from "../sdk/knowledge.js";
 // Template fallbacks (generated from protos, used when API unavailable)
 import { getTemplateFallback, getTemplateFieldDocs, VOICE_TEMPLATE_FALLBACK } from "../sdk/generated/template-fallbacks.js";
 // Workflow Compiler (Template-driven)
@@ -92,6 +108,9 @@ 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) {
@@ -111,8 +130,19 @@ function summarizeWorkflow(workflowDef) {
  * Apply automatic fixes to a workflow based on detected issues.
  * This function attempts to fix common issues like missing WORKFLOW_OUTPUT,
  * wrong input sources, and other structural problems.
+ *
+ * @deprecated This function violates the LLM-driven architecture principle.
+ * MCP should not auto-fix workflows - it should return suggestions for the Agent to apply.
+ * Per CLAUDE.md: "Auto-fix issues | ❌ FORBIDDEN | ✅ Proposes fixes"
+ *
+ * This function will be removed in a future version. Instead:
+ * 1. Use analyzeWorkflow() to detect issues
+ * 2. Return issues as suggestions to the Agent
+ * 3. Let Agent apply fixes via persona(id="...", operations=[...])
  */
 function applyWorkflowFixes(workflowDef, issues, persona) {
+    // Log deprecation warning
+    console.warn("[DEPRECATED] applyWorkflowFixes() called - this function violates LLM-driven architecture and will be removed");
     // Deep clone the workflow to avoid mutating the original
     const fixedWorkflow = JSON.parse(JSON.stringify(workflowDef));
     const appliedFixes = [];
@@ -1909,30 +1939,30 @@ const toolHandlers = {
         // Track fixes applied
         const appliedFixes = [];
         let fixAttempted = false;
-        // Validate workflow if requested and provided
-        let validationResults = { valid: true, issues: [] };
+        // Validation is now done by backend when workflow is deployed
+        // LLM should use ema://rules/* for pre-validation guidance
+        const validationResults = { valid: true, issues: [] };
         if (validateFirst && workflowDef) {
-            const analysis = analyzeWorkflow(workflowDef, {
-                persona_id: personaId,
-                persona_name: persona.name ?? "Unknown"
-            });
-            if (!analysis.validation_passed) {
-                validationResults.valid = false;
-                validationResults.issues = analysis.issues ?? [];
-                // Auto-fix if enabled
-                if (autoFix && validationResults.issues.length > 0) {
-                    fixAttempted = true;
-                    const fixResult = applyWorkflowFixes(workflowDef, validationResults.issues, persona);
-                    workflowDef = fixResult.fixedWorkflow;
-                    appliedFixes.push(...fixResult.appliedFixes);
-                    // Re-validate after fixes
-                    const reAnalysis = analyzeWorkflow(workflowDef, {
-                        persona_id: personaId,
-                        persona_name: persona.name ?? "Unknown"
-                    });
-                    validationResults.valid = reAnalysis.validation_passed;
-                    validationResults.issues = reAnalysis.issues ?? [];
-                }
+            // DEPRECATED: MCP no longer pre-validates workflows
+            // Backend validation happens on deploy
+            // LLM uses ema://rules/anti-patterns for analysis
+            console.warn("[DEPRECATED] validateFirst is deprecated - backend validates on deploy");
+            if (autoFix) {
+                // Auto-fix is removed - return guidance for LLM
+                return {
+                    environment: client["env"].name,
+                    success: false,
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    _deprecation_notice: "autoFix is deprecated. Use LLM analysis with ema://rules/* instead.",
+                    _guidance: [
+                        "1. Fetch ema://rules/anti-patterns",
+                        "2. Analyze workflow against rules",
+                        "3. Make structured modifications",
+                        "4. Deploy via workflow(mode='deploy')",
+                    ],
+                    applied_fixes: [],
+                };
             }
         }
         // If validation failed and not forcing, return the issues
@@ -2124,152 +2154,27 @@ const toolHandlers = {
                 message: "This AI Employee has no workflow. Use prompt parameter to generate one: optimize_workflow(persona_id=\"...\", prompt=\"description of what it should do\")",
             };
         }
-        // Step 2: Analyze workflow for issues
-        const analysis = analyzeWorkflow(workflowDef, {
-            persona_id: personaId,
-            persona_name: persona.name ?? "Unknown",
-        });
-        const issues = analysis.issues ?? [];
-        const criticalIssues = issues.filter(i => i.severity === "critical");
-        // If no issues, workflow is healthy
-        if (issues.length === 0) {
-            const result = {
-                success: true,
-                persona: persona.name,
-                status: "✅ Workflow is healthy",
-                nodes: analysis.summary?.total_nodes ?? 0,
-                message: "No issues found - workflow is already optimized!",
-            };
-            // If enhancement prompt was provided, note that it can't be auto-applied
-            if (enhancementPrompt) {
-                result.enhancement_note = `Enhancement requested: "${enhancementPrompt}". Since there are no issues to fix, use the Ema UI Auto Builder to make this change manually.`;
-            }
-            return result;
-        }
-        // Step 3: Apply fixes
-        let fixedWorkflow = workflowDef;
-        const appliedFixes = [];
-        if (issues.length > 0) {
-            const fixResult = applyWorkflowFixes(workflowDef, issues, persona);
-            fixedWorkflow = fixResult.fixedWorkflow;
-            appliedFixes.push(...fixResult.appliedFixes);
-        }
-        // Re-analyze after fixes
-        const postFixAnalysis = analyzeWorkflow(fixedWorkflow, {
-            persona_id: personaId,
-            persona_name: persona.name ?? "Unknown",
-        });
-        const remainingIssues = postFixAnalysis.issues ?? [];
-        const remainingCritical = remainingIssues.filter(i => i.severity === "critical");
-        // If preview mode, show what would happen without deploying
-        if (preview) {
-            const fixedCount = appliedFixes.filter(f => f.applied).length;
-            const failedCount = appliedFixes.filter(f => !f.applied).length;
-            const previewResult = {
-                success: true,
-                persona: persona.name,
-                status: "📋 Preview - Fixes Available",
-                mode: "optimize",
-                nodes: fixedWorkflow.actions?.length ?? 0,
-                found_issues: issues.length,
-                can_fix: fixedCount,
-                cannot_fix: failedCount,
-                ready_to_deploy: remainingCritical.length === 0,
-                issues: issues.length > 0 ? issues.map(i => `${i.severity === "critical" ? "❌" : "⚠️"} ${i.type}: ${i.reason}`) : ["No issues found"],
-                fixes: appliedFixes.length > 0 ? appliedFixes.map(f => `${f.applied ? "✅" : "❌"} ${f.description}`) : [],
-                next_step: remainingCritical.length === 0
-                    ? `Run workflow(persona_id="${personaId}", mode="optimize") without preview to deploy fixes.`
-                    : `${remainingCritical.length} critical issue(s) need manual fix in Ema UI.`,
-            };
-            if (enhancementPrompt) {
-                previewResult.enhancement_note = `Enhancement "${enhancementPrompt}" noted. Auto-fixes will be applied first; use Ema UI Auto Builder for the enhancement.`;
-            }
-            return previewResult;
-        }
-        // Step 4: Deploy if no critical issues remain
-        if (remainingCritical.length > 0) {
-            return {
-                success: false,
-                persona: persona.name,
-                status: "❌ Cannot auto-fix",
-                fixed: appliedFixes.filter(f => f.applied).length,
-                remaining_critical: remainingCritical.length,
-                manual_fixes_needed: remainingCritical.map(i => ({
-                    problem: i.type,
-                    details: i.reason,
-                    fix: i.recommendation,
-                })),
-                message: `${remainingCritical.length} issue(s) need manual fix in the Ema UI Auto Builder.`,
-            };
-        }
-        // Sanitize workflow before deployment
-        // Fix enumTypes - check nested structure
-        const enumTypes = fixedWorkflow.enumTypes;
-        if (Array.isArray(enumTypes)) {
-            const validEnumTypes = enumTypes.filter(e => {
-                const outerName = e.name;
-                const innerName = outerName?.name;
-                const actualName = innerName?.name;
-                return typeof actualName === "string" && actualName.trim().length > 0;
-            });
-            if (validEnumTypes.length > 0) {
-                fixedWorkflow.enumTypes = validEnumTypes;
-            }
-            else {
-                delete fixedWorkflow.enumTypes;
-            }
-        }
-        // Copy workflowName from existing
-        const existingWfName = workflowDef.workflowName;
-        if (existingWfName) {
-            fixedWorkflow.workflowName = JSON.parse(JSON.stringify(existingWfName));
-        }
-        // Sanitize existing proto_config widgets
-        const mergedProtoConfig = mergeProtoConfig(persona.proto_config, undefined);
-        // Build and send request
-        const req = {
+        // DEPRECATED: MCP no longer pre-analyzes workflows
+        // LLM should use ema://rules/* for analysis
+        console.warn("[DEPRECATED] optimize_workflow tool is deprecated - use LLM analysis with ema://rules/*");
+        const nodes = parseWorkflowDef(workflowDef);
+        return {
+            success: true,
+            persona: persona?.name ?? "Unknown",
             persona_id: personaId,
-            proto_config: mergedProtoConfig,
-            workflow: fixedWorkflow,
+            status: "DEPRECATED - use LLM analysis",
+            node_count: nodes.length,
+            workflow_def: workflowDef,
+            _deprecation_notice: {
+                message: "optimize_workflow is deprecated. MCP does not pre-compute issues.",
+                new_workflow: [
+                    "1. Fetch rules: ema://rules/anti-patterns, ema://rules/optimizations",
+                    "2. Apply rules to find issues (LLM does this, not MCP)",
+                    "3. Make structured modifications based on your analysis",
+                    "4. Deploy via workflow(mode='deploy', persona_id='...', workflow_def={...})",
+                ],
+            },
         };
-        const actionsArr = fixedWorkflow.actions ?? [];
-        try {
-            await client.updateAiEmployee(req);
-            const fixedCount = appliedFixes.filter(f => f.applied).length;
-            const deployResult = {
-                success: true,
-                persona: persona.name,
-                status: "✅ Optimized & Deployed",
-                mode: "optimized",
-                issues_found: issues.length,
-                issues_fixed: fixedCount,
-                nodes: postFixAnalysis.summary?.total_nodes ?? actionsArr.length,
-                message: fixedCount > 0
-                    ? `Fixed ${fixedCount} issue(s) and deployed!`
-                    : "Deployed successfully!",
-                next_step: "Test in the Ema simulator to verify behavior.",
-            };
-            if (enhancementPrompt) {
-                deployResult.enhancement_note = `Fixes applied. Enhancement "${enhancementPrompt}" requires manual implementation via Ema UI Auto Builder.`;
-            }
-            return deployResult;
-        }
-        catch (err) {
-            const errorMessage = err instanceof Error ? err.message : String(err);
-            // Extract EmaApiError body if available
-            const apiBody = err?.body;
-            const statusCode = err?.statusCode;
-            return {
-                success: false,
-                persona: persona.name,
-                status: "❌ Deploy Failed",
-                error: errorMessage,
-                status_code: statusCode,
-                api_response: apiBody ? JSON.parse(apiBody) : undefined,
-                fixes_attempted: appliedFixes.filter(f => f.applied).length,
-                suggestion: "Check the api_response field for the actual backend error.",
-            };
-        }
     },
     // ─────────────────────────────────────────────────────────────────────────
     // Action Handlers (Consolidated)
@@ -2884,40 +2789,41 @@ const toolHandlers = {
     // Workflow Review & Audit Handlers
     // ─────────────────────────────────────────────────────────────────────────────
     analyze_workflow: async (args) => {
+        // DEPRECATED: MCP no longer pre-analyzes workflows
+        // LLM should use ema://rules/* for analysis
         const client = createClient(args.env);
         const personaId = String(args.persona_id);
         const persona = await client.getPersonaById(personaId);
         if (!persona)
             throw new Error(`AI Employee not found: ${personaId}`);
-        if (!persona.workflow_def) {
-            return {
-                environment: client["env"].name,
-                persona_id: personaId,
-                persona_name: persona.name,
-                error: "AI Employee has no workflow_def",
-                recommendation: "This persona may not have a generated workflow. Use Auto Builder to create one.",
-            };
-        }
-        const analysis = analyzeWorkflow(persona.workflow_def, {
+        const nodes = persona.workflow_def ? parseWorkflowDef(persona.workflow_def) : [];
+        const connections = persona.workflow_def ? validateWorkflowConnections(persona.workflow_def) : [];
+        return {
+            environment: client["env"].name,
             persona_id: personaId,
             persona_name: persona.name,
-            environment: client["env"].name,
-        });
-        return {
-            ...analysis,
-            recommendations: analysis.validation_passed
-                ? ["Workflow structure looks valid. Test with sample queries to verify behavior."]
-                : [
-                    "Fix all critical issues before deployment",
-                    ...analysis.issues
-                        .filter(i => i.severity === "critical")
-                        .slice(0, 3)
-                        .map(i => `Priority: ${i.reason}`),
-                    "Use suggest_workflow_fixes to get fix proposals",
+            status: "DEPRECATED - use LLM analysis",
+            node_count: nodes.length,
+            workflow_def: persona.workflow_def,
+            connections: connections.map(c => ({
+                edge: c.edge_id,
+                source_type: c.source_type,
+                target_type: c.target_type,
+                compatible: c.compatible,
+            })),
+            _deprecation_notice: {
+                message: "analyze_workflow is deprecated. MCP does not pre-compute issues.",
+                new_workflow: [
+                    "1. Fetch rules: ema://rules/anti-patterns",
+                    "2. Apply rules to find issues (LLM does this, not MCP)",
+                    "3. Report your findings",
                 ],
+            },
         };
     },
     detect_workflow_issues: async (args) => {
+        // DEPRECATED: MCP no longer detects workflow issues
+        // LLM should use ema://rules/* for analysis
         const workflowDef = args.workflow_def;
         if (!workflowDef || typeof workflowDef !== "object") {
             return {
@@ -2925,21 +2831,19 @@ const toolHandlers = {
                 hint: "Get workflow_def from get_ai_employee_full(persona_id).ai_employee.workflow_def",
             };
         }
-        const issues = detectWorkflowIssues(workflowDef);
-        const summary = {
-            total: issues.length,
-            critical: issues.filter(i => i.severity === "critical").length,
-            warning: issues.filter(i => i.severity === "warning").length,
-            info: issues.filter(i => i.severity === "info").length,
-        };
+        const nodes = parseWorkflowDef(workflowDef);
         return {
-            issues,
-            summary,
-            validation_passed: summary.critical === 0,
-            issue_types_found: [...new Set(issues.map(i => i.type))],
-            next_steps: issues.length > 0
-                ? ["Use suggest_workflow_fixes(issues) to get fix proposals"]
-                : ["No issues detected - workflow structure looks valid"],
+            status: "DEPRECATED - use LLM analysis",
+            node_count: nodes.length,
+            nodes: nodes.map(n => ({ id: n.id, action: n.action_name })),
+            _deprecation_notice: {
+                message: "detect_workflow_issues is deprecated. MCP does not pre-compute issues.",
+                new_workflow: [
+                    "1. Fetch rules: ema://rules/anti-patterns",
+                    "2. Apply rules to this workflow (LLM does this)",
+                    "3. Report issues YOU find",
+                ],
+            },
         };
     },
     validate_workflow_connections: async (args) => {
@@ -2976,38 +2880,25 @@ const toolHandlers = {
             })),
         };
     },
-    suggest_workflow_fixes: async (args) => {
-        const issues = args.issues;
-        if (!Array.isArray(issues)) {
-            return {
-                error: "Invalid issues array",
-                hint: "Pass issues from detect_workflow_issues or analyze_workflow",
-                example_input: [
-                    { type: "missing_fallback", severity: "critical", node: "intent_classifier", reason: "..." },
-                    { type: "type_mismatch", severity: "critical", source: "trigger.chat_conversation", target: "search.query", reason: "..." },
-                ],
-            };
-        }
-        if (issues.length === 0) {
-            return {
-                message: "No issues to fix",
-                fixes: [],
-            };
-        }
-        const fixes = suggestWorkflowFixes(issues);
+    suggest_workflow_fixes: async (_args) => {
+        // DEPRECATED: MCP no longer suggests fixes
+        // LLM should reason about fixes using ema://rules/*
         return {
-            issue_count: issues.length,
-            fix_count: fixes.length,
-            fixes,
-            application_order: [
-                "1. Fix critical issues first (missing_fallback, incomplete_hitl, cycles)",
-                "2. Fix type mismatches (may require adding intermediate nodes)",
-                "3. Address warnings (wrong_input_source, orphan nodes)",
-                "4. Re-run detect_workflow_issues to verify fixes",
-            ],
+            status: "DEPRECATED - use LLM reasoning",
+            _deprecation_notice: {
+                message: "suggest_workflow_fixes is deprecated. LLM should propose fixes.",
+                new_workflow: [
+                    "1. Analyze workflow with ema://rules/anti-patterns",
+                    "2. For each issue found, reason about the fix",
+                    "3. Build structured modifications",
+                    "4. Apply via persona(mode='update', operations=[...])",
+                ],
+            },
         };
     },
     compare_workflow_versions: async (args) => {
+        // DEPRECATED: MCP no longer pre-analyzes for comparison
+        // LLM should compare workflows directly
         const client = createClient(args.env);
         const idBefore = String(args.persona_id_before);
         const idAfter = String(args.persona_id_after);
@@ -3019,59 +2910,38 @@ const toolHandlers = {
             throw new Error(`AI Employee not found (before): ${idBefore}`);
         if (!personaAfter)
             throw new Error(`AI Employee not found (after): ${idAfter}`);
-        const analysisBefore = personaBefore.workflow_def
-            ? analyzeWorkflow(personaBefore.workflow_def, { persona_id: idBefore, persona_name: personaBefore.name })
-            : null;
-        const analysisAfter = personaAfter.workflow_def
-            ? analyzeWorkflow(personaAfter.workflow_def, { persona_id: idAfter, persona_name: personaAfter.name })
-            : null;
+        const nodesBefore = personaBefore.workflow_def ? parseWorkflowDef(personaBefore.workflow_def) : [];
+        const nodesAfter = personaAfter.workflow_def ? parseWorkflowDef(personaAfter.workflow_def) : [];
         // Compare fingerprints
         const fpBefore = personaBefore.workflow_def ? fingerprintPersona(personaBefore) : null;
         const fpAfter = personaAfter.workflow_def ? fingerprintPersona(personaAfter) : null;
         return {
             environment: client["env"].name,
+            status: "DEPRECATED - LLM should compare",
             before: {
                 persona_id: idBefore,
                 name: personaBefore.name,
                 fingerprint: fpBefore,
                 has_workflow: !!personaBefore.workflow_def,
-                node_count: analysisBefore?.summary.total_nodes ?? 0,
-                edge_count: analysisBefore?.summary.total_edges ?? 0,
-                critical_issues: analysisBefore?.issue_summary.critical ?? 0,
-                validation_passed: analysisBefore?.validation_passed ?? false,
+                node_count: nodesBefore.length,
+                workflow_def: personaBefore.workflow_def,
             },
             after: {
                 persona_id: idAfter,
                 name: personaAfter.name,
                 fingerprint: fpAfter,
                 has_workflow: !!personaAfter.workflow_def,
-                node_count: analysisAfter?.summary.total_nodes ?? 0,
-                edge_count: analysisAfter?.summary.total_edges ?? 0,
-                critical_issues: analysisAfter?.issue_summary.critical ?? 0,
-                validation_passed: analysisAfter?.validation_passed ?? false,
+                node_count: nodesAfter.length,
+                workflow_def: personaAfter.workflow_def,
             },
             comparison: {
                 fingerprints_match: fpBefore === fpAfter,
-                node_count_change: (analysisAfter?.summary.total_nodes ?? 0) - (analysisBefore?.summary.total_nodes ?? 0),
-                edge_count_change: (analysisAfter?.summary.total_edges ?? 0) - (analysisBefore?.summary.total_edges ?? 0),
-                critical_issues_change: (analysisAfter?.issue_summary.critical ?? 0) - (analysisBefore?.issue_summary.critical ?? 0),
-                validation_improved: !analysisBefore?.validation_passed && (analysisAfter?.validation_passed ?? false),
-                validation_regressed: (analysisBefore?.validation_passed ?? false) && !analysisAfter?.validation_passed,
+                node_count_change: nodesAfter.length - nodesBefore.length,
+            },
+            _deprecation_notice: {
+                message: "compare_workflow_versions is deprecated. LLM should compare workflows directly.",
+                guidance: "Compare the workflow_def objects returned above. Use ema://rules/anti-patterns to check each.",
             },
-            issues_before: analysisBefore?.issues.slice(0, 5) ?? [],
-            issues_after: analysisAfter?.issues.slice(0, 5) ?? [],
-            recommendations: fpBefore === fpAfter
-                ? ["No workflow changes detected between versions"]
-                : [
-                    analysisAfter?.validation_passed
-                        ? "After version passes validation"
-                        : "After version has validation issues - review before deploying",
-                    (analysisAfter?.issue_summary.critical ?? 0) > (analysisBefore?.issue_summary.critical ?? 0)
-                        ? "Warning: More critical issues in after version"
-                        : (analysisAfter?.issue_summary.critical ?? 0) < (analysisBefore?.issue_summary.critical ?? 0)
-                            ? "Good: Fewer critical issues in after version"
-                            : "Same number of critical issues",
-                ],
         };
     },
     get_workflow_metrics: async (args) => {
@@ -3088,54 +2958,39 @@ const toolHandlers = {
                 error: "AI Employee has no workflow_def",
             };
         }
-        const analysis = analyzeWorkflow(persona.workflow_def, {
-            persona_id: personaId,
-            persona_name: persona.name,
-            environment: client["env"].name,
-        });
-        // Calculate complexity indicators
-        const avgEdgesPerNode = analysis.summary.total_nodes > 0
-            ? (analysis.summary.total_edges / analysis.summary.total_nodes).toFixed(2)
+        const nodes = parseWorkflowDef(persona.workflow_def);
+        const connections = validateWorkflowConnections(persona.workflow_def);
+        // Calculate basic metrics
+        const totalEdges = nodes.reduce((sum, n) => sum + (n.incoming_edges?.length ?? 0), 0);
+        const avgEdgesPerNode = nodes.length > 0
+            ? (totalEdges / nodes.length).toFixed(2)
             : 0;
-        // Estimate parallel vs sequential
-        const hasParallelBranches = analysis.summary.categorizers_count > 0;
+        // Check for categorizers and HITL
+        const categorizerCount = nodes.filter(n => n.action_name?.includes("categorizer")).length;
+        const hitlCount = nodes.filter(n => n.action_name?.includes("hitl") || n.id?.includes("hitl")).length;
+        const hasTrigger = nodes.some(n => n.action_name === "trigger" || n.id === "trigger");
         return {
             environment: client["env"].name,
             persona_id: personaId,
             persona_name: persona.name,
             structure: {
-                total_nodes: analysis.summary.total_nodes,
-                total_edges: analysis.summary.total_edges,
-                has_trigger: analysis.summary.has_trigger,
-                has_workflow_output: analysis.summary.has_workflow_output,
+                total_nodes: nodes.length,
+                total_edges: totalEdges,
+                has_trigger: hasTrigger,
+                connection_count: connections.length,
             },
             routing: {
-                categorizers_count: analysis.summary.categorizers_count,
-                hitl_nodes_count: analysis.summary.hitl_nodes_count,
-                has_parallel_branches: hasParallelBranches,
-            },
-            quality: {
-                validation_passed: analysis.validation_passed,
-                critical_issues: analysis.issue_summary.critical,
-                warnings: analysis.issue_summary.warning,
+                categorizers_count: categorizerCount,
+                hitl_nodes_count: hitlCount,
+                has_parallel_branches: categorizerCount > 0,
             },
             complexity: {
                 avg_edges_per_node: avgEdgesPerNode,
-                complexity_rating: analysis.summary.total_nodes <= 5 ? "simple"
-                    : analysis.summary.total_nodes <= 15 ? "moderate"
+                complexity_rating: nodes.length <= 5 ? "simple"
+                    : nodes.length <= 15 ? "moderate"
                         : "complex",
             },
-            recommendations: [
-                analysis.summary.categorizers_count === 0 && analysis.summary.total_nodes > 3
-                    ? "Consider adding intent routing with chat_categorizer for better user experience"
-                    : null,
-                analysis.summary.hitl_nodes_count === 0
-                    ? "No HITL nodes - consider adding human approval for sensitive actions"
-                    : null,
-                analysis.issue_summary.critical > 0
-                    ? `${analysis.issue_summary.critical} critical issues need attention - use analyze_workflow for details`
-                    : null,
-            ].filter(Boolean),
+            _note: "Use ema://rules/anti-patterns for quality analysis. MCP no longer pre-computes issues.",
         };
     },
     // ─────────────────────────────────────────────────────────────────────────
@@ -3856,7 +3711,7 @@ const toolHandlers = {
         return handleEnv({}, () => getAvailableEnvironments().map(e => ({
             name: e.name,
             isDefault: e.name === getDefaultEnvName(),
-        })), { name: TOOLKIT_NAME, version: TOOLKIT_VERSION });
+        })), { name: TOOLKIT_NAME, version: TOOLKIT_VERSION, commit: TOOLKIT_COMMIT });
     },
     persona: async (args) => {
         const targetEnv = args.env ?? getDefaultEnvName();
@@ -4104,7 +3959,11 @@ const toolHandlers = {
                 name: e.name,
                 isDefault: e.name === getDefaultEnvName(),
             })),
-            toolkit: { name: TOOLKIT_NAME, version: TOOLKIT_VERSION },
+            toolkit: {
+                name: TOOLKIT_NAME,
+                version: TOOLKIT_VERSION,
+                commit: TOOLKIT_COMMIT,
+            },
             client,
         });
     },
@@ -4129,7 +3988,8 @@ const toolHandlers = {
         }
         switch (catalogType) {
             case "actions": {
-                // Route to action handler
+                // API-FIRST: Try API, fall back to static AGENT_CATALOG
+                // Senior review: Use API as primary source for live data
                 if (method === "recommend" && forUseCase) {
                     const suggestions = suggestAgentsForUseCase(forUseCase);
                     return {
@@ -4141,18 +4001,55 @@ const toolHandlers = {
                             : "No specific recommendations. Try browsing with catalog(method=\"list\", type=\"actions\").",
                     };
                 }
+                // Try API first for live data
+                try {
+                    let apiActions = await client.listActions();
+                    if (id) {
+                        const action = apiActions.find(a => a.name === id || a.name?.toLowerCase() === id.toLowerCase());
+                        if (action) {
+                            // Merge with docs from catalog for richer info
+                            const docs = getAgentByName(id);
+                            return {
+                                type: "actions",
+                                action: { ...action, documentation: docs },
+                                source: "api",
+                            };
+                        }
+                        // Fall through to catalog
+                    }
+                    if (category) {
+                        apiActions = apiActions.filter(a => a.category === category);
+                    }
+                    if (query) {
+                        const q = query.toLowerCase();
+                        apiActions = apiActions.filter(a => a.name?.toLowerCase().includes(q) ||
+                            a.category?.toLowerCase().includes(q));
+                    }
+                    return {
+                        type: "actions",
+                        count: apiActions.length,
+                        actions: apiActions.map(a => ({ name: a.name, category: a.category, enabled: a.enabled })),
+                        source: "api",
+                        _tip: "Get details: catalog(method=\"get\", type=\"actions\", id=\"<name>\")",
+                        _next_step: apiActions.length > 0 ? `catalog(method="get", type="actions", id="${apiActions[0].name}")` : undefined,
+                    };
+                }
+                catch {
+                    // Fallback to static catalog
+                }
+                // Fallback: Use static AGENT_CATALOG
                 if (id) {
                     const action = getAgentByName(id);
                     if (!action) {
                         return { error: `Action not found: ${id}` };
                     }
-                    return { type: "actions", action };
+                    return { type: "actions", action, source: "catalog" };
                 }
                 if (category) {
                     const actions = getAgentsByCategory(category);
-                    return { type: "actions", category, count: actions.length, actions };
+                    return { type: "actions", category, count: actions.length, actions, source: "catalog" };
                 }
-                // List all
+                // List all from catalog
                 let actions = Object.values(AGENT_CATALOG);
                 if (query) {
                     const q = query.toLowerCase();
@@ -4164,6 +4061,7 @@ const toolHandlers = {
                     type: "actions",
                     count: actions.length,
                     actions: actions.map(a => ({ name: a.actionName, displayName: a.displayName, category: a.category, description: a.description })),
+                    source: "catalog",
                     _tip: "Get details: catalog(method=\"get\", type=\"actions\", id=\"<name>\")",
                     _next_step: actions.length > 0 ? `catalog(method="get", type="actions", id="${actions[0].actionName}")` : undefined,
                 };
@@ -4316,110 +4214,27 @@ const legacyConsolidateDemoData = toolHandlers.consolidate_demo_data;
 const legacyGenerateDemoDocument = toolHandlers.generate_demo_document;
 const legacyValidateDemoDocument = toolHandlers.validate_demo_document;
 const legacyGetDemoDataTemplate = toolHandlers.get_demo_data_template;
-// Unify workflow modes: generate | analyze | deploy | optimize | compare | compile
+// Workflow tool: MCP provides data (get) and executes (deploy). LLM does all thinking.
 toolHandlers.workflow = async (args) => {
-    // Normalize persona type alias: tool schema uses "type", internal uses "persona_type"
     const normalizedArgs = { ...(args ?? {}) };
-    if (normalizedArgs.persona_type === undefined && normalizedArgs.type !== undefined) {
-        normalizedArgs.persona_type = normalizedArgs.type;
-    }
     const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
     const workflowDef = normalizedArgs.workflow_def;
-    const inputProvided = normalizedArgs.input !== undefined;
-    // Normalize mode aliases
-    const rawMode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
-    const mode = rawMode === "improve" ? "optimize" : rawMode;
-    // Default mode selection:
-    // - persona_id + workflow_def → deploy (direct deployment, no input needed)
-    // - persona_id + input → modify (BROWNFIELD: generate new workflow from input)
-    // - persona_id only or workflow_def → analyze (inspect)
-    // - input only → generate (GREENFIELD: create from scratch)
-    // - Otherwise → generate (and prompt for missing info)
-    const effectiveMode = mode ??
-        (personaId && workflowDef ? "deploy" : // Direct deployment (no input required)
-            personaId && inputProvided ? "modify" : // BROWNFIELD: existing persona + new requirements
-                workflowDef || personaId ? "analyze" : // Inspect existing
-                    "generate"); // GREENFIELD: new workflow
-    switch (effectiveMode) {
-        case "generate": {
-            const result = await legacyWorkflowTool({ ...normalizedArgs, mode: "generate" });
-            // Ensure next_steps point at consolidated tools by default
-            if (result && typeof result === "object") {
-                const obj = result;
-                const persona_id = obj.persona_id ? String(obj.persona_id) : personaId;
-                const deployed = obj.deployed === true;
-                obj.next_steps = deployed
-                    ? persona_id
-                        ? [`Verify: persona(id="${persona_id}", include_workflow=true)`]
-                        : ["Verify the deployed AI Employee in the Ema UI"]
-                    : persona_id
-                        ? [
-                            `Deploy: workflow(mode="deploy", persona_id="${persona_id}", workflow_def=<workflow_def>, proto_config=<proto_config>)`,
-                            `Verify: persona(id="${persona_id}", include_workflow=true)`,
-                        ]
-                        : [
-                            "Create an AI Employee in Ema, then deploy:",
-                            `workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>)`,
-                        ];
-            }
-            return result;
-        }
-        case "analyze": {
-            const include = Array.isArray(normalizedArgs.include)
-                ? normalizedArgs.include.map(String)
-                : ["issues", "connections", "fixes", "metrics"];
-            let wf = workflowDef;
-            let meta;
-            if (!wf && personaId) {
-                const client = createClient(normalizedArgs.env);
-                const persona = await client.getPersonaById(personaId);
-                if (!persona)
-                    throw new Error(`AI Employee not found: ${personaId}`);
-                wf = persona.workflow_def;
-                meta = {
-                    persona_id: personaId,
-                    persona_name: persona.name,
-                    environment: client["env"].name,
-                };
-            }
-            if (!wf) {
-                return {
-                    error: "Missing workflow to analyze. Provide persona_id or workflow_def.",
-                    hint: 'Examples: workflow(mode="analyze", persona_id="...") or workflow(mode="analyze", workflow_def={...})',
-                };
-            }
-            const out = { mode: "analyze", ...(meta ?? {}) };
-            // Issues + summary (source of truth)
-            const issuesResult = await legacyDetectWorkflowIssues({ workflow_def: wf });
-            const issues = issuesResult.issues;
-            if (include.includes("issues")) {
-                out.issues = issuesResult.issues;
-                out.issue_summary = issuesResult.summary;
-                out.validation_passed = issuesResult.validation_passed;
-            }
-            if (include.includes("connections")) {
-                out.connections = await legacyValidateWorkflowConnections({ workflow_def: wf });
-            }
-            if (include.includes("fixes")) {
-                out.fixes = Array.isArray(issues) ? await legacySuggestWorkflowFixes({ issues }) : { error: "No issues array available to generate fixes" };
-            }
-            if (include.includes("metrics")) {
-                const actions = wf.actions ?? [];
-                const edges = wf.edges ?? [];
-                out.metrics = {
-                    node_count: Array.isArray(actions) ? actions.length : 0,
-                    edge_count: Array.isArray(edges) ? edges.length : 0,
-                };
-            }
-            return out;
+    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
+    // Route to handleWorkflow for get/deploy (the only public modes)
+    const client = createClient(normalizedArgs.env);
+    switch (mode) {
+        case "get": {
+            // Return workflow data for LLM to analyze/modify
+            return handleWorkflow({
+                mode: "get",
+                persona_id: personaId,
+                env: normalizedArgs.env,
+            }, client, () => undefined);
         }
         case "deploy": {
             if (!personaId) {
-                throw new Error('persona_id is required for workflow(mode="deploy")');
+                return { error: 'persona_id is required for workflow(mode="deploy")' };
             }
-            // Use clean deploy path via handleWorkflow (no brownfield merge, no excessive validation)
-            // User can still request validation via validate=true, but default is now direct deploy
-            const client = createClient(normalizedArgs.env);
             // Optional: pre-deploy version snapshot
             const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
             let versionCreated;
@@ -4445,8 +4260,7 @@ toolHandlers.workflow = async (args) => {
             catch {
                 // Version tracking is best-effort
             }
-            // Route to clean handleWorkflow deploy (handlers-consolidated.ts)
-            // This path: sanitizes workflow → calls client.updateAiEmployee → done
+            // Route to handleWorkflow deploy
             const deployResult = await handleWorkflow({
                 mode: "deploy",
                 persona_id: personaId,
@@ -4460,58 +4274,25 @@ toolHandlers.workflow = async (args) => {
             }
             return deployResult;
         }
-        case "optimize": {
-            // optimize_workflow supports both:
-            // - fix mode: id (name/id) OR persona_id
-            // - generate mode: persona_id + prompt
-            const preview = normalizedArgs.preview === true;
-            const id = normalizedArgs.id ? String(normalizedArgs.id) : undefined;
-            const identifier = normalizedArgs.identifier ? String(normalizedArgs.identifier) : undefined; // deprecated alias
-            const idOrIdentifier = id ?? identifier;
-            // If a natural-language workflow "input" is provided, treat it as a prompt to optimize_workflow.
-            const input = normalizedArgs.input;
-            const prompt = typeof input === "string" ? input : undefined;
-            return legacyOptimizeWorkflow({
-                identifier: idOrIdentifier ?? personaId,
-                persona_id: personaId,
-                prompt,
-                type: normalizedArgs.persona_type,
-                preview,
-                env: normalizedArgs.env,
-            });
-        }
-        case "compare": {
-            if (!personaId) {
-                throw new Error('persona_id is required for workflow(mode="compare")');
-            }
-            const compareTo = normalizedArgs.compare_to ? String(normalizedArgs.compare_to) : undefined;
-            if (!compareTo) {
-                throw new Error('compare_to is required for workflow(mode="compare")');
-            }
-            return legacyCompareWorkflowVersions({
-                persona_id_before: personaId,
-                persona_id_after: compareTo,
-                env: normalizedArgs.env,
-            });
-        }
-        case "compile": {
-            // Compile requires node specs + result mappings.
-            if (!normalizedArgs.name || !normalizedArgs.description) {
-                throw new Error('workflow(mode="compile") requires name and description');
-            }
-            if (!normalizedArgs.persona_type) {
-                throw new Error('workflow(mode="compile") requires persona type via type="voice|chat|dashboard"');
-            }
-            return legacyCompileWorkflow({
-                name: normalizedArgs.name,
-                description: normalizedArgs.description,
-                persona_type: normalizedArgs.persona_type,
-                nodes: normalizedArgs.nodes,
-                result_mappings: normalizedArgs.result_mappings,
-            });
+        // REMOVED modes - LLM does these
+        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", "deploy"],
+            };
         }
         default: {
-            return legacyWorkflowTool({ ...normalizedArgs, mode: effectiveMode });
+            // No mode or unknown mode - require explicit mode
+            return {
+                error: `Mode required. Valid modes: get, deploy`,
+                hint: "workflow(mode='get') returns data for LLM. workflow(mode='deploy') executes LLM's workflow_def.",
+                example: `workflow(mode="get", persona_id="...")`,
+            };
         }
     }
 };
@@ -5017,7 +4798,11 @@ export async function startMcpServer() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("Ema MCP Server started (multi-env) with prompts and resources");
+    // Log startup with version and commit info
+    const buildInfo = TOOLKIT_COMMIT
+        ? `${TOOLKIT_VERSION} (${TOOLKIT_COMMIT})`
+        : TOOLKIT_VERSION;
+    console.error(`Ema MCP Server started: ${TOOLKIT_NAME}@${buildInfo}`);
 }
 startMcpServer().catch((error) => {
     console.error("Failed to start MCP server:", error);