@kairos-sdk/core 0.4.0 → 0.5.0

package/dist/mcp-server.js

@@ -1,16 +1,22 @@
 #!/usr/bin/env node
+import {
+  PromptBuilder,
+  inferWorkflowType
+} from "./chunk-EVOAYH2K.js";
 import {
   DEFAULT_REGISTRY,
   FileLibrary,
+  GuardError,
   N8nApiClient,
   N8nFieldStripper,
   N8nValidator,
   NodeRegistry,
   PatternAnalyzer,
-  PromptBuilder,
+  TelemetryCollector,
   TelemetryReader,
+  generateUUID,
   nullLogger
-} from "./chunk-NJ6QZBIC.js";
+} from "./chunk-KIFT5LA7.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -77,15 +83,41 @@ ${regularLines}`;
 // src/mcp-server.ts
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
+import { homedir } from "os";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 var library = new FileLibrary();
-var validator = new N8nValidator();
+var _validator = new N8nValidator();
+function getValidator() {
+  return _validator;
+}
 var nodeSyncer = new NodeSyncer();
 var lastSync = null;
+var AUTO_SYNC_TIMEOUT_MS = 5e3;
 var stripper = new N8nFieldStripper();
-var promptBuilder = new PromptBuilder();
+var promptBuilder = new PromptBuilder(getMcpPatternsPath());
+function getMcpTelemetry() {
+  const val = process.env["KAIROS_TELEMETRY"];
+  if (!val || val === "false") return null;
+  return val === "true" ? new TelemetryCollector() : new TelemetryCollector(val);
+}
+function getMcpPatternsPath() {
+  const val = process.env["KAIROS_TELEMETRY"];
+  if (val && val !== "false" && val !== "true") {
+    return join(val, "..", "patterns.json");
+  }
+  return join(homedir(), ".kairos", "patterns.json");
+}
+var mcpTelemetry = getMcpTelemetry();
+var mcpSessions = /* @__PURE__ */ new Map();
+var SESSION_TTL_MS = 60 * 60 * 1e3;
+function evictStaleSessions() {
+  const cutoff = Date.now() - SESSION_TTL_MS;
+  for (const [id, session] of mcpSessions) {
+    if (session.startTime < cutoff) mcpSessions.delete(id);
+  }
+}
 function getTelemetryReader() {
   try {
     return new TelemetryReader();
@@ -97,11 +129,23 @@ function isAllowed(action) {
   const key = `KAIROS_MCP_ALLOW_${action.toUpperCase()}`;
   return process.env[key] === "true";
 }
+function mcpText(text) {
+  return { content: [{ type: "text", text }] };
+}
+function mcpError(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function checkMcpAuth(provided) {
+  const expected = process.env["KAIROS_MCP_SECRET"];
+  if (!expected) return null;
+  if (provided === expected) return null;
+  return mcpError(JSON.stringify({ error: "Unauthorized: missing or incorrect kairos_secret" }));
+}
 function getApiClient() {
   const baseUrl = process.env["N8N_BASE_URL"];
   const apiKey = process.env["N8N_API_KEY"];
   if (!baseUrl || !apiKey) {
-    throw new Error("N8N_BASE_URL and N8N_API_KEY environment variables are required for n8n operations");
+    throw new GuardError("N8N_BASE_URL and N8N_API_KEY environment variables are required for n8n operations");
   }
   return new N8nApiClient(baseUrl, apiKey, nullLogger);
 }
@@ -115,7 +159,7 @@ async function autoSync() {
     const nodeTypes = await client.getNodeTypes();
     if (nodeTypes.length === 0) return null;
     lastSync = nodeSyncer.sync(nodeTypes);
-    validator = new N8nValidator(lastSync.registry);
+    _validator = new N8nValidator(lastSync.registry);
     return lastSync;
   } catch {
     return null;
@@ -133,103 +177,110 @@ server.tool(
     name: z.string().optional().describe("Optional workflow name override")
   },
   async ({ description, name }) => {
+    evictStaleSessions();
     const baseUrl = process.env["N8N_BASE_URL"];
     const apiKey = process.env["N8N_API_KEY"];
     if (!baseUrl || !apiKey) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required. Kairos needs to sync your n8n instance's node types to generate accurate workflows." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required. Kairos needs to sync your n8n instance's node types to generate accurate workflows." }));
     }
+    const runId = generateUUID();
+    const workflowType = inferWorkflowType(description);
+    const syncPromise = autoSync();
+    const syncTimeout = new Promise((resolve) => setTimeout(() => resolve(null), AUTO_SYNC_TIMEOUT_MS));
     await library.initialize();
-    const syncResult = await autoSync();
-    const matches = await library.search(description);
-    const telemetryReader = getTelemetryReader();
-    const failureRates = await telemetryReader?.getFailureRates() ?? [];
+    const [syncResult, matches, failureRates] = await Promise.all([
+      Promise.race([syncPromise, syncTimeout]),
+      library.search(description),
+      (async () => {
+        const reader = getTelemetryReader();
+        return reader ? reader.getFailureRates() : [];
+      })()
+    ]);
     const request = { description, ...name ? { name } : {} };
     const built = promptBuilder.build(request, matches, failureRates, syncResult?.catalogText);
+    if (mcpTelemetry) {
+      mcpSessions.set(runId, {
+        description,
+        startTime: Date.now(),
+        validateAttempts: 0,
+        warnedRules: promptBuilder.getWarnedRules(),
+        workflowType
+      });
+      await mcpTelemetry.emit("build_start", { description, model: "mcp-decomposed", dryRun: false }, runId);
+    }
     const systemText = built.system.map((block) => block.text).join("\n\n---\n\n");
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          mode: built.mode,
-          matchCount: matches.length,
-          topMatchScore: matches[0]?.score ?? null,
-          nodeCatalog: syncResult ? "synced" : "static",
-          nodeCount: syncResult?.nodeCount ?? null,
-          ...syncResult ? {} : { syncWarning: "Could not sync node types from your n8n instance. Using static fallback catalog \u2014 generated workflows may not match your exact n8n setup." },
-          systemPrompt: systemText,
-          userMessage: built.userMessage,
-          outputFormat: {
-            description: "Generate a JSON object with this exact structure. The workflow field contains the n8n workflow. credentialsNeeded lists services requiring credentials.",
-            schema: {
-              workflow: {
-                name: "string \u2014 descriptive workflow name",
-                nodes: "array \u2014 n8n node objects with id (UUID v4), type, typeVersion, name, position, parameters",
-                connections: "object \u2014 keyed by source node NAME, maps to target nodes",
-                settings: 'object \u2014 include executionOrder: "v1"'
-              },
-              credentialsNeeded: [{
-                service: 'string \u2014 e.g. "Slack"',
-                credentialType: 'string \u2014 e.g. "slackOAuth2Api"',
-                description: "string \u2014 what the user needs to set up"
-              }]
-            }
-          }
-        }, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify({
+      kairos_run_id: runId,
+      mode: built.mode,
+      matchCount: matches.length,
+      topMatchScore: matches[0]?.score ?? null,
+      nodeCatalog: syncResult ? "synced" : "static",
+      nodeCount: syncResult?.nodeCount ?? null,
+      ...syncResult ? {} : { syncWarning: "Could not sync node types from your n8n instance. Using static fallback catalog \u2014 generated workflows may not match your exact n8n setup." },
+      systemPrompt: systemText,
+      userMessage: built.userMessage,
+      outputFormat: {
+        description: "Generate a JSON object with this exact structure. The workflow field contains the n8n workflow. credentialsNeeded lists services requiring credentials.",
+        schema: {
+          workflow: {
+            name: "string \u2014 descriptive workflow name",
+            nodes: "array \u2014 n8n node objects with id (UUID v4), type, typeVersion, name, position, parameters",
+            connections: "object \u2014 keyed by source node NAME, maps to target nodes",
+            settings: 'object \u2014 include executionOrder: "v1"'
+          },
+          credentialsNeeded: [{
+            service: 'string \u2014 e.g. "Slack"',
+            credentialType: 'string \u2014 e.g. "slackOAuth2Api"',
+            description: "string \u2014 what the user needs to set up"
+          }]
+        }
+      }
+    }, null, 2));
   }
 );
 server.tool(
   "kairos_validate",
-  "Validate n8n workflow JSON against 23 structural rules. Returns pass/fail with specific issues. If validation fails, fix the issues and call this again. Errors block deployment; warnings are advisory.",
+  "Validate n8n workflow JSON against 34 structural rules. Returns pass/fail with specific issues. If validation fails, fix the issues and call this again. Errors block deployment; warnings are advisory.",
   {
-    workflow: z.string().describe("The workflow JSON string to validate")
+    workflow: z.string().describe("The workflow JSON string to validate"),
+    kairos_run_id: z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation")
   },
-  async ({ workflow: workflowStr }) => {
+  async ({ workflow: workflowStr, kairos_run_id }) => {
     let parsed;
     try {
       parsed = JSON.parse(workflowStr);
     } catch (e) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            valid: false,
-            error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`
-          }, null, 2)
-        }]
-      };
+      return mcpText(JSON.stringify({ valid: false, error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` }, null, 2));
     }
