run-mcp 1.3.0 → 1.3.4

package/README.md

@@ -2,17 +2,14 @@
 
 A smart proxy, interactive REPL, and live test harness for [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers.
 
-`run-mcp` wraps any MCP server and operates in three modes:
+`run-mcp` operates in two modes:
 
-| Mode | Audience | Purpose |
-|------|----------|---------|
-| **`repl`** | Humans / developers | Interactive CLI for testing and exploring MCP servers with shorthand commands |
-| **`proxy`** | AI agents (transparent) | Transparent MCP proxy that intercepts responses to save images to disk, enforce timeouts, and truncate massive payloads |
-| **`server`** | AI agents (explicit) | MCP server that lets agents dynamically connect to, inspect, and test local MCP servers |
+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.).
 
-## Why?
+### Interception Rules (Agent Server & REPL)
 
-MCP servers often return large base64-encoded images (screenshots, charts) or massive JSON payloads that can blow up an AI agent's context window. `run-mcp` sits between the agent and the server, transparently:
+To protect the CLI and parent agents from large payloads, `run-mcp` automatically applies the following rules:
 
 - **Saving images to disk** instead of passing multi-MB base64 strings through
 - **Enforcing timeouts** so a hung tool call doesn't block forever
@@ -56,68 +53,44 @@ You'll see an interactive prompt:
 >
 ```
 
-### Proxy Mode — Protect your agent's context
-
-```bash
-run-mcp proxy node path/to/my-mcp-server.js --out-dir ./captured-images
-```
-
-Then point your AI agent at `run-mcp` as the MCP server command. It transparently forwards all tools while sanitizing responses.
-
 ## Usage
 
-```
-run-mcp <command> [options]
-
-Commands:
-  repl <target_command...>    Start an interactive REPL session
-  proxy <target_command...>   Start as a transparent MCP proxy
+run-mcp [options] [target_command...]
 
 Options:
   -V, --version               Show version number
-  -h, --help                  Show help
-```
-
-### REPL Command
-
-```
-run-mcp repl <target_command...> [options]
+  -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
 
-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)
-```
+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
 
-### Proxy Command
-
-```
-run-mcp proxy <target_command...> [options]
 
