mcp-server-commands 0.5.0 → 0.6.0

package/README.md

@@ -82,6 +82,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_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

@@ -1,3 +1,43 @@
+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));

package/build/exec-utils.js

@@ -3,7 +3,7 @@ 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.
+ * @returns {Promise<ExecResult>}
  */
 function execFileWithInput(interpreter, stdin, options) {
     // FYI for now, using `exec()` so the interpreter can have cmd+args AIO
@@ -16,9 +16,14 @@ function execFileWithInput(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 });
             }
         });
@@ -42,7 +47,11 @@ async function fishWorkaround(interpreter, stdin, options) {
         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,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

@@ -3,13 +3,35 @@
  */
 export function messagesFor(result) {
     const messages = [];
-    if (result.message) {
+    if (result.code !== undefined) {
         messages.push({
             type: "text",
-            text: result.message,
-            name: "ERROR",
+            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",

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

@@ -5,14 +5,15 @@ 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);
 }
-/**
- * Executes a command and returns the result as CallToolResult.
- */
 export async function runCommand(args) {
     const command = args?.command;
     if (!command) {
@@ -34,6 +35,22 @@ export async function runCommand(args) {
         };
     }
     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),

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,6 +1,6 @@
 {
     "name": "mcp-server-commands",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "An MCP server to run arbitrary commands",
     "private": false,
     "type": "module",