@lh8ppl/claude-memory-kit 0.2.1 → 0.2.3

package/src/read-core.mjs

@@ -0,0 +1,87 @@
+// Shared read cores (Task 108b / ADR-0014).
+//
+// The query logic behind the MCP read tools (mk_get / mk_timeline / mk_cite /
+// mk_recent_activity), extracted so the CLI read verbs (cmk get / timeline /
+// cite / recent-activity) call the SAME logic — identical results from both
+// surfaces, one implementation. Pure (db + args in, plain data out); the MCP
+// adapter wraps the result in a content envelope, the CLI adapter prints it.
+
+import { ID_PATTERN } from './tier-paths.mjs';
+
+const GET_COLUMNS =
+  'id, body, heading_path, source_file, source_line, tier, trust, ' +
+  'write_source, created_at, superseded_by, deleted_at';
+
+/**
+ * Fetch full observation rows by id. An invalid-format or missing id becomes
+ * a `{ id, error }` entry (the array stays positionally aligned with `ids`).
+ */
+export function getObservations(db, ids) {
+  const stmt = db.prepare(`SELECT ${GET_COLUMNS} FROM observations WHERE id = ?`);
+  return ids.map((id) => {
+    if (!ID_PATTERN.test(id)) return { id, error: 'invalid id format' };
+    const row = stmt.get(id);
+    if (!row) return { id, error: 'not found' };
+    return row;
+  });
+}
+
+/** The canonical Markdown citation link for an id. Pure (no DB). */
+export function citeLink(id) {
+  if (!ID_PATTERN.test(id)) return { ok: false, error: 'id must match ID_PATTERN' };
+  return { ok: true, link: `[#${id}](memkit://obs/${id})` };
+}
+
+const TIMELINE_COLUMNS = 'id, body, source_file, source_line, tier, trust, created_at';
+
+/**
+ * Sequential context: N observations before the anchor + the anchor + N after,
+ * by created_at (id as the tiebreaker so same-millisecond rows stay
+ * deterministic). Returns `{ ok:false, error }` for a bad / missing anchor.
+ */
+export function buildTimeline(db, { anchor, depthBefore = 5, depthAfter = 5 } = {}) {
+  if (!ID_PATTERN.test(anchor)) return { ok: false, error: 'anchor must be a valid kit ID' };
+  const anchorRow = db
+    .prepare('SELECT created_at, tier FROM observations WHERE id = ?')
+    .get(anchor);
+  if (!anchorRow) return { ok: false, error: 'anchor not found' };
+  const beforeRows = db
+    .prepare(`
+      SELECT ${TIMELINE_COLUMNS} FROM observations
+      WHERE created_at < ? AND deleted_at IS NULL
+      ORDER BY created_at DESC, id DESC LIMIT ?
+    `)
+    .all(anchorRow.created_at, depthBefore);
+  const anchorFull = db
+    .prepare(`SELECT ${TIMELINE_COLUMNS} FROM observations WHERE id = ?`)
+    .get(anchor);
+  const afterRows = db
+    .prepare(`
+      SELECT ${TIMELINE_COLUMNS} FROM observations
+      WHERE created_at > ? AND deleted_at IS NULL
+      ORDER BY created_at ASC, id ASC LIMIT ?
+    `)
+    .all(anchorRow.created_at, depthAfter);
+  return { ok: true, timeline: [...beforeRows.reverse(), anchorFull, ...afterRows] };
+}
+
+export const RECENT_WINDOWS = Object.freeze({
+  '1h': 60 * 60 * 1000,
+  '24h': 24 * 60 * 60 * 1000,
+  '7d': 7 * 24 * 60 * 60 * 1000,
+});
+
+/** Observations changed within a time window, newest first. */
+export function recentActivity(db, { window = '24h', limit = 20 } = {}) {
+  if (!RECENT_WINDOWS[window]) return { ok: false, error: 'window must be 1h|24h|7d' };
+  const cutoff = Date.now() - RECENT_WINDOWS[window];
+  const rows = db
+    .prepare(`
+      SELECT id, body, source_file, source_line, tier, trust, created_at
+      FROM observations
+      WHERE created_at >= ? AND deleted_at IS NULL
+      ORDER BY created_at DESC LIMIT ?
+    `)
+    .all(cutoff, limit);
+  return { ok: true, rows };
+}

