run-mcp 1.0.0 → 1.2.0

package/README.md

@@ -1 +1,246 @@
-# run-mcp
+# run-mcp
+
+A smart proxy and interactive REPL for [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers.
+
+`run-mcp` wraps any MCP server and operates in two modes:
+
+| Mode | Audience | Purpose |
+|------|----------|---------|
+| **`repl`** | Humans / developers | Interactive CLI for testing and exploring MCP servers with shorthand commands |
+| **`proxy`** | AI agents | Transparent MCP proxy that intercepts responses to save images to disk, enforce timeouts, and truncate massive payloads |
+
+## Why?
+
+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:
+
+- **Saving images to disk** instead of passing multi-MB base64 strings through
+- **Enforcing timeouts** so a hung tool call doesn't block forever
+- **Truncating huge text** responses to protect context budgets
+
+For humans, the REPL mode provides a quick way to test any MCP server without writing client code.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+To install globally (makes `run-mcp` available system-wide):
+
+```bash
+npm install -g .
+```
+
+## Quick Start
+
+### REPL Mode — Test an MCP server interactively
+
+```bash
+# Start a REPL session with any MCP server
+run-mcp repl node path/to/my-mcp-server.js
+
+# Or use npx without installing globally
+npx . repl node path/to/my-mcp-server.js
+```
+
+You'll see an interactive prompt:
+
+```
+⟳ Connecting to target MCP server...
+  Command: node path/to/my-mcp-server.js
+✓ Connected (PID: 12345)
+  5 tool(s) available. Type help for commands.
+
+>
+```
+
+### 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
+
+```
+run-mcp <command> [options]
+
+Commands:
+  repl <target_command...>    Start an interactive REPL session
+  proxy <target_command...>   Start as a transparent MCP proxy
+
+Options:
+  -V, --version               Show version number
+  -h, --help                  Show help
+```
+
+### REPL Command
+
+```
+run-mcp repl <target_command...> [options]
+
+Options:
+  -s, --script <file>    Read commands from a file instead of stdin
+  -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)
+```
+
+## REPL Commands
+
+Once in the REPL, these commands are available:
+
+| Command | Description |
+|---------|-------------|
+| `tools/list` | List all tools exposed by the target server |
+| `tools/describe <name>` | Show a tool's full input schema |
+| `tools/call <name> <json> [--timeout <ms>]` | Call a tool with JSON arguments |
+| `status` | Show target server status (PID, uptime, connection) |
+| `help` | Show available commands |
+| `exit` / `quit` | Disconnect and exit |
+
+### Examples
+
+```bash
+# List available tools
+> tools/list
+
+# Inspect a tool's schema
+> tools/describe screenshot
+
+# Call a tool with arguments
+> tools/call screenshot {"target": "#loginBtn"}
+
+# Call with a custom timeout (5 seconds)
+> tools/call long_running_tool {} --timeout 5000
+
+# Arguments with spaces work fine
+> tools/call send_message {"text": "hello world", "channel": "general"}
+```
+
+### Script Mode
+
+You can automate REPL commands by writing them to a file:
+
+```bash
+# commands.txt
+tools/list
+tools/call get_status {}
+tools/call screenshot {"save_path": "/tmp/test.png"}
+```
+
+```bash
+run-mcp repl node my-server.js --script commands.txt
+```
+
+- Lines starting with `#` are treated as comments
+- Exits with code `0` on success, `1` on first error
+
+## Proxy Mode — How It Works
+
+In proxy mode, `run-mcp` acts as an MCP server itself. Configure it as the command your AI agent spawns:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "run-mcp",
+      "args": ["proxy", "node", "path/to/actual-server.js", "--out-dir", "./images"]
+    }
+  }
+}
+```
+
+### 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. 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 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
+
+```
+┌─────────────────────┐         ┌─────────────────────┐
+│                     │  stdio  │                     │
+│   AI Agent / REPL   │◄───────►│     run-mcp         │
+│                     │         │                     │
+└─────────────────────┘         │  ┌───────────────┐  │
+                                │  │  Interceptor   │  │
+                                │  │  • Timeouts    │  │
+                                │  │  • Image Save  │  │
+                                │  │  • Truncation  │  │
+                                │  └───────┬───────┘  │
+                                │          │          │
+                                │  ┌───────▼───────┐  │
+                                │  │ TargetManager  │  │
+                                │  │ (MCP Client)   │  │
+                                │  └───────┬───────┘  │
+                                └──────────┼──────────┘
+                                           │ stdio
+                                ┌──────────▼──────────┐
+                                │  Target MCP Server   │
+                                │  (child process)     │
+                                └─────────────────────┘
+```
+
+### Modules
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| **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 transparently forwards all MCP primitives to the target, with tool responses running through the interceptor |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build (one-time)
+npm run build
+
+# Watch mode (rebuild on changes)
+npm run dev
+
+# Run directly
+node dist/index.js repl <target_command...>
+```
+
+## License
+
+ISC

