mcp-server-commands 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# mcp-server-commands MCP Server
+
+An MCP server to run commands and includ the output in chat history.
+
+## Tools
+
+- `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
+
+## Prompts
+
+- `include_command_output` - 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
+
+## Development
+
+Install dependencies:
+```bash
+npm install
+```
+
+Build the server:
+```bash
+npm run build
+```
+
+For development with auto-rebuild:
+```bash
+npm run watch
+```
+
+## Installation
+
+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`
+
+### Use the published npm package
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-commands": {
+      "command": "npx",
+      "args": ["mcp-server-commands"]
+    }
+  }
+}
+```
+
+### Use a local build (repo checkout)
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-commands": {
+      // works b/c of shebang in index.js
+      "command": "/path/to/mcp-server-commands/build/index.js"
+    }
+  }
+}
+```
+
+### 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:
+
+```bash
+npm run inspector
+```
+
+The Inspector will provide a URL to access debugging tools in your browser.

package/build/index.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+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";
+const execAsync = promisify(exec);
+const server = new Server({
+    name: "mcp-server-commands",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        //resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "run_command",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        command: {
+                            type: "string",
+                            description: "Command to run",
+                        },
+                    },
+                    required: ["command"],
+                },
+            },
+        ],
+    };
+});
+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: {
+                        content: [
+                            {
+                                type: "text",
+                                text: stdout,
+                                name: "STDOUT",
+                            },
+                            {
+                                type: "text",
+                                text: stderr,
+                                name: "STDERR",
+                            },
+                        ],
+                    },
+                };
+            }
+            catch (error) {
+                const { message, stdout, stderr } = error;
+                return {
+                    toolResult: {
+                        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",
+                            },
+                        ],
+                    },
+                };
+            }
+        }
+        default:
+            throw new Error("Unknown tool");
+    }
+});
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "include_command_output",
+                description: "Include command output in the prompt. Instead of a tool call, the user decides what commands are relevant.",
+                arguments: [
+                    {
+                        name: "command",
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "include_command_output") {
+        throw new Error("Unknown prompt");
+    }
+    const command = String(request.params.arguments?.command);
+    if (!command) {
+        throw new Error("Command is required");
+    }
+    const { stdout, stderr } = await execAsync(command);
+    // let error bubble up, errors look good in zed /prompts (i.e. command not found)
+    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,
+            },
+        });
+    }
+    return { messages };
+});
+async function main() {
+    console.log("Starting server...");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "mcp-server-commands",
+  "version": "0.1.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": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  }
+}