run-mcp 1.1.0 → 1.2.0

package/README.md

@@ -93,7 +93,9 @@ 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)
 ```
 
 ## REPL Commands
@@ -161,14 +163,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 +220,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");
   }
 };
 
@@ -157,7 +197,7 @@ var TargetManager = class _TargetManager extends EventEmitter {
         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.2.0" }, { capabilities: {} });
     this.client.onclose = () => {
       this._connected = false;
       this._clearStableTimer();
@@ -187,12 +227,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 +262,104 @@ 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 current connection status, PID, uptime, and diagnostics.
    */
@@ -345,7 +500,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 +520,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.2.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 +556,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 +564,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");
@@ -744,7 +976,7 @@ async function readScriptLines(filepath) {
 // 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(
+).version("1.2.0").addHelpText(
   "after",
   `
 Examples:
@@ -776,12 +1008,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 +1026,13 @@ 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.parse();

package/package.json

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