mcp-server-commands 0.6.0 → 0.7.2

package/README.md

@@ -1,13 +1,13 @@
 ## Tools
 
-Tools are for LLMs to request. Claude Sonnet 3.5 intelligently uses `run_command`. And, initial testing shows promising results with [Groq Desktop with MCP](https://github.com/groq/groq-desktop-beta) and `llama4` models.
+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.
 
 Currently, just one command to rule them all!
 
-- `run_command` - run a command, i.e. `hostname` or `ls -al` or `echo "hello world"` etc
+- `run_process` - run a command, i.e. `hostname` or `ls -al` or `echo "hello world"` etc
   - Returns `STDOUT` and `STDERR` as text
   - Optional `stdin` parameter means your LLM can
-    - pass code in `stdin` to commands like `fish`, `bash`, `zsh`, `python`
+    - pass scripts over `STDIN` to commands like `fish`, `bash`, `zsh`, `python`
     - create files with `cat >> foo/bar.txt` from the text in `stdin`
 
 > [!WARNING]
@@ -24,7 +24,9 @@ Currently, just one command to rule them all!
 
 Prompts are for users to include in chat history, i.e. via `Zed`'s slash commands (in its AI Chat panel)
 
-- `run_command` - generate a prompt message with the command output
+- `run_process` - generate a prompt message with the command output
+
+* FYI this was mostly a learning exercise... I see this as a user requested tool call. That's a fancy way to say, it's a template for running a command and passing the outputs to the model!
 
 ## Development
 
@@ -86,7 +88,7 @@ Make sure to run `npm run build`
 
 - Most models are trained such that they don't think they can run commands for you.
   - Sometimes, they use tools w/o hesitation... other times, I have to coax them.
-  - Use a system prompt or prompt template to instruct that they should follow user requests. Including to use `run_commands` without double checking.
+  - Use a system prompt or prompt template to instruct that they should follow user requests. Including to use `run_processs` without double checking.
 - Ollama is a great way to run a model locally (w/ Open-WebUI)
 
 ```sh

package/build/always_log.js

@@ -13,7 +13,7 @@ export function verbose_log(message, data) {
     // 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:
+    //   * SO, IIUC use STDERR for logging into Claude Desktop app logs in:
     //      '~/Library/Logs/Claude/mcp.log'
     if (verbose) {
         always_log(message, data);
@@ -39,6 +39,10 @@ export function verbose_log(message, data) {
     // 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));
     }

package/build/decide/spawn-sync.js

@@ -0,0 +1,31 @@
+import { spawnSync } from 'node:child_process';
+// NOTES:
+// - blocks event loop in exchange for convenience
+async function runSyncWithStdio(stdioValue) {
+    console.log("\n\n" + "=".repeat(20) + " run " + "=".repeat(20) + "\n");
+    const options = {
+        stdio: stdioValue,
+    };
+    console.log("options", options);
+    const command = "ls";
+    const args = ["-lh", "/usr"];
+    const result = spawnSync(command, args, options);
+    const chalk = (await import('chalk')).default;
+    console.log(chalk.green("\n## spawnSync COMPLETE\n"));
+    console.log("\n## spawnSync COMPLETE\n");
+    console.log("result", result);
+    if (result.stdout && result.stdout.byteLength > 0) {
+        console.log(`stdout (#${result.stdout.byteLength}):`, result.stdout.toString());
+    }
+    if (result.stderr && result.stderr.byteLength > 0) {
+        // PRN look for diff .length vs .byteLength => see if can find scenarios where they aren't mismatched in my codebases (for other purposes, i.e. RAG matches column offset calculations)
+        console.log(`stderr (#${result.stderr.byteLength}):`, result.stderr.toString());
+    }
+    return result;
+}
+// *** KEY setting => DO NOT USE "inherit" type behavior w/ MCP server 
+//   b/c then it is writing to the STDOUT/ERR and reading from STDIN that are intended for client to server JSON based comms only!
+//
+runSyncWithStdio("inherit"); // ls output is BEFORE result returned (b/c inherit means use parent process STDIN/OUT/ERR... so it writes immediately to STDOUT!
+// buffer STDOUT/ERR
+runSyncWithStdio("pipe"); // ls output is obtained after result returned (b/c piped to buffer)

package/build/decide/spawn.js

