mcp-server-commands 0.7.4 → 0.8.0

package/README.md

@@ -1,3 +1,16 @@
+## `runProcess` tool
+
+The `runProcess` tool runs processes on the host machine. There are two mutually exclusive ways to invoke it:
+
+1. **`command_line`** (string) — Executed via the system's default shell (just like typing into `bash`/`fish`/`pwsh`/etc). Shell features like pipes, redirects, and variable expansion all work.
+2. **`argv`** (string array) — Direct executable invocation. `argv[0]` is the executable, the rest are arguments. No shell interpretation.
+
+You cannot pass both. The tool infers whether to use a shell from which parameter you provide.
+
+If you want your model to use specific shell(s) on a system, I would list them in your system prompt. Or, maybe in your tool instructions, though models tend to pay better attention to examples in a system prompt.
+
+Let me know if you encounter problems!
+
 ## Tools
 
 Tools are for LLMs to request. Claude Sonnet 3.5 intelligently uses `run_process`. And, initial testing shows promising results with [Groq Desktop with MCP](https://github.com/groq/groq-desktop-beta) and `llama4` models.

package/build/exec-utils.js

@@ -1,17 +1,82 @@
 // TODO cleanup exec usages once spawn is ready
 import { spawn } from "child_process";
-export async function spawn_wrapped(command, args, stdin, options) {
-    return new Promise((resolve, reject) => {
+import { performance } from "perf_hooks";
+import { is_verbose, verbose_log } from "./logging.js";
+import { resultFor } from "./messages.js";
+import { errorResult } from "./messages.js";
+export function runProcess(runProcessArgs) {
+    const startTime = performance.now();
+    const options = {
+        // spawn options: https://nodejs.org/api/child_process.html#child_processspawncommand-args-options
+        encoding: "utf8"
+    };
+    if (runProcessArgs?.cwd) {
+        options.cwd = String(runProcessArgs.cwd);
+    }
+    const stdin = runProcessArgs?.stdin ? String(runProcessArgs.stdin) : undefined;
+    // ---------------------------------------------------------------------
+    // RunProcess argument handling – determine the actual command and args.
+    // ---------------------------------------------------------------------
+    const isShellMode = Boolean(runProcessArgs?.command_line);
+    const isExecutableMode = Array.isArray(runProcessArgs?.argv) && (runProcessArgs?.argv).length > 0;
+    if (isShellMode && isExecutableMode) {
+        return Promise.resolve(errorResult("Cannot pass both 'command_line' and 'argv'. Use one or the other."));
+    }
+    if (!isShellMode && !isExecutableMode) {
+        return Promise.resolve(errorResult("Either 'command_line' (string) or 'argv' (array) is required."));
+    }
+    // Resolve the command/args based on the mode.
+    let execCommand = "";
+    let execArgs = [];
+    if (isShellMode) {
+        options.shell = true;
+        execCommand = String(runProcessArgs.command_line);
+        execArgs = [];
+    }
+    else {
+        options.shell = false;
+        const argv = runProcessArgs?.argv;
+        execCommand = argv[0];
+        execArgs = argv.slice(1);
+    }
+    const logWithElapsedTime = (msg, ...rest) => {
+        if (!is_verbose)
+            return;
+        const elapsed = ((performance.now() - startTime) / 1000).toFixed(3);
+        verbose_log(`[${elapsed}s] ${msg}`, ...rest, execCommand, execArgs);
+    };
+    let child_pid;
+    const promise = new Promise((resolve, reject) => {
         if (!stdin) {
-            // FYI default is all 'pipe' (works when stdin is provided)
-            // 'ignore' attaches /dev/null
-            // order: [STDIN, STDOUT, STDERR]
+            // PRN windowsHide on Windows, signal, killSignal
+            // FYI spawn_options.stdio => default is perfect ['pipe', 'pipe', 'pipe'] 
+            //     order: [STDIN, STDOUT, STDERR]
+            //     https://nodejs.org/api/child_process.html#optionsstdio 
+            //     'ignore' attaches /dev/null
+            //     do not set 'inherit' (causes ripgrep to see STDIN socket and search it, thus hanging)
             options.stdio = ['ignore', 'pipe', 'pipe'];
-            // ? I wonder if this was related to fishWorkaround issue w/ STDIN (see commit history)... I was using base64 encoding to pass STDIN
         }
-        const child = spawn(command, args, options);
-        // PRN return pid to callers?
-        // console.log(`child.pid: ${child.pid}`);
+        // remove timeout on spawn options (if set) so the built‑in spawn timeout does not interfere
+        delete options.timeout;
+        // Use a detached child so we can kill the entire process group.
+        options.detached = true;
+        let settled = false;
+        const settle = (result, isError) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (isError) {
+                resolve(resultFor(result));
+            }
+            else {
+                resolve(resultFor(result));
+            }
+        };
+        const child = spawn(execCommand, execArgs, options);
+        logWithElapsedTime(`START SPAWN child.pid: ${child.pid}`);
+        child_pid = child.pid;
         let stdout = "";
         let stderr = "";
         if (child.stdin && stdin) {
@@ -28,45 +93,94 @@ export async function spawn_wrapped(command, args, stdin, options) {
                 stderr += chunk.toString();
             });
         }
-        let errored = false;
+        child.on("exit", (code, signal) => {
+            // child process streams MAY still be open when EXIT is emitted (use close if need to ensure they're closed)
+            // "close" will come after "exit" once process is terminated + streams are closed
+            // so for now use "close" to determine if process was terminated too, that way you can access STDOUT/STDERR reliably for returning full output to agent
+            logWithElapsedTime("EXIT", { code, signal });
+        });
+        child.on("spawn", () => {
+            // emitted after child process starts successfully
+            // if child doesn't start, error emitted instead
+            // emitted BEFORE any data received via stdout/stderr
+            logWithElapsedTime("SPAWN");
+        });
+        // Timeout handling – kill the whole process group after the supplied timeout.
+        let timer = null;
+        let timeoutMs = Number(runProcessArgs?.timeout_ms);
+        if (Number.isNaN(timeoutMs)) {
+            timeoutMs = 30_000;
+        }
+        timer = setTimeout(() => {
+            if (process.platform !== "win32") {
+                if (child.pid) {
+                    try {
+                        process.kill(-child.pid, "SIGTERM");
+                    }
+                    catch (_) { }
+                }
+            }
+            else {
+                child.kill("SIGTERM");
+            }
+            const killTimeout = setTimeout(() => {
+                if (process.platform !== "win32") {
+                    if (child.pid) {
+                        try {
+                            process.kill(-child.pid, "SIGKILL");
+                        }
+                        catch (_) { }
+                    }
+                }
+                else {
+                    child.kill("SIGKILL");
+                }
+            }, 2000);
+            const clearKill = () => clearTimeout(killTimeout);
+            child.once("exit", clearKill);
+            child.once("close", clearKill);
+        }, timeoutMs);
         child.on("error", (err) => {
+            logWithElapsedTime("ERROR");
             // ChildProcess 'error' docs: https://nodejs.org/api/child_process.html#event-error
             // error running process
             // IIUC not just b/c of command failed w/ non-zero exit code
             const result = {
-                stdout: stdout,
-                stderr: stderr,
+                stdout,
+                stderr,
                 //
-                code: err.code,
-                signal: err.signal,
+                // one of these will always be non-null
+                code: err.code, // set if process exited, else null
+                signal: err.signal, // set if process was terminated by signal, else null
                 //
                 message: err.message,
-                // killed: (err as any).killed,
-                cmd: command, // TODO does error have .cmd on it? is it the composite result of processing in spawn too? (or same as I passed)
+                // ? killed: (err as any).killed
             };
-            // console.log("ON_ERROR", result);
-            errored = true;
-            reject(result);
+            logWithElapsedTime("ERROR_RESULT", result);
+            settle(result, true);
         });
         child.on("close", (code, signal) => {
+            logWithElapsedTime("CLOSE");
             // ChildProcess 'close' docs: https://nodejs.org/api/child_process.html#event-close
             //   'close' is after child process ends AND stdio streams are closed
             //   - after 'exit' or 'error'
-            //
-            // * do not resolve if 'error' already called (promise is already resolved)
-            if (errored)
-                return;
             //   either code is set, or signal, but NOT BOTH
             //   signal if process killed
             // FYI close does not mean code==0
             const result = {
-                stdout: stdout,
-                stderr: stderr,
+                stdout,
+                stderr,
+                //
                 code: code ?? undefined,
                 signal: signal ?? undefined,
+                //
             };
-            // console.log("ON_CLOSE", result);
-            resolve(result);
+            logWithElapsedTime("CLOSE_RESULT", result);
+            settle(result, false);
         });
     });
+    // FYI later (when needed) I can map this onto the promise that comes back from runProcess too (and tie into that unit test I have that needs pid to terminate it)
+    // Resolve the underlying spawn result, then map to CallToolResult including PID.
+    promise.pid = child_pid;
+    return promise;
 }

package/build/index.js

@@ -4,7 +4,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "module";
 import { registerPrompts } from "./prompts.js";
-import { reisterTools } from "./tools.js";
+import { registerTools } from "./tools.js";
 const require = createRequire(import.meta.url);
 const { name: package_name, version: package_version, } = require("../package.json");
 const server = new Server({
@@ -19,7 +19,7 @@ const server = new Server({
         //logging: {}, // for logging messages that don't seem to work yet or I am doing them wrong
     },
 });
-reisterTools(server);
+registerTools(server);
 registerPrompts(server);
 async function main() {
     const transport = new StdioServerTransport();

package/build/logging.js

@@ -0,0 +1,51 @@
+import fs from 'fs';
+export let is_verbose = false;
+if (process.argv.includes("--verbose")) {
+    is_verbose = true;
+}
+const isJest = typeof process !== 'undefined' && !!process.env.JEST_WORKER_ID;
+if (isJest) {
+    // is_verbose = true; // comment out to disable verbose logging in JEST test runner
+}
+if (is_verbose) {
+    always_log("INFO: verbose logging enabled");
+}
+export function verbose_log(message, data) {
+    if (is_verbose) {
+        always_log(message, data);
+    }
+}
+export function always_log(message, data) {
+    // LOGGING NOTES:
+    // https://modelcontextprotocol.io/docs/tools/debugging#implementing-logging
+    // * STDIO transport => STDERR captured by host app (i.e. Claude Desktop which writes to ~/Library/Logs/Claude/mcp.log)
+    // * Streamable HTTP transport => suggests server side capture (i.e. log file)
+    // * and/or log to MCP client regardless of transport
+    //   server.sendLoggingMessage({
+    //       level: "info",
+    //       data: message,
+    //   });
+    //   // sends a message like:
+    //   server.notification({
+    //      method: "notifications/message",
+    //      params: {
+    //          level: "warning",
+    //          logger: "mcp-server-commands",
+    //          data: "ListToolsRequest2",
+    //      },
+    //   });
+    if (isJest) {
+        // * JEST => log to console so I can see in test runner output
+        console.log(`${message}${data ? ": " + JSON.stringify(data) : ""}`);
+        return;
+    }
+    // * all transports => server side log file
+    const timestamp = new Date().toISOString();
+    const logMessage = `[${timestamp}] ${message}${data ? ": " + JSON.stringify(data) : ""}`;
+    const shareDir = process.env.HOME + "/.local/share/mcp-server-commands/";
+    const logFile = shareDir + "/commands.log";
+    fs.mkdirSync(shareDir, { recursive: true });
+    fs.appendFileSync(logFile, logMessage + "\n");
+    // TODO any hail mary if this logging fails? just use console.error then?
+    //   else still can get seemingly hung tool calls
+}

package/build/prompts.js

@@ -1,5 +1,5 @@
 import { GetPromptRequestSchema, ListPromptsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { verbose_log } from "./always_log.js";
+import { verbose_log } from "./logging.js";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 const execAsync = promisify(exec);
@@ -20,10 +20,8 @@ export function registerPrompts(server) {
                     description: "Include command output in the prompt. " +
                         "This is effectively a user tool call.",
                     arguments: [
-                        { name: "mode", },
                         { name: "command_line", },
                         { name: "argv", },
-                        { name: "dry_run", },
                         // ? other args?
                     ],
                 },
@@ -41,8 +39,6 @@ export function registerPrompts(server) {
         throw new Error("run_process not yet ported to prompts");
         const command_line = String(request.params.arguments?.command_line);
         const argv = String(request.params.arguments?.argv);
-        const mode = String(request.params.arguments?.mode);
-        const dry_run = Boolean(request.params.arguments?.dry_run);
         // Is it possible/feasible to pass a path for the workdir when running the command?
         // - currently it uses / (yikez)
         // - IMO makes more sense to have it be based on the Zed workdir of each project

package/build/tools.js

@@ -1,8 +1,8 @@
 import os from "os";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { verbose_log } from "./always_log.js";
-import { runProcess } from "./run_process.js";
-export function reisterTools(server) {
+import { verbose_log } from "./logging.js";
+import { runProcess } from "./exec-utils.js";
+export function registerTools(server) {
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         verbose_log("INFO: ListTools");
         return {
@@ -10,6 +10,8 @@ export function reisterTools(server) {
             // https://modelcontextprotocol.io/docs/learn/architecture#understanding-the-tool-execution-request // tool request/response
             // typescript SDK docs:
             //   servers: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md
+            //   TODO upgrade to newer version AND check if STDIO delimiter style has changed to include content-length "header" before responses? 
+            //     OR is there an opt-in for this style vs what I get with my simple nvim uv.spawn nvim client... where \n terminates/delimits each message
             tools: [
                 {
                     // TODO RUN_PROCESS MIGRATION! provide examples in system message, that way it is very clear how to use these!
@@ -19,23 +21,15 @@ export function reisterTools(server) {
                         type: "object",
                         properties: {
                             // ListToolsResult => Tool type (in protocol) => https://modelcontextprotocol.io/specification/2025-06-18/schema#tool
-                            // * appears I can do w/e I want to describe properties (as long as give a string key (name)) => hence enum below
-                            mode: {
-                                enum: ["shell", "executable"], // * I made this up
-                                description: "What are you running, two choices: 'shell' or 'executable' (required, no default)",
-                                // FYI only use default system shell, if the model wants a different shell, can explicitly run it with command_line/argv
-                                //   DO NOT duplicate the mechanism of specifying what runs by adding yet another executable field!
-                                //   spawn's options.shell is bool/string... string is command_name/path... that duplicates and complicates needlessly!
-                            },
                             command_line: {
                                 type: "string",
-                                description: "Shell command line. Required when mode='shell'. Forbidden when mode='executable'."
+                                description: "Shell mode: a shell command line executed via the system's default shell. Supports pipes, redirects, globbing. Cannot be combined with 'argv'."
                             },
                             argv: {
                                 minItems: 1, // * made up too
                                 type: "array",
                                 items: { type: "string" },
-                                description: "Executable and arguments. argv[0] is the executable. Required when mode='executable'. Forbidden when mode='shell'."
+                                description: "Executable mode: directly spawn a process. argv[0] is the executable, followed by arguments passed verbatim (no shell interpretation). Cannot be combined with 'command_line'."
                             },
                             cwd: {
                                 // or "workdir" like before? => eval model behavior w/ each name?
@@ -49,33 +43,10 @@ export function reisterTools(server) {
                             timeout_ms: {
                                 type: "number",
                                 description: "Optional timeout in milliseconds, defaults to 30,000ms",
-                            },
-                            dry_run: {
-                                type: "boolean",
-                                description: "Optional explain what would run, defaults to False."
-                                // FYI this can help avoid the need for logging this information, I can call this as a user too!
-                                // TODO, dump info about shell (if applicable) and program versions!
-                                //  - explain the node calls too, i.e. spawn('echo foo')
-                                //  - show paths of resolved resources (i.e. shell)
-                                //  - i.e. could run command --version to see its version (attempt various flags until one works, and/or have a lookup of common tools to know how to find their version)
                             }
-                            // MAYBEs:
-                            // - env - obscure cases where command takes a param only via an env var?
                         },
-                        required: ["mode"],
-                        // PRN add proprietary constraints explanation? only if model seems to struggle and there isn't a better fix...
-                        // oneOf: [
-                        //     {
-                        //         properties: { mode: { const: "shell" } },
-                        //         required: ["command_line"],
-                        //         not: { required: ["argv"] }
-                        //     },
-                        //     {
-                        //         properties: { mode: { const: "executable" } },
-                        //         required: ["argv"],
-                        //         not: { required: ["command_line"] }
-                        //     }
-                        // ]
+                        // FYI no required arg top level and I am not gonna fret about specifiying one or the other, the tool definition is fine with that distinction in the descriptions, plus it is intuitive.
+                        //  and back when I had mode=shell/executable required, models would still forget to add it so why bother with a huge complexity in tool definition
                     },
                 },
             ],
@@ -85,7 +56,13 @@ export function reisterTools(server) {
         verbose_log("INFO: ToolRequest", request);
         switch (request.params.name) {
             case "run_process": {
-                return await runProcess(request.params.arguments);
+                if (!request.params.arguments) {
+                    throw new Error("Missing arguments for run_process");
+                }
+                const result = await runProcess(request.params.arguments);
+                // FYI logging this response is INVALUABLE! found a problem with my neovim MCP STDIO client!
+                verbose_log("INFO: ToolResponse", result);
+                return result;
             }
             default:
                 throw new Error("Unknown tool");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-server-commands",
-    "version": "0.7.4",
+    "version": "0.8.0",
     "description": "An MCP server to run arbitrary commands",
     "private": false,
     "type": "module",

package/build/always_log.js

@@ -1,52 +0,0 @@
-let verbose = false;
-// check CLI args:
-if (process.argv.includes("--verbose")) {
-    verbose = true;
-}
-if (verbose) {
-    always_log("INFO: verbose logging enabled");
-}
-export function verbose_log(message, data) {
-    // https://modelcontextprotocol.io/docs/tools/debugging - mentions various ways to debug/troubleshoot (including dev tools)
-    //
-    // remember STDIO transport means can't log over STDOUT (client expects JSON messages per the spec)
-    // https://modelcontextprotocol.io/docs/tools/debugging#implementing-logging
-    //   mentions STDERR is captured by the host app (i.e. Claude Desktop app)
-    //   server.sendLoggingMessage is captured by MCP client (not Claude Desktop app)
-    //   * SO, IIUC use STDERR for logging into Claude Desktop app logs in:
-    //      '~/Library/Logs/Claude/mcp.log'
-    if (verbose) {
-        always_log(message, data);
-    }
-    // inspector, catches these logs and shows them on left hand side of screen (sidebar)
-    // TODO add verbose parameter (CLI arg?)
-    // IF I wanted to log via MCP client logs (not sure what those are/do):
-    //  I do not see inspector catching these logs :(, there is a server notifications section and it remains empty
-    //server.sendLoggingMessage({
-    //    level: "info",
-    //    data: message,
-    //});
-    // which results in something like:
-    //server.notification({
-    //    method: "notifications/message",
-    //    params: {
-    //        level: "warning",
-    //        logger: "mcp-server-commands",
-    //        data: "ListToolsRequest2",
-    //    },
-    //});
-    //
-    // FYI client should also requets a log level from the server, so that needs to be here at some point too
-}
-export function always_log(message, data) {
-    const isJest = typeof process !== 'undefined' && !!process.env.JEST_WORKER_ID;
-    if (isJest) {
-        return;
-    }
-    if (data) {
-        console.error(message + ": " + JSON.stringify(data));
-    }
-    else {
-        console.error(message);
-    }
-}

package/build/run_process.js

@@ -1,90 +0,0 @@
-import { spawn_wrapped } from "./exec-utils.js";
-import { always_log } from "./always_log.js";
-import { errorResult, messagesFor, resultFor } from "./messages.js";
-export async function runProcess(args) {
-    const command_line = args?.command_line;
-    const argv = args?.argv;
-    const mode = String(args?.mode);
-    if (!mode) {
-        return errorResult("Mode is required");
-    }
-    const isShell = mode === "shell";
-    const isExecutable = mode === "executable";
-    if (!isShell && !isExecutable) {
-        return errorResult(`Invalid mode '${mode}'. Allowed values are 'shell' or 'executable'.`);
-    }
-    // * shared args
-    const spawn_options = {
-        // spawn options: https://nodejs.org/api/child_process.html#child_processspawncommand-args-options
-        encoding: "utf8"
-    };
-    if (args?.cwd) {
-        spawn_options.cwd = String(args.cwd);
-    }
-    // PRN args.env
-    if (args?.timeout_ms) {
-        spawn_options.timeout = Number(args.timeout_ms);
-    }
-    else {
-        // default timeout after 30s
-        spawn_options.timeout = 30000;
-    }
-    // PRN windowsHide on Windows, signal, killSignal
-    // FYI spawn_options.stdio => default is perfect ['pipe', 'pipe', 'pipe'] https://nodejs.org/api/child_process.html#optionsstdio 
-    //   do not set inherit (this is what causes ripgrep to see STDIN socket and search it, thus hanging)
-    const stdin = args?.stdin ? String(args.stdin) : undefined; // TODO
-    const dryRun = Boolean(args?.dry_run);
-    try {
-        if (dryRun) {
-            // Build a descriptive plan without executing anything
-            let plan = '';
-            if (isShell) {
-                const cmd = String(args?.command_line);
-                const shell = process.env.SHELL || (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh');
-                plan = `Shell mode: will execute command_line via ${shell}: ${cmd}`;
-            }
-            else if (isExecutable) {
-                const argv = args?.argv;
-                plan = `Executable mode: will spawn '${argv[0]}' with arguments ${JSON.stringify(argv.slice(1))}`;
-            }
-            return { content: [{ name: "PLAN", type: "text", text: plan }] };
-        }
-        if (isShell) {
-            if (!args?.command_line) {
-                return errorResult("Mode 'shell' requires a non‑empty 'command_line' parameter.");
-            }
-            if (args?.argv) {
-                return errorResult("Mode 'shell' does not accept an 'argv' parameter.");
-            }
-            spawn_options.shell = true;
-            const command_line = String(args?.command_line);
-            const result = await spawn_wrapped(command_line, [], stdin, spawn_options);
-            return resultFor(result);
-        }
-        if (isExecutable) {
-            const argv = args?.argv;
-            if (!Array.isArray(argv) || argv.length === 0) {
-                return errorResult("Mode 'executable' requires a non‑empty 'argv' array.");
-            }
-            if (args?.command_line) {
-                return errorResult("Mode 'executable' does not accept a 'command_line' parameter.");
-            }
-            spawn_options.shell = false;
-            const command = argv[0];
-            const commandArgs = argv.slice(1);
-            const result = await spawn_wrapped(command, commandArgs, stdin, spawn_options);
-            return resultFor(result);
-        }
-        // TODO... fish shell workaround (see exec-utils.ts) - ADD or FIX via a TEST FIRST
-        return errorResult("Unexpected execution path in runProcess, should not be possible");
-    }
-    catch (error) {
-        // TODO check if not SpawnFailure => i.e. test aborting/killing
-        const response = {
-            isError: true,
-            content: messagesFor(error),
-        };
-        always_log("WARN: run_process failed", error);
-        return response;
-    }
-}