@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/lib/clients/common.mjs

@@ -1,5 +1,16 @@
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, symlinkSync, cpSync, lstatSync, unlinkSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  symlinkSync,
+  cpSync,
+  lstatSync,
+  statSync,
+  unlinkSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -98,14 +109,94 @@ export function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+// statSync error codes that mean a symlink is broken — its target cannot be
+// resolved to a real inode. We deliberately do NOT include EACCES / EPERM:
+// those mean "target may exist but I can't see it", and silently removing
+// someone else's link based on a permission failure is unsafe.
+const BROKEN_SYMLINK_STAT_CODES = new Set([
+  "ENOENT", // target does not exist (the textbook "dangling symlink")
+  "ENOTDIR", // a non-directory component appears mid-path (e.g. link -> file/child)
+  "ELOOP", // too many redirections (cyclic symlinks)
+]);
+
+/**
+ * True when `targetPath` is a symlink whose target cannot be resolved. A
+ * regular file/dir or a working symlink returns false; a missing path also
+ * returns false. See `BROKEN_SYMLINK_STAT_CODES` for which resolution
+ * failures count.
+ *
+ * Why this matters: `existsSync` returns false for a broken symlink, so a
+ * naive `if (existsSync(dest)) {...}` branch falls through and tries to write
+ * over the symlink. On macOS, `cpSync` then aborts the entire process via an
+ * uncaught libc++ `filesystem_error` ("Operation not supported" inside
+ * `std::filesystem::equivalent`) whenever one operand is a broken symlink —
+ * not just the ENOENT case but also ENOTDIR (`link -> file/child`) and ELOOP.
+ * Detecting any of these lets callers either treat the path as an existing
+ * entry or clear it before writing.
+ *
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isDanglingSymlink(targetPath) {
+  let stat;
+  try {
+    stat = lstatSync(targetPath);
+  } catch {
+    return false;
+  }
+  if (!stat.isSymbolicLink()) return false;
+  try {
+    statSync(targetPath);
+    return false;
+  } catch (err) {
+    return BROKEN_SYMLINK_STAT_CODES.has(err.code);
+  }
+}
+
+/**
+ * Unlink that tolerates the narrow race window where another process
+ * already removed `targetPath` between our check and our write (ENOENT)
+ * but propagates every other failure (EACCES, EPERM, EBUSY, etc.) as a
+ * normal JS error.
+ *
+ * Why not `removePath`: that helper swallows ALL errors, which is fine
+ * for cleanup paths but dangerous in front of `cpSync`. If unlink truly
+ * fails (e.g. read-only parent dir), the broken symlink is still on
+ * disk; cpSync would then dive into the macOS libc++ `filesystem_error`
+ * abort path described in `isDanglingSymlink`. Surfacing the unlink
+ * error here lets the surrounding installer surface a clean error
+ * instead of aborting the process.
+ *
+ * @param {string} targetPath
+ */
+function unlinkAllowingMissing(targetPath) {
+  try {
+    unlinkSync(targetPath);
+  } catch (err) {
+    if (err && err.code === "ENOENT") return;
+    throw err;
+  }
+}
+
 /**
  * Create symlink when possible; fallback to copy.
+ *
+ * Pre-clears a broken symlink at `destination` so the copy fallback path
+ * doesn't crash. See `isDanglingSymlink` above for the macOS libc++ trap.
+ * Uses `unlinkAllowingMissing` rather than `removePath` so an unlink
+ * failure (e.g. read-only parent dir) surfaces as a normal JS error
+ * instead of silently leaving the broken link in place — otherwise
+ * `cpSync` below would still abort the process.
+ *
  * @param {string} source
  * @param {string} destination
  * @returns {"symlink"|"copy"}
  */
 export function symlinkOrCopy(source, destination) {
   mkdirSync(dirname(destination), { recursive: true });
+  if (isDanglingSymlink(destination)) {
+    unlinkAllowingMissing(destination);
+  }
   try {
     symlinkSync(source, destination, "junction");
     return "symlink";
@@ -131,3 +222,134 @@ export function removePath(targetPath) {
     // no-op
   }
 }
+
+// ---------------------------------------------------------------------------
+// Installer version markers
+// ---------------------------------------------------------------------------
+//
+// Each artifact the installer owns (a deployed skill dir, a built .skill
+// bundle, the Claude Code meko-capture dir, etc.) gets a `.meko-installer`
+// marker file stamped with the installer's version. On re-run we compare the
+// marker's version against the current installer to decide whether we need
+// to force-refresh a managed artifact. Without a marker the artifact is
+// treated as user-managed and left alone — we never clobber a dir we didn't
+// produce ourselves.
+//
+// The marker format is deliberately plain text, one `key=value` per line,
+// so a human inspecting it with `cat` can immediately see what produced
+// the artifact and when.
+
+const MARKER_FILENAME = ".meko-installer";
+
+/**
+ * Read the installer's package.json `version` field. Mirrors the read
+ * performed in bin/create-meko-setup.mjs:56-59 so the marker and the
+ * CLI's --version report agree.
+ *
+ * @returns {string}
+ */
+export function getInstallerVersion() {
+  const libDir = dirname(fileURLToPath(import.meta.url));
+  const pkgPath = resolve(libDir, "..", "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  return pkg.version;
+}
+
+/**
+ * Write a `.meko-installer` marker inside `dir`. Format is one `key=value`
+ * line per field, e.g.
+ *
+ *   version=1.0.8
+ *   installedAt=2026-04-30T14:22:11.123Z
+ *
+ * Extra key/value pairs can be appended via `extra`. `dir` must exist; this
+ * function will not create it (the caller has already done mkdir).
+ *
+ * @param {string} dir
+ * @param {{extra?: Record<string,string>}} [opts]
+ * @returns {{path: string, version: string, installedAt: string}}
+ */
+export function writeInstallerMarker(dir, { extra = {} } = {}) {
+  const version = getInstallerVersion();
+  const installedAt = new Date().toISOString();
+  const lines = [`version=${version}`, `installedAt=${installedAt}`];
+  for (const [key, value] of Object.entries(extra)) {
+    lines.push(`${key}=${value}`);
+  }
+  const markerPath = join(dir, MARKER_FILENAME);
+  writeFileSync(markerPath, lines.join("\n") + "\n", "utf8");
+  return { path: markerPath, version, installedAt };
+}
+
+/**
+ * Parse a `.meko-installer` marker from `dir`. Returns null if the marker
+ * is missing or unreadable. Callers treat null as "not ours / user-managed".
+ *
+ * Marker format evolved across installer versions:
+ *   - pre-1.0.9: a single line containing the word "managed". No version.
+ *   - 1.0.9+:    `key=value` lines, including `version=` and `installedAt=`.
+ *
+ * Both shapes indicate "we own this artifact"; the caller needs to know
+ * which shape it got so it can decide whether to force a refresh. Legacy
+ * markers have no version to compare against, so they are returned with
+ * `legacy: true` and no `version` — `markerIsStale` then treats them as
+ * stale (any current version mismatches) and triggers a refresh. That's
+ * exactly the behavior users hitting the "stale skill" bug from 1.0.8
+ * need on their next re-install.
+ *
+ * @param {string} dir
+ * @returns {{version?: string, installedAt?: string, legacy?: boolean, [k: string]: string|boolean|undefined}|null}
+ */
+export function readInstallerMarker(dir) {
+  const markerPath = join(dir, MARKER_FILENAME);
+  let raw;
+  try {
+    raw = readFileSync(markerPath, "utf8");
+  } catch {
+    return null;
+  }
+  const out = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    if (!key) continue;
+    out[key] = value;
+  }
+  if (out.version) return out;
+
+  // Legacy marker path: pre-1.0.9 installs wrote the literal text
+  // `managed\n` (no `=`). Recognize it so we don't mistake an older
+  // managed dir for a user-managed one. Returning a parsed object with
+  // `legacy: true` lets markerIsStale do the right thing (stale → refresh).
+  if (raw.trim() === "managed") {
+    return { legacy: true };
+  }
+  return null;
+}
+
+/**
+ * True when the artifact at `dir` was produced by a different installer
+ * version than `currentVersion`. Also true when the marker is missing or
+ * unparseable — in that case the caller still needs to check whether the
+ * artifact dir exists (missing marker + missing dir = fresh install; missing
+ * marker + existing dir = user-managed, handle separately).
+ *
+ * Strict inequality by design — any version change forces a refresh, even
+ * a downgrade. We don't want to play semver-comparison games when the
+ * artifact content may have changed in either direction.
+ *
+ * @param {string} dir
+ * @param {string} currentVersion
+ * @returns {boolean}
+ */
+export function markerIsStale(dir, currentVersion) {
+  const marker = readInstallerMarker(dir);
+  if (!marker) return true;
+  // Legacy `managed\n` marker has no version recorded — always stale.
+  if (marker.legacy) return true;
+  return marker.version !== currentVersion;
+}

package/lib/clients/cursor.mjs

@@ -2,7 +2,6 @@ import {
   existsSync,
   lstatSync,
   readlinkSync,
-  writeFileSync,
   mkdirSync,
 } from "node:fs";
 import { homedir } from "node:os";
@@ -17,16 +16,22 @@ import {
   writeJsonFile,
 } from "../config.mjs";
 import {
+  getInstallerVersion,
+  isDanglingSymlink,
+  markerIsStale,
+  readInstallerMarker,
   resolveHooksRoot,
   resolveSkillSource,
   removePath,
   symlinkOrCopy,
+  writeInstallerMarker,
 } from "./common.mjs";
 
 const SKILLS = [{ name: "meko-mcp-tools" }];
 
 const HOOKS = [
-  { event: "sessionStart", script: "session-start.sh", timeout: 15000 },
+  { event: "sessionStart", script: "cursor-session-start.sh", timeout: 15000 },
+  { event: "beforeSubmitPrompt", script: "before-submit-prompt.sh", matcher: "UserPromptSubmit", timeout: 2000 },
   { event: "preCompact", script: "pre-compact.sh" },
   { event: "sessionEnd", script: "session-end.sh", timeout: 30000 },
 ];
@@ -98,28 +103,30 @@ export function createCursorAdapter(customPaths = {}) {
       writeJsonFile(mcpPath, cfg);
     },
     setHookEnvironment({ url, apiKey, dryRun, log, scope, projectRoot, cursorHookMode }) {
-      const mode = cursorHookMode || "hybrid";
+      const mode = cursorHookMode || "native";
       if (dryRun) {
-        if (mode === "native" || mode === "hybrid") {
+        if (mode === "native") {
           log.dim(`  Would configure Cursor hooks at ${paths.getHooksPath(scope, projectRoot)}`);
         }
-        if (mode === "claude-compat" || mode === "hybrid") {
+        if (mode === "claude-compat") {
           log.dim(`  Would configure Claude-compatible hooks at ${paths.getClaudeCompatSettingsPath(scope, projectRoot)}`);
         }
         return;
       }
 
-      if (mode === "native" || mode === "hybrid") {
+      if (mode === "native") {
         installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths });
       }
-      if (mode === "claude-compat" || mode === "hybrid") {
+      if (mode === "claude-compat") {
         installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths });
       }
     },
     installSkills({ dryRun, log, scope, projectRoot }) {
       const skillDir = paths.getSkillsDir(scope, projectRoot);
+      const currentVersion = getInstallerVersion();
       if (dryRun) {
         log.dim(`  Would install skills into ${skillDir}`);
+        log.dim(`  Would write .meko-installer marker (version=${currentVersion})`);
         return { marketplace: "skipped", skills: "dry-run" };
       }
 
@@ -127,10 +134,51 @@ export function createCursorAdapter(customPaths = {}) {
       for (const skill of SKILLS) {
         const source = resolveSkillSource(skill.name);
         const destination = join(skillDir, skill.name);
-        if (existsSync(destination)) continue;
+
+        if (existsSync(destination)) {
+          // Symlinks pointing at our own source directory are already live —
+          // the source tree IS the latest content, so there's nothing to
+          // refresh. Treat them the same as a fresh-current-version install.
+          if (isOwnSymlink(destination, source)) continue;
+
+          const marker = readInstallerMarker(destination);
+          if (!marker) {
+            // No marker AND not a symlink we own — user-managed dir or a
+            // pre-marker install. Leave it alone to avoid clobbering local
+            // edits; the user can delete it themselves for a fresh deploy.
+            log.dim(
+              `  Skipping ${destination}: no .meko-installer marker (user-managed).`,
+            );
+            continue;
+          }
+          if (markerIsStale(destination, currentVersion)) {
+            const from = marker.version ?? "pre-1.0.9";
+            log.dim(
+              `  Upgrading cursor skill from ${from} -> ${currentVersion}`,
+            );
+            removePath(destination);
+          } else {
+            // Same version already deployed — nothing to do.
+            continue;
+          }
+        } else if (isDanglingSymlink(destination)) {
+          // Stale symlink left behind by an earlier install whose target
+          // (e.g. a deleted worktree) no longer exists. existsSync is false
+          // for these, so the branch above misses them. Clear it so the
+          // fresh-install path below can replace it cleanly.
+          log.dim?.(
+            `  Replacing dangling symlink at ${destination} (target missing).`,
+          );
+          removePath(destination);
+        }
+
         const strategy = symlinkOrCopy(source, destination);
+        // Only stamp a marker when we materialized a real copy. Writing into
+        // a symlinked source dir would mutate the shipped asset tree, which
+        // is confusing at best and a permission error at worst. Symlinks
+        // re-resolve via isOwnSymlink on the next run.
         if (strategy === "copy") {
-          writeFileSync(join(destination, ".meko-installer"), "managed\n", "utf8");
+          writeInstallerMarker(destination);
         }
       }
 
@@ -149,7 +197,7 @@ export function createCursorAdapter(customPaths = {}) {
         uninstallCursorHooks({
           scope,
           projectRoot,
-          mode: cursorHookMode || "hybrid",
+          mode: cursorHookMode || "native",
           paths,
         });
         results.push({ key: "hooks", ok: true, message: "Cursor hook configuration cleaned up." });
@@ -206,10 +254,12 @@ function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
   }
 
   const handlersRoot = resolveHooksRoot();
+  pruneNativeCursorMekoHooks(cfg.hooks);
   for (const hook of HOOKS) {
     const scriptPath = join(handlersRoot, hook.script);
     const entry = { command: buildScriptCommand({ scriptPath }) };
     if (hook.timeout) entry.timeout = hook.timeout;
+    if (hook.matcher) entry.matcher = hook.matcher;
     upsertHookEntry(cfg.hooks, hook.event, entry);
   }
 
@@ -217,6 +267,20 @@ function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
   writeJsonFile(hooksPath, cfg);
 }
 
+// Cursor's claude-compat mode writes absolute-path Meko hook entries into
+// the shared settings.json (on scope=user, the same file Claude Code owns)
+// and de-dupes them via upsertClaudeCompatHook. The Claude Code adapter's
+// pruneMekoHookEntries (issue #60) is narrowed to preserve any entry whose
+// command references the current resolveHooksRoot() — so the entry this
+// function writes survives a subsequent Claude Code install from the
+// SAME install root.
+//
+// TRADE-OFF: if Cursor installed from a different root (e.g. repo clone)
+// than a later Claude Code install (e.g. npx cache), Cursor's entries look
+// byte-identical to the stale Claude Code entries issue #60 targets. They
+// will be pruned; the user must re-run the Cursor installer to restore
+// them. pruneMekoHookEntries emits a warning on any removal so the user
+// has a chance to notice before hooks silently disappear.
 function installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths }) {
   const settingsPath = paths.getClaudeCompatSettingsPath(scope, projectRoot);
   const cfg = readJsonFile(settingsPath);
@@ -254,6 +318,30 @@ function upsertHookEntry(hooksObj, event, entry) {
   if (!exists) hooksObj[event].push(entry);
 }
 
+function pruneNativeCursorMekoHooks(hooksObj) {
+  if (!hooksObj || typeof hooksObj !== "object") return;
+  for (const event of Object.keys(hooksObj)) {
+    if (!Array.isArray(hooksObj[event])) continue;
+    hooksObj[event] = hooksObj[event].filter((item) => {
+      if (!item?.command) return true;
+      return !isMekoHookCommand(item.command);
+    });
+  }
+}
+
+function isMekoHookCommand(command) {
+  if (typeof command !== "string") return false;
+  if (!command.includes("hooks-handlers/")) return false;
+  return [
+    "session-start.sh",
+    "cursor-session-start.sh",
+    "before-submit-prompt.sh",
+    "pre-compact.sh",
+    "session-end.sh",
+    "post-tool-context.sh",
+  ].some((script) => command.includes(script));
+}
+
 function upsertClaudeCompatHook(hooksObj, event, entry) {
   if (!Array.isArray(hooksObj[event])) hooksObj[event] = [];
   let bucket = hooksObj[event].find((item) => Array.isArray(item.hooks));
@@ -267,10 +355,10 @@ function upsertClaudeCompatHook(hooksObj, event, entry) {
 
 function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
   const handlersRoot = resolveHooksRoot();
-  const scripts = ["session-start.sh", "pre-compact.sh", "session-end.sh"]
+  const scripts = ["session-start.sh", "cursor-session-start.sh", "before-submit-prompt.sh", "pre-compact.sh", "session-end.sh"]
     .map((name) => join(handlersRoot, name));
 
-  if (mode === "native" || mode === "hybrid") {
+  if (mode === "native") {
     const hooksPath = paths.getHooksPath(scope, projectRoot);
     const cfg = readJsonFile(hooksPath);
     if (cfg?.hooks && typeof cfg.hooks === "object") {
@@ -285,7 +373,7 @@ function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
     }
   }
 
-  if (mode === "claude-compat" || mode === "hybrid") {
+  if (mode === "claude-compat") {
     // NOTE: we deliberately do NOT strip env.MEKO_MCP_URL / env.MEKO_API_KEY here.
     // On scope=user, this file is the same ~/.claude/settings.json the Claude Code
     // adapter owns; the Claude Code uninstall (claude-code.mjs removeKeys call) is
@@ -314,6 +402,23 @@ function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
   }
 }
 
+/**
+ * True when `destination` is a symlink that resolves to `expectedSource`.
+ * Used to recognize in-place symlink installs on re-run: the live source is
+ * the latest content, so there's nothing to refresh.
+ */
+function isOwnSymlink(destination, expectedSource) {
+  try {
+    const stat = lstatSync(destination);
+    if (!stat.isSymbolicLink()) return false;
+    const linkTarget = readlinkSync(destination);
+    const resolvedTarget = resolve(dirname(destination), linkTarget);
+    return resolvedTarget === expectedSource;
+  } catch {
+    return false;
+  }
+}
+
 function uninstallCursorSkills({ scope, projectRoot, paths }) {
   const skillsDir = paths.getSkillsDir(scope, projectRoot);
 

package/lib/clients/index.mjs

@@ -1,5 +1,6 @@
 import { createClaudeCodeAdapter } from "./claude-code.mjs";
 import { createClaudeDesktopAdapter } from "./claude-desktop.mjs";
+import { createCodexAdapter } from "./codex.mjs";
 import { createCursorAdapter } from "./cursor.mjs";
 
 /**
@@ -10,5 +11,6 @@ export function getClientAdapters() {
     "claude-code": createClaudeCodeAdapter(),
     "claude-desktop": createClaudeDesktopAdapter(),
     cursor: createCursorAdapter(),
+    codex: createCodexAdapter(),
   };
 }

package/lib/config.mjs

@@ -96,6 +96,62 @@ export function getClaudeCompatSettingsPath(scope, projectRoot) {
   return getClaudeCodeSettingsPath();
 }
 
+/**
+ * Return path to Codex's user-level config (TOML).
+ * Honors $CODEX_HOME if set, else defaults to ~/.codex/config.toml.
+ * Codex has no project-level config — caller should warn and degrade
+ * if a project scope was requested.
+ * @returns {string}
+ */
+export function getCodexConfigPath() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "config.toml");
+}
+
+/**
+ * Return path to Codex's user-level AGENTS.md.
+ * @returns {string}
+ */
+export function getCodexAgentsMdPath() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "AGENTS.md");
+}
+
+/**
+ * Return path to Codex's user-level hooks config.
+ * @returns {string}
+ */
+export function getCodexHooksPath() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "hooks.json");
+}
+
+/**
+ * Return path to the Meko env file the Codex hooks source on launch.
+ * Lives next to hooks.json under $CODEX_HOME (default ~/.codex/) and is
+ * written at mode 0600. Used because Codex's hooks.json schema has no
+ * `env` block, and inlining the API key into each hook's `command`
+ * field would expose it via `ps -ef` while the hook runs.
+ *
+ * The hook command becomes `. ~/.codex/meko-env.sh && bash /path/to/hook.sh`,
+ * so the secret never appears in process arguments.
+ *
+ * @returns {string}
+ */
+export function getCodexMekoEnvFilePath() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "meko-env.sh");
+}
+
+/**
+ * Return path to the shared agent-skills directory used by Codex
+ * (and other agent runtimes that follow the convention).
+ * @returns {string}
+ */
+export function getCodexSkillsRoot() {
+  return join(homedir(), ".agents", "skills");
+}
+
 // ---------------------------------------------------------------------------
 // Read / Write primitives
 // ---------------------------------------------------------------------------

