mcp-server-commands 0.5.0 → 0.7.3

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
 
@@ -82,6 +84,42 @@ Make sure to run `npm run build`
 }
 ```
 
+## Local Models
+
+- 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_processs` without double checking.
+- Ollama is a great way to run a model locally (w/ Open-WebUI)
+
+```sh
+# NOTE: make sure to review variants and sizes, so the model fits in your VRAM to perform well!
+
+# Probably the best so far is [OpenHands LM](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model)
+ollama pull https://huggingface.co/lmstudio-community/openhands-lm-32b-v0.1-GGUF
+
+# https://ollama.com/library/devstral
+ollama pull devstral
+
+# Qwen2.5-Coder has tool use but you have to coax it
+ollama pull qwen2.5-coder
+```
+
+### HTTP / OpenAPI
+
+The server is implemented with the `STDIO` transport.
+For `HTTP`, use [`mcpo`](https://github.com/open-webui/mcpo) for an `OpenAPI` compatible web server interface.
+This works with [`Open-WebUI`](https://github.com/open-webui/open-webui)
+
+```bash
+uvx mcpo --port 3010 --api-key "supersecret" -- npx mcp-server-commands
+
+# uvx runs mcpo => mcpo run npx => npx runs mcp-server-commands
+# then, mcpo bridges STDIO <=> HTTP
+```
+
+> [!WARNING]
+> I briefly used `mcpo` with `open-webui`, make sure to vet it for security concerns.
+
 ### Logging
 
 Claude Desktop app writes logs to `~/Library/Logs/Claude/mcp-server-mcp-server-commands.log`

package/build/always_log.js

@@ -1,4 +1,48 @@
+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));
     }

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,53 +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>} A promise that resolves with the stdout and stderr of the command. `message` is provided on a failure to explain the error.
- */
-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) {
-                reject({ message: error.message, stdout, stderr });
-            }
-            else {
-                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) {
-                reject({ message: error.message, stdout, stderr });
-            }
-            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/index.js

@@ -1,22 +1,12 @@
 #!/usr/bin/env node
-import os from 'os';
+import os from "os";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
-import { runCommand } from "./run-command.js";
 import { createRequire } from "module";
-import { always_log } from "./always_log.js";
+import { registerPrompts } from "./prompts.js";
+import { reisterTools } from "./tools.js";
 const require = createRequire(import.meta.url);
 const { name: package_name, version: package_version, } = require("../package.json");
-// TODO use .promises? in node api
-const execAsync = promisify(exec);
-let verbose = false;
-// check CLI args:
-if (process.argv.includes("--verbose")) {
-    verbose = true;
-}
 const server = new Server({
     name: package_name,
     version: package_version,
@@ -29,151 +19,8 @@ const server = new Server({
         //logging: {}, // for logging messages that don't seem to work yet or I am doing them wrong
     },
 });
-if (verbose) {
-    always_log("INFO: verbose logging enabled");
-}
-else {
-    always_log("INFO: verbose logging disabled, enable it with --verbose");
-}
-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
-}
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    verbose_log("INFO: ListTools");
-    return {
-        tools: [
-            {
-                name: "run_command",
-                description: "Run a command on this " + os.platform() + " machine",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        command: {
-                            type: "string",
-                            description: "Command with args",
-                        },
-                        workdir: {
-                            // previous run_command calls can probe the filesystem and find paths to change to
-                            type: "string",
-                            description: "Optional, current 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!",
-                        },
-                        // args to consider:
-                        // - env - obscure cases where command takes a param only via an env var?
-                        // - timeout - lets just hard code this for now
-                    },
-                    required: ["command"],
-                },
-            },
-        ],
-    };
-});
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    verbose_log("INFO: ToolRequest", request);
-    switch (request.params.name) {
-        case "run_command": {
-            return await runCommand(request.params.arguments);
-        }
-        default:
-            throw new Error("Unknown tool");
-    }
-});
-server.setRequestHandler(ListPromptsRequestSchema, async () => {
-    verbose_log("INFO: ListPrompts");
-    return {
-        prompts: [
-            {
-                name: "run_command",
-                description: "Include command output in the prompt. Instead of a tool call, the user decides what commands are relevant.",
-                arguments: [
-                    {
-                        name: "command",
-                        required: true,
-                    },
-                    // if I care to keep the prompt tools then add stdin?
-                ],
-            },
-        ],
-    };
-});
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    if (request.params.name !== "run_command") {
-        throw new Error("Unknown prompt");
-    }
-    verbose_log("INFO: PromptRequest", request);
-    const command = String(request.params.arguments?.command);
-    if (!command) {
-        throw new Error("Command is required");
-    }
-    // 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 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 = [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: "I ran the following command, if there is any output it will be shown below:\n" +
-                    command,
-            },
-        },
-    ];
-    if (stdout) {
-        messages.push({
-            role: "user",
-            content: {
-                type: "text",
-                text: "STDOUT:\n" + stdout,
-            },
-        });
-    }
-    if (stderr) {
-        messages.push({
-            role: "user",
-            content: {
-                type: "text",
-                text: "STDERR:\n" + stderr,
-            },
-        });
-    }
-    verbose_log("INFO: PromptResponse", messages);
-    return { messages };
-});
+reisterTools(server);
+registerPrompts(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/build/messages.js

@@ -1,28 +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.message) {
+    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({
+            name: "EXIT_CODE",
+            type: "text",
+            text: String(result.code),
+        });
+    }
+    // // 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: result.cmd,
+    //     });
+    // }
+    if ("message" in result && result.message) {
+        // at least need error.message from spawn errors
         messages.push({
+            name: "MESSAGE",
             type: "text",
             text: result.message,
-            name: "ERROR",
         });
     }
