@kal-elsam/kairo-runtime 0.13.1 → 0.15.0

package/src/global/integrations/sdd-state.js

@@ -8,6 +8,7 @@ export function defaultSddState() {
     personaAgentIds: [],
     agentIds: [],
     files: [],
+    adopted: [],
     lastReceiptId: null,
     updatedAt: null
   };
@@ -25,6 +26,7 @@ export function normalizeSddState(raw) {
     personaAgentIds,
     agentIds: Array.isArray(raw.agentIds) ? [...raw.agentIds] : [],
     files: Array.isArray(raw.files) ? raw.files.map(normalizeSddFile) : [],
+    adopted: Array.isArray(raw.adopted) ? raw.adopted.map(normalizeAdoptedFile).filter(Boolean) : [],
     lastReceiptId: typeof raw.lastReceiptId === "string" ? raw.lastReceiptId : null,
     updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : null
   };
@@ -42,6 +44,72 @@ function normalizeSddFile(entry) {
   };
 }
 
+function normalizeAdoptedFile(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  if (typeof entry.destinationPath !== "string" || !entry.destinationPath) return null;
+  if (typeof entry.hash !== "string" || !entry.hash) return null;
+  return {
+    destinationPath: entry.destinationPath,
+    hash: entry.hash,
+    skillId: typeof entry.skillId === "string" ? entry.skillId : null,
+    agentIds: Array.isArray(entry.agentIds) ? [...entry.agentIds] : [],
+    relativePath: typeof entry.relativePath === "string" ? entry.relativePath : "SKILL.md",
+    adoptedAt: typeof entry.adoptedAt === "string" ? entry.adoptedAt : null,
+    reason: typeof entry.reason === "string" ? entry.reason : null
+  };
+}
+
+/** Map destinationPath → adopted hash for verify/plan. */
+export function adoptedHashesFromState(sdd) {
+  const adopted = normalizeSddState(sdd).adopted;
+  return Object.fromEntries(adopted.map((entry) => [entry.destinationPath, entry.hash]));
+}
+
+/** Record conflict findings as adopted disk hashes (no file writes). */
+export function recordSddAdoptions(state, {
+  adoptions = [],
+  now = () => new Date().toISOString()
+} = {}) {
+  const current = normalizeSddState(state?.sdd);
+  const byPath = new Map(current.adopted.map((entry) => [entry.destinationPath, entry]));
+  for (const entry of adoptions) {
+    const normalized = normalizeAdoptedFile({
+      ...entry,
+      adoptedAt: entry.adoptedAt ?? now()
+    });
+    if (!normalized) continue;
+    byPath.set(normalized.destinationPath, normalized);
+  }
+  const adopted = [...byPath.values()].sort((a, b) =>
+    a.destinationPath.localeCompare(b.destinationPath)
+  );
+  return {
+    ...(state ?? {}),
+    sdd: {
+      ...current,
+      adopted,
+      updatedAt: now()
+    }
+  };
+}
+
+/** Drop adopted entries for paths that become Kairo-managed (overwrite/apply). */
+export function clearSddAdoptionsForPaths(state, paths = [], {
+  now = () => new Date().toISOString()
+} = {}) {
+  const current = normalizeSddState(state?.sdd);
+  const drop = new Set(paths);
+  const adopted = current.adopted.filter((entry) => !drop.has(entry.destinationPath));
+  return {
+    ...(state ?? {}),
+    sdd: {
+      ...current,
+      adopted,
+      updatedAt: now()
+    }
+  };
+}
+
 function verifiedNoopHash(file) {
   const disk = file.afterHash ?? file.diskHash ?? file.beforeHash ?? null;
   if (disk == null || file.canonicalHash == null || disk !== file.canonicalHash) return null;
@@ -116,6 +184,7 @@ export function recordSddMaterialization(state, { receipt, now = () => new Date(
       personaAgentIds,
       agentIds: collectAgentIds(files),
       files,
+      adopted: current.adopted,
       lastReceiptId: receipt.id ?? current.lastReceiptId,
       updatedAt: now()
     }

package/src/global/integrations/sdd-verify.js

@@ -26,6 +26,7 @@ export async function verifySddConfigure({
   homeDir,
   packageRoot,
   trackedFiles = {},
+  adoptedFiles = {},
   personaAgentIds = [],
   exists = existsSync,
   readFileImpl = readFile
@@ -49,14 +50,15 @@ export async function verifySddConfigure({
         const fileExists = exists(destinationPath);
         const diskHash = fileExists ? hashBuffer(await readFileImpl(destinationPath)) : null;
         const trackedHash = trackedFiles[destinationPath] ?? null;
+        const adoptedHash = adoptedFiles[destinationPath] ?? null;
         const health = classifySddVerifyHealth({
-          exists: fileExists, canonicalHash, diskHash, trackedHash
+          exists: fileExists, canonicalHash, diskHash, trackedHash, adoptedHash
         });
         findings.push({
           skillId, relativePath: file.relativePath, destinationPath,
           agentIds: [...group.agentIds], kind: group.kind,
           status: health.status, drift: health.drift, reason: health.reason,
-          canonicalHash, skillHash, diskHash, trackedHash
+          canonicalHash, skillHash, diskHash, trackedHash, adoptedHash
         });
       }
     }
@@ -66,13 +68,15 @@ export async function verifySddConfigure({
     || compareSkillPaths(a.relativePath, b.relativePath)
     || compareSkillPaths(a.destinationPath, b.destinationPath));
 
-  const summary = { configured: 0, missing: 0, drifted: 0, conflict: 0 };
+  const summary = { configured: 0, adopted: 0, missing: 0, drifted: 0, conflict: 0 };
   for (const entry of findings) summary[entry.status] += 1;
 
   const consumers = normalizePersonaAgentIds(personaAgentIds);
   const incompleteAgentIds = consumers.filter((id) => {
     const mine = findings.filter((e) => e.agentIds.includes(id));
-    return !mine.length || mine.some((e) => e.status !== SDD_HEALTH.CONFIGURED);
+    return !mine.length || mine.some((e) =>
+      e.status !== SDD_HEALTH.CONFIGURED && e.status !== SDD_HEALTH.ADOPTED
+    );
   });
   let gatePresent = true;
   for (const id of consumers) {
@@ -100,6 +104,7 @@ export function summarizeSddHealth(summary) {
   if (summary.conflict > 0) return SDD_HEALTH.CONFLICT;
   if (summary.missing > 0) return SDD_HEALTH.MISSING;
   if (summary.drifted > 0) return SDD_HEALTH.DRIFTED;
+  if ((summary.adopted ?? 0) > 0 && (summary.configured ?? 0) === 0) return SDD_HEALTH.ADOPTED;
   return SDD_HEALTH.CONFIGURED;
 }
 

package/src/global/mcp/kairo-mcp.js

@@ -12,10 +12,20 @@ import { runGraphifyOp } from "../observability/graphify-ops.js";
 import { resolveGitHeadSha } from "../observability/graphify-probe.js";
 import { runPassiveObservabilitySnapshot } from "../observability/passive-snapshot-flight.js";
 import { inspectEngramIntegration } from "../integrations/engram-evidence.js";
+import { buildFleetReport } from "../observability/fleet-probe.js";
+import {
+  createPublishWorkSnapshotHandler,
+  workSnapshotPublishSchema
+} from "./work-snapshot-tool.js";
+import { resolveMcpWorkspaceCwd } from "./resolve-mcp-workspace.js";
+
+/** Sole MCP write tool for companion snapshots. */
+export const KAIRO_MCP_WRITE_TOOLS = Object.freeze(["kairo_publish_work_snapshot"]);
 
 export const KAIRO_MCP_TOOLS = Object.freeze([
   "kairo_status", "kairo_runs", "kairo_alerts", "kairo_gentle_status",
-  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary"
+  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary", "kairo_fleet",
+  ...KAIRO_MCP_WRITE_TOOLS
 ]);
 
 const empty = z.object({});
@@ -30,7 +40,8 @@ export const mcpSchemas = Object.freeze({
     graph: z.string().min(1), question: z.string().min(1),
     budget: z.number().int().min(1).max(8000).default(2000)
   }),
-  graphPath: z.object({ graph: z.string().min(1), from: z.string().min(1), to: z.string().min(1) })
+  graphPath: z.object({ graph: z.string().min(1), from: z.string().min(1), to: z.string().min(1) }),
+  workSnapshotPublish: workSnapshotPublishSchema
 });
 
 const CODE_RE = /^(?:[a-z][a-z0-9_]{0,48}|status=\d+)$/;
@@ -94,7 +105,11 @@ function graphEnvelope(result) {
 
 export function createToolHandlers(deps = {}) {
   const homeDir = deps.homeDir ?? resolveHomeDir();
-  const cwd = deps.cwd ?? process.cwd();
+  // Cursor may spawn MCP under $HOME; prefer VSCODE_CWD / WORKSPACE_FOLDER_PATHS.
+  const cwd = resolveMcpWorkspaceCwd({
+    cwd: deps.cwd,
+    env: deps.env ?? process.env
+  });
   const listRuns = deps.listRuns ?? ((o) => listRunRecords(homeDir, o));
   const listAlertRows = deps.listAlerts ?? ((o) => listAlerts({ homeDir, ...o }));
   const listReviews = deps.listReviews ?? (() => listReviewReceipts({ homeDir, limit: 20 }));
@@ -117,6 +132,7 @@ export function createToolHandlers(deps = {}) {
     observabilityContext: { cwd, homeDir, workspaceRoot: cwd, headSha: requestHead() }
   }));
   const gentleProbe = deps.probeGentle ?? ((ctx) => probeGentle(ctx));
+  const fleetProbe = deps.buildFleet ?? ((ctx) => buildFleetReport(ctx));
   const graphOp = deps.runGraphifyOp ?? runGraphifyOp;
   const gOpts = () => ({
     cwd, workspaceRoot: cwd, headSha: requestHead(), whichCommand: deps.whichCommand,
@@ -200,7 +216,36 @@ export function createToolHandlers(deps = {}) {
       } catch {
         return soft("degraded", { signals: null, engram: null, links: [], alertsCount: null, nextSafeAction: null });
       }
-    }
+    },
+    async kairo_fleet() {
+      try {
+        const report = await fleetProbe({ homeDir });
+        return mcpResult({
+          ok: true,
+          code: "ok",
+          data: {
+            kind: report?.kind ?? "declared",
+            note: report?.note ?? null,
+            orchestratorAuthority: report?.orchestratorAuthority ?? null,
+            fleets: Array.isArray(report?.fleets) ? report.fleets : [],
+            activity: report?.activity ?? null,
+            generatedAt: report?.generatedAt ?? null
+          }
+        });
+      } catch {
+        return soft("degraded", {
+          kind: "declared", fleets: [], activity: null, note: null, orchestratorAuthority: null
+        });
+      }
+    },
+    kairo_publish_work_snapshot: createPublishWorkSnapshotHandler({
+      homeDir,
+      cwd,
+      now: deps.now,
+      writeAtomic: deps.writeAtomic,
+      publishWorkSnapshot: deps.publishWorkSnapshot,
+      mcpResult
+    })
   };
 }
 
@@ -213,7 +258,13 @@ export function registerKairoMcpTools(registerTool, deps = {}) {
     ["kairo_gentle_status", "Gentle probe / companion gentle signal", empty],
     ["kairo_graph_query", "Read-only Graphify query", mcpSchemas.graphQuery],
     ["kairo_graph_path", "Read-only Graphify path", mcpSchemas.graphPath],
-    ["kairo_context_summary", "Companion + soft links + alerts count", empty]
+    ["kairo_context_summary", "Companion + soft links + alerts count", empty],
+    ["kairo_fleet", "Declared fleet topology + OpenCode live activity", empty],
+    [
+      "kairo_publish_work_snapshot",
+      "Publish kairo.work-snapshot/v1 for the runtime workspace (enrolls conversation)",
+      mcpSchemas.workSnapshotPublish
+    ]
   ]) registerTool(name, { description, inputSchema }, h[name]);
   return h;
 }

package/src/global/mcp/resolve-mcp-workspace.js

@@ -0,0 +1,51 @@
+/**
+ * Resolve the workspace path for Kairo MCP identity.
+ *
+ * Cursor IDE launches global `mcpServers.kairo` with process cwd = $HOME even
+ * when the entry sets `cwd: "."`. It does inject the open folder via
+ * VSCODE_CWD / WORKSPACE_FOLDER_PATHS — prefer those over process.cwd().
+ */
+import { resolve } from "node:path";
+import { canonicalizeProjectPath } from "../next/project-key.js";
+
+function firstNonEmpty(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Parse Cursor/VS Code workspace folder env into an ordered path list.
+ * WORKSPACE_FOLDER_PATHS uses commas when Cursor opens multiple roots.
+ */
+export function parseWorkspaceFolderPaths(raw) {
+  const text = firstNonEmpty(raw);
+  if (!text) return [];
+  return text
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {{ cwd?: string, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {string} absolute workspace path
+ */
+export function resolveMcpWorkspaceCwd({
+  cwd,
+  env = process.env
+} = {}) {
+  let chosen;
+  if (typeof cwd === "string" && cwd.trim()) {
+    chosen = resolve(cwd.trim());
+  } else {
+    const fromFolders = parseWorkspaceFolderPaths(env.WORKSPACE_FOLDER_PATHS);
+    if (fromFolders.length > 0) {
+      chosen = resolve(fromFolders[0]);
+    } else {
+      const vscodeCwd = firstNonEmpty(env.VSCODE_CWD);
+      chosen = vscodeCwd ? resolve(vscodeCwd) : resolve(process.cwd());
+    }
+  }
+  return canonicalizeProjectPath(chosen);
+}

package/src/global/mcp/work-snapshot-rule.js

@@ -0,0 +1,89 @@
+/**
+ * Managed Cursor rule: instruct agents to publish kairo.work-snapshot/v1.
+ */
+import { mkdir, readFile, writeFile, rename, copyFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+export const WORK_SNAPSHOT_RULE_FILENAME = "kairo-work-snapshot.mdc";
+
+export function resolveCursorRulesDir(homeDir = homedir()) {
+  return join(homeDir, ".cursor", "rules");
+}
+
+export function resolveWorkSnapshotRulePath(homeDir = homedir()) {
+  return join(resolveCursorRulesDir(homeDir), WORK_SNAPSHOT_RULE_FILENAME);
+}
+
+export const WORK_SNAPSHOT_RULE_BODY = `# Kairo work snapshot
+
+After each significant turn, publish the true work state with MCP \`kairo_publish_work_snapshot\`:
+
+- Required: \`conversationId\`, \`provider\` (\`cursor\`), \`goal\`, \`now\`, \`next\`
+- Optional: \`progress\` (≤3), \`blockers\`, \`delegations\` (only real ones)
+- Workspace identity is derived by Kairo from the runtime — never send \`projectKey\`, paths, or \`cwd\`
+- Never invent work. Never send prompts, transcripts, or tool dumps
+- Reuse the same \`conversationId\` for later turns in this chat
+`;
+
+export function buildWorkSnapshotRuleFile() {
+  return `---
+description: Publish Kairo work snapshot after significant Cursor turns
+alwaysApply: true
+---
+
+${WORK_SNAPSHOT_RULE_BODY}
+`;
+}
+
+async function writeAtomicText(targetPath, text, deps = {}) {
+  const write = deps.writeFileFn ?? writeFile;
+  const renameFn = deps.renameFn ?? rename;
+  const tempPath = join(
+    dirname(targetPath),
+    `.${WORK_SNAPSHOT_RULE_FILENAME}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`
+  );
+  await write(tempPath, text, "utf8");
+  await renameFn(tempPath, targetPath);
+}
+
+/**
+ * Plan or apply the managed work-snapshot rule under ~/.cursor/rules/.
+ */
+export async function ensureWorkSnapshotRule({
+  homeDir = homedir(),
+  apply = false,
+  now = () => Date.now(),
+  readFileFn = readFile,
+  mkdirFn = mkdir,
+  copyFileFn = copyFile,
+  writeFileFn = writeFile,
+  renameFn = rename
+} = {}) {
+  const path = resolveWorkSnapshotRulePath(homeDir);
+  const desired = buildWorkSnapshotRuleFile();
+  let existing = null;
+  try {
+    existing = await readFileFn(path, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const wouldWrite = existing !== desired;
+  const backupPath = wouldWrite && existing != null
+    ? `${path}.kairo-backup.${now()}`
+    : null;
+
+  if (!apply) {
+    return { path, wouldWrite, wrote: false, backupPath: null };
+  }
+
+  await mkdirFn(dirname(path), { recursive: true });
+  if (wouldWrite && existing != null) {
+    await copyFileFn(path, backupPath);
+  }
+  if (wouldWrite) {
+    await writeAtomicText(path, desired, { writeFileFn, renameFn });
+  }
+  return { path, wouldWrite, wrote: wouldWrite, backupPath };
+}

package/src/global/mcp/work-snapshot-tool.js

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import { publishWorkSnapshot } from "../next/publish-work-snapshot.js";
+
+export const workSnapshotPublishSchema = z.object({
+  conversationId: z.string().min(1).max(160),
+  provider: z.enum(["cursor", "codex", "claude", "opencode", "pi", "other"]),
+  goal: z.string().min(1).max(160),
+  now: z.string().min(1).max(240),
+  next: z.string().min(1).max(240),
+  progress: z.array(z.string().max(160)).max(3).optional(),
+  blockers: z.array(z.string().max(200)).max(12).optional(),
+  delegations: z.array(z.object({
+    workId: z.string().max(64).optional(),
+    title: z.string().max(160).optional(),
+    role: z.enum(["orchestrator", "worker"]).optional(),
+    state: z.enum(["assigned", "working", "blocked", "completed", "failed"]).optional()
+  }).strict()).max(12).optional()
+}).strict();
+
+export function createPublishWorkSnapshotHandler(deps = {}) {
+  const publishSnapshot = deps.publishWorkSnapshot ?? ((input) => publishWorkSnapshot(input, {
+    homeDir: deps.homeDir,
+    cwd: deps.cwd,
+    now: deps.now,
+    writeAtomic: deps.writeAtomic
+  }));
+  const toResult = deps.mcpResult;
+  if (typeof toResult !== "function") {
+    throw new Error("mcpResult dependency is required");
+  }
+
+  return async function kairo_publish_work_snapshot(args = {}) {
+    try {
+      const result = await publishSnapshot(args);
+      return toResult({
+        ok: Boolean(result?.ok),
+        code: result?.code ?? "publish_failed",
+        data: result?.data ?? null,
+        diagnostics: result?.diagnostics ?? [],
+        isError: !result?.ok
+      });
+    } catch {
+      return toResult({
+        ok: false, code: "publish_failed", data: null,
+        diagnostics: ["publish_failed"], isError: true
+      });
+    }
+  };
+}

package/src/global/mcp-install.js

@@ -0,0 +1,239 @@
+/**
+ * Register Kairo as an MCP server in a client config (Cursor v1).
+ * Consent-gated: plan by default, --yes applies. Atomic write + backup.
+ */
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { writeAtomicJson } from "./runtime/write-atomic-json.js";
+import {
+  MCP_CLIENTS,
+  detectAgentMcpRegistration,
+  resolveMcpConfigPath
+} from "./connections.js";
+import { printJson } from "./json-output.js";
+import { commandHeader } from "./brand/index.js";
+import { formatCliCommand } from "./brand/cli.js";
+import {
+  buildWorkSnapshotRuleFile,
+  ensureWorkSnapshotRule,
+  resolveWorkSnapshotRulePath
+} from "./mcp/work-snapshot-rule.js";
+import { resolveHomeDir } from "./paths.js";
+
+/**
+ * Cursor MCP entry. `cwd: "."` is best-effort for clients that honor it.
+ * Cursor IDE 3.15+ may still spawn under $HOME — runtime identity then uses
+ * VSCODE_CWD / WORKSPACE_FOLDER_PATHS (see resolve-mcp-workspace.js).
+ */
+export const KAIRO_MCP_SERVER_ENTRY = Object.freeze({
+  command: "kairo",
+  args: Object.freeze(["mcp"]),
+  cwd: "."
+});
+
+export function buildKairoMcpServerEntry() {
+  return {
+    command: KAIRO_MCP_SERVER_ENTRY.command,
+    args: [...KAIRO_MCP_SERVER_ENTRY.args],
+    cwd: KAIRO_MCP_SERVER_ENTRY.cwd
+  };
+}
+
+function backupPath(configPath, stamp = Date.now()) {
+  return `${configPath}.kairo-backup.${stamp}`;
+}
+
+export function buildMcpInstallPlan({
+  client = "cursor",
+  homeDir = resolveHomeDir(),
+  existing = null,
+  alreadyConnected = false
+} = {}) {
+  const clientMeta = MCP_CLIENTS[client] ?? MCP_CLIENTS.cursor;
+  const path = resolveMcpConfigPath(client, { homeDir });
+  const entry = buildKairoMcpServerEntry();
+  const next = {
+    ...(existing && typeof existing === "object" ? existing : {}),
+    mcpServers: {
+      ...((existing && typeof existing === "object" && existing.mcpServers) || {}),
+      kairo: entry
+    }
+  };
+  return {
+    client: clientMeta.id,
+    clientLabel: clientMeta.label,
+    path,
+    alreadyConnected,
+    wouldWrite: !alreadyConnected || JSON.stringify(existing?.mcpServers?.kairo)
+      !== JSON.stringify(next.mcpServers.kairo),
+    entry: next.mcpServers.kairo,
+    next,
+    backupPath: backupPath(path),
+    rulePath: resolveWorkSnapshotRulePath(homeDir),
+    ruleBody: buildWorkSnapshotRuleFile(),
+    note: alreadyConnected
+      ? "Kairo MCP already registered; --yes rewrites the entry if it drifted."
+      : `Will add mcpServers.kairo to ${path}. Reload Cursor MCP after apply.`
+  };
+}
+
+async function readExistingConfig(path, readFileFn) {
+  try {
+    const raw = await readFileFn(path, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Plan (default) or apply (--yes) Cursor MCP registration for Kairo.
+ */
+export async function runMcpInstall({
+  client = "cursor",
+  yes = false,
+  json = false,
+  homeDir = resolveHomeDir(),
+  readFileFn = readFile,
+  mkdirFn = mkdir,
+  copyFileFn = copyFile,
+  writeAtomicJsonFn = writeAtomicJson,
+  writeFileFn = null,
+  renameFn = null,
+  ensureRule = ensureWorkSnapshotRule,
+  detectAgent = detectAgentMcpRegistration,
+  now = () => Date.now()
+} = {}) {
+  if (client !== "cursor") {
+    throw new Error(
+      `Unsupported MCP client "${client}". v1 supports --client=cursor only.`
+    );
+  }
+
+  const detection = await detectAgent({ client, homeDir, readFileFn });
+  const path = detection.path ?? resolveMcpConfigPath(client, { homeDir });
+  const existing = await readExistingConfig(path, readFileFn);
+  const plan = buildMcpInstallPlan({
+    client,
+    homeDir,
+    existing,
+    alreadyConnected: detection.connected === true
+  });
+  plan.backupPath = backupPath(path, now());
+  const rulePlan = await ensureRule({
+    homeDir,
+    apply: false,
+    now,
+    readFileFn,
+    mkdirFn,
+    copyFileFn,
+    writeFileFn: writeFileFn ?? undefined,
+    renameFn: renameFn ?? undefined
+  });
+  plan.ruleWouldWrite = rulePlan.wouldWrite === true;
+  plan.rulePath = rulePlan.path;
+
+  if (!yes) {
+    const payload = {
+      ok: true,
+      applied: false,
+      plan: {
+        path: plan.path,
+        client: plan.client,
+        alreadyConnected: plan.alreadyConnected,
+        wouldWrite: plan.wouldWrite,
+        entry: plan.entry,
+        rulePath: plan.rulePath,
+        ruleWouldWrite: plan.ruleWouldWrite,
+        note: plan.note,
+        applyWith: formatCliCommand("mcp install --yes")
+      }
+    };
+    if (json) {
+      printJson(payload);
+    } else {
+      console.log(commandHeader("MCP install"));
+      console.log(`Client · ${plan.clientLabel}`);
+      console.log(`Path · ${plan.path}`);
+      console.log(`Entry · ${JSON.stringify(plan.entry)}`);
+      console.log(`Rule · ${plan.rulePath}${plan.ruleWouldWrite ? " (will write)" : " (up to date)"}`);
+      console.log(plan.note);
+      console.log(`Apply · ${formatCliCommand("mcp install --yes")}`);
+    }
+    return payload;
+  }
+
+  await mkdirFn(dirname(path), { recursive: true });
+  if (existing != null && plan.wouldWrite) {
+    await copyFileFn(path, plan.backupPath);
+  }
+  if (plan.wouldWrite) {
+    await writeAtomicJsonFn(path, plan.next);
+  }
+
+  const ruleReceipt = await ensureRule({
+    homeDir,
+    apply: true,
+    now,
+    readFileFn,
+    mkdirFn,
+    copyFileFn,
+    writeFileFn: writeFileFn ?? undefined,
+    renameFn: renameFn ?? undefined
+  });
+
+  const receipt = {
+    ok: true,
+    applied: true,
+    path,
+    backupPath: existing != null && plan.wouldWrite ? plan.backupPath : null,
+    entry: plan.entry,
+    client: plan.client,
+    rulePath: ruleReceipt.path,
+    ruleWrote: ruleReceipt.wrote === true,
+    ruleBackupPath: ruleReceipt.backupPath,
+    note: "Reload Cursor MCP (Command Palette → MCP: Restart) to load kairo_* tools."
+  };
+
+  if (json) {
+    printJson(receipt);
+  } else {
+    console.log(commandHeader("MCP install"));
+    if (plan.wouldWrite) console.log(`Wrote · ${path}`);
+    else console.log(`MCP · up to date (${path})`);
+    if (receipt.backupPath) console.log(`Backup · ${receipt.backupPath}`);
+    console.log(`Rule · ${receipt.rulePath}${receipt.ruleWrote ? " (wrote)" : " (up to date)"}`);
+    if (receipt.ruleBackupPath) console.log(`Rule backup · ${receipt.ruleBackupPath}`);
+    console.log(receipt.note);
+  }
+  return receipt;
+}
+
+export function resolveMcpServeCwd(options = {}) {
+  return options.cwdExplicit === false ? undefined : options.cwd;
+}
+
+export async function runMcpCli(options = {}) {
+  const action = options.mcpAction ?? "serve";
+  if (action === "install") {
+    return runMcpInstall({
+      client: options.mcpClient ?? "cursor",
+      yes: options.yes === true,
+      json: options.json === true,
+      homeDir: options.homeDir ?? resolveHomeDir()
+    });
+  }
+  if (action === "serve" || action == null) {
+    const { runKairoMcp } = await import("./mcp/kairo-mcp.js");
+    return runKairoMcp({
+      cwd: resolveMcpServeCwd(options),
+      packageRoot: options.packageRoot,
+      packageName: options.packageName,
+      version: options.version
+    });
+  }
+  throw new Error(
+    `Unknown mcp action "${action}". Use: ${formatCliCommand("mcp")} or ${formatCliCommand("mcp install [--yes]")}`
+  );
+}