@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

package/dist/mcp/resources.js

@@ -4,10 +4,13 @@
  * Provides static and file-backed resources for the Ema MCP Server.
  *
  * Resources are the canonical source of truth for:
- * - Templates: Persona configuration templates (voice, chat, dashboard)
- * - Agent Catalog: Dynamic list of available workflow agents
+ * - Agent Catalog: Dynamic list of available workflow agents + API templates
  * - Validation Rules: Input/output compatibility rules
  * - Documentation: User guides and references
+ * - Schemas: Action schemas and type definitions
+ *
+ * Note: File-backed templates (ema://templates/*) were removed.
+ * Use API templates via ema://catalog/persona-templates or template() tool.
  *
  * Why resources vs tools:
  * - Resources: Static/reference content the AI assistant reads to understand context
@@ -27,11 +30,12 @@ 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 { 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
 // ─────────────────────────────────────────────────────────────────────────────
@@ -97,7 +101,7 @@ function hasPathTraversal(uriPath) {
 const RESOURCE_MAP = {
     // Core Documentation (files that exist in this repo)
     "ema://docs/getting-started": {
-        path: "resources/docs/getting-started.md",
+        path: "docs/mcp-tools-guide.md",
         description: "Quick start guide: first steps, key concepts, essential rules, common operations",
         mimeType: "text/markdown",
     },
@@ -116,42 +120,10 @@ const RESOURCE_MAP = {
         description: "MCP tools usage guide: tool categories, best practices, example call sequences, workflow review patterns",
         mimeType: "text/markdown",
     },
-    // Templates - Persona configuration templates
-    "ema://templates/voice-ai/config": {
-        path: "resources/templates/voice-ai/persona-config.json",
-        description: "Voice AI persona configuration template: voiceSettings, conversationSettings, vadSettings, dataProtection",
-        mimeType: "application/json",
-    },
-    "ema://templates/voice-ai/workflow-prompt": {
-        path: "resources/templates/voice-ai/workflow-prompt.md",
-        description: "Voice AI Auto Builder prompt template with node definitions, connections, and validation assertions",
-        mimeType: "text/markdown",
-    },
-    "ema://templates/voice-ai/readme": {
-        path: "resources/templates/voice-ai/README.md",
-        description: "Voice AI deployment guide: setup steps, testing checklist, maintenance procedures",
-        mimeType: "text/markdown",
-    },
-    "ema://templates/chat-ai/config": {
-        path: "resources/templates/chat-ai/persona-config.json",
-        description: "Chat AI persona configuration template: chatbotSdkConfig, feedbackMessage, fileUpload settings",
-        mimeType: "application/json",
-    },
-    "ema://templates/chat-ai/readme": {
-        path: "resources/templates/chat-ai/README.md",
-        description: "Chat AI deployment guide: workflow generation, widget configuration, knowledge base setup",
-        mimeType: "text/markdown",
-    },
-    "ema://templates/dashboard-ai/config": {
-        path: "resources/templates/dashboard-ai/persona-config.json",
-        description: "Dashboard AI persona configuration template: inputSchema, batchSettings, timeout configuration",
-        mimeType: "application/json",
-    },
-    "ema://templates/dashboard-ai/readme": {
-        path: "resources/templates/dashboard-ai/README.md",
-        description: "Dashboard AI deployment guide: batch processing setup, input configuration",
-        mimeType: "text/markdown",
-    },
+    // Templates - REMOVED (file-backed templates removed in favor of API + generated fallbacks)
+    // Use: client.getPersonaTemplates() for live API templates
+    // Use: getTemplateFallback("voice") from sdk/generated/template-fallbacks.ts for offline fallbacks
+    // See: ema://catalog/persona-templates for dynamic API-backed template listing
     // DEPRECATED: Use ema://docs/usage-guide (dynamic) instead
     // This static resource is kept for backwards compatibility but now generates from guidance module
 };
@@ -236,7 +208,330 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async () => JSON.stringify(OPTIMIZATION_RULES, null, 2),
     },
-    // Persona Templates - Dynamic from API
+    // 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",
         name: "catalog/templates",
@@ -244,7 +539,15 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async (ctx) => {
             const templates = await getDynamicPersonaTemplates({ env: ctx.env });
-            return JSON.stringify(templates.map(templateDtoToResource), null, 2);
+            if (templates.length > 0) {
+                return JSON.stringify(templates.map(templateDtoToResource), null, 2);
+            }
+            // Fallback when API unavailable - provide guidance
+            return JSON.stringify({
+                _note: "API templates unavailable. Use catalog(method='list', type='templates') tool which connects to API directly, or use template(config='voice|chat|dashboard') for config fallbacks.",
+                fallback_types: ["voice", "chat", "dashboard"],
+                how_to_get: "catalog(method='list', type='templates') or template(config='voice')",
+            }, null, 2);
         },
     },
     {
@@ -255,7 +558,28 @@ const DYNAMIC_RESOURCES = [
         generate: async (ctx) => {
             const templates = await getDynamicPersonaTemplates({ env: ctx.env });
             if (templates.length === 0) {
-                return "# Persona Templates\n\n> No templates available from API. Check configuration or use file-backed templates at `ema://templates/*`.\n";
+                return `# Persona Templates
+
+> API templates not available. Use one of these alternatives:
+
+## Option 1: Use the catalog tool directly
+\`\`\`
+catalog(method="list", type="templates")
+\`\`\`
+This connects to the API and may have different credentials.
+
+## Option 2: Use config fallbacks
+\`\`\`
+template(config="voice")   // Voice AI config template
+template(config="chat")    // Chat AI config template
+template(config="dashboard") // Dashboard AI config template
+\`\`\`
+
+## Option 3: Create from scratch
+\`\`\`
+persona(method="create", name="My AI", type="voice|chat|dashboard")
+\`\`\`
+`;
             }
             const byCategory = new Map();
             for (const t of templates) {
@@ -727,10 +1051,11 @@ export class ResourceRegistry {
     buildResourceIndex() {
         const resources = this.list().filter((r) => r.uri !== "ema://index/all-resources");
         // Group resources by category
+        // Note: ema://templates/* file-backed resources removed - use API templates or generated fallbacks
         const docs = resources.filter((r) => r.uri.startsWith("ema://docs/"));
-        const templates = resources.filter((r) => r.uri.startsWith("ema://templates/"));
         const catalog = resources.filter((r) => r.uri.startsWith("ema://catalog/"));
         const rules = resources.filter((r) => r.uri.startsWith("ema://rules/"));
+        const schemas = resources.filter((r) => r.uri.startsWith("ema://schema/"));
         const markdown = `# Ema MCP Resources Index
 
 > Available resources exposed by the Ema MCP Server
@@ -742,9 +1067,9 @@ export class ResourceRegistry {
 | Category | Count | Description |
 |----------|-------|-------------|
 | Documentation | ${docs.length} | User guides, README, tool references |
-| Templates | ${templates.length} | Persona configuration templates (voice/chat/dashboard) |
-| Catalog | ${catalog.length} | Agent catalog, workflow patterns, widgets |
+| Catalog | ${catalog.length} | Agent catalog, workflow patterns, templates |
 | Rules | ${rules.length} | Validation rules, anti-patterns, optimizations |
+| Schemas | ${schemas.length} | Action schemas, type definitions |
 
 ## Documentation (${docs.length})
 
@@ -752,14 +1077,6 @@ export class ResourceRegistry {
 |-----|-------------|
 ${docs.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
 
-## Templates (${templates.length})
-
-> Use templates as starting points for new AI Employees
-
-| URI | Description |
-|-----|-------------|
-${templates.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
-
 ## Catalog (${catalog.length})
 
 > Dynamic catalogs generated from SDK knowledge
@@ -776,6 +1093,14 @@ ${catalog.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
 |-----|-------------|
 ${rules.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
 
+## Schemas (${schemas.length})
+
+> Action schemas and type definitions
+
+| URI | Description |
+|-----|-------------|
+${schemas.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
+
 ## Usage
 
 To read a resource, use the \`resources/read\` endpoint:
@@ -795,10 +1120,10 @@ To read a resource, use the \`resources/read\` endpoint:
 |------|-----|
 | Get agent definitions | Resource: \`ema://catalog/agents\` |
 | Get input/output compatibility rules | Resource: \`ema://rules/input-sources\` |
-| Get persona template | Resource: \`ema://templates/voice-ai/config\` |
+| 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",