run-mcp 1.3.2 → 1.3.4

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:
 
@@ -55,47 +55,42 @@ 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)
+  -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"]
     }
   }
 }
@@ -116,9 +111,9 @@ Then use these tools from your agent:
 | `get_mcp_prompt` | Get a prompt by name |
 | `get_mcp_server_stderr` | View target server stderr output |
 
-## 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 |
 |---------|-------------|

package/dist/index.js

@@ -318,7 +318,11 @@ var TargetManager = class _TargetManager extends EventEmitter {
   async callTool(name, args = {}, _timeoutMs) {
     this._assertConnected();
     const requestOptions = { timeout: 36e5 * 10 };
-    const result = await this.client.callTool({ name, arguments: args }, void 0, requestOptions);
+    const result = await this.client.callTool(
+      { name, arguments: args },
+      void 0,
+      requestOptions
+    );
     this.recordResponse();
     return result;
   }
@@ -1029,7 +1033,10 @@ Check that the command is correct and the server starts without errors. You can
       if (!target?.connected) {
         return {
           content: [
-            { type: "text", text: "No target server connected. Use connect_to_mcp first." }
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
           ],
           isError: true
         };
@@ -1041,16 +1048,17 @@ Check that the command is correct and the server starts without errors. You can
           const available = result.tools.map((t) => t.name).join(", ");
           return {
             content: [
-              { type: "text", text: `Tool "${name}" not found.
-Available tools: ${available}` }
+              {
+                type: "text",
+                text: `Tool "${name}" not found.
+Available tools: ${available}`
+              }
             ],
             isError: true
           };
         }
         return {
-          content: [
-            { type: "text", text: JSON.stringify(tool, null, 2) }
-          ]
+          content: [{ type: "text", text: JSON.stringify(tool, null, 2) }]
         };
       } catch (err) {
         return {
@@ -1277,68 +1285,60 @@ Available tools: ${available}` }
 }
 
 // src/index.ts
-program.name("run-mcp").enablePositionalOptions().description(
-  "A smart interactive REPL and live test harness for MCP servers.\n\nOperates in two modes:\n  repl    - Human-friendly CLI for testing MCP servers interactively\n  server  - MCP server that lets AI agents dynamically test local MCP servers"
-).version("1.3.1").addHelpText(
-  "after",
-  `
-Examples:
-  $ run-mcp repl node my-server.js               # Interactive testing (human)
-  $ run-mcp repl node my-server.js -s test.txt    # Run a script
-  $ run-mcp server                                # Test harness (agent)
-  $ run-mcp repl npx -y some-mcp-server           # Test an npx server
-
-Run 'run-mcp <command> --help' for detailed options.`
-);
-if (process.argv.length <= 2) {
-  program.outputHelp();
-  process.exit(0);
-}
-program.command("repl").description("Start an interactive REPL session with a target MCP server").passThroughOptions().allowUnknownOption().argument("<target_command...>", "Command to spawn the target MCP server").option("-s, --script <file>", "Read commands from a file instead of stdin").option("-o, --out-dir <path>", "Directory to save intercepted images").addHelpText(
+program.name("run-mcp").description("A smart interactive REPL and live test harness for MCP servers").version("1.3.4").passThroughOptions().allowUnknownOption().argument(
+  "[target_command...]",
+  "Command to spawn the target MCP server (starts REPL if provided, Agent server otherwise)"
+).option("-o, --out-dir <path>", "Directory to save intercepted images and audio").option(
+  "-t, --timeout <ms>",
+  "Default tool call timeout in milliseconds (default: 300000) (Agent Mode only)"
+).option(
+  "--max-text <chars>",
+  "Max text response length before truncation (default: 50000) (Agent Mode only)"
+).option("-s, --script <file>", "Read commands from a file instead of stdin (REPL Mode only)").addHelpText(
   "after",
   `
 Examples:
-  $ run-mcp repl node my-server.js
-  $ run-mcp repl node my-server.js --script verify.txt
-  $ run-mcp repl node my-server.js --out-dir ./screenshots
+  $ 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
 
-REPL Commands (once connected):
-  tools/list                          List all available tools
-  tools/describe <name>               Show a tool's input schema
-  tools/call <name> <json> [opts]     Call a tool with JSON arguments
-  status                              Show target server status
-  help                                Show all commands`
-).action(async (targetCommand, opts) => {
-  await startRepl(targetCommand, opts);
-});
-program.command("server").description("Start as an MCP server that lets AI agents dynamically test local MCP servers").option("-o, --out-dir <path>", "Directory to save intercepted images and audio").option("-t, --timeout <ms>", "Default tool call timeout in milliseconds (default: 300000)").option("--max-text <chars>", "Max text response length before truncation (default: 50000)").addHelpText(
-  "after",
-  `
-Examples:
-  $ run-mcp server
-  $ run-mcp server --out-dir ./test-output
-  $ run-mcp server --timeout 120000
-
-Add to your MCP client configuration:
+Agent Mode Configuration (mcp.json):
   {
     "mcpServers": {
       "run-mcp": {
         "command": "npx",
-        "args": ["-y", "run-mcp", "server"]
+        "args": ["-y", "run-mcp"]
       }
     }
   }
 
-Then use these tools from your agent:
+Agent Mode Tools:
   connect_to_mcp      \u2192 Spawn and connect to a local MCP server
   list_mcp_tools      \u2192 List tools on the connected server
+  describe_mcp_tool   \u2192 Show a tool's input schema
   call_mcp_tool       \u2192 Call a tool (with interception)
-  disconnect_from_mcp \u2192 Tear down and reconnect after changes`
-).action(async (opts) => {
-  await startServer({
-    outDir: opts.outDir,
-    timeoutMs: opts.timeout ? Number.parseInt(opts.timeout, 10) : void 0,
-    maxTextLength: opts.maxText ? Number.parseInt(opts.maxText, 10) : void 0
-  });
-});
+  disconnect_from_mcp \u2192 Tear down and reconnect after changes
+
+REPL Mode Commands (once connected):
+  tools/list                          List all available tools
+  tools/describe <name>               Show a tool's input schema
+  tools/call <name> <json> [opts]     Call a tool with JSON arguments
+  status                              Show target server status
+  help                                Show all commands`
+).action(
+  async (targetCommand, opts) => {
+    if (targetCommand && targetCommand.length > 0) {
+      await startRepl(targetCommand, { script: opts.script, outDir: opts.outDir });
+    } else {
+      await startServer({
+        outDir: opts.outDir,
+        timeoutMs: opts.timeout ? Number.parseInt(opts.timeout, 10) : void 0,
+        maxTextLength: opts.maxText ? Number.parseInt(opts.maxText, 10) : void 0
+      });
+    }
+  }
+);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-mcp",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "A smart proxy and interactive REPL for Model Context Protocol (MCP) servers",
   "homepage": "https://github.com/funkyfunc/run-mcp#readme",
   "bugs": {