@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/mcp/resources-dynamic.js

@@ -974,19 +974,17 @@ Chat workflows that process \`chat_conversation\` through search, extraction, or
 
 ## Correct Patterns
 
-### Pattern 1: Search + Respond (most common)
+### Pattern 1: Search + Respond (most common — 89% of production)
 \`\`\`
 chat_trigger.chat_conversation → conversation_to_search_query.conversation
 conversation_to_search_query.summarized_conversation → search.query
-search.search_results → respond_for_external_actions.external_action_result
-chat_trigger.user_query → respond_for_external_actions.query
-chat_trigger.chat_conversation → respond_for_external_actions.conversation
-respond_for_external_actions.response → WORKFLOW_OUTPUT
+search.search_results → call_llm.named_inputs_Search_Results
+chat_trigger.user_query → call_llm.query
+chat_trigger.chat_conversation → call_llm.named_inputs_Conversation
+call_llm.response_with_sources → WORKFLOW_OUTPUT
 \`\`\`
 
-> **Note**: \`respond_with_sources/v0\` is DEPRECATED. Use \`respond_for_external_actions\` for all new workflows (search results, tool results, or any context-aware response).
-
-### Pattern 2: Tool/Action + Respond
+### Pattern 2: Tool/Action + Respond (uses respond_for_external_actions)
 \`\`\`
 chat_trigger.chat_conversation → external_action_caller.conversation
 external_action_caller.tool_execution_result → respond_for_external_actions.external_action_result
@@ -995,12 +993,14 @@ chat_trigger.chat_conversation → respond_for_external_actions.conversation
 respond_for_external_actions.response → WORKFLOW_OUTPUT
 \`\`\`
 
-### Pattern 3: call_llm with Conversation Context (advanced)
-If you must use \`call_llm\` as the terminal responder, you **must** wire \`chat_conversation\` into its \`named_inputs\`:
+> **Note**: \`respond_for_external_actions\` is ONLY for explaining \`external_action_caller\` results (Salesforce, ServiceNow, etc). For KB Q&A after search, use \`call_llm\` with \`named_inputs\`.
+
+### Pattern 3: Search + Respond with Citations
 \`\`\`
-chat_trigger.chat_conversation → call_llm.named_inputs (key: "conversation_history")
+search.search_results → respond_with_sources.search_results
+chat_trigger.user_query → respond_with_sources.query
+respond_with_sources.response → WORKFLOW_OUTPUT
 \`\`\`
-This ensures the LLM sees prior turns.
 
 ## Anti-Patterns
 
@@ -1009,6 +1009,13 @@ This ensures the LLM sees prior turns.
 chat_trigger → search → call_llm (no conversation) → WORKFLOW_OUTPUT
 \`\`\`
 **Problem**: call_llm only sees search results, not prior conversation. Repeats questions.
+**Fix**: Wire \`chat_conversation\` into \`call_llm.named_inputs_Conversation\`.
+
+### ❌ respond_for_external_actions for KB Q&A
+\`\`\`
+chat_trigger → search → respond_for_external_actions → WORKFLOW_OUTPUT
+\`\`\`
+**Problem**: \`respond_for_external_actions\` is designed for \`external_action_caller\` tool results, not search results. Use \`call_llm\` with \`named_inputs_Search_Results\` instead.
 
 ### ❌ Entity Extraction → call_llm (no history)
 \`\`\`
@@ -1016,19 +1023,14 @@ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT
 \`\`\`
 **Problem**: LLM extracts entities but response node doesn't know what was already discussed.
 
-## Key Insight
-
-\`respond_for_external_actions\` is **conversation-aware by design** — it incorporates conversation context via its \`conversation\` input. Generic \`call_llm\` does not — you must manually wire \`chat_conversation\` via \`named_inputs\`.
-
-> **Deprecated**: \`respond_with_sources/v0\` — use \`respond_for_external_actions\` for all new workflows.
-
 ## When to Use Each Response Node
 
 | Scenario | Response Node | Why |
 |----------|---------------|-----|
-| KB/document Q&A | \`respond_for_external_actions\` | Handles search results, conversation-aware |
-| Tool/API results | \`respond_for_external_actions\` | Explains tool results in conversation context |
-| Complex multi-step reasoning | \`call_llm/v2\` + named_inputs with chat_conversation | Full control but requires manual history wiring |
+| KB/document Q&A | \`call_llm\` with \`named_inputs_Search_Results\` | Most common (89%), full control via named_inputs |
+| KB Q&A with citations | \`respond_with_sources\` | Automatic citation grounding |
+| External tool results | \`respond_for_external_actions\` | ONLY for \`external_action_caller\` outputs |
+| Complex multi-step reasoning | \`custom_agent\` | Role context + multi-step reasoning |
 | Static/template response | \`fixed_response/v1\` | No LLM needed, just template + variables |
 `;
         },
