run-mcp 1.3.2 → 1.5.0

package/README.md

@@ -4,10 +4,10 @@ A smart proxy, interactive REPL, and live test harness for [Model Context Protoc
 
 `run-mcp` operates in two modes:
 
-1. **Interactive REPL** (`run-mcp repl`) — A headless CLI for human developers to manually test and explore MCP servers using short, memorable commands (`tools/call`, `status`, etc.).
-2. **Server Mode** (`run-mcp server`) — 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.
+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`.
+2. **Interactive REPL** (`run-mcp repl`) — A headless CLI for human developers to manually test and explore MCP servers using short, memorable commands (`tools/call`, `status`, etc.).
 
-### Interception Rules (Server Mode & REPL)
+### Interception Rules (Agent Server & REPL)
 
 To protect the CLI and parent agents from large payloads, `run-mcp` automatically applies the following rules:
 
@@ -40,6 +40,9 @@ run-mcp repl node path/to/my-mcp-server.js
 
 # Or use npx without installing globally
 npx . repl node path/to/my-mcp-server.js
+
+# Or start it without arguments to open the interactive server discovery menu!
+run-mcp
 ```
 
 You'll see an interactive prompt:
@@ -55,47 +58,43 @@ You'll see an interactive prompt:
 
 ## Usage
 
-```
-run-mcp <command> [options]
-
-Commands:
-  repl <target_command...>    Start an interactive REPL session
-  server                      Start as an MCP server for agents
+run-mcp [options] [target_command...]
 
 Options:
   -V, --version               Show version number
-  -h, --help                  Show help
-```
+  -o, --out-dir <path>        Directory to save intercepted images and audio
+  -t, --timeout <ms>          Default tool call timeout in milliseconds (default: 300000) (Agent Mode only)
+      --max-text <chars>      Max text response length before truncation (default: 50000) (Agent Mode only)
+      --mcp                   Force start Agent Server mode even if run interactively without arguments
+  -s, --script <file>         Read commands from a file instead of stdin (REPL Mode only)
+  -h, --help                  Display help for command
 
-### REPL Command
+Examples:
+  $ run-mcp                                       # Test harness (agent mode)
+  $ run-mcp node my-server.js                     # Interactive testing (human REPL mode)
+  $ run-mcp node my-server.js -s test.txt         # Run a script in REPL mode
+  $ run-mcp npx -y some-mcp-server                # Test an npx server
+  $ run-mcp --out-dir ./test-output               # Agent mode with options
+  $ run-mcp --out-dir ./screenshots node srv.js   # REPL mode with options
 
-```
-run-mcp repl <target_command...> [options]
 
-Options:
-  -s, --script <file>    Read commands from a file instead of stdin
-  -o, --out-dir <path>   Directory to save intercepted images (default: $TMPDIR/run-mcp)
-```
 
-### Server Command
+## Agent Use Cases
 
-```
-run-mcp server [options]
+### Dynamic Testing
 
-Options:
-  -o, --out-dir <path>     Directory to save intercepted images and audio (default: $TMPDIR/run-mcp)
-  -t, --timeout <ms>       Default tool call timeout in milliseconds (default: 60000)
-      --max-text <chars>   Max text response length before truncation (default: 50000)
-```
+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.
 
-Add to your MCP client configuration:
+`run-mcp` solves this by giving the agent a suite of tools to dynamically spawn, inspect, and test local MCP servers on the fly.
 
+**How to use:**
+Add `run-mcp` to your agent's MCP configuration using `npx`:
 ```json
 {
   "mcpServers": {
     "run-mcp": {
       "command": "npx",
-      "args": ["-y", "run-mcp", "server"]
+      "args": ["-y", "run-mcp"]
     }
   }
 }
@@ -105,26 +104,25 @@ Then use these tools from your agent:
 
 | Tool | Description |
 |------|-------------|
-| `connect_to_mcp` | Spawn and connect to a local MCP server |
+| `connect_to_mcp` | Spawn and connect to a local MCP server. Use `include` to get tools/resources/prompts inline. Shows a diff on reconnect. |
 | `disconnect_from_mcp` | Tear down the connection |
 | `mcp_server_status` | Check connection status |
-| `list_mcp_tools` | List tools on the connected server |
-| `call_mcp_tool` | Call a tool (with interception) |
-| `list_mcp_resources` | List resources |
-| `read_mcp_resource` | Read a resource by URI |
-| `list_mcp_prompts` | List prompts |
-| `get_mcp_prompt` | Get a prompt by name |
+| `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. |
+| `list_mcp_primitives` | List tools, resources, and/or prompts on the connected server |
 | `get_mcp_server_stderr` | View target server stderr output |
+| `list_available_mcp_servers`| Discover other local MCP servers configured on the host machine |
 
-## REPL Commands
+## REPL Mode Commands
 
-Once in the REPL, these commands are available:
+Once connected via `run-mcp <command>`, the following shorthand commands are available:
 
 | Command | Description |
 |---------|-------------|
+| `explore` | Open interactive fuzzy-search selector for tools, resources, and prompts |
 | `tools/list` | List all tools exposed by the target server |
 | `tools/describe <name>` | Show a tool's full input schema |
-| `tools/call <name> <json> [--timeout <ms>]` | Call a tool with JSON arguments |
+| `tools/call <name> [json] [--clear]` | Call a tool. Launch interactive wizard if no JSON provided. Use `--clear` to ignore remembered arguments. |
+| `tools/forget [name]` | Clear remembered interactive arguments for a tool, or all tools if no name provided. |
 | `status` | Show target server status (PID, uptime, connection) |
 | `help` | Show available commands |
 | `exit` / `quit` | Disconnect and exit |
@@ -146,6 +144,19 @@ Once in the REPL, these commands are available:
 
 # Arguments with spaces work fine
 > tools/call send_message {"text": "hello world", "channel": "general"}
+
+### Interactive Wizard & Argument Memory
+
+If you invoke a tool without JSON arguments, `run-mcp` will guide you through an interactive scaffolding wizard:
+```bash
+> tools/call send_message
+✔ text (string) Message text to send: Hello World!
+✔ Select optional arguments to provide: channel
+✔ channel (string) The Slack channel: general
+✔ Execute? Yes
+  Calling send_message...
+```
+`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.
 ```
 
 ### Script Mode
@@ -261,4 +272,4 @@ node dist/index.js repl <target_command...>
 
 ## License
 
-ISC
+MIT