@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

package/dist/mcp/handlers/feedback/store.js

@@ -0,0 +1,262 @@
+/**
+ * Feedback Store - JSONL file-based storage for feedback and telemetry
+ *
+ * Provides append-only JSONL storage with rotation to prevent unbounded growth.
+ * Data is stored in `.feedback/` directory relative to the toolkit root.
+ *
+ * Two files:
+ * - feedback.jsonl  - Explicit agent feedback (gaps, confusion, suggestions)
+ * - telemetry.jsonl - Passive telemetry (tool calls, resource fetches, errors)
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getToolkitRoot } from "../../../sdk/paths.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const FEEDBACK_DIR = ".feedback";
+const FEEDBACK_FILE = "feedback.jsonl";
+const TELEMETRY_FILE = "telemetry.jsonl";
+const MAX_TELEMETRY_ENTRIES = 1000;
+const MAX_FEEDBACK_ENTRIES = 500;
+// ─────────────────────────────────────────────────────────────────────────────
+// Store
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Get the feedback directory path, creating it if necessary.
+ */
+async function ensureFeedbackDir(rootOverride) {
+    const root = rootOverride ?? getToolkitRoot();
+    const dir = join(root, FEEDBACK_DIR);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Append a single JSON line to a JSONL file.
+ */
+async function appendJsonl(filePath, entry) {
+    const line = JSON.stringify(entry) + "\n";
+    await fs.appendFile(filePath, line, "utf-8");
+}
+/**
+ * Read all entries from a JSONL file.
+ * Returns empty array if file doesn't exist.
+ */
+async function readJsonl(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        return content
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                // Skip corrupted lines (e.g., from crash mid-write)
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return [];
+        }
+        throw err;
+    }
+}
+/**
+ * Rotate a JSONL file by keeping only the last N entries.
+ */
+async function rotateJsonl(filePath, maxEntries) {
+    const entries = await readJsonl(filePath);
+    if (entries.length <= maxEntries)
+        return;
+    const kept = entries.slice(entries.length - maxEntries);
+    const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    await fs.writeFile(filePath, content, "utf-8");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Submit a feedback entry from an agent.
+ */
+export async function submitFeedback(entry, rootOverride) {
+    const dir = await ensureFeedbackDir(rootOverride);
+    const filePath = join(dir, FEEDBACK_FILE);
+    const full = {
+        id: randomUUID(),
+        ts: new Date().toISOString(),
+        ...entry,
+    };
+    await appendJsonl(filePath, full);
+    // Log to stderr for visibility (stdout is the MCP stdio transport - never write there)
+    console.error(`[FEEDBACK] ${full.category}: ${full.message}`);
+    return full;
+}
+/**
+ * Record a telemetry event (passive, fire-and-forget).
+ */
+export async function recordTelemetry(entry, rootOverride) {
+    try {
+        const dir = await ensureFeedbackDir(rootOverride);
+        const filePath = join(dir, TELEMETRY_FILE);
+        const full = {
+            ts: new Date().toISOString(),
+            ...entry,
+        };
+        await appendJsonl(filePath, full);
+        // Rotate periodically (check every 100 writes based on simple modulo of time)
+        // We use a lightweight check: rotate if file > MAX * 1.5 entries
+        const now = Date.now();
+        if (now % 100 < 5) {
+            await rotateJsonl(filePath, MAX_TELEMETRY_ENTRIES);
+        }
+    }
+    catch {
+        // Telemetry is fire-and-forget; never block tool execution
+    }
+}
+/**
+ * List recent feedback entries.
+ */
+export async function listFeedback(options, rootOverride) {
+    const dir = await ensureFeedbackDir(rootOverride);
+    const filePath = join(dir, FEEDBACK_FILE);
+    let entries = await readJsonl(filePath);
+    if (options?.category) {
+        entries = entries.filter((e) => e.category === options.category);
+    }
+    const limit = options?.limit ?? 50;
+    return entries.slice(-limit);
+}
+/**
+ * List recent telemetry entries.
+ */
+export async function listTelemetry(options, rootOverride) {
+    const dir = await ensureFeedbackDir(rootOverride);
+    const filePath = join(dir, TELEMETRY_FILE);
+    let entries = await readJsonl(filePath);
+    if (options?.type) {
+        entries = entries.filter((e) => e.type === options.type);
+    }
+    const limit = options?.limit ?? 100;
+    return entries.slice(-limit);
+}
+/**
+ * Analyze feedback and telemetry to produce actionable insights.
+ */
+export async function analyzeFeedback(rootOverride) {
+    const dir = await ensureFeedbackDir(rootOverride);
+    const feedback = await readJsonl(join(dir, FEEDBACK_FILE));
+    const telemetry = await readJsonl(join(dir, TELEMETRY_FILE));
+    // Category breakdown
+    const categoryBreakdown = {};
+    for (const entry of feedback) {
+        categoryBreakdown[entry.category] = (categoryBreakdown[entry.category] ?? 0) + 1;
+    }
+    // Hot spots - which tools/operations have the most issues
+    const issuesByTool = {};
+    const issuesByOperation = {};
+    const negativeFeedback = feedback.filter((e) => e.category !== "success");
+    for (const entry of negativeFeedback) {
+        if (entry.tool) {
+            issuesByTool[entry.tool] = (issuesByTool[entry.tool] ?? 0) + 1;
+        }
+        if (entry.operation) {
+            issuesByOperation[entry.operation] = (issuesByOperation[entry.operation] ?? 0) + 1;
+        }
+    }
+    // Tool usage from telemetry
+    const toolUsage = {};
+    for (const entry of telemetry.filter((t) => t.type === "tool_call")) {
+        const key = entry.tool ?? "unknown";
+        if (!toolUsage[key]) {
+            toolUsage[key] = { total: 0, errors: 0 };
+        }
+        toolUsage[key].total++;
+        if (!entry.ok) {
+            toolUsage[key].errors++;
+        }
+    }
+    // Resource usage from telemetry
+    const resourceUsage = {};
+    for (const entry of telemetry.filter((t) => t.type === "resource_fetch")) {
+        const uri = entry.resource_uri ?? "unknown";
+        resourceUsage[uri] = (resourceUsage[uri] ?? 0) + 1;
+    }
+    // Error patterns
+    const errorMessages = {};
+    for (const entry of telemetry.filter((t) => t.type === "error" && t.error_message)) {
+        const msg = entry.error_message;
+        // Normalize error messages by truncating at 100 chars
+        const normalized = msg.length > 100 ? msg.slice(0, 100) + "..." : msg;
+        errorMessages[normalized] = (errorMessages[normalized] ?? 0) + 1;
+    }
+    // High-severity items
+    const highSeverity = feedback.filter((e) => e.severity === "high");
+    // Actionable items
+    const actionableItems = [];
+    // Tools with high error rates
+    for (const [tool, usage] of Object.entries(toolUsage)) {
+        const errorRate = usage.errors / usage.total;
+        if (errorRate > 0.3 && usage.total >= 5) {
+            actionableItems.push(`Tool "${tool}" has ${Math.round(errorRate * 100)}% error rate (${usage.errors}/${usage.total}) - investigate error handling and documentation`);
+        }
+    }
+    // Gaps are high-priority feedback
+    const gaps = feedback.filter((e) => e.category === "gap");
+    for (const gap of gaps) {
+        actionableItems.push(`Documentation gap: ${gap.message}${gap.tool ? ` (tool: ${gap.tool})` : ""}`);
+    }
+    // Confusion items suggest unclear docs
+    const confusions = feedback.filter((e) => e.category === "confusion");
+    for (const confusion of confusions) {
+        actionableItems.push(`Unclear guidance: ${confusion.message}${confusion.tool ? ` (tool: ${confusion.tool})` : ""}`);
+    }
+    return {
+        summary: {
+            total_feedback: feedback.length,
+            total_telemetry: telemetry.length,
+            feedback_period: feedback.length > 0
+                ? { from: feedback[0].ts, to: feedback[feedback.length - 1].ts }
+                : null,
+            telemetry_period: telemetry.length > 0
+                ? { from: telemetry[0].ts, to: telemetry[telemetry.length - 1].ts }
+                : null,
+        },
+        category_breakdown: categoryBreakdown,
+        hot_spots: {
+            by_tool: sortDescending(issuesByTool),
+            by_operation: sortDescending(issuesByOperation),
+        },
+        tool_usage: toolUsage,
+        resource_usage: sortDescending(resourceUsage),
+        error_patterns: sortDescending(errorMessages),
+        high_severity: highSeverity,
+        actionable_items: actionableItems,
+    };
+}
+/**
+ * Rotate both feedback and telemetry files to prevent unbounded growth.
+ */
+export async function rotateLogs(rootOverride) {
+    const dir = await ensureFeedbackDir(rootOverride);
+    await rotateJsonl(join(dir, FEEDBACK_FILE), MAX_FEEDBACK_ENTRIES);
+    await rotateJsonl(join(dir, TELEMETRY_FILE), MAX_TELEMETRY_ENTRIES);
+    const feedbackEntries = await readJsonl(join(dir, FEEDBACK_FILE));
+    const telemetryEntries = await readJsonl(join(dir, TELEMETRY_FILE));
+    return {
+        feedback_kept: feedbackEntries.length,
+        telemetry_kept: telemetryEntries.length,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function sortDescending(record) {
+    return Object.fromEntries(Object.entries(record).sort((a, b) => b[1] - a[1]));
+}

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

@@ -1,9 +1,9 @@
 /**
- * Persona Handler - Dispatch Table Pattern
+ * Persona Handler - Dispatch Table + Top-Level Router
  *
  * This module exports persona mode handlers using a dispatch table
- * instead of a giant switch statement. Each mode is in its own file
- * for better testability and maintainability.
+ * and provides the top-level `handlePersona` function that was previously
+ * (previously in the now-deleted handlers-consolidated.ts).
  *
  * Persona modes:
  * - get: Fetch single persona (LLM then analyzes the data)
@@ -13,7 +13,7 @@
  * - update: Update persona config
  * - delete: Delete persona (with confirmation)
  * - create/clone: Create new persona from template or clone existing
- * - intent: Direct Intent Architect invocation for qualification
+ * - schema: Get persona input schema (dashboard columns, types)
  *
  * REMOVED (LLM does these):
  * - analyze: LLM analyzes data from 'get'
@@ -23,6 +23,10 @@
  * - snapshot/version_create, history/version_list, version_get
  * - version_compare, restore/version_restore, version_policy
  */
+import { resolvePersona } from "../utils.js";
+import { checkDeprecatedParams, addDeprecationWarnings } from "../deprecation.js";
+import { handleData } from "../data/index.js";
+import { handleWorkflow } from "../workflow/index.js";
 // Import mode handlers
 import { handleGet } from "./get.js";
 import { handleList } from "./list.js";
@@ -31,7 +35,7 @@ import { handleSanitize } from "./sanitize.js";
 import { handleUpdate } from "./update.js";
 import { handleDelete } from "./delete.js";
 import { handleCreate } from "./create.js";
-import { handleIntent } from "./intent.js";
+import { handleSchema } from "./schema.js";
 /**
  * Dispatch table for persona modes
  *
@@ -48,7 +52,7 @@ export const PERSONA_MODE_HANDLERS = {
     delete: handleDelete,
     create: handleCreate,
     clone: handleCreate, // Clone uses same handler as create
-    intent: handleIntent,
+    schema: handleSchema,
 };
 /**
  * Check if a mode has been extracted to this module
@@ -70,7 +74,232 @@ export { handleSanitize } from "./sanitize.js";
 export { handleUpdate } from "./update.js";
 export { handleDelete } from "./delete.js";
 export { handleCreate } from "./create.js";
-export { handleIntent } from "./intent.js";
-// REMOVED: handleCompare, handleAnalyze - LLM does analysis/comparison
+export { handleSchema } from "./schema.js";
 // Version management
 export { handleVersion, isVersionMode } from "./version.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// Top-level Persona Router
+// ═══════════════════════════════════════════════════════════════════════════
+import { handleVersion } from "./version.js";
+/**
+ * Top-level persona handler that routes to mode-specific handlers.
+ *
+ * Handles:
+ * - Data sub-resource routing (data={method:...})
+ * - Legacy workflow routing (optimize flag, workflow_def without update mode)
+ * - Mode resolution and dispatch
+ * - Version management modes
+ */
+export async function handlePersona(args, client, getTemplateId, createClientForEnv, versionContext) {
+    const deprecationWarnings = checkDeprecatedParams(args);
+    for (const warning of deprecationWarnings) {
+        console.warn(`[persona] Deprecation: ${warning}`);
+    }
+    const id = args.id;
+    const identifier = args.identifier;
+    const idOrName = id ?? identifier;
+    // Support both 'method' (new) and 'mode' (legacy) - method takes precedence
+    const method = args.method;
+    const mode = method ?? args.mode;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // DATA SUB-RESOURCE: Handle data={method:...} early
+    // ═══════════════════════════════════════════════════════════════════════════
+    const dataArg = args.data;
+    if (dataArg && typeof dataArg === "object") {
+        if (!idOrName) {
+            return {
+                error: "Data operations require persona id",
+                hint: "Use persona(id=\"abc\", data={method:\"list\"})",
+            };
+        }
+        const dataMethod = dataArg.method;
+        if (!dataMethod) {
+            return {
+                error: "Data operations require explicit method",
+                hint: "Use data={method:\"list|schema|upload|copy|delete|embed|search\", ...}",
+                valid_methods: ["list", "schema", "upload", "copy", "delete", "embed", "search"],
+            };
+        }
+        const methodToMode = {
+            "list": "list",
+            "schema": "schema",
+            "upload": "upload",
+            "copy": "dashboard_clone",
+            "delete": "delete",
+            "embed": "embed",
+            "search": "search",
+        };
+        const mappedMode = methodToMode[dataMethod];
+        if (!mappedMode) {
+            return {
+                error: `Unknown data method: ${dataMethod}`,
+                valid_methods: Object.keys(methodToMode),
+            };
+        }
+        const dataArgs = {
+            persona_id: idOrName,
+            mode: mappedMode,
+        };
+        if (dataArg.from)
+            dataArgs.source_persona_id = dataArg.from;
+        if (dataArg.sanitize !== undefined)
+            dataArgs.sanitize = dataArg.sanitize;
+        if (dataArg.path)
+            dataArgs.file_path = dataArg.path;
+        if (dataArg.content)
+            dataArgs.content = dataArg.content;
+        if (dataArg.file_id)
+            dataArgs.file_id = dataArg.file_id;
+        else if (dataArg.id)
+            dataArgs.file_id = dataArg.id;
+        if (dataArg.enabled !== undefined)
+            dataArgs.embed = dataArg.enabled;
+        if (dataArg.query)
+            dataArgs.query = dataArg.query;
+        const readFile = async (path) => {
+            const fs = await import("fs/promises");
+            return fs.readFile(path);
+        };
+        return handleData(dataArgs, client, readFile);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ROUTING: Persona operations
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LLM-DRIVEN ARCHITECTURE:
+    // - persona tool: config changes only (name, description, widgets)
+    // - workflow tool: ALL workflow changes (get → modify → deploy)
+    // mode="update" → modular handleUpdate (config changes, workflow_spec for rewire/remove only)
+    if (mode === "update" && idOrName) {
+        return getPersonaModeHandler("update")(args, client);
+    }
+    // Legacy: optimize flag routes to workflow handler
+    const optimize = args.optimize;
+    const workflowDef = args.workflow_def ?? args.workflow;
+    if (optimize || (idOrName && workflowDef && mode !== "update")) {
+        const workflowArgs = {
+            ...args,
+            persona_id: idOrName,
+        };
+        delete workflowArgs.id;
+        delete workflowArgs.identifier;
+        return handleWorkflow(workflowArgs, client, getTemplateId);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Standard persona operations (get, list, compare, version management)
+    // ═══════════════════════════════════════════════════════════════════════════
+    const fromParam = args.from;
+    const cloneFromParam = args.clone_from;
+    const templateIdParam = args.template_id;
+    const hasBase = fromParam || cloneFromParam || templateIdParam;
+    let effectiveMode = mode;
+    if (!effectiveMode) {
+        const availableMethods = ["list", "get", "create", "update", "delete", "analyze", "sanitize", "snapshot", "history", "restore", "compare"];
+        if (idOrName && args.proto_config) {
+            return {
+                error: "Explicit method required",
+                message: "You provided id and proto_config. Did you want to update this persona?",
+                suggested_method: "update",
+                hint: "Use method='update' to apply changes",
+                example: `persona(method="update", id="${idOrName}", config={...})`,
+            };
+        }
+        else if (idOrName) {
+            return {
+                error: "Explicit method required",
+                message: "You provided a persona id/name. What operation would you like to perform?",
+                valid_methods: ["get", "update", "delete", "sanitize", "snapshot", "history", "restore"],
+                hint: "LLM does analysis/comparison. Use method='get' to fetch data, then reason about it.",
+                example: `persona(method="get", id="${idOrName}")`,
+            };
+        }
+        else if (hasBase || (args.name && args.type)) {
+            return {
+                error: "Explicit method required",
+                message: "You provided creation parameters. Did you want to create a new persona?",
+                suggested_method: "create",
+                hint: "Use method='create'",
+                example: `persona(method="create", name="...", type="voice")`,
+            };
+        }
+        else {
+            return {
+                error: "Explicit method required",
+                message: "All persona operations require explicit method parameter",
+                valid_methods: availableMethods,
+                examples: [
+                    'persona(method="list") - list all personas',
+                    'persona(method="get", id="...") - get specific persona',
+                    'persona(method="create", name="...", type="voice") - create new',
+                    'persona(method="update", id="...", config={...}) - update config',
+                    'persona(method="delete", id="...", confirm=true) - delete',
+                ],
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Dispatch to handlers via dispatch table
+    // ─────────────────────────────────────────────────────────────────────────
+    if (hasExtractedHandler(effectiveMode)) {
+        const handler = getPersonaModeHandler(effectiveMode);
+        if (handler) {
+            let extraContext = undefined;
+            if (effectiveMode === "create" || effectiveMode === "clone") {
+                extraContext = getTemplateId;
+            }
+            else if (effectiveMode === "compare") {
+                extraContext = createClientForEnv;
+            }
+            const result = await handler(args, client, extraContext);
+            return addDeprecationWarnings(result, deprecationWarnings);
+        }
+    }
+    switch (effectiveMode) {
+        // Fallback cases for modes already in dispatch table (should not be reached)
+        case "get":
+        case "list":
+        case "templates":
+        case "sanitize":
+        case "update":
+        case "delete": {
+            return { error: `Mode "${effectiveMode}" should be handled by extracted handler` };
+        }
+        // Clone and create - handled by dispatch table
+        case "clone":
+        case "create": {
+            return { error: `Mode "${effectiveMode}" should be handled by extracted handler` };
+        }
+        // Analyze and compare - LLM does this, not MCP
+        case "analyze":
+        case "compare": {
+            return {
+                error: `Method "${effectiveMode}" removed - LLM does analysis/comparison`,
+                hint: "Use method='get' to fetch persona data, then do your own analysis/comparison.",
+                example: `persona(method="get", id="...", include_workflow=true)`,
+            };
+        }
+        // ─────────────── Version Management Modes ───────────────
+        case "snapshot":
+        case "history":
+        case "restore":
+        case "version_create":
+        case "version_list":
+        case "version_get":
+        case "version_compare":
+        case "version_restore":
+        case "version_policy": {
+            if (!idOrName) {
+                return { error: `id required for ${effectiveMode} mode` };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            return handleVersion(effectiveMode, args, client, persona, versionContext);
+        }
+        default:
+            return { error: `Unknown mode: ${effectiveMode}` };
+    }
+}

package/dist/mcp/handlers/persona/schema.js

@@ -0,0 +1,27 @@
+/**
+ * Schema Handler - Get persona input schema (dashboard columns, types)
+ */
+import { resolvePersona } from "../utils.js";
+export async function handleSchema(args, client) {
+    const id = (args.id ?? args.identifier);
+    if (!id) {
+        return { error: "id required for schema mode" };
+    }
+    const persona = await resolvePersona(client, id);
+    if (!persona) {
+        return { error: `Persona not found: ${id}` };
+    }
+    try {
+        const schema = await client.getDashboardSchema(persona.id, persona.id);
+        return {
+            mode: "schema",
+            persona_id: persona.id,
+            persona_name: persona.name,
+            schema: schema,
+            column_count: schema.columns?.length ?? 0,
+        };
+    }
+    catch (error) {
+        return { error: `Failed to get schema: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

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

@@ -4,7 +4,7 @@
  * Unified reference tool for envs, actions, templates, patterns, concepts, guidance.
  */
 import { errorResult } from "../types.js";
-import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, } from "../../knowledge.js";
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, } from "../../knowledge.js";
 /**
  * Handle reference tool requests - unified lookup for all reference data
  */
@@ -284,10 +284,12 @@ export async function handleReference(args, context) {
             note: result?.note,
         };
     }
-    // Validate prompt
+    // Validate prompt (deprecated — LLM responsibility)
     if (args.validate_prompt) {
-        const result = validateWorkflowPrompt(args.validate_prompt);
-        return result;
+        return {
+            error: "Workflow prompt validation is the LLM's responsibility. Use workflow(mode='validate') for structural validation.",
+            _deprecated: true,
+        };
     }
     // ─────────────────────────────────────────────────────────────────────────
     // type="demo_kits" or demo_kits=true - List demo kits