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

package/dist/mcp/server.js

@@ -41,22 +41,22 @@ import { createVersionPolicyEngine } from "../sdk/version-policy.js";
 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, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
+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";
+// 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)
 import { compileWorkflow, } from "../sdk/workflow-generator.js";
 // V2 Tools (4 tools: persona, catalog, sync, env) - NEW DEFAULT
-import { generateToolsV2, } from "./tools-v2.js";
-// V1 Consolidated Tools (7 mode-based tools) - BACKWARDS COMPAT
-import { generateConsolidatedTools, } from "./tools-consolidated.js";
-// Legacy Tools (get_persona, find_personas, etc.) - DEPRECATED
-import { generateLegacyTools, } from "./tools-legacy.js";
-// Feature flags for tool versions
-// V2 is default (4 tools), set EMA_ENABLE_V1_TOOLS=true for 7-tool mode-based interface
-const ENABLE_V1_TOOLS = process.env.EMA_ENABLE_V1_TOOLS === "true";
-const ENABLE_LEGACY_TOOLS = process.env.EMA_ENABLE_LEGACY_TOOLS === "true";
-import { handleEnv, handlePersona, handleWorkflow, handleAction, handleData, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+import { generateTools, } from "./tools.js";
+import { handleEnv, handlePersona, 
+// handleWorkflow - removed, now using extracted handler from ./handlers/workflow/index.js
+handleAction, 
+// handleData - removed, now using extracted handler from ./handlers/data/index.js
+handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+// Import extracted handlers
+import { handleWorkflow } from "./handlers/workflow/index.js";
 // Import from handler utilities (normalizeTriggerType uses generated enum labels)
 import { normalizeTriggerType } from "./handlers/utils.js";
 // Import from SDK proto-config (CANONICAL widget validation and merging)
@@ -92,6 +92,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 +114,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 = [];
@@ -1093,102 +1107,46 @@ function withEnvParam(props, required = []) {
 // Tool Definitions
 // ─────────────────────────────────────────────────────────────────────────────
 //
-// TOOL STRUCTURE:
-// 1. CONSOLIDATED TOOLS (9 tools) - Unix CLI pattern with flags
-//    - env, persona, workflow, action, template, knowledge, reference, sync, demo
-//    - Defined in: ./tools-consolidated.ts
-//
-// 2. LEGACY TOOLS (40+ tools) - Old separate tools for backwards compatibility  
-//    - Defined in: ./tools-legacy.ts
-//    - Enable with EMA_ENABLE_LEGACY_TOOLS=true
+// V2 TOOLS (5 tools) - LLM-optimized minimal interface
+//   - env, persona, catalog, workflow, sync
+//   - Defined in: ./tools.ts
 //
 // NAMING CONVENTION:
-// - Tool names are defined as BASE NAMES (e.g., "persona", "list_ai_employees")
+// - Tool names are defined as BASE NAMES (e.g., "persona")
 // - MCP clients prefix with "mcp_{server}_" (e.g., "mcp_ema_persona")
 //
 // ─────────────────────────────────────────────────────────────────────────────
 /**
- * Generate all available tools based on configuration
+ * Generate all available tools
  *
- * Tool versions:
- * - V2 (default): 4 tools (persona, catalog, sync, env) - LLM-optimized
- * - V1: 7 mode-based tools - set EMA_ENABLE_V1_TOOLS=true
- * - Legacy: Individual tools - set EMA_ENABLE_LEGACY_TOOLS=true
+ * V2: 5 tools (persona, catalog, workflow, sync, env) - LLM-optimized
  *
- * Why V2 by default:
+ * Why V2:
  * - Minimal tool count optimizes LLM tool selection
  * - Data operations under persona (always persona-scoped)
  * - Catalog consolidates all reference data (actions, templates, etc.)
- * - Clear separation: entity (persona), reference (catalog), operation (sync)
+ * - Clear separation: entity (persona), reference (catalog), operation (sync, workflow)
  */
 function generateAllTools() {
     const envNames = getAvailableEnvironments().map(e => e.name);
     const defaultEnv = getDefaultEnvName();
-    // V1 mode-based tools (for backwards compat)
-    if (ENABLE_V1_TOOLS) {
-        console.error("[MCP] V1 mode-based tools enabled via EMA_ENABLE_V1_TOOLS=true");
-        const consolidatedTools = generateConsolidatedTools(envNames, defaultEnv);
-        if (ENABLE_LEGACY_TOOLS) {
-            console.error("[MCP] WARNING: Legacy tools also enabled");
-            const legacyTools = generateLegacyTools(envNames, defaultEnv);
-            return [...consolidatedTools, ...legacyTools];
-        }
-        return consolidatedTools;
-    }
-    // V2 minimal tools (default) - 4 tools: persona, catalog, sync, env
-    const v2Tools = generateToolsV2(envNames, defaultEnv);
-    if (ENABLE_LEGACY_TOOLS) {
-        console.error("[MCP] WARNING: Legacy tools enabled alongside V2");
-        const legacyTools = generateLegacyTools(envNames, defaultEnv);
-        return [...v2Tools, ...legacyTools];
-    }
-    return v2Tools;
+    return generateTools(envNames, defaultEnv);
 }
 // Generate tools (called once at module load)
 const TOOLS = generateAllTools();
 // ─────────────────────────────────────────────────────────────────────────────
-// ADDITIONAL TOOLS (not in consolidated or legacy)
-// These are special-purpose tools that don't fit the standard patterns
+// ADDITIONAL TOOLS (special-purpose inline tools)
+// These handle specific operations that don't fit the V2 pattern
 // ─────────────────────────────────────────────────────────────────────────────
 const ADDITIONAL_TOOLS = [
-    // ─────────────────────────────────────────────────────────────────────────
-    // NOTE: Legacy tools (get_persona, find_personas, create_ai_employee, etc.)
-    // have been moved to ./tools-legacy.ts for backwards compatibility.
-    //
-    // Consolidated tools (persona, workflow, action, etc.) are generated from
-    // ./tools-consolidated.ts following Unix CLI patterns.
+    // NOTE: Tools (persona, catalog, workflow, sync, env) are in ./tools.ts
     //
-    // Only special-purpose tools remain here:
-    // - "workflow" (unified tool) - experimental, bridges old and new patterns
-    // - Demo data tools - special-purpose data generation
-    // ─────────────────────────────────────────────────────────────────────────
-    // INLINE LEGACY TOOLS REMOVED
-    // All legacy tools (get_workflow_action, find_workflow_actions, compare_ai_employees,
-    // list_ai_employee_templates, sync, sync_info, list_auto_builder_agents, etc.)
-    // have been moved to ./tools-legacy.ts
-    // ─────────────────────────────────────────────────────────────────────────
-    // ─────────────────────────────────────────────────────────────────────────────
-    // LEGACY INLINE TOOLS REMOVED - See ./tools-legacy.ts
-    // ─────────────────────────────────────────────────────────────────────────────
-    // The following tools have been removed from this file and are now generated
-    // from tools-legacy.ts: list_auto_builder_agents, get_auto_builder_agent,
-    // suggest_agents_for_use_case, get_workflow_pattern, list_workflow_patterns,
-    // check_type_compatibility, get_widget_reference, get_qualifying_questions,
-    // get_voice_persona_template, validate_workflow_prompt, get_auto_builder_guidance,
-    // get_platform_concept, list_platform_concepts, get_common_mistakes,
-    // get_debug_checklist, get_workflow_execution_model, analyze_workflow,
-    // detect_workflow_issues, validate_workflow_connections, suggest_workflow_fixes,
-    // compare_workflow_versions, get_workflow_metrics, compile_workflow,
-    // upload_data_source, delete_data_source, list_data_sources, get_embedding_status,
+    // Special-purpose tools here:
+    // - compile_workflow - Direct workflow compilation
+    // - Demo data tools - RAG document generation/validation
+    // - Data source tools - Upload/delete/manage knowledge sources
     // toggle_embedding
     // ─────────────────────────────────────────────────────────────────────────────
-    // The remaining legacy tools are handled by the LEGACY_TOOL_MAPPING in
-    // tools-consolidated.ts for routing to consolidated handlers.
-    //
-    // INLINE DEFINITIONS REMOVED - They are now in tools-legacy.ts
-    // (analyze_workflow, detect_workflow_issues, validate_workflow_connections, suggest_workflow_fixes)
-    // (compare_workflow_versions, get_workflow_metrics) - moved to tools-legacy.ts
-    // ─────────────────────────────────────────────────────────────────────────────
     // Workflow Compilation - Template-driven, no biased patterns
     // Read ema://catalog/patterns for pattern references, then construct nodes
     // ─────────────────────────────────────────────────────────────────────────────
@@ -1606,11 +1564,6 @@ Returns:
             required: ["entity_type"],
         },
     },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // CONSOLIDATED TOOLS (Unix CLI pattern)
-    // These 9 tools follow Unix conventions: single command with flags
-    // ═══════════════════════════════════════════════════════════════════════════
-    ...generateConsolidatedTools(getAvailableEnvironments().map(e => e.name), getDefaultEnvName()),
 ];
 const toolHandlers = {
     // Environment Management
@@ -1980,19 +1933,29 @@ const toolHandlers = {
             if (!analysis.validation_passed) {
                 validationResults.valid = false;
                 validationResults.issues = analysis.issues ?? [];
-                // Auto-fix if enabled
+                // Auto-fix handling (DEPRECATED - returns suggestions instead of auto-applying)
                 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, {
+                    // DEPRECATED: autoFix no longer auto-applies fixes.
+                    // Per LLM-driven architecture, MCP returns suggestions for Agent to apply.
+                    return {
+                        environment: client["env"].name,
+                        success: false,
                         persona_id: personaId,
-                        persona_name: persona.name ?? "Unknown"
-                    });
-                    validationResults.valid = reAnalysis.validation_passed;
-                    validationResults.issues = reAnalysis.issues ?? [];
+                        persona_name: persona.name,
+                        validation_failed: true,
+                        issues: validationResults.issues,
+                        // Return suggestions instead of applying fixes
+                        suggestions: validationResults.issues.map(issue => ({
+                            issue_type: issue.type,
+                            severity: issue.severity,
+                            node: issue.node,
+                            reason: issue.reason,
+                            suggested_action: `Fix "${issue.type}" on node "${issue.node ?? 'workflow'}": ${issue.reason}`,
+                        })),
+                        applied_fixes: [], // Empty - no longer auto-applying
+                        _deprecated: "autoFix is deprecated. Fixes are no longer auto-applied. Use the suggestions to build explicit workflow modifications.",
+                        _tip: "Apply fixes using: persona(id=\"...\", operations=[{type:\"rewire\", ...}]) or persona(id=\"...\", workflow_spec={...})",
+                    };
                 }
             }
         }
