@ema.co/mcp-toolkit 2026.3.24 → 2026.3.25-2

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

@@ -18,6 +18,7 @@
  */
 import { generateSchema } from "../../domain/generation-schema.js";
 import { fingerprintPersona } from "../../../sync.js";
+import { LLM_ACTIONS, LLM_WIDGET_INPUTS, widgetBinding } from "../../../config/widget-bindings.js";
 // Re-export types
 export * from "./types.js";
 // Re-export utilities  
@@ -172,7 +173,7 @@ function slimWorkflowDef(wf) {
  *
  * LLM uses this to generate or modify workflow_def
  */
-async function handleWorkflowGet(args, client) {
+async function handleWorkflowGet(args, client, cache) {
     const personaId = args.persona_id;
     if (!personaId) {
         return { error: "persona_id required" };
@@ -191,8 +192,8 @@ async function handleWorkflowGet(args, client) {
         name: w.name,
         type: w.type,
     }));
-    // Get generation schema for LLM
-    const schema = generateSchema();
+    // Get generation schema for LLM — API-first + DE-first for structural invariants
+    const schema = await generateSchema(client, cache);
     // Get deprecated actions (API-first, with fallback)
     const { deprecated: deprecatedActions, source: deprecationSource } = await getDeprecatedActions(client);
     // Check if current workflow uses deprecated actions
@@ -217,6 +218,17 @@ async function handleWorkflowGet(args, client) {
             agents: schema.agents,
             constraints: schema.constraints,
             input_rules: schema.inputRules,
+            widget_bindings: LLM_WIDGET_INPUTS.map(b => ({
+                input: b.inputName,
+                widget: b.widgetName,
+                required: b.required,
+                binding: widgetBinding(b),
+            })),
+            llm_actions: [...LLM_ACTIONS],
+            _source: schema.schema_source,
+            ...(schema.schema_source === "catalog" ? {
+                _warning: "Using static catalog (API unavailable) — input lists may be incomplete. Search knowledge('<action_name> inputs') for full definitions.",
+            } : {}),
         },
         // HARD REQUIREMENTS (must be satisfied)
         hard_requirements: {
@@ -255,8 +267,8 @@ async function handleWorkflowGet(args, client) {
                 "",
                 "IMPORTANT: Before deploying changes, re-run workflow(mode='get') and pass fingerprint as base_fingerprint to workflow(mode='deploy').",
                 "To analyze workflow health:",
-                "1. Fetch ema://rules/anti-patterns",
-                "2. Fetch ema://rules/structural-invariants",
+                "1. Search knowledge('workflow anti-patterns')",
+                "2. Search knowledge('structural invariants')",
                 "3. Check workflow_def nodes against the rules",
                 "4. Report issues YOU find (MCP does not pre-compute)",
                 "",
@@ -264,8 +276,8 @@ async function handleWorkflowGet(args, client) {
             ]
             : [
                 "To analyze workflow health:",
-                "1. Fetch ema://rules/anti-patterns",
-                "2. Fetch ema://rules/structural-invariants",
+                "1. Search knowledge('workflow anti-patterns')",
+                "2. Search knowledge('structural invariants')",
                 "3. Check workflow_def nodes against the rules",
                 "4. Report issues YOU find (MCP does not pre-compute)",
                 "",
@@ -310,14 +322,14 @@ async function handleWorkflowGet(args, client) {
  * PUBLIC modes: get, deploy, validate, optimize
  * INTERNAL modes: modify, generate, analyze, compare (called from persona tool)
  */
-export async function handleWorkflow(args, client, _getTemplateId) {
+export async function handleWorkflow(args, client, _getTemplateId, cache) {
     const personaId = args.persona_id;
     const workflowDef = args.workflow_def;
     // Explicit mode takes priority
     const mode = args.mode;
     // PUBLIC MODES (from workflow tool)
     if (mode === "get") {
-        return handleWorkflowGet(args, client);
+        return handleWorkflowGet(args, client, cache);
     }
     if (mode === "deploy") {
         return handleWorkflowDeploy(args, client);
@@ -347,10 +359,10 @@ export async function handleWorkflow(args, client, _getTemplateId) {
     if (mode === "analyze" || mode === "compare") {
         return {
             error: `Mode "${mode}" has been removed.`,
-            reason: "LLM can do analysis/comparison by fetching ema://rules/* and reasoning about workflow_def.",
+            reason: "LLM can do analysis/comparison by fetching knowledge('anti-patterns') and reasoning about workflow_def.",
             correct_flow: [
                 "1. workflow(mode='get', persona_id='...') - get current workflow_def",
-                "2. Fetch ema://rules/anti-patterns and ema://rules/structural-invariants",
+                "2. Fetch knowledge('anti-patterns') and knowledge('structural invariants')",
                 "3. LLM analyzes/compares the data",
             ],
         };

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

@@ -5,7 +5,8 @@
  * Validates: wiring, deprecated actions, circular refs, categorizer fallbacks, etc.
  */
 import { validateWorkflowStatic } from "../../domain/workflow-static-validator.js";
-import { validateWorkflowSchema, validateNodeInputsWired, validateNoDeprecatedActions, validateExternalActionCallerTools, validateNoCircularReferences, validateCategorizersFallback, checkBestPractices, checkRunIfGatedDependencies, } from "./validation.js";
+import { validateWorkflowDefStructure } from "../../domain/workflow-def-validator.js";
+import { validateWorkflowSchema, validateNodeInputsWired, validateNoDeprecatedActions, validateExternalActionCallerTools, validateNoCircularReferences, validateCategorizersFallback, checkBestPractices, checkRunIfGatedDependencies, detectTypeMismatches, } from "./validation.js";
 import { DEPRECATED_ACTIONS_MAP } from "../../../sdk/generated/deprecated-actions.js";
 /**
  * Handle workflow(mode="validate") - pre-deployment validation
@@ -85,6 +86,26 @@ export async function handleWorkflowValidate(args, client) {
             _tip: "Fix structural errors first. Use workflow(mode='get') to see valid structure.",
         };
     }
+    // 0b. Proto structural validation — catches empty namespaces, wrong named_inputs
+    // format, invalid extraction_columns, missing typeArguments, etc. that cause
+    // opaque API 500s. MUST match the deploy handler's validation (deploy.ts:106).
+    const protoValidation = validateWorkflowDefStructure(workflowToValidate);
+    const protoErrors = protoValidation.issues.filter(i => i.severity === "error");
+    if (protoErrors.length > 0) {
+        for (const issue of protoErrors) {
+            errors.push({
+                check: "proto_structural",
+                message: `${issue.path}: ${issue.message}`,
+            });
+        }
+    }
+    const protoWarnings = protoValidation.issues.filter(i => i.severity === "warning");
+    for (const issue of protoWarnings) {
+        warnings.push({
+            check: "proto_structural",
+            message: `${issue.path}: ${issue.message}`,
+        });
+    }
     // 1. Node inputs must be wired
     const inputsValidation = validateNodeInputsWired(workflowToValidate);
     if (!inputsValidation.valid) {
@@ -155,6 +176,14 @@ export async function handleWorkflowValidate(args, client) {
             message: gd.issue,
         });
     }
+    // 8. Type mismatch detection (warnings — uses generation schema type info)
+    const typeMismatches = detectTypeMismatches(workflowToValidate);
+    for (const tm of typeMismatches) {
+        warnings.push({
+            check: "type_mismatch",
+            message: `Type mismatch: "${tm.action}.${tm.input}" expects ${tm.expectedType} but receives ${tm.sourceType} from "${tm.sourceAction}.${tm.sourceOutput}"`,
+        });
+    }
     const valid = errors.length === 0;
     return {
         valid,

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

@@ -17,7 +17,7 @@
 import { ConnectError, Code } from "@connectrpc/connect";
 import { validateWorkflowDefSchema } from "../../domain/workflow-def-schema.js";
 import { LLM_ACTIONS, MODEL_CONFIG, widgetBinding } from "../../../config/widget-bindings.js";
-import { generateSchema, isTypeCompatible } from "../../domain/generation-schema.js";
+import { generateSchemaSync, isTypeCompatible } from "../../domain/generation-schema.js";
 // Re-export schema validation for use by other handlers
 export { validateWorkflowDefSchema };
 /**
@@ -585,7 +585,7 @@ export function validateNodeInputsWired(workflowDef) {
         fixSteps.push("To find required inputs for an action:");
         fixSteps.push("  knowledge(\"id=<action_type>\")");
         fixSteps.push("For full input format reference:");
-        fixSteps.push("  Fetch ema://schema/workflow-def → 'Raw workflow_def Input Binding Formats' section");
+        fixSteps.push("  Search knowledge(\"input binding formats\") for correct wiring structure");
         return {
             valid: false,
             error: `DEPLOYMENT BLOCKED: ${unwiredNodes.length} node(s) have empty inputs and are not wired to any data source.`,
@@ -1017,7 +1017,7 @@ export function checkBestPractices(workflowDef) {
                     issue: "custom_agent output consumed by json_mapper but no output_fields defined",
                     recommendation: "Add output_fields with extraction columns matching your JSON keys, OR " +
                         "ensure task_instructions prompt says 'output ONLY JSON, no markdown'. " +
-                        "See ema://rules/json-output-patterns for the full pattern.",
+                        "Search knowledge(\"json output patterns\") for the full pattern.",
                     severity: "warning",
                 });
             }
@@ -1163,7 +1163,7 @@ export function checkRunIfGatedDependencies(workflowDef) {
  * the schema may not cover all actions (custom actions, unknown versions).
  */
 export function detectTypeMismatches(workflowDef) {
-    const schema = generateSchema();
+    const schema = generateSchemaSync();
     const actions = (workflowDef.actions ?? []);
     const mismatches = [];
     // Build action name → schema agent lookup

package/dist/mcp/server.js

@@ -16,7 +16,7 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, SubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 // Environment configuration, client factories, and toolkit metadata
 import { TOOLKIT_NAME, TOOLKIT_VERSION, TOOLKIT_COMMIT, createClient, getSyncSDK, getAvailableEnvironments, getDefaultEnvName, initializeApiKeyTokens, } from "./handlers/env/config.js";
 export { TOOLKIT_NAME, TOOLKIT_VERSION, TOOLKIT_COMMIT };
@@ -28,6 +28,27 @@ import { generateServerInstructions, getContextualTip, TOOL_GUIDANCE } from "./g
 // Set EMA_GUIDANCE_CACHE=false to disable and use local constants only.
 import { GuidanceCache } from "../knowledge/guidance-cache.js";
 import { createDeSearchAdapter } from "../knowledge/search-adapter.js";
+// Dynamic contextual guidance middleware — DE-first, defaults fallback
+import { enrichWithGuidance } from "./guidance/middleware.js";
+import { searchDocuments } from "../knowledge/search-client.js";
+// Live DE search for contextual error guidance.
+// On errors, the middleware queries DE with the error context to find
+// relevant solutions — including agent-published fixes for similar errors.
+const guidanceSearchFn = async (query, options) => {
+    const response = await searchDocuments(query, {
+        topK: options?.limit ?? 3,
+        filters: { type: ["contextual-guidance", "guidance", "entity", "pattern"] },
+    });
+    return response.results.map((r) => {
+        const doc = r.document;
+        return {
+            id: r.id,
+            score: r.score,
+            content: doc.description,
+            structData: doc.structData,
+        };
+    });
+};
 const cacheEnabled = process.env.EMA_GUIDANCE_CACHE?.trim().toLowerCase() !== "false";
 const guidanceCache = cacheEnabled ? new GuidanceCache(createDeSearchAdapter()) : undefined;
 // Cache is warmed in startMcpServer() before generating server instructions.
@@ -162,7 +183,7 @@ const toolHandlers = {
     },
     // V2 adapters — routing + transformation extracted to handler files
     workflow: async (args) => {
-        return handleWorkflowAdapter(args, createClient, getDefaultEnvName);
+        return handleWorkflowAdapter(args, createClient, getDefaultEnvName, guidanceCache);
     },
     sync: async (args) => {
         return handleSyncAdapter(args, createClient, getDefaultEnvName, getSyncSDK);
@@ -355,15 +376,44 @@ export async function startMcpServer() {
             if (name !== "feedback" && name !== "toolkit_feedback") {
                 recordTelemetry({ type: "tool_call", tool: name, op: operation, ok: true, ms: elapsedMs }).catch(() => { });
             }
+            // ── Dynamic Contextual Guidance (DE-first, defaults fallback) ──────
+            // Classifies result shape and injects error-aware hints BEFORE
+            // the legacy hint injection layers below. Only sets fields the
+            // handler didn't already set.
+            const response = result;
+            try {
+                const method = (argsObj.method ?? argsObj.mode ?? operation);
+                let profileName;
+                let envName;
+                try {
+                    const p = getActiveProfile();
+                    profileName = p?.name;
+                    envName = p?.env;
+                }
+                catch { /* config not available */ }
+                await enrichWithGuidance(response, {
+                    tool: name,
+                    method,
+                    args: argsObj,
+                    result: response,
+                    env: envName,
+                    profile: profileName,
+                }, guidanceCache, guidanceSearchFn);
+            }
+            catch {
+                // Guidance middleware must never break tool dispatch
+            }
+            // ── Legacy hint injection (kept for backwards compatibility) ────────
+            // These layers run AFTER the middleware. They use ??= so they won't
+            // overwrite hints the middleware already set.
             // Get contextual tip based on operation and result
             const tip = getContextualTip({
                 operation,
                 args: argsObj,
-                result: result,
+                result: response,
             }, guidanceCache);
             // Add tip and next_step to response if available
-            const response = result;
-            if (tip) {
+            if (tip && !response._tip) {
                 response._tip = {
                     message: tip.message,
                     level: tip.level,
@@ -521,6 +571,8 @@ export async function startMcpServer() {
             ],
         };
     });
+    // Subscribe handler — no-op (resources are generated on-read, no push notifications yet)
+    server.setRequestHandler(SubscribeRequestSchema, async () => ({}));
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Log startup with version, commit, and tool count

package/dist/mcp/tools.js

@@ -289,10 +289,10 @@ Sync a persona between environments (dev, staging, prod). Always preview first.
                         properties: {
                             method: {
                                 type: "string",
-                                enum: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+                                enum: ["conversations", "conversation_detail", "show_work", "action_detail", "workflow_runs", "search"],
                                 description: "Debug operation to perform (required)"
                             },
-                            conversation_id: { type: "string", description: "Conversation ID (for conversation_detail)" },
+                            conversation_id: { type: "string", description: "Conversation ID (for conversation_detail). Also accepted by show_work." },
                             workflow_run_id: { type: "string", description: "Workflow run ID (for show_work, action_detail)" },
                             action_name: { type: "string", description: "Action name (for action_detail)" },
                             query: { type: "string", description: "Search query (for search)" },
@@ -777,6 +777,11 @@ Include \`knowledge_ref\` to correlate feedback with specific knowledge document
 - \`feedback(method="analyze")\` - aggregate local insights and actionable items
 - \`feedback(method="analyze", scope="global")\` - [Ema maintainers only] aggregate across ALL clients from cloud storage (requires EMA_INTERNAL=1 + gcloud auth with @ema.co account)
 
+## Inter-Agent Messaging
+- \`feedback(method="local")\` - read scoped messages from the in-memory session buffer
+- \`feedback(method="local", scope="role:compliance")\` - filter by message scope
+Messages are emitted by MCP response actions (search, publish, deploy) and stay in-memory for the session. Use for coordination between agents working on the same task.
+
 ## Maintenance
 - \`feedback(method="flush")\` - force immediate upload of pending outbox entries to remote storage
 
@@ -791,8 +796,8 @@ Include \`knowledge_ref\` to correlate feedback with specific knowledge document
                 properties: {
                     method: {
                         type: "string",
-                        enum: ["submit", "list", "analyze", "flush"],
-                        description: "Operation to perform (required)",
+                        enum: ["submit", "list", "local", "analyze", "flush"],
+                        description: "Operation to perform (required). 'local' reads scoped messages from the in-memory session buffer for inter-agent coordination.",
                     },
                     category: {
                         type: "string",
@@ -858,12 +863,14 @@ Include \`knowledge_ref\` to correlate feedback with specific knowledge document
 3. \`debug(method="show_work", persona_id="abc", workflow_run_id="...")\` - see all actions' execution traces
 4. \`debug(method="action_detail", persona_id="abc", workflow_run_id="...", action_name="...")\` - deep trace
 
-## Dashboard personas (no conversations)
-Dashboard personas do NOT create conversations. Skip steps 1-2:
-1. Get \`workflow_run_id\` from the dashboard UI debug view
+## Dashboard personas
+1. \`debug(method="workflow_runs", persona_id="abc")\` - list recent workflow runs (dashboard rows)
 2. \`debug(method="show_work", persona_id="abc", workflow_run_id="...")\` - see execution traces
 3. \`debug(method="action_detail", persona_id="abc", workflow_run_id="...", action_name="...")\` - deep trace
 
+## Auto-routing
+If you pass a workflow_run_id to \`conversation_detail\`, it auto-routes to \`show_work\`. \`show_work\` also accepts \`conversation_id\` as an alias for \`workflow_run_id\`.
+
 ## Also available as persona sub-resource
 - \`persona(id="abc", debug={method:"conversations"})\` - same as debug tool but scoped to persona`,
             inputSchema: {
@@ -871,20 +878,20 @@ Dashboard personas do NOT create conversations. Skip steps 1-2:
                 properties: {
                     method: {
                         type: "string",
-                        enum: ["conversations", "conversation_detail", "show_work", "action_detail"],
+                        enum: ["conversations", "conversation_detail", "show_work", "action_detail", "workflow_runs", "search"],
                         description: "Operation to perform (required)",
                     },
                     persona_id: {
                         type: "string",
-                        description: "Persona ID (required for conversations, show_work, action_detail, search)",
+                        description: "Persona ID (required for conversations, workflow_runs, show_work, action_detail, search)",
                     },
                     conversation_id: {
                         type: "string",
-                        description: "Conversation ID (for method=conversation_detail, or to scope search)",
+                        description: "Conversation ID (for method=conversation_detail, or to scope search). Also accepted by show_work as alias for workflow_run_id.",
                     },
                     workflow_run_id: {
                         type: "string",
-                        description: "Workflow run ID (for method=show_work, action_detail)",
+                        description: "Workflow run ID (for method=show_work, action_detail). Auto-discovered via workflow_runs for dashboard personas.",
                     },
                     action_name: {
                         type: "string",

package/dist/sdk/client.js

@@ -1028,13 +1028,13 @@ export class EmaClient {
      * that define pre-configured AI Employee configurations.
      */
     async getPersonaTemplates() {
-        // Try GET first (newer API), fall back to POST
-        let resp = await this.requestWithRetries("GET", "/api/personas/get_persona_templates", {});
-        if (resp.status === 405) {
-            // Fall back to POST
-            resp = await this.requestWithRetries("POST", "/api/personas/get_persona_templates", {
-                json: {},
-            });
+        // POST first (original, frontend still uses), GET fallback (planned replacement).
+        // Once backend drops POST, GET takes over automatically.
+        let resp = await this.requestWithRetries("POST", "/api/personas/get_persona_templates", {
+            json: {},
+        });
+        if (!resp.ok || resp.status === 405) {
+            resp = await this.requestWithRetries("GET", "/api/personas/get_persona_templates", {});
         }
         if (!resp.ok) {
             throw new EmaApiError({

package/dist/sdk/ema-client.js

@@ -293,9 +293,24 @@ export class EmaClientV2 {
     // Persona Templates - REST API
     // ─────────────────────────────────────────────────────────────────────────────
     /**
-     * List all persona templates available to the tenant
+     * List all persona templates available to the tenant.
+     *
+     * Backend has both POST (original, frontend still uses) and GET (planned
+     * replacement — TODO in backend to drop POST once frontend migrates).
+     * POST first since GET is not yet deployed everywhere; GET as fallback
+     * so we're ready when POST is eventually removed.
      */
     async listPersonaTemplates() {
+        try {
+            const result = await api.listPersonaTemplatesPost({ client: this.restClient });
+            const response = result.data;
+            const templates = response?.templates ?? [];
+            if (templates.length > 0)
+                return templates;
+        }
+        catch {
+            // POST failed (removed or 405) — fall through to GET
+        }
         const result = await api.listPersonaTemplates({ client: this.restClient });
         const response = result.data;
         return response?.templates ?? [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.3.24",
+  "version": "2026.3.25-2",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",