package/lib/detect.mjs

@@ -8,6 +8,10 @@
  */
 
 import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { readJsonFile } from "./config.mjs";
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -70,56 +74,60 @@ export function detectClaude() {
 // detectExistingMeko
 // ---------------------------------------------------------------------------
 
+/**
+ * Canonical location of Claude Code's user-scope MCP registry. This is the
+ * file `claude mcp add` writes to — we read it directly rather than shelling
+ * out to `claude mcp list`, which takes 18–28s on real user machines and
+ * was timing out against our 10s guard (issue #80).
+ *
+ * @returns {string}
+ */
+export function getClaudeCodeConfigPath() {
+  return join(homedir(), ".claude.json");
+}
+
 /**
  * Check if a Meko MCP server is already registered in Claude Code.
  *
- * Runs `claude mcp list` and scans the output for the given server name.
- * The output format may vary between Claude CLI versions; we look for a
- * line that starts with `<serverName>:` (e.g. "meko: http://... - Connected")
- * and extract a status keyword from it.
+ * Reads `~/.claude.json` directly and inspects either `mcpServers[serverName]`
+ * (user scope) or `projects[projectRoot].mcpServers[serverName]` (project
+ * scope). This mirrors the approach the Claude Desktop adapter already uses
+ * against its own config (installer/lib/clients/claude-desktop.mjs:detectExisting)
+ * and replaces the previous `claude mcp list` shell-out, which silently
+ * returned `found: false` whenever the CLI exceeded the 10s run() timeout.
+ *
+ * Scope handling: `claude mcp add --scope project` writes under
+ * `projects[<absolute projectRoot>].mcpServers`, not the top-level
+ * `mcpServers`. A project-scope re-install must detect the existing entry
+ * in that nested location, otherwise the overwrite prompt is skipped and
+ * `claude mcp add --scope project` rejects the duplicate with "already
+ * exists". User-scope installs read the top-level `mcpServers` object
+ * (which is where the CLI writes entries added with `--scope user`).
  *
  * @param {string} [serverName="meko"] - The MCP server name to look for.
+ * @param {{ configPath?: string, scope?: "user"|"project", projectRoot?: string }} [options]
+ *   `configPath` — test-only injection point for the config file path; defaults to `~/.claude.json`.
+ *   `scope`      — "user" (default) or "project". Project scope looks under `projects[projectRoot].mcpServers`.
+ *   `projectRoot` — absolute path used as the key into `projects[...]` when `scope === "project"`.
+ *                   Ignored for user scope. Must be supplied by the caller for project scope.
  * @returns {{ found: boolean, status: string }}
- *   `found`  - true if a line matching `serverName` was found.
- *   `status` - the status value from that line (e.g. "Connected", "Failed"),
- *              or "" if not found.
+ *   `found`  - true if a matching MCP entry exists at the scope-appropriate location.
+ *   `status` - "Configured" when found, "" otherwise. (Kept as a string for
+ *              API compatibility with the prior implementation; callers use
+ *              this only for logging, never parsing.)
  */
-export function detectExistingMeko(serverName = "meko") {
-  const result = { found: false, status: "" };
-
-  const output = run("claude mcp list");
-  if (!output) return result;
-
-  // Scan each line for one that begins with the server name.
-  const lines = output.split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // Match "serverName:" prefix (colon-delimited format) or a table row
-    // where the first whitespace-separated token equals the server name.
-    const isMatch =
-      trimmed.startsWith(`${serverName}:`) ||
-      trimmed.split(/\s+/)[0] === serverName;
-
-    if (!isMatch) continue;
-
-    result.found = true;
-
-    // Extract status from known keywords anywhere on the line.
-    if (/\bConnected\b/i.test(trimmed)) {
-      result.status = "Connected";
-    } else if (/\bFailed\b/i.test(trimmed)) {
-      result.status = "Failed";
-    } else if (/\bError\b/i.test(trimmed)) {
-      result.status = "Error";
-    } else if (/\bDisconnected\b/i.test(trimmed)) {
-      result.status = "Disconnected";
-    } else {
-      result.status = "Unknown";
-    }
-
-    return result;
+export function detectExistingMeko(serverName = "meko", options = {}) {
+  const { scope = "user", projectRoot } = options;
+  const configPath = options.configPath ?? getClaudeCodeConfigPath();
+  const cfg = readJsonFile(configPath);
+
+  const entry =
+    scope === "project"
+      ? cfg?.projects?.[projectRoot]?.mcpServers?.[serverName]
+      : cfg?.mcpServers?.[serverName];
+
+  if (!entry) {
+    return { found: false, status: "" };
   }
-
-  return result;
+  return { found: true, status: "Configured" };
 }