mcp-server-commands 0.4.2 → 0.6.0

package/LICENSE

@@ -0,0 +1,5 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,6 +1,14 @@
-# mcp-server-commands
+## 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.
 
-An MCP server to run commands.
+Currently, just one command to rule them all!
+
+- `run_command` - 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`
+    - create files with `cat >> foo/bar.txt` from the text in `stdin`
 
 > [!WARNING]
 > Be careful what you ask this server to run!
@@ -8,17 +16,9 @@ An MCP server to run commands.
 > Permissions are dictated by the user that runs the server.
 > DO NOT run with `sudo`.
 
-## Tools
-
-Tools are for LLMs to request, i.e. Claude Desktop app. Claude Sonnet 3.5 intelligently uses both tools, I was pleasantly surprised.
+## Video walkthrough
 
-- `run_command` - run a command, i.e. `hostname` or `ls -al` or `echo "hello world"` etc
-  - Returns STDOUT and STDERR as text
-- `run_script` - run a script! (i.e. `fish`, `bash`, `zsh`, `python`)
-  - Let your LLM run the code it writes!
-  - script is passed over STDIN
-  - `run_script` == `run_command` + script over STDIN
-  - Claude has been pretty creative with this, i.e. using `cat` as the interpreter to create new files!
+<a href="https://youtu.be/0-VPu1Pc18w"><img src="https://img.youtube.com/vi/0-VPu1Pc18w/maxresdefault.jpg" width="480" alt="YouTube Thumbnail"></a>
 
 ## Prompts
 
@@ -50,8 +50,12 @@ To use with Claude Desktop, add the server config:
 On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
 
+Groq Desktop (beta, macOS) uses `~/Library/Application Support/groq-desktop-app/settings.json`
+
 ### Use the published npm package
 
+Published to npm as [mcp-server-commands](https://www.npmjs.com/package/mcp-server-commands) using this [workflow](https://github.com/g0t4/mcp-server-commands/actions)
+
 ```json
 {
   "mcpServers": {
@@ -65,6 +69,8 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
 
 ### Use a local build (repo checkout)
 
+Make sure to run `npm run build`
+
 ```json
 {
   "mcpServers": {
@@ -76,6 +82,42 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
 }
 ```
 
+## 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_commands` 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

@@ -0,0 +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) {
+    if (data) {
+        console.error(message + ": " + JSON.stringify(data));
+    }
+    else {
+        console.error(message);
+    }
+}

package/build/exec-utils.js

@@ -2,47 +2,56 @@ 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_text - 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.
+ * @param {string} stdin - The string to pipe to stdin.
+ * @returns {Promise<ExecResult>}
  */
-function execFileWithInput(interpreter, stdin_text, options) {
+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_text, options);
+        return fishWorkaround(interpreter, stdin, options);
     }
     return new Promise((resolve, reject) => {
         const child = exec(interpreter, options, (error, stdout, stderr) => {
             if (error) {
-                reject({ message: error.message, stdout, stderr });
+                // 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_text) {
+        if (stdin) {
             if (child.stdin === null) {
                 reject(new Error("Unexpected failure: child.stdin is null"));
                 return;
             }
-            child.stdin.write(stdin_text);
+            child.stdin.write(stdin);
             child.stdin.end();
         }
     });
 }
-async function fishWorkaround(interpreter, script, options) {
+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 base64Script = Buffer.from(script).toString("base64");
-    const command = `${interpreter} -c "echo ${base64Script} | base64 -d | fish"`;
+    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 });
+                // console.log("fishWorkaround ERROR:", error);
+                // mirror ExecException used by throws
+                error.stdout = stdout;
+                error.stderr = stderr;
+                reject(error);
             }
             else {
                 resolve({ stdout, stderr });

package/build/index.js

@@ -1,24 +1,16 @@
 #!/usr/bin/env node
+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 { execFileWithInput } from "./exec-utils.js";
 import { createRequire } from "module";
+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 { name: package_name, version: package_version, } = require("../package.json");
 const server = new Server({
     name: package_name,
     version: package_version,
-    //description: "Run commands on this " + os.platform() + " machine",
+    description: "Run commands on this " + os.platform() + " machine",
 }, {
     capabilities: {
         //resources: {},
@@ -27,280 +19,8 @@ const server = new Server({
         //logging: {}, // for logging messages that don't seem to work yet or I am doing them wrong
     },
 });
-function always_log(message, data) {
-    if (data) {
-        console.error(message + ": " + JSON.stringify(data));
-    }
-    else {
-        console.error(message);
-    }
-}
-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",
-                        },
-                        cwd: {
-                            // previous run_command calls can probe the filesystem and find paths to change to
-                            type: "string",
-                            description: "Current working directory, leave empty in most cases",
-                        },
-                        // FYI using child_process.exec runs command in a shell, so you can pass a script here too but I still think separate tools would be helpful?
-                        //   FYI gonna use execFile for run_script
-                        // - env - obscure cases where command takes a param only via an env var?
-                        // args to consider:
-                        // - timeout - lets just hard code this for now
-                        // - shell - (cmd/args) - for now use run_script for this case, also can just pass "fish -c 'command'" or "sh ..."
-                        // - stdin? though this borders on the run_script below
-                        // - capture_output (default true) - for now can just redirect to /dev/null - perhaps capture_stdout/capture_stderr
-                    },
-                    required: ["command"],
-                },
-            },
-            // PRN tool to introspect the environment (i.e. windows vs linux vs mac, maybe default shell, etc?) - for now LLM can run commands and when they fail it can make adjustments accordingly - some cases where knowing this would help avoid dispatching erroneous commands (i.e. using free on linux, vm_stat on mac)
-            {
-                // TODO is run_script even needed if I were to add STDIN support to run_command above?
-                name: "run_script",
-                // TODO is it useful to include OS type? I need to test this on a windows machine and see how Claude does w/ and w/o this os hint:
-                //description: "Run a script on this " + os.platform() + " machine",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        interpreter: {
-                            // TODO use shebang on *nix?
-                            type: "string",
-                            description: "Command with arguments. Script will be piped to stdin. Examples: bash, fish, zsh, python, or: bash --norc",
-                        },
-                        script: {
-                            type: "string",
-                            description: "Script to run",
-                        },
-                        cwd: {
-                            type: "string",
-                            description: "Current working directory",
-                        },
-                    },
-                    required: ["script"],
-                },
-            },
-        ],
-    };
-});
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    verbose_log("INFO: ToolRequest", request);
-    switch (request.params.name) {
-        case "run_command": {
-            return {
-                toolResult: await runCommand(request.params.arguments),
-            };
-        }
-        case "run_script": {
-            return {
-                toolResult: await runScript(request.params.arguments),
-            };
-        }
-        default:
-            throw new Error("Unknown tool");
-    }
-});
-async function runCommand(args) {
-    const command = String(args?.command);
-    if (!command) {
-        throw new Error("Command is required");
-    }
-    const options = {};
-    if (args?.cwd) {
-        options.cwd = String(args.cwd);
-        // ENOENT is thrown if the cwd doesn't exist, and I think LLMs can understand that?
-    }
-    try {
-        const result = await execAsync(command, options);
-        return {
-            isError: false,
-            content: messagesFor(result),
-        };
-    }
-    catch (error) {
-        // TODO catch for other errors, not just ExecException
-        // FYI failure may not always be a bad thing if for example checking for a file to exist so just keep that in mind in terms of logging?
-        const response = {
-            isError: true,
-            content: messagesFor(error),
-        };
-        always_log("WARN: run_command failed", response);
-        return response;
-    }
-}
-async function runScript(args) {
-    const interpreter = String(args?.interpreter);
-    if (!interpreter) {
-        throw new Error("Interpreter is required");
-    }
-    const options = {
-        //const options = {
-        // constrains typescript too, to string based overload
-        encoding: "utf8",
-    };
-    if (args?.cwd) {
-        options.cwd = String(args.cwd);
-        // ENOENT is thrown if the cwd doesn't exist, and I think LLMs can understand that?
-    }
-    const script = String(args?.script);
-    if (!script) {
-        throw new Error("Script is required");
-    }
-    try {
-        const result = await execFileWithInput(interpreter, script, options);
-        return {
-            isError: false,
-            content: messagesFor(result),
-        };
-    }
-    catch (error) {
-        const response = {
-            isError: true,
-            content: messagesFor(error),
-        };
-        always_log("WARN: run_script failed", response);
-        return response;
-    }
-}
-function messagesFor(result) {
-    const messages = [];
-    if (result.message) {
-        messages.push({
-            // most of the time this is gonna match stderr, TODO do I want/need both error and stderr?
-            type: "text",
-            text: result.message,
-            name: "ERROR",
-        });
-    }
-    if (result.stdout) {
-        messages.push({
-            type: "text",
-            text: result.stdout,
-            name: "STDOUT",
-        });
-    }
-    if (result.stderr) {
-        messages.push({
-            type: "text",
-            text: result.stderr,
-            name: "STDERR",
-        });
-    }
-    return messages;
-}
-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,
-                    },
-                ],
-            },
-        ],
-    };
-});
-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 CWD when running the command?
-    // - currently it uses / (yikez)
-    // - IMO makes more sense to have it be based on the Zed CWD 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

