@ema.co/mcp-toolkit 2026.2.5 → 2026.2.13

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/workflow/index.js

@@ -5,6 +5,7 @@
  * - get: Return workflow data + schema for LLM to generate/modify
  * - deploy: Deploy LLM-generated workflow_def
  * - validate: Validate a workflow_def before deploying
+ * - optimize: Structural graph optimization
  *
  * THE LLM DOES ALL THE THINKING. MCP provides data and executes.
  *
@@ -13,7 +14,7 @@
  * - generate: Had MCP generating workflow - LLM should generate full workflow_def
  *
  * DEPRECATED (kept for backwards compat, but not exposed):
- * - analyze, optimize, compare: LLM can do this by fetching rules and comparing
+ * - analyze, compare: LLM can do this by fetching rules and comparing
  */
 import { generateSchema } from "../../domain/generation-schema.js";
 import { fingerprintPersona } from "../../../sync.js";
@@ -228,8 +229,8 @@ async function handleWorkflowGet(args, client) {
 /**
  * Main workflow handler with mode-based dispatch
  *
- * PUBLIC modes: get, deploy
- * INTERNAL modes: modify, generate, analyze, optimize, compare (called from persona tool)
+ * PUBLIC modes: get, deploy, validate, optimize
+ * INTERNAL modes: modify, generate, analyze, compare (called from persona tool)
  */
 export async function handleWorkflow(args, client, _getTemplateId) {
     const personaId = args.persona_id;
@@ -246,6 +247,9 @@ export async function handleWorkflow(args, client, _getTemplateId) {
     if (mode === "validate") {
         return handleWorkflowValidate(args, client);
     }
+    if (mode === "optimize") {
+        return handleWorkflowOptimize(args, client);
+    }
     // REMOVED: modify, generate modes violated LLM-driven architecture
     // MCP was doing LLM work (parsing operations, generating workflows)
     // Correct flow: LLM generates full workflow_def → workflow(mode="deploy")
@@ -261,14 +265,11 @@ export async function handleWorkflow(args, client, _getTemplateId) {
             _tip: "The LLM generates the full workflow_def. MCP just deploys it.",
         };
     }
-    // DEPRECATED: analyze, optimize, compare - LLM can do this directly
+    // DEPRECATED: analyze, compare - LLM can do this directly
     // Kept for backwards compat but may be removed
     if (mode === "analyze") {
         return handleWorkflowAnalyze(args, client);
     }
-    if (mode === "optimize") {
-        return handleWorkflowOptimize(args, client);
-    }
     if (mode === "compare") {
         return handleWorkflowCompare(args, client);
     }
@@ -283,16 +284,16 @@ export async function handleWorkflow(args, client, _getTemplateId) {
     // Invalid mode
     return {
         error: `Invalid or missing mode: ${mode}`,
-        public_modes: ["get", "deploy", "validate"],
-        hint: "MCP provides data (get), validates (validate), and executes (deploy). LLM does all thinking.",
+        public_modes: ["get", "deploy", "validate", "optimize"],
+        hint: "MCP provides data (get), validates (validate), optimizes (optimize), and executes (deploy). LLM does all thinking.",
     };
 }
 /**
  * Check if a workflow mode has been extracted
  */
 export function hasExtractedWorkflowHandler(mode) {
-    // PUBLIC: get, deploy, validate
-    // DEPRECATED (kept for compat): analyze, optimize, compare
+    // PUBLIC: get, deploy, validate, optimize
+    // DEPRECATED (kept for compat): analyze, compare
     // REMOVED: modify, extend, generate (violated LLM-driven architecture)
     const extractedModes = ["get", "deploy", "validate", "analyze", "optimize", "compare"];
     return extractedModes.includes(mode);

package/dist/mcp/handlers/workflow/optimize.js

@@ -1,50 +1,90 @@
 /**
  * Workflow Optimize Handler
  *
- * DEPRECATED: This handler returned pre-computed fixes which violates
- * the "MCP = data, LLM = logic" principle.
- *
- * The LLM should:
- * 1. Get workflow with workflow(mode="get")
- * 2. Fetch rules from ema://rules/anti-patterns
- * 3. Apply rules and propose fixes
- * 4. Deploy via workflow(mode="deploy")
+ * Structural graph optimization using the workflow-graph-optimizer.
+ * Accepts persona_id (fetches workflow) OR workflow_def (direct optimization).
+ * Returns optimized workflow_def + report. Does NOT auto-deploy.
  */
+import { optimizeWorkflow } from "../../domain/workflow-graph-optimizer.js";
 /**
- * Handle workflow optimize mode
+ * Handle workflow(mode="optimize") - structural graph optimization
  *
- * NOW DEPRECATED - Returns guidance for LLM to do the analysis.
+ * Follows the same parameter extraction pattern as handleWorkflowValidate:
+ * - persona_id → fetch workflow from persona
+ * - workflow_def → optimize directly
+ * - auto_apply (default true) → apply safe auto-transforms
+ * - max_passes (default 5) → convergence limit
  */
 export async function handleWorkflowOptimize(args, client) {
     const personaId = args.persona_id;
-    if (!personaId) {
-        return { error: "persona_id required for optimize mode" };
+    const workflowDef = args.workflow_def;
+    const autoApply = args.auto_apply ?? true;
+    const maxPasses = args.max_passes ?? 5;
+    // Get workflow to optimize
+    let workflowToOptimize = null;
+    let personaName;
+    if (workflowDef) {
+        // Use provided workflow_def directly
+        workflowToOptimize = workflowDef;
     }
-    const persona = await client.getPersonaById(personaId);
-    if (!persona) {
-        return { error: `Persona not found: ${personaId}` };
+    else if (personaId) {
+        // Get workflow from persona
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        personaName = persona.name;
+        const personaWorkflowDef = persona.workflow_def;
+        if (!personaWorkflowDef) {
+            return {
+                error: `Persona "${persona.name}" has no workflow to optimize`,
+                _tip: "Deploy a workflow first, then optimize it",
+            };
+        }
+        workflowToOptimize = personaWorkflowDef;
     }
-    const existingWorkflow = persona.workflow_def;
-    if (!existingWorkflow) {
+    else {
         return {
-            error: `Persona "${persona.name}" has no workflow to optimize`,
-            hint: "Use mode='generate' to create a workflow first",
+            error: "Either persona_id or workflow_def required for optimize mode",
         };
     }
-    // Return the workflow and guidance for LLM to do the analysis
-    return {
+    if (!workflowToOptimize) {
+        return { error: "Could not extract workflow for optimization" };
+    }
+    // Run the graph optimizer
+    const result = optimizeWorkflow(workflowToOptimize, {
+        autoApply,
+        maxPasses,
+    });
+    // Format response
+    const response = {
         mode: "optimize",
-        status: "DEPRECATED - Use LLM analysis instead",
-        persona_id: personaId,
-        persona_name: persona.name,
-        // Return the workflow for LLM to analyze
-        workflow_def: existingWorkflow,
-        _next_steps: [
-            "1. Use workflow(mode='get') to get workflow data",
-            "2. Fetch ema://rules/anti-patterns",
-            "3. Apply rules to find issues (LLM does this, not MCP)",
-            "4. Modify workflow based on analysis",
-            "5. Deploy via workflow(mode='deploy', workflow_def={...})",
-        ],
+        ...(personaId && { persona_id: personaId }),
+        ...(personaName && { persona_name: personaName }),
+        // Core result
+        modified: result.modified,
+        workflow_def: result.workflowDef,
+        // What was done
+        applied_transforms: result.appliedTransforms.length > 0
+            ? result.appliedTransforms
+            : undefined,
+        // What the LLM should review
+        advisories: result.advisories.length > 0
+            ? result.advisories
+            : undefined,
+        // Before/after metrics
+        metrics: result.metrics,
+        // Post-optimization validation
+        validation: result.validation,
+        // Guidance
+        _tip: result.modified
+            ? "Optimization applied transforms. Review the changes, then deploy with: workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={...})"
+            : result.advisories.length > 0
+                ? "No auto-transforms applied, but advisories found. Review them and modify the workflow_def manually if needed."
+                : "Workflow is already optimal. No changes needed.",
+        _next_step: result.modified
+            ? "workflow(mode='get', persona_id='...') to get fresh fingerprint, then workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={optimized_workflow_def})"
+            : undefined,
     };
+    return response;
 }