run-mcp 1.3.0 → 1.3.2

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. **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
@@ -56,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
 
 ```
@@ -71,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
@@ -88,17 +77,6 @@ Options:
   -o, --out-dir <path>   Directory to save intercepted images (default: $TMPDIR/run-mcp)
 ```
 
-### 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
 
 ```

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,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;
   }
@@ -511,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.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 +831,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 +841,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 +1016,50 @@ 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 +1264,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();
@@ -1392,14 +1278,13 @@ 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(
+  "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 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
 
@@ -1426,34 +1311,7 @@ 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(
-  "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(
+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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-mcp",
-  "version": "1.3.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": {