@ema.co/mcp-toolkit 2026.2.13 → 2026.2.19

package/dist/mcp/handlers/persona/intent.js

@@ -1,141 +0,0 @@
-/**
- * Persona INTENT mode handler
- *
- * Exposes the Intent Architect for direct invocation.
- * Supports iterative qualification via previous_answers.
- *
- * Applies to BOTH greenfield AND brownfield scenarios:
- * - Greenfield: Creating new complex personas
- * - Brownfield: Complex modifications to existing personas (may have ripple effects)
- *
- * Flow:
- * 1. First call: Analyze complexity, return questions or prompt
- * 2. Iterative calls: Provide answers, refine until ready
- * 3. Final: Return IntentSpec for downstream WorkflowSpec generation/modification
- */
-import { resolvePersona } from "../utils.js";
-import { runIntentArchitect, } from "../../domain/intent-architect.js";
-/**
- * Handle persona(mode="intent") - direct Intent Architect invocation
- *
- * @param args.input - Natural language description (required)
- * @param args.id - Existing persona ID for brownfield modifications
- * @param args.type - Persona type hint (voice/chat/dashboard)
- * @param args.previous_answers - Answers to qualification questions (iterative)
- * @param args.iteration - Iteration number (1 = first)
- * @param args.max_complexity - Cap complexity level for gradual rollout
- */
-export async function handleIntent(args, client) {
-    const input = args.input;
-    const existingPersonaId = (args.id ?? args.identifier);
-    if (!input) {
-        return {
-            status: "error",
-            error: "input required for intent mode",
-            hint: "Provide natural language description: persona(mode=\"intent\", input=\"Add email capability...\")",
-            examples: [
-                "Greenfield: persona(mode=\"intent\", input=\"Voice AI SDR that qualifies leads\", type=\"voice\")",
-                "Brownfield: persona(mode=\"intent\", input=\"Send emails with discussion items\", id=\"abc-123\")",
-            ],
-        };
-    }
-    // Extract parameters
-    let personaType = args.type;
-    const previousAnswers = args.previous_answers;
-    const iteration = args.iteration;
-    const maxComplexity = args.max_complexity;
-    // Brownfield: Resolve existing persona for context
-    let existingPersonaContext;
-    if (existingPersonaId) {
-        const persona = await resolvePersona(client, existingPersonaId);
-        if (persona) {
-            existingPersonaContext = {
-                id: persona.id,
-                name: persona.name ?? "Unknown",
-                type: persona.trigger_type ?? "unknown",
-            };
-            // Infer type from existing persona if not specified
-            if (!personaType && persona.trigger_type) {
-                const typeMap = {
-                    "5": "voice", "voice": "voice",
-                    "1": "chat", "chat": "chat",
-                    "2": "dashboard", "dashboard": "dashboard",
-                };
-                personaType = typeMap[String(persona.trigger_type)] ?? undefined;
-            }
-        }
-    }
-    // Determine if this is greenfield or brownfield
-    const isBrownfield = !!existingPersonaContext;
-    // Call the canonical SDK entrypoint
-    const result = runIntentArchitect(input, { persona_type: personaType }, {
-        previous_answers: previousAnswers,
-        iteration: iteration ?? 1,
-        max_complexity: maxComplexity,
-    });
-    // Build base response with context
-    const baseResponse = {
-        assessment: result.assessment,
-        strategy: result.strategy,
-        context: isBrownfield ? {
-            mode: "brownfield",
-            existing_persona: existingPersonaContext,
-        } : {
-            mode: "greenfield",
-        },
-    };
-    // Format response based on strategy
-    if (result.strategy.can_proceed) {
-        // Ready to proceed - return IntentSpec
-        const nextStep = isBrownfield
-            ? `Use intent_spec to modify existing persona. Steps:\n` +
-                `1. Get current state: persona(mode="analyze", id="${existingPersonaContext?.id}")\n` +
-                `2. LLM transforms IntentSpec + current workflow_spec → modified WorkflowSpec\n` +
-                `3. Deploy: persona(mode="update", id="${existingPersonaContext?.id}", workflow_spec=...)`
-            : `Use intent_spec to create WorkflowSpec. Options:\n` +
-                `1. LLM transforms IntentSpec → WorkflowSpec (recommended)\n` +
-                `2. Call persona(mode="create", workflow_spec=...) to deploy`;
-        return {
-            status: "ready",
-            ...baseResponse,
-            intent_spec: result.intentSpec,
-            next_step: nextStep,
-        };
-    }
-    if (result.questions && result.questions.length > 0) {
-        // Needs qualification - return questions
-        const idParam = isBrownfield ? `, id="${existingPersonaContext?.id}"` : "";
-        return {
-            status: "needs_qualification",
-            ...baseResponse,
-            questions: result.questions,
-            gates_blocking: result.strategy.gates_to_ask,
-            next_step: result.strategy.next_step,
-            hint: `Answer the questions and call again with previous_answers:\n` +
-                `persona(mode="intent", input="${input.substring(0, 50)}..."${idParam}, previous_answers={...}, iteration=${(iteration ?? 1) + 1})`,
-        };
-    }
-    if (result.prompt_package) {
-        // Complex - return prompt for LLM
-        const deployStep = isBrownfield
-            ? `3. Transform IntentSpec + existing workflow → modified WorkflowSpec\n` +
-                `4. Deploy: persona(mode="update", id="${existingPersonaContext?.id}", workflow_spec=...)`
-            : `3. Transform IntentSpec → WorkflowSpec → Deploy`;
-        return {
-            status: "needs_llm",
-            ...baseResponse,
-            llm_prompt: result.prompt_package,
-            next_step: `Send llm_prompt to an LLM to generate IntentSpec. The LLM will:\n` +
-                `1. Parse the request using Intent Architect methodology\n` +
-                `2. Return a structured IntentSpec\n` +
-                deployStep,
-        };
-    }
-    // Fallback - unexpected state
-    return {
-        status: "error",
-        ...baseResponse,
-        error: "Unexpected state: no questions, no prompt, but can_proceed=false",
-        hint: "This may indicate a bug in the Intent Architect logic. Please report.",
-    };
-}

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