@@ -0,0 +1,92 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+async function ls() {
+    const ls = spawn('ls', ['-lh', '/usr']);
+    // NOTES:
+    // - spawn/spawnSync are the foundation of all other methods
+    // - async, non-blocking (event loop)
+    ls.stdout.on('data', (data) => {
+        console.log(`stdout: ${data}`);
+    });
+    ls.stderr.on('data', (data) => {
+        console.error(`stderr: ${data}`);
+    });
+    const [code] = await once(ls, 'close');
+    console.log(`child process exited with code ${code}`);
+}
+// await ls();
+async function cat_hello() {
+    const cat = spawn('cat');
+    cat.stdout.on('data', (data) => {
+        console.log(`stdout: ${data}`);
+    });
+    cat.stderr.on('data', (data) => {
+        console.error(`stderr: ${data}`);
+    });
+    cat.stdin.write("HEY FUCKTURD");
+    cat.stdin.end();
+    const [code] = await once(cat, 'close');
+    console.log(`child process exited with code ${code}`);
+}
+// await cat_hello();
+async function sleep_abort() {
+    const aborter = new AbortController();
+    const options = {};
+    // options.shell = ""
+    options.signal = aborter.signal;
+    const cat = spawn('sleep', ["5"], options);
+    if (cat.stdout) {
+        cat.stdout.on('data', (data) => {
+            console.log(`stdout: ${data}`);
+        });
+    }
+    if (cat.stderr) {
+        cat.stderr.on('data', (data) => {
+            console.error(`stderr: ${data}`);
+        });
+    }
+    cat.on('error', (err) => {
+        console.log("ERR", err);
+    });
+    aborter.abort();
+    const [code] = await once(cat, 'close');
+    console.log(`child process exited with code ${code}`);
+}
+// await sleep_abort();
+async function shells(child_process) {
+    if (child_process.stdout) {
+        child_process.stdout.on('data', (data) => {
+            console.log(`stdout: ${data}`);
+        });
+    }
+    if (child_process.stderr) {
+        child_process.stderr.on('data', (data) => {
+            console.error(`stderr: ${data}`);
+        });
+    }
+    child_process.on('error', (err) => {
+        console.log("ERR", err);
+    });
+    const [code] = await once(child_process, 'close');
+    console.log(`child process exited with code ${code}`);
+}
+await shells(spawn('echo', ["5"], { shell: false })); // works
+// await shells(spawn('echo 55', { shell: false })); // fails
+// *** pass only command arg w/ cmd+args and shell=true
+await shells(spawn('echo 66', { shell: true })); // works
+await shells(spawn('echo $fish_pid', { shell: true })); // no fish_pid (not fish shell) 
+await shells(spawn('echo $fish_pid', { shell: "fish" })); // works! fish shell!
+// await shells(spawn('echo', ["5"], { shell: true })); // works but w/ warning about args are just concatenated (not sanitized)
+// default shell info
+await shells(spawn("echo", ['$PATH'], { shell: false })); // verbatim prints "$PATH" b/c no shell
+await shells(spawn("echo", ['$PATH'], { shell: true })); // shows PATH variable value // warning too (first call w/ cmd,args array)
+await shells(spawn("echo", ['$$'], { shell: false })); // verbatim $$ printed (no shell) 
+await shells(spawn("echo", ['$$'], { shell: true })); // prints PID of default shell
+// await shells(spawn("set", { shell: true }));  // prints PID of default shell
+await shells(spawn("set -x; echo $0; echo $PATH; echo $BASH_VERSION", { shell: true })); // /bin/sh => bash in POSIX mode
+// $0 = /bin/sh (on mac/linux)
+// $BASH_VERSION
+await shells(spawn("declare", { shell: true })); //  dump default shell variables
+// await shells(spawn("ps", { shell: false })); // default shell info
+console.log("HERE:");
+await shells(spawn("echo", ['$PATH'])); // default is shell=false

package/build/exec-utils.js