@@ -2207,130 +2170,62 @@ const toolHandlers = {
             }
             return result;
         }
-        // Step 3: Apply fixes
-        let fixedWorkflow = workflowDef;
+        // Step 3: Return suggestions instead of auto-applying (DEPRECATED behavior)
+        // Per LLM-driven architecture, MCP returns suggestions for Agent to apply.
+        const suggestions = issues.map(issue => ({
+            issue_type: issue.type,
+            severity: issue.severity,
+            node: issue.node,
+            reason: issue.reason,
+            suggested_action: `Fix "${issue.type}" on node "${issue.node ?? 'workflow'}": ${issue.reason}`,
+        }));
+        // DEPRECATED: No longer auto-apply fixes
+        // The appliedFixes array is now always empty
         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 fixedWorkflow = workflowDef; // Workflow unchanged
+        // No re-analysis needed since we don't auto-fix
+        const remainingIssues = issues;
         const remainingCritical = remainingIssues.filter(i => i.severity === "critical");
-        // If preview mode, show what would happen without deploying
+        // If preview mode, show suggestions (DEPRECATED: no longer auto-applies)
         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",
+                status: "📋 Preview - Suggestions Available",
                 mode: "optimize",
                 nodes: fixedWorkflow.actions?.length ?? 0,
                 found_issues: issues.length,
