mcp-server-commands 0.4.0 → 0.5.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.
+
+Currently, just one command to rule them all!
 
-An MCP server to run commands.
+- `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,15 +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
+## 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
+<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
 
@@ -48,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": {
@@ -63,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": {
@@ -93,7 +101,3 @@ npm run inspector
 ```
 
 The Inspector will provide a URL to access debugging tools in your browser.
-
-## TODOs
-
-- Add some mechanism (likely in a new MCP server) to retain memory of past command failures, i.e. to use `python3` and not `python` and tie it to a machine or some context?

package/build/always_log.js

@@ -0,0 +1,8 @@
+export function always_log(message, data) {
+    if (data) {
+        console.error(message + ": " + JSON.stringify(data));
+    }
+    else {
+        console.error(message);
+    }
+}

package/build/exec-utils.js

@@ -2,16 +2,16 @@ 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.
+ * @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_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) => {
@@ -22,21 +22,21 @@ function execFileWithInput(interpreter, stdin_text, options) {
                 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) => {

package/build/index.js

@@ -1,10 +1,15 @@
 #!/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 { runCommand } from "./run-command.js";
+import { createRequire } from "module";
+import { always_log } from "./always_log.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;
@@ -13,8 +18,9 @@ if (process.argv.includes("--verbose")) {
     verbose = true;
 }
 const server = new Server({
-    name: "mcp-server-commands",
-    version: "0.4.0",
+    name: package_name,
+    version: package_version,
+    description: "Run commands on this " + os.platform() + " machine",
 }, {
     capabilities: {
         //resources: {},
@@ -23,14 +29,6 @@ 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");
 }
@@ -75,6 +73,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: "run_command",
+                description: "Run a command on this " + os.platform() + " machine",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -82,47 +81,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Command with args",
                         },
-                        cwd: {
+                        workdir: {
                             // 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",
+                            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!",
                         },
-                        // 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:
+                        // - env - obscure cases where command takes a param only via an env var?
                         // - 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"],
-                },
-            },
         ],
     };
 });
@@ -130,107 +104,12 @@ 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),
-            };
+            return await runCommand(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 {
@@ -243,6 +122,7 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
                         name: "command",
                         required: true,
                     },
+                    // if I care to keep the prompt tools then add stdin?
                 ],
             },
         ],
@@ -257,9 +137,9 @@ 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?
+    // 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 CWD of each project
+    // - 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

package/build/messages.js

@@ -0,0 +1,28 @@
+/**
+ * Converts an ExecResult into an array of TextContent messages.
+ */
+export function messagesFor(result) {
+    const messages = [];
+    if (result.message) {
+        messages.push({
+            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;
+}

package/build/run-command.js

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

package/package.json

@@ -1,33 +1,33 @@
 {
-  "name": "mcp-server-commands",
-  "version": "0.4.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": "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.5.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"
+    }
 }