@@ -1239,10 +1241,10 @@ When you already have a clean extracted value and just need TEXT_WITH_SOURCES wr
             md += `- **Outputs**: \`response_with_sources\` (TEXT_WITH_SOURCES)\n`;
             md += `- **Critical**: Must wire to WORKFLOW_OUTPUT or response is lost. \`call_llm/v0\` is deprecated.\n\n`;
             md += `### respond_for_external_actions\n`;
-            md += `Generate conversation-aware response from search results or tool outputs.\n`;
-            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`conversation\` (CHAT_CONVERSATION), \`external_action_result\` (TEXT_WITH_SOURCES/SEARCH_RESULT)\n`;
+            md += `Explain results from external_action_caller (Salesforce, ServiceNow, etc) in conversation context.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`conversation\` (CHAT_CONVERSATION), \`external_action_result\` (from external_action_caller)\n`;
             md += `- **Outputs**: \`response\` (TEXT_WITH_SOURCES)\n`;
-            md += `- **Critical**: Replaces deprecated \`respond_with_sources/v0\`. Has built-in citation handling and conversation awareness.\n\n`;
+            md += `- **Critical**: ONLY use after \`external_action_caller\`. For KB Q&A after search, use \`call_llm\` with \`named_inputs_Search_Results\`.\n\n`;
             md += `### fixed_response/v1\n`;
             md += `Return a static predefined message.\n`;
             md += `- **Inputs**: \`trigger_when\` (ENUM), \`named_inputs_*\` for template variables\n`;
@@ -1280,12 +1282,12 @@ When you already have a clean extracted value and just need TEXT_WITH_SOURCES wr
             md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES)\n`;
             md += `- **Outputs**: \`web_search_results\` (SEARCH_RESULT)\n`;
             md += `- **Critical**: No data upload needed (searches the web).\n\n`;
-            md += `### combine_search_results\n`;
-            md += `Merge results from multiple search sources with deduplication.\n`;
-            md += `- **Inputs**: \`search_results_1\` (SEARCH_RESULT), \`search_results_2\` (SEARCH_RESULT)\n`;
-            md += `- **Outputs**: \`combined_results\` (SEARCH_RESULT)\n`;
-            md += `- **Pairs with**: search/v2 + live_web_search, or any two search sources\n`;
-            md += `- **Note**: \`combine_search_results/v0\` is deprecated. For new workflows, prefer \`call_llm\` with multiple \`named_inputs\` to combine search results.\n\n`;
+            md += `### combine_and_rerank_search_results\n`;
+            md += `Merge results from multiple search sources with relevance-based reranking.\n`;
+            md += `- **Inputs**: Multiple search result inputs (SEARCH_RESULT)\n`;
+            md += `- **Outputs**: Reranked combined results (SEARCH_RESULT)\n`;
+            md += `- **When**: Need weighted/prioritized results from multiple sources, or need to ensure certain results rank higher\n`;
+            md += `- **Alternative**: \`call_llm\` with multiple \`named_inputs\` gives prompt-level control over how results are synthesized.\n\n`;
             md += `### response_validator\n`;
             md += `Validate LLM output against quality/compliance criteria.\n`;
             md += `- **Inputs**: \`reference_query\` (TEXT_WITH_SOURCES), \`response_to_validate\` (TEXT_WITH_SOURCES)\n`;
@@ -1420,15 +1422,16 @@ When you already have a clean extracted value and just need TEXT_WITH_SOURCES wr
                     { name: "vadSettings", type: 42, purpose: "Voice activity detection, timeouts" },
                 ],
                 common_patterns: {
-                    simple_qa: "chat_trigger → search → respond_for_external_actions → WORKFLOW_OUTPUT",
+                    simple_qa: "chat_trigger → search → call_llm (via named_inputs_Search_Results) → WORKFLOW_OUTPUT",
                     with_routing: "chat_trigger → chat_categorizer → [branch per intent] → respond → WORKFLOW_OUTPUT",
                     with_tools: "chat_trigger → categorizer → external_action_caller → respond_for_external_actions → WORKFLOW_OUTPUT",
                 },
                 best_practices: [
                     "Use search/v2 (NOT v0) with datastore_configs",
                     "Include Fallback category in every categorizer",
-                    "Use respond_for_external_actions (NOT deprecated respond_with_sources)",
-                    "For approval workflows: enable HITL flag on send_email_agent or entity_extraction_with_documents (only nodes that support HITL). general_hitl is NOT deployable.",
+                    "For KB Q&A after search: use call_llm with named_inputs_Search_Results (89% of production)",
+                    "respond_for_external_actions is ONLY for external_action_caller results (Salesforce, etc)",
+                    "For approval workflows: use general_hitl (Human Collaboration Agent) or HITL flags on send_email_agent/entity_extraction_with_documents",
                 ],
                 _next_step: "Call workflow(mode='get', persona_id='...') to get full schema, then generate workflow_def",
             }, null, 2);