@@ -0,0 +1,50 @@
+/**
+ * Converts an ExecResult into an array of TextContent messages.
+ */
+export function messagesFor(result) {
+    const messages = [];
+    if (result.code !== undefined) {
+        messages.push({
+            type: "text",
+            text: `${result.code}`,
+            name: "EXIT_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) {
+    //     messages.push({
+    //         type: "text",
+    //         text: `Signal: ${result.signal}`,
+    //         name: "SIGNAL",
+    //     });
+    // } 
+    // if (!!result.killed) {
+    //     // killed == true is the only time to include this
+    //     messages.push({
+    //         type: "text",
+    //         text: "Process was killed",
+    //         name: "KILLED",
+    //     });
+    // }
+    if (result.stdout) {
+        messages.push({
+            type: "text",
+            text: result.stdout,
+            name: "STDOUT",
+        });
+    }
+    if (result.stderr) {
+        messages.push({
+            type: "text",
+            text: result.stderr,
+            name: "STDERR",
+        });
+    }
+    return messages;
+}

package/build/prompts.js

@@ -0,0 +1,91 @@
+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: [
+                // TODO! add prompts for various LLMs that tailor instructions to make them optimize use of run_command 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
+                //  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",
+                    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?
+                    ],
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        // if (request.params.name == "examples") {
+        //     return GetExamplePromptMessages();
+        // } else
+        if (request.params.name !== "run_command") {
+            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");
+        }
+        // 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 };
+    });
+}
+function GetExamplePromptMessages() {
+    throw new Error("Function not implemented.");
+}