-    const result = validator.validate(parsed);
+    const result = getValidator().validate(parsed);
     const errors = result.issues.filter((i) => i.severity === "error");
     const warnings = result.issues.filter((i) => i.severity === "warn");
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          valid: result.valid,
-          errorCount: errors.length,
-          warningCount: warnings.length,
-          errors: errors.map((i) => ({
-            rule: i.rule,
-            message: i.message,
-            nodeId: i.nodeId ?? null
-          })),
-          warnings: warnings.map((i) => ({
-            rule: i.rule,
-            message: i.message,
-            nodeId: i.nodeId ?? null
-          })),
-          deployable: errors.length === 0
-        }, null, 2)
-      }]
-    };
+    if (mcpTelemetry && kairos_run_id) {
+      const session = mcpSessions.get(kairos_run_id);
+      if (session) {
+        session.validateAttempts++;
+        await mcpTelemetry.emit("generation_attempt", {
+          description: session.description,
+          attempt: session.validateAttempts,
+          temperature: 0,
+          durationMs: 0,
+          tokensInput: 0,
+          tokensOutput: 0,
+          validationPassed: result.valid,
+          issueCount: result.issues.length,
+          issues: result.issues.map((i) => ({ rule: i.rule, severity: i.severity, message: i.message, nodeId: i.nodeId ?? null })),
+          workflowType: session.workflowType
+        }, kairos_run_id);
+      }
+    }
+    return mcpText(JSON.stringify({
+      valid: result.valid,
+      errorCount: errors.length,
+      warningCount: warnings.length,
+      errors: errors.map((i) => ({ rule: i.rule, message: i.message, nodeId: i.nodeId ?? null })),
+      warnings: warnings.map((i) => ({ rule: i.rule, message: i.message, nodeId: i.nodeId ?? null })),
+      deployable: errors.length === 0
+    }, null, 2));
   }
 );
 server.tool(
@@ -237,79 +288,147 @@ server.tool(
   "Deploy a validated workflow to n8n. Pass the workflow JSON that passed kairos_validate. Strips server-assigned fields automatically. Requires N8N_BASE_URL and N8N_API_KEY.",
   {
     workflow: z.string().describe("The validated workflow JSON string to deploy"),
-    activate: z.boolean().default(false).describe("Activate the workflow immediately after deployment")
+    activate: z.boolean().default(false).describe("Activate the workflow immediately after deployment"),
+    kairos_run_id: z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation"),
+    kairos_secret: z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
   },
-  async ({ workflow: workflowStr, activate }) => {
+  async ({ workflow: workflowStr, activate, kairos_run_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
     if (!isAllowed("deploy")) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Deploy is disabled. Set KAIROS_MCP_ALLOW_DEPLOY=true to enable." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Deploy is disabled. Set KAIROS_MCP_ALLOW_DEPLOY=true to enable." }));
     }
     let parsed;
     try {
       parsed = JSON.parse(workflowStr);
     } catch (e) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` })
-        }]
-      };
+      return mcpError(JSON.stringify({ error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` }));
     }
