run-mcp 1.2.0 → 1.3.0

package/README.md

@@ -1,13 +1,14 @@
 # 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` wraps any MCP server and operates in three 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 |
+| **`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 |
 
 ## Why?
 
@@ -98,6 +99,45 @@ Options:
       --max-text <chars>   Max text response length before truncation (default: 50000)
 ```
 
+### Server Command
+
+```
+run-mcp server [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)
+```
+
+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

@@ -167,6 +167,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 +195,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.0" }, { capabilities: {} });
     this.client.onclose = () => {
       this._connected = false;
       this._clearStableTimer();
@@ -360,6 +367,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.
    */
@@ -539,7 +554,7 @@ async function startProxy(targetCommand, opts) {
   const mcpServer = new McpServer(
     {
       name: "run-mcp-proxy",
-      version: "1.2.0"
+      version: "1.3.0"
     },
     { capabilities: proxyCaps }
   );
@@ -973,16 +988,419 @@ async function readScriptLines(filepath) {
   return content.split("\n");
 }
 
+// src/server.ts
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport as StdioServerTransport2 } 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 McpServer2(
+    { name: "run-mcp", version: "1.3.0" },
+    {
+      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(
+    "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 StdioServerTransport2();
+  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 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(
   "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 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 'run-mcp <command> --help' for detailed options.`
@@ -1035,4 +1453,34 @@ Use this in your MCP client configuration to wrap any MCP server:
     });
   }
 );
+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:
+  {
+    "mcpServers": {
+      "run-mcp": {
+        "command": "npx",
+        "args": ["-y", "run-mcp", "server"]
+      }
+    }
+  }
+
+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.0",
   "description": "A smart proxy and interactive REPL for Model Context Protocol (MCP) servers",
   "homepage": "https://github.com/funkyfunc/run-mcp#readme",
   "bugs": {