run-mcp 1.1.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?
 
@@ -93,8 +94,49 @@ Options:
 run-mcp proxy <target_command...> [options]
 
 Options:
-  -o, --out-dir <path>   Directory to save intercepted images (default: $TMPDIR/run-mcp)
+  -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
+
 ```
+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
 
@@ -161,14 +203,32 @@ In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the comma
 }
 ```
 
+### What the proxy forwards
+
+The proxy dynamically mirrors the target server's capabilities. All MCP primitives that the target supports are forwarded transparently:
+
+| Primitive | Forwarded? |
+|-----------|------------|
+| **Tools** (`tools/list`, `tools/call`) | ✅ Always (with interception) |
+| **Resources** (`resources/list`, `resources/read`, `resources/templates/list`) | ✅ If target supports |
+| **Prompts** (`prompts/list`, `prompts/get`) | ✅ If target supports |
+| **Logging** (`logging/setLevel`) | ✅ If target supports |
+| **Completion** (`completion/complete`) | ✅ If target supports |
+| **Notifications** (list changes, logging) | ✅ Forwarded from target to agent |
+| **Tool annotations** (`readOnlyHint`, `destructiveHint`, etc.) | ✅ Preserved as-is |
+| **Pagination** (`nextCursor` / `cursor`) | ✅ Passed through |
+
 ### What the proxy intercepts
 
+Tool call responses are processed through the interceptor pipeline. All other primitives pass through untouched.
+
 | Feature | Behavior |
 |---------|----------|
-| **Image extraction** | `type: "image"` responses with base64 data are saved to disk. The response is replaced with `[Image saved to /path/to/img.png (24KB)]` |
+| **Image extraction** | `type: "image"` responses with base64 data are saved to disk. Replaced with `[Image saved to /path/to/img.png (24KB)]` |
+| **Audio extraction** | `type: "audio"` responses with base64 data are saved to disk. Replaced with `[Audio saved to /path/to/audio.wav (12KB)]` |
 | **Base64 detection** | Text responses that are entirely base64-encoded (1000+ chars) are also saved as images |
-| **Timeouts** | Tool calls are wrapped in a 60-second timeout (prevents hung calls from blocking the agent) |
-| **Truncation** | Text responses exceeding 50,000 characters are truncated with a `... (truncated, N chars total)` message |
+| **Timeouts** | Tool calls are wrapped in a configurable timeout (default 60s, use `--timeout` to change) |
+| **Truncation** | Text responses exceeding the limit (default 50K chars, use `--max-text` to change) are truncated |
 
 ## Architecture
 
@@ -200,10 +260,10 @@ In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the comma
 
 | Module | File | Responsibility |
 |--------|------|----------------|
-| **TargetManager** | `src/target-manager.ts` | Spawns the target MCP server, manages the MCP Client connection, captures stderr, tracks lifecycle |
-| **ResponseInterceptor** | `src/interceptor.ts` | Wraps tool calls with timeouts, extracts base64 images to disk, truncates oversized text |
+| **TargetManager** | `src/target-manager.ts` | Spawns the target MCP server, manages the MCP Client connection, forwards all MCP primitives (tools, resources, prompts, logging), captures stderr, tracks lifecycle |
+| **ResponseInterceptor** | `src/interceptor.ts` | Wraps tool calls with timeouts, extracts base64 images and audio to disk, truncates oversized text |
 | **REPLMode** | `src/repl.ts` | Interactive readline REPL with shorthand command parsing and script mode |
-| **ProxyMode** | `src/proxy.ts` | MCP Server that bridges `tools/list` and `tools/call` through the interceptor to the target |
+| **ProxyMode** | `src/proxy.ts` | MCP Server that transparently forwards all MCP primitives to the target, with tool responses running through the interceptor |
 
 ## Development
 

package/dist/index.js