@@ -1,119 +0,0 @@
-/**
- * Workflow Analyze Handler
- *
- * Returns workflow DATA for LLM to analyze using rules from ema://rules/*.
- *
- * IMPORTANT: This handler does NOT pre-compute issues or fixes.
- * The LLM applies ANTI_PATTERNS, INPUT_SOURCE_RULES, and OPTIMIZATION_RULES
- * to reason about the workflow.
- *
- * Returns:
- * - workflow_def: The raw workflow structure
- * - connections: Type information for each edge
- * - metrics: Basic counts (nodes, edges, etc.)
- * - rules_hint: Pointer to ema://rules/* for analysis guidance
- */
-import { validateWorkflowConnections, parseWorkflowDef } from "../../knowledge.js";
-/**
- * Calculate workflow metrics (pure data, no analysis)
- */
-function calculateMetrics(workflow) {
-    const actions = workflow.actions;
-    if (!actions)
-        return { node_count: 0, connection_count: 0 };
-    // Count connections
-    let connectionCount = 0;
-    for (const action of actions) {
-        const inputs = action.inputs;
-        if (inputs) {
-            connectionCount += Object.keys(inputs).length;
-        }
-    }
-    // Check for HITL
-    const hasHitl = actions.some(a => {
-        const name = a.name?.toLowerCase() ?? "";
-        return name.includes("hitl") || name.includes("human");
-    });
-    // Get trigger type
-    const trigger = workflow.trigger;
-    const triggerType = trigger?.trigger_type;
-    // Check for categorizer
-    const hasCategorizer = actions.some(a => {
-        const name = a.name?.toLowerCase() ?? "";
-        const action = a.action?.name?.name;
-        return name.includes("categorizer") || action?.includes("categorizer");
-    });
-    return {
-        node_count: actions.length,
-        connection_count: connectionCount,
-        has_hitl: hasHitl,
-        has_categorizer: hasCategorizer,
-        trigger_type: triggerType,
-    };
-}
-/**
- * Handle workflow analyze mode
- *
- * Returns DATA for LLM to analyze - does NOT pre-compute issues.
- */
-export async function handleWorkflowAnalyze(args, client) {
-    const personaId = args.persona_id;
-    let workflow = args.workflow_def;
-    let persona = null;
-    // Get workflow from persona if not provided
-    if (personaId && !workflow) {
-        const fetchedPersona = await client.getPersonaById(personaId);
-        if (!fetchedPersona) {
-            return { error: `Persona not found: ${personaId}` };
-        }
-        persona = fetchedPersona;
-        workflow = fetchedPersona.workflow_def;
-    }
-    if (!workflow) {
-        return { error: "No workflow to analyze. Provide workflow_def or persona_id." };
-    }
-    // Parse workflow to simpler structure
-    const nodes = parseWorkflowDef(workflow);
-    // Get connection type information
-    const connections = validateWorkflowConnections(workflow);
-    // Calculate metrics
-    const metrics = calculateMetrics(workflow);
-    const result = {
-        mode: "analyze",
-        persona_id: personaId,
-        persona_name: persona?.name,
-        // RAW DATA for LLM to analyze
-        workflow_def: workflow,
-        node_count: nodes.length,
-        nodes: nodes.map(n => ({
-            id: n.id,
-            action: n.action_name,
-            display_name: n.display_name,
-            inputs: n.incoming_edges?.map(e => `${e.source_node_id}.${e.source_output}`),
-        })),
-        // Type information for connections
-        connections: connections.map(c => ({
-            edge: c.edge_id,
-            source_type: c.source_type,
-            target_type: c.target_type,
-            compatible: c.compatible,
-            note: c.note,
-        })),
-        // Basic metrics
-        metrics,
-        // Tell LLM where to find analysis rules
-        _next_steps: [
-            "1. Fetch ema://rules/anti-patterns",
-            "2. Fetch ema://rules/structural-invariants",
-            "3. Check each node against the rules",
-            "4. Report issues YOU find (MCP does not pre-compute)",
-        ],
-    };
-    if (persona) {
-        result.persona = {
-            id: persona.id,
-            name: persona.name
-        };
-    }
-    return result;
-}

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