-    const validation = validator.validate(parsed);
+    const validation = getValidator().validate(parsed);
     const errors = validation.issues.filter((i) => i.severity === "error");
     if (errors.length > 0) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            error: "Workflow has validation errors \u2014 fix them before deploying",
-            errors: errors.map((i) => ({ rule: i.rule, message: i.message }))
-          }, null, 2)
-        }]
-      };
+      return mcpError(JSON.stringify({
+        error: "Workflow has validation errors \u2014 fix them before deploying",
+        errors: errors.map((i) => ({ rule: i.rule, message: i.message }))
+      }, null, 2));
     }
     const client = getApiClient();
     const stripped = stripper.stripForCreate(parsed);
     const response = await client.createWorkflow(stripped);
     if (activate) {
       if (!isAllowed("activate")) {
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              workflowId: response.id,
-              name: response.name,
-              activated: false,
-              warning: "Workflow deployed but activation is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable.",
-              url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
-            }, null, 2)
-          }]
-        };
+        return mcpText(JSON.stringify({
+          workflowId: response.id,
+          name: response.name,
+          activated: false,
+          warning: "Workflow deployed but activation is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable.",
+          url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
+        }, null, 2));
       }
       await client.activateWorkflow(response.id);
     }
+    const session = kairos_run_id ? mcpSessions.get(kairos_run_id) : void 0;
+    const missingSessionWarning = kairos_run_id && !session ? `
+
+Note: kairos_run_id "${kairos_run_id}" was provided but no active session was found. This usually means kairos_deploy was called without a prior kairos_prompt call, or the session expired. Telemetry and pattern learning for this build were skipped.` : "";
     await library.initialize();
     await library.save(parsed, {
-      description: parsed.name,
+      description: session?.description ?? parsed.name,
       generationMode: "scratch",
-      generationAttempts: 1
+      generationAttempts: session?.validateAttempts ?? 1,
+      n8nWorkflowId: response.id
     });
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          workflowId: response.id,
-          name: response.name,
-          activated: activate,
-          url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
-        }, null, 2)
-      }]
-    };
+    if (mcpTelemetry && kairos_run_id && session) {
+      await mcpTelemetry.emit("build_complete", {
+        description: session.description,
+        success: true,
+        totalAttempts: session.validateAttempts,
+        totalDurationMs: Date.now() - session.startTime,
+        totalTokensInput: 0,
+        totalTokensOutput: 0,
+        workflowName: response.name,
+        workflowId: response.id,
+        dryRun: false,
+        credentialsNeeded: 0,
+        warnedRules: session.warnedRules,
+        workflowType: session.workflowType
+      }, kairos_run_id);
+      mcpSessions.delete(kairos_run_id);
+      PatternAnalyzer.fromEnv().analyzeAndSave().catch(() => {
+      });
+    }
+    return mcpText(JSON.stringify({
+      workflowId: response.id,
+      name: response.name,
+      activated: activate,
+      url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
+    }, null, 2) + missingSessionWarning);
+  }
+);
+server.tool(
+  "kairos_replace",
+  "Replace an existing n8n workflow with a new version. Validates before updating. Use kairos_prompt \u2192 kairos_validate \u2192 kairos_replace for iteration on existing workflows.",
+  {
+    workflow_id: z.string().describe("The n8n workflow ID to replace"),
+    workflow: z.string().describe("The validated workflow JSON string"),
+    kairos_run_id: z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation"),
+    kairos_secret: z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
+  },
+  async ({ workflow_id, workflow: workflowStr, kairos_run_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
+    let parsed;
+    try {
+      parsed = JSON.parse(workflowStr);
+    } catch (e) {
+      return mcpError(JSON.stringify({ error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` }));
+    }
+    const validation = getValidator().validate(parsed);
+    const errors = validation.issues.filter((i) => i.severity === "error");
+    if (errors.length > 0) {
+      return mcpError(JSON.stringify({
+        error: "Workflow has validation errors \u2014 fix them before replacing",
+        errors: errors.map((i) => ({ rule: i.rule, message: i.message }))
+      }, null, 2));
+    }
+    const client = getApiClient();
+    const stripped = stripper.stripForUpdate(parsed);
+    const response = await client.updateWorkflow(workflow_id, stripped);
+    const session = kairos_run_id ? mcpSessions.get(kairos_run_id) : void 0;
+    const missingSessionWarning = kairos_run_id && !session ? `
+
+Note: kairos_run_id "${kairos_run_id}" was provided but no active session was found.` : "";
+    await library.initialize();
+    await library.save(parsed, {
+      description: session?.description ?? parsed.name,
+      generationMode: "scratch",
+      generationAttempts: session?.validateAttempts ?? 1,
+      n8nWorkflowId: workflow_id
+    });
+    if (mcpTelemetry && kairos_run_id && session) {
+      await mcpTelemetry.emit("build_complete", {
+        description: session.description,
+        success: true,
+        totalAttempts: session.validateAttempts,
+        totalDurationMs: Date.now() - session.startTime,
+        totalTokensInput: 0,
+        totalTokensOutput: 0,
+        workflowName: response.name,
+        workflowId: response.id,
+        dryRun: false,
+        credentialsNeeded: 0,
+        warnedRules: session.warnedRules,
+        workflowType: session.workflowType
+      }, kairos_run_id);
+      mcpSessions.delete(kairos_run_id);
+      PatternAnalyzer.fromEnv().analyzeAndSave().catch(() => {
+      });
+    }
+    return mcpText(JSON.stringify({
+      workflowId: response.id,
+      name: response.name,
+      url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
+    }, null, 2) + missingSessionWarning);
   }
 );
 server.tool(
@@ -322,23 +441,20 @@ server.tool(
   async ({ query, limit }) => {
     await library.initialize();
     const matches = await library.search(query);
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          matches.slice(0, limit).map((m) => ({
-            score: Number(m.score.toFixed(3)),
-            mode: m.mode,
-            description: m.workflow.description,
-            nodeCount: m.workflow.workflow.nodes.length,
-            nodes: m.workflow.workflow.nodes.map((n) => n.name),
-            failurePatterns: m.workflow.failurePatterns ?? []
-          })),
-          null,
-          2
-        )
-      }]
-    };
+    return mcpText(JSON.stringify(
+      matches.slice(0, limit).map((m) => ({
+        id: m.workflow.id,
+        score: Number(m.score.toFixed(3)),
+        mode: m.mode,
+        description: m.workflow.description,
+        nodeCount: m.workflow.workflow.nodes.length,
+        nodes: m.workflow.workflow.nodes.map((n) => n.name),
+        n8nWorkflowId: m.workflow.n8nWorkflowId ?? null,
+        failurePatterns: m.workflow.failurePatterns ?? []
+      })),
+      null,
+      2
+    ));
   }
 );
 server.tool(
@@ -349,36 +465,19 @@ server.tool(
     const baseUrl = process.env["N8N_BASE_URL"];
     const apiKey = process.env["N8N_API_KEY"];
     if (!baseUrl || !apiKey) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required for sync." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required for sync." }));
     }
     lastSync = null;
     const result = await autoSync();
     if (!result) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Failed to fetch node types from n8n. Check your credentials and that your instance is running." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Failed to fetch node types from n8n. Check your credentials and that your instance is running." }));
     }
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          synced: true,
-          nodeCount: result.nodeCount,
-          newNodes: result.newNodes,
-          message: `Synced ${result.nodeCount} node types from your n8n instance (${result.newNodes} not in default catalog).`
-        }, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify({
+      synced: true,
+      nodeCount: result.nodeCount,
+      newNodes: result.newNodes,
+      message: `Synced ${result.nodeCount} node types from your n8n instance (${result.newNodes} not in default catalog).`
+    }, null, 2));
   }
 );
 server.tool(
@@ -394,12 +493,72 @@ server.tool(
     if (limit !== void 0 && limit > 0) {
       analysis.topFailureRules = analysis.topFailureRules.slice(0, limit);
     }
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(analysis, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(analysis, null, 2));
+  }
+);
+server.tool(
+  "kairos_library",
+  "Browse the local Kairos workflow library. Returns saved workflow metadata. Use the optional query to search, or omit it to list all entries.",
+  {
+    query: z.string().optional().describe("Optional search query \u2014 omit to list all entries"),
+    limit: z.number().default(20).describe("Maximum entries to return")
+  },
+  async ({ query, limit }) => {
+    await library.initialize();
+    if (query) {
+      const matches = await library.search(query);
+      return mcpText(JSON.stringify(
+        matches.slice(0, limit).map((m) => ({
+          id: m.workflow.id,
+          description: m.workflow.description,
+          score: Number(m.score.toFixed(3)),
+          mode: m.mode,
+          nodeCount: m.workflow.workflow.nodes.length,
+          nodes: m.workflow.workflow.nodes.map((n) => n.name),
+          deployCount: m.workflow.deployCount,
+          n8nWorkflowId: m.workflow.n8nWorkflowId ?? null,
+          createdAt: m.workflow.createdAt
+        })),
+        null,
+        2
+      ));
+    }
+    const all = await library.list();
+    return mcpText(JSON.stringify(
+      all.slice(0, limit).map((w) => ({
+        id: w.id,
+        description: w.description,
+        nodeCount: w.workflow.nodes.length,
+        nodes: w.workflow.nodes.map((n) => n.name),
+        deployCount: w.deployCount,
+        n8nWorkflowId: w.n8nWorkflowId ?? null,
+        timesRetrieved: w.timesRetrieved ?? 0,
+        createdAt: w.createdAt
+      })),
+      null,
+      2
+    ));
+  }
+);
+server.tool(
+  "kairos_outcome",
+  "Record the outcome of a workflow build against a library entry. Trains the pattern learning system to know what works and what fails over time.",
+  {
+    library_id: z.string().describe("The Kairos library entry ID (returned by kairos_deploy, kairos_replace, or kairos_library)"),
+    attempts: z.number().describe("Number of generation+validation attempts before success"),
+    first_try_pass: z.boolean().describe("Whether the first attempt passed validation"),
+    failed_rules: z.array(z.number()).describe("Validation rule IDs that failed during generation"),
+    mode: z.enum(["direct", "reference"]).describe("How the library entry was used during generation")
+  },
+  async ({ library_id, attempts, first_try_pass, failed_rules, mode }) => {
+    await library.initialize();
+    await library.recordOutcome(library_id, {
+      attempts,
+      firstTryPass: first_try_pass,
+      failedRules: failed_rules,
+      mode
+    });
+    return mcpText(JSON.stringify({ recorded: true, libraryId: library_id }));
   }
 );
 server.tool(
@@ -409,12 +568,7 @@ server.tool(
   async () => {
     const client = getApiClient();
     const workflows = await client.listWorkflows();
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(workflows, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(workflows, null, 2));
   }
 );
 server.tool(
@@ -426,12 +580,7 @@ server.tool(
   async ({ workflow_id }) => {
     const client = getApiClient();
     const workflow = await client.getWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(workflow, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(workflow, null, 2));
   }
 );
 server.tool(
@@ -442,22 +591,11 @@ server.tool(
   },
   async ({ workflow_id }) => {
     if (!isAllowed("activate")) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Activate is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Activate is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable." }));
     }
     const client = getApiClient();
     await client.activateWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: `Activated workflow ${workflow_id}`
-      }]
-    };
+    return mcpText(`Activated workflow ${workflow_id}`);
   }
 );
 server.tool(
@@ -469,38 +607,25 @@ server.tool(
   async ({ workflow_id }) => {
     const client = getApiClient();
     await client.deactivateWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: `Deactivated workflow ${workflow_id}`
-      }]
-    };
+    return mcpText(`Deactivated workflow ${workflow_id}`);
   }
 );
 server.tool(
   "kairos_delete",
   "Delete a workflow from n8n. This is irreversible.",
   {
-    workflow_id: z.string().describe("The n8n workflow ID to delete")
+    workflow_id: z.string().describe("The n8n workflow ID to delete"),
+    kairos_secret: z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
   },
-  async ({ workflow_id }) => {
+  async ({ workflow_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
     if (!isAllowed("delete")) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Delete is disabled. Set KAIROS_MCP_ALLOW_DELETE=true to enable." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Delete is disabled. Set KAIROS_MCP_ALLOW_DELETE=true to enable." }));
     }
     const client = getApiClient();
     await client.deleteWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: `Deleted workflow ${workflow_id}`
-      }]
-    };
+    return mcpText(`Deleted workflow ${workflow_id}`);
   }
 );
 server.tool(
@@ -513,15 +638,15 @@ server.tool(
   async ({ workflow_id, limit }) => {
     const client = getApiClient();
     const executions = await client.getExecutions(workflow_id, { limit });
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(executions, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(executions, null, 2));
   }
 );
 async function main() {
+  if (!process.env["ANTHROPIC_API_KEY"]) {
+    process.stderr.write(
+      "[kairos-mcp] WARNING: ANTHROPIC_API_KEY is not set \u2014 kairos_prompt will fail. Set it before using workflow generation tools.\n"
+    );
+  }
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }