mcp-server-commands 0.2.1 → 0.3.0

package/README.md

@@ -1,17 +1,28 @@
 # mcp-server-commands
 
-An MCP server to run commands and includ the output in chat history.
+An MCP server to run commands.
+
+> [!WARNING]
+> Be careful what you ask this server to run!
+> In Claude Desktop app, use `Approve Once` (not `Allow for This Chat`) so you can review each command, use `Deny` if you don't trust the command.
+> 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
+
 - `run_command` - run a command, i.e. `hostname` or `ls -al` or `echo "hello world"` etc
   - Returns STDOUT and STDERR as text
-- for LLMs to request tool use and get back the command output, i.e. Claude Desktop app
+- `run_script` - run a script! (i.e. `fish`, `bash`, `zsh`, `python`)
+  - Let your LLM run the code it writes!
+  - script is passed over STDIN
 
 ## Prompts
 
-- `run_command` - include the output of a command in the chat history
-- for users to include relevant commands in chat history, i.e. via `Zed`'s slash commands
+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
 
 ## Development
 

package/build/exec-utils.js

@@ -0,0 +1,53 @@
+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.
+ */
+function execFileWithInput(interpreter, stdin_text, 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 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_text) {
+            if (child.stdin === null) {
+                reject(new Error("Unexpected failure: child.stdin is null"));
+                return;
+            }
+            child.stdin.write(stdin_text);
+            child.stdin.end();
+        }
+    });
+}
+async function fishWorkaround(interpreter, script, 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"`;
+    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 });
+            }
+        });
+    });
+}
+export { execFileWithInput };

package/build/index.js

@@ -4,10 +4,12 @@ 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";
+// TODO use .promises?
 const execAsync = promisify(exec);
 const server = new Server({
     name: "mcp-server-commands",
-    version: "0.2.0",
+    version: "0.3.0",
 }, {
     capabilities: {
         //resources: {},
@@ -25,74 +27,152 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         command: {
                             type: "string",
-                            description: "Command to run",
+                            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",
+                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) => {
     switch (request.params.name) {
         case "run_command": {
-            const command = String(request.params.arguments?.command);
-            if (!command) {
-                throw new Error("Command is required");
-            }
-            try {
-                const { stdout, stderr } = await execAsync(command);
-                return {
-                    toolResult: {
-                        isError: false,
-                        content: [
-                            {
-                                type: "text",
-                                text: stdout,
-                                name: "STDOUT",
-                            },
-                            {
-                                type: "text",
-                                text: stderr,
-                                name: "STDERR",
-                            },
-                        ],
-                    },
-                };
-            }
-            catch (error) {
-                const { message, stdout, stderr } = error;
-                return {
-                    toolResult: {
-                        isError: true,
-                        content: [
-                            {
-                                // most of the time this is gonna match stderr, TODO do I want/need both error and stderr?
-                                type: "text",
-                                text: message,
-                                name: "ERROR",
-                            },
-                            {
-                                type: "text",
-                                text: stderr || "",
-                                name: "STDERR",
-                            },
-                            {
-                                // keep STDOUT b/c there might be some useful output before the failure
-                                type: "text",
-                                text: stdout || "",
-                                name: "STDOUT",
-                            },
-                        ],
-                    },
-                };
-            }
+            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
+        return {
+            isError: true,
+            content: messagesFor(error),
+            //content: [{ type: "text", text: JSON.stringify(error) }],
+        };
+    }
+}
+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) {
+        return {
+            isError: true,
+            content: messagesFor(error),
+        };
+    }
+}
+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 () => {
     return {
         prompts: [
@@ -117,8 +197,12 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     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);
-    // let error bubble up, errors look good in zed /prompts (i.e. command not found)
+    // 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",
@@ -129,7 +213,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             },
         },
     ];
-    if (stdout && stdout.length > 0) {
+    if (stdout) {
         messages.push({
             role: "user",
             content: {
@@ -138,7 +222,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             },
         });
     }
-    if (stderr && stderr.length > 0) {
+    if (stderr) {
         messages.push({
             role: "user",
             content: {
@@ -150,7 +234,6 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     return { messages };
 });
 async function main() {
-    console.log("Starting server...");
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-commands",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "An MCP server to run arbitrary commands",
   "private": false,
   "type": "module",
@@ -14,7 +14,7 @@
     "clean": "rm -rf build",
     "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
     "prepare": "npm run build",
-    "watch": "tsc --watch",
+    "watch": "npm run build && tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js"
   },
   "dependencies": {