fix(mcp): address code review — atomic config write, resilient emit chain, ordering comment, sync test

- writeJsonConfig: write to a sibling .clerk-tmp-<pid> file then rename so
  concurrent readers (e.g. Claude Code) never see a partial ~/.claude.json
- emit write chain: catch EPIPE / write errors so a single failure doesn't
  wedge every subsequent frame
- forwardJsonBody: note that protocol-version capture ordering relies on the
  MCP client awaiting the initialize reply before sending the next request
- GLOBAL_FLAGS_WITH_VALUE: export the set and add a test that fails if a new
  root value-option in cli-program.ts is not listed there

Author: rafa-thayto

packages/cli-core/src/commands/mcp/clients/json-config.ts

@@ -9,7 +9,7 @@
  * formatting and a 2-space indent.
  */
 
-import { chmod, mkdir } from "node:fs/promises";
+import { chmod, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { log } from "../../../lib/log.ts";
 import { CliError, ERROR_CODE, errorMessage } from "../../../lib/errors.ts";
@@ -53,8 +53,18 @@ export async function readJsonConfig(path: string): Promise<ConfigRecord> {
 
 export async function writeJsonConfig(path: string, config: ConfigRecord): Promise<void> {
   log.debug(`mcp: write ${path}`);
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  await Bun.write(path, JSON.stringify(config, null, 2) + "\n");
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // Atomic write: write to a sibling temp file then rename so a concurrent
+  // reader (e.g. Claude Code) never sees a partial file.
+  const tmp = `${path}.clerk-tmp-${process.pid}`;
+  try {
+    await writeFile(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    await rename(tmp, path);
+  } catch (error) {
+    await unlink(tmp).catch(() => {});
+    throw error;
+  }
   await restrictPermissions(path);
 }
 

packages/cli-core/src/commands/mcp/run.ts

@@ -50,7 +50,12 @@ export async function mcpRun(options: McpOptions = {}, streams: RunStreams = {})
   const emit: Emit = (message) => {
     captureProtocolVersion(message, session);
     const line = JSON.stringify(message) + "\n";
-    writeTail = writeTail.then(() => writeRaw(line));
+    // Swallow write errors (e.g. EPIPE) so one failed frame doesn't wedge the chain.
+    writeTail = writeTail
+      .then(() => writeRaw(line))
+      .catch((err: unknown) => {
+        log.debug(`mcp run: write error — ${errorMessage(err)}`);
+      });
     return writeTail;
   };
 
@@ -181,6 +186,9 @@ async function dispatch(message: JsonRpcMessage, ctx: DispatchCtx): Promise<void
     track(pipeEventStream(response, emitPayload, signal));
     return;
   }
+  // The initialize response body is drained concurrently via track(); the
+  // protocol version captured inside emitPayload→emit is set before the next
+  // request fires because the MCP client awaits the initialize reply.
   track(forwardJsonBody(response, message, emit, emitPayload));
 }
 

packages/cli-core/src/lib/input-json.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe, beforeEach, afterEach } from "bun:test";
-import { expandInputJson, toKebabCase } from "./input-json.ts";
+import { expandInputJson, toKebabCase, GLOBAL_FLAGS_WITH_VALUE } from "./input-json.ts";
 import { join } from "node:path";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -393,3 +393,18 @@ describe("expandInputJson", () => {
     });
   });
 });
+
+describe("GLOBAL_FLAGS_WITH_VALUE", () => {
+  test("covers every root value-option in cli-program.ts", async () => {
+    // If a new value-flag is added to the root program but omitted from
+    // GLOBAL_FLAGS_WITH_VALUE, its value can leak into positionals and
+    // incorrectly trigger the `mcp run` stdin bypass.
+    const { createProgram } = await import("../cli-program.ts");
+    const program = createProgram();
+    const missing = program.options
+      .filter((opt) => (opt.required || opt.optional) && opt.long)
+      .map((opt) => opt.long!)
+      .filter((flag) => !GLOBAL_FLAGS_WITH_VALUE.has(flag));
+    expect(missing).toEqual([]);
+  });
+});

packages/cli-core/src/lib/input-json.ts

@@ -141,7 +141,8 @@ function hasStdinPipe(): boolean {
 // sync with the root options in cli-program.ts: if a value-flag isn't listed,
 // its value (e.g. `--mode mcp`) leaks into the positionals and could misfire
 // the `mcp run` detection below.
-const GLOBAL_FLAGS_WITH_VALUE = new Set(["--mode", "--input-json"]);
+// Exported so tests can verify this set covers all root value-options.
+export const GLOBAL_FLAGS_WITH_VALUE = new Set(["--mode", "--input-json"]);
 
 function ownsRawStdin(argv: string[]): boolean {
   // Drop flags (and the values of known global value-flags) so what remains is