@kairos-sdk/core 0.4.5 → 0.5.1

package/dist/mcp-server.js

@@ -2,10 +2,11 @@
 import {
   PromptBuilder,
   inferWorkflowType
-} from "./chunk-CR2NHLOH.js";
+} from "./chunk-V2IZBZGB.js";
 import {
   DEFAULT_REGISTRY,
   FileLibrary,
+  GuardError,
   N8nApiClient,
   N8nFieldStripper,
   N8nValidator,
@@ -15,11 +16,13 @@ import {
   TelemetryReader,
   generateUUID,
   nullLogger
-} from "./chunk-6IXW3WCC.js";
+} from "./chunk-VPPWTMRJ.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "http";
 import { z } from "zod";
 
 // src/validation/node-syncer.ts
@@ -81,15 +84,44 @@ ${regularLines}`;
 
 // src/mcp-server.ts
 import { readFileSync } from "fs";
-import { dirname, join } from "path";
+import { dirname as dirname2, join } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
-var __dirname = dirname(fileURLToPath(import.meta.url));
+
+// src/utils/node-catalog-cache.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+async function readCatalogCache(cachePath) {
+  try {
+    const raw = await readFile(cachePath, "utf-8");
+    const cached = JSON.parse(raw);
+    if (Date.now() - cached.cachedAt > CACHE_TTL_MS) return null;
+    return cached.syncResult;
+  } catch {
+    return null;
+  }
+}
+async function writeCatalogCache(cachePath, syncResult) {
+  try {
+    await mkdir(dirname(cachePath), { recursive: true });
+    const payload = { cachedAt: Date.now(), syncResult };
+    await writeFile(cachePath, JSON.stringify(payload), "utf-8");
+  } catch {
+  }
+}
+
+// src/mcp-server.ts
+var __dirname = dirname2(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(getMcpPatternsPath());
 function getMcpTelemetry() {
@@ -120,20 +152,51 @@ function getTelemetryReader() {
     return null;
   }
 }
+function getMcpMode() {
+  const mode = process.env["KAIROS_MCP_MODE"]?.toLowerCase();
+  if (mode === "readonly" || mode === "validate") return mode;
+  return "deploy";
+}
 function isAllowed(action) {
+  const mode = getMcpMode();
+  if (mode === "readonly" || mode === "validate") return false;
   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);
 }
+function getCatalogCachePath() {
+  const telemetry = process.env["KAIROS_TELEMETRY"];
+  const base = telemetry ? join(telemetry, "..") : join(homedir(), ".kairos");
+  return join(base, "node-catalog-cache.json");
+}
 async function autoSync() {
   if (lastSync) return lastSync;
+  const cachePath = getCatalogCachePath();
+  const cached = await readCatalogCache(cachePath);
+  if (cached) {
+    lastSync = cached;
+    _validator = new N8nValidator(lastSync.registry);
+    return lastSync;
+  }
   const baseUrl = process.env["N8N_BASE_URL"];
   const apiKey = process.env["N8N_API_KEY"];
   if (!baseUrl || !apiKey) return null;
@@ -142,7 +205,9 @@ 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);
+    writeCatalogCache(cachePath, lastSync).catch(() => {
+    });
     return lastSync;
   } catch {
     return null;
@@ -161,24 +226,20 @@ server.tool(
   },
   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
-      };
-    }
     const runId = generateUUID();
     const workflowType = inferWorkflowType(description);
+    const hasN8nCreds = !!(process.env["N8N_BASE_URL"] && process.env["N8N_API_KEY"]);
+    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) {
@@ -187,48 +248,46 @@ server.tool(
         startTime: Date.now(),
         validateAttempts: 0,
         warnedRules: promptBuilder.getWarnedRules(),
-        workflowType
+        workflowType,
+        matchCount: matches.length
       });
       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({
-          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)
-      }]
-    };
+    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: hasN8nCreds ? "Could not sync node types from your n8n instance. Using static fallback catalog \u2014 generated workflows may not match your exact n8n setup." : "N8N_BASE_URL and N8N_API_KEY are not set. Using static fallback catalog \u2014 node types may not match your n8n instance. Set these env vars to enable accurate generation and deployment."
+      },
+      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 26 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"),
     kairos_run_id: z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation")
@@ -238,17 +297,9 @@ server.tool(
     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");
     if (mcpTelemetry && kairos_run_id) {
@@ -269,27 +320,14 @@ server.tool(
         }, kairos_run_id);
       }
     }
-    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)
-      }]
-    };
+    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(
@@ -298,101 +336,151 @@ server.tool(
   {
     workflow: z.string().describe("The validated workflow JSON string to deploy"),
     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")
+    description: z.string().optional().describe("The original user intent / description for this workflow \u2014 used to improve library search quality over time"),
+    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, kairos_run_id }) => {
+  async ({ workflow: workflowStr, activate, description: userDescription, 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,
-      generationMode: "scratch",
-      generationAttempts: 1
+      description: session?.description ?? userDescription ?? parsed.name,
+      generationMode: session && session.matchCount > 0 ? "reference" : "scratch",
+      generationAttempts: session?.validateAttempts ?? 1,
+      n8nWorkflowId: response.id
     });
-    if (mcpTelemetry && kairos_run_id) {
-      const session = mcpSessions.get(kairos_run_id);
-      if (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(() => {
-        });
-      }
+    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 {
-      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)
-      }]
-    };
+    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"),
+    description: z.string().optional().describe("The original user intent / description for this workflow \u2014 used to improve library search quality over time"),
+    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, description: userDescription, kairos_run_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
+    if (!isAllowed("deploy")) {
+      return mcpError(JSON.stringify({ error: "Replace is disabled. Set KAIROS_MCP_ALLOW_DEPLOY=true or KAIROS_MCP_MODE=deploy to enable." }));
+    }
+    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 ?? userDescription ?? parsed.name,
+      generationMode: session && session.matchCount > 0 ? "reference" : "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(
@@ -405,23 +493,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(
@@ -432,36 +517,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(
@@ -477,12 +545,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(
@@ -492,12 +620,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(
@@ -509,12 +632,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(
@@ -525,22 +643,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(
@@ -552,38 +659,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(
@@ -596,17 +690,36 @@ 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() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  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 useHttp = process.argv.includes("--http");
+  if (useHttp) {
+    const port = parseInt(process.env["KAIROS_MCP_PORT"] ?? "3000", 10);
+    const transport = new StreamableHTTPServerTransport();
+    await server.connect(transport);
+    const httpServer = createServer(async (req, res) => {
+      if (req.method === "GET" || req.method === "POST" || req.method === "DELETE") {
+        await transport.handleRequest(req, res);
+      } else {
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Method not allowed" }));
+      }
+    });
+    httpServer.listen(port, () => {
+      process.stderr.write(`[kairos-mcp] HTTP transport listening on port ${port}
+`);
+    });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  }
 }
 main().catch((err) => {
   console.error("Kairos MCP server failed to start:", err);