run-mcp 1.6.0 → 1.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +112 -72
- package/dist/index.js +2127 -1168
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ A smart proxy, interactive REPL, and live test harness for [Model Context Protoc
|
|
|
5
5
|
`run-mcp` operates in two modes:
|
|
6
6
|
|
|
7
7
|
1. **Agent MCP Server** (`run-mcp`) — An MCP server that exposes tools (`connect_to_mcp`, `call_mcp_tool`) so AI agents can dynamically connect to and test local MCP projects without hardcoding them in configuration files. This is the **default mode** when you run `npx -y run-mcp`.
|
|
8
|
-
2. **Interactive REPL** (
|
|
8
|
+
2. **Interactive REPL** (Interactive mode) — A headless CLI for human developers to manually test and explore MCP servers using short, memorable commands (`tools/call`, `status`, etc.).
|
|
9
9
|
|
|
10
10
|
### Interception Rules (Agent Server & REPL)
|
|
11
11
|
|
|
@@ -36,12 +36,12 @@ npm install -g .
|
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
38
|
# Start a REPL session with any MCP server
|
|
39
|
-
run-mcp
|
|
39
|
+
run-mcp -- node path/to/my-mcp-server.js
|
|
40
40
|
|
|
41
41
|
# Or use npx without installing globally
|
|
42
|
-
npx .
|
|
42
|
+
npx . -- node path/to/my-mcp-server.js
|
|
43
43
|
|
|
44
|
-
# Or start it without arguments to
|
|
44
|
+
# Or start it without arguments to run the Agent Server mode!
|
|
45
45
|
run-mcp
|
|
46
46
|
```
|
|
47
47
|
|
|
@@ -61,57 +61,86 @@ You'll see an interactive prompt:
|
|
|
61
61
|
run-mcp [options] [target_command...]
|
|
62
62
|
|
|
63
63
|
Options:
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
64
|
+
-V, --version Show version number
|
|
65
|
+
-o, --out-dir <path> Directory to save intercepted images and audio
|
|
66
|
+
-t, --timeout <ms> Default tool call timeout in milliseconds (default: 300000) (Agent Mode only)
|
|
67
|
+
--max-text <chars> Max text response length before truncation (default: 50000) (Agent Mode only)
|
|
68
|
+
--mcp Force start Agent Server mode even if run interactively without arguments
|
|
69
|
+
-s, --script <file> Read commands from a file instead of stdin (REPL Mode only)
|
|
70
|
+
-h, --help Display help for command
|
|
71
71
|
|
|
72
72
|
Examples:
|
|
73
73
|
$ run-mcp # Test harness (agent mode)
|
|
74
|
-
$ run-mcp node my-server.js
|
|
75
|
-
$ run-mcp node my-server.js
|
|
76
|
-
$ run-mcp npx -y some-mcp-server
|
|
74
|
+
$ run-mcp -- node my-server.js # Interactive testing (human REPL mode)
|
|
75
|
+
$ run-mcp -s test.txt -- node my-server.js # Run a script in REPL mode
|
|
76
|
+
$ run-mcp -- npx -y some-mcp-server # Test an npx server
|
|
77
77
|
$ run-mcp --out-dir ./test-output # Agent mode with options
|
|
78
|
-
$ run-mcp --out-dir ./screenshots node srv.js
|
|
78
|
+
$ run-mcp --out-dir ./screenshots -- node srv.js # REPL mode with options
|
|
79
79
|
|
|
80
80
|
## Headless Mode (Single-Shot CI/CD)
|
|
81
81
|
|
|
82
|
-
For CI/CD pipelines, shell scripts, or parsing via `jq`, `run-mcp` exposes a suite of headless subcommands that pipe clean JSON to stdout and isolate standard errors and progress updates to stderr.
|
|
82
|
+
For CI/CD pipelines, shell scripts, or parsing via `jq`, `run-mcp` exposes a suite of headless subcommands that pipe clean JSON to stdout and isolate standard errors and progress updates to stderr.
|
|
83
|
+
|
|
84
|
+
### ⚠️ Strictly Required Double-Dash `--`
|
|
85
|
+
|
|
86
|
+
To prevent argument parsing conflicts between `run-mcp` and the target server, **you must always separate the target command with a double-dash `--`**. This applies to both default REPL launching and all headless subcommands.
|
|
87
|
+
|
|
88
|
+
- **Correct**: `run-mcp list-tools -- node my-server.js`
|
|
89
|
+
- **Incorrect**: `run-mcp list-tools node my-server.js` (will exit with a coaching error)
|
|
90
|
+
|
|
91
|
+
### ⚡ HTTPie-Style Shorthand Arguments
|
|
92
|
+
|
|
93
|
+
Instead of escaping complex JSON strings on the command line, you can provide arguments using simple key-value shorthand notation:
|
|
94
|
+
|
|
95
|
+
- `key=value` -> evaluated as a string
|
|
96
|
+
- `key:=json_val` -> parsed as a JSON primitive (boolean, number, array, object, null)
|
|
97
|
+
|
|
98
|
+
_Example:_
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
# Call a tool using shorthand arguments
|
|
102
|
+
run-mcp call greet name=Alice count:=5 -- node my-server.js
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 🔄 Stateful/Persistent CLI Sessions
|
|
106
|
+
|
|
107
|
+
Normally, every headless command spawns a fresh process of the target server, which is slow and discards connection state. By passing `--session <name>`, `run-mcp` will spawn a persistent background daemon on the first call. Subsequent commands will dynamically attach to the same running session:
|
|
83
108
|
|
|
84
109
|
```bash
|
|
85
|
-
#
|
|
86
|
-
run-mcp
|
|
110
|
+
# Spawns a background session daemon & launches a browser
|
|
111
|
+
run-mcp call browser_launch headless:=true --session main -- node browser-server.js
|
|
87
112
|
|
|
88
|
-
#
|
|
89
|
-
run-mcp call
|
|
113
|
+
# Navigates the browser on the active running session (no target command needed!)
|
|
114
|
+
run-mcp call browser_navigate url=https://google.com --session main
|
|
90
115
|
|
|
91
|
-
#
|
|
92
|
-
run-mcp
|
|
116
|
+
# Closes the session and stops the background target server
|
|
117
|
+
run-mcp close-session main
|
|
93
118
|
```
|
|
94
119
|
|
|
95
|
-
Available
|
|
96
|
-
|
|
120
|
+
### Available Headless Subcommands
|
|
121
|
+
|
|
122
|
+
- `call <tool> [json_or_shorthand_args]`
|
|
97
123
|
- `list-tools`
|
|
98
124
|
- `list-resources`
|
|
99
125
|
- `list-prompts`
|
|
100
126
|
- `read <uri>`
|
|
101
127
|
- `describe <tool>`
|
|
102
|
-
- `get-prompt <name> [
|
|
128
|
+
- `get-prompt <name> [json_or_shorthand_args]`
|
|
129
|
+
- `close-session <session_name>`
|
|
130
|
+
|
|
131
|
+
Use `run-mcp <subcommand> --help` for specific command options.
|
|
103
132
|
|
|
104
|
-
Use `run-mcp <subcommand> --help` for specific command options (like `--timeout` and `--raw`).
|
|
105
133
|
## Agent Use Cases
|
|
106
134
|
|
|
107
135
|
### Dynamic Testing
|
|
108
136
|
|
|
109
|
-
When an AI agent is actively
|
|
137
|
+
When an AI agent is actively _developing_ an MCP server, it needs to test it. Standard MCP clients require updating a configuration file (`mcp.json`) and restarting the agent session entirely.
|
|
110
138
|
|
|
111
139
|
`run-mcp` solves this by giving the agent a suite of tools to dynamically spawn, inspect, and test local MCP servers on the fly.
|
|
112
140
|
|
|
113
141
|
**How to use:**
|
|
114
142
|
Add `run-mcp` to your agent's MCP configuration using `npx`:
|
|
143
|
+
|
|
115
144
|
```json
|
|
116
145
|
{
|
|
117
146
|
"mcpServers": {
|
|
@@ -125,30 +154,30 @@ Add `run-mcp` to your agent's MCP configuration using `npx`:
|
|
|
125
154
|
|
|
126
155
|
Then use these tools from your agent:
|
|
127
156
|
|
|
128
|
-
| Tool
|
|
129
|
-
|
|
130
|
-
| `connect_to_mcp`
|
|
131
|
-
| `disconnect_from_mcp`
|
|
132
|
-
| `mcp_server_status`
|
|
133
|
-
| `call_mcp_primitive`
|
|
134
|
-
| `list_mcp_primitives`
|
|
135
|
-
| `get_mcp_server_stderr`
|
|
136
|
-
| `list_available_mcp_servers
|
|
157
|
+
| Tool | Description |
|
|
158
|
+
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
159
|
+
| `connect_to_mcp` | Spawn and connect to a local MCP server. Use `include` to get tools/resources/prompts inline. Shows a diff on reconnect. |
|
|
160
|
+
| `disconnect_from_mcp` | Tear down the connection |
|
|
161
|
+
| `mcp_server_status` | Check connection status |
|
|
162
|
+
| `call_mcp_primitive` | Call a tool, read a resource, or get a prompt. Auto-connects if not already connected. Use `disconnect_after` for one-shot tests. |
|
|
163
|
+
| `list_mcp_primitives` | List tools, resources, and/or prompts on the connected server |
|
|
164
|
+
| `get_mcp_server_stderr` | View target server stderr output |
|
|
165
|
+
| `list_available_mcp_servers` | Discover other local MCP servers configured on the host machine |
|
|
137
166
|
|
|
138
167
|
## REPL Mode Commands
|
|
139
168
|
|
|
140
169
|
Once connected via `run-mcp <command>`, the following shorthand commands are available:
|
|
141
170
|
|
|
142
|
-
| Command
|
|
143
|
-
|
|
144
|
-
| `explore`
|
|
145
|
-
| `tools/list`
|
|
146
|
-
| `tools/describe <name>`
|
|
171
|
+
| Command | Description |
|
|
172
|
+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
|
|
173
|
+
| `explore` | Open interactive fuzzy-search selector for tools, resources, and prompts |
|
|
174
|
+
| `tools/list` | List all tools exposed by the target server |
|
|
175
|
+
| `tools/describe <name>` | Show a tool's full input schema |
|
|
147
176
|
| `tools/call <name> [json] [--clear]` | Call a tool. Launch interactive wizard if no JSON provided. Use `--clear` to ignore remembered arguments. |
|
|
148
|
-
| `tools/forget [name]`
|
|
149
|
-
| `status`
|
|
150
|
-
| `help`
|
|
151
|
-
| `exit` / `quit`
|
|
177
|
+
| `tools/forget [name]` | Clear remembered interactive arguments for a tool, or all tools if no name provided. |
|
|
178
|
+
| `status` | Show target server status (PID, uptime, connection) |
|
|
179
|
+
| `help` | Show available commands |
|
|
180
|
+
| `exit` / `quit` | Disconnect and exit |
|
|
152
181
|
|
|
153
182
|
### Examples
|
|
154
183
|
|
|
@@ -167,10 +196,21 @@ Once connected via `run-mcp <command>`, the following shorthand commands are ava
|
|
|
167
196
|
|
|
168
197
|
# Arguments with spaces work fine
|
|
169
198
|
> tools/call send_message {"text": "hello world", "channel": "general"}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Direct Inline Tool Calls & Shorthand Arguments
|
|
202
|
+
|
|
203
|
+
Instead of prefixing every tool call with `tools/call`, you can invoke any target server tool directly by name, and provide arguments in shorthand key-value form:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
# Direct inline tool execution with HTTPie shorthand parameters
|
|
207
|
+
> greet name=Bob count:=3
|
|
208
|
+
```
|
|
170
209
|
|
|
171
210
|
### Interactive Wizard & Argument Memory
|
|
172
211
|
|
|
173
212
|
If you invoke a tool without JSON arguments, `run-mcp` will guide you through an interactive scaffolding wizard:
|
|
213
|
+
|
|
174
214
|
```bash
|
|
175
215
|
> tools/call send_message
|
|
176
216
|
✔ text (string) Message text to send: Hello World!
|
|
@@ -179,8 +219,8 @@ If you invoke a tool without JSON arguments, `run-mcp` will guide you through an
|
|
|
179
219
|
✔ Execute? Yes
|
|
180
220
|
Calling send_message...
|
|
181
221
|
```
|
|
222
|
+
|
|
182
223
|
`run-mcp` actively **remembers** your inputs across identical interactive calls, scaffolding defaults based on your last execution! Use `tools/forget` or `--clear` if you need a clean slate.
|
|
183
|
-
```
|
|
184
224
|
|
|
185
225
|
### Script Mode
|
|
186
226
|
|
|
@@ -194,7 +234,7 @@ tools/call screenshot {"save_path": "/tmp/test.png"}
|
|
|
194
234
|
```
|
|
195
235
|
|
|
196
236
|
```bash
|
|
197
|
-
run-mcp
|
|
237
|
+
run-mcp -s commands.txt -- node my-server.js
|
|
198
238
|
```
|
|
199
239
|
|
|
200
240
|
- Lines starting with `#` are treated as comments
|
|
@@ -209,7 +249,7 @@ In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the comma
|
|
|
209
249
|
"mcpServers": {
|
|
210
250
|
"my-server": {
|
|
211
251
|
"command": "run-mcp",
|
|
212
|
-
"args": ["
|
|
252
|
+
"args": ["--mcp", "--out-dir", "./images", "--", "node", "path/to/actual-server.js"]
|
|
213
253
|
}
|
|
214
254
|
}
|
|
215
255
|
}
|
|
@@ -219,28 +259,28 @@ In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the comma
|
|
|
219
259
|
|
|
220
260
|
The proxy dynamically mirrors the target server's capabilities. All MCP primitives that the target supports are forwarded transparently:
|
|
221
261
|
|
|
222
|
-
| Primitive
|
|
223
|
-
|
|
224
|
-
| **Tools** (`tools/list`, `tools/call`)
|
|
225
|
-
| **Resources** (`resources/list`, `resources/read`, `resources/templates/list`) | ✅ If target supports
|
|
226
|
-
| **Prompts** (`prompts/list`, `prompts/get`)
|
|
227
|
-
| **Logging** (`logging/setLevel`)
|
|
228
|
-
| **Completion** (`completion/complete`)
|
|
229
|
-
| **Notifications** (list changes, logging)
|
|
230
|
-
| **Tool annotations** (`readOnlyHint`, `destructiveHint`, etc.)
|
|
231
|
-
| **Pagination** (`nextCursor` / `cursor`)
|
|
262
|
+
| Primitive | Forwarded? |
|
|
263
|
+
| ------------------------------------------------------------------------------ | --------------------------------- |
|
|
264
|
+
| **Tools** (`tools/list`, `tools/call`) | ✅ Always (with interception) |
|
|
265
|
+
| **Resources** (`resources/list`, `resources/read`, `resources/templates/list`) | ✅ If target supports |
|
|
266
|
+
| **Prompts** (`prompts/list`, `prompts/get`) | ✅ If target supports |
|
|
267
|
+
| **Logging** (`logging/setLevel`) | ✅ If target supports |
|
|
268
|
+
| **Completion** (`completion/complete`) | ✅ If target supports |
|
|
269
|
+
| **Notifications** (list changes, logging) | ✅ Forwarded from target to agent |
|
|
270
|
+
| **Tool annotations** (`readOnlyHint`, `destructiveHint`, etc.) | ✅ Preserved as-is |
|
|
271
|
+
| **Pagination** (`nextCursor` / `cursor`) | ✅ Passed through |
|
|
232
272
|
|
|
233
273
|
### What the proxy intercepts
|
|
234
274
|
|
|
235
275
|
Tool call responses are processed through the interceptor pipeline. All other primitives pass through untouched.
|
|
236
276
|
|
|
237
|
-
| Feature
|
|
238
|
-
|
|
239
|
-
| **Image extraction** | `type: "image"` responses with base64 data are saved to disk. Replaced with `[Image saved to /path/to/img.png (24KB)]`
|
|
277
|
+
| Feature | Behavior |
|
|
278
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
279
|
+
| **Image extraction** | `type: "image"` responses with base64 data are saved to disk. Replaced with `[Image saved to /path/to/img.png (24KB)]` |
|
|
240
280
|
| **Audio extraction** | `type: "audio"` responses with base64 data are saved to disk. Replaced with `[Audio saved to /path/to/audio.wav (12KB)]` |
|
|
241
|
-
| **Base64 detection** | Text responses that are entirely base64-encoded (1000+ chars) are also saved as images
|
|
242
|
-
| **Timeouts**
|
|
243
|
-
| **Truncation**
|
|
281
|
+
| **Base64 detection** | Text responses that are entirely base64-encoded (1000+ chars) are also saved as images |
|
|
282
|
+
| **Timeouts** | Tool calls are wrapped in a configurable timeout (default 60s, use `--timeout` to change) |
|
|
283
|
+
| **Truncation** | Text responses exceeding the limit (default 50K chars, use `--max-text` to change) are truncated |
|
|
244
284
|
|
|
245
285
|
## Architecture
|
|
246
286
|
|
|
@@ -270,12 +310,12 @@ Tool call responses are processed through the interceptor pipeline. All other pr
|
|
|
270
310
|
|
|
271
311
|
### Modules
|
|
272
312
|
|
|
273
|
-
| Module
|
|
274
|
-
|
|
275
|
-
| **TargetManager**
|
|
276
|
-
| **ResponseInterceptor** | `src/interceptor.ts`
|
|
277
|
-
| **REPLMode**
|
|
278
|
-
| **
|
|
313
|
+
| Module | File | Responsibility |
|
|
314
|
+
| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
315
|
+
| **TargetManager** | `src/target-manager.ts` | Spawns the target MCP server, manages the MCP Client connection, forwards all MCP primitives (tools, resources, prompts, logging), captures stderr, tracks lifecycle |
|
|
316
|
+
| **ResponseInterceptor** | `src/interceptor.ts` | Wraps tool calls with timeouts, extracts base64 images and audio to disk, truncates oversized text |
|
|
317
|
+
| **REPLMode** | `src/repl.ts` | Interactive readline REPL with shorthand command parsing and script mode |
|
|
318
|
+
| **AgentServer** | `src/server.ts` | MCP Server that dynamically exposes primitives to agents and proxies target servers |
|
|
279
319
|
|
|
280
320
|
## Development
|
|
281
321
|
|
|
@@ -290,9 +330,9 @@ npm run build
|
|
|
290
330
|
npm run dev
|
|
291
331
|
|
|
292
332
|
# Run directly
|
|
293
|
-
node dist/index.js
|
|
333
|
+
node dist/index.js -- <target_command...>
|
|
294
334
|
```
|
|
295
335
|
|
|
296
336
|
## License
|
|
297
337
|
|
|
298
|
-
MIT
|
|
338
|
+
MIT
|