@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

package/dist/mcp/handlers/debug/formatters.js

@@ -0,0 +1,282 @@
+/**
+ * Debug Handler Formatters
+ *
+ * Transforms raw proto→JSON debug responses into concise, actionable summaries.
+ * Applies value truncation for large strings and adds _next_step hints
+ * to guide the agent through the drill-down flow.
+ */
+const MAX_VALUE_LENGTH = 2000;
+/** Action run status enum values from ShowWorkLog.ActionRunStatus */
+const STATUS_LABELS = {
+    0: "UNSPECIFIED",
+    1: "SUCCESS",
+    2: "ERRORED",
+    3: "WARNING",
+    4: "NOT_RUN",
+    5: "PAUSED",
+    ACTION_RUN_STATUS_UNSPECIFIED: "UNSPECIFIED",
+    ACTION_RUN_STATUS_SUCCESS: "SUCCESS",
+    ACTION_RUN_STATUS_ERRORED: "ERRORED",
+    ACTION_RUN_STATUS_WARNING: "WARNING",
+    ACTION_RUN_STATUS_NOT_RUN: "NOT_RUN",
+    ACTION_RUN_STATUS_PAUSED: "PAUSED",
+};
+function truncateValue(value) {
+    if (typeof value === "string" && value.length > MAX_VALUE_LENGTH) {
+        return value.slice(0, MAX_VALUE_LENGTH) + `... [truncated, ${value.length} total chars]`;
+    }
+    if (Array.isArray(value)) {
+        return value.map(truncateValue);
+    }
+    if (value !== null && typeof value === "object") {
+        return truncateObject(value);
+    }
+    return value;
+}
+function truncateObject(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        result[k] = truncateValue(v);
+    }
+    return result;
+}
+function resolveStatus(raw) {
+    if (typeof raw === "number" || typeof raw === "string") {
+        return STATUS_LABELS[raw] ?? String(raw);
+    }
+    return "UNKNOWN";
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// conversations
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatConversations(data, personaId) {
+    // toJson() serializes the response field as "items" (proto field name)
+    const reviews = data.items ?? data.conversationReviews ?? data.conversation_reviews;
+    const items = Array.isArray(reviews) ? reviews : [];
+    return {
+        persona_id: personaId,
+        total: items.length,
+        conversations: items.map((c) => ({
+            conversation_id: c.conversationId ?? c.conversation_id,
+            channel: c.channel,
+            resolution_status: c.resolutionStatus ?? c.resolution_status,
+            user_rating: c.userRating ?? c.user_rating,
+            message_count: c.messageCount ?? c.message_count,
+            created_at: c.createdAt ?? c.created_at,
+            last_message_at: c.lastMessageAt ?? c.last_message_at,
+            user_identifier: c.userIdentifier ?? c.user_identifier,
+        })),
+        _tip: "Use conversation_id with debug(method='conversation_detail') to see messages and workflow_run_ids.",
+        _next_step: items.length > 0
+            ? `debug(method="conversation_detail", conversation_id="${items[0].conversationId ?? items[0].conversation_id}")`
+            : "No conversations found. Try adjusting filters or date range.",
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// conversation_detail
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatConversationDetail(data, conversationId, personaId) {
+    const messages = data.messages ?? data.messageDetails ?? data.message_details;
+    const items = Array.isArray(messages) ? messages : [];
+    const formatted = items.map((m) => {
+        const workflowRunId = m.workflowRunId ?? m.workflow_run_id;
+        const chatMsg = (m.chatbotMessage ?? m.chatbot_message ?? {});
+        // Derive role from ChatbotMessage.type + isUserMessage
+        const msgType = chatMsg.type ?? chatMsg.message_type;
+        const isUser = chatMsg.isUserMessage ?? chatMsg.is_user_message;
+        const role = isUser ? "user" : (msgType ? "assistant" : undefined);
+        // Extract content from the message oneof (textMessage, buttonsMessage, etc.)
+        const textMsg = (chatMsg.textMessage ?? chatMsg.text_message);
+        const buttonsMsg = (chatMsg.buttonsMessage ?? chatMsg.buttons_message);
+        const content = textMsg?.contents ?? textMsg?.content ?? buttonsMsg?.content ?? chatMsg.content;
+        return {
+            workflow_run_id: workflowRunId,
+            role,
+            type: msgType,
+            content: truncateValue(content),
+            user_feedback: m.userFeedback ?? m.user_feedback,
+            work_log_steps_count: Array.isArray(m.workLogSteps ?? m.work_log_steps)
+                ? (m.workLogSteps ?? m.work_log_steps).length
+                : 0,
+        };
+    });
+    // Find the first message with a workflow_run_id for the next step hint
+    const withRunId = formatted.find((m) => m.workflow_run_id);
+    return {
+        conversation_id: conversationId,
+        message_count: formatted.length,
+        messages: formatted,
+        _tip: "Messages with workflow_run_id can be inspected with debug(method='show_work', persona_id='...', workflow_run_id='...').",
+        _next_step: withRunId
+            ? `debug(method="show_work", persona_id="${personaId ?? "<persona_id>"}", workflow_run_id="${withRunId.workflow_run_id}")`
+            : "No workflow_run_ids found in this conversation.",
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// show_work
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatShowWork(data, workflowRunId, personaId) {
+    const showWorkLogs = (data.showWorkLogs ?? data.show_work_logs ?? {});
+    const actions = [];
+    const erroredActions = [];
+    for (const [actionName, logRaw] of Object.entries(showWorkLogs)) {
+        const log = logRaw;
+        const status = resolveStatus(log.actionRunStatus ?? log.action_run_status);
+        const inputs = log.inputs;
+        const outputs = log.outputs;
+        const inputEntries = Array.isArray(inputs?.entries) ? inputs.entries : [];
+        const outputEntries = Array.isArray(outputs?.entries) ? outputs.entries : [];
+        const actionSummary = {
+            action_name: actionName,
+            title: log.actionTitle ?? log.action_title,
+            status,
+            llm_call_count: log.llmCallCount ?? log.llm_call_count ?? 0,
+            llm_cost_usd: log.llmCostUsd ?? log.llm_cost_usd ?? 0,
+            llm_latency_ms: log.llmLatencyMs ?? log.llm_latency_ms ?? 0,
+            input_names: inputEntries.map((e) => e.name),
+            output_names: outputEntries.map((e) => e.name),
+            step_count: Array.isArray(log.workLogs ?? log.work_logs) ? (log.workLogs ?? log.work_logs).length : 0,
+            hitl_round_count: Array.isArray(log.hitlRounds ?? log.hitl_rounds) ? (log.hitlRounds ?? log.hitl_rounds).length : 0,
+        };
+        // Include error info if present
+        const messages = Array.isArray(log.messages) ? log.messages : [];
+        const errorMessages = messages.filter((m) => m.logLevel === "LOG_LEVEL_ERROR" || m.log_level === "LOG_LEVEL_ERROR" || m.logLevel === 1 || m.log_level === 1);
+        if (errorMessages.length > 0) {
+            actionSummary.errors = errorMessages.map((m) => {
+                const errorInfo = (m.errorInfo ?? m.error_info);
+                return {
+                    message: m.messageTemplate ?? m.message_template,
+                    error_name: errorInfo?.name,
+                    external_message: errorInfo?.externalMessage ?? errorInfo?.external_message,
+                };
+            });
+        }
+        if (status === "ERRORED") {
+            erroredActions.push(actionName);
+        }
+        actions.push(actionSummary);
+    }
+    const result = {
+        workflow_run_id: workflowRunId,
+        action_count: actions.length,
+        actions,
+        _tip: "Use action_name with debug(method='action_detail', persona_id='...') to see full inputs, outputs, LLM calls, and steps for any action.",
+    };
+    // Smart _next_step: auto-suggest drilling into errored actions
+    if (erroredActions.length > 0) {
+        const pid = personaId ?? "<persona_id>";
+        result._next_step = `Action(s) ERRORED: ${erroredActions.join(", ")}. Investigate with: debug(method="action_detail", persona_id="${pid}", workflow_run_id="${workflowRunId}", action_name="${erroredActions[0]}")`;
+    }
+    else {
+        const pid = personaId ?? "<persona_id>";
+        result._next_step = actions.length > 0
+            ? `debug(method="action_detail", persona_id="${pid}", workflow_run_id="${workflowRunId}", action_name="${actions[0].action_name}") to see detailed execution trace.`
+            : "No actions found in this workflow run.";
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// action_detail
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatActionDetail(data, workflowRunId, actionName) {
+    const log = (data.showWorkLog ?? data.show_work_log ?? {});
+    const status = resolveStatus(log.actionRunStatus ?? log.action_run_status);
+    // Inputs
+    const inputs = log.inputs;
+    const inputEntries = Array.isArray(inputs?.entries) ? inputs.entries : [];
+    const formattedInputs = inputEntries.map((e) => ({
+        name: e.name,
+        value: truncateValue(e.value),
+        type: e.type,
+        source_agent: e.sourceAgentName ?? e.source_agent_name,
+    }));
+    // Outputs
+    const outputs = log.outputs;
+    const outputEntries = Array.isArray(outputs?.entries) ? outputs.entries : [];
+    const formattedOutputs = outputEntries.map((e) => ({
+        name: e.name,
+        value: truncateValue(e.value),
+        type: e.type,
+        published_as_chat_response: e.publishedAsChatResponse ?? e.published_as_chat_response,
+    }));
+    // Steps (work logs)
+    const steps = Array.isArray(log.workLogs ?? log.work_logs) ? (log.workLogs ?? log.work_logs) : [];
+    const formattedSteps = steps.map((s) => {
+        const msgs = Array.isArray(s.messages) ? s.messages : [];
+        const stepLlmCalls = Array.isArray(s.llmCalls ?? s.llm_calls) ? (s.llmCalls ?? s.llm_calls) : [];
+        return {
+            name: s.name,
+            messages: msgs.map((m) => ({
+                heading: m.heading,
+                template: truncateValue(m.messageTemplate ?? m.message_template),
+                log_level: m.logLevel ?? m.log_level,
+                error_info: m.errorInfo ?? m.error_info,
+            })),
+            llm_calls: stepLlmCalls.map((c) => formatLlmCall(c)),
+        };
+    });
+    // Top-level LLM calls
+    const topLlmCalls = Array.isArray(log.llmCalls ?? log.llm_calls) ? (log.llmCalls ?? log.llm_calls) : [];
+    const formattedLlmCalls = topLlmCalls.map((c) => formatLlmCall(c));
+    // HITL rounds
+    const hitlRounds = Array.isArray(log.hitlRounds ?? log.hitl_rounds) ? (log.hitlRounds ?? log.hitl_rounds) : [];
+    const formattedHitl = hitlRounds.map((r) => truncateObject(r));
+    return {
+        workflow_run_id: workflowRunId,
+        action_name: actionName,
+        action_type: data.actionType ?? data.action_type,
+        title: log.actionTitle ?? log.action_title,
+        status,
+        llm_call_count: log.llmCallCount ?? log.llm_call_count ?? 0,
+        llm_cost_usd: log.llmCostUsd ?? log.llm_cost_usd ?? 0,
+        llm_latency_ms: log.llmLatencyMs ?? log.llm_latency_ms ?? 0,
+        inputs: formattedInputs,
+        outputs: formattedOutputs,
+        steps: formattedSteps,
+        llm_calls: formattedLlmCalls,
+        hitl_rounds: formattedHitl.length > 0 ? formattedHitl : undefined,
+        _tip: status === "ERRORED"
+            ? "Check the steps and error_info fields for failure details. LLM calls show the exact prompts and responses."
+            : "Review inputs/outputs for data flow and llm_calls for prompt details.",
+    };
+}
+function formatLlmCall(call) {
+    const prompt = (call.prompt ?? {});
+    const metrics = (call.metrics ?? {});
+    return {
+        heading: call.heading,
+        success: call.success,
+        error_message: call.errorMessage ?? call.error_message,
+        fusion_used: call.fusionUsed ?? call.fusion_used,
+        cost_final_choice: call.llmCostFinalChoice ?? call.llm_cost_final_choice,
+        timestamp_ms: call.timestampMs ?? call.timestamp_ms,
+        prompt: {
+            system_prompt: truncateValue(prompt.systemPrompt ?? prompt.system_prompt),
+            user_prompt: truncateValue(prompt.userPrompt ?? prompt.user_prompt),
+            response: truncateValue(prompt.response),
+        },
+        metrics: Object.keys(metrics).length > 0 ? truncateObject(metrics) : undefined,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// search
+// ─────────────────────────────────────────────────────────────────────────────
+export function formatSearch(data, query, personaId) {
+    const results = Array.isArray(data.results) ? data.results : [];
+    return {
+        persona_id: personaId,
+        query,
+        total: results.length,
+        results: results.map((r) => ({
+            run_id: r.runId ?? r.run_id,
+            conversation_id: r.conversationId ?? r.conversation_id,
+            user_message_created_at: r.userMessageCreatedAt ?? r.user_message_created_at,
+            user_message: truncateValue(r.userMessage ?? r.user_message),
+            bot_message: truncateValue(r.botMessage ?? r.bot_message),
+        })),
+        _tip: "Use conversation_id with debug(method='conversation_detail') to see the full conversation, or run_id to identify the workflow execution.",
+        _next_step: results.length > 0
+            ? `debug(method="conversation_detail", conversation_id="${results[0].conversationId ?? results[0].conversation_id}")`
+            : "No messages matched the search query.",
+    };
+}

package/dist/mcp/handlers/debug/index.js

@@ -0,0 +1,133 @@
+/**
+ * Debug Handler — Method Dispatch
+ *
+ * Routes debug tool methods to the appropriate SDK calls and formatters.
+ * Follows the drill-down pattern: conversations → conversation_detail → show_work → action_detail
+ */
+import { formatConversations, formatConversationDetail, formatShowWork, formatActionDetail, formatSearch, } from "./formatters.js";
+export async function handleDebug(args, client) {
+    const method = args.method;
+    if (!method) {
+        return {
+            error: "Missing required parameter: method",
+            available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+            _tip: "Start with debug(method='conversations', persona_id='...') to list audit conversations.",
+        };
+    }
+    switch (method) {
+        case "conversations":
+            return handleConversations(args, client);
+        case "conversation_detail":
+            return handleConversationDetail(args, client);
+        case "show_work":
+            return handleShowWork(args, client);
+        case "action_detail":
+            return handleActionDetail(args, client);
+        case "search":
+            return handleSearch(args, client);
+        default:
+            return {
+                error: `Unknown method: ${method}`,
+                available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+            };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Method handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleConversations(args, client) {
+    const personaId = args.persona_id;
+    if (!personaId) {
+        return { error: "Missing required parameter: persona_id" };
+    }
+    // Build filters matching the gRPC ConversationReviewFilters proto shape
+    const filters = {};
+    if (args.start_time)
+        filters.createdFrom = new Date(String(args.start_time));
+    if (args.end_time)
+        filters.createdTo = new Date(String(args.end_time));
+    if (args.channel)
+        filters.channel = Number(args.channel);
+    if (args.status)
+        filters.status = Number(args.status);
+    if (args.search_query)
+        filters.searchQuery = String(args.search_query);
+    if (args.workflow_failure)
+        filters.workflowFailure = true;
+    if (args.has_user_frustration)
+        filters.hasUserFrustration = true;
+    if (args.no_results_found)
+        filters.noResultsFound = true;
+    const opts = {
+        ...(Object.keys(filters).length > 0 ? { filters } : {}),
+        ...(args.limit ? { limit: Number(args.limit) } : {}),
+        ...(args.pagination_token ? { paginationToken: String(args.pagination_token) } : {}),
+    };
+    const response = await client.getConversationReviews(personaId, opts);
+    return formatConversations(response, personaId);
+}
+async function handleConversationDetail(args, client) {
+    const conversationId = args.conversation_id;
+    if (!conversationId) {
+        return { error: "Missing required parameter: conversation_id" };
+    }
+    const personaId = args.persona_id;
+    const response = await client.getConversationReviewDetail(conversationId);
+    return formatConversationDetail(response, conversationId, personaId);
+}
+async function handleShowWork(args, client) {
+    const workflowRunId = args.workflow_run_id;
+    const personaId = args.persona_id;
+    if (!workflowRunId) {
+        return { error: "Missing required parameter: workflow_run_id" };
+    }
+    if (!personaId) {
+        return {
+            error: "Missing required parameter: persona_id",
+            _tip: "DebugLogService requires persona context. Pass persona_id alongside workflow_run_id.",
+        };
+    }
+    const response = await client.getWorkflowLevelDebugLog(workflowRunId, personaId);
+    return formatShowWork(response, workflowRunId, personaId);
+}
+async function handleActionDetail(args, client) {
+    const workflowRunId = args.workflow_run_id;
+    const actionName = args.action_name;
+    const personaId = args.persona_id;
+    if (!workflowRunId) {
+        return { error: "Missing required parameter: workflow_run_id" };
+    }
+    if (!actionName) {
+        return {
+            error: "Missing required parameter: action_name",
+            _tip: "Use debug(method='show_work') first to see available action names.",
+        };
+    }
+    if (!personaId) {
+        return {
+            error: "Missing required parameter: persona_id",
+            _tip: "DebugLogService requires persona context. Pass persona_id alongside workflow_run_id and action_name.",
+        };
+    }
+    const response = await client.getActionLevelShowWorkLog(actionName, workflowRunId, personaId);
+    return formatActionDetail(response, workflowRunId, actionName);
+}
+async function handleSearch(args, client) {
+    const personaId = args.persona_id;
+    const query = args.query;
+    if (!personaId) {
+        return { error: "Missing required parameter: persona_id" };
+    }
+    if (!query) {
+        return { error: "Missing required parameter: query" };
+    }
+    const opts = { personaId, query };
+    if (args.conversation_id)
+        opts.conversationId = String(args.conversation_id);
+    if (args.start_time)
+        opts.startTime = new Date(String(args.start_time));
+    if (args.end_time)
+        opts.endTime = new Date(String(args.end_time));
+    const response = await client.searchMessages(opts);
+    return formatSearch(response, query, personaId);
+}

package/dist/mcp/handlers/demo/adapter.js

@@ -0,0 +1,180 @@
+/**
+ * Demo V2 Adapter
+ *
+ * Routes the consolidated demo tool modes (kit, validate_kit, scenarios,
+ * consolidate, generate, validate, template) to the appropriate handlers.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { handleConsolidateDemoData, handleGenerateDemoDocument, handleValidateDemoDocument, handleGetDemoDataTemplate, } from "./index.js";
+export async function handleDemoAdapter(args, createClient) {
+    const normalizedArgs = { ...(args ?? {}) };
+    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : "template";
+    const deprecationWarning = {
+        _deprecation: {
+            message: "The 'demo' tool is deprecated. Please use 'data' and 'persona' tools instead.",
+            migration: {
+                "demo(mode='kit')": "persona(from='demo-sales-sdr', include_data=true)",
+                "demo(mode='generate')": "data(mode='generate', from='customer', count=5)",
+                "demo(mode='scenarios')": "data(mode='templates')",
+                "demo(mode='template')": "data(mode='templates', template='customer')",
+            },
+        },
+    };
+    switch (mode) {
+        case "kit": {
+            const personaId = String(normalizedArgs.persona_id ?? "");
+            const scenarioId = String(normalizedArgs.scenario ?? "sales-sdr");
+            if (!personaId) {
+                throw new Error('demo(mode="kit") requires: persona_id');
+            }
+            const { generateDemoKit, DEMO_SCENARIOS, generateDemoScriptMarkdown, validateDemoKit } = await import("../../demo-generator.js");
+            const scenario = DEMO_SCENARIOS[scenarioId];
+            if (!scenario) {
+                throw new Error(`Unknown scenario: ${scenarioId}. Available: ${Object.keys(DEMO_SCENARIOS).join(", ")}`);
+            }
+            const client = await createClient(normalizedArgs.env);
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                throw new Error(`Persona not found: ${personaId}`);
+            }
+            const workflowDef = persona.workflow_def || {};
+            const customQA = normalizedArgs.custom_qa;
+            const kit = generateDemoKit(personaId, persona.name || personaId, workflowDef, scenario, customQA);
+            const demoScript = generateDemoScriptMarkdown(kit);
+            const validation = validateDemoKit(kit);
+            return {
+                success: true,
+                persona_id: personaId,
+                persona_name: persona.name,
+                scenario: scenarioId,
+                kit_summary: {
+                    kb_documents: kit.kb_documents.length,
+                    demo_questions: kit.demo_script.length,
+                    fixed_responses: kit.fixed_responses.length,
+                    validation_queries: kit.validation_queries.length,
+                },
+                validation,
+                demo_script_preview: demoScript.slice(0, 2000) + (demoScript.length > 2000 ? "\n\n... (truncated)" : ""),
+                kit,
+                instructions: [
+                    "1. Upload KB documents to the persona's knowledge base",
+                    "2. Review the demo script and practice the questions",
+                    "3. Optionally apply fixed_responses for guaranteed fallbacks",
+                    "4. Run validation queries to verify demo readiness",
+                    "5. Conduct the demo with confidence!",
+                ],
+            };
+        }
+        case "validate_kit": {
+            const personaId = String(normalizedArgs.persona_id ?? "");
+            if (!personaId) {
+                throw new Error('demo(mode="validate_kit") requires: persona_id');
+            }
+            const { analyzeWorkflowForDemo, DEMO_SCENARIOS } = await import("../../demo-generator.js");
+            const client = await createClient(normalizedArgs.env);
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                throw new Error(`Persona not found: ${personaId}`);
+            }
+            const analysis = analyzeWorkflowForDemo(persona.workflow_def || {});
+            const dataSourcesResult = await client.listDataSourceFiles(personaId);
+            const dataSources = dataSourcesResult.files || [];
+            const hasKnowledgeBase = dataSources.length > 0;
+            const issues = [];
+            if (!hasKnowledgeBase) {
+                issues.push("No knowledge base documents uploaded - RAG search will fail");
+            }
+            if (analysis.intents.length === 0) {
+                issues.push("No categorizer intents detected - workflow may not route correctly");
+            }
+            if (!analysis.has_search) {
+                issues.push("No search nodes detected - cannot retrieve KB data");
+            }
+            let suggestedScenario = "sales-sdr";
+            for (const [id, scenario] of Object.entries(DEMO_SCENARIOS)) {
+                const intentOverlap = scenario.intents.filter(i => analysis.intents.some(ai => ai.toLowerCase().includes(i.name.toLowerCase()))).length;
+                if (intentOverlap > 0) {
+                    suggestedScenario = id;
+                    break;
+                }
+            }
+            return {
+                persona_id: personaId,
+                persona_name: persona.name,
+                ready: issues.length === 0,
+                issues,
+                workflow_analysis: analysis,
+                knowledge_base: {
+                    has_documents: hasKnowledgeBase,
+                    document_count: dataSources.length,
+                },
+                suggested_scenario: suggestedScenario,
+                next_steps: issues.length > 0
+                    ? issues.map((issue, i) => `${i + 1}. Fix: ${issue}`)
+                    : [`Generate demo kit: demo(mode="kit", persona_id="${personaId}", scenario="${suggestedScenario}")`],
+            };
+        }
+        case "scenarios": {
+            const { DEMO_SCENARIOS } = await import("../../demo-generator.js");
+            return {
+                scenarios: Object.entries(DEMO_SCENARIOS).map(([id, scenario]) => ({
+                    id,
+                    name: scenario.name,
+                    description: scenario.description,
+                    persona_types: scenario.persona_types,
+                    tags: scenario.tags,
+                    intent_count: scenario.intents.length,
+                    qa_count: scenario.qa_pairs.length,
+                    entity_types: scenario.entities.map(e => e.type),
+                })),
+                usage: 'demo(mode="kit", persona_id="...", scenario="<scenario_id>")',
+            };
+        }
+        case "consolidate": {
+            const source = String(normalizedArgs.source ?? "");
+            const output = String(normalizedArgs.output ?? "");
+            const entity = String(normalizedArgs.entity ?? "");
+            if (!source || !output || !entity) {
+                throw new Error('demo(mode="consolidate") requires: source, output, entity');
+            }
+            return handleConsolidateDemoData({
+                source_dir: source,
+                output_dir: output,
+                entity_type: entity,
+                primary_file: normalizedArgs.primary ?? `${entity}s.json`,
+                joins: normalizedArgs.joins ?? [],
+                tags: normalizedArgs.tags,
+            });
+        }
+        case "generate": {
+            const entity = String(normalizedArgs.entity ?? "");
+            if (!entity)
+                throw new Error('demo(mode="generate") requires: entity');
+            return handleGenerateDemoDocument({
+                entity_type: entity,
+                data: normalizedArgs.data ?? {},
+                related_data: normalizedArgs.related ?? {},
+                output_path: normalizedArgs.output,
+                tags: normalizedArgs.tags,
+            });
+        }
+        case "validate": {
+            return handleValidateDemoDocument({
+                file_path: normalizedArgs.file,
+                content: normalizedArgs.content,
+            });
+        }
+        case "template": {
+            const entity = String(normalizedArgs.entity ?? "");
+            if (!entity)
+                throw new Error('demo(mode="template") requires: entity');
+            return handleGetDemoDataTemplate({
+                entity_type: entity,
+                include_example: normalizedArgs.include_example,
+            });
+        }
+        default:
+            throw new Error(`Unknown demo mode: ${mode}`);
+    }
+}

package/dist/mcp/handlers/env/config.js

@@ -9,7 +9,7 @@ import { readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { EmaClient } from "../../../sdk/client.js";
+import { EmaClientAdapter } from "../../../sdk/client-adapter.js";
 import { loadConfigOptional } from "../../../sdk/config.js";
 import { SyncSDK } from "../../../sync/sdk.js";
 // ─────────────────────────────────────────────────────────────────────────────
@@ -282,7 +282,7 @@ export function createClient(envName) {
             },
         }
         : undefined;
-    return new EmaClient({
+    return new EmaClientAdapter({
         name: envInfo.name,
         baseUrl: envInfo.baseUrl,
         bearerToken,

package/dist/mcp/handlers/feedback/index.js

@@ -125,7 +125,7 @@ async function handleAnalyze() {
             ? `Found ${analysis.actionable_items.length} actionable item(s). Review and address these to improve agent experience.`
             : "No actionable items found. Feedback data may be limited - encourage agents to submit feedback.",
         _next_step: analysis.actionable_items.length > 0
-            ? "Review actionable_items and update guidance.ts, resources.ts, or workflow-builder-patterns.md accordingly."
+            ? "Review actionable_items and update guidance.ts or resources.ts accordingly."
             : "Continue collecting feedback. Use toolkit_feedback(method='list') to review individual entries.",
     };
 }

package/dist/mcp/handlers/index.js

@@ -27,6 +27,5 @@ export { handleEnv } from "./env/index.js";
 export { handleTemplate } from "./template/index.js";
 export { handleAction } from "./action/index.js";
 export { handleReference } from "./reference/index.js";
-export { handleKnowledge } from "./knowledge/index.js";
 export { handleSync } from "./sync/index.js";
 // Note: handleDashboardGenerate removed - LLM generates content, MCP uploads via data.method="upload"