@@ -1,62 +1,72 @@
-import { exec } from "child_process";
-/**
- * Executes a file with the given arguments, piping input to stdin.
- * @param {string} interpreter - The file to execute.
- * @param {string} stdin - The string to pipe to stdin.
- * @returns {Promise<ExecResult>}
- */
-function execFileWithInput(interpreter, stdin, options) {
-    // FYI for now, using `exec()` so the interpreter can have cmd+args AIO
-    //  could switch to `execFile()` to pass args array separately
-    // TODO starts with fish too? "fish -..." PRN use a library to parse the command and determine this?
-    if (interpreter.split(" ")[0] === "fish") {
-        // PRN also check error from fish and add possible clarification to error message though there are legit ways to trigger that same error message! i.e. `fish .` which is not the same issue!
-        return fishWorkaround(interpreter, stdin, options);
-    }
+// 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) => {
-        const child = exec(interpreter, options, (error, stdout, stderr) => {
-            if (error) {
-                // console.log("execFileWithInput ERROR:", error);
-                // mirror ExecException used by throws
-                error.stdout = stdout;
-                error.stderr = stderr;
-                reject(error);
-            }
-            else {
-                // I assume RC==0 else would trigger error?
-                resolve({ stdout, stderr });
-            }
-        });
-        if (stdin) {
-            if (child.stdin === null) {
-                reject(new Error("Unexpected failure: child.stdin is null"));
-                return;
-            }
+        if (!stdin) {
+            // FYI default is all 'pipe' (works when stdin is provided)
+            // 'ignore' attaches /dev/null
+            // order: [STDIN, STDOUT, STDERR]
+            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}`);
+        let stdout = "";
+        let stderr = "";
+        if (child.stdin && stdin) {
             child.stdin.write(stdin);
             child.stdin.end();
         }
-    });
-}
-async function fishWorkaround(interpreter, stdin, options) {
-    // fish right now chokes on piped input (STDIN) + node's exec/spawn/etc, so lets use a workaround to echo the input
-    // base64 encode thee input, then decode in pipeline
-    const base64stdin = Buffer.from(stdin).toString("base64");
-    const command = `${interpreter} -c "echo ${base64stdin} | base64 -d | fish"`;
-    return new Promise((resolve, reject) => {
-        // const child = ... // careful with refactoring not to return that unused child
-        exec(command, options, (error, stdout, stderr) => {
-            // I like this style of error vs success handling! it's beautiful-est (prommises are underrated)
-            if (error) {
-                // console.log("fishWorkaround ERROR:", error);
-                // mirror ExecException used by throws
-                error.stdout = stdout;
-                error.stderr = stderr;
-                reject(error);
-            }
-            else {
-                resolve({ stdout, stderr });
-            }
+        if (child.stdout) {
+            child.stdout.on("data", (chunk) => {
+                stdout += chunk.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on("data", (chunk) => {
+                stderr += chunk.toString();
+            });
+        }
+        let errored = false;
+        child.on("error", (err) => {
+            // 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,
+                //
+                code: err.code,
+                signal: err.signal,
+                //
+                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)
+            };
+            // console.log("ON_ERROR", result);
+            errored = true;
+            reject(result);
+        });
+        child.on("close", (code, signal) => {
+            // 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,
+                code: code ?? undefined,
+                signal: signal ?? undefined,
+            };
+            // console.log("ON_CLOSE", result);
+            resolve(result);
         });
     });
 }
-export { execFileWithInput };

package/build/messages.js

@@ -1,50 +1,79 @@
-/**
- * Converts an ExecResult into an array of TextContent messages.
- */
+export function resultFor(spawn_result) {
+    const result_obj = {
+        content: messagesFor(spawn_result),
+    };
+    if (spawn_result.code !== 0) {
+        result_obj.isError = true;
+    }
+    return result_obj;
+}
 export function messagesFor(result) {
     const messages = [];
     if (result.code !== undefined) {
+        // FYI include EXIT_CODE always, to make EXPLICIT when it is NOT a FAILURE!
+        //   will double underscore when a comman fails vs not stating if it was a failure
+        //   some commands give no other indication of success!
         messages.push({
-            type: "text",
-            text: `${result.code}`,
             name: "EXIT_CODE",
+            type: "text",
+            text: String(result.code),
         });
     }
-    // PRN any situation where I want to pass .message and/or .cmd?
-    // maybe on errors I should? that way there's a chance to make sure the command was as intended
-    // and maybe include message when it doesn't contain stderr?
-    // FYI if I put these back, start with tests first
-    // PRN use a test to add these, sleep 10s maybe and then kill that process?
-    //  definitely could be useful to know if a command was killed
-    //  make sure signal is not null, which is what's used when no signal killed the process
-    // if (result.signal) {
+    // // PRN map COMMAND for failures so model can adjust what it passes vs what actually ran?
+    // if ("cmd" in result && result.cmd) {
     //     messages.push({
+    //         name: "COMMAND",
     //         type: "text",
-    //         text: `Signal: ${result.signal}`,
-    //         name: "SIGNAL",
+    //         text: result.cmd,
     //     });
-    // } 
-    // if (!!result.killed) {
+    // }
+    if ("message" in result && result.message) {
+        // at least need error.message from spawn errors
+        messages.push({
+            name: "MESSAGE",
+            type: "text",
+            text: result.message,
+        });
+    }
+    if (result.signal) {
+        messages.push({
+            name: "SIGNAL",
+            type: "text",
+            text: result.signal,
+        });
+    }
+    // // when is this set? what conditions? I tried `kill -9` and didn't trigger "error" event
+    // if ("killed" in result && result.killed) {
     //     // killed == true is the only time to include this
     //     messages.push({
+    //         name: "KILLED",
     //         type: "text",
     //         text: "Process was killed",
-    //         name: "KILLED",
     //     });
     // }
     if (result.stdout) {
         messages.push({
+            name: "STDOUT",
             type: "text",
             text: result.stdout,
-            name: "STDOUT",
         });
     }
     if (result.stderr) {
         messages.push({
+            name: "STDERR",
             type: "text",
             text: result.stderr,
-            name: "STDERR",
         });
     }
     return messages;
 }
+export function errorResult(message) {
+    return {
+        isError: true,
+        content: [{
+                name: "ERROR",
+                type: "text",
+                text: message,
+            }],
+    };
+}

package/build/prompts.js

@@ -9,27 +9,22 @@ export function registerPrompts(server) {
         verbose_log("INFO: ListPrompts");
         return {
             prompts: [
-                // TODO! add prompts for various LLMs that tailor instructions to make them optimize use of run_command tool
+                // ?? add prompts for various LLMs that tailor instructions to make them optimize use of run_process tool
                 //  idea is, users could insert those manually, or perhaps automatically if necessary, depending on context
                 //  that way you don't need one prompt for everything and certain models won't need any help (i.e. Claude) vs
-                //  llama4 which struggled with old run_script tool (now just stdin on run_command) so it might need some
+                //  llama4 which struggled with old run_script tool (now just stdin on run_process) so it might need some
                 //  special instructions and yeah... I think that's a use case for these prompts
                 //  /prompt llama4 ?
                 {
-                    name: "examples",
-                    description: "Novel examples of run_command tool use to nudge models to the possibilities. " +
-                        "Based on assumption that most models understand shell commands/scripts very well.",
-                },
-                {
-                    name: "run_command",
+                    name: "run_process",
                     description: "Include command output in the prompt. " +
                         "This is effectively a user tool call.",
                     arguments: [
-                        {
-                            name: "command",
-                            required: true,
-                        },
-                        // if I care to keep the prompt tools then add stdin?
+                        { name: "mode", },
+                        { name: "command_line", },
+                        { name: "argv", },
+                        { name: "dry_run", },
+                        // ? other args?
                     ],
                 },
             ],
@@ -39,20 +34,21 @@ export function registerPrompts(server) {
         // if (request.params.name == "examples") {
         //     return GetExamplePromptMessages();
         // } else
-        if (request.params.name !== "run_command") {
+        if (request.params.name !== "run_process") {
             throw new Error("Unknown or not implemented prompt: " + request.params.name);
         }
         verbose_log("INFO: PromptRequest", request);
-        const command = String(request.params.arguments?.command);
-        if (!command) {
-            // TODO is there a format to follow for reporting failure like isError for tools?
-            throw new Error("Command is required");
-        }
+        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
         // - Fallback could be to configure on server level (i.e. home dir of current user) - perhaps CLI arg? (thinking of zed's context_servers config section)
-        const { stdout, stderr } = await execAsync(command);
+        // TODO RUN_PROCESS MIGRATION - finish rest of migrtation to run_process
+        const { stdout, stderr } = await execAsync(command_line);
         // TODO gracefully handle errors and turn them into a prompt message that can be used by LLM to troubleshoot the issue, currently errors result in nothing inserted into the prompt and instead it shows the Zed's chat panel as a failure
         const messages = [
             {
@@ -60,7 +56,7 @@ export function registerPrompts(server) {
                 content: {
                     type: "text",
                     text: "I ran the following command, if there is any output it will be shown below:\n" +
-                        command,
+                        command_line,
                 },
             },
         ];

package/build/run_process.js

@@ -0,0 +1,90 @@
+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;
+    }
+}

package/build/tools.js

@@ -1,36 +1,81 @@
 import os from "os";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { verbose_log } from "./always_log.js";
-import { runCommand } from "./run-command.js";
+import { runProcess } from "./run_process.js";
 export function reisterTools(server) {
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         verbose_log("INFO: ListTools");
         return {
+            // https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool // tool definition
+            // 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
             tools: [
                 {
-                    name: "run_command",
-                    description: "Run a command on this " + os.platform() + " machine",
+                    // TODO RUN_PROCESS MIGRATION! provide examples in system message, that way it is very clear how to use these!
+                    name: "run_process",
+                    description: "Run a process on this " + os.platform() + " machine",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            command: {
+                            // 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: "Command with args",
+                                description: "Shell command line. Required when mode='shell'. Forbidden when mode='executable'."
+                            },
+                            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'."
                             },
-                            workdir: {
-                                // previous run_command calls can probe the filesystem and find paths to change to
+                            cwd: {
+                                // or "workdir" like before? => eval model behavior w/ each name?
                                 type: "string",
-                                description: "Optional, current working directory",
+                                description: "Optional to set working directory",
                             },
                             stdin: {
                                 type: "string",
-                                description: "Optional, text to pipe into the command's STDIN. For example, pass a python script to python3. Or, pass text for a new file to the cat command to create it!",
+                                description: "Optional text written to STDIN (written fully, then closed). Useful for heredoc-style input or file contents."
+                            },
+                            timeout_ms: {
+                                type: "number",
+                                description: "Optional timeout in milliseconds, defaults to 30,000ms",
                             },
-                            // args to consider:
+                            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?
-                            // - timeout - lets just hard code this for now
                         },
-                        required: ["command"],
+                        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"] }
+                        //     }
+                        // ]
                     },
                 },
             ],
@@ -39,8 +84,8 @@ export function reisterTools(server) {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         verbose_log("INFO: ToolRequest", request);
         switch (request.params.name) {
-            case "run_command": {
-                return await runCommand(request.params.arguments);
+            case "run_process": {
+                return await runProcess(request.params.arguments);
             }
             default:
                 throw new Error("Unknown tool");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-server-commands",
-    "version": "0.6.0",
+    "version": "0.7.2",
     "description": "An MCP server to run arbitrary commands",
     "private": false,
     "type": "module",
@@ -18,7 +18,9 @@
         "inspector": "npx @modelcontextprotocol/inspector build/index.js",
         "test": "jest",
         "test:watch": "jest --watch",
-        "test:integration": "jest tests/integration"
+        "test:integration-all": "jest tests/integration",
+        "test:watch:integration-all": "jest --watch tests/integration",
+        "test:watch:integration-run_process": "jest --watch tests/integration/run_process.test.ts"
     },
     "dependencies": {
         "@modelcontextprotocol/sdk": "1.9.0"
@@ -26,6 +28,7 @@
     "devDependencies": {
         "@types/jest": "^29.5.14",
         "@types/node": "^22.14.1",
+        "chalk": "^5.6.2",
         "jest": "^29.7.0",
         "ts-jest": "^29.3.2",
         "typescript": "^5.8.3"

package/build/run-command.js

@@ -1,61 +0,0 @@
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
-import { execFileWithInput } from "./exec-utils.js";
-import { always_log } from "./always_log.js";
-import { messagesFor } from "./messages.js";
-const execAsync = promisify(exec);
-async function execute(command, stdin, options) {
-    // PRN merge calls to exec into one single paradigm with conditional STDIN handled in one spot?
-    //   right now no STDIN => exec directly and let it throw to catch failures
-    //   w/ STDIN => you manually glue together callbacks + promises (i.e. reject)
-    //     feels sloppy to say the least, notably the error handling with ExecExeption error that has stdin/stderr on it
-    if (!stdin) {
-        return await execAsync(command, options);
-    }
-    return await execFileWithInput(command, stdin, options);
-}
-export async function runCommand(args) {
-    const command = args?.command;
-    if (!command) {
-        const message = "Command is required, current value: " + command;
-        return {
-            isError: true,
-            content: [{ type: "text", text: message }],
-        };
-    }
-    const options = { encoding: "utf8" };
-    if (args?.workdir) {
-        options.cwd = String(args.workdir);
-    }
-    const stdin = args?.stdin;
-    try {
-        const result = await execute(command, stdin, options);
-        return {
-            content: messagesFor(result),
-        };
-    }
-    catch (error) {
-        // PRN do I want to differentiate non-command related error (i.e. if messagesFor blows up
-        //   or presumably if smth else goes wrong with the node code in exec that isn't command related
-        //   if so, write a test first
-        // console.log("ERROR_runCommand", error);
-        // ExecException (error + stdout/stderr) merged
-        // - IIUC this happens on uncaught failures
-        // - but if you catch an exec() promise failure (or use exec's callback) => you get separated values: error, stdout, stderr
-        // - which is why I mirror this response type in my reject(error) calls
-        //
-        // 'error' example:
-        // code: 127,
-        // killed: false,
-        // signal: null,
-        // cmd: 'nonexistentcommand',
-        // stdout: '',
-        // stderr: '/bin/sh: nonexistentcommand: command not found\n'
-        const response = {
-            isError: true,
-            content: messagesFor(error),
-        };
-        always_log("WARN: run_command failed", response);
-        return response;
-    }
-}