@ema.co/mcp-toolkit 0.2.0

package/dist/mcp/resources.js

@@ -0,0 +1,624 @@
+/**
+ * MCP Resources Registry
+ *
+ * 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
+ * - Validation Rules: Input/output compatibility rules
+ * - Documentation: User guides and references
+ *
+ * Why resources vs tools:
+ * - Resources: Static/reference content the AI assistant reads to understand context
+ * - Tools: Actions that query, compute, or mutate data
+ *
+ * Security:
+ * - Only allowlisted paths can be read
+ * - Path traversal is blocked
+ * - Secret patterns are detected and blocked
+ * - Only ema:// URI scheme is supported
+ */
+import * as fs from "fs";
+import * as path from "path";
+// Import knowledge catalogs for dynamic resources
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG } from "../sdk/knowledge.js";
+import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "../sdk/validation-rules.js";
+import { EmaClient } from "../sdk/client.js";
+import { loadConfigFromJsonEnv, loadConfigOptional, resolveBearerToken, getEnvByName, getMasterEnv, } from "../sdk/config.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Security Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+// Patterns that indicate ACTUAL secret content - never expose
+// These patterns are designed to catch real secrets while avoiding false positives
+// on documentation examples (e.g., "your-token-here", "...", etc.)
+const SECRET_PATTERNS = [
+    // Private keys - definitive indicator of secrets
+    /-----BEGIN\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----/i,
+    // AWS Access Key - specific format
+    /AKIA[0-9A-Z]{16}/i,
+    // OpenAI API Key - specific format (sk- followed by 48+ chars)
+    /sk-[a-zA-Z0-9]{48,}/i,
+    // GitHub tokens - specific formats
+    /ghp_[a-zA-Z0-9]{36}/i,
+    /gho_[a-zA-Z0-9]{36}/i,
+    // JWT tokens (3 base64 segments separated by dots, min length)
+    /eyJ[a-zA-Z0-9_-]{20,}\.eyJ[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}/,
+    // Actual Bearer tokens (not just "Bearer" keyword)
+    // Exclude placeholder patterns like "...", "your-token", etc.
+    /Bearer\s+(?!\.{3}|your|example|placeholder|<)[a-zA-Z0-9_\-.]{20,}/i,
+    // Password with actual value (not placeholders)
+    // Exclude: password: "...", password: "your-password", password: ""
+    /password\s*[:=]\s*["'](?!\.{3}|your|example|placeholder|<|$)[a-zA-Z0-9!@#$%^&*()_+\-=]{8,}["']/i,
+];
+// Files that should never be exposed
+const BLOCKED_FILES = [
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production",
+    ".env.test",
+    "secrets.yaml",
+    "secrets.json",
+    ".npmrc",
+    ".pypirc",
+    "id_rsa",
+    "id_ed25519",
+    "*.pem",
+    "*.key",
+];
+function containsSecrets(content) {
+    return SECRET_PATTERNS.some((pattern) => pattern.test(content));
+}
+function isBlockedFile(filename) {
+    const basename = path.basename(filename);
+    return BLOCKED_FILES.some((blocked) => {
+        if (blocked.startsWith("*")) {
+            return basename.endsWith(blocked.slice(1));
+        }
+        return basename === blocked;
+    });
+}
+function hasPathTraversal(uriPath) {
+    return uriPath.includes("..") || uriPath.includes("//");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Resource Registry
+// ─────────────────────────────────────────────────────────────────────────────
+// Allowlisted resource mappings: uri -> relative file path
+// Only includes files that ACTUALLY exist in this repo (not symlinked)
+// and are useful for MCP consumers
+const RESOURCE_MAP = {
+    // Core Documentation (files that exist in this repo)
+    "ema://docs/readme": {
+        path: "README.md",
+        description: "Ema Toolkit overview: MCP tools, prompts, resources, CLI usage, SDK API, configuration",
+        mimeType: "text/markdown",
+    },
+    "ema://docs/ema-user-guide": {
+        path: "docs/ema-user-guide.md",
+        description: "Ema Platform guide: concepts (AI Employees, Workflows, Agents), glossary, architecture, examples, troubleshooting",
+        mimeType: "text/markdown",
+    },
+    "ema://docs/mcp-tools-guide": {
+        path: "docs/mcp-tools-guide.md",
+        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",
+    },
+    // Cursor Rules - Generation guidance
+    "ema://rules/generation": {
+        path: ".cursor/rules/platforms/ema/generation/LOCAL-GENERATION.md",
+        description: "Local workflow generation rules: how to generate workflows without Auto Builder",
+        mimeType: "text/markdown",
+    },
+};
+const DYNAMIC_RESOURCES = [
+    // Agent Catalog - Dynamic list of all workflow agents
+    {
+        uri: "ema://catalog/agents",
+        name: "catalog/agents",
+        description: "Complete agent catalog: all available workflow agents with inputs, outputs, critical rules, and usage guidance",
+        mimeType: "application/json",
+        generate: async (ctx) => JSON.stringify(await getDynamicAgentCatalog({ env: ctx.env }), null, 2),
+    },
+    {
+        uri: "ema://catalog/agents-summary",
+        name: "catalog/agents-summary",
+        description: "Agent catalog summary: agent names, categories, and brief descriptions for quick reference",
+        mimeType: "text/markdown",
+        generate: async (ctx) => {
+            const agents = await getDynamicAgentCatalog({ env: ctx.env });
+            const byCategory = new Map();
+            for (const agent of agents) {
+                const cat = agent.category || "other";
+                if (!byCategory.has(cat))
+                    byCategory.set(cat, []);
+                byCategory.get(cat).push(agent);
+            }
+            let md = "# Ema Agent Catalog\n\n";
+            md += `> ${agents.length} agents available for workflow composition\n\n`;
+            for (const [category, agents] of byCategory) {
+                md += `## ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
+                md += "| Agent | Description | Key Inputs | Key Outputs |\n";
+                md += "|-------|-------------|------------|-------------|\n";
+                for (const agent of agents) {
+                    const inputs = agent.inputs?.slice(0, 2).map((i) => i.name).join(", ") || "-";
+                    const outputs = agent.outputs?.slice(0, 2).map((o) => o.name).join(", ") || "-";
+                    md += `| \`${agent.actionName}\` | ${agent.description?.slice(0, 60) || "-"}... | ${inputs} | ${outputs} |\n`;
+                }
+                md += "\n";
+            }
+            return md;
+        },
+    },
+    // Workflow Patterns - Common workflow templates
+    {
+        uri: "ema://catalog/patterns",
+        name: "catalog/patterns",
+        description: "Workflow patterns: common workflow structures (kb-search, intent-routing, tool-calling) with examples",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(WORKFLOW_PATTERNS, null, 2),
+    },
+    // Widget Catalog - UI configuration widgets
+    {
+        uri: "ema://catalog/widgets",
+        name: "catalog/widgets",
+        description: "Widget catalog: proto_config widget types for voice, chat, and dashboard personas",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(WIDGET_CATALOG, null, 2),
+    },
+    // Validation Rules - Input source and anti-pattern rules
+    {
+        uri: "ema://rules/input-sources",
+        name: "rules/input-sources",
+        description: "Input source validation rules: which agent inputs accept which data types (user_query vs chat_conversation)",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(INPUT_SOURCE_RULES, null, 2),
+    },
+    {
+        uri: "ema://rules/anti-patterns",
+        name: "rules/anti-patterns",
+        description: "Anti-patterns to avoid: common workflow mistakes and how to prevent them",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(ANTI_PATTERNS, null, 2),
+    },
+    {
+        uri: "ema://rules/optimizations",
+        name: "rules/optimizations",
+        description: "Optimization rules: workflow improvements for better performance and reliability",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(OPTIMIZATION_RULES, null, 2),
+    },
+    // Persona Templates - Dynamic from API
+    {
+        uri: "ema://catalog/templates",
+        name: "catalog/templates",
+        description: "Persona templates from Ema API: pre-configured AI Employee templates (chatbot_starter, voicebot, dashboard, etc.)",
+        mimeType: "application/json",
+        generate: async (ctx) => {
+            const templates = await getDynamicPersonaTemplates({ env: ctx.env });
+            return JSON.stringify(templates.map(templateDtoToResource), null, 2);
+        },
+    },
+    {
+        uri: "ema://catalog/templates-summary",
+        name: "catalog/templates-summary",
+        description: "Persona templates summary: template names, categories, and descriptions for quick reference",
+        mimeType: "text/markdown",
+        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";
+            }
+            const byCategory = new Map();
+            for (const t of templates) {
+                const cat = t.category || "GENERAL";
+                if (!byCategory.has(cat))
+                    byCategory.set(cat, []);
+                byCategory.get(cat).push(t);
+            }
+            let md = "# Persona Templates (from API)\n\n";
+            md += `> ${templates.length} templates available for creating AI Employees\n\n`;
+            for (const [category, tpls] of byCategory) {
+                md += `## ${category}\n\n`;
+                md += "| Template | Type | Description |\n";
+                md += "|----------|------|-------------|\n";
+                for (const t of tpls) {
+                    const triggerType = t.trigger_type || "-";
+                    const desc = t.description?.slice(0, 80) || "-";
+                    md += `| \`${t.name}\` | ${triggerType} | ${desc}... |\n`;
+                }
+                md += "\n";
+            }
+            return md;
+        },
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic fetching helpers (Ema API as source of truth when available)
+// ─────────────────────────────────────────────────────────────────────────────
+function loadAnyConfig() {
+    return (loadConfigFromJsonEnv() ??
+        loadConfigOptional(process.env.EMA_AGENT_SYNC_CONFIG ?? "./config.yaml"));
+}
+function getDefaultEnvNameFromConfig(cfg) {
+    const fromEnv = process.env.EMA_ENV_NAME?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const master = getMasterEnv(cfg);
+    return master?.name ?? cfg.environments[0]?.name ?? "demo";
+}
+const WK_ANY = "WELL_KNOWN_TYPE_ANY";
+function actionDtoToAgentDefinition(a) {
+    return {
+        actionName: a.name ?? a.id,
+        displayName: a.name ?? a.id,
+        category: (a.category ?? "other"),
+        description: a.description ?? "",
+        inputs: (a.inputs ?? []).map((p) => ({
+            name: p.name ?? "input",
+            type: WK_ANY,
+            required: Boolean(p.required),
+            description: p.description ?? "",
+        })),
+        outputs: (a.outputs ?? []).map((p) => ({
+            name: p.name ?? "output",
+            type: WK_ANY,
+            description: p.description ?? "",
+        })),
+        whenToUse: "",
+    };
+}
+const clientCache = new Map();
+const agentCatalogCache = new Map();
+function getClientForEnvName(envName) {
+    const cfg = loadAnyConfig();
+    if (!cfg)
+        return null;
+    const effectiveEnv = envName ?? getDefaultEnvNameFromConfig(cfg);
+    const cached = clientCache.get(effectiveEnv);
+    if (cached)
+        return cached;
+    const envCfg = getEnvByName(cfg, effectiveEnv) ?? getEnvByName(cfg, getDefaultEnvNameFromConfig(cfg));
+    if (!envCfg)
+        return null;
+    const env = {
+        name: envCfg.name,
+        baseUrl: envCfg.baseUrl,
+        bearerToken: resolveBearerToken(envCfg.bearerTokenEnv),
+    };
+    const client = new EmaClient(env);
+    clientCache.set(effectiveEnv, client);
+    return client;
+}
+async function getDynamicAgentCatalog(opts) {
+    const cacheKey = opts.env ?? "";
+    const now = Date.now();
+    const cached = agentCatalogCache.get(cacheKey);
+    if (cached && now - cached.ts < 60_000)
+        return cached.agents;
+    const client = getClientForEnvName(opts.env);
+    if (!client)
+        return AGENT_CATALOG;
+    try {
+        const actions = await client.listActions();
+        const agents = actions
+            .filter((a) => typeof a.name === "string" && a.name.trim().length > 0)
+            .map(actionDtoToAgentDefinition);
+        agentCatalogCache.set(cacheKey, { ts: now, agents });
+        return agents.length > 0 ? agents : AGENT_CATALOG;
+    }
+    catch {
+        return AGENT_CATALOG;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic Persona Templates (API-first)
+// ─────────────────────────────────────────────────────────────────────────────
+const templateCatalogCache = new Map();
+/**
+ * Fetch persona templates from API with caching.
+ * Falls back to empty array if API unavailable (file-backed templates still available via RESOURCE_MAP).
+ */
+async function getDynamicPersonaTemplates(opts) {
+    const cacheKey = opts.env ?? "";
+    const now = Date.now();
+    const cached = templateCatalogCache.get(cacheKey);
+    if (cached && now - cached.ts < 60_000)
+        return cached.templates;
+    const client = getClientForEnvName(opts.env);
+    if (!client)
+        return [];
+    try {
+        const templates = await client.getPersonaTemplates();
+        templateCatalogCache.set(cacheKey, { ts: now, templates });
+        return templates;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Convert PersonaTemplateDTO to a simplified format for MCP resources.
+ */
+function templateDtoToResource(t) {
+    return {
+        id: t.id,
+        name: t.name,
+        description: t.description,
+        category: t.category,
+        trigger_type: t.trigger_type,
+        has_project_template: t.has_project_template,
+        how_to_use: t.how_to_use,
+        value_prop: t.value_prop,
+        // Include proto_config for full template details
+        proto_config: t.proto_config,
+        // Include workflow_definition if available
+        workflow_definition: t.workflow_definition,
+    };
+}
+// Get workspace root from environment or default
+function getWorkspaceRoot() {
+    // Try EMA_WORKSPACE_ROOT first (for testing)
+    if (process.env.EMA_WORKSPACE_ROOT) {
+        return process.env.EMA_WORKSPACE_ROOT;
+    }
+    // Otherwise use current working directory
+    return process.cwd();
+}
+export class ResourceRegistry {
+    workspaceRoot;
+    constructor(workspaceRoot) {
+        this.workspaceRoot = workspaceRoot ?? getWorkspaceRoot();
+    }
+    /**
+     * List all available resources
+     */
+    list() {
+        const resources = [];
+        // Add file-backed resources
+        for (const [uri, config] of Object.entries(RESOURCE_MAP)) {
+            resources.push({
+                uri,
+                name: uri.replace("ema://", ""),
+                description: config.description,
+                mimeType: config.mimeType,
+            });
+        }
+        // Add dynamic resources
+        for (const resource of DYNAMIC_RESOURCES) {
+            resources.push({
+                uri: resource.uri,
+                name: resource.name,
+                description: resource.description,
+                mimeType: resource.mimeType,
+            });
+        }
+        // Add virtual index resource
+        resources.push({
+            uri: "ema://index/all-resources",
+            name: "index/all-resources",
+            description: "Index of all available Ema MCP resources with descriptions",
+            mimeType: "text/markdown",
+        });
+        return resources;
+    }
+    /**
+     * Read a specific resource by URI
+     */
+    async read(uri) {
+        // Validate URI scheme
+        if (!uri.startsWith("ema://")) {
+            return {
+                code: "INVALID_URI",
+                message: `Invalid URI scheme. Expected 'ema://', got '${uri.split("://")[0] ?? "unknown"}://'`,
+            };
+        }
+        const rawUriPath = uri.replace("ema://", "");
+        // Check for path traversal
+        // IMPORTANT: check the raw, non-normalized path so `..` can't be
+        // normalized away by URL parsing.
+        if (hasPathTraversal(rawUriPath)) {
+            return {
+                code: "UNAUTHORIZED",
+                message: "Path traversal detected and blocked",
+            };
+        }
+        let baseUri = uri;
+        let envFromQuery;
+        try {
+            const u = new URL(uri);
+            envFromQuery = u.searchParams.get("env") ?? undefined;
+            baseUri = `ema://${u.host}${u.pathname}`;
+        }
+        catch {
+            // ignore parse errors; treat as raw URI
+        }
+        // Handle virtual index resource
+        if (baseUri === "ema://index/all-resources") {
+            return this.buildResourceIndex();
+        }
+        // Check for dynamic resources first
+        const dynamicResource = DYNAMIC_RESOURCES.find((r) => r.uri === baseUri);
+        if (dynamicResource) {
+            return {
+                uri: baseUri,
+                mimeType: dynamicResource.mimeType,
+                text: await dynamicResource.generate({ env: envFromQuery }),
+            };
+        }
+        // Look up in file-backed allowlist
+        const resourceConfig = RESOURCE_MAP[baseUri];
+        if (!resourceConfig) {
+            return {
+                code: "NOT_FOUND",
+                message: `Resource not found: ${uri}. Use resources/list to see available resources.`,
+            };
+        }
+        // Check if file is blocked
+        if (isBlockedFile(resourceConfig.path)) {
+            return {
+                code: "UNAUTHORIZED",
+                message: "Access to this file type is not permitted",
+            };
+        }
+        // Read the file
+        const fullPath = path.resolve(this.workspaceRoot, resourceConfig.path);
+        // Verify path is still within workspace (defense in depth)
+        if (!fullPath.startsWith(this.workspaceRoot)) {
+            return {
+                code: "UNAUTHORIZED",
+                message: "Path traversal detected and blocked",
+            };
+        }
+        try {
+            const content = fs.readFileSync(fullPath, "utf-8");
+            // Check for secrets
+            if (containsSecrets(content)) {
+                return {
+                    code: "SECRET_DETECTED",
+                    message: "This resource contains sensitive data and cannot be exposed",
+                };
+            }
+            return {
+                uri: baseUri,
+                mimeType: resourceConfig.mimeType,
+                text: content,
+            };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return {
+                    code: "NOT_FOUND",
+                    message: `Resource file not found: ${resourceConfig.path}`,
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Build the virtual resource index
+     */
+    buildResourceIndex() {
+        const resources = this.list().filter((r) => r.uri !== "ema://index/all-resources");
+        // Group resources by category
+        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 markdown = `# Ema MCP Resources Index
+
+> Available resources exposed by the Ema MCP Server
+> 
+> **Use resources for reference data. Use tools for actions.**
+
+## Summary
+
+| 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 |
+| Rules | ${rules.length} | Validation rules, anti-patterns, optimizations |
+
+## Documentation (${docs.length})
+
+| URI | Description |
+|-----|-------------|
+${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
+
+| URI | Description |
+|-----|-------------|
+${catalog.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
+
+## Rules (${rules.length})
+
+> Validation and best-practice rules
+
+| URI | Description |
+|-----|-------------|
+${rules.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
+
+## Usage
+
+To read a resource, use the \`resources/read\` endpoint:
+
+\`\`\`json
+{
+  "method": "resources/read",
+  "params": {
+    "uri": "ema://catalog/agents-summary"
+  }
+}
+\`\`\`
+
+## When to Use Resources vs Tools
+
+| Need | Use |
+|------|-----|
+| 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\` |
+| Query live persona data | Tool: \`persona\` |
+| Generate a workflow | Tool: \`workflow\` |
+| Analyze an existing workflow | Tool: \`workflow(mode="analyze")\` |
+`;
+        return {
+            uri: "ema://index/all-resources",
+            mimeType: "text/markdown",
+            text: markdown,
+        };
+    }
+}
+// Helper to check if result is an error
+export function isResourceError(result) {
+    return "code" in result;
+}