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

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)
@@ -1923,40 +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 handling (DEPRECATED - returns suggestions instead of auto-applying)
-                if (autoFix && validationResults.issues.length > 0) {
-                    // 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,
-                        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={...})",
-                    };
-                }
+            // 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
@@ -2148,84 +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: 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 = [];
-        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 suggestions (DEPRECATED: no longer auto-applies)
-        if (preview) {
-            const previewResult = {
-                success: true,
-                persona: persona.name,
-                status: "📋 Preview - Suggestions Available",
-                mode: "optimize",
-                nodes: fixedWorkflow.actions?.length ?? 0,
-                found_issues: issues.length,
-                // 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"],
-                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. Use Ema UI Auto Builder to make this change.`;
-            }
-            return previewResult;
-        }
-        // 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.
+        // 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,
-            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",
+            persona: persona?.name ?? "Unknown",
+            persona_id: personaId,
+            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={...})",
+                ],
+            },
         };
-        // Note: Auto-deploy code removed (was dead code after deprecation)
     },
     // ─────────────────────────────────────────────────────────────────────────
     // Action Handlers (Consolidated)
@@ -2840,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 {
@@ -2881,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) => {
@@ -2932,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);
@@ -2975,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) => {
@@ -3044,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.",
         };
     },
     // ─────────────────────────────────────────────────────────────────────────
@@ -3812,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();
@@ -4060,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,
         });
     },
@@ -4085,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 {
@@ -4097,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();
@@ -4120,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,
                 };
@@ -4856,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);