@@ -6,7 +6,23 @@ 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, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import {
+  CallToolRequestSchema,
+  CompleteRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListToolsRequestSchema,
+  LoggingMessageNotificationSchema,
+  PromptListChangedNotificationSchema,
+  ReadResourceRequestSchema,
+  ResourceListChangedNotificationSchema,
+  SetLevelRequestSchema,
+  SubscribeRequestSchema,
+  ToolListChangedNotificationSchema,
+  UnsubscribeRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
 
 // src/interceptor.ts
 import { mkdir, writeFile } from "fs/promises";
@@ -14,17 +30,22 @@ import { tmpdir } from "os";
 import { join } from "path";
 var BASE64_PATTERN = /^[A-Za-z0-9+/]{1000,}={0,2}$/;
 var DEFAULT_TIMEOUT_MS = 6e4;
-var MAX_TEXT_LENGTH = 5e4;
+var DEFAULT_MAX_TEXT_LENGTH = 5e4;
 var ResponseInterceptor = class {
   outDir;
   defaultTimeoutMs;
+  maxTextLength;
   fileCounter = 0;
   constructor(opts = {}) {
     this.outDir = opts.outDir ?? join(tmpdir(), "run-mcp");
     this.defaultTimeoutMs = opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxTextLength = opts.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH;
   }
   /**
-   * Call a tool on the target, applying timeout, image extraction, and truncation.
+   * Call a tool on the target, applying timeout, media extraction, and truncation.
+   *
+   * Returns the full result object as-is (including structuredContent, isError, _meta)
+   * with only the content array items modified when interception is needed.
    */
   async callTool(target, name, args = {}, timeoutMs) {
     const timeout = timeoutMs ?? this.defaultTimeoutMs;
@@ -38,20 +59,25 @@ var ResponseInterceptor = class {
     return result;
   }
   /**
-   * Process a single content item — extract images, truncate text.
+   * Process a single content item — extract media, truncate text.
+   * Preserves all item properties not related to the intercepted data
+   * (e.g., annotations, _meta).
    */
   async _processItem(item) {
     if (item.type === "image" && item.data) {
-      return this._saveImage(item.data, item.mimeType ?? "image/png");
+      return this._saveMedia(item.data, item.mimeType ?? "image/png", "image");
+    }
+    if (item.type === "audio" && item.data) {
+      return this._saveMedia(item.data, item.mimeType ?? "audio/wav", "audio");
     }
     if (item.type === "text" && item.text && BASE64_PATTERN.test(item.text.trim())) {
-      return this._saveImage(item.text.trim(), "image/png");
+      return this._saveMedia(item.text.trim(), "image/png", "image");
     }
-    if (item.type === "text" && item.text && item.text.length > MAX_TEXT_LENGTH) {
+    if (item.type === "text" && item.text && item.text.length > this.maxTextLength) {
       const totalLength = item.text.length;
       return {
-        type: "text",
-        text: item.text.slice(0, MAX_TEXT_LENGTH) + `
+        ...item,
+        text: item.text.slice(0, this.maxTextLength) + `
 ... (truncated, ${totalLength.toLocaleString()} chars total)`
       };
     }
@@ -59,20 +85,23 @@ var ResponseInterceptor = class {
   }
   /**
    * Decode base64, write to disk, return a text item with the file path.
+   * Works for both images and audio.
    */
-  async _saveImage(base64Data, mimeType) {
+  async _saveMedia(base64Data, mimeType, mediaType) {
     await mkdir(this.outDir, { recursive: true });
     const ext = this._extensionFromMime(mimeType);
     const timestamp = Date.now();
     const counter = this.fileCounter++;
-    const filename = `img_${timestamp}_${counter}${ext}`;
+    const prefix = mediaType === "audio" ? "audio" : "img";
+    const filename = `${prefix}_${timestamp}_${counter}${ext}`;
     const filepath = join(this.outDir, filename);
     const buffer = Buffer.from(base64Data, "base64");
     await writeFile(filepath, buffer);
     const sizeKB = (buffer.length / 1024).toFixed(1);
+    const label = mediaType === "audio" ? "Audio" : "Image";
     return {
       type: "text",
-      text: `[Image saved to ${filepath} (${sizeKB}KB)]`
+      text: `[${label} saved to ${filepath} (${sizeKB}KB)]`
     };
   }
   /**
@@ -92,17 +121,28 @@ var ResponseInterceptor = class {
   }
   /**
    * Map MIME type to file extension.
+   * Covers image and audio types.
    */
   _extensionFromMime(mimeType) {
     const map = {
+      // Images
       "image/png": ".png",
       "image/jpeg": ".jpg",
       "image/gif": ".gif",
       "image/webp": ".webp",
       "image/svg+xml": ".svg",
-      "image/bmp": ".bmp"
+      "image/bmp": ".bmp",
+      // Audio
+      "audio/wav": ".wav",
+      "audio/mpeg": ".mp3",
+      "audio/mp3": ".mp3",
+      "audio/ogg": ".ogg",
+      "audio/flac": ".flac",
+      "audio/aac": ".aac",
+      "audio/webm": ".webm",
+      "audio/mp4": ".m4a"
     };
-    return map[mimeType] ?? ".png";
+    return map[mimeType] ?? (mimeType.startsWith("audio/") ? ".wav" : ".png");
   }
 };
 
@@ -127,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;
@@ -153,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.1.0" }, { capabilities: {} });
+    this.client = new Client({ name: "run-mcp", version: "1.3.0" }, { capabilities: {} });
     this.client.onclose = () => {
       this._connected = false;
       this._clearStableTimer();
@@ -187,12 +234,29 @@ var TargetManager = class _TargetManager extends EventEmitter {
   recordResponse() {
     this._lastResponseTime = Date.now();
   }
+  // ─── Server introspection ───────────────────────────────────────────────────
+  /**
+   * Returns the target server's advertised capabilities.
+   * Available after connect() completes.
+   */
+  getServerCapabilities() {
+    return this.client?.getServerCapabilities();
+  }
+  /**
+   * Returns the target server's instructions string (if any).
+   * Agents may use this for system prompts or behavioral hints.
+   */
+  getInstructions() {
+    return this.client?.getInstructions();
+  }
+  // ─── Tools ──────────────────────────────────────────────────────────────────
   /**
    * List all tools exposed by the target MCP server.
+   * Supports cursor-based pagination via params.
    */
-  async listTools() {
+  async listTools(params) {
     this._assertConnected();
-    const result = await this.client.listTools();
+    const result = await this.client.listTools(params);
     this.recordResponse();
     return result;
   }
@@ -205,6 +269,112 @@ var TargetManager = class _TargetManager extends EventEmitter {
     this.recordResponse();
     return result;
   }
+  // ─── Resources ──────────────────────────────────────────────────────────────
+  /**
+   * List resources exposed by the target MCP server.
+   * Supports cursor-based pagination.
+   */
+  async listResources(params) {
+    this._assertConnected();
+    const result = await this.client.listResources(params);
+    this.recordResponse();
+    return result;
+  }
+  /**
+   * List resource templates exposed by the target MCP server.
+   * Supports cursor-based pagination.
+   */
+  async listResourceTemplates(params) {
+    this._assertConnected();
+    const result = await this.client.listResourceTemplates(params);
+    this.recordResponse();
+    return result;
+  }
+  /**
+   * Read a specific resource by URI from the target MCP server.
+   */
+  async readResource(params) {
+    this._assertConnected();
+    const result = await this.client.readResource(params);
+    this.recordResponse();
+    return result;
+  }
+  /**
+   * Subscribe to resource updates on the target MCP server.
+   */
+  async subscribeResource(params) {
+    this._assertConnected();
+    const result = await this.client.subscribeResource(params);
+    this.recordResponse();
+    return result;
+  }
+  /**
+   * Unsubscribe from resource updates on the target MCP server.
+   */
+  async unsubscribeResource(params) {
+    this._assertConnected();
+    const result = await this.client.unsubscribeResource(params);
+    this.recordResponse();
+    return result;
+  }
+  // ─── Prompts ────────────────────────────────────────────────────────────────
+  /**
+   * List prompts exposed by the target MCP server.
+   * Supports cursor-based pagination.
+   */
+  async listPrompts(params) {
+    this._assertConnected();
+    const result = await this.client.listPrompts(params);
+    this.recordResponse();
+    return result;
+  }
+  /**
+   * Get a specific prompt by name from the target MCP server.
+   */
+  async getPrompt(params) {
+    this._assertConnected();
+    const result = await this.client.getPrompt(params);
+    this.recordResponse();
+    return result;
+  }
+  // ─── Logging ────────────────────────────────────────────────────────────────
+  /**
+   * Set the logging level on the target MCP server.
+   */
+  async setLoggingLevel(level) {
+    this._assertConnected();
+    const result = await this.client.setLoggingLevel(level);
+    this.recordResponse();
+    return result;
+  }
+  // ─── Completion ─────────────────────────────────────────────────────────────
+  /**
+   * Request completion from the target MCP server (for autocomplete UX).
+   */
+  async complete(params) {
+    this._assertConnected();
+    const result = await this.client.complete(params);
+    this.recordResponse();
+    return result;
+  }
+  // ─── Notification forwarding ────────────────────────────────────────────────
+  /**
+   * Access the underlying MCP client for advanced use cases like
+   * subscribing to notifications with proper SDK schemas.
+   * Prefer the typed methods above when possible.
+   */
+  getRawClient() {
+    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.
    */
@@ -345,7 +515,11 @@ var TargetManager = class _TargetManager extends EventEmitter {
 async function startProxy(targetCommand, opts) {
   const [command, ...args] = targetCommand;
   const target = new TargetManager(command, args);
-  const interceptor = new ResponseInterceptor({ outDir: opts.outDir });
+  const interceptor = new ResponseInterceptor({
+    outDir: opts.outDir,
+    defaultTimeoutMs: opts.timeoutMs,
+    maxTextLength: opts.maxTextLength
+  });
   target.on("stderr", (text) => {
     process.stderr.write(`[target] ${text}
 `);
@@ -361,17 +535,33 @@ async function startProxy(targetCommand, opts) {
   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.1.0"
+      version: "1.3.0"
     },
-    { capabilities: { tools: {} } }
+    { capabilities: proxyCaps }
   );
   const server = mcpServer.server;
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    const result = await target.listTools();
-    return { tools: result.tools };
+  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;
@@ -381,13 +571,7 @@ async function startProxy(targetCommand, opts) {
         name,
         toolArgs ?? {}
       );
-      const content = (result.content ?? []).map((item) => {
-        if (item.type === "image") {
-          return { type: "image", data: item.data, mimeType: item.mimeType };
-        }
-        return { type: "text", text: String(item.text ?? "") };
-      });
-      return { content };
+      return result;
     } catch (err) {
       return {
         content: [{ type: "text", text: `Error: ${err.message}` }],
@@ -395,6 +579,69 @@ async function startProxy(targetCommand, opts) {
       };
     }
   });
+  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");
@@ -741,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.1.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.`
@@ -776,12 +1426,14 @@ 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").addHelpText(
+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:
   {
@@ -792,7 +1444,43 @@ Use this in your MCP client configuration to wrap any MCP server:
       }
     }
   }`
-).action(async (targetCommand, opts) => {
-  await startProxy(targetCommand, opts);
+).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:
+  {
+    "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.1.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": {