@@ -1549,7 +1552,7 @@ Wire any custom widget to a search node: \`search/v2\` → \`datastore_configs\`
 | Deprecated | Use Instead |
 |------------|-------------|
 | search/v0 | search/v2 (requires datastore_configs) |
-| respond_with_sources | respond_for_external_actions |
+| respond_with_sources/v0 | call_llm with named_inputs (for KB Q&A) or respond_with_sources current version (for citations) |
 | call_llm/v0 | call_llm/v2 |
 
 ## Anti-Patterns
@@ -1791,15 +1794,20 @@ interface ResultMapping {
     },
     {
       "id": "respond",
-      "actionType": "respond_for_external_actions",
+      "actionType": "call_llm",
       "displayName": "Generate Response",
       "inputs": {
-        "search_results": {
+        "query": {
+          "type": "action_output",
+          "actionName": "trigger",
+          "output": "user_query"
+        },
+        "named_inputs_Search_Results": {
           "type": "action_output",
           "actionName": "search",
           "output": "search_results"
         },
-        "conversation": {
+        "named_inputs_Conversation": {
           "type": "action_output",
           "actionName": "trigger",
           "output": "chat_conversation"
@@ -1808,7 +1816,7 @@ interface ResultMapping {
     }
   ],
   "resultMappings": [
-    { "nodeId": "respond", "output": "response" }
+    { "nodeId": "respond", "output": "response_with_sources" }
   ]
 }
 \`\`\`

package/dist/mcp/resources-validation.js

@@ -59,9 +59,9 @@ These rules are extracted from the Go validator's static validation logic. Follo
 **Good Pattern**:
 \`\`\`json
 {
-  "path": ["trigger", "categorizer", "billing_branch", "search", "respond_for_external_actions"],
+  "path": ["trigger", "categorizer", "billing_branch", "search", "respond"],
   "named_result": "response",
-  "produces": ["response"]  // ✅ Produced
+  "produces": ["response"]  // ✅ Produced (respond is call_llm with named_inputs)
 }
 \`\`\`
 
@@ -75,8 +75,8 @@ These rules are extracted from the Go validator's static validation logic. Follo
 3. Connect the node's output to WORKFLOW_OUTPUT
 
 **Common Fixes**:
-- Add \`respond_for_external_actions\` node after search
-- Add \`call_llm\` node for text generation
+- Add \`call_llm\` node with \`named_inputs_Search_Results\` after search (most common)
+- Add \`respond_with_sources\` for citation-grounded responses
 - Add \`fixed_response\` for static responses
 
 **Prevention** (During Generation):
@@ -183,7 +183,7 @@ These rules are extracted from the Go validator's static validation logic. Follo
 **Good Pattern**:
 \`\`\`json
 {
-  "path": ["trigger", "categorizer", "billing", "search", "respond_for_external_actions"],
+  "path": ["trigger", "categorizer", "billing", "search", "respond"],
   "has_response": true  // ✅ Has response
 }
 \`\`\`

package/dist/mcp/server.js

@@ -29,25 +29,28 @@ import { generateTools } from "./tools.js";
 // Handler imports (simple 1-2 line handlers stay inline)
 import { handleEnv } from "./handlers/env/index.js";
 import { handleAction } from "./handlers/action/index.js";
-import { handleTemplate } from "./handlers/template/index.js";
 import { handleReference } from "./handlers/reference/index.js";
 import { handleCatalog } from "./handlers/catalog/index.js";
 import { handleFeedback } from "./handlers/feedback/index.js";
 import { recordTelemetry } from "./handlers/feedback/store.js";
+import { flushOutbox, startFlushTimer, stopFlushTimer } from "./handlers/feedback/outbox.js";
+import { maybeInjectProbe } from "./handlers/feedback/probes.js";
 // V2 adapters (extracted from server.ts — each owns its routing/transformation logic)
 import { handlePersonaAdapter } from "./handlers/persona/adapter.js";
 import { handleWorkflowAdapter } from "./handlers/workflow/adapter.js";
 import { handleSyncAdapter } from "./handlers/sync/adapter.js";
 import { handleDemoAdapter } from "./handlers/demo/adapter.js";
 import { handleDebugAdapter } from "./handlers/debug/adapter.js";
+import { handleConversationAdapter } from "./handlers/conversation/adapter.js";
+import { handleTemplateAdapter } from "./handlers/template/adapter.js";
 // Start token initialization in background (non-blocking)
 void initializeApiKeyTokens();
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Definitions
 // ─────────────────────────────────────────────────────────────────────────────
 //
-// V2 TOOLS (7 tools) - LLM-optimized minimal interface
-//   - env, persona, catalog, workflow, sync, toolkit_feedback, debug
+// V2 TOOLS (9 tools) - LLM-optimized minimal interface
+//   - env, persona, catalog, workflow, sync, toolkit_feedback, debug, conversation, template
 //   - Defined in: ./tools.ts
 //
 // NAMING CONVENTION:
@@ -58,7 +61,7 @@ void initializeApiKeyTokens();
 /**
  * Generate all available tools
  *
- * V2: 7 tools (persona, catalog, workflow, sync, env, toolkit_feedback, debug) - LLM-optimized
+ * V2: 9 tools (persona, catalog, workflow, sync, env, toolkit_feedback, debug, conversation, template) - LLM-optimized
  *
  * Why V2:
  * - Minimal tool count optimizes LLM tool selection
@@ -73,6 +76,8 @@ function generateAllTools() {
 }
 // Generate tools (called once at module load)
 const TOOLS = generateAllTools();
+// Track whether the first-session opt-out notice has been shown
+let firstNoticeShown = false;
 const toolHandlers = {
     // ═══════════════════════════════════════════════════════════════════════════
     // V2 TOOLS — LLM-optimized interface
@@ -91,7 +96,7 @@ const toolHandlers = {
         return handleAction(args, client);
     },
     template: async (args) => {
-        return handleTemplate(args);
+        return handleTemplateAdapter(args, createClient, getDefaultEnvName);
     },
     data: async (args) => {
         const client = createClient(args.env);
@@ -138,6 +143,9 @@ const toolHandlers = {
     debug: async (args) => {
         return handleDebugAdapter(args, createClient, getDefaultEnvName);
     },
+    conversation: async (args) => {
+        return handleConversationAdapter(args, createClient, getDefaultEnvName);
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
@@ -172,6 +180,12 @@ function determineOperation(toolName, args) {
     if (toolName === "debug") {
         return args.method ? String(args.method) : "conversations";
     }
+    if (toolName === "conversation") {
+        return args.method ? String(args.method) : "create";
+    }
+    if (toolName === "template") {
+        return args.method ? String(args.method) : "list";
+    }
     return toolName;
 }
 // ─────────────────────────────────────────────────────────────────────────────
@@ -238,6 +252,15 @@ export async function startMcpServer() {
             if (toolGuidance?.nextSteps?.[operation]) {
                 response._next_step = toolGuidance.nextSteps[operation];
             }
+            // Inject targeted probe question if conditions are met
+            maybeInjectProbe(response, name, operation);
+            // First-session opt-out notice (shown once)
+            if (!firstNoticeShown && name !== "toolkit_feedback") {
+                response._notice =
+                    "This toolkit collects anonymous usage telemetry to improve quality. " +
+                        "Set EMA_FEEDBACK_DISABLED=1 to opt out. See ~/.ema-mcp/outbox/sent-log.jsonl for transparency.";
+                firstNoticeShown = true;
+            }
             return {
                 content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
             };
@@ -333,6 +356,16 @@ export async function startMcpServer() {
         : TOOLKIT_VERSION;
     const toolCount = TOOLS.length;
     console.error(`Ema MCP Server started: ${TOOLKIT_NAME}@${buildInfo} | ${toolCount} tools`);
+    // Flush any pending outbox entries from previous sessions (catches npx ephemeral runs)
+    flushOutbox(TOOLKIT_VERSION).catch(() => { });
+    startFlushTimer(TOOLKIT_VERSION);
+    // Graceful shutdown — flush remaining outbox entries before exit
+    const gracefulShutdown = () => {
+        stopFlushTimer(TOOLKIT_VERSION).catch(() => { });
+    };
+    process.on("SIGTERM", gracefulShutdown);
+    process.on("SIGINT", gracefulShutdown);
+    process.on("beforeExit", gracefulShutdown);
 }
 // CLI support: allow --help to exit (used by build:verify)
 const argv = process.argv.slice(2);