mcp-agents 0.5.8 → 0.6.5

package/README.md

@@ -78,14 +78,29 @@ Any additional `tools/call` arguments are ignored (for example `model` or `model
 ### `codex` (pass-through)
 
 The codex provider passes through to Codex's native MCP server (`codex mcp-server`)
-using `-c key=value` config overrides:
+inside an isolated `CODEX_HOME`. The bridge copies `auth.json` into a temporary Codex
+home, writes a minimal `config.toml`, and does not inherit your normal external MCP
+server list. That keeps Codex from recursively starting other agent tools like Claude
+or Gemini during bridge calls.
 
 | CLI Flag | Default | Codex config key |
 |----------|---------|-----------------|
 | `--model` | `gpt-5.4` | `model` |
-| `--model_reasoning_effort` | `high` | `model_reasoning_effort` |
+| `--model_reasoning_effort` | `xhigh` | `model_reasoning_effort` |
 
-Hardcoded defaults: `sandbox_mode=read-only`, `approval_policy=never` (safe for MCP server mode).
+Hardcoded defaults: `sandbox_mode=read-only`, `approval_policy=never`,
+`features.multi_agent=false`.
+
+Startup flags set server-wide defaults for the native Codex MCP server. Per-call overrides still work through the native `codex` tool schema, for example:
+
+```json
+{
+  "prompt": "Review this diff",
+  "config": {
+    "model_reasoning_effort": "medium"
+  }
+}
+```
 
 ## Integration with Claude Code
 
@@ -119,7 +134,7 @@ Optional Gemini sandbox mode in `.mcp.json`:
 }
 ```
 
-Override codex defaults at server startup (not via `tools/call` arguments):
+Override codex defaults at server startup:
 
 ```json
 {
@@ -132,6 +147,11 @@ Override codex defaults at server startup (not via `tools/call` arguments):
 }
 ```
 
+The startup default can still be overridden for a single Codex tool call by passing `config.model_reasoning_effort` to the native `codex` tool.
+
+Because the bridge runs in an isolated Codex home, inherited MCP servers from your normal
+`~/.codex/config.toml` are intentionally unavailable inside bridged Codex sessions.
+
 <details>
 <summary>Alternative: using npx (slower, not recommended)</summary>
 
@@ -196,7 +216,11 @@ After `npm link`, any edits to `server.js` take effect immediately — no reinst
 4. Client calls `tools/call` with the tool name and a `prompt`
 5. The server runs the CLI as a child process and returns tool text (Claude JSON `result`, or stdout/stderr for other providers)
 
-The server includes a keepalive timer to prevent Node.js from exiting prematurely when stdin reaches EOF before the async subprocess registers an active handle.
+The server keeps a small keepalive timer so Node.js does not exit prematurely
+when stdin reaches EOF before an async subprocess registers an active handle.
+For Claude and Gemini provider mode, that keepalive is cleared during shutdown:
+the server now exits when the MCP stdio connection closes and kills any tracked
+detached provider child process groups that would otherwise linger.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-agents",
-  "version": "0.5.8",
+  "version": "0.6.5",
   "description": "MCP server that wraps AI CLI tools (Claude Code, Gemini CLI, Codex CLI) for use by any MCP client",
   "type": "module",
   "bin": {

package/server.js

@@ -2,7 +2,15 @@
 /* eslint-disable no-console */
 
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -19,8 +27,13 @@ const VERSION = JSON.parse(
 ).version;
 
 const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_CODEX_MODEL = "gpt-5.4";
+const DEFAULT_CODEX_MODEL_REASONING_EFFORT = "xhigh";
 const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const CLAUDE_EMPTY_OUTPUT_MAX_ATTEMPTS = 2;
+const SIGNAL_CODES = { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 };
+const SHUTDOWN_TIMEOUT_MS = 3_000;
+let fatalShutdown;
 
 // ---------------------------------------------------------------------------
 // CLI Backend Definitions
@@ -111,8 +124,8 @@ Usage: mcp-agents [options]
 
 Options:
   --provider <name>              CLI backend to use (${providers}) [default: codex]
-  --model <model>                Codex model [default: gpt-5.4]
-  --model_reasoning_effort <e>   Codex reasoning effort [default: high]
+  --model <model>                Codex model [default: ${DEFAULT_CODEX_MODEL}]
+  --model_reasoning_effort <e>   Codex reasoning effort [default: ${DEFAULT_CODEX_MODEL_REASONING_EFFORT}]
   --timeout <seconds>            Default timeout per call [default: 300]
   --help, -h                     Show this help message
   --version, -v                  Show version number`);
@@ -193,12 +206,19 @@ function parseArgs() {
  * on timeout — prevents orphan child processes.
  * @param {string} command
  * @param {string[]} args
- * @param {{ timeoutMs?: number, stdinData?: string }} [opts]
+ * @param {{
+ *   timeoutMs?: number,
+ *   stdinData?: string,
+ *   onSpawn?: (childInfo: { pid?: number, killGroup: () => void }) => void,
+ *   onSettled?: (pid?: number) => void,
+ * }} [opts]
  * @returns {Promise<{ output: string, stdoutBytes: number, stderrBytes: number, durationMs: number }>}
  */
 function runCli(command, args, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const stdinData = opts.stdinData;
+  const onSpawn = opts.onSpawn;
+  const onSettled = opts.onSettled;
   const startedAt = Date.now();
 
   return new Promise((resolve, reject) => {
@@ -225,11 +245,13 @@ function runCli(command, args, opts = {}) {
     const killGroup = () => {
       try { process.kill(-child.pid, "SIGKILL"); } catch {}
     };
+    onSpawn?.({ pid: child.pid, killGroup });
 
     const done = (err) => {
       clearTimeout(timer);
       if (settled) return;
       settled = true;
+      onSettled?.(child.pid);
       err ? reject(err) : resolve({
         output: (stdout || stderr || "").trimEnd(),
         stdoutBytes: stdoutLen,
@@ -262,6 +284,7 @@ function runCli(command, args, opts = {}) {
     const timer = setTimeout(() => {
       killGroup();
     }, timeoutMs);
+    timer.unref();
 
     child.on("error", (err) => {
       done(new Error(`Failed to start ${command}: ${err.message}`));
@@ -284,22 +307,108 @@ function runCli(command, args, opts = {}) {
   });
 }
 
+/**
+ * Resolve the source Codex home used by the parent process.
+ * @returns {string}
+ */
+function resolveCodexHome() {
+  return process.env.CODEX_HOME || join(process.env.HOME || tmpdir(), ".codex");
+}
+
+/**
+ * Quote a string for TOML output.
+ * @param {string} value
+ * @returns {string}
+ */
+function toTomlString(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * Build the minimal config for the isolated Codex bridge runtime.
+ * @param {{ model: string, modelReasoningEffort: string }} opts
+ * @returns {string}
+ */
+function buildCodexBridgeConfig({ model, modelReasoningEffort }) {
+  return [
+    `model = ${toTomlString(model)}`,
+    `model_reasoning_effort = ${toTomlString(modelReasoningEffort)}`,
+    'approval_policy = "never"',
+    'sandbox_mode = "read-only"',
+    "",
+    "[features]",
+    "multi_agent = false",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Create an isolated Codex home that preserves auth but strips inherited MCP servers.
+ * @param {{ model: string, modelReasoningEffort: string }} opts
+ * @returns {string}
+ */
+function createIsolatedCodexHome({ model, modelReasoningEffort }) {
+  const codexHome = mkdtempSync(join(tmpdir(), "mcp-agents-codex-"));
+  const sourceAuthPath = join(resolveCodexHome(), "auth.json");
+  const targetAuthPath = join(codexHome, "auth.json");
+  const configPath = join(codexHome, "config.toml");
+
+  if (existsSync(sourceAuthPath)) {
+    copyFileSync(sourceAuthPath, targetAuthPath);
+  }
+
+  writeFileSync(
+    configPath,
+    buildCodexBridgeConfig({ model, modelReasoningEffort }),
+    "utf8",
+  );
+
+  return codexHome;
+}
+
 /**
  * Spawn codex mcp-server as a pass-through, piping stdio directly.
  * @param {{ model?: string, modelReasoningEffort?: string }} opts
  */
 function runCodexPassthrough({ model, modelReasoningEffort }) {
-  const args = [
-    "mcp-server",
-    "-c", `model=${model || "gpt-5.4"}`,
-    "-c", "sandbox_mode=read-only",
-    "-c", "approval_policy=never",
-    "-c", `model_reasoning_effort=${modelReasoningEffort || "high"}`,
-  ];
+  const resolvedModel = model || DEFAULT_CODEX_MODEL;
+  const resolvedModelReasoningEffort =
+    modelReasoningEffort || DEFAULT_CODEX_MODEL_REASONING_EFFORT;
+  let isolatedCodexHome;
 
-  logErr(`[mcp-agents] passthrough: codex ${args.join(" ")}`);
+  try {
+    isolatedCodexHome = createIsolatedCodexHome({
+      model: resolvedModel,
+      modelReasoningEffort: resolvedModelReasoningEffort,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logErr(`[mcp-agents] failed to prepare isolated codex home: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const args = ["mcp-server"];
+  let cleanedUp = false;
+  const cleanupIsolatedCodexHome = () => {
+    if (cleanedUp || !isolatedCodexHome) return;
+    cleanedUp = true;
+
+    try {
+      rmSync(isolatedCodexHome, { recursive: true, force: true });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logErr(`[mcp-agents] failed to clean isolated codex home: ${msg}`);
+    }
+  };
+
+  logErr(
+    `[mcp-agents] passthrough: codex ${args.join(" ")} ` +
+      `(model=${resolvedModel}, reasoning_effort=${resolvedModelReasoningEffort}, isolated_home=true)`,
+  );
 
   const child = spawn("codex", args, {
+    env: { ...process.env, CODEX_HOME: isolatedCodexHome },
     stdio: ["inherit", "inherit", "pipe"],
   });
 
@@ -307,23 +416,25 @@ function runCodexPassthrough({ model, modelReasoningEffort }) {
     logErr(`[codex] ${chunk.toString().trimEnd()}`);
   });
 
-  const SIGNAL_CODES = { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 };
   for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
     process.once(sig, () => {
       child.kill(sig);
       setTimeout(() => {
         child.kill("SIGKILL");
+        cleanupIsolatedCodexHome();
         process.exit(128 + SIGNAL_CODES[sig]);
       }, 5000).unref();
     });
   }
 
   child.on("error", (err) => {
+    cleanupIsolatedCodexHome();
     logErr(`[mcp-agents] failed to start codex: ${err.message}`);
     process.exitCode = 1;
   });
 
   child.on("exit", (code, signal) => {
+    cleanupIsolatedCodexHome();
     if (signal) {
       logErr(`[mcp-agents] codex killed by ${signal}`);
       process.exitCode = 128 + (SIGNAL_CODES[signal] ?? 0);
@@ -358,6 +469,53 @@ async function main() {
     { name: "mcp-agents", version: VERSION },
     { capabilities: { tools: {} } },
   );
+  let keepAlive;
+  let shutdownStarted = false;
+  let shutdownExitCode = 0;
+  let shutdownPromise;
+  let shutdownTimer;
+  let activeRequests = 0;
+  const activeChildren = new Map();
+
+  const maybeFinalizeShutdown = () => {
+    if (!shutdownStarted || activeRequests > 0 || shutdownPromise) return;
+
+    shutdownPromise = Promise.resolve()
+      .then(async () => {
+        if (keepAlive) clearInterval(keepAlive);
+        await server.close();
+      })
+      .catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        logErr(`[mcp-agents] shutdown close failed: ${msg}`);
+      })
+      .finally(() => {
+        if (shutdownTimer) clearTimeout(shutdownTimer);
+        process.exit(shutdownExitCode);
+      });
+  };
+
+  const beginShutdown = (reason, exitCode = 0) => {
+    if (shutdownStarted) return;
+
+    shutdownStarted = true;
+    shutdownExitCode = exitCode;
+    logErr(
+      `[mcp-agents] shutting down (provider=${providerName}, reason=${reason})`,
+    );
+
+    shutdownTimer = setTimeout(() => {
+      process.exit(shutdownExitCode);
+    }, SHUTDOWN_TIMEOUT_MS);
+    shutdownTimer.unref();
+
+    for (const killGroup of activeChildren.values()) {
+      killGroup();
+    }
+
+    maybeFinalizeShutdown();
+  };
+  fatalShutdown = beginShutdown;
 
   const effectiveTimeout = defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
 
@@ -404,6 +562,13 @@ async function main() {
       return { content: [{ type: "text", text: "pong" }] };
     }
 
+    if (shutdownStarted) {
+      return {
+        content: [{ type: "text", text: "Server is shutting down" }],
+        isError: true,
+      };
+    }
+
     if (params.name !== backend.toolName) {
       return {
         content: [
@@ -416,6 +581,7 @@ async function main() {
       };
     }
 
+    activeRequests += 1;
     const rawArgs =
       params.arguments && typeof params.arguments === "object"
         ? params.arguments
@@ -441,6 +607,8 @@ async function main() {
       : effectiveTimeout;
 
     if (!prompt.trim()) {
+      activeRequests -= 1;
+      maybeFinalizeShutdown();
       return {
         content: [
           {
@@ -461,13 +629,30 @@ async function main() {
       ? backend.buildArgs(extraOpts)
       : backend.buildArgs(prompt, extraOpts);
     const buildCliOpts = (attemptTimeoutMs) => (
-      backend.stdinPrompt
-        ? { timeoutMs: attemptTimeoutMs, stdinData: prompt }
-        : { timeoutMs: attemptTimeoutMs }
+      {
+        timeoutMs: attemptTimeoutMs,
+        ...(backend.stdinPrompt ? { stdinData: prompt } : {}),
+        onSpawn: ({ pid, killGroup }) => {
+          if (!pid) return;
+          activeChildren.set(pid, killGroup);
+        },
+        onSettled: (pid) => {
+          if (!pid) return;
+          activeChildren.delete(pid);
+          maybeFinalizeShutdown();
+        },
+      }
     );
 
     logErr(`[mcp-agents] tools/call: running ${backend.command} …`);
     try {
+      if (shutdownStarted) {
+        return {
+          content: [{ type: "text", text: "Server is shutting down" }],
+          isError: true,
+        };
+      }
+
       const startedAt = Date.now();
       const maxAttempts = providerName === "claude"
         ? CLAUDE_EMPTY_OUTPUT_MAX_ATTEMPTS
@@ -552,6 +737,9 @@ async function main() {
         content: [{ type: "text", text: msg }],
         isError: true,
       };
+    } finally {
+      activeRequests -= 1;
+      maybeFinalizeShutdown();
     }
   });
 
@@ -562,13 +750,28 @@ async function main() {
   // request handlers (tools/call -> execFile) register active handles.
   // The SDK transport doesn't listen for stdin 'end', so the event
   // loop loses its only handle when the pipe closes.
-  const keepAlive = setInterval(() => {}, 60_000);
+  keepAlive = setInterval(() => {}, 60_000);
   const origOnClose = transport.onclose;
   transport.onclose = () => {
     clearInterval(keepAlive);
     origOnClose?.();
   };
 
+  process.stdin.once("end", () => {
+    beginShutdown("stdin-end");
+  });
+  process.stdin.once("close", () => {
+    beginShutdown("stdin-close");
+  });
+  process.stdout.on("error", (err) => {
+    if (err?.code === "EPIPE") beginShutdown("stdout-epipe");
+  });
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.once(sig, () => {
+      beginShutdown(sig, 128 + SIGNAL_CODES[sig]);
+    });
+  }
+
   logErr(`[mcp-agents] ready (provider: ${providerName})`);
 }
 
@@ -576,15 +779,23 @@ process.on("unhandledRejection", (reason) => {
   logErr(
     `UnhandledRejection: ${reason instanceof Error ? reason.stack : reason}`,
   );
-  process.exitCode = 1;
+  if (fatalShutdown) {
+    fatalShutdown("unhandledRejection", 1);
+    return;
+  }
+  process.exit(1);
 });
 
 process.on("uncaughtException", (err) => {
   logErr(`UncaughtException: ${err.stack || err.message}`);
-  process.exitCode = 1;
+  if (fatalShutdown) {
+    fatalShutdown("uncaughtException", 1);
+    return;
+  }
+  process.exit(1);
 });
 
 main().catch((err) => {
   logErr(err.stack || err.message);
-  process.exitCode = 1;
+  process.exit(1);
 });