@ema.co/mcp-toolkit 2026.1.26 → 2026.1.27-1

package/dist/mcp/resources.js

@@ -30,11 +30,13 @@ import { dirname } from "node:path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Import knowledge catalogs for dynamic resources
-import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG } from "../sdk/knowledge.js";
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG, ALL_DEPRECATED_ACTIONS, DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT, WORKFLOW_ENABLING_CONSTRAINTS, MINIMUM_VIABLE_WORKFLOWS, } from "../sdk/knowledge.js";
 import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "../sdk/validation-rules.js";
+import { STRUCTURAL_INVARIANTS } from "../sdk/structural-rules.js";
 import { EmaClient } from "../sdk/client.js";
 import { APISchemaRegistry } from "../sdk/workflow-validator.js";
 import { loadConfigFromJsonEnv, loadConfigOptional, resolveBearerToken, getEnvByName, getMasterEnv, } from "../sdk/config.js";
+import { VOICE_TEMPLATE_FALLBACK, VOICE_TEMPLATE_FIELD_DOCS, } from "../sdk/generated/template-fallbacks.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Security Utilities
 // ─────────────────────────────────────────────────────────────────────────────
@@ -207,6 +209,336 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async () => JSON.stringify(OPTIMIZATION_RULES, null, 2),
     },