-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)
-```
 
-### 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"]
     }
   }
 }
@@ -138,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

@@ -3,33 +3,17 @@
 // src/index.ts
 import { program } from "commander";
 
-// src/proxy.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  CompleteRequestSchema,
-  GetPromptRequestSchema,
-  ListPromptsRequestSchema,
-  ListResourcesRequestSchema,
-  ListResourceTemplatesRequestSchema,
-  ListToolsRequestSchema,
-  LoggingMessageNotificationSchema,
-  PromptListChangedNotificationSchema,
-  ReadResourceRequestSchema,
-  ResourceListChangedNotificationSchema,
-  SetLevelRequestSchema,
-  SubscribeRequestSchema,
-  ToolListChangedNotificationSchema,
-  UnsubscribeRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
+// src/repl.ts
+import { readFile } from "fs/promises";
+import { createInterface } from "readline";
+import pc from "picocolors";
 
 // src/interceptor.ts
 import { mkdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
 var BASE64_PATTERN = /^[A-Za-z0-9+/]{1000,}={0,2}$/;
-var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_TIMEOUT_MS = 3e5;
 var DEFAULT_MAX_TEXT_LENGTH = 5e4;
 var ResponseInterceptor = class {
   outDir;
@@ -49,7 +33,10 @@ var ResponseInterceptor = class {
    */
   async callTool(target, name, args = {}, timeoutMs) {
     const timeout = timeoutMs ?? this.defaultTimeoutMs;
-    const result = await Promise.race([target.callTool(name, args), this._timeout(timeout, name)]);
+    const targetCall = target.callTool(name, args);
+    targetCall.catch(() => {
+    });
+    const result = await Promise.race([targetCall, this._timeout(timeout, name)]);
     const content = result.content;
     if (Array.isArray(content)) {
       for (let i = 0; i < content.length; i++) {
@@ -146,6 +133,67 @@ var ResponseInterceptor = class {
   }
 };
 
+// src/parsing.ts
+function parseCommandLine(input) {
+  const spaceIdx = input.indexOf(" ");
+  if (spaceIdx === -1) {
+    return { cmd: input.toLowerCase(), rest: "" };
+  }
+  return {
+    cmd: input.slice(0, spaceIdx).toLowerCase(),
+    rest: input.slice(spaceIdx + 1)
+  };
+}
+function parseCallArgs(rest) {
+  const trimmed = rest.trim();
+  if (!trimmed) return { toolName: "", jsonArgs: "" };
+  const spaceIdx = trimmed.indexOf(" ");
+  if (spaceIdx === -1) {
+    return { toolName: trimmed, jsonArgs: "" };
+  }
+  const toolName = trimmed.slice(0, spaceIdx);
+  let remainder = trimmed.slice(spaceIdx + 1).trim();
+  let timeoutMs;
+  const timeoutMatch = remainder.match(/\s--timeout\s+(\d+)\s*$/);
+  if (timeoutMatch) {
+    timeoutMs = parseInt(timeoutMatch[1], 10);
+    remainder = remainder.slice(0, timeoutMatch.index).trim();
+  }
+  return { toolName, jsonArgs: remainder, timeoutMs };
+}
+function formatJson(obj, indent = 2) {
+  const json = JSON.stringify(obj, null, indent);
+  return json.split("\n").map((line) => " ".repeat(indent) + line).join("\n");
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+function suggestCommand(input, commands, threshold = 0.4) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of commands) {
+    const dist = levenshtein(input, cmd);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = cmd;
+    }
+  }
+  if (best && bestDist <= Math.ceil(input.length * threshold)) {
+    return best;
+  }
+  return null;
+}
+
 // src/target-manager.ts
 import { EventEmitter } from "events";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -204,7 +252,7 @@ var TargetManager = class _TargetManager extends EventEmitter {
         this.emit("stderr", text);
       }
     });
-    this.client = new Client({ name: "run-mcp", version: "1.3.0" }, { capabilities: {} });
+    this.client = new Client({ name: "run-mcp", version: "1.3.1" }, { capabilities: {} });
     this.client.onclose = () => {
       this._connected = false;
       this._clearStableTimer();
@@ -262,10 +310,19 @@ var TargetManager = class _TargetManager extends EventEmitter {
   }
   /**
    * Call a tool on the target MCP server.
+   * We apply a massive SDK-level timeout (e.g. 10 hours) because we want to handle
+   * timeouts in the interceptor via Promise.race, and we DO NOT want to send
+   * protocol-level cancellation requests to the target server if the agent gives up.
+   * This allows long-running builds (like mobile app compiling) to finish in the background.
    */
-  async callTool(name, args = {}) {
+  async callTool(name, args = {}, _timeoutMs) {
     this._assertConnected();
-    const result = await this.client.callTool({ name, arguments: args });
+    const requestOptions = { timeout: 36e5 * 10 };
+    const result = await this.client.callTool(
+      { name, arguments: args },
+      void 0,
+      requestOptions
+    );
     this.recordResponse();
     return result;
   }
@@ -511,217 +568,6 @@ var TargetManager = class _TargetManager extends EventEmitter {
   }
 };
 
-// src/proxy.ts
-async function startProxy(targetCommand, opts) {
-  const [command, ...args] = targetCommand;
-  const target = new TargetManager(command, args);
-  const interceptor = new ResponseInterceptor({
-    outDir: opts.outDir,
-    defaultTimeoutMs: opts.timeoutMs,
-    maxTextLength: opts.maxTextLength
-  });
-  target.on("stderr", (text) => {
-    process.stderr.write(`[target] ${text}
-`);
-  });
-  process.stderr.write("[proxy] Connecting to target MCP server...\n");
-  try {
-    await target.connect();
-  } catch (err) {
-    process.stderr.write(`[proxy] Failed to connect to target: ${err.message}
-`);
-    process.exit(1);
-  }
-  const status = target.getStatus();
-  process.stderr.write(`[proxy] Connected to target (PID: ${status.pid})
-`);
-  const targetCaps = target.getServerCapabilities() ?? {};
-  const proxyCaps = {};
-  proxyCaps.tools = targetCaps.tools ?? {};
-  if (targetCaps.resources) proxyCaps.resources = targetCaps.resources;
-  if (targetCaps.prompts) proxyCaps.prompts = targetCaps.prompts;
-  if (targetCaps.logging) proxyCaps.logging = targetCaps.logging;
-  if (targetCaps.completions) proxyCaps.completions = targetCaps.completions;
-  process.stderr.write(`[proxy] Mirroring capabilities: ${Object.keys(proxyCaps).join(", ")}
-`);
-  const instructions = target.getInstructions();
-  if (instructions) {
-    process.stderr.write(
-      `[proxy] Target instructions: ${instructions.slice(0, 200)}${instructions.length > 200 ? "..." : ""}
-`
-    );
-  }
-  const mcpServer = new McpServer(
-    {
-      name: "run-mcp-proxy",
-      version: "1.3.0"
-    },
-    { capabilities: proxyCaps }
-  );
-  const server = mcpServer.server;
-  server.setRequestHandler(ListToolsRequestSchema, async (request) => {
-    const result = await target.listTools(request.params);
-    return result;
-  });
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: toolArgs } = request.params;
-    try {
-      const result = await interceptor.callTool(
-        target,
-        name,
-        toolArgs ?? {}
-      );
-      return result;
-    } catch (err) {
-      return {
-        content: [{ type: "text", text: `Error: ${err.message}` }],
-        isError: true
-      };
-    }
-  });
-  if (targetCaps.resources) {
-    server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
-      return await target.listResources(request.params);
-    });
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async (request) => {
-      return await target.listResourceTemplates(request.params);
-    });
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      return await target.readResource(request.params);
-    });
-    if (targetCaps.resources.subscribe) {
-      server.setRequestHandler(SubscribeRequestSchema, async (request) => {
-        return await target.subscribeResource(request.params);
-      });
-      server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
-        return await target.unsubscribeResource(request.params);
-      });
-    }
-  }
-  if (targetCaps.prompts) {
-    server.setRequestHandler(ListPromptsRequestSchema, async (request) => {
-      return await target.listPrompts(request.params);
-    });
-    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      return await target.getPrompt(request.params);
-    });
-  }
-  if (targetCaps.logging) {
-    server.setRequestHandler(SetLevelRequestSchema, async (request) => {
-      return await target.setLoggingLevel(request.params.level);
-    });
-  }
-  if (targetCaps.completions) {
-    server.setRequestHandler(CompleteRequestSchema, async (request) => {
-      return await target.complete(request.params);
-    });
-  }
-  const rawClient = target.getRawClient();
-  if (rawClient) {
-    if (targetCaps.tools && targetCaps.tools.listChanged) {
-      rawClient.setNotificationHandler(ToolListChangedNotificationSchema, () => {
-        server.notification({ method: "notifications/tools/list_changed" });
-      });
-    }
-    if (targetCaps.resources && targetCaps.resources.listChanged) {
-      rawClient.setNotificationHandler(ResourceListChangedNotificationSchema, () => {
-        server.notification({ method: "notifications/resources/list_changed" });
-      });
-    }
-    if (targetCaps.prompts && targetCaps.prompts.listChanged) {
-      rawClient.setNotificationHandler(PromptListChangedNotificationSchema, () => {
-        server.notification({ method: "notifications/prompts/list_changed" });
-      });
-    }
-    if (targetCaps.logging) {
-      rawClient.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
-        server.notification({
-          method: "notifications/message",
-          params: notification.params
-        });
-      });
-    }
-  }
-  const transport = new StdioServerTransport();
-  server.onclose = async () => {
-    process.stderr.write("[proxy] Parent disconnected, shutting down...\n");
-    await target.close();
-    process.exit(0);
-  };
-  await mcpServer.connect(transport);
-  process.stderr.write("[proxy] Proxy server running on stdio.\n");
-  target.on("disconnected", () => {
-    process.stderr.write("[proxy] Target server disconnected.\n");
-    process.exit(1);
-  });
-}
-
-// src/repl.ts
-import { readFile } from "fs/promises";
-import { createInterface } from "readline";
-import pc from "picocolors";
-
-// src/parsing.ts
-function parseCommandLine(input) {
-  const spaceIdx = input.indexOf(" ");
-  if (spaceIdx === -1) {
-    return { cmd: input.toLowerCase(), rest: "" };
-  }
-  return {
-    cmd: input.slice(0, spaceIdx).toLowerCase(),
-    rest: input.slice(spaceIdx + 1)
-  };
-}
-function parseCallArgs(rest) {
-  const trimmed = rest.trim();
-  if (!trimmed) return { toolName: "", jsonArgs: "" };
-  const spaceIdx = trimmed.indexOf(" ");
-  if (spaceIdx === -1) {
-    return { toolName: trimmed, jsonArgs: "" };
-  }
-  const toolName = trimmed.slice(0, spaceIdx);
-  let remainder = trimmed.slice(spaceIdx + 1).trim();
-  let timeoutMs;
-  const timeoutMatch = remainder.match(/\s--timeout\s+(\d+)\s*$/);
-  if (timeoutMatch) {
-    timeoutMs = parseInt(timeoutMatch[1], 10);
-    remainder = remainder.slice(0, timeoutMatch.index).trim();
-  }
-  return { toolName, jsonArgs: remainder, timeoutMs };
-}
-function formatJson(obj, indent = 2) {
-  const json = JSON.stringify(obj, null, indent);
-  return json.split("\n").map((line) => " ".repeat(indent) + line).join("\n");
-}
-function levenshtein(a, b) {
-  const m = a.length;
-  const n = b.length;
-  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
-  for (let i = 0; i <= m; i++) dp[i][0] = i;
-  for (let j = 0; j <= n; j++) dp[0][j] = j;
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-    }
-  }
-  return dp[m][n];
-}
-function suggestCommand(input, commands, threshold = 0.4) {
-  let best = null;
-  let bestDist = Infinity;
-  for (const cmd of commands) {
-    const dist = levenshtein(input, cmd);
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = cmd;
-    }
-  }
-  if (best && bestDist <= Math.ceil(input.length * threshold)) {
-    return best;
-  }
-  return null;
-}
-
 // src/repl.ts
 var KNOWN_COMMANDS = [
   "tools/list",
@@ -989,8 +835,8 @@ async function readScriptLines(filepath) {
 }
 
 // src/server.ts
-import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 async function startServer(opts) {
   let target = null;
@@ -999,8 +845,8 @@ async function startServer(opts) {
     defaultTimeoutMs: opts.timeoutMs,
     maxTextLength: opts.maxTextLength
   });
-  const mcpServer = new McpServer2(
-    { name: "run-mcp", version: "1.3.0" },
+  const mcpServer = new McpServer(
+    { name: "run-mcp", version: "1.3.1" },
     {
       capabilities: {
         tools: {}
@@ -1174,6 +1020,54 @@ Check that the command is correct and the server starts without errors. You can
       }
     }
   );
+  mcpServer.registerTool(
+    "describe_mcp_tool",
+    {
+      title: "Describe MCP Tool",
+      description: "Get the description and input schema for a specific tool on the connected server.",
+      inputSchema: {
+        name: z.string().describe("Name of the tool to describe")
+      }
+    },
+    async ({ name }) => {
+      if (!target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await target.listTools();
+        const tool = result.tools.find((t) => t.name === name);
+        if (!tool) {
+          const available = result.tools.map((t) => t.name).join(", ");
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Tool "${name}" not found.
+Available tools: ${available}`
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(tool, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error describing tool: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
   mcpServer.registerTool(
     "call_mcp_tool",
     {
@@ -1378,7 +1272,7 @@ Check that the command is correct and the server starts without errors. You can
       };
     }
   );