package/dist/index.js

@@ -0,0 +1,1038 @@
+#!/usr/bin/env node
+
+// 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/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_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, 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;
+    const result = await Promise.race([target.callTool(name, args), this._timeout(timeout, name)]);
+    const content = result.content;
+    if (Array.isArray(content)) {
+      for (let i = 0; i < content.length; i++) {
+        content[i] = await this._processItem(content[i]);
+      }
+    }
+    return result;
+  }
+  /**
+   * 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._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._saveMedia(item.text.trim(), "image/png", "image");
+    }
+    if (item.type === "text" && item.text && item.text.length > this.maxTextLength) {
+      const totalLength = item.text.length;
+      return {
+        ...item,
+        text: item.text.slice(0, this.maxTextLength) + `
+... (truncated, ${totalLength.toLocaleString()} chars total)`
+      };
+    }
+    return item;
+  }
+  /**
+   * Decode base64, write to disk, return a text item with the file path.
+   * Works for both images and audio.
+   */
+  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 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: `[${label} saved to ${filepath} (${sizeKB}KB)]`
+    };
+  }
+  /**
+   * Returns a promise that rejects after the given timeout.
+   */
+  _timeout(ms, toolName) {
+    return new Promise((_, reject) => {
+      setTimeout(() => {
+        const humanMs = ms >= 1e3 ? `${(ms / 1e3).toFixed(1)}s` : `${ms}ms`;
+        reject(
+          new Error(
+            `Tool "${toolName}" timed out after ${ms}ms (${humanMs}). Use --timeout <ms> to increase the limit.`
+          )
+        );
+      }, ms);
+    });
+  }
+  /**
+   * 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",
+      // 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] ?? (mimeType.startsWith("audio/") ? ".wav" : ".png");
+  }
+};
+
+// src/target-manager.ts
+import { EventEmitter } from "events";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+var MIN_UPTIME_FOR_RESTART_MS = 5e3;
+var MAX_RECONNECT_ATTEMPTS = 3;
+var STABLE_CONNECTION_RESET_MS = 6e4;
+var TargetManager = class _TargetManager extends EventEmitter {
+  constructor(command, args) {
+    super();
+    this.command = command;
+    this.args = args;
+  }
+  client = null;
+  transport = null;
+  startTime = 0;
+  childPid = null;
+  _connected = false;
+  // Enhanced status tracking
+  _lastResponseTime = null;
+  _stderrLineCount = 0;
+  // Auto-reconnect state
+  _reconnectAttempts = 0;
+  _stableTimer = null;
+  _autoReconnect = false;
+  _reconnecting = false;
+  _intentionalClose = false;
+  /**
+   * Enable auto-reconnect behavior.
+   * Only applies to interactive REPL mode — proxy mode manages its own lifecycle.
+   */
+  enableAutoReconnect() {
+    this._autoReconnect = true;
+  }
+  /**
+   * Spawn the target MCP server and establish the MCP client connection.
+   * Stderr from the child process is emitted as 'stderr' events.
+   */
+  async connect() {
+    this.transport = new StdioClientTransport({
+      command: this.command,
+      args: this.args,
+      stderr: "pipe"
+    });
+    this.transport.stderr?.on("data", (chunk) => {
+      const text = chunk.toString().trimEnd();
+      if (text) {
+        this._stderrLineCount += text.split("\n").length;
+        this.emit("stderr", text);
+      }
+    });
+    this.client = new Client({ name: "run-mcp", version: "1.2.0" }, { capabilities: {} });
+    this.client.onclose = () => {
+      this._connected = false;
+      this._clearStableTimer();
+      if (this._intentionalClose) {
+        return;
+      }
+      this.emit("disconnected");
+      this._maybeReconnect();
+    };
+    await this.client.connect(this.transport);
+    this._connected = true;
+    this.startTime = Date.now();
+    const proc = this.transport._process;
+    if (proc?.pid) {
+      this.childPid = proc.pid;
+    }
+    this.emit("connected");
+    this._registerCleanup();
+    this._startStableTimer();
+  }
+  get connected() {
+    return this._connected;
+  }
+  /**
+   * Record that a response was received (for status tracking).
+   */
+  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(params) {
+    this._assertConnected();
+    const result = await this.client.listTools(params);
+    this.recordResponse();
+    return result;
+  }
+  /**
+   * Call a tool on the target MCP server.
+   */
+  async callTool(name, args = {}) {
+    this._assertConnected();
+    const result = await this.client.callTool({ name, arguments: args });
+    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.
+   */
+  getStatus() {
+    return {
+      pid: this.childPid,
+      uptime: this._connected ? (Date.now() - this.startTime) / 1e3 : 0,
+      connected: this._connected,
+      command: this.command,
+      args: this.args,
+      lastResponseTime: this._lastResponseTime,
+      stderrLineCount: this._stderrLineCount,
+      reconnectAttempts: this._reconnectAttempts,
+      maxReconnectAttempts: MAX_RECONNECT_ATTEMPTS
+    };
+  }
+  /**
+   * Cleanly shut down the client connection and child process.
+   */
+  async close() {
+    this._intentionalClose = true;
+    this._clearStableTimer();
+    if (this.client) {
+      try {
+        await this.client.close();
+      } catch {
+      }
+      this.client = null;
+    }
+    if (this.transport) {
+      try {
+        await this.transport.close();
+      } catch {
+      }
+      this.transport = null;
+    }
+    this._connected = false;
+    this.childPid = null;
+  }
+  // ─── Auto-reconnect logic ──────────────────────────────────────────────────
+  /**
+   * Decide whether to attempt auto-reconnect after a disconnect.
+   *
+   * Rules:
+   *  1. Auto-reconnect must be enabled
+   *  2. Server must have been alive for ≥5s (otherwise it's a startup bug)
+   *  3. Must not exceed MAX_RECONNECT_ATTEMPTS consecutive retries
+   *  4. Must not already be reconnecting
+   */
+  async _maybeReconnect() {
+    if (!this._autoReconnect || this._reconnecting) return;
+    const uptimeMs = Date.now() - this.startTime;
+    if (uptimeMs < MIN_UPTIME_FOR_RESTART_MS) {
+      this.emit("reconnect_failed", {
+        reason: "startup_crash",
+        message: `Server crashed after ${(uptimeMs / 1e3).toFixed(1)}s \u2014 too soon to be a transient failure (min ${MIN_UPTIME_FOR_RESTART_MS / 1e3}s). Not retrying.`
+      });
+      return;
+    }
+    if (this._reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      this.emit("reconnect_failed", {
+        reason: "max_retries",
+        message: `Server has crashed ${this._reconnectAttempts} times in a row. Giving up.`
+      });
+      return;
+    }
+    this._reconnecting = true;
+    this._reconnectAttempts++;
+    this.emit("reconnecting", {
+      attempt: this._reconnectAttempts,
+      maxAttempts: MAX_RECONNECT_ATTEMPTS
+    });
+    this.client = null;
+    this.transport = null;
+    this.childPid = null;
+    try {
+      await this.connect();
+      this.emit("reconnected", { attempt: this._reconnectAttempts });
+    } catch (err) {
+      this.emit("reconnect_failed", {
+        reason: "connect_error",
+        message: `Reconnect attempt ${this._reconnectAttempts} failed: ${err.message}`
+      });
+    } finally {
+      this._reconnecting = false;
+    }
+  }
+  /**
+   * After STABLE_CONNECTION_RESET_MS of being connected, reset the retry counter.
+   * This way, a server that crashes once after 10 minutes of stability
+   * gets a fresh set of retries.
+   */
+  _startStableTimer() {
+    this._clearStableTimer();
+    this._stableTimer = setTimeout(() => {
+      if (this._connected) {
+        this._reconnectAttempts = 0;
+      }
+    }, STABLE_CONNECTION_RESET_MS);
+  }
+  _clearStableTimer() {
+    if (this._stableTimer) {
+      clearTimeout(this._stableTimer);
+      this._stableTimer = null;
+    }
+  }
+  // ─── Internal helpers ──────────────────────────────────────────────────────
+  _assertConnected() {
+    if (!this._connected || !this.client) {
+      throw new Error("Not connected to target MCP server");
+    }
+  }
+  static _cleanupRegistered = false;
+  static _instances = /* @__PURE__ */ new Set();
+  _registerCleanup() {
+    _TargetManager._instances.add(this);
+    if (_TargetManager._cleanupRegistered) return;
+    _TargetManager._cleanupRegistered = true;
+    const cleanupAll = () => {
+      for (const instance of _TargetManager._instances) {
+        instance.close().catch(() => {
+        });
+      }
+    };
+    process.on("exit", cleanupAll);
+    process.on("SIGINT", () => {
+      cleanupAll();
+      process.exit(130);
+    });
+    process.on("SIGTERM", () => {
+      cleanupAll();
+      process.exit(143);
+    });
+  }
+};
+
+// src/proxy.ts
+async function startProxy(targetCommand, opts) {
+  const [command, ...args] = targetCommand;
+  const target = new TargetManager(command, args);
+  const interceptor = new ResponseInterceptor({
+    outDir: opts.outDir,
+    defaultTimeoutMs: opts.timeoutMs,
+    maxTextLength: opts.maxTextLength
+  });
+  target.on("stderr", (text) => {
+    process.stderr.write(`[target] ${text}
+`);
+  });
+  process.stderr.write("[proxy] Connecting to target MCP server...\n");
+  try {
+    await target.connect();
+  } catch (err) {
+    process.stderr.write(`[proxy] Failed to connect to target: ${err.message}
+`);
+    process.exit(1);
+  }
+  const status = target.getStatus();
+  process.stderr.write(`[proxy] Connected to target (PID: ${status.pid})
+`);
+  const targetCaps = target.getServerCapabilities() ?? {};
+  const proxyCaps = {};
+  proxyCaps.tools = targetCaps.tools ?? {};
+  if (targetCaps.resources) proxyCaps.resources = targetCaps.resources;
+  if (targetCaps.prompts) proxyCaps.prompts = targetCaps.prompts;
+  if (targetCaps.logging) proxyCaps.logging = targetCaps.logging;
+  if (targetCaps.completions) proxyCaps.completions = targetCaps.completions;
+  process.stderr.write(`[proxy] Mirroring capabilities: ${Object.keys(proxyCaps).join(", ")}
+`);
+  const instructions = target.getInstructions();
+  if (instructions) {
+    process.stderr.write(
+      `[proxy] Target instructions: ${instructions.slice(0, 200)}${instructions.length > 200 ? "..." : ""}
+`
+    );
+  }
+  const mcpServer = new McpServer(
+    {
+      name: "run-mcp-proxy",
+      version: "1.2.0"
+    },
+    { capabilities: proxyCaps }
+  );
+  const server = mcpServer.server;
+  server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    const result = await target.listTools(request.params);
+    return result;
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: toolArgs } = request.params;
+    try {
+      const result = await interceptor.callTool(
+        target,
+        name,
+        toolArgs ?? {}
+      );
+      return result;
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  });
+  if (targetCaps.resources) {
+    server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
+      return await target.listResources(request.params);
+    });
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async (request) => {
+      return await target.listResourceTemplates(request.params);
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      return await target.readResource(request.params);
+    });
+    if (targetCaps.resources.subscribe) {
+      server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        return await target.subscribeResource(request.params);
+      });
+      server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        return await target.unsubscribeResource(request.params);
+      });
+    }
+  }
+  if (targetCaps.prompts) {
+    server.setRequestHandler(ListPromptsRequestSchema, async (request) => {
+      return await target.listPrompts(request.params);
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      return await target.getPrompt(request.params);
+    });
+  }
+  if (targetCaps.logging) {
+    server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+      return await target.setLoggingLevel(request.params.level);
+    });
+  }
+  if (targetCaps.completions) {
+    server.setRequestHandler(CompleteRequestSchema, async (request) => {
+      return await target.complete(request.params);
+    });
+  }
+  const rawClient = target.getRawClient();
+  if (rawClient) {
+    if (targetCaps.tools && targetCaps.tools.listChanged) {
+      rawClient.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+        server.notification({ method: "notifications/tools/list_changed" });
+      });
+    }
+    if (targetCaps.resources && targetCaps.resources.listChanged) {
+      rawClient.setNotificationHandler(ResourceListChangedNotificationSchema, () => {
+        server.notification({ method: "notifications/resources/list_changed" });
+      });
+    }
+    if (targetCaps.prompts && targetCaps.prompts.listChanged) {
+      rawClient.setNotificationHandler(PromptListChangedNotificationSchema, () => {
+        server.notification({ method: "notifications/prompts/list_changed" });
+      });
+    }
+    if (targetCaps.logging) {
+      rawClient.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+        server.notification({
+          method: "notifications/message",
+          params: notification.params
+        });
+      });
+    }
+  }
+  const transport = new StdioServerTransport();
+  server.onclose = async () => {
+    process.stderr.write("[proxy] Parent disconnected, shutting down...\n");
+    await target.close();
+    process.exit(0);
+  };
+  await mcpServer.connect(transport);
+  process.stderr.write("[proxy] Proxy server running on stdio.\n");
+  target.on("disconnected", () => {
+    process.stderr.write("[proxy] Target server disconnected.\n");
+    process.exit(1);
+  });
+}
+
+// src/repl.ts
+import { readFile } from "fs/promises";
+import { createInterface } from "readline";
+import pc from "picocolors";
+
+// src/parsing.ts
+function parseCommandLine(input) {
+  const spaceIdx = input.indexOf(" ");
+  if (spaceIdx === -1) {
+    return { cmd: input.toLowerCase(), rest: "" };
+  }
+  return {
+    cmd: input.slice(0, spaceIdx).toLowerCase(),
+    rest: input.slice(spaceIdx + 1)
+  };
+}
+function parseCallArgs(rest) {
+  const trimmed = rest.trim();
+  if (!trimmed) return { toolName: "", jsonArgs: "" };
+  const spaceIdx = trimmed.indexOf(" ");
+  if (spaceIdx === -1) {
+    return { toolName: trimmed, jsonArgs: "" };
+  }
+  const toolName = trimmed.slice(0, spaceIdx);
+  let remainder = trimmed.slice(spaceIdx + 1).trim();
+  let timeoutMs;
+  const timeoutMatch = remainder.match(/\s--timeout\s+(\d+)\s*$/);
+  if (timeoutMatch) {
+    timeoutMs = parseInt(timeoutMatch[1], 10);
+    remainder = remainder.slice(0, timeoutMatch.index).trim();
+  }
+  return { toolName, jsonArgs: remainder, timeoutMs };
+}
+function formatJson(obj, indent = 2) {
+  const json = JSON.stringify(obj, null, indent);
+  return json.split("\n").map((line) => " ".repeat(indent) + line).join("\n");
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+function suggestCommand(input, commands, threshold = 0.4) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of commands) {
+    const dist = levenshtein(input, cmd);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = cmd;
+    }
+  }
+  if (best && bestDist <= Math.ceil(input.length * threshold)) {
+    return best;
+  }
+  return null;
+}
+
+// src/repl.ts
+var KNOWN_COMMANDS = [
+  "tools/list",
+  "tools/describe",
+  "tools/call",
+  "status",
+  "help",
+  "exit",
+  "quit"
+];
+async function startRepl(targetCommand, opts) {
+  const [command, ...args] = targetCommand;
+  const target = new TargetManager(command, args);
+  const interceptor = new ResponseInterceptor({ outDir: opts.outDir });
+  target.on("stderr", (text) => {
+    for (const line of text.split("\n")) {
+      console.error(pc.dim(`[server] ${line}`));
+    }
+  });
+  console.log(pc.cyan("\u27F3 Connecting to target MCP server..."));
+  console.log(pc.dim(`  Command: ${targetCommand.join(" ")}`));
+  try {
+    await target.connect();
+  } catch (err) {
+    const msg = err.message ?? String(err);
+    if (msg.includes("ENOENT") || msg.includes("spawn")) {
+      console.error(pc.red(`\u2717 Failed to start server: command "${command}" not found.`));
+      console.error(pc.dim(`  Check that "${command}" is installed and in your PATH.`));
+    } else {
+      console.error(pc.red(`\u2717 Failed to connect: ${msg}`));
+      console.error(pc.dim(`  Check that the target command starts a valid MCP server on stdio.`));
+    }
+    process.exit(1);
+  }
+  const status = target.getStatus();
+  console.log(pc.green(`\u2713 Connected (PID: ${status.pid})`));
+  if (!opts.script) {
+    target.enableAutoReconnect();
+    target.on(
+      "reconnecting",
+      ({ attempt, maxAttempts }) => {
+        console.log(
+          pc.yellow(`
+\u27F3 Server disconnected. Reconnecting (${attempt}/${maxAttempts})...`)
+        );
+      }
+    );
+    target.on("reconnected", ({ attempt }) => {
+      const s = target.getStatus();
+      console.log(pc.green(`\u2713 Reconnected (PID: ${s.pid}, attempt ${attempt})`));
+    });
+    target.on("reconnect_failed", ({ reason, message }) => {
+      console.error(pc.red(`\u2717 ${message}`));
+      if (reason === "max_retries") {
+        console.log(
+          pc.dim("  Use 'exit' to quit or wait for the server to be fixed and restart manually.")
+        );
+      }
+    });
+  }
+  try {
+    const { tools } = await target.listTools();
+    console.log(
+      pc.cyan(`  ${tools.length} tool(s) available. Type ${pc.bold("help")} for commands.
+`)
+    );
+  } catch (err) {
+    console.log(pc.yellow(`  Warning: Could not list tools: ${err.message}
+`));
+  }
+  const isScript = !!opts.script;
+  if (isScript) {
+    const lines = await readScriptLines(opts.script);
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      try {
+        await handleCommand(trimmed, target, interceptor);
+      } catch (err) {
+        console.error(pc.red(`\u2717 Error: ${err.message}`));
+        console.log(pc.dim("\nShutting down..."));
+        await target.close();
+        process.exit(1);
+      }
+    }
+    console.log(pc.dim("\nShutting down..."));
+    await target.close();
+    process.exit(0);
+  } else {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: pc.cyan("> "),
+      terminal: true
+    });
+    rl.prompt();
+    let processing = false;
+    const queue = [];
+    const processQueue = async () => {
+      if (processing) return;
+      processing = true;
+      while (queue.length > 0) {
+        const trimmed = queue.shift();
+        try {
+          await handleCommand(trimmed, target, interceptor);
+        } catch (err) {
+          console.error(pc.red(`\u2717 Error: ${err.message}`));
+        }
+        rl.prompt();
+      }
+      processing = false;
+    };
+    rl.on("line", (line) => {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) {
+        rl.prompt();
+        return;
+      }
+      queue.push(trimmed);
+      processQueue();
+    });
+    rl.on("close", async () => {
+      console.log(pc.dim("\nShutting down..."));
+      await target.close();
+      process.exit(0);
+    });
+  }
+}
+async function handleCommand(input, target, interceptor) {
+  const { cmd, rest } = parseCommandLine(input);
+  switch (cmd) {
+    case "help":
+      printHelp();
+      return;
+    case "tools/list":
+      await cmdToolsList(target);
+      return;
+    case "tools/describe":
+      await cmdToolsDescribe(target, rest);
+      return;
+    case "tools/call":
+      await cmdToolsCall(target, interceptor, rest);
+      return;
+    case "status":
+      cmdStatus(target);
+      return;
+    case "exit":
+    case "quit":
+      process.emit("SIGINT", "SIGINT");
+      return;
+    default: {
+      const suggestion = suggestCommand(cmd, KNOWN_COMMANDS);
+      if (suggestion) {
+        console.log(pc.yellow(`Unknown command: ${cmd}. Did you mean ${pc.bold(suggestion)}?`));
+      } else {
+        console.log(pc.yellow(`Unknown command: ${cmd}. Type ${pc.bold("help")} for usage.`));
+      }
+    }
+  }
+}
+async function cmdToolsList(target) {
+  const { tools } = await target.listTools();
+  if (tools.length === 0) {
+    console.log(pc.dim("  No tools available."));
+    return;
+  }
+  const nameWidth = Math.max(8, ...tools.map((t) => t.name.length));
+  console.log(pc.bold(`  ${"Name".padEnd(nameWidth)}  Description`));
+  console.log(pc.dim(`  ${"\u2500".repeat(nameWidth)}  ${"\u2500".repeat(50)}`));
+  for (const tool of tools) {
+    const desc = tool.description ? tool.description.length > 60 ? `${tool.description.slice(0, 57)}...` : tool.description : pc.dim("(no description)");
+    console.log(`  ${pc.green(tool.name.padEnd(nameWidth))}  ${desc}`);
+  }
+  console.log(pc.dim(`
+  ${tools.length} tool(s) total.`));
+}
+async function cmdToolsDescribe(target, rest) {
+  const name = rest.trim();
+  if (!name) {
+    console.log(pc.yellow("Usage: tools/describe <tool_name>"));
+    return;
+  }
+  const { tools } = await target.listTools();
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) {
+    console.log(pc.red(`Tool "${name}" not found.`));
+    console.log(pc.dim(`Available: ${tools.map((t) => t.name).join(", ")}`));
+    return;
+  }
+  console.log(pc.bold(`
+  ${tool.name}`));
+  if (tool.description) {
+    console.log(pc.dim(`  ${tool.description}`));
+  }
+  console.log(pc.cyan("\n  Input Schema:"));
+  console.log(formatJson(tool.inputSchema, 4));
+}
+async function cmdToolsCall(target, interceptor, rest) {
+  const { toolName, jsonArgs, timeoutMs } = parseCallArgs(rest);
+  if (!toolName) {
+    console.log(pc.yellow("Usage: tools/call <tool_name> [json_args] [--timeout <ms>]"));
+    return;
+  }
+  let args = {};
+  if (jsonArgs) {
+    try {
+      args = JSON.parse(jsonArgs);
+    } catch (err) {
+      console.error(pc.red(`Invalid JSON: ${err.message}`));
+      console.log(pc.dim(`  Received: ${jsonArgs}`));
+      return;
+    }
+  }
+  console.log(pc.dim(`  Calling ${toolName}...`));
+  const startTime = Date.now();
+  const result = await interceptor.callTool(target, toolName, args, timeoutMs);
+  const elapsed = Date.now() - startTime;
+  const content = result.content;
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      if (item.type === "text") {
+        console.log(item.text);
+      } else {
+        console.log(formatJson(item, 2));
+      }
+    }
+  } else {
+    console.log(formatJson(result, 2));
+  }
+  console.log(pc.dim(`  (${elapsed}ms)`));
+}
+function cmdStatus(target) {
+  const s = target.getStatus();
+  const uptimeStr = s.uptime >= 60 ? `${Math.floor(s.uptime / 60)}m ${(s.uptime % 60).toFixed(0)}s` : `${s.uptime.toFixed(1)}s`;
+  const lastRespStr = s.lastResponseTime ? `${((Date.now() - s.lastResponseTime) / 1e3).toFixed(1)}s ago` : "never";
+  console.log(pc.bold("\n  Target Server Status"));
+  console.log(`  ${pc.dim("Connected:")}      ${s.connected ? pc.green("yes") : pc.red("no")}`);
+  console.log(`  ${pc.dim("PID:")}            ${s.pid ?? "N/A"}`);
+  console.log(`  ${pc.dim("Uptime:")}         ${uptimeStr}`);
+  console.log(`  ${pc.dim("Last response:")}  ${lastRespStr}`);
+  console.log(`  ${pc.dim("Stderr lines:")}   ${s.stderrLineCount.toLocaleString()}`);
+  console.log(`  ${pc.dim("Reconnects:")}     ${s.reconnectAttempts}/${s.maxReconnectAttempts}`);
+  console.log(`  ${pc.dim("Command:")}        ${s.command} ${s.args.join(" ")}`);
+  console.log();
+}
+function printHelp() {
+  console.log(`
+${pc.bold("Available Commands:")}
+
+  ${pc.green("tools/list")}                         List all available tools
+  ${pc.green("tools/describe")} <name>              Show a tool's input schema
+  ${pc.green("tools/call")} <name> <json> [opts]    Call a tool with JSON arguments
+    Options: ${pc.dim("--timeout <ms>")}            Override default timeout (60s)
+  ${pc.green("status")}                             Show target server status
+  ${pc.green("help")}                               Show this help
+  ${pc.green("exit")} / ${pc.green("quit")}                         Disconnect and exit
+
+${pc.dim("Lines starting with # are treated as comments.")}
+${pc.dim('JSON arguments can contain spaces: tools/call say {"message": "hello world"}')}
+`);
+}
+async function readScriptLines(filepath) {
+  const content = await readFile(filepath, "utf-8");
+  return content.split("\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(
+  "after",
+  `
+Examples:
+  $ run-mcp repl node my-server.js               # Interactive testing
+  $ 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 repl npx -y some-mcp-server           # Test an npx server
+
+Run 'run-mcp <command> --help' for detailed options.`
+);
+if (process.argv.length <= 2) {
+  program.outputHelp();
+  process.exit(0);
+}
+program.command("repl").description("Start an interactive REPL session with a target MCP server").passThroughOptions().allowUnknownOption().argument("<target_command...>", "Command to spawn the target MCP server").option("-s, --script <file>", "Read commands from a file instead of stdin").option("-o, --out-dir <path>", "Directory to save intercepted images").addHelpText(
+  "after",
+  `
+Examples:
+  $ run-mcp repl node my-server.js
+  $ run-mcp repl node my-server.js --script verify.txt
+  $ run-mcp repl node my-server.js --out-dir ./screenshots
+
+REPL Commands (once connected):
+  tools/list                          List all available tools
+  tools/describe <name>               Show a tool's input schema
+  tools/call <name> <json> [opts]     Call a tool with JSON arguments
+  status                              Show target server status
+  help                                Show all commands`
+).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.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "run-mcp",
-  "version": "1.0.0",
-  "description": "",
+  "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": {
     "url": "https://github.com/funkyfunc/run-mcp/issues"
@@ -12,9 +12,45 @@
   },
   "license": "ISC",
   "author": "",
-  "type": "commonjs",
-  "main": "index.js",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "proxy",
+    "repl",
+    "cli"
+  ],
+  "bin": {
+    "run-mcp": "dist/index.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "pretest": "tsup",
+    "test": "vitest run",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "commander": "^13.1.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@types/node": "^22.13.14",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.2"
   }
 }