mcp-agents 0.5.7 → 0.6.0

package/README.md

@@ -196,7 +196,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.7",
+  "version": "0.6.0",
   "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

@@ -21,6 +21,9 @@ const VERSION = JSON.parse(
 const DEFAULT_TIMEOUT_MS = 300_000;
 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
@@ -40,21 +43,10 @@ const CLI_BACKENDS = {
     command: "gemini",
     toolName: "gemini",
     description:
-      "Run Gemini CLI (gemini -p) with a prompt. Supports prompt + optional timeout_ms/sandbox only; other arguments are ignored.",
+      "Run Gemini CLI with a prompt. Always runs in sandbox mode with --approval-mode=plan.",
     stdinPrompt: false,
-    buildArgs: (prompt, opts) => {
-      const args = [];
-      if (opts.sandbox === true) args.push("-s");
-      args.push("-p", prompt);
-      return args;
-    },
-    extraProperties: {
-      sandbox: {
-        type: "boolean",
-        default: false,
-        description: "Run in sandbox mode (-s flag). Defaults to false.",
-      },
-    },
+    buildArgs: (prompt) => ["-s", "--approval-mode=plan", "-p", prompt],
+    extraProperties: {},
   },
   codex: {
     passthrough: true,
@@ -124,7 +116,6 @@ 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]
-  --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`);
@@ -132,15 +123,14 @@ 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, defaultTimeoutMs?: number }}
+ * Handles --help, --version, --provider, --model, --model_reasoning_effort, and unknown flags.
+ * @returns {{ provider: string, model?: string, modelReasoningEffort?: string, defaultTimeoutMs?: number }}
  */
 function parseArgs() {
   const args = process.argv.slice(2);
   let provider = "codex";
   let model;
   let modelReasoningEffort;
-  let sandbox = false;
   let defaultTimeoutMs;
 
   for (let i = 0; i < args.length; i++) {
@@ -178,13 +168,6 @@ function parseArgs() {
         }
         modelReasoningEffort = args[++i];
         break;
-      case "--sandbox":
-        if (i + 1 >= args.length) {
-          process.stderr.write("error: --sandbox requires a value\n");
-          process.exit(1);
-        }
-        sandbox = args[++i] === "true";
-        break;
       case "--timeout": {
         if (i + 1 >= args.length) {
           process.stderr.write("error: --timeout requires a value\n");
@@ -204,7 +187,7 @@ function parseArgs() {
     }
   }
 
-  return { provider, model, modelReasoningEffort, sandbox, defaultTimeoutMs };
+  return { provider, model, modelReasoningEffort, defaultTimeoutMs };
 }
 
 /**
@@ -213,12 +196,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) => {
@@ -245,11 +235,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,
@@ -282,6 +274,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}`));
@@ -327,7 +320,6 @@ 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);
@@ -359,7 +351,7 @@ function runCodexPassthrough({ model, modelReasoningEffort }) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const { provider: providerName, model, modelReasoningEffort, sandbox, defaultTimeoutMs } = parseArgs();
+  const { provider: providerName, model, modelReasoningEffort, defaultTimeoutMs } = parseArgs();
   const backend = CLI_BACKENDS[providerName];
 
   if (!backend) {
@@ -374,14 +366,57 @@ async function main() {
     return;
   }
 
-  if (backend.extraProperties.sandbox) {
-    backend.extraProperties.sandbox.default = sandbox;
-  }
-
   const server = new Server(
     { 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;
 
@@ -428,6 +463,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: [
@@ -440,6 +482,7 @@ async function main() {
       };
     }
 
+    activeRequests += 1;
     const rawArgs =
       params.arguments && typeof params.arguments === "object"
         ? params.arguments
@@ -465,6 +508,8 @@ async function main() {
       : effectiveTimeout;
 
     if (!prompt.trim()) {
+      activeRequests -= 1;
+      maybeFinalizeShutdown();
       return {
         content: [
           {
@@ -485,13 +530,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
@@ -576,6 +638,9 @@ async function main() {
         content: [{ type: "text", text: msg }],
         isError: true,
       };
+    } finally {
+      activeRequests -= 1;
+      maybeFinalizeShutdown();
     }
   });
 
@@ -586,13 +651,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})`);
 }
 
@@ -600,15 +680,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);
 });