run-mcp 1.2.0 → 1.3.2

package/README.md

@@ -1,17 +1,15 @@
 # run-mcp
 
-A smart proxy and interactive REPL for [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers.
+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 two 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 MCP proxy that intercepts responses to save images to disk, enforce timeouts, and truncate massive payloads |
+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.
 
-## Why?
+### Interception Rules (Server Mode & 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
@@ -55,14 +53,6 @@ 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
 
 ```
@@ -70,7 +60,7 @@ run-mcp <command> [options]
 
 Commands:
   repl <target_command...>    Start an interactive REPL session
-  proxy <target_command...>   Start as a transparent MCP proxy
+  server                      Start as an MCP server for agents
 
 Options:
   -V, --version               Show version number
@@ -87,10 +77,10 @@ Options:
   -o, --out-dir <path>   Directory to save intercepted images (default: $TMPDIR/run-mcp)
 ```
 
-### Proxy Command
+### Server Command
 
 ```
-run-mcp proxy <target_command...> [options]
+run-mcp server [options]
 
 Options:
   -o, --out-dir <path>     Directory to save intercepted images and audio (default: $TMPDIR/run-mcp)
@@ -98,6 +88,34 @@ Options:
       --max-text <chars>   Max text response length before truncation (default: 50000)
 ```
 
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "run-mcp": {
+      "command": "npx",
+      "args": ["-y", "run-mcp", "server"]
+    }
+  }
+}
+```
+
+Then use these tools from your agent:
+
+| Tool | Description |
+|------|-------------|
+| `connect_to_mcp` | Spawn and connect to a local MCP server |
+| `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 |
+| `get_mcp_server_stderr` | View target server stderr output |
+
 ## REPL Commands
 
 Once in the REPL, these commands are available:

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";
@@ -167,6 +215,8 @@ var TargetManager = class _TargetManager extends EventEmitter {
   // Enhanced status tracking
   _lastResponseTime = null;
   _stderrLineCount = 0;
+  _stderrLines = [];
+  static MAX_STDERR_LINES = 200;
   // Auto-reconnect state
   _reconnectAttempts = 0;
   _stableTimer = null;
@@ -193,11 +243,16 @@ var TargetManager = class _TargetManager extends EventEmitter {
     this.transport.stderr?.on("data", (chunk) => {
       const text = chunk.toString().trimEnd();
       if (text) {
-        this._stderrLineCount += text.split("\n").length;
+        const lines = text.split("\n");
+        this._stderrLineCount += lines.length;
+        this._stderrLines.push(...lines);
+        if (this._stderrLines.length > _TargetManager.MAX_STDERR_LINES) {
+          this._stderrLines = this._stderrLines.slice(-_TargetManager.MAX_STDERR_LINES);
+        }
         this.emit("stderr", text);
       }
     });
-    this.client = new Client({ name: "run-mcp", version: "1.2.0" }, { capabilities: {} });
+    this.client = new Client({ name: "run-mcp", version: "1.3.1" }, { capabilities: {} });
     this.client.onclose = () => {
       this._connected = false;
       this._clearStableTimer();
@@ -255,10 +310,15 @@ 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;
   }
@@ -360,6 +420,14 @@ var TargetManager = class _TargetManager extends EventEmitter {
     return this.client;
   }
   // ─── Status & lifecycle ─────────────────────────────────────────────────────
+  /**
+   * Returns the last N lines of stderr output from the target server.
+   * Useful for debugging crashes or unexpected behavior.
+   */
+  getStderrLines(count) {
+    if (!count || count >= this._stderrLines.length) return [...this._stderrLines];
+    return this._stderrLines.slice(-count);
+  }
   /**
    * Returns current connection status, PID, uptime, and diagnostics.
    */
@@ -496,217 +564,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.2.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",
@@ -973,16 +830,462 @@ async function readScriptLines(filepath) {
   return content.split("\n");
 }
 
+// src/server.ts
+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;
+  const interceptor = new ResponseInterceptor({
+    outDir: opts.outDir,
+    defaultTimeoutMs: opts.timeoutMs,
+    maxTextLength: opts.maxTextLength
+  });
+  const mcpServer = new McpServer(
+    { name: "run-mcp", version: "1.3.1" },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "connect_to_mcp",
+    {
+      title: "Connect to MCP Server",
+      description: "Spawn and connect to a local MCP server process. Use this to test an MCP server you're building. Only one connection at a time \u2014 call disconnect_from_mcp first if already connected.",
+      inputSchema: {
+        command: z.string().describe("Command to run (e.g. 'node', 'python', 'npx')"),
+        args: z.array(z.string()).optional().describe("Arguments to pass (e.g. ['src/index.js'] or ['-y', 'some-server'])"),
+        env: z.record(z.string()).optional().describe("Extra environment variables for the child process")
+      }
+    },
+    async ({ command, args, env }) => {
+      if (target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Already connected to a target server. Call disconnect_from_mcp first, then connect again."
+            }
+          ],
+          isError: true
+        };
+      }
+      if (target) {
+        await target.close();
+        target = null;
+      }
+      try {
+        if (env) {
+          for (const [key, value] of Object.entries(env)) {
+            process.env[key] = value;
+          }
+        }
+        target = new TargetManager(command, args ?? []);
+        await target.connect();
+        const status = target.getStatus();
+        const caps = target.getServerCapabilities() ?? {};
+        const capSummary = [];
+        if (caps.tools) capSummary.push("tools");
+        if (caps.resources) capSummary.push("resources");
+        if (caps.prompts) capSummary.push("prompts");
+        if (caps.logging) capSummary.push("logging");
+        let toolCount = 0;
+        try {
+          const tools = await target.listTools();
+          toolCount = tools.tools.length;
+        } catch {
+        }
+        const lines = [
+          `Connected to MCP server (PID: ${status.pid})`,
+          `Command: ${command} ${(args ?? []).join(" ")}`,
+          `Capabilities: ${capSummary.join(", ") || "none"}`,
+          `Tools available: ${toolCount}`,
+          "",
+          "Use list_mcp_tools, call_mcp_tool, list_mcp_resources, etc. to interact with it.",
+          "Use disconnect_from_mcp when done, or to reconnect after code changes."
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        target = null;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to connect: ${err.message}
+
+Check that the command is correct and the server starts without errors. You can also check get_mcp_server_stderr after a failed connect for more details.`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "disconnect_from_mcp",
+    {
+      title: "Disconnect from MCP Server",
+      description: "Tear down the current MCP server connection. Call this before reconnecting after code changes."
+    },
+    async () => {
+      if (!target) {
+        return {
+          content: [{ type: "text", text: "No target server is connected." }],
+          isError: true
+        };
+      }
+      const status = target.getStatus();
+      await target.close();
+      target = null;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Disconnected from MCP server (was PID: ${status.pid}, uptime: ${status.uptime.toFixed(1)}s).`
+          }
+        ]
+      };
+    }
+  );
+  mcpServer.registerTool(
+    "mcp_server_status",
+    {
+      title: "MCP Server Status",
+      description: "Check the current target server connection status, PID, uptime, and capabilities."
+    },
+    async () => {
+      if (!target) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp to connect to one."
+            }
+          ]
+        };
+      }
+      const status = target.getStatus();
+      const caps = target.getServerCapabilities() ?? {};
+      const lines = [
+        `Connected: ${status.connected}`,
+        `PID: ${status.pid}`,
+        `Uptime: ${status.uptime.toFixed(1)}s`,
+        `Command: ${status.command} ${status.args.join(" ")}`,
+        `Capabilities: ${Object.keys(caps).join(", ") || "none"}`,
+        `Stderr lines: ${status.stderrLineCount}`,
+        `Last response: ${status.lastResponseTime ? new Date(status.lastResponseTime).toISOString() : "none"}`
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  mcpServer.registerTool(
+    "list_mcp_tools",
+    {
+      title: "List MCP Tools",
+      description: "List all tools exposed by the connected MCP server, including descriptions, input schemas, and annotations."
+    },
+    async () => {
+      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();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result.tools, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error listing tools: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  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",
+    {
+      title: "Call MCP Tool",
+      description: "Call a tool on the connected MCP server. Responses go through the interceptor: images/audio are saved to disk, timeouts are enforced, and oversized text is truncated.",
+      inputSchema: {
+        name: z.string().describe("Name of the tool to call"),
+        arguments: z.record(z.unknown()).optional().describe("Arguments to pass to the tool (as a JSON object)"),
+        timeout_ms: z.number().optional().describe("Timeout for this specific call in milliseconds (overrides default)")
+      }
+    },
+    async ({ name, arguments: toolArgs, timeout_ms }) => {
+      if (!target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await interceptor.callTool(
+          target,
+          name,
+          toolArgs ?? {},
+          timeout_ms
+        );
+        return result;
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "list_mcp_resources",
+    {
+      title: "List MCP Resources",
+      description: "List all resources exposed by the connected MCP server."
+    },
+    async () => {
+      if (!target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await target.listResources();
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.resources, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error listing resources: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "read_mcp_resource",
+    {
+      title: "Read MCP Resource",
+      description: "Read a specific resource by URI from the connected MCP server.",
+      inputSchema: {
+        uri: z.string().describe("URI of the resource to read (e.g. 'docs://readme')")
+      }
+    },
+    async ({ uri }) => {
+      if (!target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await target.readResource({ uri });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.contents, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error reading resource: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "list_mcp_prompts",
+    {
+      title: "List MCP Prompts",
+      description: "List all prompts exposed by the connected MCP server."
+    },
+    async () => {
+      if (!target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await target.listPrompts();
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.prompts, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error listing prompts: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "get_mcp_prompt",
+    {
+      title: "Get MCP Prompt",
+      description: "Get a specific prompt by name from the connected MCP server.",
+      inputSchema: {
+        name: z.string().describe("Name of the prompt"),
+        arguments: z.record(z.string()).optional().describe("Arguments to pass to the prompt")
+      }
+    },
+    async ({ name, arguments: promptArgs }) => {
+      if (!target?.connected) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server connected. Use connect_to_mcp first."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await target.getPrompt({
+          name,
+          arguments: promptArgs ?? {}
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.messages, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error getting prompt: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  mcpServer.registerTool(
+    "get_mcp_server_stderr",
+    {
+      title: "Get MCP Server Stderr",
+      description: "Get recent stderr output from the target MCP server. Useful for debugging crashes, startup failures, or unexpected behavior.",
+      inputSchema: {
+        lines: z.number().optional().describe("Number of recent lines to return (default: all, max 200)")
+      }
+    },
+    async ({ lines }) => {
+      if (!target) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No target server (current or previous). Nothing to show."
+            }
+          ]
+        };
+      }
+      const stderrLines = target.getStderrLines(lines);
+      if (stderrLines.length === 0) {
+        return {
+          content: [{ type: "text", text: "No stderr output captured." }]
+        };
+      }
+      return {
+        content: [{ type: "text", text: stderrLines.join("\n") }]
+      };
+    }
+  );
+  const transport = new StdioServerTransport();
+  mcpServer.server.onclose = async () => {
+    if (target) {
+      await target.close();
+    }
+    process.exit(0);
+  };
+  await mcpServer.connect(transport);
+  process.stderr.write("[server] run-mcp test harness running on stdio.\n");
+  process.stderr.write("[server] Waiting for connect_to_mcp call...\n");
+}
+
 // src/index.ts
 program.name("run-mcp").enablePositionalOptions().description(
-  "A smart proxy and interactive REPL for Model Context Protocol (MCP) servers.\n\nOperates in two 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"
-).version("1.2.0").addHelpText(
+  "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
+  $ 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               # Proxy for AI agents
+  $ 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.`
@@ -1008,31 +1311,34 @@ REPL Commands (once connected):
 ).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(
+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 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
+  $ run-mcp server
+  $ run-mcp server --out-dir ./test-output
+  $ run-mcp server --timeout 120000
 
-Use this in your MCP client configuration to wrap any MCP server:
+Add to your MCP client configuration:
   {
     "mcpServers": {
-      "my-server": {
-        "command": "run-mcp",
-        "args": ["proxy", "node", "my-server.js"]
+      "run-mcp": {
+        "command": "npx",
+        "args": ["-y", "run-mcp", "server"]
       }
     }
-  }`
-).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
-    });
   }
-);
+
+Then use these tools from your agent:
+  connect_to_mcp      \u2192 Spawn and connect to a local MCP server
+  list_mcp_tools      \u2192 List tools on the connected server
+  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
+  });
+});
 program.parse();

package/package.json

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