mcp-server-commands 0.3.0 → 0.4.2

package/README.md

@@ -10,13 +10,15 @@ An MCP server to run commands.
 
 ## Tools
 
-Tools are for LLMs to request, i.e. Claude Desktop app
+Tools are for LLMs to request, i.e. Claude Desktop app. Claude Sonnet 3.5 intelligently uses both tools, I was pleasantly surprised.
 
 - `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!
 
 ## Prompts
 
@@ -74,6 +76,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:

package/build/index.js

@@ -5,23 +5,81 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { execFileWithInput } from "./exec-utils.js";
-// TODO use .promises?
+import { createRequire } from "module";
+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: "mcp-server-commands",
-    version: "0.3.0",
+    name: package_name,
+    version: package_version,
+    //description: "Run commands on this " + os.platform() + " machine",
 }, {
     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: [
             {
                 name: "run_command",
+                //description: "Run a command on this " + os.platform() + " machine",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -50,6 +108,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             {
                 // 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: {
@@ -74,6 +134,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    verbose_log("INFO: ToolRequest", request);
     switch (request.params.name) {
         case "run_command": {
             return {
@@ -108,11 +169,13 @@ async function runCommand(args) {
     }
     catch (error) {
         // TODO catch for other errors, not just ExecException
-        return {
+        // 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),
-            //content: [{ type: "text", text: JSON.stringify(error) }],
         };
+        always_log("WARN: run_command failed", response);
+        return response;
     }
 }
 async function runScript(args) {
@@ -141,10 +204,12 @@ async function runScript(args) {
         };
     }
     catch (error) {
-        return {
+        const response = {
             isError: true,
             content: messagesFor(error),
         };
+        always_log("WARN: run_script failed", response);
+        return response;
     }
 }
 function messagesFor(result) {
@@ -174,6 +239,7 @@ function messagesFor(result) {
     return messages;
 }
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    verbose_log("INFO: ListPrompts");
     return {
         prompts: [
             {
@@ -193,6 +259,7 @@ 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");
@@ -231,6 +298,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             },
         });
     }
+    verbose_log("INFO: PromptResponse", messages);
     return { messages };
 });
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-commands",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "An MCP server to run arbitrary commands",
   "private": false,
   "type": "module",
@@ -15,13 +15,19 @@
     "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"
+    "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"
   }
 }