run-mcp 1.5.1 → 1.6.1
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 +121 -58
- package/dist/index.js +2223 -680
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -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,34 +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
|
+
## Headless Mode (Single-Shot CI/CD)
|
|
80
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.
|
|
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:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# Spawns a background session daemon & launches a browser
|
|
111
|
+
run-mcp call browser_launch headless:=true --session main -- node browser-server.js
|
|
112
|
+
|
|
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
|
|
115
|
+
|
|
116
|
+
# Closes the session and stops the background target server
|
|
117
|
+
run-mcp close-session main
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Available Headless Subcommands
|
|
121
|
+
|
|
122
|
+
- `call <tool> [json_or_shorthand_args]`
|
|
123
|
+
- `list-tools`
|
|
124
|
+
- `list-resources`
|
|
125
|
+
- `list-prompts`
|
|
126
|
+
- `read <uri>`
|
|
127
|
+
- `describe <tool>`
|
|
128
|
+
- `get-prompt <name> [json_or_shorthand_args]`
|
|
129
|
+
- `close-session <session_name>`
|
|
130
|
+
|
|
131
|
+
Use `run-mcp <subcommand> --help` for specific command options.
|
|
81
132
|
|
|
82
133
|
## Agent Use Cases
|
|
83
134
|
|
|
84
135
|
### Dynamic Testing
|
|
85
136
|
|
|
86
|
-
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.
|
|
87
138
|
|
|
88
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.
|
|
89
140
|
|
|
90
141
|
**How to use:**
|
|
91
142
|
Add `run-mcp` to your agent's MCP configuration using `npx`:
|
|
143
|
+
|
|
92
144
|
```json
|
|
93
145
|
{
|
|
94
146
|
"mcpServers": {
|
|
@@ -102,30 +154,30 @@ Add `run-mcp` to your agent's MCP configuration using `npx`:
|
|
|
102
154
|
|
|
103
155
|
Then use these tools from your agent:
|
|
104
156
|
|
|
105
|
-
| Tool
|
|
106
|
-
|
|
107
|
-
| `connect_to_mcp`
|
|
108
|
-
| `disconnect_from_mcp`
|
|
109
|
-
| `mcp_server_status`
|
|
110
|
-
| `call_mcp_primitive`
|
|
111
|
-
| `list_mcp_primitives`
|
|
112
|
-
| `get_mcp_server_stderr`
|
|
113
|
-
| `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 |
|
|
114
166
|
|
|
115
167
|
## REPL Mode Commands
|
|
116
168
|
|
|
117
169
|
Once connected via `run-mcp <command>`, the following shorthand commands are available:
|
|
118
170
|
|
|
119
|
-
| Command
|
|
120
|
-
|
|
121
|
-
| `explore`
|
|
122
|
-
| `tools/list`
|
|
123
|
-
| `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 |
|
|
124
176
|
| `tools/call <name> [json] [--clear]` | Call a tool. Launch interactive wizard if no JSON provided. Use `--clear` to ignore remembered arguments. |
|
|
125
|
-
| `tools/forget [name]`
|
|
126
|
-
| `status`
|
|
127
|
-
| `help`
|
|
128
|
-
| `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 |
|
|
129
181
|
|
|
130
182
|
### Examples
|
|
131
183
|
|
|
@@ -144,10 +196,21 @@ Once connected via `run-mcp <command>`, the following shorthand commands are ava
|
|
|
144
196
|
|
|
145
197
|
# Arguments with spaces work fine
|
|
146
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
|
+
```
|
|
147
209
|
|
|
148
210
|
### Interactive Wizard & Argument Memory
|
|
149
211
|
|
|
150
212
|
If you invoke a tool without JSON arguments, `run-mcp` will guide you through an interactive scaffolding wizard:
|
|
213
|
+
|
|
151
214
|
```bash
|
|
152
215
|
> tools/call send_message
|
|
153
216
|
✔ text (string) Message text to send: Hello World!
|
|
@@ -156,8 +219,8 @@ If you invoke a tool without JSON arguments, `run-mcp` will guide you through an
|
|
|
156
219
|
✔ Execute? Yes
|
|
157
220
|
Calling send_message...
|
|
158
221
|
```
|
|
222
|
+
|
|
159
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.
|
|
160
|
-
```
|
|
161
224
|
|
|
162
225
|
### Script Mode
|
|
163
226
|
|
|
@@ -186,7 +249,7 @@ In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the comma
|
|
|
186
249
|
"mcpServers": {
|
|
187
250
|
"my-server": {
|
|
188
251
|
"command": "run-mcp",
|
|
189
|
-
"args": ["
|
|
252
|
+
"args": ["--mcp", "--out-dir", "./images", "--", "node", "path/to/actual-server.js"]
|
|
190
253
|
}
|
|
191
254
|
}
|
|
192
255
|
}
|
|
@@ -196,28 +259,28 @@ In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the comma
|
|
|
196
259
|
|
|
197
260
|
The proxy dynamically mirrors the target server's capabilities. All MCP primitives that the target supports are forwarded transparently:
|
|
198
261
|
|
|
199
|
-
| Primitive
|
|
200
|
-
|
|
201
|
-
| **Tools** (`tools/list`, `tools/call`)
|
|
202
|
-
| **Resources** (`resources/list`, `resources/read`, `resources/templates/list`) | ✅ If target supports
|
|
203
|
-
| **Prompts** (`prompts/list`, `prompts/get`)
|
|
204
|
-
| **Logging** (`logging/setLevel`)
|
|
205
|
-
| **Completion** (`completion/complete`)
|
|
206
|
-
| **Notifications** (list changes, logging)
|
|
207
|
-
| **Tool annotations** (`readOnlyHint`, `destructiveHint`, etc.)
|
|
208
|
-
| **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 |
|
|
209
272
|
|
|
210
273
|
### What the proxy intercepts
|
|
211
274
|
|
|
212
275
|
Tool call responses are processed through the interceptor pipeline. All other primitives pass through untouched.
|
|
213
276
|
|
|
214
|
-
| Feature
|
|
215
|
-
|
|
216
|
-
| **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)]` |
|
|
217
280
|
| **Audio extraction** | `type: "audio"` responses with base64 data are saved to disk. Replaced with `[Audio saved to /path/to/audio.wav (12KB)]` |
|
|
218
|
-
| **Base64 detection** | Text responses that are entirely base64-encoded (1000+ chars) are also saved as images
|
|
219
|
-
| **Timeouts**
|
|
220
|
-
| **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 |
|
|
221
284
|
|
|
222
285
|
## Architecture
|
|
223
286
|
|
|
@@ -247,12 +310,12 @@ Tool call responses are processed through the interceptor pipeline. All other pr
|
|
|
247
310
|
|
|
248
311
|
### Modules
|
|
249
312
|
|
|
250
|
-
| Module
|
|
251
|
-
|
|
252
|
-
| **TargetManager**
|
|
253
|
-
| **ResponseInterceptor** | `src/interceptor.ts`
|
|
254
|
-
| **REPLMode**
|
|
255
|
-
| **
|
|
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 |
|
|
256
319
|
|
|
257
320
|
## Development
|
|
258
321
|
|
|
@@ -272,4 +335,4 @@ node dist/index.js repl <target_command...>
|
|
|
272
335
|
|
|
273
336
|
## License
|
|
274
337
|
|
|
275
|
-
MIT
|
|
338
|
+
MIT
|