+    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",
+    //     });
+    // }
     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

@@ -0,0 +1,87 @@
+import { GetPromptRequestSchema, ListPromptsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { verbose_log } from "./always_log.js";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+// TODO use .promises? in node api
+export function registerPrompts(server) {
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        verbose_log("INFO: ListPrompts");
+        return {
+            prompts: [
+                // ?? 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_process) so it might need some
+                //  special instructions and yeah... I think that's a use case for these prompts
+                //  /prompt llama4 ?
+                {
+                    name: "run_process",
+                    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?
+                    ],
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        // if (request.params.name == "examples") {
+        //     return GetExamplePromptMessages();
+        // } else
+        if (request.params.name !== "run_process") {
+            throw new Error("Unknown or not implemented prompt: " + request.params.name);
+        }
+        verbose_log("INFO: PromptRequest", request);
+        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)
+        // 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 = [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "I ran the following command, if there is any output it will be shown below:\n" +
+                        command_line,
+                },
+            },
+        ];
+        if (stdout) {
+            messages.push({
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "STDOUT:\n" + stdout,
+                },
+            });
+        }
+        if (stderr) {
+            messages.push({
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "STDERR:\n" + stderr,
+                },
+            });
+        }
+        verbose_log("INFO: PromptResponse", messages);
+        return { messages };
+    });
+}
+function GetExamplePromptMessages() {
+    throw new Error("Function not implemented.");
+}

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

@@ -0,0 +1,94 @@
+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) {
+    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: [
+                {
+                    // 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: {
+                            // 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'."
+                            },
+                            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'."
+                            },
+                            cwd: {
+                                // or "workdir" like before? => eval model behavior w/ each name?
+                                type: "string",
+                                description: "Optional to set working directory",
+                            },
+                            stdin: {
+                                type: "string",
+                                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",
+                            },
+                            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"] }
+                        //     }
+                        // ]
+                    },
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        verbose_log("INFO: ToolRequest", request);
+        switch (request.params.name) {
+            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.5.0",
+    "version": "0.7.3",
     "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,44 +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) {
-    if (!stdin) {
-        return await execAsync(command, options);
-    }
-    return await execFileWithInput(command, stdin, options);
-}
-/**
- * Executes a command and returns the result as CallToolResult.
- */
-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) {
-        const response = {
-            isError: true,
-            content: messagesFor(error),
-        };
-        always_log("WARN: run_command failed", response);
-        return response;
-    }
-}