package/src/register-crons.mjs

@@ -74,7 +74,18 @@ function macOsPlistPath(entryName) {
 function buildMacOsPlist({ command, entryName, hour, minute, dayOfWeek }) {
   // Split command on whitespace for the ProgramArguments array.
   // launchd doesn't honor shell quoting — each arg is its own element.
-  const args = command.split(/\s+/).filter(Boolean);
+  // Strip the surrounding double-quotes the caller wraps each path in (the
+  // command is `"<node>" "<script>" "<projectRoot>"`): launchd execs the arg
+  // LITERALLY, so a `<string>"/path/node"</string>` with quotes baked in is a
+  // path that starts with `"` → ENOENT (Task 109: the macOS sibling of the
+  // Windows D-83 bug). Each split token is one quoted path; drop the wrapping
+  // quotes to get the clean path. (A path that itself contains a space is the
+  // remaining edge — rare for node/project paths — and needs the argv-array
+  // refactor noted in the Task 109 follow-up.)
+  const args = command
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((a) => a.replace(/^"(.*)"$/, '$1'));
   const argXml = args
     .map((a) => `    <string>${escapeXml(a)}</string>`)
     .join('\n');
@@ -116,34 +127,35 @@ function escapeXml(s) {
     .replace(/'/g, '&apos;');
 }
 
-function buildWindowsSchtasks({ command, entryName, hour, minute, dayOfWeek }) {
-  // schtasks accepts /ST as HH:mm. /F forces re-create if the task
-  // already exists (idempotency primitive). /RL LIMITED (not HIGHEST)
-  // because daily distill doesn't need admin.
+export function buildWindowsSchtasks({ command, entryName, hour, minute, dayOfWeek }) {
+  // Returns the schtasks.exe ARGV ARRAY (not a shell string). The /TR value — the
+  // command to run, `"<node>" "<script>" "<projectRoot>"` with its own quotes
+  // around each spaced path — is ONE array element, delivered to schtasks.exe
+  // verbatim via CreateProcess (Node's Windows arg-quoting), with NO cmd.exe
+  // re-parse at registration time.
+  //
+  // This is the D-83 fix. The old `/TR "${command}"` shell-string form double-
+  // wrapped the inner quotes (schtasks AND cmd.exe both tried to parse them) and
+  // the registerCron guard then rejected the inner `"` outright — so cron could
+  // NEVER register on Windows. Array-exec sidesteps the nesting entirely: Task
+  // Scheduler stores the /TR value and cmd.exe parses the quoted paths only when
+  // the task FIRES. (No `\"`-escaping needed → no CodeQL js/incomplete-
+  // sanitization, no path-corrupting backslash-doubling.)
+  //
+  // /ST is HH:mm; /F forces re-create for idempotency; /RL LIMITED (not HIGHEST)
+  // because distill needs no admin. Task 34: /SC WEEKLY /D <SUN|...> for weekly.
   const time = `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
-  // The command is wrapped in `/TR "${command}"`. cmd.exe/schtasks treats
-  // backslash as a PATH separator, not an escape character, so the only
-  // char that can break out of the quotes is a literal `"` — and that is
-  // rejected at the registerCron boundary (see the validation below), the
-  // same way an embedded `'` is rejected for the Linux cron line. So no
-  // escaping is applied here. (The earlier `command.replace(/"/g, '\\"')`
-  // was both unnecessary — controlled bin-name+path commands never contain
-  // `"` — and CodeQL-flagged js/incomplete-sanitization, since it didn't
-  // escape backslashes; but `\"`/`\\` is not how cmd.exe quotes anyway, and
-  // doubling backslashes would corrupt Windows paths. Reject-at-boundary is
-  // the correct, safe contract.)
-  // Task 34: /SC WEEKLY /D <SUN|MON|...> for weekly cadence; /SC DAILY otherwise.
-  let scheduleFlags;
+  let scheduleArgs;
   if (dayOfWeek !== undefined && dayOfWeek !== null) {
     const day = WIN_DAY_MAP[dayOfWeek];
     if (!day) {
       throw new Error(`buildWindowsSchtasks: invalid dayOfWeek ${dayOfWeek}`);
     }
-    scheduleFlags = `/SC WEEKLY /D ${day}`;
+    scheduleArgs = ['/SC', 'WEEKLY', '/D', day];
   } else {
-    scheduleFlags = '/SC DAILY';
+    scheduleArgs = ['/SC', 'DAILY'];
   }
-  return `schtasks /Create /TN "${entryName}" ${scheduleFlags} /ST ${time} /TR "${command}" /RL LIMITED /F`;
+  return ['/Create', '/TN', entryName, ...scheduleArgs, '/ST', time, '/TR', command, '/RL', 'LIMITED', '/F'];
 }
 
 /**
@@ -169,12 +181,16 @@ export function registerCron(opts = {}) {
     // cron command needs to either escape POSIX-style ('\'') or
     // we extend this helper with a sanitizer (v0.1.x candidate).
     errors.push("command: must not contain single quotes (Linux cron-line shell-quoting contract)");
-  } else if (opts.command.includes('"')) {
-    // Windows schtasks /TR wraps the command in double-quotes; an embedded
-    // `"` would break out of the quoting. Reject at the boundary (cmd.exe
-    // has no usable in-quote escape for `"`), mirroring the `'` contract.
-    errors.push('command: must not contain double quotes (Windows schtasks /TR quoting contract)');
   }
+  // NOTE (Task 109 / D-83): there is deliberately NO double-quote rejection. The
+  // Windows command legitimately CONTAINS double-quotes — it's the quoted path
+  // triple `"<node>" "<script>" "<projectRoot>"` (Task 36 B1/B2). The earlier
+  // guard rejected `"` because the old `/TR "${command}"` SHELL form double-
+  // wrapped them; that made cron un-registerable on Windows (the whole D-83 bug).
+  // The win32 branch now execs schtasks with an ARGS ARRAY (no shell), so the
+  // /TR value is delivered verbatim and the inner quotes never need escaping.
+  // macOS XML-escapes them in the plist; Linux nests them inside its single-quote
+  // `echo '...'` — so `"` is safe on every platform.
   const entryName = opts.entryName ?? CRON_ENTRY_NAME;
   if (!entryName || typeof entryName !== 'string' || !/^[a-zA-Z0-9_.-]+$/.test(entryName)) {
     errors.push("entryName: must match /^[a-zA-Z0-9_.-]+$/ (used in shell + plist + schtasks identifiers)");
@@ -199,7 +215,9 @@ export function registerCron(opts = {}) {
     return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
   }
 
-  const platform = detectPlatform();
+  // opts.platform is a test seam (detectPlatform() reads process.platform, which
+  // can't vary on a single CI host) — production never passes it.
+  const platform = opts.platform ?? detectPlatform();
   const dryRun = opts.dryRun === true;
 
   if (platform === 'linux') {
@@ -259,24 +277,37 @@ export function registerCron(opts = {}) {
   }
 
   if (platform === 'win32') {
-    const cmd = buildWindowsSchtasks({ command: opts.command, entryName, hour, minute, dayOfWeek });
+    const argv = buildWindowsSchtasks({ command: opts.command, entryName, hour, minute, dayOfWeek });
+    const displayCmd = `schtasks ${argv.join(' ')}`; // informational (dry-run + result.command)
     if (dryRun) {
       return {
         action: 'dry-run',
         platform,
         executed: false,
-        command: cmd,
+        command: displayCmd,
         output: '',
       };
     }
-    // schtasks is a .exe; spawnSync handles it directly via shell:true
-    // (per the kit's Windows .cmd shim pattern in compressor.mjs).
-    const r = spawnSync(cmd, { shell: true, encoding: 'utf8', windowsHide: true, timeout: 10_000 });
+    // Exec schtasks.exe with the ARGS ARRAY — NOT shell:true. This delivers the
+    // /TR value's inner quotes to schtasks verbatim (CreateProcess arg-quoting),
+    // never re-parsed by cmd.exe at registration time (the D-83 fix). Task
+    // Scheduler stores the command; cmd.exe parses the quoted paths at fire time.
+    // Resolve the ABSOLUTE System32 path rather than relying on PATH: schtasks
+    // creates a scheduled task, so a PATH-hijacked `schtasks.exe` in a writable
+    // dir would be a privilege-escalation vector (Sonar S4036). %SystemRoot% is
+    // a fixed, unwriteable system directory.
+    const schtasksExe = join(process.env.SystemRoot || process.env.windir || 'C:\\Windows', 'System32', 'schtasks.exe');
+    // opts.spawn is a test seam (defaults to spawnSync): the real schtasks exec
+    // can't run on a non-Windows CI host, so a fake lets the exec branch be
+    // covered in-process AND asserts WHAT gets spawned (Door 3: the absolute
+    // schtasks path + the verbatim argv). Production never passes it.
+    const spawn = opts.spawn ?? spawnSync;
+    const r = spawn(schtasksExe, argv, { encoding: 'utf8', windowsHide: true, timeout: 10_000 });
     return {
       action: r.status === 0 ? 'registered' : 'error',
       platform,
       executed: true,
-      command: cmd,
+      command: displayCmd,
       output: (r.stdout || '') + (r.stderr || ''),
       ...(r.status === 0 ? {} : { error: `schtasks exit ${r.status}` }),
     };

package/src/remember-core.mjs

@@ -0,0 +1,91 @@
+// Shared rich-capture core (Task 108b / ADR-0014).
+//
+// `rememberRich` writes a granular Why/How fact file via writeFact(). BOTH
+// surfaces call it so they produce byte-identical fact files with one
+// implementation of the contract:
+//   - CLI  — subcommands.runRememberRich (re-exports this) ← `cmk remember --why/--how` + `--from-file`
+//   - MCP  — mcp-server.makeMkRemember rich path           ← `mk_remember` with why/how/title/type
+//
+// It lives in its own module (not subcommands.mjs) because subcommands.mjs
+// imports runMcpServer from mcp-server.mjs — so mcp-server importing the core
+// back from subcommands would be a circular dependency. The core depends only
+// on the write/format primitives, never on either front-end.
+//
+// Logging is the CALLER's concern: this returns the writeFact result and the
+// CLI/MCP adapter formats its own message (the CLI's "saved rich fact" line vs
+// the MCP's JSON envelope) — so stdout-purity on the MCP path is the adapter's
+// to keep (design §10.1), not the core's.
+
+import { resolve as resolvePath } from 'node:path';
+import { createHash } from 'node:crypto';
+import { writeFact as defaultWriteFact } from './write-fact.mjs';
+import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
+
+/**
+ * The note shown when a non-project tier (U/L) is requested on a capture. Both
+ * `cmk remember` and `mk_remember` write the PROJECT tier (P) regardless of the
+ * requested tier; a fact becomes cross-project via lessons-promote, not a direct
+ * tier write (direct U/L routing is the deferred feature in design §16.40). This is the ONE
+ * source of truth for that note across all three adapter paths (CLI terse, CLI
+ * rich, MCP) — Task 108 unified the write core but the tier message had drifted
+ * into three divergent, independently-stale copies (D-102). Centralizing it here
+ * means it can't drift again.
+ */
+export function nonProjectTierNote(tier) {
+  return (
+    `tier '${tier}' is not a direct write target — captured to the project tier (P). ` +
+    'To make it cross-project, promote it (`cmk lessons promote <id>` / the `mk_lessons_promote` tool).'
+  );
+}
+
+/**
+ * Write a rich Why/How fact file. Pure (no console logging) — returns the
+ * writeFact result so the caller can format its own message / envelope.
+ *
+ * @param {string} text - the fact headline.
+ * @param {object} [options] - { why, how, type, title, links, trust }. (tier is
+ *   not honored here — rich capture writes the project tier P; the CLI/MCP
+ *   adapters surface the non-project-tier note before/around calling.)
+ * @param {object} [deps] - { projectRoot, writeFact } injection seams for tests.
+ * @returns the writeFact result: { action:'created'|'skipped'|'error', id?, path?, errorCategory?, errors?, skipReason? }
+ */
+export function rememberRich(text, options = {}, deps = {}) {
+  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
+  const write = deps.writeFact ?? defaultWriteFact;
+
+  const headline = String(text).trim();
+  const title = (options.title && String(options.title).trim()) || headline.split('\n')[0].slice(0, 80);
+  const body = buildRichFactBody({ text: headline, why: options.why, how: options.how });
+  // `links` arrives as an ARRAY from the MCP tool (z.array) and as a
+  // comma-STRING from the CLI flag — accept both. The old `String(links)` path
+  // coerced an array via toString (works only until a link contains a comma);
+  // handle the array explicitly (D-102 / 121.6).
+  const related = Array.isArray(options.links)
+    ? options.links.map((s) => String(s).trim()).filter(Boolean)
+    : options.links
+      ? String(options.links).split(',').map((s) => s.trim()).filter(Boolean)
+      : undefined;
+
+  return write({
+    tier: 'P',
+    type: options.type ?? 'feedback',
+    slug: slugifyFact(title),
+    title,
+    body,
+    writeSource: 'user-explicit',
+    trust: options.trust ?? 'high',
+    sourceFile: 'user-explicit',
+    sourceLine: 1,
+    // Content fingerprint for provenance/dedup — NOT a security context. Matches
+    // the kit's sha1-of-content convention (memory-write.mjs, index-rebuild.mjs);
+    // writeFact dedups by content-addressed id, this is the source_sha1 field. // NOSONAR
+    sourceSha1: createHash('sha1').update(body).digest('hex'), // NOSONAR
+    related,
+    projectRoot,
+  });
+}
+
+/** The title rememberRich() will derive for `text`/`options` (for caller messages). */
+export function richFactTitle(text, options = {}) {
+  return (options.title && String(options.title).trim()) || String(text).trim().split('\n')[0].slice(0, 80);
+}

package/src/review-queue.mjs

@@ -209,6 +209,19 @@ function serializeReviewQueue({ preamble, entries }) {
 // works because Active Threads is where transient observations
 // belong by convention; the user can promote into a different
 // section by editing MEMORY.md after promotion.
+/**
+ * Pure-read list of pending review-queue entries (no mutation). Used by the MCP
+ * `mk_queue_list` tool so a "list" never rewrites the queue file — unlike
+ * resolveReviewQueue, which reserializes on every call. Returns `[]` when the
+ * queue file doesn't exist.
+ */
+export function listReviewQueue({ tier = 'P', projectRoot, userDir } = {}) {
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const queuePath = join(tierRoot, ...QUEUE_RELATIVE);
+  if (!existsSync(queuePath)) return [];
+  return parseReviewQueue(readFileSync(queuePath, 'utf8')).entries;
+}
+
 export async function resolveReviewQueue({
   tier,
   projectRoot,

package/src/rich-fact.mjs

@@ -0,0 +1,46 @@
+// Rich-fact body + slug shaping — the single source of truth for HOW a rich
+// fact's file body and filename slug are built (Task 103).
+//
+// Extracted from subcommands.mjs so the TWO rich-capture paths build identical
+// fact files (the shared-modules / no-drift rule, CLAUDE.md §1.3):
+//   1. explicit  — `cmk remember --why/--how` → runRememberRich (subcommands.mjs)
+//   2. automatic — the Stop-hook auto-extract synthesizing rich facts on the
+//                  native-immune path (auto-extract.mjs, Task 103)
+// Both call writeFact() with a body produced here, so an auto-extracted fact
+// reads the same as an explicitly-captured one.
+
+/**
+ * Build a slug for a rich fact's filename from its title.
+ *
+ * Collapse every run of non-alphanumerics to a single '-' (so dashes are never
+ * doubled), cap at 60 chars, then trim a leading/trailing dash without a regex
+ * quantifier (static analysis flags trailing `-+$` as ReDoS-prone; a single
+ * dash is all that can remain after the collapse, so string ops suffice).
+ *
+ * @param {string} s - the source text (typically the fact title).
+ * @returns {string} a `[a-z0-9][a-z0-9_-]*`-safe slug, or 'fact' if empty.
+ */
+export function slugifyFact(s) {
+  let base = String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 60);
+  if (base.startsWith('-')) base = base.slice(1);
+  if (base.endsWith('-')) base = base.slice(0, -1);
+  return base || 'fact';
+}
+
+/**
+ * Assemble the rich fact body in the v0.1.1 shape: headline + Why + How.
+ * The headline/body may itself be multi-line markdown (a structured breakdown);
+ * Why/How are appended as labelled blocks only when present.
+ *
+ * @param {object} opts
+ * @param {string} opts.text - the headline / body (may be multi-line markdown).
+ * @param {string} [opts.why] - the rationale → `**Why:**` block.
+ * @param {string} [opts.how] - how to apply → `**How to apply:**` block.
+ * @returns {string} the assembled markdown body for writeFact().
+ */
+export function buildRichFactBody({ text, why, how }) {
+  const parts = [String(text).trim()];
+  if (why && String(why).trim()) parts.push(`**Why:** ${String(why).trim()}`);
+  if (how && String(how).trim()) parts.push(`**How to apply:** ${String(how).trim()}`);
+  return parts.join('\n\n');
+}

package/src/settings-hooks.mjs

@@ -56,7 +56,7 @@ import {
   readFileSync,
   writeFileSync,
 } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 
 /**
  * Canonical npm-route hooks block. Shell form (no `args`), PATH-resolved
@@ -191,7 +191,17 @@ export function writeKitHooks(settingsPath) {
   //     returned one layer up once capture moved into the skill.
   // Idempotent + over-mutation safe: preserve the user's existing allow entries;
   // only append ours if absent.
-  const KIT_ALLOW = ['Bash(cmk:*)', 'Skill(memory-write)'];
+  //   - `mcp__cmk__*` (Task 108b, R2 / D-80) — allow-lists the kit's MCP tools
+  //     (mk_remember / mk_forget / mk_trust / …) so the model's memory ops run
+  //     without a per-call approval prompt. This is the structural fix for the
+  //     `cd`-compound bash-permission edge (D-80): the permissions doc confirms
+  //     "Combining `cd` with `git` in one compound command always prompts" — and
+  //     a `Bash(cmk:*)` rule can't cover a `cd … && cmk …` compound. Running the
+  //     SAME memory op as an allow-listed MCP tool sidesteps the bash gate
+  //     entirely. `mcp__cmk__*` is the documented server-wildcard form
+  //     (code.claude.com/docs/en/permissions — MCP section). Pairs with the
+  //     `.mcp.json` server registration written by writeKitMcpServer().
+  const KIT_ALLOW = ['Bash(cmk:*)', 'Skill(memory-write)', 'mcp__cmk__*'];
   if (!settings.permissions || typeof settings.permissions !== 'object') {
     settings.permissions = {};
   }
@@ -214,3 +224,47 @@ export function writeKitHooks(settingsPath) {
 
   return { changed, settingsPath, events };
 }
+
+/**
+ * Read-merge-write the kit's MCP server registration into
+ * `<projectRoot>/.mcp.json` — the project-scoped, committed MCP config
+ * (code.claude.com/docs/en/mcp). This makes the kit's memory tools
+ * (mk_remember / mk_forget / mk_trust / mk_queue_* / …) available to the model
+ * in conversation, so the user never has to run `cmk` themselves (D-85). Pairs
+ * with the `mcp__cmk__*` allow rule writeKitHooks() adds (Task 108b, R2 / D-80).
+ *
+ * The server runs `cmk mcp serve` (PATH-resolved bare bin, matching the hooks);
+ * `cmk mcp serve` resolves the project root from CLAUDE_PROJECT_DIR (which Claude
+ * Code sets in the spawned server's environment) so it indexes the right project.
+ *
+ * Idempotent + non-destructive: preserves any OTHER `mcpServers` the user
+ * registered; only (re)writes the `cmk` entry. On a JSON parse error of an
+ * existing `.mcp.json`, returns `{changed:false, error}` (never clobbers).
+ */
+export function writeKitMcpServer(projectRoot) {
+  const mcpPath = join(projectRoot, '.mcp.json');
+
+  let config = {};
+  if (existsSync(mcpPath)) {
+    try {
+      config = JSON.parse(readFileSync(mcpPath, 'utf8'));
+    } catch (err) {
+      return { changed: false, path: mcpPath, error: `${mcpPath} parse error: ${err?.message ?? err}` };
+    }
+  }
+
+  const before = JSON.stringify(config);
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+    config.mcpServers = {};
+  }
+  config.mcpServers.cmk = { type: 'stdio', command: 'cmk', args: ['mcp', 'serve'] };
+  const after = JSON.stringify(config);
+  const changed = before !== after;
+
+  if (changed) {
+    mkdirSync(dirname(mcpPath), { recursive: true });
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  }
+
+  return { changed, path: mcpPath };
+}