mcp-agents 0.5.1 → 0.5.3

package/README.md

@@ -15,16 +15,29 @@ MCP server that wraps AI CLI tools — [Claude Code](https://docs.anthropic.com/
 
 Only the CLI you select with `--provider` needs to be present.
 
+## Install
+
+```bash
+npm install -g mcp-agents
+```
+
+Global install is **strongly recommended** over `npx -y mcp-agents@latest`. The `npx`
+approach performs a network round-trip on every cold start, which can exceed MCP client
+connection timeouts and cause "stream disconnected" errors.
+
+**Tip:** If your project's `.mcp.json` references `mcp-agents`, add `npm install -g mcp-agents`
+to your setup script (e.g. `bin/setup`) so new developers get it automatically.
+
 ## Quick test
 
 ```bash
 # Default provider (codex)
-npx mcp-agents
+mcp-agents
 
 # Specific provider
-npx mcp-agents --provider claude
-npx mcp-agents --provider gemini
-npx mcp-agents --provider gemini --sandbox false
+mcp-agents --provider claude
+mcp-agents --provider gemini
+mcp-agents --provider gemini --sandbox false
 ```
 
 The server speaks [JSON-RPC over stdio](https://modelcontextprotocol.io/docs/concepts/transports#stdio). It prints `[mcp-agents] ready (provider: <name>)` to stderr when it's listening.
@@ -57,29 +70,29 @@ Each `--provider` flag maps to a single exposed tool:
 ### `codex` (pass-through)
 
 The codex provider passes through to Codex's native MCP server (`codex mcp-server`)
-with configurable flags:
+using `-c key=value` config overrides:
 
-| CLI Flag | Default | Codex flag |
-|----------|---------|------------|
-| `--model` | `gpt-5.3-codex` | `-m <model>` |
-| `--model_reasoning_effort` | `high` | `-c model_reasoning_effort=<value>` |
+| CLI Flag | Default | Codex config key |
+|----------|---------|-----------------|
+| `--model` | `gpt-5.3-codex` | `model` |
+| `--model_reasoning_effort` | `high` | `model_reasoning_effort` |
 
-Hardcoded defaults: `-s read-only -a never` (safe for MCP server mode).
+Hardcoded defaults: `sandbox_mode=read-only`, `approval_policy=never` (safe for MCP server mode).
 
 ## Integration with Claude Code
 
-Add entries to your project's `.mcp.json`:
+Add entries to your project's `.mcp.json` (requires `npm i -g mcp-agents`):
 
 ```json
 {
   "mcpServers": {
     "codex": {
-      "command": "npx",
-      "args": ["-y", "mcp-agents@latest", "--provider", "codex"]
+      "command": "mcp-agents",
+      "args": ["--provider", "codex"]
     },
     "gemini": {
-      "command": "npx",
-      "args": ["-y", "mcp-agents@latest", "--provider", "gemini", "--sandbox", "false"]
+      "command": "mcp-agents",
+      "args": ["--provider", "gemini", "--sandbox", "false"]
     }
   }
 }
@@ -87,33 +100,61 @@ Add entries to your project's `.mcp.json`:
 
 Override codex defaults:
 
+```json
+{
+  "mcpServers": {
+    "codex": {
+      "command": "mcp-agents",
+      "args": ["--provider", "codex", "--model", "o3-pro", "--model_reasoning_effort", "medium"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Alternative: using npx (slower, not recommended)</summary>
+
 ```json
 {
   "mcpServers": {
     "codex": {
       "command": "npx",
-      "args": ["-y", "mcp-agents@latest", "--provider", "codex", "--model", "o3-pro", "--model_reasoning_effort", "medium"]
+      "args": ["-y", "mcp-agents@latest", "--provider", "codex"]
     }
   }
 }
 ```
 
+> **Warning:** `npx -y mcp-agents@latest` performs a network round-trip on every cold
+> start (~70s), which can exceed MCP client connection timeouts.
+
+</details>
+
 ## Integration with OpenAI Codex
 
 Add two entries to `~/.codex/config.toml` — one per provider you want available:
 
 ```toml
 [mcp_servers.claude-code]
-command = "npx"
-args = ["-y", "mcp-agents", "--provider", "claude"]
+command = "mcp-agents"
+args = ["--provider", "claude"]
 
 [mcp_servers.gemini]
-command = "npx"
-args = ["-y", "mcp-agents", "--provider", "gemini", "--sandbox", "false"]
+command = "mcp-agents"
+args = ["--provider", "gemini", "--sandbox", "false"]
 ```
 
 Then in a Codex session you can call the `claude_code` or `gemini` tools, which shell out to the respective CLIs.
 
+## Development
+
+```bash
+npm install
+npm link          # symlinks mcp-agents to your local server.js
+```
+
+After `npm link`, any edits to `server.js` take effect immediately — no reinstall needed.
+
 ## How it works
 
 1. An MCP client connects over stdio

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-agents",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /* eslint-disable no-console */
 
-import { execFile, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -92,9 +92,10 @@ Usage: mcp-agents [options]
 
 Options:
   --provider <name>              CLI backend to use (${providers}) [default: codex]
-  --model <model>                Model to use (codex) [default: gpt-5.3-codex]
-  --model_reasoning_effort <e>   Reasoning effort (codex) [default: high]
+  --model <model>                Codex model [default: gpt-5.3-codex]
+  --model_reasoning_effort <e>   Codex reasoning effort [default: high]
   --sandbox <bool>               Gemini sandbox mode (true/false) [default: false]
+  --timeout <seconds>            Default timeout per call [default: 300]
   --help, -h                     Show this help message
   --version, -v                  Show version number`);
 }
@@ -102,7 +103,7 @@ Options:
 /**
  * Parse CLI flags from process.argv.
  * Handles --help, --version, --provider, --model, --model_reasoning_effort, --sandbox, and unknown flags.
- * @returns {{ provider: string, model?: string, modelReasoningEffort?: string, sandbox: boolean }}
+ * @returns {{ provider: string, model?: string, modelReasoningEffort?: string, sandbox: boolean, defaultTimeoutMs?: number }}
  */
 function parseArgs() {
   const args = process.argv.slice(2);
@@ -110,6 +111,7 @@ function parseArgs() {
   let model;
   let modelReasoningEffort;
   let sandbox = false;
+  let defaultTimeoutMs;
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
@@ -153,17 +155,32 @@ function parseArgs() {
         }
         sandbox = args[++i] === "true";
         break;
+      case "--timeout": {
+        if (i + 1 >= args.length) {
+          process.stderr.write("error: --timeout requires a value\n");
+          process.exit(1);
+        }
+        const secs = Number(args[++i]);
+        if (!(secs > 0)) {
+          process.stderr.write("error: --timeout must be a positive number\n");
+          process.exit(1);
+        }
+        defaultTimeoutMs = Math.round(secs * 1000);
+        break;
+      }
       default:
         process.stderr.write(`error: unknown option: ${args[i]}\n`);
         process.exit(1);
     }
   }
 
-  return { provider, model, modelReasoningEffort, sandbox };
+  return { provider, model, modelReasoningEffort, sandbox, defaultTimeoutMs };
 }
 
 /**
  * Run a CLI command and return stdout (or stderr if stdout is empty).
+ * Uses spawn with detached:true so the entire process group can be killed
+ * on timeout — prevents orphan child processes.
  * @param {string} command
  * @param {string[]} args
  * @param {{ timeoutMs?: number, stdinData?: string }} [opts]
@@ -174,31 +191,17 @@ function runCli(command, args, opts = {}) {
   const stdinData = opts.stdinData;
 
   return new Promise((resolve, reject) => {
-    const child = execFile(
-      command,
-      args,
-      {
-        timeout: timeoutMs,
-        maxBuffer: MAX_BUFFER_BYTES,
-        env: { ...process.env, NO_COLOR: "1" },
-      },
-      (error, stdout, stderr) => {
-        if (error) {
-          const details = [
-            `${command} failed: ${error.message}`,
-            stderr ? `stderr:\n${stderr}` : null,
-          ]
-            .filter(Boolean)
-            .join("\n");
-
-          reject(new Error(details));
-          return;
-        }
-
-        const out = (stdout || stderr || "").trimEnd();
-        resolve(out);
-      },
-    );
+    let stdout = "";
+    let stderr = "";
+    let stdoutLen = 0;
+    let stderrLen = 0;
+    let settled = false;
+
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, NO_COLOR: "1" },
+    });
 
     // Pipe prompt via stdin to avoid arg-quoting issues, then close.
     child.stdin?.on("error", () => {}); // ignore EPIPE if child exits early
@@ -208,8 +211,59 @@ function runCli(command, args, opts = {}) {
       child.stdin?.end();
     }
 
+    const killGroup = () => {
+      try { process.kill(-child.pid, "SIGKILL"); } catch {}
+    };
+
+    const done = (err) => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      err ? reject(err) : resolve((stdout || stderr || "").trimEnd());
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdoutLen += chunk.length;
+      if (stdoutLen > MAX_BUFFER_BYTES) {
+        killGroup();
+        done(new Error(`${command} stdout maxBuffer exceeded`));
+      } else {
+        stdout += chunk;
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderrLen += chunk.length;
+      if (stderrLen > MAX_BUFFER_BYTES) {
+        killGroup();
+        done(new Error(`${command} stderr maxBuffer exceeded`));
+      } else {
+        stderr += chunk;
+      }
+    });
+
+    // Kill entire process group on timeout (prevents orphan processes).
+    const timer = setTimeout(() => {
+      killGroup();
+    }, timeoutMs);
+
     child.on("error", (err) => {
-      reject(new Error(`Failed to start ${command}: ${err.message}`));
+      done(new Error(`Failed to start ${command}: ${err.message}`));
+    });
+
+    child.on("close", (code, signal) => {
+      if (signal || code !== 0) {
+        const reason = signal ? `killed by ${signal}` : `exit code ${code}`;
+        const details = [
+          `${command} failed: ${reason}`,
+          stderr ? `stderr:\n${stderr}` : null,
+        ]
+          .filter(Boolean)
+          .join("\n");
+        done(new Error(details));
+        return;
+      }
+      done(null);
     });
   });
 }
@@ -220,28 +274,47 @@ function runCli(command, args, opts = {}) {
  */
 function runCodexPassthrough({ model, modelReasoningEffort }) {
   const args = [
-    "-m",
-    model || "gpt-5.3-codex",
-    "-s",
-    "read-only",
-    "-a",
-    "never",
-    "-c",
-    `model_reasoning_effort=${modelReasoningEffort || "high"}`,
     "mcp-server",
+    "-c", `model=${model || "gpt-5.3-codex"}`,
+    "-c", "sandbox_mode=read-only",
+    "-c", "approval_policy=never",
+    "-c", `model_reasoning_effort=${modelReasoningEffort || "high"}`,
   ];
 
   logErr(`[mcp-agents] passthrough: codex ${args.join(" ")}`);
 
-  const child = spawn("codex", args, { stdio: "inherit" });
+  const child = spawn("codex", args, {
+    stdio: ["inherit", "inherit", "pipe"],
+  });
+
+  child.stderr.on("data", (chunk) => {
+    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");
+        process.exit(128 + SIGNAL_CODES[sig]);
+      }, 5000).unref();
+    });
+  }
 
   child.on("error", (err) => {
     logErr(`[mcp-agents] failed to start codex: ${err.message}`);
     process.exitCode = 1;
   });
 
-  child.on("exit", (code) => {
-    process.exitCode = code ?? 1;
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      logErr(`[mcp-agents] codex killed by ${signal}`);
+      process.exitCode = 128 + (SIGNAL_CODES[signal] ?? 0);
+    } else {
+      if (code !== 0) logErr(`[mcp-agents] codex exited with code ${code}`);
+      process.exitCode = code ?? 1;
+    }
   });
 }
 
@@ -250,7 +323,7 @@ function runCodexPassthrough({ model, modelReasoningEffort }) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const { provider: providerName, model, modelReasoningEffort, sandbox } = parseArgs();
+  const { provider: providerName, model, modelReasoningEffort, sandbox, defaultTimeoutMs } = parseArgs();
   const backend = CLI_BACKENDS[providerName];
 
   if (!backend) {
@@ -274,6 +347,8 @@ async function main() {
     { capabilities: { tools: {} } },
   );
 
+  const effectiveTimeout = defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+
   const properties = {
     prompt: {
       type: "string",
@@ -282,7 +357,7 @@ async function main() {
     timeout_ms: {
       type: "integer",
       minimum: 1,
-      description: `Optional timeout override (default ${DEFAULT_TIMEOUT_MS})`,
+      description: `Optional timeout override (default ${effectiveTimeout}ms)`,
     },
     ...backend.extraProperties,
   };
@@ -333,7 +408,7 @@ async function main() {
     const timeoutMsRaw = params.arguments?.timeout_ms;
     const timeoutMs = Number.isInteger(timeoutMsRaw)
       ? timeoutMsRaw
-      : DEFAULT_TIMEOUT_MS;
+      : effectiveTimeout;
 
     if (!prompt.trim()) {
       return {