+    {
+        uri: "ema://rules/structural-invariants",
+        name: "rules/structural-invariants",
+        description: "Structural invariants: hard constraints that workflows must satisfy (no cycles, reachability, etc.)",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(STRUCTURAL_INVARIANTS, null, 2),
+    },
+    // Deprecated Actions - API-first with fallback
+    {
+        uri: "ema://rules/deprecated-actions",
+        name: "rules/deprecated-actions",
+        description: "Deprecated actions list: actions to avoid in new workflows, with their replacements and migration notes",
+        mimeType: "application/json",
+        generate: async (ctx) => {
+            // Try API first using existing client infrastructure
+            let apiDeprecated = [];
+            let source = "fallback";
+            try {
+                const client = getClientForEnvName(ctx.env);
+                if (client) {
+                    const actions = await client.listActions();
+                    apiDeprecated = actions.filter(a => a.deprecated).map(a => a.id);
+                    source = "api";
+                }
+            }
+            catch {
+                // API unavailable, use fallback
+            }
+            // Merge API deprecated with fallback replacement info
+            const result = {
+                _note: "Actions marked deprecated should not be used in new workflows. Use replacements where available.",
+                _source: source,
+                _api_deprecated_count: apiDeprecated.length,
+                // From API (current deprecated status)
+                api_deprecated: apiDeprecated.length > 0 ? apiDeprecated : undefined,
+                // From fallback (includes replacement info)
+                with_replacement: DEPRECATED_ACTIONS_WITH_REPLACEMENT.map(d => ({
+                    action: d.action,
+                    version: d.version,
+                    replacement: d.replacement,
+                    replacement_version: d.replacementVersion,
+                    migration_notes: d.migrationNotes,
+                })),
+                no_replacement: DEPRECATED_ACTIONS_NO_REPLACEMENT.map(d => ({
+                    action: d.action,
+                    version: d.version,
+                    environment: d.environment,
+                    notes: d.migrationNotes,
+                })),
+                _tip: "Check workflow(mode='get') for deprecation_warnings on specific workflows",
+            };
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        uri: "ema://rules/deprecated-actions-summary",
+        name: "rules/deprecated-actions-summary",
+        description: "Deprecated actions summary: quick reference table of deprecated actions and replacements",
+        mimeType: "text/markdown",
+        generate: async (ctx) => {
+            // Try API first using existing client infrastructure
+            let apiDeprecated = [];
+            let source = "fallback";
+            try {
+                const client = getClientForEnvName(ctx.env);
+                if (client) {
+                    const actions = await client.listActions();
+                    apiDeprecated = actions.filter(a => a.deprecated).map(a => a.id);
+                    source = "api";
+                }
+            }
+            catch {
+                // API unavailable, use fallback
+            }
+            let md = "# Deprecated Actions\n\n";
+            md += "> Do NOT use these actions in new workflows. Use replacements where available.\n\n";
+            md += `> Source: ${source} (${source === "api" ? "live" : "synced 2026-01-26"})\n\n`;
+            if (apiDeprecated.length > 0) {
+                md += "## From API (Current)\n\n";
+                md += "| Action ID | Status |\n";
+                md += "|-----------|--------|\n";
+                for (const id of apiDeprecated) {
+                    md += `| \`${id}\` | DEPRECATED |\n`;
+                }
+                md += "\n";
+            }
+            md += "## Actions with Known Replacements\n\n";
+            md += "| Deprecated Action | Version | Replacement | Notes |\n";
+            md += "|-------------------|---------|-------------|-------|\n";
+            for (const d of DEPRECATED_ACTIONS_WITH_REPLACEMENT) {
+                const repl = Array.isArray(d.replacement) ? d.replacement.join(" or ") : d.replacement;
+                const replVer = d.replacementVersion ? ` ${d.replacementVersion}` : "";
+                md += `| \`${d.action}\` | ${d.version} | \`${repl}\`${replVer} | ${d.migrationNotes || "-"} |\n`;
+            }
+            md += "\n## Actions with No Known Replacement\n\n";
+            md += "| Action | Environment | Notes |\n";
+            md += "|--------|-------------|-------|\n";
+            for (const d of DEPRECATED_ACTIONS_NO_REPLACEMENT) {
+                md += `| \`${d.action}\` | ${d.environment || "all"} | ${d.migrationNotes || "-"} |\n`;
+            }
+            md += `\n**Total Known Deprecated**: ${ALL_DEPRECATED_ACTIONS.length} actions\n`;
+            md += `\n> **Best Practice**: Use \`workflow(mode="get")\` to check for deprecation warnings in specific workflows.\n`;
+            return md;
+        },
+    },
+    // Workflow Enabling Constraints - Requirements for persona activation
+    {
+        uri: "ema://rules/workflow-constraints",
+        name: "rules/workflow-constraints",
+        description: "Workflow enabling constraints: requirements that must be met before a persona can be activated",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify({
+            _note: "These constraints are checked by the Ema backend when enabling a persona.",
+            _source: "ema/ema_backend/db/models/personas_model.py:672-756",
+            _last_synced: "2026-01-26",
+            enabling_constraints: WORKFLOW_ENABLING_CONSTRAINTS,
+            minimum_viable_workflows: MINIMUM_VIABLE_WORKFLOWS,
+        }, null, 2),
+    },
+    {
+        uri: "ema://rules/workflow-constraints-summary",
+        name: "rules/workflow-constraints-summary",
+        description: "Workflow constraints summary: checklist of requirements for enabling a persona",
+        mimeType: "text/markdown",
+        generate: async () => {
+            let md = "# Workflow Enabling Constraints\n\n";
+            md += "> These constraints must be satisfied for a persona to be activated.\n\n";
+            md += "> Source: ema_backend/db/models/personas_model.py (synced 2026-01-26)\n\n";
+            md += "## Required Checks\n\n";
+            md += "| # | Constraint | Error State | Fix |\n";
+            md += "|---|------------|-------------|-----|\n";
+            for (const c of WORKFLOW_ENABLING_CONSTRAINTS) {
+                const critical = c.critical ? "**" : "";
+                md += `| ${c.id} | ${critical}${c.name}${critical} | \`${c.errorState}\` | ${c.fix} |\n`;
+            }
+            md += "\n## Minimum Viable Workflows by Type\n\n";
+            for (const [type, mvw] of Object.entries(MINIMUM_VIABLE_WORKFLOWS)) {
+                md += `### ${type}\n\n`;
+                md += `**Structure**: \`${mvw.exampleStructure}\`\n\n`;
+                md += `- Required nodes: ${mvw.requiredNodes.map(n => `\`${n}\``).join(", ")}\n`;
+                md += `- Required outputs: ${mvw.requiredOutputs.map(o => `\`${o}\``).join(", ")}\n`;
+                if (mvw.requiredWidgets) {
+                    md += `- Required widgets: ${mvw.requiredWidgets.map(w => `\`${w}\``).join(", ")}\n`;
+                }
+                if (mvw.notes) {
+                    md += `- Notes: ${mvw.notes}\n`;
+                }
+                md += "\n";
+            }
+            md += "## Critical Rule: WORKFLOW_OUTPUT\n\n";
+            md += "**Every workflow must have a `results.WORKFLOW_OUTPUT` that maps to an action output.**\n\n";
+            md += "```json\n";
+            md += '{\n  "results": {\n    "WORKFLOW_OUTPUT": {\n      "actionName": "respond_node",\n      "outputName": "response_with_sources"\n    }\n  }\n}\n';
+            md += "```\n";
+            return md;
+        },
+    },
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Workflow Requirements & Guidance
+    // NOT hardcoded templates - provide requirements and let LLM generate
+    // ─────────────────────────────────────────────────────────────────────────────
+    {
+        uri: "ema://templates/voice-ai/requirements",
+        name: "templates/voice-ai/requirements",
+        description: "Voice AI workflow requirements and guidance. Use workflow(mode='get') for schema, then generate workflow_def.",
+        mimeType: "application/json",
+        generate: async () => {
+            return JSON.stringify({
+                _note: "Requirements and guidance for Voice AI workflows. LLM generates workflow_def based on these.",
+                _usage: "1) workflow(mode='get', persona_id='...') for schema, 2) Generate workflow_def, 3) workflow(mode='deploy', ...)",
+                hard_requirements: {
+                    workflow_output: {
+                        rule: "MUST have results.WORKFLOW_OUTPUT mapped to final action output",
+                        example: '{ "results": { "WORKFLOW_OUTPUT": { "actionName": "respond", "outputName": "response" } } }',
+                    },
+                    workflow_name: {
+                        rule: "workflowName MUST be ['ema', 'personas', '<actual_persona_id>']",
+                    },
+                    trigger: {
+                        rule: "Voice AI uses chat_trigger (type CHAT)",
+                        namespace: ["triggers", "emainternal"],
+                    },
+                    response: {
+                        rule: "Must produce a response output that wires to WORKFLOW_OUTPUT",
+                    },
+                },
+                required_widgets: [
+                    { name: "conversationSettings", type: 39, purpose: "Voice identity, welcome message, instructions" },
+                    { name: "voiceSettings", type: 40, purpose: "Language, voice model" },
+                    { name: "callSettings", type: 41, purpose: "Call forwarding, spam prevention" },
+                    { name: "vadSettings", type: 42, purpose: "Voice activity detection, timeouts" },
+                ],
+                common_patterns: {
+                    simple_qa: "chat_trigger → search → respond_for_external_actions → 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)",
+                    "Consider general_hitl before actions with side effects",
+                ],
+                _next_step: "Call workflow(mode='get', persona_id='...') to get full schema, then generate workflow_def",
+            }, null, 2);
+        },
+    },
+    {
+        uri: "ema://templates/voice-ai/config",
+        name: "templates/voice-ai/config",
+        description: "Voice AI configuration template (proto_config widgets). Customize values for your use case.",
+        mimeType: "application/json",
+        generate: async () => {
+            const config = {
+                _note: "Voice AI configuration template. Customize values for your use case.",
+                _usage: "persona(method='update', id='<ID>', config={widgets: [<these widgets with your values>]})",
+                widgets: [
+                    {
+                        name: "conversationSettings",
+                        type: 39,
+                        conversationSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.conversationSettings,
+                        },
+                    },
+                    {
+                        name: "voiceSettings",
+                        type: 40,
+                        voiceSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.voiceSettings,
+                        },
+                    },
+                    {
+                        name: "callSettings",
+                        type: 41,
+                        callSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.callSettings,
+                        },
+                    },
+                    {
+                        name: "vadSettings",
+                        type: 42,
+                        vadSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.vadSettings,
+                        },
+                    },
+                ],
+                field_docs: VOICE_TEMPLATE_FIELD_DOCS,
+            };
+            return JSON.stringify(config, null, 2);
+        },
+    },
+    {
+        uri: "ema://templates/voice-ai/guide",
+        name: "templates/voice-ai/guide",
+        description: "Voice AI creation guide with requirements and step-by-step process",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Voice AI Creation Guide
+
+## Process (Follow This Order)
+
+### 1. Create Persona
+\`\`\`
+persona(method="create", name="Your Voice AI", type="voice")
+\`\`\`
+
+### 2. Get Workflow Schema
+\`\`\`
+workflow(mode="get", persona_id="<ID>")
+\`\`\`
+This returns:
+- Current workflow (if any)
+- Deprecation warnings (fix these first!)
+- Generation schema (agents, constraints)
+- Requirements and guidance
+
+### 3. Generate Workflow
+Using the schema, generate a workflow_def that:
+- Has WORKFLOW_OUTPUT in results
+- Uses non-deprecated actions
+- Follows the flow pattern: trigger → processing → response → OUTPUT
+
+### 4. Deploy Workflow
+\`\`\`
+workflow(mode="deploy", persona_id="<ID>", workflow_def={...}, preview=true)
+\`\`\`
+Always preview first!
+
+### 5. Configure Settings
+\`\`\`
+persona(method="update", id="<ID>", config={widgets: [...]})
+\`\`\`
+
+### 6. Upload Knowledge
+\`\`\`
+persona(id="<ID>", data={method:"upload", path:"your-data.txt"})
+\`\`\`
+
+## Hard Requirements
+
+| Requirement | Why |
+|-------------|-----|
+| WORKFLOW_OUTPUT | Persona cannot be activated without it |
+| workflowName format | API rejects invalid namespaces |
+| Non-deprecated actions | Deprecated actions may fail |
+
+## Check for Deprecated Actions
+
+\`workflow(mode="get")\` returns \`deprecation_warnings\` if any actions are deprecated.
+**Fix these BEFORE deploying.**
+
+## Common Deprecated Actions
+
+| Deprecated | Use Instead |
+|------------|-------------|
+| search/v0 | search/v2 (requires datastore_configs) |
+| respond_with_sources | respond_for_external_actions |
+| call_llm/v0 | call_llm/v2 |
+
+## Anti-Patterns
+
+❌ Cloning random existing persona
+❌ Skipping workflow_def
+❌ Using deprecated actions
+❌ Deploying without preview
+
+${VOICE_TEMPLATE_FIELD_DOCS}
+`;
+        },
+    },
     // Persona Templates - Dynamic from API with fallback
     {
         uri: "ema://catalog/templates",
@@ -798,8 +1130,8 @@ To read a resource, use the \`resources/read\` endpoint:
 | Get input/output compatibility rules | Resource: \`ema://rules/input-sources\` |
 | Get persona templates | Resource: \`ema://catalog/persona-templates\` (API) or Tool: \`template(config="voice")\` |
 | Query live persona data | Tool: \`persona\` |
-| Generate a workflow | Tool: \`workflow\` |
-| Analyze an existing workflow | Tool: \`workflow(mode="analyze")\` |
+| Get workflow data | Tool: \`workflow(mode="get")\` |
+| Deploy workflow | Tool: \`workflow(mode="deploy")\` |
 `;
         return {
             uri: "ema://index/all-resources",