MCP Server Commands

1## `runProcess` renaming/redesign
2 
3Recently I renamed the tool to `runProcess` to better reflect that you can run more than just shell commands with it. There are two explicit modes now:
41. `mode=executable` where you pass `argv` with `argv[0]` representing the `executable` file and then the rest of the array contains args to it.
52. `mode=shell` where you pass `command_line` (just like typing into `bash`/`fish`/`pwsh`/etc) which will use your system's default shell.
6 
7I hate APIs that make ambiguous if you're executing something via a shell, or not. I hate it being a toggle b/c there's way more to running a shell command vs exec than just flipping a switch. So I made that explicit in the new tool's parameters
8 
9If you want your model to use specific shell(s) on a system, I would list them in your system prompt. Or, maybe in your tool instructions, though models tend to pay better attention to examples in a system prompt.
10 
11I've used this new design with `gptoss-120b` extensively and it went off without a hitch, no issues switching as the model doesn't care about names nor even the redesigned `mode` part, it all seems to "make sense" to gptoss. 
12 
13Let me know if you encounter problems!
14 
15## Tools
16 
17Tools are for LLMs to request. Claude Sonnet 3.5 intelligently uses `run_process`. And, initial testing shows promising results with [Groq Desktop with MCP](https://github.com/groq/groq-desktop-beta) and `llama4` models.
18 
19Currently, just one command to rule them all!
20 
21- `run_process` - run a command, i.e. `hostname` or `ls -al` or `echo "hello world"` etc
22  - Returns `STDOUT` and `STDERR` as text
23  - Optional `stdin` parameter means your LLM can
24    - pass scripts over `STDIN` to commands like `fish`, `bash`, `zsh`, `python`
25    - create files with `cat >> foo/bar.txt` from the text in `stdin`
26 
27> [!WARNING]
28> Be careful what you ask this server to run!
29> 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.
30> Permissions are dictated by the user that runs the server.
31> DO NOT run with `sudo`.
32 
33## Video walkthrough
34 
35<a href="https://youtu.be/0-VPu1Pc18w"><img src="https://img.youtube.com/vi/0-VPu1Pc18w/maxresdefault.jpg" width="480" alt="YouTube Thumbnail"></a>
36 
37## Prompts
38 
39Prompts are for users to include in chat history, i.e. via `Zed`'s slash commands (in its AI Chat panel)
40 
41- `run_process` - generate a prompt message with the command output
42 
43* FYI this was mostly a learning exercise... I see this as a user requested tool call. That's a fancy way to say, it's a template for running a command and passing the outputs to the model!
44 
45## Development
46 
47Install dependencies:
48```bash
49npm install
50```
51 
52Build the server:
53```bash
54npm run build
55```
56 
57For development with auto-rebuild:
58```bash
59npm run watch
60```
61 
62## Installation
63 
64To use with Claude Desktop, add the server config:
65 
66On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
67On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
68 
69Groq Desktop (beta, macOS) uses `~/Library/Application Support/groq-desktop-app/settings.json`
70 
71### Use the published npm package
72 
73Published 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)
74 
75```json
76{
77  "mcpServers": {
78    "mcp-server-commands": {
79      "command": "npx",
80      "args": ["mcp-server-commands"]
81    }
82  }
83}
84```
85 
86### Use a local build (repo checkout)
87 
88Make sure to run `npm run build`
89 
90```json
91{
92  "mcpServers": {
93    "mcp-server-commands": {
94      // works b/c of shebang in index.js
95      "command": "/path/to/mcp-server-commands/build/index.js"
96    }
97  }
98}
99```
100 
101## Local Models
102 
103- Most models are trained such that they don't think they can run commands for you.
104  - Sometimes, they use tools w/o hesitation... other times, I have to coax them.
105  - Use a system prompt or prompt template to instruct that they should follow user requests. Including to use `run_processs` without double checking.
106- Ollama is a great way to run a model locally (w/ Open-WebUI)
107 
108```sh
109# NOTE: make sure to review variants and sizes, so the model fits in your VRAM to perform well!
110 
111# Probably the best so far is [OpenHands LM](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model)
112ollama pull https://huggingface.co/lmstudio-community/openhands-lm-32b-v0.1-GGUF
113 
114# https://ollama.com/library/devstral
115ollama pull devstral
116 
117# Qwen2.5-Coder has tool use but you have to coax it
118ollama pull qwen2.5-coder
119```
120 
121### HTTP / OpenAPI
122 
123The server is implemented with the `STDIO` transport.
124For `HTTP`, use [`mcpo`](https://github.com/open-webui/mcpo) for an `OpenAPI` compatible web server interface.
125This works with [`Open-WebUI`](https://github.com/open-webui/open-webui)
126 
127```bash
128uvx mcpo --port 3010 --api-key "supersecret" -- npx mcp-server-commands
129 
130# uvx runs mcpo => mcpo run npx => npx runs mcp-server-commands
131# then, mcpo bridges STDIO <=> HTTP
132```
133 
134> [!WARNING]
135> I briefly used `mcpo` with `open-webui`, make sure to vet it for security concerns.
136 
137### Logging
138 
139Claude Desktop app writes logs to `~/Library/Logs/Claude/mcp-server-mcp-server-commands.log`
140 
141By default, only important messages are logged (i.e. errors).
142If you want to see more messages, add `--verbose` to the `args` when configuring the server.
143 
144By the way, logs are written to `STDERR` because that is what Claude Desktop routes to the log files.
145In the future, I expect well formatted log messages to be written over the `STDIO` transport to the MCP client (note: not Claude Desktop app).
146 
147### Debugging
148 
149Since 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:
150 
151```bash
152npm run inspector
153```
154 
155The Inspector will provide a URL to access debugging tools in your browser.
156