mcp-agents 0.5.2 → 0.5.4

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.
@@ -44,7 +57,9 @@ Each `--provider` flag maps to a single exposed tool:
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `prompt` | `string` | yes | The prompt to send to Claude Code |
-| `timeout_ms` | `integer` | no | Timeout in ms (default: 120 000) |
+| `timeout_ms` | `integer` | no | Timeout in ms (default: 300 000 / 5 minutes) |
+
+Any additional `tools/call` arguments are ignored (for example `model` or `model_reasoning_effort`).
 
 ### `gemini` parameters
 
@@ -52,68 +67,98 @@ Each `--provider` flag maps to a single exposed tool:
 |-----------|------|----------|-------------|
 | `prompt` | `string` | yes | The prompt to send to Gemini CLI |
 | `sandbox` | `boolean` | no | Run in sandbox mode (`-s` flag, default: false) |
-| `timeout_ms` | `integer` | no | Timeout in ms (default: 120 000) |
+| `timeout_ms` | `integer` | no | Timeout in ms (default: 300 000 / 5 minutes) |
+
+Any additional `tools/call` arguments are ignored (for example `model` or `model_reasoning_effort`).
 
 ### `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"]
     }
   }
 }
 ```
 
-Override codex defaults:
+Override codex defaults at server startup (not via `tools/call` arguments):
+
+```json
+{
+  "mcpServers": {
+    "codex": {
+      "command": "mcp-agents",
+      "args": ["--provider", "codex", "--model", "gpt-5.3-codex", "--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.2",
+  "version": "0.5.4",
   "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

@@ -29,7 +29,8 @@ const CLI_BACKENDS = {
   claude: {
     command: "claude",
     toolName: "claude_code",
-    description: "Run Claude Code CLI with a prompt (via stdin).",
+    description:
+      "Run Claude Code CLI with a prompt (via stdin). Supports prompt + optional timeout_ms only; other arguments are ignored.",
     stdinPrompt: true,
     buildArgs: () => ["--no-session-persistence", "-p"],
     extraProperties: {},
@@ -37,7 +38,8 @@ const CLI_BACKENDS = {
   gemini: {
     command: "gemini",
     toolName: "gemini",
-    description: "Run Gemini CLI (gemini -p) with a prompt.",
+    description:
+      "Run Gemini CLI (gemini -p) with a prompt. Supports prompt + optional timeout_ms/sandbox only; other arguments are ignored.",
     stdinPrompt: false,
     buildArgs: (prompt, opts) => {
       const args = [];
@@ -92,8 +94,8 @@ 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
@@ -274,28 +276,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;
+    }
   });
 }
 
@@ -333,7 +354,7 @@ async function main() {
   const properties = {
     prompt: {
       type: "string",
-      description: `Prompt for ${backend.command}`,
+      description: `Prompt for ${backend.command}. Unsupported extra arguments are ignored.`,
     },
     timeout_ms: {
       type: "integer",
@@ -360,7 +381,7 @@ async function main() {
         description: backend.description,
         inputSchema: {
           type: "object",
-          additionalProperties: false,
+          additionalProperties: true,
           properties,
           required: ["prompt"],
         },
@@ -385,8 +406,26 @@ async function main() {
       };
     }
 
-    const prompt = toStringArg(params.arguments?.prompt);
-    const timeoutMsRaw = params.arguments?.timeout_ms;
+    const rawArgs =
+      params.arguments && typeof params.arguments === "object"
+        ? params.arguments
+        : {};
+    const allowedArgKeys = new Set([
+      "prompt",
+      "timeout_ms",
+      ...Object.keys(backend.extraProperties),
+    ]);
+    const ignoredArgKeys = Object.keys(rawArgs).filter(
+      (key) => !allowedArgKeys.has(key),
+    );
+    if (ignoredArgKeys.length > 0) {
+      logErr(
+        `[mcp-agents] tools/call: ignoring unsupported args: ${ignoredArgKeys.join(", ")}`,
+      );
+    }
+
+    const prompt = toStringArg(rawArgs.prompt);
+    const timeoutMsRaw = rawArgs.timeout_ms;
     const timeoutMs = Number.isInteger(timeoutMsRaw)
       ? timeoutMsRaw
       : effectiveTimeout;
@@ -405,7 +444,7 @@ async function main() {
 
     const extraOpts = {};
     for (const key of Object.keys(backend.extraProperties)) {
-      extraOpts[key] = params.arguments?.[key] ?? backend.extraProperties[key].default;
+      extraOpts[key] = rawArgs[key] ?? backend.extraProperties[key].default;
     }
 
     const cliArgs = backend.stdinPrompt