-  const transport = new StdioServerTransport2();
+  const transport = new StdioServerTransport();
   mcpServer.server.onclose = async () => {
     if (target) {
       await target.close();
@@ -1391,96 +1285,60 @@ Check that the command is correct and the server starts without errors. You can
 }
 
 // src/index.ts
-program.name("run-mcp").enablePositionalOptions().description(
-  "A smart proxy, interactive REPL, and live test harness for MCP servers.\n\nOperates in three modes:\n  repl    - Human-friendly CLI for testing MCP servers interactively\n  proxy   - Transparent MCP proxy that intercepts images, enforces timeouts,\n            and truncates large payloads to protect an AI agent's context window\n  server  - MCP server that lets AI agents dynamically test local MCP servers"
-).version("1.3.0").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               # Interactive testing (human)
-  $ run-mcp repl node my-server.js -s test.txt    # Run a script
-  $ run-mcp proxy node my-server.js               # Transparent proxy (agent)
-  $ run-mcp server                                # Test harness (agent)
-  $ run-mcp repl npx -y some-mcp-server           # Test an npx server
+  $ 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 '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(
-  "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
-
-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("proxy").description("Start as a transparent MCP proxy between an AI agent and a target server").passThroughOptions().allowUnknownOption().argument("<target_command...>", "Command to spawn the target MCP server").option("-o, --out-dir <path>", "Directory to save intercepted images and audio").option("-t, --timeout <ms>", "Default tool call timeout in milliseconds (default: 60000)").option("--max-text <chars>", "Max text response length before truncation (default: 50000)").addHelpText(
-  "after",
-  `
-Examples:
-  $ run-mcp proxy node my-server.js
-  $ run-mcp proxy node my-server.js --out-dir ./images
-  $ run-mcp proxy node my-server.js --timeout 120000
-  $ run-mcp proxy node my-server.js --max-text 100000
-
-Use this in your MCP client configuration to wrap any MCP server:
-  {
-    "mcpServers": {
-      "my-server": {
-        "command": "run-mcp",
-        "args": ["proxy", "node", "my-server.js"]
-      }
-    }
-  }`
-).action(
-  async (targetCommand, opts) => {
-    await startProxy(targetCommand, {
-      outDir: opts.outDir,
-      timeoutMs: opts.timeout ? Number.parseInt(opts.timeout, 10) : void 0,
-      maxTextLength: opts.maxText ? Number.parseInt(opts.maxText, 10) : void 0
-    });
-  }
-);
-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: 60000)").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.0",
+  "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": {