code-ai-installer 4.0.1 → 4.1.0

package/README.md

@@ -48,7 +48,7 @@ Every domain also carries a meta **Auditor** beside the pipeline. Each skill dec
 
 ## 🚪 The MCP Gate Pipeline
 
-When you install for **Claude**, the installer registers `code-ai-mcp` in your global (user-scope) Claude config via `claude mcp add --scope user` (idempotent — a server already present in user scope is left untouched). From then on, the agents drive the work *through the server*, not by free-form prompting:
+When you install for **Claude**, the installer registers `code-ai-mcp` in your global (user-scope) Claude config — it adds an entry to the `mcpServers` object of `~/.claude.json` (idempotent — a server already present is left untouched, so an existing global `mempalace` is never duplicated). From then on, the agents drive the work *through the server*, not by free-form prompting:
 
 1. **`current_gate` / `classify_gate`** — the conductor reads where the run is and classifies the gate outcome (`auto_resolve` / `fork` / `exception`).
 2. **`get_skill`** — the active role fetches the skills it owns at this gate (the fetch is logged as telemetry for the Auditor).
@@ -151,7 +151,7 @@ Depending on `--target`, `code-ai` restructures your project:
 1. **Orchestration entry** — `AGENTS.md` (plus tool aliases like `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `QWEN.md`, `KIMI.md`).
 2. **Agents** — roles copied into the target's layout (e.g. `.claude/agents/<role>.md`, `.github/copilot-instructions.md`).
 3. **Skills & workflows** — the execution skillsets, with per-tool metadata sidecars.
-4. **MCP wiring (Claude only)** — registers `code-ai-mcp` (run as `npx -p code-ai-installer code-ai-mcp`) in your global (user-scope) Claude config via `claude mcp add --scope user`, plus an optional [MemPalace](https://www.npmjs.com/package/mempalace) memory server when present, and a project-local `.code-ai/config.json` that records the active domain and decision-store backend. If the `claude` CLI isn't on PATH, the installer prints the exact commands to run instead of editing your config by hand.
+4. **MCP wiring (Claude only)** — registers `code-ai-mcp` (run as `npx -p code-ai-installer code-ai-mcp`) in your global (user-scope) Claude config by adding it to the `mcpServers` object of `~/.claude.json` (backed up first, written atomically, idempotent), plus an optional [MemPalace](https://www.npmjs.com/package/mempalace) memory server when present, and a project-local `.code-ai/config.json` that records the active domain and decision-store backend. If `~/.claude.json` can't be read or written, the installer prints the exact JSON entries to add by hand instead of guessing.
 
 ---
 

package/dist/mcp_setup.d.ts

@@ -5,23 +5,33 @@ import type { DomainId } from "./shared/index.js";
  * Responsibilities:
  *   1. Detect / install MemPalace as an opt-in mirror for decision storage.
  *   2. Register `code-ai-mcp` (always) and `mempalace` (when accepted) in
- *      Claude Code's USER (global) scope via `claude mcp add --scope user`,
- *      so the servers are available across all the user's projects.
+ *      Claude Code's USER (global) config so the servers are available across
+ *      all the user's projects.
  *   3. Write `.code-ai/config.json` so `code-ai-mcp` knows which backend +
  *      domain to use. This stays PROJECT-local — the global server reads it
  *      from the project cwd at runtime.
  *
+ * Why direct edit of `~/.claude.json` (not `claude mcp add --scope user`):
+ * earlier versions registered via the CLI, but `claude mcp add` in current
+ * Claude Code rejects the `-s/--scope` flag whenever a stdio passthrough
+ * (`-- <command> ...`) is present — a commander parsing quirk — so a stdio
+ * server like `code-ai-mcp` can never be added to user scope through the CLI.
+ * The CLI is also version-unstable here. User-scope servers live as plain
+ * entries in the top-level `mcpServers` object of `~/.claude.json` (exactly
+ * where `mempalace`, `figma`, etc. already sit), so we merge there directly.
+ *
  * Why user scope (not a project `.mcp.json`): MCP servers are tools the user
- * wants everywhere, not per-project copies. Writing a project `.mcp.json` both
+ * wants everywhere, not per-project copies. A project `.mcp.json` both
  * scattered `code-ai-mcp` per-project and duplicated an already-global
- * `mempalace` into the project. Registration is idempotent — a server already
- * present in user scope is left untouched.
+ * `mempalace`. Registration is idempotent — a server already present in the
+ * user config is left untouched (so a pre-existing global `mempalace` is never
+ * duplicated or rewritten).
  *
  * Non-Claude targets skip this whole flow — MCP is Claude-specific.
  *
- * Graceful degradation: every step is best-effort. If the `claude` CLI is not
- * on PATH we never touch the user's config by hand — we print the exact
- * `claude mcp add` commands to run manually instead.
+ * Graceful degradation: every step is best-effort. If `~/.claude.json` cannot
+ * be read or written we never guess — we print the exact JSON entries to add by
+ * hand. Writes are atomic (temp file + rename) and back up the original first.
  */
 export type PythonRuntimeTool = "uv" | "pipx" | "pip";
 export interface PythonRuntime {
@@ -35,17 +45,6 @@ export interface McpServerEntry {
     args: string[];
     env?: Record<string, string>;
 }
-/**
- * Minimal `claude` CLI surface this module needs. Injectable so tests can
- * assert the constructed argv without spawning the real CLI.
- */
-export interface ClaudeCli {
-    /** Run `claude <args>`; resolve { ok, output } (combined stdout+stderr). */
-    run(args: string[]): Promise<{
-        ok: boolean;
-        output: string;
-    }>;
-}
 export interface McpSetupOptions {
     destinationDir: string;
     /** User's answer to the MemPalace prompt (true = wants it). */
@@ -64,15 +63,15 @@ export interface McpSetupReport {
     mempalaceInstallAttempted: boolean;
     mempalaceInstallSucceeded: boolean;
     pythonRuntime: PythonRuntime | null;
-    /** Was the `claude` CLI found on PATH? When false, registration falls back to manual instructions. */
-    claudeCliAvailable: boolean;
+    /** Absolute path of the Claude user config we register servers into. */
+    userConfigPath: string;
     /** How servers were registered. */
     registration: "user-scope" | "manual-fallback";
-    /** Server names freshly added to user scope this run. */
+    /** Server names freshly added to the user config this run. */
     serversRegistered: string[];
-    /** Server names already present in user scope (left untouched). */
+    /** Server names already present in the user config (left untouched). */
     serversAlreadyPresent: string[];
-    /** Server names whose registration failed. */
+    /** Server names whose registration failed (config unwritable). */
     serversFailed: string[];
     configPath: string;
     notices: string[];
@@ -85,8 +84,6 @@ export interface McpSetupReport {
  * instead of registering a config that can't launch.
  */
 export declare function detectMemPalace(): Promise<boolean>;
-/** True when the `claude` CLI is on PATH (probed via `claude --version`). */
-export declare function detectClaudeCli(cli?: ClaudeCli): Promise<boolean>;
 /**
  * Find the first available Python install runtime, in preference order:
  * uv → pipx → pip. Returns null if none available.
@@ -102,20 +99,54 @@ export declare function installMemPalace(runtime: PythonRuntime): Promise<{
     output: string;
 }>;
 /**
- * Build the argv for `claude mcp add --scope user <name> -- <command> [args]`.
- * Pure — exported for testing. Env vars become `-e KEY=VALUE` flags placed
- * before the server name (as `claude mcp add` expects options first).
+ * The Claude user config holds user-scope MCP servers in a top-level
+ * `mcpServers` object. We only ever read it, merge our entries, and write it
+ * back — preserving every other key.
+ */
+export interface UserConfigIO {
+    /** Absolute path of the config file. */
+    readonly configPath: string;
+    /** Read + parse the config. `ok:false` when missing or not a JSON object. */
+    read(): Promise<{
+        ok: boolean;
+        data?: Record<string, unknown>;
+        error?: string;
+    }>;
+    /** Back up the original then atomically write `data`. */
+    writeWithBackup(data: Record<string, unknown>): Promise<{
+        ok: boolean;
+        backupPath?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Resolve the Claude user config path. Honours `CLAUDE_CONFIG_DIR` when set,
+ * else `~/.claude.json`.
+ */
+export declare function userConfigPath(): string;
+/** Real filesystem-backed UserConfigIO. Factory so tests can target a temp file. */
+export declare function createUserConfigIO(configPath: string): UserConfigIO;
+/**
+ * Idempotently merge `servers` into the config's top-level `mcpServers`. Pure —
+ * returns a new config object plus which names were freshly added vs already
+ * present. An existing key is NEVER overwritten (so a pre-existing global
+ * `mempalace` is preserved untouched). Exported for unit testing.
  */
-export declare function buildClaudeAddArgs(name: string, entry: McpServerEntry): string[];
-/** Build the argv for `claude mcp remove --scope user <name>`. Pure — exported for testing. */
-export declare function buildClaudeRemoveArgs(name: string): string[];
+export declare function mergeUserScopeServers(config: Record<string, unknown>, servers: Record<string, McpServerEntry>): {
+    config: Record<string, unknown>;
+    registered: string[];
+    alreadyPresent: string[];
+};
 /**
- * Is `name` already registered in Claude's USER scope? Uses `claude mcp get`,
- * whose output prints `Scope: User config` for user-scope servers. A server in
- * a different scope (local/project) returns false here — we still want it in
- * user scope.
+ * Idempotently remove `names` from the config's `mcpServers`. Pure — returns a
+ * new config object plus which names were removed vs were not present. Exported
+ * for unit testing.
  */
-export declare function isRegisteredInUserScope(cli: ClaudeCli, name: string): Promise<boolean>;
+export declare function removeUserScopeServers(config: Record<string, unknown>, names: string[]): {
+    config: Record<string, unknown>;
+    removed: string[];
+    notPresent: string[];
+};
 /**
  * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
  * Idempotent — re-running overwrites with the same content if backend unchanged.
@@ -133,17 +164,17 @@ export declare function writeCodeAiConfig(destinationDir: string, config: {
  * Order:
  *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
  *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
- *   3. Register them in Claude USER scope via `claude mcp add --scope user`
- *      (idempotent; skip if already present). If `claude` CLI is absent, emit
- *      manual commands instead of touching the config by hand.
+ *   3. Merge them into the Claude user config's `mcpServers` (idempotent; skip
+ *      already-present). If the config can't be read/written, print the exact
+ *      JSON to add by hand instead of guessing.
  *   4. Write project-local `.code-ai/config.json` with the backend choice.
  *
  * Reports all decisions in `McpSetupReport.notices` so callers can surface
- * them to the user verbatim. `cli` is injectable for testing.
+ * them to the user verbatim. `io` is injectable for testing.
  */
-export declare function setupMcp(opts: McpSetupOptions, cli?: ClaudeCli): Promise<McpSetupReport>;
+export declare function setupMcp(opts: McpSetupOptions, io?: UserConfigIO): Promise<McpSetupReport>;
 export interface McpTeardownReport {
-    claudeCliAvailable: boolean;
+    userConfigPath: string;
     removal: "user-scope" | "manual-fallback";
     serversRemoved: string[];
     serversNotPresent: string[];
@@ -151,10 +182,10 @@ export interface McpTeardownReport {
     notices: string[];
 }
 /**
- * Remove the installer-owned MCP server(s) from Claude's USER scope via
- * `claude mcp remove --scope user`. Idempotent — a server that isn't registered
- * is reported as "nothing to remove". If the `claude` CLI is absent, prints the
- * manual commands instead of touching the config. `cli` is injectable for tests.
+ * Remove the installer-owned MCP server(s) from the Claude user config's
+ * `mcpServers`. Idempotent — a server that isn't present is reported as
+ * "nothing to remove". If the config can't be read/written, prints guidance
+ * instead of guessing. `mempalace` is never touched. `io` is injectable.
  *
  * NOTE: the registration is global (shared across all projects), so this removes
  * code-ai-mcp for every project. That is the chosen behaviour (symmetric with
@@ -162,4 +193,4 @@ export interface McpTeardownReport {
  */
 export declare function teardownMcp(opts: {
     dryRun: boolean;
-}, cli?: ClaudeCli): Promise<McpTeardownReport>;
+}, io?: UserConfigIO): Promise<McpTeardownReport>;

package/dist/mcp_setup.js

@@ -1,9 +1,7 @@
 import { spawn } from "node:child_process";
-import { mkdir, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
-const defaultClaudeCli = {
-    run: (args) => spawnCapture("claude", args),
-};
 /**
  * Try `mempalace-mcp --help` — the dedicated MCP-server bin, which is exactly
  * what we register. Resolves true on exit code 0, false otherwise (including
@@ -14,11 +12,6 @@ const defaultClaudeCli = {
 export async function detectMemPalace() {
     return spawnExitZero("mempalace-mcp", ["--help"]);
 }
-/** True when the `claude` CLI is on PATH (probed via `claude --version`). */
-export async function detectClaudeCli(cli = defaultClaudeCli) {
-    const res = await cli.run(["--version"]);
-    return res.ok;
-}
 /**
  * Find the first available Python install runtime, in preference order:
  * uv → pipx → pip. Returns null if none available.
@@ -56,55 +49,118 @@ function installCommandArgs(runtime) {
     }
 }
 /**
- * Build the argv for `claude mcp add --scope user <name> -- <command> [args]`.
- * Pure — exported for testing. Env vars become `-e KEY=VALUE` flags placed
- * before the server name (as `claude mcp add` expects options first).
+ * Resolve the Claude user config path. Honours `CLAUDE_CONFIG_DIR` when set,
+ * else `~/.claude.json`.
  */
-export function buildClaudeAddArgs(name, entry) {
-    const envFlags = entry.env
-        ? Object.entries(entry.env).flatMap(([k, v]) => ["-e", `${k}=${v}`])
-        : [];
-    return ["mcp", "add", ...envFlags, "--scope", "user", name, "--", entry.command, ...entry.args];
+export function userConfigPath() {
+    const dir = process.env.CLAUDE_CONFIG_DIR?.trim();
+    return dir ? join(dir, ".claude.json") : join(homedir(), ".claude.json");
+}
+/** Real filesystem-backed UserConfigIO. Factory so tests can target a temp file. */
+export function createUserConfigIO(configPath) {
+    return {
+        configPath,
+        async read() {
+            let raw;
+            try {
+                raw = await readFile(configPath, "utf8");
+            }
+            catch (err) {
+                const e = err;
+                return { ok: false, error: e.code === "ENOENT" ? "file not found" : e.message };
+            }
+            try {
+                const data = JSON.parse(raw);
+                if (data === null || typeof data !== "object" || Array.isArray(data)) {
+                    return { ok: false, error: "config is not a JSON object" };
+                }
+                return { ok: true, data: data };
+            }
+            catch (err) {
+                return { ok: false, error: `JSON parse error: ${err.message}` };
+            }
+        },
+        async writeWithBackup(data) {
+            const backupPath = `${configPath}.bak`;
+            try {
+                try {
+                    await copyFile(configPath, backupPath);
+                }
+                catch (err) {
+                    // Only tolerate "original did not exist"; surface anything else.
+                    if (err.code !== "ENOENT")
+                        throw err;
+                }
+                const tmpPath = `${configPath}.code-ai.tmp`;
+                await writeFile(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+                await rename(tmpPath, configPath);
+                return { ok: true, backupPath };
+            }
+            catch (err) {
+                return { ok: false, error: err.message };
+            }
+        },
+    };
 }
-/** Build the argv for `claude mcp remove --scope user <name>`. Pure — exported for testing. */
-export function buildClaudeRemoveArgs(name) {
-    return ["mcp", "remove", "--scope", "user", name];
+const defaultUserConfigIO = createUserConfigIO(userConfigPath());
+/** Shape a server entry the way Claude stores user-scope stdio servers. */
+function toUserScopeEntry(entry) {
+    return {
+        type: "stdio",
+        command: entry.command,
+        args: [...entry.args],
+        env: entry.env ?? {},
+    };
 }
-/** Human-readable manual command, for the no-CLI fallback notice. */
-function manualAddCommand(name, entry) {
-    return `claude ${buildClaudeAddArgs(name, entry).join(" ")}`;
+function readMcpServers(config) {
+    const existing = config.mcpServers;
+    return existing && typeof existing === "object" && !Array.isArray(existing)
+        ? { ...existing }
+        : {};
 }
 /**
- * Is `name` already registered in Claude's USER scope? Uses `claude mcp get`,
- * whose output prints `Scope: User config` for user-scope servers. A server in
- * a different scope (local/project) returns false here — we still want it in
- * user scope.
+ * Idempotently merge `servers` into the config's top-level `mcpServers`. Pure —
+ * returns a new config object plus which names were freshly added vs already
+ * present. An existing key is NEVER overwritten (so a pre-existing global
+ * `mempalace` is preserved untouched). Exported for unit testing.
  */
-export async function isRegisteredInUserScope(cli, name) {
-    const res = await cli.run(["mcp", "get", name]);
-    return res.ok && /Scope:\s*User config/i.test(res.output);
+export function mergeUserScopeServers(config, servers) {
+    const next = { ...config };
+    const mcpServers = readMcpServers(config);
+    const registered = [];
+    const alreadyPresent = [];
+    for (const [name, entry] of Object.entries(servers)) {
+        if (Object.prototype.hasOwnProperty.call(mcpServers, name)) {
+            alreadyPresent.push(name);
+            continue;
+        }
+        mcpServers[name] = toUserScopeEntry(entry);
+        registered.push(name);
+    }
+    next.mcpServers = mcpServers;
+    return { config: next, registered, alreadyPresent };
 }
 /**
- * Register one server in user scope, idempotently. Skips if already present in
- * user scope. Never throws — returns the outcome + a notice for the report.
+ * Idempotently remove `names` from the config's `mcpServers`. Pure — returns a
+ * new config object plus which names were removed vs were not present. Exported
+ * for unit testing.
  */
-async function addServerToUserScope(cli, name, entry) {
-    if (await isRegisteredInUserScope(cli, name)) {
-        return {
-            outcome: "already-present",
-            notice: `MCP server '${name}' already registered in user scope — left untouched.`,
-        };
-    }
-    const res = await cli.run(buildClaudeAddArgs(name, entry));
-    if (res.ok) {
-        return { outcome: "registered", notice: `Registered MCP server '${name}' in user scope (global).` };
+export function removeUserScopeServers(config, names) {
+    const next = { ...config };
+    const mcpServers = readMcpServers(config);
+    const removed = [];
+    const notPresent = [];
+    for (const name of names) {
+        if (Object.prototype.hasOwnProperty.call(mcpServers, name)) {
+            delete mcpServers[name];
+            removed.push(name);
+        }
+        else {
+            notPresent.push(name);
+        }
     }
-    return {
-        outcome: "failed",
-        notice: `Failed to register '${name}' in user scope. Run it manually:\n` +
-            `    ${manualAddCommand(name, entry)}\n` +
-            `  Output:\n${res.output}`,
-    };
+    next.mcpServers = mcpServers;
+    return { config: next, removed, notPresent };
 }
 /**
  * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
@@ -142,21 +198,25 @@ function buildServerEntries(mempalaceUsed) {
     }
     return servers;
 }
+/** Format a single "name: entry-json" line for the manual-fallback notice. */
+function manualEntryLine(name, entry) {
+    return `    "${name}": ${JSON.stringify(toUserScopeEntry(entry))}`;
+}
 /**
  * End-to-end orchestrator. Called from the install flow when `target=claude`.
  *
  * Order:
  *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
  *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
- *   3. Register them in Claude USER scope via `claude mcp add --scope user`
- *      (idempotent; skip if already present). If `claude` CLI is absent, emit
- *      manual commands instead of touching the config by hand.
+ *   3. Merge them into the Claude user config's `mcpServers` (idempotent; skip
+ *      already-present). If the config can't be read/written, print the exact
+ *      JSON to add by hand instead of guessing.
  *   4. Write project-local `.code-ai/config.json` with the backend choice.
  *
  * Reports all decisions in `McpSetupReport.notices` so callers can surface
- * them to the user verbatim. `cli` is injectable for testing.
+ * them to the user verbatim. `io` is injectable for testing.
  */
-export async function setupMcp(opts, cli = defaultClaudeCli) {
+export async function setupMcp(opts, io = defaultUserConfigIO) {
     const notices = [];
     let mempalaceUsed = false;
     let mempalaceInstallAttempted = false;
@@ -191,33 +251,49 @@ export async function setupMcp(opts, cli = defaultClaudeCli) {
     const serversRegistered = [];
     const serversAlreadyPresent = [];
     const serversFailed = [];
-    const claudeCliAvailable = !opts.dryRun && (await detectClaudeCli(cli));
     let registration;
     if (opts.dryRun) {
         registration = "user-scope";
         for (const [name, entry] of Object.entries(servers)) {
-            notices.push(`Would register MCP server '${name}' in user scope: ${manualAddCommand(name, entry)}`);
-        }
-    }
-    else if (claudeCliAvailable) {
-        registration = "user-scope";
-        for (const [name, entry] of Object.entries(servers)) {
-            const { outcome, notice } = await addServerToUserScope(cli, name, entry);
-            notices.push(notice);
-            if (outcome === "registered")
-                serversRegistered.push(name);
-            else if (outcome === "already-present")
-                serversAlreadyPresent.push(name);
-            else
-                serversFailed.push(name);
+            notices.push(`Would register MCP server '${name}' in Claude user config (${io.configPath}): ${JSON.stringify(toUserScopeEntry(entry))}`);
         }
     }
     else {
-        registration = "manual-fallback";
-        notices.push("The `claude` CLI was not found on PATH — not modifying your global config automatically. " +
-            "Register the MCP server(s) in user scope by running:");
-        for (const [name, entry] of Object.entries(servers)) {
-            notices.push(`    ${manualAddCommand(name, entry)}`);
+        const read = await io.read();
+        if (!read.ok || !read.data) {
+            registration = "manual-fallback";
+            notices.push(`Could not read Claude user config at ${io.configPath} (${read.error ?? "unknown error"}). ` +
+                `Not modifying it automatically — add these entries to its "mcpServers" object by hand:`);
+            for (const [name, entry] of Object.entries(servers))
+                notices.push(manualEntryLine(name, entry));
+        }
+        else {
+            const merged = mergeUserScopeServers(read.data, servers);
+            serversAlreadyPresent.push(...merged.alreadyPresent);
+            for (const name of merged.alreadyPresent) {
+                notices.push(`MCP server '${name}' already in user config — left untouched.`);
+            }
+            if (merged.registered.length === 0) {
+                registration = "user-scope";
+            }
+            else {
+                const written = await io.writeWithBackup(merged.config);
+                if (written.ok) {
+                    registration = "user-scope";
+                    serversRegistered.push(...merged.registered);
+                    notices.push(`Registered MCP server(s) [${merged.registered.join(", ")}] in Claude user config ${io.configPath}` +
+                        (written.backupPath ? ` (backup: ${written.backupPath})` : "") +
+                        ". Restart your Claude Code session to load them.");
+                }
+                else {
+                    registration = "manual-fallback";
+                    serversFailed.push(...merged.registered);
+                    notices.push(`Failed to write Claude user config at ${io.configPath} (${written.error ?? "unknown error"}). ` +
+                        `No changes made — add these entries to its "mcpServers" object by hand:`);
+                    for (const name of merged.registered)
+                        notices.push(manualEntryLine(name, servers[name]));
+                }
+            }
         }
     }
     const cfg = await writeCodeAiConfig(opts.destinationDir, {
@@ -229,7 +305,7 @@ export async function setupMcp(opts, cli = defaultClaudeCli) {
         mempalaceInstallAttempted,
         mempalaceInstallSucceeded,
         pythonRuntime,
-        claudeCliAvailable,
+        userConfigPath: io.configPath,
         registration,
         serversRegistered,
         serversAlreadyPresent,
@@ -246,54 +322,86 @@ export async function setupMcp(opts, cli = defaultClaudeCli) {
  */
 const INSTALLER_OWNED_SERVERS = ["code-ai-mcp"];
 /**
- * Remove the installer-owned MCP server(s) from Claude's USER scope via
- * `claude mcp remove --scope user`. Idempotent — a server that isn't registered
- * is reported as "nothing to remove". If the `claude` CLI is absent, prints the
- * manual commands instead of touching the config. `cli` is injectable for tests.
+ * Remove the installer-owned MCP server(s) from the Claude user config's
+ * `mcpServers`. Idempotent — a server that isn't present is reported as
+ * "nothing to remove". If the config can't be read/written, prints guidance
+ * instead of guessing. `mempalace` is never touched. `io` is injectable.
  *
  * NOTE: the registration is global (shared across all projects), so this removes
  * code-ai-mcp for every project. That is the chosen behaviour (symmetric with
  * install); a multi-project user re-runs the installer to restore it.
  */
-export async function teardownMcp(opts, cli = defaultClaudeCli) {
+export async function teardownMcp(opts, io = defaultUserConfigIO) {
     const notices = [];
     const serversRemoved = [];
     const serversNotPresent = [];
     const serversFailed = [];
     if (opts.dryRun) {
         for (const name of INSTALLER_OWNED_SERVERS) {
-            notices.push(`Would remove MCP server '${name}' from user scope: claude ${buildClaudeRemoveArgs(name).join(" ")}`);
+            notices.push(`Would remove MCP server '${name}' from Claude user config (${io.configPath}).`);
         }
-        return { claudeCliAvailable: false, removal: "user-scope", serversRemoved, serversNotPresent, serversFailed, notices };
+        return {
+            userConfigPath: io.configPath,
+            removal: "user-scope",
+            serversRemoved,
+            serversNotPresent,
+            serversFailed,
+            notices,
+        };
     }
-    const claudeCliAvailable = await detectClaudeCli(cli);
-    if (!claudeCliAvailable) {
-        notices.push("The `claude` CLI was not found on PATH — not modifying your global config automatically. " +
-            "Remove the MCP server(s) from user scope by running:");
-        for (const name of INSTALLER_OWNED_SERVERS) {
-            notices.push(`    claude ${buildClaudeRemoveArgs(name).join(" ")}`);
-        }
-        return { claudeCliAvailable, removal: "manual-fallback", serversRemoved, serversNotPresent, serversFailed, notices };
+    const read = await io.read();
+    if (!read.ok || !read.data) {
+        notices.push(`Could not read Claude user config at ${io.configPath} (${read.error ?? "unknown error"}). ` +
+            `Remove the server(s) [${INSTALLER_OWNED_SERVERS.join(", ")}] from its "mcpServers" object by hand.`);
+        return {
+            userConfigPath: io.configPath,
+            removal: "manual-fallback",
+            serversRemoved,
+            serversNotPresent,
+            serversFailed,
+            notices,
+        };
     }
-    for (const name of INSTALLER_OWNED_SERVERS) {
-        if (!(await isRegisteredInUserScope(cli, name))) {
-            serversNotPresent.push(name);
-            notices.push(`MCP server '${name}' is not registered in user scope — nothing to remove.`);
-            continue;
-        }
-        const res = await cli.run(buildClaudeRemoveArgs(name));
-        if (res.ok) {
-            serversRemoved.push(name);
-            notices.push(`Removed MCP server '${name}' from user scope.`);
-        }
-        else {
-            serversFailed.push(name);
-            notices.push(`Failed to remove '${name}' from user scope. Run it manually:\n` +
-                `    claude ${buildClaudeRemoveArgs(name).join(" ")}\n` +
-                `  Output:\n${res.output}`);
-        }
+    const result = removeUserScopeServers(read.data, INSTALLER_OWNED_SERVERS);
+    serversNotPresent.push(...result.notPresent);
+    for (const name of result.notPresent) {
+        notices.push(`MCP server '${name}' is not in user config — nothing to remove.`);
+    }
+    if (result.removed.length === 0) {
+        return {
+            userConfigPath: io.configPath,
+            removal: "user-scope",
+            serversRemoved,
+            serversNotPresent,
+            serversFailed,
+            notices,
+        };
+    }
+    const written = await io.writeWithBackup(result.config);
+    if (written.ok) {
+        serversRemoved.push(...result.removed);
+        notices.push(`Removed MCP server(s) [${result.removed.join(", ")}] from Claude user config ${io.configPath}` +
+            (written.backupPath ? ` (backup: ${written.backupPath})` : "") +
+            ".");
+        return {
+            userConfigPath: io.configPath,
+            removal: "user-scope",
+            serversRemoved,
+            serversNotPresent,
+            serversFailed,
+            notices,
+        };
     }
-    return { claudeCliAvailable, removal: "user-scope", serversRemoved, serversNotPresent, serversFailed, notices };
+    serversFailed.push(...result.removed);
+    notices.push(`Failed to write Claude user config at ${io.configPath} (${written.error ?? "unknown error"}). No changes made.`);
+    return {
+        userConfigPath: io.configPath,
+        removal: "manual-fallback",
+        serversRemoved,
+        serversNotPresent,
+        serversFailed,
+        notices,
+    };
 }
 // ─── Subprocess helpers ─────────────────────────────────────────────────────
 async function spawnExitZero(command, args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-ai-installer",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Production-ready CLI to install code-ai agents and skills for multiple AI coding assistants. Bundles the code-ai-mcp MCP server for Claude Code.",
   "license": "MIT",
   "author": "Denish1209",