mcp-server-commands 0.2.1 → 0.4.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
 
@@ -63,6 +74,16 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
 }
 ```
 
+### Logging
+
+Claude Desktop app writes logs to `~/Library/Logs/Claude/mcp-server-mcp-server-commands.log`
+
+By default, only important messages are logged (i.e. errors).
+If you want to see more messages, add `--verbose` to the `args` when configuring the server.
+
+By the way, logs are written to `STDERR` because that is what Claude Desktop routes to the log files.
+In the future, I expect well formatted log messages to be written over the `STDIO` transport to the MCP client (note: not Claude Desktop app).
+
 ### Debugging
 
 Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
@@ -72,3 +93,7 @@ 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/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,18 +4,73 @@ 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? 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: "mcp-server-commands",
-    version: "0.2.0",
+    version: "0.4.0",
 }, {
     capabilities: {
         //resources: {},
         tools: {},
         prompts: {},
+        //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: [
             {
@@ -25,75 +80,159 @@ 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) => {
+    verbose_log("INFO: ToolRequest", 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
+        // 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: [
             {
@@ -113,12 +252,17 @@ 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);
-    // 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 +273,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             },
         },
     ];
-    if (stdout && stdout.length > 0) {
+    if (stdout) {
         messages.push({
             role: "user",
             content: {
@@ -138,7 +282,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             },
         });
     }
-    if (stderr && stderr.length > 0) {
+    if (stderr) {
         messages.push({
             role: "user",
             content: {
@@ -147,10 +291,10 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             },
         });
     }
+    verbose_log("INFO: PromptResponse", messages);
     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.4.0",
   "description": "An MCP server to run arbitrary commands",
   "private": false,
   "type": "module",
@@ -14,14 +14,20 @@
     "clean": "rm -rf build",
     "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
     "prepare": "npm run build",
-    "watch": "tsc --watch",
-    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+    "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"
   }
 }