@@ -1,70 +0,0 @@
-/**
- * Workflow Compare Handler
- *
- * Compares two workflow versions to identify differences.
- */
-/**
- * Compare two workflows and return differences
- */
-function compareWorkflows(workflow1, workflow2) {
-    const differences = [];
-    if (!workflow1 && !workflow2)
-        return differences;
-    if (!workflow1) {
-        differences.push({ type: "added", path: "workflow", new_value: "entire workflow" });
-        return differences;
-    }
-    if (!workflow2) {
-        differences.push({ type: "removed", path: "workflow", old_value: "entire workflow" });
-        return differences;
-    }
-    // Compare actions
-    const actions1 = workflow1.actions || [];
-    const actions2 = workflow2.actions || [];
-    const actionIds1 = new Set(actions1.map(a => (a.id ?? a.name)));
-    const actionIds2 = new Set(actions2.map(a => (a.id ?? a.name)));
-    // Find added/removed actions
-    for (const id of actionIds2) {
-        if (!actionIds1.has(id)) {
-            differences.push({ type: "added", path: `actions.${id}`, new_value: id });
-        }
-    }
-    for (const id of actionIds1) {
-        if (!actionIds2.has(id)) {
-            differences.push({ type: "removed", path: `actions.${id}`, old_value: id });
-        }
-    }
-    // Node count change
-    if (actions1.length !== actions2.length) {
-        differences.push({
-            type: "changed",
-            path: "actions.length",
-            old_value: actions1.length,
-            new_value: actions2.length,
-        });
-    }
-    return differences;
-}
-/**
- * Handle workflow compare mode
- */
-export async function handleWorkflowCompare(args, client) {
-    const personaId = args.persona_id;
-    const compareTo = args.compare_to;
-    if (!personaId || !compareTo) {
-        return { error: "persona_id and compare_to required for compare mode" };
-    }
-    const persona1 = await client.getPersonaById(personaId);
-    const persona2 = await client.getPersonaById(compareTo);
-    if (!persona1 || !persona2) {
-        return { error: "One or both personas not found" };
-    }
-    const workflow1 = persona1.workflow_def;
-    const workflow2 = persona2.workflow_def;
-    return {
-        mode: "compare",
-        persona_1: { id: persona1.id, name: persona1.name },
-        persona_2: { id: persona2.id, name: persona2.name },
-        differences: compareWorkflows(workflow1, workflow2),
-    };
-}