-                can_fix: fixedCount,
-                cannot_fix: failedCount,
-                ready_to_deploy: remainingCritical.length === 0,
+                // Return suggestions instead of applied fixes
+                suggestions: suggestions,
                 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.`,
+                applied_fixes: [], // Empty - no longer auto-applying
+                _deprecated: "Auto-fix is deprecated. Review suggestions and apply fixes explicitly.",
+                _tip: "Apply fixes using: persona(id=\"...\", operations=[...]) or use Ema UI Auto Builder",
             };
             if (enhancementPrompt) {
-                previewResult.enhancement_note = `Enhancement "${enhancementPrompt}" noted. Auto-fixes will be applied first; use Ema UI Auto Builder for the enhancement.`;
+                previewResult.enhancement_note = `Enhancement "${enhancementPrompt}" noted. Use Ema UI Auto Builder to make this change.`;
             }
             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 = {
-            persona_id: personaId,
-            proto_config: mergedProtoConfig,
-            workflow: fixedWorkflow,
+        // Step 4: Return suggestions for issues (DEPRECATED: no longer auto-deploys)
+        // Per LLM-driven architecture, return suggestions for Agent to review and apply
+        // The Agent should use explicit operations to apply fixes, then deploy separately.
+        return {
+            success: true,
+            persona: persona.name,
+            status: remainingCritical.length > 0
+                ? "⚠️ Issues Found - Review Suggestions"
+                : "📋 Minor Issues - Review Suggestions",
+            found_issues: issues.length,
+            critical_issues: remainingCritical.length,
+            suggestions: suggestions,
+            applied_fixes: [], // Empty - no longer auto-applying
+            _deprecated: "Auto-fix and auto-deploy are deprecated. Review suggestions and apply fixes explicitly.",
+            _tip: remainingCritical.length > 0
+                ? "Critical issues found. Review suggestions and fix in Ema UI Auto Builder or use explicit operations."
+                : "Apply fixes using: persona(id=\"...\", operations=[...]) or use Ema UI Auto Builder",
         };
-        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.",
-            };
-        }
+        // Note: Auto-deploy code removed (was dead code after deprecation)
     },
     // ─────────────────────────────────────────────────────────────────────────
     // Action Handlers (Consolidated)
@@ -2826,10 +2721,14 @@ const toolHandlers = {
         };
     },
     get_voice_persona_template: async () => {
+        // Use generated fallback from proto definitions
+        // In production, prefer API templates via client.getPersonaTemplates()
+        const template = getTemplateFallback("voice");
         return {
-            template: VOICE_PERSONA_TEMPLATE,
-            required_fields: ["welcomeMessage", "identityAndPurpose", "takeActionInstructions", "hangupInstructions"],
-            optional_fields: ["transferCallInstructions", "speechCharacteristics", "systemPrompt", "formFillingInstructions", "waitMessage"],
+            template: template || VOICE_TEMPLATE_FALLBACK,
+            field_docs: getTemplateFieldDocs("voice"),
+            required_fields: ["conversationSettings.welcomeMessage", "conversationSettings.identityAndPurpose", "conversationSettings.takeActionInstructions", "conversationSettings.hangupInstructions"],
+            optional_fields: ["conversationSettings.transferCallInstructions", "conversationSettings.speechCharacteristics", "conversationSettings.systemPrompt", "conversationSettings.formFillingInstructions", "conversationSettings.waitMessage"],
             project_type: PROJECT_TYPES.voice,
             widget_ids: {
                 voiceSettings: 38,
@@ -2837,12 +2736,8 @@ const toolHandlers = {
                 vadSettings: 43,
                 dataStorageSettings: 42,
             },
-            instructions: [
-                "Replace all {placeholder} values with actual content",
-                "takeActionInstructions uses </Case N> format for each action",
-                "speechCharacteristics should include TTS pronunciation rules",
-                "systemPrompt defines tool calling behavior",
-            ],
+            _source: "generated_fallback",
+            _note: "This template is auto-generated from proto definitions. For live templates, use client.getPersonaTemplates().",
         };
     },
     validate_workflow_prompt: async (args) => {
@@ -4049,28 +3944,32 @@ const toolHandlers = {
                 const { handleData: handleDataNew } = await import("./handlers/data/index.js");
                 return handleDataNew({ persona_id: personaId, env: args.env, data }, client);
             }
-            // LEGACY FLAG FORMAT (backwards compatibility)
+            // LEGACY FLAG FORMAT (backwards compatibility) - use extracted handler
+            const { handleData: handleDataExtracted } = await import("./handlers/data/index.js");
+            const readFileFn = (path) => fs.readFile(path);
             if (data.list === true) {
-                return handleData({ mode: "list", persona_id: personaId, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "list", persona_id: personaId, env: args.env }, client, readFileFn);
             }
             if (typeof data.upload === "string") {
-                return handleData({ mode: "upload", persona_id: personaId, file: data.upload, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "upload", persona_id: personaId, data: { path: data.upload }, env: args.env }, client, readFileFn);
             }
             if (typeof data.delete === "string") {
-                return handleData({ mode: "delete", persona_id: personaId, file_id: data.delete, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "delete", persona_id: personaId, data: { file_id: data.delete }, env: args.env }, client, readFileFn);
             }
             if (typeof data.generate === "string" || data.template) {
-                return handleData({
-                    mode: "generate",
+                return handleDataExtracted({
+                    method: "generate",
                     persona_id: personaId,
-                    input: data.generate,
-                    from: data.template,
-                    count: data.count,
+                    data: {
+                        input: data.generate,
+                        from: data.template,
+                        count: data.count,
+                    },
                     env: args.env
-                }, client, (path) => fs.readFile(path));
+                }, client, readFileFn);
             }
             if (typeof data.embed === "boolean") {
-                return handleData({ mode: "embedding", persona_id: personaId, enabled: data.embed, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "embedding", persona_id: personaId, data: { enabled: data.embed }, env: args.env }, client, readFileFn);
             }
             if (typeof data.search === "string") {
                 return handleKnowledge({ mode: "search", persona_id: personaId, query: data.search, env: args.env }, client, (path) => fs.readFile(path));
@@ -4149,7 +4048,9 @@ const toolHandlers = {
     data: async (args) => {
         const client = createClient(args.env);
         const fs = await import("fs/promises");
-        return handleData(args, client, (path) => fs.readFile(path));
+        // Use extracted handler
+        const { handleData: handleDataExtracted } = await import("./handlers/data/index.js");
+        return handleDataExtracted(args, client, (path) => fs.readFile(path));
     },
     reference: async (args) => {
         // v2: expanded reference handler with envs, actions, templates, patterns support
@@ -4169,9 +4070,11 @@ const toolHandlers = {
     // catalog: Consolidated reference data (actions, templates, widgets, voices, patterns, concepts)
     catalog: async (args) => {
         const catalogType = args.type;
+        const method = args.method;
         const id = args.id;
         const query = args.query;
-        const recommend = args.recommend;
+        // Note: schema uses 'for' parameter for recommend (not 'recommend')
+        const forUseCase = args.for;
         const category = args.category;
         const client = createClient(args.env);
         if (!catalogType) {
@@ -4183,9 +4086,16 @@ const toolHandlers = {
         switch (catalogType) {
             case "actions": {
                 // Route to action handler
-                if (recommend) {
-                    const suggestions = suggestAgentsForUseCase(recommend);
-                    return { type: "actions", use_case: recommend, recommendations: suggestions };
+                if (method === "recommend" && forUseCase) {
+                    const suggestions = suggestAgentsForUseCase(forUseCase);
+                    return {
+                        type: "actions",
+                        use_case: forUseCase,
+                        recommendations: suggestions,
+                        _tip: suggestions.length > 0
+                            ? `Found ${suggestions.length} relevant agents. Use catalog(method="get", type="actions", id="<name>") for details.`
+                            : "No specific recommendations. Try browsing with catalog(method=\"list\", type=\"actions\").",
+                    };
                 }
                 if (id) {
                     const action = getAgentByName(id);
@@ -4209,7 +4119,9 @@ const toolHandlers = {
                 return {
                     type: "actions",
                     count: actions.length,
-                    actions: actions.map(a => ({ name: a.actionName, displayName: a.displayName, category: a.category, description: a.description }))
+                    actions: actions.map(a => ({ name: a.actionName, displayName: a.displayName, category: a.category, description: a.description })),
+                    _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,
                 };
             }
             case "templates": {
@@ -4231,7 +4143,13 @@ const toolHandlers = {
                 return {
                     type: "templates",
                     count: filtered.length,
-                    templates: filtered.map(t => ({ id: t.id, name: t.name, description: t.description }))
+                    templates: filtered.map(t => ({ id: t.id, name: t.name, description: t.description })),
+                    _tip: filtered.length > 0
+                        ? "Create from template: persona(method=\"create\", name=\"My AI\", from=\"<template_id>\")"
+                        : "No templates found. Create from scratch: persona(method=\"create\", name=\"My AI\", type=\"voice|chat|dashboard\")",
+                    _next_step: filtered.length > 0
+                        ? `catalog(method="get", type="templates", id="${filtered[0].id}")`
+                        : undefined,
                 };
             }
             case "widgets": {
@@ -4266,13 +4184,20 @@ const toolHandlers = {
                 };
             }
             case "patterns": {
-                if (recommend) {
+                if (method === "recommend" && forUseCase) {
                     // Find patterns matching use case
-                    const q = recommend.toLowerCase();
+                    const q = forUseCase.toLowerCase();
                     const matches = WORKFLOW_PATTERNS.filter(p => p.name.toLowerCase().includes(q) ||
                         p.description.toLowerCase().includes(q) ||
                         p.useCase.toLowerCase().includes(q));
-                    return { type: "patterns", use_case: recommend, recommendations: matches };
+                    return {
+                        type: "patterns",
+                        use_case: forUseCase,
+                        recommendations: matches,
+                        _tip: matches.length > 0
+                            ? `Found ${matches.length} matching patterns. Use catalog(method="get", type="patterns", id="<name>") for full details.`
+                            : "No matching patterns. Try catalog(method=\"list\", type=\"patterns\") to see all available.",
+                    };
                 }
                 if (id) {
                     const pattern = WORKFLOW_PATTERNS.find(p => p.name === id);
@@ -4324,14 +4249,14 @@ const toolHandlers = {
     // Note: demo is handled via a consolidated adapter below
 };
 // ─────────────────────────────────────────────────────────────────────────────
-// Consolidated Tool Adapters (contract ↔ implementation)
+// V2 Tool Adapters (contract ↔ implementation)
 // ─────────────────────────────────────────────────────────────────────────────
 //
-// The tool schemas in tools-consolidated.ts are the public MCP contract.
-// This file still contains a number of proven "legacy" handlers that we reuse
+// The tool schemas in tools.ts are the public MCP contract.
+// This file still contains proven handlers that we reuse
 // (e.g. deploy_workflow, optimize_workflow, compile_workflow, etc.).
 //
-// These adapters ensure the consolidated tool surface behaves as documented,
+// These adapters ensure the V2 tool surface behaves as documented,
 // while preserving the existing internal implementations.
 const legacyWorkflowTool = toolHandlers.workflow;
 const legacyDeployWorkflow = toolHandlers.deploy_workflow;
@@ -4347,110 +4272,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;
@@ -4476,8 +4318,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,
@@ -4491,58 +4332,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="...")`,
+            };
         }
     }
 };
@@ -4904,8 +4712,8 @@ function determineOperation(toolName, args) {
     if (toolName === "catalog") {
         if (args.id)
             return "get";
-        if (args.recommend)
-            return "recommend";
+        if (args.for)
+            return "recommend"; // V2 schema uses 'for' parameter
         if (args.query)
             return "search";
         return "list";