@kairos-sdk/core 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1,10 +1,9 @@
-import { C as ClientOptions, B as BuildOptions, a as BuildResult, N as N8nWorkflow, W as WorkflowListItem, D as DeleteOptions, E as ExecutionFilter, b as ExecutionSummary, c as ExecutionDetail, T as Tag } from './reader-B5mV20H6.cjs';
-export { A as ApiError, d as AttemptMetadata, e as CredentialRequirement, f as DEFAULT_REGISTRY, g as DeployResult, F as FailurePattern, h as FileLibrary, G as GenerationError, i as GuardError, I as ILogger, j as IProvider, k as IWorkflowLibrary, K as KairosError, l as N8nApiClient, m as N8nConnections, n as N8nFieldStripper, o as N8nNode, p as N8nProvider, q as N8nSettings, r as N8nValidator, s as NodeRegistry, t as NullLibrary, O as OutcomeData, u as OutcomeStats, P as ProviderError, R as ResponseParseError, v as RuleFailureRate, S as ScoredEntry, w as SmokeTestResult, x as SourceKind, y as StoredWorkflow, z as SyncProgress, H as TelemetryCollector, J as TelemetryEvent, L as TelemetryReader, M as TemplateSyncer, Q as TrustLevel, V as ValidationError, U as ValidationIssue, X as ValidationResult, Y as WorkflowCluster, Z as WorkflowMatch, _ as WorkflowMetadataInput, $ as buildSearchCorpus, a0 as clusterWorkflows, a1 as hybridScore, a2 as nullLogger, a3 as rerank, a4 as tokenize } from './reader-B5mV20H6.cjs';
+import { C as ClientOptions, B as BuildOptions, b as BuildResult, r as N8nWorkflow, Z as WorkflowListItem, d as DeleteOptions, f as ExecutionFilter, g as ExecutionSummary, E as ExecutionDetail, T as Tag, c as CredentialRequirement } from './reader-CfWGpL4V.cjs';
+export { A as ApiError, a as AttemptMetadata, D as DEFAULT_REGISTRY, e as DeployResult, F as FailurePattern, h as FileLibrary, G as GenerationError, i as GuardError, I as ILogger, j as IProvider, k as IWorkflowLibrary, K as KairosError, N as N8nApiClient, l as N8nConnections, m as N8nFieldStripper, n as N8nNode, o as N8nProvider, p as N8nSettings, q as N8nValidator, s as NodeRegistry, t as NullLibrary, O as OutcomeData, u as OutcomeStats, P as ProviderError, R as ResponseParseError, v as RuleFailureRate, S as ScoredEntry, w as SmokeTestResult, y as SourceKind, z as StoredWorkflow, H as SyncProgress, J as TelemetryCollector, L as TelemetryEvent, M as TelemetryReader, Q as TemplateSyncer, U as TrustLevel, V as ValidationError, W as ValidationIssue, X as ValidationResult, Y as WorkflowCluster, _ as WorkflowMatch, $ as WorkflowMetadataInput, a0 as buildSearchCorpus, a1 as clusterWorkflows, a2 as hybridScore, a3 as nullLogger, a4 as rerank, a5 as tokenize } from './reader-CfWGpL4V.cjs';
 
 declare class Kairos {
     private readonly provider;
     private readonly designer;
-    private readonly validator;
     private readonly library;
     private readonly logger;
     private readonly telemetry;
@@ -35,4 +34,87 @@ declare class Kairos {
     untag(workflowId: string, tagIds: string[]): Promise<void>;
 }
 
-export { BuildOptions, BuildResult, ClientOptions, DeleteOptions, ExecutionDetail, ExecutionFilter, ExecutionSummary, Kairos, N8nWorkflow, Tag, WorkflowListItem };
+type AssumptionType = 'safe' | 'needs_confirmation' | 'blocking';
+type PackStatus = 'draft' | 'blocked' | 'ready_for_test' | 'ready_for_activation' | 'active' | 'needs_attention';
+interface TypedAssumption {
+    type: AssumptionType;
+    text: string;
+}
+interface WorkflowPlan {
+    name: string;
+    description: string;
+    purpose: string;
+}
+interface PackPlan {
+    businessContext: string;
+    workflows: WorkflowPlan[];
+    assumptions: TypedAssumption[];
+    sheetsColumns: Array<{
+        sheet: string;
+        columns: string[];
+    }>;
+    testChecklist: Array<{
+        workflow: string;
+        steps: string[];
+    }>;
+}
+interface PackWorkflowResult {
+    name: string;
+    purpose: string;
+    workflowId: string | null;
+    deployed: boolean;
+    generationAttempts: number;
+    credentialsNeeded: CredentialRequirement[];
+    error?: string;
+}
+interface WorkflowPackResult {
+    businessContext: string;
+    packName: string;
+    status: PackStatus;
+    workflows: PackWorkflowResult[];
+    allCredentials: Array<{
+        service: string;
+        credentialType: string;
+    }>;
+    sheetsColumns: Array<{
+        sheet: string;
+        columns: string[];
+    }>;
+    assumptions: TypedAssumption[];
+    testChecklist: Array<{
+        workflow: string;
+        steps: string[];
+    }>;
+    builtAt: string;
+}
+declare function derivePackStatus(pack: Pick<WorkflowPackResult, 'assumptions' | 'workflows'> & {
+    status?: PackStatus;
+}): PackStatus;
+declare class PackBuilder {
+    private client;
+    private kairos;
+    private model;
+    constructor(options: {
+        anthropicApiKey: string;
+        kairos: Kairos;
+        model?: string;
+    });
+    plan(businessContext: string): Promise<PackPlan>;
+    build(plan: PackPlan, options?: {
+        dryRun?: boolean;
+        activate?: boolean;
+        onProgress?: (workflow: WorkflowPlan, index: number, total: number) => void;
+    }): Promise<WorkflowPackResult>;
+}
+
+declare function generateHandoff(pack: WorkflowPackResult): string;
+
+interface PackValidationIssue {
+    type: 'duplicate_name' | 'blocking_assumption' | 'unsafe_activation' | 'schedule_conflict';
+    severity: 'error' | 'warning';
+    message: string;
+    workflows?: string[];
+}
+declare function validatePack(pack: WorkflowPackResult): PackValidationIssue[];
+
+export { type AssumptionType, BuildOptions, BuildResult, ClientOptions, CredentialRequirement, DeleteOptions, ExecutionDetail, ExecutionFilter, ExecutionSummary, Kairos, N8nWorkflow, PackBuilder, type PackPlan, type PackStatus, type PackValidationIssue, type PackWorkflowResult, Tag, type TypedAssumption, WorkflowListItem, type WorkflowPackResult, type WorkflowPlan, derivePackStatus, generateHandoff, validatePack };

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import { C as ClientOptions, B as BuildOptions, a as BuildResult, N as N8nWorkflow, W as WorkflowListItem, D as DeleteOptions, E as ExecutionFilter, b as ExecutionSummary, c as ExecutionDetail, T as Tag } from './reader-B5mV20H6.js';
-export { A as ApiError, d as AttemptMetadata, e as CredentialRequirement, f as DEFAULT_REGISTRY, g as DeployResult, F as FailurePattern, h as FileLibrary, G as GenerationError, i as GuardError, I as ILogger, j as IProvider, k as IWorkflowLibrary, K as KairosError, l as N8nApiClient, m as N8nConnections, n as N8nFieldStripper, o as N8nNode, p as N8nProvider, q as N8nSettings, r as N8nValidator, s as NodeRegistry, t as NullLibrary, O as OutcomeData, u as OutcomeStats, P as ProviderError, R as ResponseParseError, v as RuleFailureRate, S as ScoredEntry, w as SmokeTestResult, x as SourceKind, y as StoredWorkflow, z as SyncProgress, H as TelemetryCollector, J as TelemetryEvent, L as TelemetryReader, M as TemplateSyncer, Q as TrustLevel, V as ValidationError, U as ValidationIssue, X as ValidationResult, Y as WorkflowCluster, Z as WorkflowMatch, _ as WorkflowMetadataInput, $ as buildSearchCorpus, a0 as clusterWorkflows, a1 as hybridScore, a2 as nullLogger, a3 as rerank, a4 as tokenize } from './reader-B5mV20H6.js';
+import { C as ClientOptions, B as BuildOptions, b as BuildResult, r as N8nWorkflow, Z as WorkflowListItem, d as DeleteOptions, f as ExecutionFilter, g as ExecutionSummary, E as ExecutionDetail, T as Tag, c as CredentialRequirement } from './reader-CfWGpL4V.js';
+export { A as ApiError, a as AttemptMetadata, D as DEFAULT_REGISTRY, e as DeployResult, F as FailurePattern, h as FileLibrary, G as GenerationError, i as GuardError, I as ILogger, j as IProvider, k as IWorkflowLibrary, K as KairosError, N as N8nApiClient, l as N8nConnections, m as N8nFieldStripper, n as N8nNode, o as N8nProvider, p as N8nSettings, q as N8nValidator, s as NodeRegistry, t as NullLibrary, O as OutcomeData, u as OutcomeStats, P as ProviderError, R as ResponseParseError, v as RuleFailureRate, S as ScoredEntry, w as SmokeTestResult, y as SourceKind, z as StoredWorkflow, H as SyncProgress, J as TelemetryCollector, L as TelemetryEvent, M as TelemetryReader, Q as TemplateSyncer, U as TrustLevel, V as ValidationError, W as ValidationIssue, X as ValidationResult, Y as WorkflowCluster, _ as WorkflowMatch, $ as WorkflowMetadataInput, a0 as buildSearchCorpus, a1 as clusterWorkflows, a2 as hybridScore, a3 as nullLogger, a4 as rerank, a5 as tokenize } from './reader-CfWGpL4V.js';
 
 declare class Kairos {
     private readonly provider;
     private readonly designer;
-    private readonly validator;
     private readonly library;
     private readonly logger;
     private readonly telemetry;
@@ -35,4 +34,87 @@ declare class Kairos {
     untag(workflowId: string, tagIds: string[]): Promise<void>;
 }
 
-export { BuildOptions, BuildResult, ClientOptions, DeleteOptions, ExecutionDetail, ExecutionFilter, ExecutionSummary, Kairos, N8nWorkflow, Tag, WorkflowListItem };
+type AssumptionType = 'safe' | 'needs_confirmation' | 'blocking';
+type PackStatus = 'draft' | 'blocked' | 'ready_for_test' | 'ready_for_activation' | 'active' | 'needs_attention';
+interface TypedAssumption {
+    type: AssumptionType;
+    text: string;
+}
+interface WorkflowPlan {
+    name: string;
+    description: string;
+    purpose: string;
+}
+interface PackPlan {
+    businessContext: string;
+    workflows: WorkflowPlan[];
+    assumptions: TypedAssumption[];
+    sheetsColumns: Array<{
+        sheet: string;
+        columns: string[];
+    }>;
+    testChecklist: Array<{
+        workflow: string;
+        steps: string[];
+    }>;
+}
+interface PackWorkflowResult {
+    name: string;
+    purpose: string;
+    workflowId: string | null;
+    deployed: boolean;
+    generationAttempts: number;
+    credentialsNeeded: CredentialRequirement[];
+    error?: string;
+}
+interface WorkflowPackResult {
+    businessContext: string;
+    packName: string;
+    status: PackStatus;
+    workflows: PackWorkflowResult[];
+    allCredentials: Array<{
+        service: string;
+        credentialType: string;
+    }>;
+    sheetsColumns: Array<{
+        sheet: string;
+        columns: string[];
+    }>;
+    assumptions: TypedAssumption[];
+    testChecklist: Array<{
+        workflow: string;
+        steps: string[];
+    }>;
+    builtAt: string;
+}
+declare function derivePackStatus(pack: Pick<WorkflowPackResult, 'assumptions' | 'workflows'> & {
+    status?: PackStatus;
+}): PackStatus;
+declare class PackBuilder {
+    private client;
+    private kairos;
+    private model;
+    constructor(options: {
+        anthropicApiKey: string;
+        kairos: Kairos;
+        model?: string;
+    });
+    plan(businessContext: string): Promise<PackPlan>;
+    build(plan: PackPlan, options?: {
+        dryRun?: boolean;
+        activate?: boolean;
+        onProgress?: (workflow: WorkflowPlan, index: number, total: number) => void;
+    }): Promise<WorkflowPackResult>;
+}
+
+declare function generateHandoff(pack: WorkflowPackResult): string;
+
+interface PackValidationIssue {
+    type: 'duplicate_name' | 'blocking_assumption' | 'unsafe_activation' | 'schedule_conflict';
+    severity: 'error' | 'warning';
+    message: string;
+    workflows?: string[];
+}
+declare function validatePack(pack: WorkflowPackResult): PackValidationIssue[];
+
+export { type AssumptionType, BuildOptions, BuildResult, ClientOptions, CredentialRequirement, DeleteOptions, ExecutionDetail, ExecutionFilter, ExecutionSummary, Kairos, N8nWorkflow, PackBuilder, type PackPlan, type PackStatus, type PackValidationIssue, type PackWorkflowResult, Tag, type TypedAssumption, WorkflowListItem, type WorkflowPackResult, type WorkflowPlan, derivePackStatus, generateHandoff, validatePack };

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   Kairos
-} from "./chunk-HBGZTUUZ.js";
-import "./chunk-EVOAYH2K.js";
+} from "./chunk-YOQTEVDB.js";
+import "./chunk-STG7Z2SS.js";
 import "./chunk-6FOFWVMG.js";
 import {
   GenerationError,
@@ -10,7 +10,7 @@ import {
   ResponseParseError,
   TemplateSyncer,
   ValidationError
-} from "./chunk-5GAY7CSJ.js";
+} from "./chunk-PCNW5ZUD.js";
 import {
   ApiError,
   DEFAULT_REGISTRY,
@@ -30,7 +30,17 @@ import {
   nullLogger,
   rerank,
   tokenize
-} from "./chunk-KIFT5LA7.js";
+} from "./chunk-2ZHNO37N.js";
+import {
+  PackBuilder,
+  derivePackStatus
+} from "./chunk-GG4B4TYG.js";
+import {
+  generateHandoff
+} from "./chunk-SC6CLQZB.js";
+import {
+  validatePack
+} from "./chunk-SQS4QHDH.js";
 export {
   ApiError,
   DEFAULT_REGISTRY,
@@ -45,6 +55,7 @@ export {
   N8nValidator,
   NodeRegistry,
   NullLibrary,
+  PackBuilder,
   ProviderError,
   ResponseParseError,
   TelemetryCollector,
@@ -53,9 +64,12 @@ export {
   ValidationError,
   buildSearchCorpus,
   clusterWorkflows,
+  derivePackStatus,
+  generateHandoff,
   hybridScore,
   nullLogger,
   rerank,
-  tokenize
+  tokenize,
+  validatePack
 };
 //# sourceMappingURL=index.js.map

package/dist/mcp-server.cjs

@@ -4,6 +4,8 @@
 // src/mcp-server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+var import_node_http = require("http");
 var import_zod = require("zod");
 
 // src/library/file-library.ts
@@ -899,6 +901,7 @@ var N8nValidator = class {
     this.checkRule32(workflow, issues);
     this.checkRule33(workflow, issues);
     this.checkRule34(workflow, issues);
+    this.checkRule35(workflow, issues);
     if (Array.isArray(workflow.nodes)) {
       const nodeById = new Map(workflow.nodes.map((n) => [n.id, n.type]));
       for (const issue of issues) {
@@ -1471,6 +1474,43 @@ var N8nValidator = class {
       }
     }
   }
+  // Rule 35 (WARN): email-sending node with no duplicate-prevention signal
+  checkRule35(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const sendNodes = w.nodes.filter((node) => {
+      if (node.type === "n8n-nodes-base.gmail") {
+        const op = node.parameters?.["operation"];
+        return !op || op === "send" || op === "sendEmail" || op === "reply";
+      }
+      return node.type === "n8n-nodes-base.emailSend" || node.type === "n8n-nodes-base.sendEmail";
+    });
+    if (sendNodes.length === 0) return;
+    const workflowText = JSON.stringify(w).toLowerCase();
+    const IDEMPOTENCY_SIGNALS = [
+      "sent_at",
+      "last_sent",
+      "last_reminder",
+      "processed_at",
+      "already_sent",
+      "email_sent",
+      "notified_at",
+      "reminder_sent",
+      "contacted_at",
+      "dedupe",
+      "idempotent"
+    ];
+    const hasIdempotencySignal = IDEMPOTENCY_SIGNALS.some((s) => workflowText.includes(s));
+    if (!hasIdempotencySignal) {
+      for (const node of sendNodes) {
+        this.warn(
+          issues,
+          35,
+          `Node "${node.name}" sends email but no duplicate-prevention signal detected \u2014 add a sent_at timestamp field, a prior-send IF check, or a deduplication key to avoid repeat sends`,
+          node.id
+        );
+      }
+    }
+  }
   // Rule 34 (WARN): webhook path contains spaces, starts with slash, or looks like a full URL
   checkRule34(w, issues) {
     if (!Array.isArray(w.nodes)) return;
@@ -2018,7 +2058,7 @@ Respond ONLY with a generate_workflow tool call. No prose. No markdown outside t
 If the request is impossible or unclear, set the error field instead of generating a workflow.`;
 
 // src/validation/rule-metadata.ts
-var VALIDATOR_RULE_IDS = Array.from({ length: 34 }, (_, i) => i + 1);
+var VALIDATOR_RULE_IDS = Array.from({ length: 35 }, (_, i) => i + 1);
 var RULE_PIPELINE_STAGES = {
   1: "node_generation",
   2: "node_generation",
@@ -2053,7 +2093,8 @@ var RULE_PIPELINE_STAGES = {
   31: "node_generation",
   32: "node_generation",
   33: "node_generation",
-  34: "node_generation"
+  34: "node_generation",
+  35: "node_generation"
 };
 var RULE_EXAMPLES = {
   17: {
@@ -2103,6 +2144,10 @@ var RULE_EXAMPLES = {
   34: {
     bad: '"path": "/my webhook"',
     good: '"path": "my-webhook"'
+  },
+  35: {
+    bad: '"type": "n8n-nodes-base.gmail", "parameters": { "operation": "send" }  // no sent_at tracking',
+    good: 'Add a Set node after send that writes "sent_at": "={{ $now }}" back to the sheet, or an IF node that checks sent_at before sending'
   }
 };
 var RULE_MITIGATIONS = {
@@ -2139,7 +2184,8 @@ var RULE_MITIGATIONS = {
   31: "Add at least one condition to the if node \u2014 conditions.conditions array must be non-empty",
   32: "Add field assignments to the set node \u2014 assignments.assignments array must be non-empty for typeVersion 3.x",
   33: "Add at least one schedule rule to scheduleTrigger \u2014 rule.interval array must have at least one entry",
-  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")'
+  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")',
+  35: "Add duplicate-prevention to email-sending workflows: a sent_at timestamp field updated after each send, or an IF node that checks prior-send status before sending"
 };
 
 // src/generation/prompt-builder.ts
@@ -2594,7 +2640,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
     this._cachedEvents = events;
     const starts = events.filter((e) => e.eventType === "build_start");
     const attempts = events.filter((e) => e.eventType === "generation_attempt");
-    const passed = attempts.filter(
+    const _passed = attempts.filter(
       (a) => a.data.validationPassed === true
     );
     const failed = attempts.filter(
@@ -3177,12 +3223,37 @@ function inferWorkflowType(description) {
 
 // src/mcp-server.ts
 var import_node_fs3 = require("fs");
-var import_node_path7 = require("path");
+var import_node_path8 = require("path");
 var import_node_os6 = require("os");
 var import_node_url = require("url");
+
+// src/utils/node-catalog-cache.ts
+var import_promises5 = require("fs/promises");
+var import_node_path7 = require("path");
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+async function readCatalogCache(cachePath) {
+  try {
+    const raw = await (0, import_promises5.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 (0, import_promises5.mkdir)((0, import_node_path7.dirname)(cachePath), { recursive: true });
+    const payload = { cachedAt: Date.now(), syncResult };
+    await (0, import_promises5.writeFile)(cachePath, JSON.stringify(payload), "utf-8");
+  } catch {
+  }
+}
+
+// src/mcp-server.ts
 var import_meta = {};
-var __dirname = (0, import_node_path7.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
-var pkg = JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path7.join)(__dirname, "..", "package.json"), "utf-8"));
+var __dirname = (0, import_node_path8.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+var pkg = JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path8.join)(__dirname, "..", "package.json"), "utf-8"));
 var library = new FileLibrary();
 var _validator = new N8nValidator();
 function getValidator() {
@@ -3201,9 +3272,9 @@ function getMcpTelemetry() {
 function getMcpPatternsPath() {
   const val = process.env["KAIROS_TELEMETRY"];
   if (val && val !== "false" && val !== "true") {
-    return (0, import_node_path7.join)(val, "..", "patterns.json");
+    return (0, import_node_path8.join)(val, "..", "patterns.json");
   }
-  return (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".kairos", "patterns.json");
+  return (0, import_node_path8.join)((0, import_node_os6.homedir)(), ".kairos", "patterns.json");
 }
 var mcpTelemetry = getMcpTelemetry();
 var mcpSessions = /* @__PURE__ */ new Map();
@@ -3221,7 +3292,14 @@ 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";
 }
@@ -3245,8 +3323,20 @@ function getApiClient() {
   }
   return new N8nApiClient(baseUrl, apiKey, nullLogger);
 }
+function getCatalogCachePath() {
+  const telemetry = process.env["KAIROS_TELEMETRY"];
+  const base = telemetry ? (0, import_node_path8.join)(telemetry, "..") : (0, import_node_path8.join)((0, import_node_os6.homedir)(), ".kairos");
+  return (0, import_node_path8.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;
@@ -3256,6 +3346,8 @@ async function autoSync() {
     if (nodeTypes.length === 0) return null;
     lastSync = nodeSyncer.sync(nodeTypes);
     _validator = new N8nValidator(lastSync.registry);
+    writeCatalogCache(cachePath, lastSync).catch(() => {
+    });
     return lastSync;
   } catch {
     return null;
@@ -3274,13 +3366,9 @@ server.tool(
   },
   async ({ description, name }) => {
     evictStaleSessions();
-    const baseUrl = process.env["N8N_BASE_URL"];
-    const apiKey = process.env["N8N_API_KEY"];
-    if (!baseUrl || !apiKey) {
-      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 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();
@@ -3300,7 +3388,8 @@ 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);
     }
@@ -3312,7 +3401,9 @@ server.tool(
       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." },
+      ...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: {
@@ -3385,10 +3476,11 @@ server.tool(
   {
     workflow: import_zod.z.string().describe("The validated workflow JSON string to deploy"),
     activate: import_zod.z.boolean().default(false).describe("Activate the workflow immediately after deployment"),
+    description: import_zod.z.string().optional().describe("The original user intent / description for this workflow \u2014 used to improve library search quality over time"),
     kairos_run_id: import_zod.z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation"),
     kairos_secret: import_zod.z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
   },
-  async ({ workflow: workflowStr, activate, kairos_run_id, kairos_secret }) => {
+  async ({ workflow: workflowStr, activate, description: userDescription, kairos_run_id, kairos_secret }) => {
     const authError = checkMcpAuth(kairos_secret);
     if (authError) return authError;
     if (!isAllowed("deploy")) {
@@ -3429,8 +3521,8 @@ server.tool(
 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: session?.description ?? parsed.name,
-      generationMode: "scratch",
+      description: session?.description ?? userDescription ?? parsed.name,
+      generationMode: session && session.matchCount > 0 ? "reference" : "scratch",
       generationAttempts: session?.validateAttempts ?? 1,
       n8nWorkflowId: response.id
     });
@@ -3467,12 +3559,16 @@ server.tool(
   {
     workflow_id: import_zod.z.string().describe("The n8n workflow ID to replace"),
     workflow: import_zod.z.string().describe("The validated workflow JSON string"),
+    description: import_zod.z.string().optional().describe("The original user intent / description for this workflow \u2014 used to improve library search quality over time"),
     kairos_run_id: import_zod.z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation"),
     kairos_secret: import_zod.z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
   },
-  async ({ workflow_id, workflow: workflowStr, kairos_run_id, kairos_secret }) => {
+  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);
@@ -3496,8 +3592,8 @@ server.tool(
 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",
+      description: session?.description ?? userDescription ?? parsed.name,
+      generationMode: session && session.matchCount > 0 ? "reference" : "scratch",
       generationAttempts: session?.validateAttempts ?? 1,
       n8nWorkflowId: workflow_id
     });
@@ -3743,8 +3839,27 @@ async function main() {
       "[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 import_stdio.StdioServerTransport();
-  await server.connect(transport);
+  const useHttp = process.argv.includes("--http");
+  if (useHttp) {
+    const port = parseInt(process.env["KAIROS_MCP_PORT"] ?? "3000", 10);
+    const transport = new import_streamableHttp.StreamableHTTPServerTransport();
+    await server.connect(transport);
+    const httpServer = (0, import_node_http.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 import_stdio.StdioServerTransport();
+    await server.connect(transport);
+  }
 }
 main().catch((err) => {
   console.error("Kairos MCP server failed to start:", err);