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

package/dist/knowledge/guidance-cache.js

@@ -32,6 +32,7 @@ export class GuidanceCache {
     patterns = [];
     questions = [];
     invariants = [];
+    contextualGuidanceMap = new Map();
     warmedAt = null;
     constructor(searchFn, config) {
         this.searchFn = searchFn;
@@ -122,6 +123,32 @@ export class GuidanceCache {
         this.maybeRefresh();
         return this.invariants;
     }
+    /**
+     * Get contextual guidance for a specific key.
+     * Keys follow the pattern: "{tool}.{method}.{result_shape}"
+     * Also checks wildcards: "*.{method}.{shape}", "{tool}.*.{shape}", "*.*.{shape}"
+     */
+    getContextualGuidance(tool, method, shape) {
+        this.maybeRefresh();
+        // Try exact match first, then progressively broader wildcards
+        const candidates = [
+            `${tool}.${method}.${shape}`,
+            `${tool}.*.${shape}`,
+            `*.${method}.${shape}`,
+            `*.*.${shape}`,
+        ];
+        for (const key of candidates) {
+            const atom = this.contextualGuidanceMap.get(key);
+            if (atom)
+                return atom;
+        }
+        return undefined;
+    }
+    /** All contextual guidance atoms (for debugging/inspection). */
+    getAllContextualGuidance() {
+        this.maybeRefresh();
+        return Array.from(this.contextualGuidanceMap.values());
+    }
     // ── Internals ───────────────────────────────────────────────────────────
     clear() {
         this.rules = [];
@@ -131,6 +158,7 @@ export class GuidanceCache {
         this.patterns = [];
         this.questions = [];
         this.invariants = [];
+        this.contextualGuidanceMap = new Map();
     }
     /**
      * Index artifacts by reading structured data from structData.data.
@@ -184,6 +212,13 @@ export class GuidanceCache {
                     case "structural-invariant":
                         this.invariants.push(data);
                         break;
+                    case "contextual-guidance": {
+                        const atom = data;
+                        const key = atom.key
+                            ?? `${atom.tool ?? "*"}.${atom.method ?? "*"}.${atom.result_shape ?? "*"}`;
+                        this.contextualGuidanceMap.set(key, { ...atom, key });
+                        break;
+                    }
                     default:
                         break;
                 }
@@ -209,10 +244,16 @@ export class GuidanceCache {
             return "qualifying-question";
         if (tags.includes("structural-invariant"))
             return "structural-invariant";
+        if (tags.includes("structural-invariant"))
+            return "structural-invariant";
+        if (tags.includes("contextual-guidance"))
+            return "contextual-guidance";
         if (name.includes("tool-guidance"))
             return "tool-guidance";
         if (name.startsWith("invariant-"))
             return "structural-invariant";
+        if (name.includes("contextual-guidance"))
+            return "contextual-guidance";
         return undefined;
     }
 }

package/dist/mcp/domain/generation-schema.js

@@ -1,8 +1,12 @@
 /**
  * Generation Schema
  *
- * Transforms AGENT_CATALOG into a compact format for workflow generation.
- * This avoids the token waste of including full documentation in prompts.
+ * API-first schema generation: fetches live action definitions from the
+ * backend, enriches with catalog metadata, falls back to static catalog
+ * when the API is unavailable.
+ *
+ * This ensures agents always see the FULL set of required inputs/outputs
+ * as defined by the backend, not a hand-curated subset from documentation.
  *
  * The auto-builder sends ~70K tokens of documentation per request.
  * This schema reduces that to ~5K tokens of actionable constraints.
@@ -11,42 +15,213 @@ import { AGENT_CATALOG } from "../knowledge.js";
 import { INPUT_SOURCE_RULES } from "./validation-rules.js";
 import { STRUCTURAL_INVARIANTS } from "./structural-rules.js";
 import { LLM_ACTIONS, LLM_WIDGET_INPUTS, widgetBinding } from "../../config/widget-bindings.js";
-// ─────────────────────────────────────────────────────────────────────────────
-// Schema Generation
-// ─────────────────────────────────────────────────────────────────────────────
+import { searchDocuments } from "../../knowledge/search-client.js";
+export async function buildCompactAgents(client) {
+    // Build catalog index for enrichment
+    const catalogIndex = new Map();
+    for (const agent of AGENT_CATALOG) {
+        catalogIndex.set(agent.actionName, agent);
+    }
+    // Try API-first for full input/output definitions
+    if (client) {
+        try {
+            const apiAgents = await buildFromApi(client, catalogIndex);
+            if (Object.keys(apiAgents).length > 0) {
+                return { agents: apiAgents, source: "api" };
+            }
+        }
+        catch (e) {
+            console.error(`[generation-schema] API listActions failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // DE middle layer: search for action definitions in Discovery Engine
+    try {
+        const deAgents = await buildFromDE(catalogIndex);
+        if (deAgents && Object.keys(deAgents).length > 0) {
+            return { agents: deAgents, source: "api" };
+        }
+    }
+    catch (e) {
+        console.error(`[generation-schema] DE search failed, using static catalog: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Final fallback: static catalog (may have incomplete inputs)
+    return { agents: buildFromCatalog(catalogIndex), source: "catalog" };
+}
+/** Synchronous version for backwards compatibility (uses catalog only). */
+export function buildCompactAgentsSync() {
+    const catalogIndex = new Map();
+    for (const agent of AGENT_CATALOG) {
+        catalogIndex.set(agent.actionName, agent);
+    }
+    return { agents: buildFromCatalog(catalogIndex), source: "catalog" };
+}
 /**
- * Build a compact agent lookup from the full catalog
+ * Build agents from live API — full input/output definitions.
+ * Enriches with catalog metadata (description, whenToUse, etc.).
  */
-export function buildCompactAgents() {
+async function buildFromApi(client, catalogIndex) {
+    const actionDTOs = await client.listActions();
     const agents = {};
-    for (const agent of AGENT_CATALOG) {
+    for (const dto of actionDTOs) {
+        const typeName = dto.typeName;
+        const name = typeName?.name?.name;
+        if (!name)
+            continue;
         const inputs = {};
-        for (const input of agent.inputs ?? []) {
-            inputs[input.name] = { type: input.type, required: input.required };
+        const outputs = {};
+        // Parse inputs from API response (FULL definition)
+        const inputsObj = dto.inputs?.inputs;
+        if (inputsObj && typeof inputsObj === "object") {
+            for (const [inputName, inputDef] of Object.entries(inputsObj)) {
+                const def = inputDef;
+                inputs[inputName] = {
+                    type: (def.type?.wellKnownType ?? "WELL_KNOWN_TYPE_ANY"),
+                    required: !def.isOptional,
+                };
+            }
         }
+        // Parse outputs from API response
+        const outputsObj = dto.outputs?.outputs;
+        if (outputsObj && typeof outputsObj === "object") {
+            for (const [outputName, outputDef] of Object.entries(outputsObj)) {
+                const def = outputDef;
+                outputs[outputName] = (def.type?.wellKnownType ?? "WELL_KNOWN_TYPE_ANY");
+            }
+        }
+        // Inject widget inputs for LLM actions (may already be in API response)
+        if (LLM_ACTIONS.has(name)) {
+            for (const binding of LLM_WIDGET_INPUTS) {
+                if (!inputs[binding.inputName]) {
+                    inputs[binding.inputName] = {
+                        type: "WELL_KNOWN_TYPE_ANY",
+                        required: binding.required,
+                    };
+                }
+            }
+        }
+        // Enrich with catalog metadata (doesn't override inputs/outputs)
+        const catalogEntry = catalogIndex.get(name);
+        agents[name] = {
+            name: catalogEntry?.displayName ?? name,
+            category: catalogEntry?.category ?? "unknown",
+            description: catalogEntry?.description,
+            whenToUse: catalogEntry?.whenToUse,
+            aliases: catalogEntry?.aliases,
+            tier: catalogEntry?.tier,
+            inputs,
+            outputs,
+            constraints: catalogEntry?.criticalRules,
+        };
+    }
+    return agents;
+}
+/**
+ * Build agents from DE search — middle layer between API and static catalog.
+ * Queries DE for entity-type action docs, matches to catalog by action name
+ * extracted from the document ID (e.g., "entity:search_v2" → "search_v2").
+ * Returns null if DE search yields no action entities.
+ */
+async function buildFromDE(catalogIndex) {
+    const response = await searchDocuments("action definitions inputs outputs workflow actions", {
+        topK: 15,
+        filters: { type: ["entity"] },
+    });
+    if (!response.results || response.results.length === 0)
+        return null;
+    const deAgents = {};
+    const deActionNames = new Set();
+    for (const result of response.results) {
+        const doc = result.document;
+        if (!doc?.id)
+            continue;
+        // Extract action name from entity ID (e.g., "entity:search_v2" → "search_v2")
+        const actionName = doc.id.startsWith("entity:") ? doc.id.slice("entity:".length) : "";
+        if (!actionName)
+            continue;
+        deActionNames.add(actionName);
+        const catalogEntry = catalogIndex.get(actionName);
+        const inputs = {};
         const outputs = {};
-        for (const output of agent.outputs ?? []) {
-            outputs[output.name] = output.type;
+        // Use catalog I/O specs (DE entities don't carry structured I/O)
+        if (catalogEntry) {
+            for (const input of catalogEntry.inputs ?? []) {
+                inputs[input.name] = { type: input.type, required: input.required };
+            }
+            for (const output of catalogEntry.outputs ?? []) {
+                outputs[output.name] = output.type;
+            }
         }
-        if (LLM_ACTIONS.has(agent.actionName)) {
+        if (LLM_ACTIONS.has(actionName)) {
             for (const binding of LLM_WIDGET_INPUTS) {
+                if (!inputs[binding.inputName]) {
+                    inputs[binding.inputName] = {
+                        type: "WELL_KNOWN_TYPE_ANY",
+                        required: binding.required,
+                    };
+                }
+            }
+        }
+        deAgents[actionName] = {
+            name: catalogEntry?.displayName ?? doc.name ?? actionName,
+            category: catalogEntry?.category ?? "unknown",
+            description: catalogEntry?.description ?? doc.description ?? doc.summary,
+            whenToUse: catalogEntry?.whenToUse,
+            aliases: catalogEntry?.aliases,
+            tier: catalogEntry?.tier,
+            inputs,
+            outputs,
+            constraints: catalogEntry?.criticalRules,
+        };
+    }
+    if (deActionNames.size === 0)
+        return null;
+    // Supplement with catalog entries not found in DE
+    for (const [actionName, catalogEntry] of catalogIndex) {
+        if (deAgents[actionName])
+            continue;
+        deAgents[actionName] = buildCatalogAgent(actionName, catalogEntry);
+    }
+    return deAgents;
+}
+/** Build a CompactAgent from a single catalog entry. */
+function buildCatalogAgent(actionName, entry) {
+    const inputs = {};
+    for (const input of entry.inputs ?? []) {
+        inputs[input.name] = { type: input.type, required: input.required };
+    }
+    const outputs = {};
+    for (const output of entry.outputs ?? []) {
+        outputs[output.name] = output.type;
+    }
+    if (LLM_ACTIONS.has(actionName)) {
+        for (const binding of LLM_WIDGET_INPUTS) {
+            if (!inputs[binding.inputName]) {
                 inputs[binding.inputName] = {
                     type: "WELL_KNOWN_TYPE_ANY",
                     required: binding.required,
                 };
             }
         }
-        agents[agent.actionName] = {
-            name: agent.displayName,
-            category: agent.category,
-            description: agent.description,
-            whenToUse: agent.whenToUse,
-            aliases: agent.aliases,
-            tier: agent.tier,
-            inputs,
-            outputs,
-            constraints: agent.criticalRules,
-        };
+    }
+    return {
+        name: entry.displayName,
+        category: entry.category,
+        description: entry.description,
+        whenToUse: entry.whenToUse,
+        aliases: entry.aliases,
+        tier: entry.tier,
+        inputs,
+        outputs,
+        constraints: entry.criticalRules,
+    };
+}
+/**
+ * Build agents from static AGENT_CATALOG (fallback when API unavailable).
+ */
+function buildFromCatalog(catalogIndex) {
+    const agents = {};
+    for (const [actionName, entry] of catalogIndex) {
+        agents[actionName] = buildCatalogAgent(actionName, entry);
     }
     return agents;
 }
@@ -119,15 +294,37 @@ export function buildConstraints() {
     };
 }
 /**
- * Generate the complete compact schema for workflow generation
+ * Generate the complete compact schema for workflow generation.
+ * API-first: fetches live action definitions when client is provided.
  */
-export function generateSchema(cache) {
-    // DE-first for structural invariants: use cache if populated, fall back to local constants
+export async function generateSchema(client, cache) {
+    const invariants = cache?.getInvariants()?.length
+        ? cache.getInvariants()
+        : STRUCTURAL_INVARIANTS;
+    const { agents, source } = await buildCompactAgents(client);
+    return {
+        agents,
+        schema_source: source,
+        typeRules: buildTypeRules(),
+        inputRules: INPUT_SOURCE_RULES.map(rule => ({
+            action: rule.actionPattern,
+            recommended: rule.recommended,
+            avoid: rule.avoid,
+            severity: rule.severity,
+        })),
+        constraints: buildConstraints(),
+        structuralInvariants: invariants.map(({ id, rule, violation, fix, severity }) => ({ id, rule, violation, fix, severity })),
+    };
+}
+/** Synchronous version (catalog-only, no API). For callers that can't await. */
+export function generateSchemaSync(cache) {
     const invariants = cache?.getInvariants()?.length
         ? cache.getInvariants()
         : STRUCTURAL_INVARIANTS;
+    const { agents, source } = buildCompactAgentsSync();
     return {
-        agents: buildCompactAgents(),
+        agents,
+        schema_source: source,
         typeRules: buildTypeRules(),
         inputRules: INPUT_SOURCE_RULES.map(rule => ({
             action: rule.actionPattern,
@@ -144,7 +341,7 @@ export function generateSchema(cache) {
  * This is ~5K tokens vs ~70K for full documentation
  */
 export function generateSchemaMarkdown(cache) {
-    const schema = generateSchema(cache);
+    const schema = generateSchemaSync(cache);
     let md = `# Workflow Generation Schema\n\n`;
     // Agent summary table with tier and description
     md += `## Available Agents (${Object.keys(schema.agents).length})\n\n`;
@@ -217,7 +414,7 @@ export function generateSchemaMarkdown(cache) {
  * Get compact agent info for a specific action
  */
 export function getAgentSchema(actionName) {
-    const schema = generateSchema();
+    const schema = generateSchemaSync();
     return schema.agents[actionName];
 }
 /**
@@ -231,7 +428,7 @@ export function isTypeCompatible(sourceType, targetType) {
     if (sourceType === targetType)
         return true;
     // Check explicit rules
-    const schema = generateSchema();
+    const schema = generateSchemaSync();
     const rule = schema.typeRules.find(r => r.sourceType === sourceType);
     return rule?.targetTypes.includes(targetType) ?? false;
 }