package/build/run-command.js

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

package/build/tools.js

@@ -0,0 +1,49 @@
+import os from "os";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { verbose_log } from "./always_log.js";
+import { runCommand } from "./run-command.js";
+export function reisterTools(server) {
+    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");
+        }
+    });
+}

package/package.json

@@ -1,33 +1,33 @@
 {
-  "name": "mcp-server-commands",
-  "version": "0.4.2",
-  "description": "An MCP server to run arbitrary commands",
-  "private": false,
-  "type": "module",
-  "bin": {
-    "mcp-server-commands": "./build/index.js"
-  },
-  "files": [
-    "build"
-  ],
-  "scripts": {
-    "clean": "rm -rf build",
-    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
-    "prepare": "npm run build",
-    "watch": "npm run build && tsc --watch",
-    "inspector": "npx @modelcontextprotocol/inspector build/index.js",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:integration": "jest tests/integration"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "0.6.0"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.11",
-    "@types/node": "^20.11.24",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.3.3"
-  }
+    "name": "mcp-server-commands",
+    "version": "0.6.0",
+    "description": "An MCP server to run arbitrary commands",
+    "private": false,
+    "type": "module",
+    "bin": {
+        "mcp-server-commands": "./build/index.js"
+    },
+    "files": [
+        "build"
+    ],
+    "scripts": {
+        "clean": "rm -rf build",
+        "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+        "prepare": "npm run build",
+        "watch": "npm run build && tsc --watch",
+        "inspector": "npx @modelcontextprotocol/inspector build/index.js",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:integration": "jest tests/integration"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "1.9.0"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.14",
+        "@types/node": "^22.14.1",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.3.2",
+        "typescript": "^5.8.3"
+    }
 }