run-mcp 1.6.0 → 1.6.1

package/dist/index.js

@@ -2,6 +2,12 @@
 
 // src/index.ts
 import { program } from "commander";
+import { createConnection, createServer } from "net";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, readFile as readFile3, rm, writeFile as writeFile2 } from "fs/promises";
+import { join as join2, resolve } from "path";
+import { tmpdir as tmpdir2 } from "os";
+import { spawn } from "child_process";
 
 // src/config-scanner.ts
 import { existsSync } from "fs";
@@ -16,7 +22,6 @@ function getConfigPaths() {
   const isWin = process2.platform === "win32";
   const isMac = process2.platform === "darwin";
   const appData = process2.env.APPDATA || path.join(home, "AppData", "Roaming");
-  const localAppData = process2.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
   let claudeDesktopGlob;
   if (isWin) {
     claudeDesktopGlob = path.join(appData, "Claude", "claude_desktop_config.json");
@@ -145,11 +150,13 @@ var ResponseInterceptor = class {
   outDir;
   defaultTimeoutMs;
   maxTextLength;
+  mediaThresholdKb;
   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;
+    this.mediaThresholdKb = opts.mediaThresholdKb ?? 0;
   }
   /**
    * Call a tool on the target, applying timeout, media extraction, and truncation.
@@ -157,21 +164,101 @@ var ResponseInterceptor = class {
    * 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 { result } = await this._callToolInternal(target, name, args, timeoutMs);
+  async callTool(target, name, args = {}, timeoutMs, maxTextLength) {
+    const { result } = await this._callToolInternal(target, name, args, timeoutMs, maxTextLength);
     return result;
   }
   /**
    * Call a tool and return both the result and metadata about interception actions.
    * Used by the agent server when `include_metadata` is requested.
    */
-  async callToolWithMetadata(target, name, args = {}, timeoutMs) {
-    return this._callToolInternal(target, name, args, timeoutMs);
+  async callToolWithMetadata(target, name, args = {}, timeoutMs, maxTextLength) {
+    return this._callToolInternal(target, name, args, timeoutMs, maxTextLength);
+  }
+  /**
+   * Read a resource on the target, applying timeout, media extraction, and truncation.
+   */
+  async readResource(target, params, timeoutMs, maxTextLength) {
+    const timeout = timeoutMs ?? this.defaultTimeoutMs;
+    const metadata = {
+      truncated: false,
+      imagesSaved: 0,
+      audioSaved: 0,
+      originalSizeBytes: 0
+    };
+    const targetCall = target.readResource(params);
+    targetCall.catch(() => {
+    });
+    const result = await Promise.race([
+      targetCall,
+      this._timeout(timeout, `resource:${params.uri}`)
+    ]);
+    const contents = result.contents;
+    if (Array.isArray(contents)) {
+      for (const item of contents) {
+        if (item.text) {
+          metadata.originalSizeBytes += Buffer.byteLength(item.text, "utf8");
+        } else if (item.blob) {
+          metadata.originalSizeBytes += Buffer.byteLength(item.blob, "base64");
+        }
+      }
+      for (let i = 0; i < contents.length; i++) {
+        contents[i] = await this._processResourceItem(contents[i], metadata, maxTextLength);
+      }
+    }
+    return result;
+  }
+  /**
+   * Get a prompt on the target, applying timeout, media extraction, and truncation.
+   */
+  async getPrompt(target, params, timeoutMs, maxTextLength) {
+    const timeout = timeoutMs ?? this.defaultTimeoutMs;
+    const metadata = {
+      truncated: false,
+      imagesSaved: 0,
+      audioSaved: 0,
+      originalSizeBytes: 0
+    };
+    const targetCall = target.getPrompt(params);
+    targetCall.catch(() => {
+    });
+    const result = await Promise.race([
+      targetCall,
+      this._timeout(timeout, `prompt:${params.name}`)
+    ]);
+    const messages = result.messages;
+    if (Array.isArray(messages)) {
+      for (const msg of messages) {
+        const content = msg.content;
+        if (content) {
+          if (Array.isArray(content)) {
+            for (const item of content) {
+              if (item.type === "text" && item.text) {
+                metadata.originalSizeBytes += Buffer.byteLength(item.text, "utf8");
+              } else if ((item.type === "image" || item.type === "audio") && item.data) {
+                metadata.originalSizeBytes += Buffer.byteLength(item.data, "base64");
+              }
+            }
+            for (let i = 0; i < content.length; i++) {
+              content[i] = await this._processItem(content[i], metadata, maxTextLength);
+            }
+          } else if (typeof content === "object") {
+            if (content.type === "text" && content.text) {
+              metadata.originalSizeBytes += Buffer.byteLength(content.text, "utf8");
+            } else if ((content.type === "image" || content.type === "audio") && content.data) {
+              metadata.originalSizeBytes += Buffer.byteLength(content.data, "base64");
+            }
+            msg.content = await this._processItem(content, metadata, maxTextLength);
+          }
+        }
+      }
+    }
+    return result;
   }
   /**
    * Internal implementation shared by callTool and callToolWithMetadata.
    */
-  async _callToolInternal(target, name, args = {}, timeoutMs) {
+  async _callToolInternal(target, name, args = {}, timeoutMs, maxTextLength) {
     const timeout = timeoutMs ?? this.defaultTimeoutMs;
     const metadata = {
       truncated: false,
@@ -193,7 +280,7 @@ var ResponseInterceptor = class {
         }
       }
       for (let i = 0; i < content.length; i++) {
-        content[i] = await this._processItem(content[i], metadata);
+        content[i] = await this._processItem(content[i], metadata, maxTextLength);
       }
     }
     return { result, metadata };
@@ -203,25 +290,70 @@ var ResponseInterceptor = class {
    * Preserves all item properties not related to the intercepted data
    * (e.g., annotations, _meta).
    */
-  async _processItem(item, metadata) {
+  async _processItem(item, metadata, maxTextLength) {
     if (item.type === "image" && item.data) {
+      const sizeKB = Buffer.byteLength(item.data, "base64") / 1024;
+      if (this.mediaThresholdKb === -1 || this.mediaThresholdKb > 0 && sizeKB <= this.mediaThresholdKb) {
+        return item;
+      }
       metadata.imagesSaved++;
       return this._saveMedia(item.data, item.mimeType ?? "image/png", "image");
     }
     if (item.type === "audio" && item.data) {
+      const sizeKB = Buffer.byteLength(item.data, "base64") / 1024;
+      if (this.mediaThresholdKb === -1 || this.mediaThresholdKb > 0 && sizeKB <= this.mediaThresholdKb) {
+        return item;
+      }
       metadata.audioSaved++;
       return this._saveMedia(item.data, item.mimeType ?? "audio/wav", "audio");
     }
     if (item.type === "text" && item.text && BASE64_PATTERN.test(item.text.trim())) {
+      const sizeKB = Buffer.byteLength(item.text.trim(), "base64") / 1024;
+      if (this.mediaThresholdKb === -1 || this.mediaThresholdKb > 0 && sizeKB <= this.mediaThresholdKb) {
+        return item;
+      }
       metadata.imagesSaved++;
       return this._saveMedia(item.text.trim(), "image/png", "image");
     }
-    if (item.type === "text" && item.text && item.text.length > this.maxTextLength) {
+    const limit = maxTextLength ?? this.maxTextLength;
+    if (item.type === "text" && item.text && limit !== -1 && item.text.length > limit) {
+      const totalLength = item.text.length;
+      metadata.truncated = true;
+      return {
+        ...item,
+        text: item.text.slice(0, limit) + `
+... (truncated, ${totalLength.toLocaleString()} chars total)`
+      };
+    }
+    return item;
+  }
+  /**
+   * Process a single resource content item.
+   */
+  async _processResourceItem(item, metadata, maxTextLength) {
+    if (item.blob) {
+      const mime = item.mimeType ?? "image/png";
+      const isAudio = mime.startsWith("audio/");
+      const sizeKB = Buffer.byteLength(item.blob, "base64") / 1024;
+      if (this.mediaThresholdKb === -1 || this.mediaThresholdKb > 0 && sizeKB <= this.mediaThresholdKb) {
+        return item;
+      }
+      if (isAudio) metadata.audioSaved++;
+      else metadata.imagesSaved++;
+      const saved = await this._saveMedia(item.blob, mime, isAudio ? "audio" : "image");
+      return {
+        uri: item.uri,
+        mimeType: "text/plain",
+        text: saved.text
+      };
+    }
+    const limit = maxTextLength ?? this.maxTextLength;
+    if (item.text && limit !== -1 && item.text.length > limit) {
       const totalLength = item.text.length;
       metadata.truncated = true;
       return {
         ...item,
-        text: item.text.slice(0, this.maxTextLength) + `
+        text: item.text.slice(0, limit) + `
 ... (truncated, ${totalLength.toLocaleString()} chars total)`
       };
     }
@@ -251,13 +383,14 @@ var ResponseInterceptor = class {
   /**
    * Returns a promise that rejects after the given timeout.
    */
-  _timeout(ms, toolName) {
+  _timeout(ms, targetName) {
     return new Promise((_, reject) => {
       setTimeout(() => {
         const humanMs = ms >= 1e3 ? `${(ms / 1e3).toFixed(1)}s` : `${ms}ms`;
+        const typeLabel2 = targetName.includes(":") ? "Request" : "Tool";
         reject(
           new Error(
-            `Tool "${toolName}" timed out after ${ms}ms (${humanMs}). Use --timeout <ms> to increase the limit.`
+            `${typeLabel2} "${targetName}" timed out after ${ms}ms (${humanMs}). Use --timeout <ms> to increase the limit.`
           )
         );
       }, ms);
@@ -290,1070 +423,1202 @@ var ResponseInterceptor = class {
   }
 };
 
-// src/target-manager.ts
-import { EventEmitter } from "events";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import {
-  CreateMessageRequestSchema,
-  ElicitRequestSchema,
-  ListRootsRequestSchema,
-  LoggingMessageNotificationSchema,
-  PromptListChangedNotificationSchema,
-  ResourceListChangedNotificationSchema,
-  ResourceUpdatedNotificationSchema,
-  ToolListChangedNotificationSchema
-} from "@modelcontextprotocol/sdk/types.js";
-var MIN_UPTIME_FOR_RESTART_MS = 5e3;
-var MAX_RECONNECT_ATTEMPTS = 3;
-var STABLE_CONNECTION_RESET_MS = 6e4;
-var MAX_HISTORY = 100;
-var TargetManager = class _TargetManager extends EventEmitter {
-  constructor(command, args) {
-    super();
-    this.command = command;
-    this.args = args;
+// src/parsing.ts
+import pc from "picocolors";
+function parseCommandLine(input3) {
+  const spaceIdx = input3.indexOf(" ");
+  if (spaceIdx === -1) {
+    return { cmd: input3.toLowerCase(), rest: "" };
   }
-  client = null;
-  transport = null;
-  startTime = 0;
-  childPid = null;
-  _connected = false;
-  // Enhanced status tracking
-  _lastResponseTime = null;
-  _stderrLineCount = 0;
-  _stderrLines = [];
-  static MAX_STDERR_LINES = 200;
-  // Auto-reconnect state
-  _reconnectAttempts = 0;
-  _stableTimer = null;
-  _autoReconnect = false;
-  _reconnecting = false;
-  _intentionalClose = false;
-  // Request history
-  _history = [];
-  _historyIdCounter = 0;
-  // Notifications
-  _notifications = [];
-  static MAX_NOTIFICATIONS = 200;
-  // Roots
-  _roots = [];
-  /**
-   * Enable auto-reconnect behavior.
-   * Only applies to interactive REPL mode — proxy mode manages its own lifecycle.
-   */
-  enableAutoReconnect() {
-    this._autoReconnect = true;
+  return {
+    cmd: input3.slice(0, spaceIdx).toLowerCase(),
+    rest: input3.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: "" };
   }
-  /**
-   * Spawn the target MCP server and establish the MCP client connection.
-   * Stderr from the child process is emitted as 'stderr' events.
-   */
-  async connect() {
-    this._intentionalClose = false;
-    if (this.command.startsWith("http://") || this.command.startsWith("https://")) {
-      this.transport = new SSEClientTransport(new URL(this.command));
-    } else {
-      const stdioTransport = new StdioClientTransport({
-        command: this.command,
-        args: this.args,
-        stderr: "pipe"
-      });
-      stdioTransport.stderr?.on("data", (chunk) => {
-        const text = chunk.toString().trimEnd();
-        if (text) {
-          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.transport = stdioTransport;
-    }
-    this.client = new Client(
-      { name: "run-mcp", version: "1.6.0" },
-      {
-        capabilities: {
-          roots: { listChanged: true },
-          sampling: {},
-          elicitation: {}
-        }
-      }
-    );
-    this.client.setNotificationHandler(
-      LoggingMessageNotificationSchema,
-      async (notification) => {
-        const record = {
-          method: "notifications/message",
-          params: notification.params,
-          timestamp: Date.now()
-        };
-        this._pushNotification(record);
-        this.emit("notification", record);
-      }
-    );
-    this.client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
-      const record = {
-        method: "notifications/tools/list_changed",
-        timestamp: Date.now()
-      };
-      this._pushNotification(record);
-      this.emit("notification", record);
-    });
-    this.client.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
-      const record = {
-        method: "notifications/resources/list_changed",
-        timestamp: Date.now()
-      };
-      this._pushNotification(record);
-      this.emit("notification", record);
-    });
-    this.client.setNotificationHandler(
-      ResourceUpdatedNotificationSchema,
-      async (notification) => {
-        const record = {
-          method: "notifications/resources/updated",
-          params: notification.params,
-          timestamp: Date.now()
-        };
-        this._pushNotification(record);
-        this.emit("notification", record);
+  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, colorize = false) {
+  const json = JSON.stringify(obj, null, indent);
+  const output = colorize ? colorizeJson(json) : json;
+  return output.split("\n").map((line) => " ".repeat(indent) + line).join("\n");
+}
+function colorizeJson(json) {
+  const result = [];
+  let i = 0;
+  let expectingValue = false;
+  while (i < json.length) {
+    const ch = json[i];
+    if (ch === '"') {
+      const str = consumeString(json, i);
+      if (expectingValue) {
+        result.push(pc.green(str));
+        expectingValue = false;
+      } else {
+        result.push(pc.cyan(str));
       }
-    );
-    this.client.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
-      const record = {
-        method: "notifications/prompts/list_changed",
-        timestamp: Date.now()
-      };
-      this._pushNotification(record);
-      this.emit("notification", record);
-    });
-    this.client.setRequestHandler(CreateMessageRequestSchema, async (request) => {
-      return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new Error("Sampling request timed out (no response from user in 5 minutes)"));
-        }, 3e5);
-        this.emit("sampling_request", {
-          request: request.params,
-          respond: (result) => {
-            clearTimeout(timeout);
-            resolve(result);
-          },
-          reject: (err) => {
-            clearTimeout(timeout);
-            reject(err);
-          }
-        });
-      });
-    });
-    this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
-      return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new Error("Elicitation request timed out (no response from user in 5 minutes)"));
-        }, 3e5);
-        this.emit("elicitation_request", {
-          request: request.params,
-          respond: (result) => {
-            clearTimeout(timeout);
-            resolve(result);
-          },
-          reject: (err) => {
-            clearTimeout(timeout);
-            reject(err);
-          }
-        });
-      });
-    });
-    this.client.setRequestHandler(ListRootsRequestSchema, async () => {
-      return { roots: this._roots };
-    });
-    this.client.onclose = () => {
-      this._connected = false;
-      this._clearStableTimer();
-      if (this._intentionalClose) {
-        return;
+      i += str.length;
+      continue;
+    }
+    if (ch === ":") {
+      result.push(ch);
+      expectingValue = true;
+      i++;
+      continue;
+    }
+    if (ch === "," || ch === "}" || ch === "]") {
+      result.push(ch);
+      expectingValue = false;
+      i++;
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      result.push(ch);
+      if (ch === "[") expectingValue = true;
+      i++;
+      continue;
+    }
+    if (json.startsWith("true", i)) {
+      result.push(pc.magenta("true"));
+      expectingValue = false;
+      i += 4;
+      continue;
+    }
+    if (json.startsWith("false", i)) {
+      result.push(pc.magenta("false"));
+      expectingValue = false;
+      i += 5;
+      continue;
+    }
+    if (json.startsWith("null", i)) {
+      result.push(pc.dim("null"));
+      expectingValue = false;
+      i += 4;
+      continue;
+    }
+    if (ch === "-" || ch >= "0" && ch <= "9") {
+      let num = "";
+      while (i < json.length && /[0-9.eE+-]/.test(json[i])) {
+        num += json[i];
+        i++;
       }
-      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;
-    } else {
-      this.childPid = null;
+      result.push(pc.yellow(num));
+      expectingValue = false;
+      continue;
     }
-    this.emit("connected");
-    this._registerCleanup();
-    this._startStableTimer();
-  }
-  get connected() {
-    return this._connected;
+    result.push(ch);
+    i++;
   }
-  /**
-   * 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();
+  return result.join("");
+}
+function consumeString(json, start) {
+  let i = start + 1;
+  while (i < json.length) {
+    if (json[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (json[i] === '"') {
+      return json.slice(start, i + 1);
+    }
+    i++;
   }
-  /**
-   * Returns the target server's instructions string (if any).
-   * Agents may use this for system prompts or behavioral hints.
-   */
-  getInstructions() {
-    return this.client?.getInstructions();
+  return json.slice(start);
+}
+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]);
+    }
   }
-  /**
-   * Returns the target server's name and version from the MCP handshake.
-   * Available after connect() completes.
-   */
-  getServerVersion() {
-    return this.client?.getServerVersion();
+  return dp[m][n];
+}
+function suggestCommand(input3, commands, threshold = 0.4) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of commands) {
+    const dist = levenshtein(input3, cmd);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = cmd;
+    }
   }
-  // ─── Ping ──────────────────────────────────────────────────────────────────
-  /**
-   * Send a ping to the target MCP server and return the round-trip time.
-   */
-  async ping() {
-    this._assertConnected();
-    const start = Date.now();
-    await this.client.ping();
-    const elapsed = Date.now() - start;
-    this.recordResponse();
-    this._addHistory("ping", void 0, { ok: true }, elapsed);
-    return elapsed;
+  if (best && bestDist <= Math.ceil(input3.length * threshold)) {
+    return best;
   }
-  // ─── Tools ──────────────────────────────────────────────────────────────────
-  /**
-   * List all tools exposed by the target MCP server.
-   * Supports cursor-based pagination via params.
-   */
-  async listTools(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.listTools(params);
-    this.recordResponse();
-    this._addHistory("tools/list", params, result, Date.now() - start);
-    return result;
+  return null;
+}
+function scaffoldArgs(schema) {
+  return JSON.stringify(scaffoldObject(schema), null, 2);
+}
+function scaffoldValue(prop) {
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+    return prop.enum[0];
   }
-  /**
-   * Call a tool on the target MCP server.
-   * We apply a massive SDK-level timeout (e.g. 10 hours) because we want to handle
-   * timeouts in the interceptor via Promise.race, and we DO NOT want to send
-   * protocol-level cancellation requests to the target server if the agent gives up.
-   * This allows long-running builds (like mobile app compiling) to finish in the background.
-   */
-  async callTool(name, args = {}, _timeoutMs) {
-    this._assertConnected();
-    const requestOptions = { timeout: 36e5 * 10 };
-    const start = Date.now();
-    const result = await this.client.callTool(
-      { name, arguments: args },
-      void 0,
-      requestOptions
-    );
-    this.recordResponse();
-    this._addHistory(`tools/call ${name}`, args, result, Date.now() - start);
-    return result;
+  const variants = prop.anyOf ?? prop.oneOf;
+  if (Array.isArray(variants) && variants.length > 0) {
+    return scaffoldValue(variants[0]);
   }
-  // ─── Resources ──────────────────────────────────────────────────────────────
-  /**
-   * List resources exposed by the target MCP server.
-   * Supports cursor-based pagination.
-   */
-  async listResources(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.listResources(params);
-    this.recordResponse();
-    this._addHistory("resources/list", params, result, Date.now() - start);
-    return result;
+  switch (prop.type) {
+    case "string":
+      return "<string>";
+    case "number":
+    case "integer":
+      return "<number>";
+    case "boolean":
+      return "<boolean>";
+    case "array": {
+      const items = prop.items;
+      return items ? [scaffoldValue(items)] : ["<item>"];
+    }
+    case "object":
+      return scaffoldObject(prop);
+    default:
+      return `<${prop.type ?? "unknown"}>`;
   }
-  /**
-   * List resource templates exposed by the target MCP server.
-   * Supports cursor-based pagination.
-   */
-  async listResourceTemplates(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.listResourceTemplates(params);
-    this.recordResponse();
-    this._addHistory("resources/templates/list", params, result, Date.now() - start);
+}
+function scaffoldObject(schema) {
+  const properties = schema.properties;
+  if (properties) {
+    const result = {};
+    for (const [key, prop] of Object.entries(properties)) {
+      result[key] = scaffoldValue(prop);
+    }
     return result;
   }
-  /**
-   * Read a specific resource by URI from the target MCP server.
-   */
-  async readResource(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.readResource(params);
-    this.recordResponse();
-    this._addHistory(`resources/read ${params.uri}`, params, result, Date.now() - start);
-    return result;
+  const additionalProperties = schema.additionalProperties;
+  if (additionalProperties && typeof additionalProperties === "object") {
+    return { "<key>": scaffoldValue(additionalProperties) };
   }
-  /**
-   * Subscribe to resource updates on the target MCP server.
-   */
-  async subscribeResource(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.subscribeResource(params);
-    this.recordResponse();
-    this._addHistory(`resources/subscribe ${params.uri}`, params, result, Date.now() - start);
-    return result;
+  if (additionalProperties === true || schema.type === "object" && !properties) {
+    return { "<key>": "<value>" };
   }
-  /**
-   * Unsubscribe from resource updates on the target MCP server.
-   */
-  async unsubscribeResource(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.unsubscribeResource(params);
-    this.recordResponse();
-    this._addHistory(`resources/unsubscribe ${params.uri}`, params, result, Date.now() - start);
-    return result;
+  return {};
+}
+function formatToolDescription(tool) {
+  const lines = [];
+  lines.push(`  ${tool.name}`);
+  if (tool.description) {
+    lines.push(`  ${tool.description}`);
   }
-  // ─── Prompts ────────────────────────────────────────────────────────────────
-  /**
-   * List prompts exposed by the target MCP server.
-   * Supports cursor-based pagination.
-   */
-  async listPrompts(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.listPrompts(params);
-    this.recordResponse();
-    this._addHistory("prompts/list", params, result, Date.now() - start);
-    return result;
+  const schema = tool.inputSchema ?? {};
+  const properties = schema.properties;
+  const required = schema.required ?? [];
+  if (properties && Object.keys(properties).length > 0) {
+    lines.push("");
+    lines.push("  Arguments:");
+    const nameWidth = Math.max(6, ...Object.keys(properties).map((n) => n.length));
+    const typeWidth = Math.max(4, ...Object.values(properties).map((p) => typeLabel(p).length));
+    for (const [name, prop] of Object.entries(properties)) {
+      const type = typeLabel(prop);
+      const req = required.includes(name) ? "(required)" : "(optional)";
+      const desc = prop.description ?? "";
+      lines.push(
+        `    ${name.padEnd(nameWidth)}  ${type.padEnd(typeWidth)}  ${req.padEnd(10)}  ${desc}`
+      );
+    }
+  } else {
+    lines.push("");
+    lines.push("  No arguments required.");
   }
-  /**
-   * Get a specific prompt by name from the target MCP server.
-   */
-  async getPrompt(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.getPrompt(params);
-    this.recordResponse();
-    this._addHistory(`prompts/get ${params.name}`, params, result, Date.now() - start);
-    return result;
+  lines.push("");
+  lines.push("  Example:");
+  if (properties && Object.keys(properties).length > 0) {
+    const example = scaffoldObject(schema);
+    lines.push(`    tools/call ${tool.name} ${JSON.stringify(example)}`);
+  } else {
+    lines.push(`    tools/call ${tool.name}`);
   }
-  // ─── Logging ────────────────────────────────────────────────────────────────
-  /**
-   * Set the logging level on the target MCP server.
-   */
-  async setLoggingLevel(level) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.setLoggingLevel(level);
-    this.recordResponse();
-    this._addHistory(`logging/setLevel ${level}`, { level }, result, Date.now() - start);
-    return result;
+  if (tool.annotations) {
+    const entries = Object.entries(tool.annotations).filter(([key]) => key !== "title");
+    if (entries.length > 0) {
+      lines.push("");
+      lines.push("  Annotations:");
+      for (const [key, value] of entries) {
+        lines.push(`    ${key}: ${value}`);
+      }
+    }
   }
-  // ─── Completion ─────────────────────────────────────────────────────────────
-  /**
-   * Request completion from the target MCP server (for autocomplete UX).
-   */
-  async complete(params) {
-    this._assertConnected();
-    const start = Date.now();
-    const result = await this.client.complete(params);
-    this.recordResponse();
-    this._addHistory("completion/complete", params, result, Date.now() - start);
-    return result;
+  return lines.join("\n");
+}
+function typeLabel(prop) {
+  const type = prop.type;
+  if (!type) return "any";
+  if (type === "array") {
+    const items = prop.items;
+    return items ? `${typeLabel(items)}[]` : "array";
   }
-  // ─── Request History ────────────────────────────────────────────────────────
-  /**
-   * Get the request/response history.
-   * @param count - Number of recent records to return (default: all)
-   */
-  getHistory(count) {
-    if (!count || count >= this._history.length) return [...this._history];
-    return this._history.slice(-count);
+  return type;
+}
+function groupToolsByPrefix(toolNames) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const name of toolNames) {
+    const underscoreIdx = name.indexOf("_");
+    const prefix = underscoreIdx > 0 ? name.slice(0, underscoreIdx) : name;
+    const list = groups.get(prefix) ?? [];
+    list.push(name);
+    groups.set(prefix, list);
   }
-  /**
-   * Clear the history buffer.
-   */
-  clearHistory() {
-    this._history = [];
+  const meaningfulGroups = [...groups.entries()].filter(([, members]) => members.length >= 2);
+  if (meaningfulGroups.length < 2) {
+    const all = /* @__PURE__ */ new Map();
+    all.set("All", [...toolNames]);
+    return all;
   }
-  _addHistory(method, params, result, durationMs) {
-    const record = {
-      id: ++this._historyIdCounter,
-      method,
-      params,
-      result,
-      durationMs,
-      timestamp: Date.now()
-    };
-    this._history.push(record);
-    if (this._history.length > MAX_HISTORY) {
-      this._history = this._history.slice(-MAX_HISTORY);
+  const result = /* @__PURE__ */ new Map();
+  const other = [];
+  for (const [prefix, members] of groups) {
+    if (members.length >= 2) {
+      const label = prefix.charAt(0).toUpperCase() + prefix.slice(1);
+      result.set(label, members);
+    } else {
+      other.push(...members);
     }
   }
-  // ─── Notification History ───────────────────────────────────────────────────
-  /**
-   * Get recent server notifications.
-   * @param count - Number of recent notifications to return (default: all)
-   */
-  getNotifications(count) {
-    if (!count || count >= this._notifications.length) return [...this._notifications];
-    return this._notifications.slice(-count);
-  }
-  /**
-   * Clear the notification buffer.
-   */
-  clearNotifications() {
-    this._notifications = [];
+  if (other.length > 0) {
+    result.set("Other", other);
   }
-  _pushNotification(record) {
-    this._notifications.push(record);
-    if (this._notifications.length > _TargetManager.MAX_NOTIFICATIONS) {
-      this._notifications = this._notifications.slice(-_TargetManager.MAX_NOTIFICATIONS);
+  return result;
+}
+var LOG_LEVELS = [
+  "debug",
+  "info",
+  "notice",
+  "warning",
+  "error",
+  "critical",
+  "alert",
+  "emergency"
+];
+var ALIASES = {
+  tl: "tools/list",
+  td: "tools/describe",
+  tc: "tools/call",
+  ts: "tools/scaffold",
+  rl: "resources/list",
+  rr: "resources/read",
+  rt: "resources/templates",
+  rs: "resources/subscribe",
+  ru: "resources/unsubscribe",
+  pl: "prompts/list",
+  pg: "prompts/get"
+};
+function resolveAlias(input3) {
+  const spaceIdx = input3.indexOf(" ");
+  const token = spaceIdx === -1 ? input3 : input3.slice(0, spaceIdx);
+  const rest = spaceIdx === -1 ? "" : input3.slice(spaceIdx);
+  const expanded = ALIASES[token.toLowerCase()];
+  if (!expanded) return null;
+  return expanded + rest;
+}
+function splitArgs(input3) {
+  const tokens = [];
+  let current = "";
+  let inDoubleQuote = false;
+  let inSingleQuote = false;
+  let escape = false;
+  for (let i = 0; i < input3.length; i++) {
+    const ch = input3[i];
+    if (escape) {
+      current += ch;
+      escape = false;
+      continue;
     }
-  }
-  // ─── Roots Management ─────────────────────────────────────────────────────
-  /**
-   * Get the current roots list that this client advertises.
-   */
-  getRoots() {
-    return [...this._roots];
-  }
-  /**
-   * Add a root and send notification to the server.
-   */
-  async addRoot(root) {
-    if (this._roots.some((r) => r.uri === root.uri)) return;
-    this._roots.push(root);
-    await this._sendRootsChanged();
-  }
-  /**
-   * Remove a root by URI and send notification to the server.
-   */
-  async removeRoot(uri) {
-    const before = this._roots.length;
-    this._roots = this._roots.filter((r) => r.uri !== uri);
-    if (this._roots.length < before) {
-      await this._sendRootsChanged();
-      return true;
+    if (ch === "\\") {
+      escape = true;
+      continue;
     }
-    return false;
-  }
-  async _sendRootsChanged() {
-    if (!this._connected || !this.client) return;
-    try {
-      await this.client.sendRootsListChanged();
-    } catch {
+    if (ch === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      current += ch;
+      continue;
     }
+    if (ch === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      current += ch;
+      continue;
+    }
+    if (ch === " " && !inDoubleQuote && !inSingleQuote) {
+      if (current.trim()) {
+        tokens.push(current.trim());
+      }
+      current = "";
+      continue;
+    }
+    current += ch;
   }
-  // ─── 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.
-   */
-  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
-    };
+  if (current.trim()) {
+    tokens.push(current.trim());
   }
-  /**
-   * 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;
+  return tokens;
+}
+function parseHttpieArgs(argsString) {
+  const result = {};
+  const trimmedArgs = argsString.trim();
+  if (!trimmedArgs) return result;
+  const tokens = splitArgs(trimmedArgs);
+  for (const token of tokens) {
+    const eqIdx = token.indexOf("=");
+    if (eqIdx === -1) continue;
+    const isJson = eqIdx > 0 && token[eqIdx - 1] === ":";
+    const key = isJson ? token.slice(0, eqIdx - 1).trim() : token.slice(0, eqIdx).trim();
+    let rawVal = token.slice(eqIdx + 1).trim();
+    if (rawVal.startsWith('"') && rawVal.endsWith('"') || rawVal.startsWith("'") && rawVal.endsWith("'")) {
+      rawVal = rawVal.slice(1, -1);
     }
-    if (this.transport) {
+    if (isJson) {
       try {
-        await this.transport.close();
+        result[key] = JSON.parse(rawVal);
       } catch {
+        result[key] = rawVal;
       }
-      this.transport = null;
+    } else {
+      result[key] = rawVal;
     }
-    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;
+  return result;
+}
+function resolveJsonPath(obj, path2) {
+  const parts = path2.replace(/\["([^"]+)"\]/g, ".$1").replace(/\['([^']+)'\]/g, ".$1").replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  let current = obj;
+  for (const part of parts) {
+    if (current === void 0 || current === null) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function interpolateString(input3, context) {
+  const regex = /\$([a-zA-Z_][a-zA-Z0-9_]*|\[\d+\])?((?:\.[a-zA-Z0-9_]+|\[\d+\]|\["[^"]+"\]|\['[^']+'\])*)/g;
+  return input3.replace(regex, (match, root, path2) => {
+    let baseName = root;
+    let fullPath = path2 || "";
+    if (baseName && baseName.startsWith("[")) {
+      fullPath = baseName + fullPath;
+      baseName = "LAST";
     }
-    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;
+    if (!baseName) {
+      baseName = "LAST";
     }
-    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;
+    if (!(baseName in context)) {
+      return match;
+    }
+    const value = resolveJsonPath(context[baseName], fullPath);
+    if (value === void 0) {
+      return match;
     }
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  });
+}
+
+// src/target-manager.ts
+import { EventEmitter } from "events";
+import treeKill from "tree-kill";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import {
+  CreateMessageRequestSchema,
+  ElicitRequestSchema,
+  ListRootsRequestSchema,
+  LoggingMessageNotificationSchema,
+  PromptListChangedNotificationSchema,
+  ResourceListChangedNotificationSchema,
+  ResourceUpdatedNotificationSchema,
+  ToolListChangedNotificationSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var MIN_UPTIME_FOR_RESTART_MS = 5e3;
+var MAX_RECONNECT_ATTEMPTS = 3;
+var STABLE_CONNECTION_RESET_MS = 6e4;
+var MAX_HISTORY = 100;
+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;
+  _stderrLines = [];
+  static MAX_STDERR_LINES = 200;
+  // Auto-reconnect state
+  _reconnectAttempts = 0;
+  _stableTimer = null;
+  _autoReconnect = false;
+  _reconnecting = false;
+  _intentionalClose = false;
+  _everConnected = false;
+  // Request history
+  _history = [];
+  _historyIdCounter = 0;
+  // Notifications
+  _notifications = [];
+  static MAX_NOTIFICATIONS = 200;
+  // Roots
+  _roots = [];
   /**
-   * 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.
+   * Enable auto-reconnect behavior.
+   * Only applies to interactive REPL mode — proxy mode manages its own lifecycle.
    */
-  _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");
-    }
+  enableAutoReconnect() {
+    this._autoReconnect = true;
   }
-  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(() => {
+  /**
+   * Spawn the target MCP server and establish the MCP client connection.
+   * Stderr from the child process is emitted as 'stderr' events.
+   */
+  async connect() {
+    this._intentionalClose = false;
+    this._everConnected = false;
+    try {
+      if (this.command.startsWith("http://") || this.command.startsWith("https://")) {
+        this.transport = new SSEClientTransport(new URL(this.command));
+      } else {
+        const stdioTransport = new StdioClientTransport({
+          command: this.command,
+          args: this.args,
+          stderr: "pipe"
+        });
+        stdioTransport.stderr?.on("data", (chunk) => {
+          const text = chunk.toString().trimEnd();
+          if (text) {
+            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.transport = stdioTransport;
       }
-    };
-    process.on("exit", cleanupAll);
-    process.on("SIGINT", () => {
-      cleanupAll();
-      process.exit(130);
-    });
-    process.on("SIGTERM", () => {
-      cleanupAll();
-      process.exit(143);
-    });
-  }
-};
-
-// src/headless.ts
-var DEFAULT_HEADLESS_TIMEOUT_MS = 3e4;
-async function runHeadless(targetCommand, operation, opts = {}) {
-  const [command, ...args] = targetCommand;
-  const target = new TargetManager(command, args);
-  const interceptor = new ResponseInterceptor({
-    outDir: opts.outDir,
-    defaultTimeoutMs: opts.timeoutMs ?? DEFAULT_HEADLESS_TIMEOUT_MS
-  });
-  target.on("stderr", () => {
-  });
-  try {
-    process.stderr.write(`Connecting to ${targetCommand.join(" ")}...
-`);
-    await target.connect();
-    const status = target.getStatus();
-    process.stderr.write(`Connected (PID: ${status.pid})
-`);
-    const result = await executeOperation(target, interceptor, operation, opts);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
-    await target.close();
-    process.exit(0);
-  } catch (err) {
-    const msg = err.message ?? String(err);
-    if (msg.includes("ENOENT") || msg.includes("spawn")) {
-      process.stderr.write(
-        `Error: command "${command}" not found. Check that it is installed and in your PATH.
-`
+      this.client = new Client(
+        { name: "run-mcp", version: "1.6.1" },
+        {
+          capabilities: {
+            roots: { listChanged: true },
+            sampling: {},
+            elicitation: {}
+          }
+        }
       );
-    } else if (msg.includes("timed out")) {
-      process.stderr.write(`Error: ${msg}
-`);
-    } else {
-      process.stderr.write(`Error: ${msg}
-`);
-    }
-    await target.close().catch(() => {
-    });
-    process.exit(1);
-  }
-}
-async function executeOperation(target, interceptor, operation, opts) {
-  switch (operation.type) {
-    case "call": {
-      let parsedArgs = {};
-      if (operation.args) {
-        try {
-          parsedArgs = JSON.parse(operation.args);
-        } catch (err) {
-          process.stderr.write(`Error: Invalid JSON arguments: ${err.message}
-`);
-          process.stderr.write(`  Received: ${operation.args}
-`);
-          process.exit(2);
+      this.client.setNotificationHandler(
+        LoggingMessageNotificationSchema,
+        async (notification) => {
+          const record = {
+            method: "notifications/message",
+            params: notification.params,
+            timestamp: Date.now()
+          };
+          this._pushNotification(record);
+          this.emit("notification", record);
         }
-      }
-      const result = await interceptor.callTool(target, operation.tool, parsedArgs);
-      if (result.isError) {
-        const content = result.content;
-        if (Array.isArray(content)) {
-          const errorText = content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
-          if (errorText) {
-            process.stderr.write(`Tool error: ${errorText}
-`);
-          }
+      );
+      this.client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        const record = {
+          method: "notifications/tools/list_changed",
+          timestamp: Date.now()
+        };
+        this._pushNotification(record);
+        this.emit("notification", record);
+      });
+      this.client.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+        const record = {
+          method: "notifications/resources/list_changed",
+          timestamp: Date.now()
+        };
+        this._pushNotification(record);
+        this.emit("notification", record);
+      });
+      this.client.setNotificationHandler(
+        ResourceUpdatedNotificationSchema,
+        async (notification) => {
+          const record = {
+            method: "notifications/resources/updated",
+            params: notification.params,
+            timestamp: Date.now()
+          };
+          this._pushNotification(record);
+          this.emit("notification", record);
         }
-        if (opts.raw) return result;
-        return result.content ?? result;
-      }
-      if (opts.raw) return result;
-      return result.content ?? result;
-    }
-    case "list-tools": {
-      const { tools } = await target.listTools();
-      return tools;
-    }
-    case "list-resources": {
-      const { resources } = await target.listResources();
-      return resources;
-    }
-    case "list-prompts": {
-      const { prompts } = await target.listPrompts();
-      return prompts;
-    }
-    case "read": {
-      const result = await target.readResource({ uri: operation.uri });
-      return result;
-    }
-    case "describe": {
-      const { tools } = await target.listTools();
-      const tool = tools.find((t) => t.name === operation.tool);
-      if (!tool) {
-        const available = tools.map((t) => t.name).join(", ");
-        process.stderr.write(
-          `Error: Tool "${operation.tool}" not found.
-Available tools: ${available}
-`
-        );
-        process.exit(1);
+      );
+      this.client.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
+        const record = {
+          method: "notifications/prompts/list_changed",
+          timestamp: Date.now()
+        };
+        this._pushNotification(record);
+        this.emit("notification", record);
+      });
+      this.client.setRequestHandler(CreateMessageRequestSchema, async (request) => {
+        return new Promise((resolve2, reject) => {
+          const timeout = setTimeout(() => {
+            reject(new Error("Sampling request timed out (no response from user in 5 minutes)"));
+          }, 3e5);
+          this.emit("sampling_request", {
+            request: request.params,
+            respond: (result) => {
+              clearTimeout(timeout);
+              resolve2(result);
+            },
+            reject: (err) => {
+              clearTimeout(timeout);
+              reject(err);
+            }
+          });
+        });
+      });
+      this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
+        return new Promise((resolve2, reject) => {
+          const timeout = setTimeout(() => {
+            reject(new Error("Elicitation request timed out (no response from user in 5 minutes)"));
+          }, 3e5);
+          this.emit("elicitation_request", {
+            request: request.params,
+            respond: (result) => {
+              clearTimeout(timeout);
+              resolve2(result);
+            },
+            reject: (err) => {
+              clearTimeout(timeout);
+              reject(err);
+            }
+          });
+        });
+      });
+      this.client.setRequestHandler(ListRootsRequestSchema, async () => {
+        return { roots: this._roots };
+      });
+      this.client.onclose = () => {
+        this._connected = false;
+        this._clearStableTimer();
+        if (this._intentionalClose || !this._everConnected) {
+          return;
+        }
+        this.emit("disconnected");
+        this._maybeReconnect();
+      };
+      await this.client.connect(this.transport);
+      this._connected = true;
+      this._everConnected = true;
+      this.startTime = Date.now();
+      const proc = this.transport._process;
+      if (proc?.pid) {
+        this.childPid = proc.pid;
+      } else {
+        this.childPid = null;
       }
-      return tool;
-    }
-    case "get-prompt": {
-      let parsedArgs;
-      if (operation.args) {
-        try {
-          parsedArgs = JSON.parse(operation.args);
-        } catch (err) {
-          process.stderr.write(`Error: Invalid JSON arguments: ${err.message}
-`);
-          process.stderr.write(`  Received: ${operation.args}
-`);
-          process.exit(2);
-        }
-      }
-      const result = await target.getPrompt({
-        name: operation.name,
-        arguments: parsedArgs
-      });
-      return result;
+      this.emit("connected");
+      this._registerCleanup();
+      this._startStableTimer();
+    } catch (err) {
+      await this.close().catch(() => {
+      });
+      throw err;
     }
   }
-}
-
-// src/repl.ts
-import { readFile as readFile2 } from "fs/promises";
-import { createInterface } from "readline";
-import { checkbox, confirm, input as input2, search } from "@inquirer/prompts";
-import pc2 from "picocolors";
-
-// src/parsing.ts
-import pc from "picocolors";
-function parseCommandLine(input3) {
-  const spaceIdx = input3.indexOf(" ");
-  if (spaceIdx === -1) {
-    return { cmd: input3.toLowerCase(), rest: "" };
+  get connected() {
+    return this._connected;
   }
-  return {
-    cmd: input3.slice(0, spaceIdx).toLowerCase(),
-    rest: input3.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: "" };
+  /**
+   * Record that a response was received (for status tracking).
+   */
+  recordResponse() {
+    this._lastResponseTime = Date.now();
   }
-  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();
+  // ─── Server introspection ───────────────────────────────────────────────────
+  /**
+   * Returns the target server's advertised capabilities.
+   * Available after connect() completes.
+   */
+  getServerCapabilities() {
+    return this.client?.getServerCapabilities();
   }
-  return { toolName, jsonArgs: remainder, timeoutMs };
-}
-function formatJson(obj, indent = 2, colorize = false) {
-  const json = JSON.stringify(obj, null, indent);
-  const output = colorize ? colorizeJson(json) : json;
-  return output.split("\n").map((line) => " ".repeat(indent) + line).join("\n");
-}
-function colorizeJson(json) {
-  const result = [];
-  let i = 0;
-  let expectingValue = false;
-  while (i < json.length) {
-    const ch = json[i];
-    if (ch === '"') {
-      const str = consumeString(json, i);
-      if (expectingValue) {
-        result.push(pc.green(str));
-        expectingValue = false;
-      } else {
-        result.push(pc.cyan(str));
-      }
-      i += str.length;
-      continue;
-    }
-    if (ch === ":") {
-      result.push(ch);
-      expectingValue = true;
-      i++;
-      continue;
-    }
-    if (ch === "," || ch === "}" || ch === "]") {
-      result.push(ch);
-      expectingValue = false;
-      i++;
-      continue;
-    }
-    if (ch === "{" || ch === "[") {
-      result.push(ch);
-      if (ch === "[") expectingValue = true;
-      i++;
-      continue;
-    }
-    if (json.startsWith("true", i)) {
-      result.push(pc.magenta("true"));
-      expectingValue = false;
-      i += 4;
-      continue;
-    }
-    if (json.startsWith("false", i)) {
-      result.push(pc.magenta("false"));
-      expectingValue = false;
-      i += 5;
-      continue;
-    }
-    if (json.startsWith("null", i)) {
-      result.push(pc.dim("null"));
-      expectingValue = false;
-      i += 4;
-      continue;
-    }
-    if (ch === "-" || ch >= "0" && ch <= "9") {
-      let num = "";
-      while (i < json.length && /[0-9.eE+-]/.test(json[i])) {
-        num += json[i];
-        i++;
-      }
-      result.push(pc.yellow(num));
-      expectingValue = false;
-      continue;
-    }
-    result.push(ch);
-    i++;
+  /**
+   * Returns the target server's instructions string (if any).
+   * Agents may use this for system prompts or behavioral hints.
+   */
+  getInstructions() {
+    return this.client?.getInstructions();
   }
-  return result.join("");
-}
-function consumeString(json, start) {
-  let i = start + 1;
-  while (i < json.length) {
-    if (json[i] === "\\") {
-      i += 2;
-      continue;
+  /**
+   * Returns the target server's name and version from the MCP handshake.
+   * Available after connect() completes.
+   */
+  getServerVersion() {
+    return this.client?.getServerVersion();
+  }
+  // ─── Ping ──────────────────────────────────────────────────────────────────
+  /**
+   * Send a ping to the target MCP server and return the round-trip time.
+   */
+  async ping() {
+    this._assertConnected();
+    const start = Date.now();
+    await this.client.ping();
+    const elapsed = Date.now() - start;
+    this.recordResponse();
+    this._addHistory("ping", void 0, { ok: true }, elapsed);
+    return elapsed;
+  }
+  // ─── Tools ──────────────────────────────────────────────────────────────────
+  /**
+   * List all tools exposed by the target MCP server.
+   * Supports cursor-based pagination via params.
+   */
+  async listTools(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.listTools(params);
+    this.recordResponse();
+    this._addHistory("tools/list", params, result, Date.now() - start);
+    return result;
+  }
+  /**
+   * Call a tool on the target MCP server.
+   * We apply a massive SDK-level timeout (e.g. 10 hours) because we want to handle
+   * timeouts in the interceptor via Promise.race, and we DO NOT want to send
+   * protocol-level cancellation requests to the target server if the agent gives up.
+   * This allows long-running builds (like mobile app compiling) to finish in the background.
+   */
+  async callTool(name, args = {}, _timeoutMs) {
+    this._assertConnected();
+    const requestOptions = { timeout: 36e5 * 10 };
+    const start = Date.now();
+    const result = await this.client.callTool(
+      { name, arguments: args },
+      void 0,
+      requestOptions
+    );
+    this.recordResponse();
+    this._addHistory(`tools/call ${name}`, args, result, Date.now() - start);
+    return result;
+  }
+  // ─── Resources ──────────────────────────────────────────────────────────────
+  /**
+   * List resources exposed by the target MCP server.
+   * Supports cursor-based pagination.
+   */
+  async listResources(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.listResources(params);
+    this.recordResponse();
+    this._addHistory("resources/list", params, result, Date.now() - start);
+    return result;
+  }
+  /**
+   * List resource templates exposed by the target MCP server.
+   * Supports cursor-based pagination.
+   */
+  async listResourceTemplates(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.listResourceTemplates(params);
+    this.recordResponse();
+    this._addHistory("resources/templates/list", params, result, Date.now() - start);
+    return result;
+  }
+  /**
+   * Read a specific resource by URI from the target MCP server.
+   */
+  async readResource(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.readResource(params);
+    this.recordResponse();
+    this._addHistory(`resources/read ${params.uri}`, params, result, Date.now() - start);
+    return result;
+  }
+  /**
+   * Subscribe to resource updates on the target MCP server.
+   */
+  async subscribeResource(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.subscribeResource(params);
+    this.recordResponse();
+    this._addHistory(`resources/subscribe ${params.uri}`, params, result, Date.now() - start);
+    return result;
+  }
+  /**
+   * Unsubscribe from resource updates on the target MCP server.
+   */
+  async unsubscribeResource(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.unsubscribeResource(params);
+    this.recordResponse();
+    this._addHistory(`resources/unsubscribe ${params.uri}`, params, result, Date.now() - start);
+    return result;
+  }
+  // ─── Prompts ────────────────────────────────────────────────────────────────
+  /**
+   * List prompts exposed by the target MCP server.
+   * Supports cursor-based pagination.
+   */
+  async listPrompts(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.listPrompts(params);
+    this.recordResponse();
+    this._addHistory("prompts/list", params, result, Date.now() - start);
+    return result;
+  }
+  /**
+   * Get a specific prompt by name from the target MCP server.
+   */
+  async getPrompt(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.getPrompt(params);
+    this.recordResponse();
+    this._addHistory(`prompts/get ${params.name}`, params, result, Date.now() - start);
+    return result;
+  }
+  // ─── Logging ────────────────────────────────────────────────────────────────
+  /**
+   * Set the logging level on the target MCP server.
+   */
+  async setLoggingLevel(level) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.setLoggingLevel(level);
+    this.recordResponse();
+    this._addHistory(`logging/setLevel ${level}`, { level }, result, Date.now() - start);
+    return result;
+  }
+  // ─── Completion ─────────────────────────────────────────────────────────────
+  /**
+   * Request completion from the target MCP server (for autocomplete UX).
+   */
+  async complete(params) {
+    this._assertConnected();
+    const start = Date.now();
+    const result = await this.client.complete(params);
+    this.recordResponse();
+    this._addHistory("completion/complete", params, result, Date.now() - start);
+    return result;
+  }
+  // ─── Request History ────────────────────────────────────────────────────────
+  /**
+   * Get the request/response history.
+   * @param count - Number of recent records to return (default: all)
+   */
+  getHistory(count) {
+    if (!count || count >= this._history.length) return [...this._history];
+    return this._history.slice(-count);
+  }
+  /**
+   * Clear the history buffer.
+   */
+  clearHistory() {
+    this._history = [];
+  }
+  _addHistory(method, params, result, durationMs) {
+    const record = {
+      id: ++this._historyIdCounter,
+      method,
+      params,
+      result,
+      durationMs,
+      timestamp: Date.now()
+    };
+    this._history.push(record);
+    if (this._history.length > MAX_HISTORY) {
+      this._history = this._history.slice(-MAX_HISTORY);
     }
-    if (json[i] === '"') {
-      return json.slice(start, i + 1);
+  }
+  // ─── Notification History ───────────────────────────────────────────────────
+  /**
+   * Get recent server notifications.
+   * @param count - Number of recent notifications to return (default: all)
+   */
+  getNotifications(count) {
+    if (!count || count >= this._notifications.length) return [...this._notifications];
+    return this._notifications.slice(-count);
+  }
+  /**
+   * Clear the notification buffer.
+   */
+  clearNotifications() {
+    this._notifications = [];
+  }
+  _pushNotification(record) {
+    this._notifications.push(record);
+    if (this._notifications.length > _TargetManager.MAX_NOTIFICATIONS) {
+      this._notifications = this._notifications.slice(-_TargetManager.MAX_NOTIFICATIONS);
     }
-    i++;
   }
-  return json.slice(start);
-}
-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]);
+  // ─── Roots Management ─────────────────────────────────────────────────────
+  /**
+   * Get the current roots list that this client advertises.
+   */
+  getRoots() {
+    return [...this._roots];
+  }
+  /**
+   * Add a root and send notification to the server.
+   */
+  async addRoot(root) {
+    if (this._roots.some((r) => r.uri === root.uri)) return;
+    this._roots.push(root);
+    await this._sendRootsChanged();
+  }
+  /**
+   * Remove a root by URI and send notification to the server.
+   */
+  async removeRoot(uri) {
+    const before = this._roots.length;
+    this._roots = this._roots.filter((r) => r.uri !== uri);
+    if (this._roots.length < before) {
+      await this._sendRootsChanged();
+      return true;
     }
+    return false;
   }
-  return dp[m][n];
-}
-function suggestCommand(input3, commands, threshold = 0.4) {
-  let best = null;
-  let bestDist = Infinity;
-  for (const cmd of commands) {
-    const dist = levenshtein(input3, cmd);
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = cmd;
+  async _sendRootsChanged() {
+    if (!this._connected || !this.client) return;
+    try {
+      await this.client.sendRootsListChanged();
+    } catch {
     }
   }
-  if (best && bestDist <= Math.ceil(input3.length * threshold)) {
-    return best;
+  // ─── 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;
   }
-  return null;
-}
-function scaffoldArgs(schema) {
-  return JSON.stringify(scaffoldObject(schema), null, 2);
-}
-function scaffoldValue(prop) {
-  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
-    return prop.enum[0];
+  // ─── 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);
   }
-  const variants = prop.anyOf ?? prop.oneOf;
-  if (Array.isArray(variants) && variants.length > 0) {
-    return scaffoldValue(variants[0]);
+  /**
+   * 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
+    };
   }
-  switch (prop.type) {
-    case "string":
-      return "<string>";
-    case "number":
-    case "integer":
-      return "<number>";
-    case "boolean":
-      return "<boolean>";
-    case "array": {
-      const items = prop.items;
-      return items ? [scaffoldValue(items)] : ["<item>"];
+  /**
+   * Cleanly shut down the client connection and forcefully kill the child process tree.
+   */
+  async close() {
+    this._intentionalClose = true;
+    this._clearStableTimer();
+    const pidToKill = this.childPid;
+    if (this.client) {
+      try {
+        await this.client.close();
+      } catch {
+      }
+      this.client = null;
     }
-    case "object":
-      return scaffoldObject(prop);
-    default:
-      return `<${prop.type ?? "unknown"}>`;
-  }
-}
-function scaffoldObject(schema) {
-  const properties = schema.properties;
-  if (properties) {
-    const result = {};
-    for (const [key, prop] of Object.entries(properties)) {
-      result[key] = scaffoldValue(prop);
+    if (this.transport) {
+      try {
+        await this.transport.close();
+      } catch {
+      }
+      this.transport = null;
     }
-    return result;
+    if (pidToKill) {
+      await new Promise((resolve2) => {
+        treeKill(pidToKill, "SIGKILL", () => resolve2());
+      });
+    }
+    this._connected = false;
+    this.childPid = null;
   }
-  const additionalProperties = schema.additionalProperties;
-  if (additionalProperties && typeof additionalProperties === "object") {
-    return { "<key>": scaffoldValue(additionalProperties) };
+  // ─── 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;
+    }
   }
-  if (additionalProperties === true || schema.type === "object" && !properties) {
-    return { "<key>": "<value>" };
+  /**
+   * 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);
   }
-  return {};
-}
-function formatToolDescription(tool) {
-  const lines = [];
-  lines.push(`  ${tool.name}`);
-  if (tool.description) {
-    lines.push(`  ${tool.description}`);
+  _clearStableTimer() {
+    if (this._stableTimer) {
+      clearTimeout(this._stableTimer);
+      this._stableTimer = null;
+    }
   }
-  const schema = tool.inputSchema ?? {};
-  const properties = schema.properties;
-  const required = schema.required ?? [];
-  if (properties && Object.keys(properties).length > 0) {
-    lines.push("");
-    lines.push("  Arguments:");
-    const nameWidth = Math.max(6, ...Object.keys(properties).map((n) => n.length));
-    const typeWidth = Math.max(4, ...Object.values(properties).map((p) => typeLabel(p).length));
-    for (const [name, prop] of Object.entries(properties)) {
-      const type = typeLabel(prop);
-      const req = required.includes(name) ? "(required)" : "(optional)";
-      const desc = prop.description ?? "";
-      lines.push(
-        `    ${name.padEnd(nameWidth)}  ${type.padEnd(typeWidth)}  ${req.padEnd(10)}  ${desc}`
-      );
+  // ─── Internal helpers ──────────────────────────────────────────────────────
+  _assertConnected() {
+    if (!this._connected || !this.client) {
+      throw new Error("Not connected to target MCP server");
     }
-  } else {
-    lines.push("");
-    lines.push("  No arguments required.");
   }
-  lines.push("");
-  lines.push("  Example:");
-  if (properties && Object.keys(properties).length > 0) {
-    const example = scaffoldObject(schema);
-    lines.push(`    tools/call ${tool.name} ${JSON.stringify(example)}`);
+  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/headless.ts
+var DEFAULT_HEADLESS_TIMEOUT_MS = 3e4;
+async function runHeadless(targetCommand, operation, opts = {}) {
+  const [command, ...args] = targetCommand;
+  const target = new TargetManager(command, args);
+  const interceptor = new ResponseInterceptor({
+    outDir: opts.outDir,
+    defaultTimeoutMs: opts.timeoutMs ?? DEFAULT_HEADLESS_TIMEOUT_MS
+  });
+  if (opts.showStderr) {
+    target.on("stderr", (text) => {
+      process.stderr.write(`${text}
+`);
+    });
   } else {
-    lines.push(`    tools/call ${tool.name}`);
+    target.on("stderr", () => {
+    });
   }
-  if (tool.annotations) {
-    const entries = Object.entries(tool.annotations).filter(([key]) => key !== "title");
-    if (entries.length > 0) {
-      lines.push("");
-      lines.push("  Annotations:");
-      for (const [key, value] of entries) {
-        lines.push(`    ${key}: ${value}`);
-      }
+  try {
+    process.stderr.write(`Connecting to ${targetCommand.join(" ")}...
+`);
+    await target.connect();
+    const status = target.getStatus();
+    process.stderr.write(`Connected (PID: ${status.pid})
+`);
+    const { result, hasError } = await executeOperation(target, interceptor, operation, opts);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    await target.close();
+    process.exit(hasError ? 1 : 0);
+  } catch (err) {
+    const msg = err.message ?? String(err);
+    if (msg.includes("ENOENT") || msg.includes("spawn")) {
+      process.stderr.write(
+        `Error: command "${command}" not found. Check that it is installed and in your PATH.
+`
+      );
+    } else if (msg.includes("timed out")) {
+      process.stderr.write(`Error: ${msg}
+`);
+    } else {
+      process.stderr.write(`Error: ${msg}
+`);
     }
+    await target.close().catch(() => {
+    });
+    process.exit(1);
   }
-  return lines.join("\n");
-}
-function typeLabel(prop) {
-  const type = prop.type;
-  if (!type) return "any";
-  if (type === "array") {
-    const items = prop.items;
-    return items ? `${typeLabel(items)}[]` : "array";
-  }
-  return type;
 }
-function groupToolsByPrefix(toolNames) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const name of toolNames) {
-    const underscoreIdx = name.indexOf("_");
-    const prefix = underscoreIdx > 0 ? name.slice(0, underscoreIdx) : name;
-    const list = groups.get(prefix) ?? [];
-    list.push(name);
-    groups.set(prefix, list);
-  }
-  const meaningfulGroups = [...groups.entries()].filter(([, members]) => members.length >= 2);
-  if (meaningfulGroups.length < 2) {
-    const all = /* @__PURE__ */ new Map();
-    all.set("All", [...toolNames]);
-    return all;
-  }
-  const result = /* @__PURE__ */ new Map();
-  const other = [];
-  for (const [prefix, members] of groups) {
-    if (members.length >= 2) {
-      const label = prefix.charAt(0).toUpperCase() + prefix.slice(1);
-      result.set(label, members);
-    } else {
-      other.push(...members);
+async function executeOperation(target, interceptor, operation, opts) {
+  switch (operation.type) {
+    case "call": {
+      let parsedArgs = {};
+      if (operation.args) {
+        const trimmed = operation.args.trim();
+        if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+          try {
+            parsedArgs = JSON.parse(trimmed);
+          } catch (err) {
+            process.stderr.write(`Error: Invalid JSON arguments: ${err.message}
+`);
+            process.stderr.write(`  Received: ${operation.args}
+`);
+            process.exit(2);
+          }
+        } else {
+          parsedArgs = parseHttpieArgs(trimmed);
+        }
+      }
+      const result = await interceptor.callTool(target, operation.tool, parsedArgs);
+      if (result.isError) {
+        const content = result.content;
+        if (Array.isArray(content)) {
+          const errorText = content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
+          if (errorText) {
+            process.stderr.write(`Tool error: ${errorText}
+`);
+          }
+        }
+        if (opts.raw) return { result, hasError: true };
+        return { result: result.content ?? result, hasError: true };
+      }
+      if (opts.raw) return { result, hasError: false };
+      return { result: result.content ?? result, hasError: false };
+    }
+    case "list-tools": {
+      const { tools } = await target.listTools();
+      return { result: tools, hasError: false };
+    }
+    case "list-resources": {
+      const { resources } = await target.listResources();
+      return { result: resources, hasError: false };
+    }
+    case "list-prompts": {
+      const { prompts } = await target.listPrompts();
+      return { result: prompts, hasError: false };
+    }
+    case "read": {
+      const result = await interceptor.readResource(target, { uri: operation.uri });
+      return { result, hasError: false };
+    }
+    case "describe": {
+      const { tools } = await target.listTools();
+      const tool = tools.find((t) => t.name === operation.tool);
+      if (!tool) {
+        const available = tools.map((t) => t.name).join(", ");
+        process.stderr.write(
+          `Error: Tool "${operation.tool}" not found.
+Available tools: ${available}
+`
+        );
+        process.exit(1);
+      }
+      return { result: tool, hasError: false };
+    }
+    case "get-prompt": {
+      let parsedArgs;
+      if (operation.args) {
+        const trimmed = operation.args.trim();
+        if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+          try {
+            parsedArgs = JSON.parse(trimmed);
+          } catch (err) {
+            process.stderr.write(`Error: Invalid JSON arguments: ${err.message}
+`);
+            process.stderr.write(`  Received: ${operation.args}
+`);
+            process.exit(2);
+          }
+        } else {
+          parsedArgs = parseHttpieArgs(trimmed);
+        }
+      }
+      const result = await interceptor.getPrompt(target, {
+        name: operation.name,
+        arguments: parsedArgs
+      });
+      return { result, hasError: false };
     }
   }
-  if (other.length > 0) {
-    result.set("Other", other);
-  }
-  return result;
-}
-var LOG_LEVELS = [
-  "debug",
-  "info",
-  "notice",
-  "warning",
-  "error",
-  "critical",
-  "alert",
-  "emergency"
-];
-var ALIASES = {
-  tl: "tools/list",
-  td: "tools/describe",
-  tc: "tools/call",
-  ts: "tools/scaffold",
-  rl: "resources/list",
-  rr: "resources/read",
-  rt: "resources/templates",
-  rs: "resources/subscribe",
-  ru: "resources/unsubscribe",
-  pl: "prompts/list",
-  pg: "prompts/get"
-};
-function resolveAlias(input3) {
-  const spaceIdx = input3.indexOf(" ");
-  const token = spaceIdx === -1 ? input3 : input3.slice(0, spaceIdx);
-  const rest = spaceIdx === -1 ? "" : input3.slice(spaceIdx);
-  const expanded = ALIASES[token.toLowerCase()];
-  if (!expanded) return null;
-  return expanded + rest;
 }
 
 // src/repl.ts
+import { readFile as readFile2 } from "fs/promises";
+import { createInterface } from "readline";
+import { checkbox, confirm, input as input2, search } from "@inquirer/prompts";
+import pc2 from "picocolors";
 var KNOWN_COMMANDS = [
   "explore",
   "interactive",
@@ -1563,7 +1828,10 @@ function stripAnsi(str) {
 async function startRepl(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,
+    mediaThresholdKb: opts.mediaThresholdKb
+  });
   isScriptMode = !!opts.script;
   target.on("stderr", (text) => {
     for (const line of text.split("\n")) {
@@ -1708,7 +1976,7 @@ async function startRepl(targetCommand, opts) {
       }
     });
   }
-  let toolCount = 0;
+  let toolCount;
   let resourceCount = 0;
   let promptCount = 0;
   try {
@@ -1751,26 +2019,60 @@ async function startRepl(targetCommand, opts) {
   await refreshCaches(target);
   if (isScriptMode) {
     const lines = await readScriptLines(opts.script);
+    const scriptContext = {};
+    let expectError = false;
     for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
+      let trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) {
+        if (trimmed === "# @expect-error") {
+          expectError = true;
+        }
+        continue;
+      }
+      if (trimmed.endsWith("# @expect-error")) {
+        expectError = true;
+        trimmed = trimmed.replace(/\s*#\s*@expect-error$/, "");
+      }
+      const interpolated = interpolateString(trimmed, scriptContext);
       try {
-        await handleCommand(trimmed, target, interceptor);
+        const res = await handleCommand(interpolated, target, interceptor);
+        if (res !== void 0) {
+          scriptContext.LAST = res;
+        }
+        const isErrorRes = res && typeof res === "object" && res.isError === true;
+        if (expectError && !isErrorRes) {
+          console.error(pc2.red(`\u2717 Expected an error but the command succeeded.`));
+          await target.close();
+          process.exit(1);
+        }
+        if (!expectError && isErrorRes) {
+          console.error(pc2.red(`\u2717 Command failed unexpectedly.`));
+          await target.close();
+          process.exit(1);
+        }
+        if (expectError && isErrorRes) {
+          console.log(pc2.yellow(`  \u2713 Expected error caught: tool returned isError: true`));
+        }
       } catch (err) {
-        if (err?.message?.includes("-32601") || err?.code === -32601) {
-          let msg = "Server does not support this feature (Method not found)";
-          if (trimmed.startsWith("prompts/")) msg = "This server does not have any prompts.";
-          else if (trimmed.startsWith("resources/"))
-            msg = "This server does not have any resources.";
-          else if (trimmed.startsWith("tools/")) msg = "This server does not have any tools.";
-          console.log(pc2.yellow(`  ${msg}`));
+        if (expectError) {
+          console.log(pc2.yellow(`  \u2713 Expected error caught: ${err.message}`));
         } else {
-          console.error(pc2.red(`\u2717 Error: ${err.message}`));
+          if (err?.message?.includes("-32601") || err?.code === -32601) {
+            let msg = "Server does not support this feature (Method not found)";
+            if (trimmed.startsWith("prompts/")) msg = "This server does not have any prompts.";
+            else if (trimmed.startsWith("resources/"))
+              msg = "This server does not have any resources.";
+            else if (trimmed.startsWith("tools/")) msg = "This server does not have any tools.";
+            console.log(pc2.yellow(`  ${msg}`));
+          } else {
+            console.error(pc2.red(`\u2717 Error: ${err.message}`));
+          }
+          console.log(pc2.dim("\nShutting down..."));
+          await target.close();
+          process.exit(1);
         }
-        console.log(pc2.dim("\nShutting down..."));
-        await target.close();
-        process.exit(1);
       }
+      expectError = false;
     }
     console.log(pc2.dim("\nShutting down..."));
     await target.close();
@@ -1885,8 +2187,7 @@ async function handleCommand(input3, target, interceptor) {
       await cmdToolsDescribe(target, rest);
       return;
     case "tools/call":
-      await cmdToolsCall(target, interceptor, rest);
-      return;
+      return await cmdToolsCall(target, interceptor, rest);
     case "tools/scaffold":
       await cmdToolsScaffold(target, rest);
       return;
@@ -1897,8 +2198,7 @@ async function handleCommand(input3, target, interceptor) {
       await cmdResourcesList(target);
       return;
     case "resources/read":
-      await cmdResourcesRead(target, rest, interceptor);
-      return;
+      return await cmdResourcesRead(target, rest, interceptor);
     case "resources/templates":
       await cmdResourcesTemplates(target);
       return;
@@ -1906,8 +2206,7 @@ async function handleCommand(input3, target, interceptor) {
       await cmdPromptsList(target);
       return;
     case "prompts/get":
-      await cmdPromptsGet(target, rest, interceptor);
-      return;
+      return await cmdPromptsGet(target, rest, interceptor);
     case "timing":
       cmdTiming();
       return;
@@ -1945,7 +2244,7 @@ async function handleCommand(input3, target, interceptor) {
     case "last":
       if (lastCommand) {
         console.log(pc2.dim(`  Re-running: ${lastCommand}`));
-        await handleCommand(lastCommand, target, interceptor);
+        return await handleCommand(lastCommand, target, interceptor);
       } else {
         console.log(pc2.yellow("No previous command to re-run."));
       }
@@ -1961,6 +2260,9 @@ async function handleCommand(input3, target, interceptor) {
       return;
     }
     default: {
+      if (cachedToolNames.includes(cmd)) {
+        return await cmdToolsCall(target, interceptor, input3);
+      }
       const suggestion = suggestCommand(cmd, getActiveCommands());
       if (suggestion) {
         console.log(pc2.yellow(`Unknown command: ${cmd}.`));
@@ -1972,7 +2274,7 @@ async function handleCommand(input3, target, interceptor) {
             });
             if (runIt) {
               const rebuiltCommand = rest ? `${suggestion} ${rest}` : suggestion;
-              await handleCommand(rebuiltCommand, target, interceptor);
+              return await handleCommand(rebuiltCommand, target, interceptor);
             }
           });
         } catch (err) {
@@ -2080,32 +2382,54 @@ async function cmdToolsCall(target, interceptor, rest) {
   }
   let args = {};
   if (jsonArgs) {
-    try {
-      args = JSON.parse(jsonArgs);
-    } catch (err) {
-      console.error(pc2.red(`Invalid JSON: ${err.message}`));
-      console.log(pc2.dim(`  Received: ${jsonArgs}`));
-      return;
+    const trimmed = jsonArgs.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+      try {
+        args = JSON.parse(trimmed);
+      } catch (err) {
+        console.error(pc2.red(`Invalid JSON: ${err.message}`));
+        console.log(pc2.dim(`  Received: ${jsonArgs}`));
+        return;
+      }
+    } else {
+      try {
+        args = parseHttpieArgs(trimmed);
+      } catch (err) {
+        console.error(pc2.red(`Invalid shorthand arguments: ${err.message}`));
+        return;
+      }
     }
     const { tools } = await target.listTools();
     const tool = tools.find((t) => t.name === toolName);
-    if (tool) {
-      const schema = tool.inputSchema;
-      const required = schema.required ?? [];
-      const missing = required.filter((r) => !(r in args));
-      if (missing.length > 0) {
-        console.log(pc2.yellow(`
-  Missing required arguments: ${missing.join(", ")}`));
-        console.log();
-        const scaffolded = scaffoldArgs(schema);
-        console.log(pc2.dim("  Try:"));
-        console.log(`    tools/call ${toolName} ${scaffolded}`);
-        console.log();
-        console.log(pc2.dim("  Or run without args for interactive mode:"));
-        console.log(`    tools/call ${toolName}`);
-        console.log();
-        return;
+    if (!tool) {
+      console.log(pc2.red(`
+  \u2717 Tool "${toolName}" not found.`));
+      const toolNames = tools.map((t) => t.name);
+      const suggestion = suggestCommand(toolName, toolNames);
+      if (suggestion) {
+        console.log(pc2.yellow(`  \u{1F4A1} Did you mean "${suggestion}"?`));
+      } else {
+        const preview = toolNames.slice(0, 6);
+        const more = toolNames.length > 6 ? `, ... (${toolNames.length} total)` : "";
+        console.log(pc2.dim(`  Available tools: ${preview.join(", ")}${more}`));
       }
+      return { isError: true, content: [{ type: "text", text: `Tool not found: ${toolName}` }] };
+    }
+    const schema = tool.inputSchema;
+    const required = schema.required ?? [];
+    const missing = required.filter((r) => !(r in args));
+    if (missing.length > 0) {
+      console.log(pc2.yellow(`
+  Missing required arguments: ${missing.join(", ")}`));
+      console.log();
+      const scaffolded = scaffoldArgs(schema);
+      console.log(pc2.dim("  Try:"));
+      console.log(`    tools/call ${toolName} ${scaffolded}`);
+      console.log();
+      console.log(pc2.dim("  Or run without args for interactive mode:"));
+      console.log(`    tools/call ${toolName}`);
+      console.log();
+      return;
     }
   } else {
     const collectedArgs = await interactiveArgPrompt(target, interceptor, toolName, clearPrevious);
@@ -2159,14 +2483,18 @@ async function cmdToolsCall(target, interceptor, rest) {
     console.log(formatJson(result, 2, true));
   }
   if (isError) {
-    console.log(
-      pc2.yellow(
-        `  \u{1F4A1} Tip: Check the tool arguments via 'tools/describe ${toolName}' 
+    const errText = Array.isArray(content) ? content.map((c) => c.text || "").join(" ").toLowerCase() : typeof content === "object" ? (content.text || "").toLowerCase() : "";
+    if (errText.includes("argument") || errText.includes("validation") || errText.includes("schema") || errText.includes("missing") || errText.includes("invalid")) {
+      console.log(
+        pc2.yellow(
+          `  \u{1F4A1} Tip: Check the tool arguments via 'tools/describe ${toolName}' 
           or view the raw server stderr above.`
-      )
-    );
+        )
+      );
+    }
   }
   console.log();
+  return result;
 }
 async function interactiveArgPrompt(target, interceptor, toolName, clearPrevious = false) {
   const { tools } = await target.listTools();
@@ -2327,7 +2655,7 @@ function coerceValue(input3, type) {
   }
 }
 function question(rl, prompt) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let aborted = false;
     const onKeypress = (_str, key) => {
       if (key && key.name === "escape") {
@@ -2351,7 +2679,7 @@ function question(rl, prompt) {
       if (aborted) {
         reject(new AbortFlowError());
       } else {
-        resolve(answer);
+        resolve2(answer);
       }
     });
   });
@@ -2458,6 +2786,7 @@ async function cmdResourcesRead(target, rest, interceptor) {
     }
   }
   console.log();
+  return result;
 }
 async function cmdResourcesTemplates(target) {
   const { resourceTemplates } = await target.listResourceTemplates();
@@ -2500,9 +2829,9 @@ async function cmdPromptsGet(target, rest, interceptor) {
   if (!promptName) {
     if (!isScriptMode && cachedPromptNames.length > 0 && process.stdin.isTTY && interceptor) {
       const picked = await withSuspendedReadline(target, interceptor, async () => {
-        const { prompts } = await target.listPrompts();
+        const { prompts: prompts2 } = await target.listPrompts();
         return pickInteractive(
-          prompts.map((p) => ({ name: p.name, description: p.description })),
+          prompts2.map((p) => ({ name: p.name, description: p.description })),
           "Pick a prompt to get:"
         );
       });
@@ -2516,15 +2845,39 @@ async function cmdPromptsGet(target, rest, interceptor) {
     }
     return;
   }
-  let promptArgs = {};
-  if (jsonArgs) {
-    try {
-      promptArgs = JSON.parse(jsonArgs);
-    } catch (err) {
-      console.error(pc2.red(`Invalid JSON: ${err.message}`));
-      console.log(pc2.dim(`  Received: ${jsonArgs}`));
-      return;
+  let promptArgs = {};
+  if (jsonArgs) {
+    const trimmed = jsonArgs.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+      try {
+        promptArgs = JSON.parse(trimmed);
+      } catch (err) {
+        console.error(pc2.red(`Invalid JSON: ${err.message}`));
+        console.log(pc2.dim(`  Received: ${jsonArgs}`));
+        return;
+      }
+    } else {
+      try {
+        promptArgs = parseHttpieArgs(trimmed);
+      } catch (err) {
+        console.error(pc2.red(`Invalid shorthand arguments: ${err.message}`));
+        return;
+      }
+    }
+  }
+  const { prompts } = await target.listPrompts();
+  const prompt = prompts.find((p) => p.name === promptName);
+  if (!prompt) {
+    console.log(pc2.red(`
+  \u2717 Prompt "${promptName}" not found.`));
+    const promptNames = prompts.map((p) => p.name);
+    const suggestion = suggestCommand(promptName, promptNames);
+    if (suggestion) {
+      console.log(pc2.yellow(`  \u{1F4A1} Did you mean "${suggestion}"?`));
+    } else {
+      console.log(pc2.dim(`  Available prompts: ${promptNames.join(", ")}`));
     }
+    return { isError: true, content: [{ type: "text", text: `Prompt not found: ${promptName}` }] };
   }
   const startTime = Date.now();
   const result = await target.getPrompt({ name: promptName, arguments: promptArgs });
@@ -2551,6 +2904,7 @@ async function cmdPromptsGet(target, rest, interceptor) {
     }
   }
   console.log();
+  return result;
 }
 async function cmdPing(target) {
   try {
@@ -2724,7 +3078,7 @@ async function cmdRootsRemove(target, rest) {
 async function cmdReconnect(target) {
   console.log(pc2.cyan("\u27F3 Disconnecting..."));
   await target.close();
-  await new Promise((resolve) => setTimeout(resolve, 200));
+  await new Promise((resolve2) => setTimeout(resolve2, 200));
   console.log(pc2.cyan("\u27F3 Reconnecting..."));
   const { command, args } = target.getStatus();
   console.log(pc2.dim(`  Command: ${command} ${args.join(" ")}`));
@@ -3062,6 +3416,13 @@ function computeResourceDiff(prev, curr) {
   const removed = [...prevUris].filter((u) => !currUris.has(u));
   return { added, removed, modified: [] };
 }
+function computeResourceTemplateDiff(prev, curr) {
+  const prevUris = new Set(prev.map((t) => t.uriTemplate));
+  const currUris = new Set(curr.map((t) => t.uriTemplate));
+  const added = [...currUris].filter((u) => !prevUris.has(u));
+  const removed = [...prevUris].filter((u) => !currUris.has(u));
+  return { added, removed, modified: [] };
+}
 function formatDiffLine(label, diff) {
   const parts = [];
   if (diff.added.length > 0) parts.push(`+${diff.added.length} added`);
@@ -3075,19 +3436,70 @@ function formatDiffLine(label, diff) {
 async function startServer(opts) {
   let target = null;
   let previousSnapshot = null;
+  let cachedSpawnConfig = null;
   const interceptor = new ResponseInterceptor({
     outDir: opts.outDir,
     defaultTimeoutMs: opts.timeoutMs,
-    maxTextLength: opts.maxTextLength
+    maxTextLength: opts.maxTextLength,
+    mediaThresholdKb: opts.mediaThresholdKb
   });
   const mcpServer = new McpServer(
-    { name: "run-mcp", version: "1.6.0" },
+    { name: "run-mcp", version: "1.6.1" },
     {
       capabilities: {
-        tools: {}
+        tools: {},
+        logging: {}
       }
     }
   );
+  function setupTargetListeners(t) {
+    t.on("stderr", (text) => {
+      mcpServer.sendLoggingMessage({
+        level: "info",
+        logger: "target-stderr",
+        data: text
+      }).catch(() => {
+      });
+    });
+    t.on("disconnected", () => {
+      const pid = t.getStatus().pid;
+      mcpServer.sendLoggingMessage({
+        level: "error",
+        logger: "run-mcp",
+        data: `Target server disconnected unexpectedly! (PID: ${pid})`
+      }).catch(() => {
+      });
+    });
+    t.on("notification", (record) => {
+      mcpServer.server.notification({
+        method: record.method,
+        params: record.params
+      }).catch(() => {
+      });
+    });
+    t.on("sampling_request", async ({ request, respond, reject }) => {
+      try {
+        const result = await mcpServer.server.request(
+          { method: "sampling/createMessage", params: request },
+          z.any()
+        );
+        respond(result);
+      } catch (err) {
+        reject(err);
+      }
+    });
+    t.on("elicitation_request", async ({ request, respond, reject }) => {
+      try {
+        const result = await mcpServer.server.request(
+          { method: "elicitation/create", params: request },
+          z.any()
+        );
+        respond(result);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
   async function takeSnapshot() {
     if (!target?.connected) return {};
     const snap = {};
@@ -3114,6 +3526,14 @@ async function startServer(opts) {
         }));
       } catch {
       }
+      try {
+        const { resourceTemplates } = await target.listResourceTemplates();
+        snap.resourceTemplates = resourceTemplates.map((t) => ({
+          uriTemplate: t.uriTemplate,
+          name: t.name ?? ""
+        }));
+      } catch {
+      }
     }
     if (caps.prompts) {
       try {
@@ -3141,6 +3561,17 @@ async function startServer(opts) {
         )
       );
     }
+    if (current.resourceTemplates && previousSnapshot.resourceTemplates) {
+      lines.push(
+        formatDiffLine(
+          "Resource Templates",
+          computeResourceTemplateDiff(
+            previousSnapshot.resourceTemplates,
+            current.resourceTemplates
+          )
+        )
+      );
+    }
     if (current.prompts && previousSnapshot.prompts) {
       lines.push(formatDiffLine("Prompts", computeDiff(previousSnapshot.prompts, current.prompts)));
     }
@@ -3154,29 +3585,59 @@ async function startServer(opts) {
   }
   async function ensureConnected(command, args, env) {
     if (target?.connected) return null;
-    if (!command) {
+    let cmdToUse = command;
+    let argsToUse = args;
+    let envToUse = env;
+    if (!cmdToUse && cachedSpawnConfig) {
+      cmdToUse = cachedSpawnConfig.command;
+      argsToUse = cachedSpawnConfig.args;
+      envToUse = cachedSpawnConfig.env;
+    }
+    if (!cmdToUse) {
       return "Not connected to a target server. Provide command/args to auto-connect, or call connect_to_mcp first.";
     }
     if (target) {
       await target.close();
       target = null;
     }
-    if (env) {
-      for (const [key, value] of Object.entries(env)) {
+    if (envToUse) {
+      for (const [key, value] of Object.entries(envToUse)) {
         process.env[key] = value;
       }
     }
-    target = new TargetManager(command, args ?? []);
-    await target.connect();
+    target = new TargetManager(cmdToUse, argsToUse ?? []);
+    setupTargetListeners(target);
+    try {
+      await target.connect();
+    } catch (err) {
+      await target.close().catch(() => {
+      });
+      target = null;
+      throw err;
+    }
+    cachedSpawnConfig = { command: cmdToUse, args: argsToUse ?? [], env: envToUse };
     return null;
   }
-  async function buildIncludeData(include) {
+  async function buildIncludeData(include, summary = false) {
     if (!target?.connected || include.length === 0) return [];
     const lines = [];
     if (include.includes("tools")) {
       try {
         const { tools } = await target.listTools();
-        lines.push("", "--- Tools ---", JSON.stringify(tools, null, 2));
+        let displayTools = summary ? tools.map((t) => ({ name: t.name, description: t.description })) : tools;
+        let jsonStr = JSON.stringify(displayTools, null, 2);
+        if (!summary && jsonStr.length > 2e4) {
+          displayTools = tools.map((t) => ({ name: t.name, description: t.description }));
+          jsonStr = JSON.stringify(displayTools, null, 2);
+          lines.push(
+            "",
+            "--- Tools ---",
+            jsonStr,
+            "[Note: Full schemas omitted to protect context window. Use list_mcp_primitives with name='tool_name' to inspect schemas individually.]"
+          );
+        } else {
+          lines.push("", "--- Tools ---", jsonStr);
+        }
       } catch (err) {
         lines.push("", "--- Tools ---", `Error: ${err.message}`);
       }
@@ -3184,15 +3645,50 @@ async function startServer(opts) {
     if (include.includes("resources")) {
       try {
         const { resources } = await target.listResources();
-        lines.push("", "--- Resources ---", JSON.stringify(resources, null, 2));
+        let displayResources = summary ? resources.map((r) => ({
+          name: r.name,
+          uri: r.uri,
+          description: r.description
+        })) : resources;
+        let jsonStr = JSON.stringify(displayResources, null, 2);
+        if (!summary && jsonStr.length > 2e4) {
+          displayResources = resources.map((r) => ({
+            name: r.name,
+            uri: r.uri,
+            description: r.description
+          }));
+          jsonStr = JSON.stringify(displayResources, null, 2);
+          lines.push(
+            "",
+            "--- Resources ---",
+            jsonStr,
+            "[Note: Full schemas omitted to protect context window.]"
+          );
+        } else {
+          lines.push("", "--- Resources ---", jsonStr);
+        }
       } catch (err) {
         lines.push("", "--- Resources ---", `Error: ${err.message}`);
       }
     }
+    if (include.includes("resource_templates")) {
+      try {
+        const { resourceTemplates } = await target.listResourceTemplates();
+        const displayTemplates = summary ? resourceTemplates.map((t) => ({
+          name: t.name,
+          uriTemplate: t.uriTemplate,
+          description: t.description
+        })) : resourceTemplates;
+        lines.push("", "--- Resource Templates ---", JSON.stringify(displayTemplates, null, 2));
+      } catch (err) {
+        lines.push("", "--- Resource Templates ---", `Error: ${err.message}`);
+      }
+    }
     if (include.includes("prompts")) {
       try {
         const { prompts } = await target.listPrompts();
-        lines.push("", "--- Prompts ---", JSON.stringify(prompts, null, 2));
+        const displayPrompts = summary ? prompts.map((p) => ({ name: p.name, description: p.description })) : prompts;
+        lines.push("", "--- Prompts ---", JSON.stringify(displayPrompts, null, 2));
       } catch (err) {
         lines.push("", "--- Prompts ---", `Error: ${err.message}`);
       }
@@ -3203,17 +3699,20 @@ async function startServer(opts) {
     "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. Use the 'include' parameter to get tools/resources/prompts in the response, saving round trips.",
+      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. Use the 'include' parameter to get tools/resources/prompts/resource_templates in the response, saving round trips.",
       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"),
-        include: z.array(z.enum(["tools", "resources", "prompts"])).optional().describe(
+        include: z.array(z.enum(["tools", "resources", "resource_templates", "prompts"])).optional().describe(
           "Primitives to include in the response. Saves round trips vs calling list_mcp_primitives separately. On reconnect, also shows a diff of what changed since the last connection."
+        ),
+        summary: z.boolean().optional().describe(
+          "If true, returns only the name and description of each primitive (omitting full schemas) when included to save tokens."
         )
       }
     },
-    async ({ command, args, env, include }) => {
+    async ({ command, args, env, include, summary }) => {
       if (target?.connected) {
         return {
           content: [
@@ -3236,7 +3735,16 @@ async function startServer(opts) {
           }
         }
         target = new TargetManager(command, args ?? []);
-        await target.connect();
+        setupTargetListeners(target);
+        try {
+          await target.connect();
+        } catch (err) {
+          await target.close().catch(() => {
+          });
+          target = null;
+          throw err;
+        }
+        cachedSpawnConfig = { command, args: args ?? [], env };
         const status = target.getStatus();
         const caps = target.getServerCapabilities() ?? {};
         const capSummary = [];
@@ -3265,7 +3773,7 @@ async function startServer(opts) {
         }
         previousSnapshot = currentSnapshot;
         if (include && include.length > 0) {
-          lines.push(...await buildIncludeData(include));
+          lines.push(...await buildIncludeData(include, summary));
         }
         const instructions = target.getInstructions();
         if (instructions) {
@@ -3349,17 +3857,21 @@ Check that the command is correct and the server starts without errors. You can
     "list_mcp_primitives",
     {
       title: "List MCP Primitives",
-      description: "List tools, resources, and/or prompts on the connected MCP server. Specify which types to include. Defaults to all available. Use 'name' to filter to a specific item (e.g. describe a single tool's schema).",
+      description: "List tools, resources, resource templates, and/or prompts on the connected MCP server. Specify which types to include. Defaults to all available. Use 'name' to filter to a specific item (e.g. describe a single tool's schema).",
       inputSchema: {
-        type: z.array(z.enum(["tools", "resources", "prompts"])).optional().describe(
+        type: z.array(z.enum(["tools", "resources", "resource_templates", "prompts"])).optional().describe(
           "Which primitives to list. Defaults to all that the server supports. Example: ['tools'] to list only tools."
         ),
         name: z.string().optional().describe(
-          "Filter to a specific item by name. For tools: matches tool name. For resources: matches URI. For prompts: matches prompt name. Returns the full schema/details for just that item."
-        )
+          "Filter to a specific item by name. For tools: matches tool name. For resources: matches URI. For resource templates: matches URI template. For prompts: matches prompt name. Returns the full schema/details for just that item."
+        ),
+        summary: z.boolean().optional().describe(
+          "If true, returns only the name and description of each primitive (omitting full schemas) to save tokens."
+        ),
+        cursor: z.string().optional().describe("Cursor for pagination (returned from a previous list call)")
       }
     },
-    async ({ type, name }) => {
+    async ({ type, name, summary, cursor }) => {
       if (!target?.connected) {
         return {
           content: [
@@ -3372,11 +3884,11 @@ Check that the command is correct and the server starts without errors. You can
         };
       }
       const caps = target.getServerCapabilities() ?? {};
-      const requested = type ?? ["tools", "resources", "prompts"];
+      const requested = type ?? ["tools", "resources", "resource_templates", "prompts"];
       const sections = [];
       if (requested.includes("tools") && caps.tools) {
         try {
-          const result = await target.listTools();
+          const result = await target.listTools({ cursor });
           let tools = result.tools;
           if (name) {
             tools = tools.filter((t) => t.name === name);
@@ -3388,7 +3900,11 @@ Available: ${available}`);
               sections.push("--- Tools ---", JSON.stringify(tools[0], null, 2));
             }
           } else {
-            sections.push("--- Tools ---", JSON.stringify(tools, null, 2));
+            const displayTools = summary ? tools.map((t) => ({ name: t.name, description: t.description })) : tools;
+            sections.push("--- Tools ---", JSON.stringify(displayTools, null, 2));
+          }
+          if (result.nextCursor) {
+            sections.push(`--- Tools Next Cursor: ${result.nextCursor} ---`);
           }
         } catch (err) {
           sections.push("--- Tools ---", `Error: ${err.message}`);
@@ -3396,7 +3912,7 @@ Available: ${available}`);
       }
       if (requested.includes("resources") && caps.resources) {
         try {
-          const result = await target.listResources();
+          const result = await target.listResources({ cursor });
           let resources = result.resources;
           if (name) {
             resources = resources.filter((r) => r.uri === name || r.name === name);
@@ -3411,15 +3927,54 @@ Available: ${available}`
               sections.push("--- Resources ---", JSON.stringify(resources[0], null, 2));
             }
           } else {
-            sections.push("--- Resources ---", JSON.stringify(resources, null, 2));
+            const displayResources = summary ? resources.map((r) => ({
+              name: r.name,
+              uri: r.uri,
+              description: r.description
+            })) : resources;
+            sections.push("--- Resources ---", JSON.stringify(displayResources, null, 2));
+          }
+          if (result.nextCursor) {
+            sections.push(`--- Resources Next Cursor: ${result.nextCursor} ---`);
           }
         } catch (err) {
           sections.push("--- Resources ---", `Error: ${err.message}`);
         }
       }
+      if (requested.includes("resource_templates") && caps.resources) {
+        try {
+          const result = await target.listResourceTemplates({ cursor });
+          let templates = result.resourceTemplates;
+          if (name) {
+            templates = templates.filter((t) => t.uriTemplate === name || t.name === name);
+            if (templates.length === 0) {
+              const available = result.resourceTemplates.map((t) => t.uriTemplate).join(", ");
+              sections.push(
+                "--- Resource Templates ---",
+                `Resource Template "${name}" not found.
+Available: ${available}`
+              );
+            } else {
+              sections.push("--- Resource Templates ---", JSON.stringify(templates[0], null, 2));
+            }
+          } else {
+            const displayTemplates = summary ? templates.map((t) => ({
+              name: t.name,
+              uriTemplate: t.uriTemplate,
+              description: t.description
+            })) : templates;
+            sections.push("--- Resource Templates ---", JSON.stringify(displayTemplates, null, 2));
+          }
+          if (result.nextCursor) {
+            sections.push(`--- Resource Templates Next Cursor: ${result.nextCursor} ---`);
+          }
+        } catch (err) {
+          sections.push("--- Resource Templates ---", `Error: ${err.message}`);
+        }
+      }
       if (requested.includes("prompts") && caps.prompts) {
         try {
-          const result = await target.listPrompts();
+          const result = await target.listPrompts({ cursor });
           let prompts = result.prompts;
           if (name) {
             prompts = prompts.filter((p) => p.name === name);
@@ -3434,7 +3989,11 @@ Available: ${available}`
               sections.push("--- Prompts ---", JSON.stringify(prompts[0], null, 2));
             }
           } else {
-            sections.push("--- Prompts ---", JSON.stringify(prompts, null, 2));
+            const displayPrompts = summary ? prompts.map((p) => ({ name: p.name, description: p.description })) : prompts;
+            sections.push("--- Prompts ---", JSON.stringify(displayPrompts, null, 2));
+          }
+          if (result.nextCursor) {
+            sections.push(`--- Prompts Next Cursor: ${result.nextCursor} ---`);
           }
         } catch (err) {
           sections.push("--- Prompts ---", `Error: ${err.message}`);
@@ -3511,16 +4070,21 @@ Available: ${available}`
         name: z.string().describe("Tool name, resource URI, or prompt name"),
         arguments: z.record(z.unknown()).optional().describe("Arguments for the tool or prompt (not used for resources)"),
         // Auto-connect params (only needed if not already connected)
-        command: z.string().optional().describe(
-          "Command to spawn the server (e.g. 'node'). Required if not already connected."
+        auto_connect: z.object({
+          command: z.string().describe("Command to spawn the server (e.g. 'node')."),
+          args: z.array(z.string()).optional().describe("Arguments for the server command (e.g. ['src/index.js'])"),
+          env: z.record(z.string()).optional().describe("Extra environment variables for the server process")
+        }).optional().describe(
+          "Provide this to automatically spawn and connect to a server if not already connected. Required if no active connection exists."
         ),
-        args: z.array(z.string()).optional().describe("Arguments for the server command (e.g. ['src/index.js'])"),
-        env: z.record(z.string()).optional().describe("Extra environment variables for the server process"),
         // Lifecycle
         disconnect_after: z.boolean().optional().describe("Tear down the connection after this call (default: false)"),
         timeout_ms: z.number().optional().describe("Timeout in ms (only applies to type: 'tool')"),
         include_metadata: z.boolean().optional().describe(
           "Include a structured metadata content item with latency, interception info, and content statistics. Useful for programmatic consumption."
+        ),
+        max_text_length: z.number().optional().describe(
+          "Max text response length before truncation for this call. Use -1 to disable truncation."
         )
       }
     },
@@ -3528,15 +4092,18 @@ Available: ${available}`
       type: primitiveType,
       name,
       arguments: callArgs,
-      command,
-      args,
-      env,
+      auto_connect,
       disconnect_after,
       timeout_ms,
-      include_metadata
+      include_metadata,
+      max_text_length
     }) => {
       try {
-        const connectError = await ensureConnected(command, args, env);
+        const connectError = await ensureConnected(
+          auto_connect?.command,
+          auto_connect?.args,
+          auto_connect?.env
+        );
         if (connectError) {
           return {
             content: [{ type: "text", text: connectError }],
@@ -3602,7 +4169,8 @@ Available tools: ${toolNames.join(", ")}`
                 target,
                 name,
                 callArgs ?? {},
-                timeout_ms
+                timeout_ms,
+                max_text_length
               );
               result = toolResult;
               interceptionMeta = metadata;
@@ -3611,17 +4179,12 @@ Available tools: ${toolNames.join(", ")}`
                 target,
                 name,
                 callArgs ?? {},
-                timeout_ms
+                timeout_ms,
+                max_text_length
               );
             }
             const elapsedMs = Date.now() - startMs;
             const resultContent = result.content;
-            if (!include_metadata && Array.isArray(resultContent) && resultContent.length > 0) {
-              const lastItem = resultContent[resultContent.length - 1];
-              if (lastItem.type === "text") {
-                lastItem.text += ` (${elapsedMs}ms)`;
-              }
-            }
             if (include_metadata && Array.isArray(resultContent)) {
               const meta = {
                 latency_ms: elapsedMs,
@@ -3643,24 +4206,102 @@ ${JSON.stringify(meta)}`
             break;
           }
           case "resource": {
-            const resourceResult = await target.readResource({ uri: name });
-            result = {
-              content: [
-                { type: "text", text: JSON.stringify(resourceResult.contents, null, 2) }
-              ]
-            };
+            const startMs = Date.now();
+            const resourceResult = await interceptor.readResource(
+              target,
+              { uri: name },
+              timeout_ms,
+              max_text_length
+            );
+            const elapsedMs = Date.now() - startMs;
+            const contentItems = resourceResult.contents.map((c) => {
+              if (c.text !== void 0) {
+                return { type: "text", text: c.text };
+              } else {
+                return { type: "text", text: `[Resource blob: ${c.uri}]` };
+              }
+            });
+            result = { content: contentItems };
+            if (include_metadata) {
+              const meta = {
+                latency_ms: elapsedMs,
+                content_items: contentItems.length,
+                is_error: false
+              };
+              contentItems.unshift({
+                type: "text",
+                text: `--- metadata ---
+${JSON.stringify(meta)}`
+              });
+            }
             break;
           }
           case "prompt": {
-            const promptResult = await target.getPrompt({
-              name,
-              arguments: callArgs ?? {}
-            });
-            result = {
-              content: [
-                { type: "text", text: JSON.stringify(promptResult.messages, null, 2) }
-              ]
-            };
+            try {
+              const { prompts } = await target.listPrompts();
+              const promptNames = prompts.map((p) => p.name);
+              const matchedPrompt = prompts.find((p) => p.name === name);
+              if (!matchedPrompt) {
+                const suggestion = suggestCommand(name, promptNames);
+                const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
+                return {
+                  content: [
+                    {
+                      type: "text",
+                      text: `Prompt "${name}" not found.${hint}
+Available prompts: ${promptNames.join(", ")}`
+                    }
+                  ],
+                  isError: true
+                };
+              }
+            } catch {
+            }
+            const startMs = Date.now();
+            const promptResult = await interceptor.getPrompt(
+              target,
+              {
+                name,
+                arguments: callArgs ?? {}
+              },
+              timeout_ms,
+              max_text_length
+            );
+            const elapsedMs = Date.now() - startMs;
+            const contentItems = [];
+            for (const msg of promptResult.messages) {
+              const role = msg.role;
+              const content = msg.content;
+              const prefix = `[${role.toUpperCase()} MESSAGE]`;
+              if (content.type === "text") {
+                contentItems.push({ type: "text", text: `${prefix}
+${content.text}` });
+              } else if (Array.isArray(content)) {
+                for (const item of content) {
+                  if (item.type === "text") {
+                    contentItems.push({ type: "text", text: `${prefix}
+${item.text}` });
+                  } else {
+                    contentItems.push(item);
+                  }
+                }
+              } else {
+                contentItems.push(content);
+              }
+            }
+            result = { content: contentItems };
+            if (include_metadata) {
+              const meta = {
+                latency_ms: elapsedMs,
+                content_items: contentItems.length,
+                is_error: false
+              };
+              contentItems.unshift({
+                type: "text",
+                text: `--- metadata ---
+${JSON.stringify(meta)}`
+              });
+            }
             break;
           }
         }
@@ -3722,74 +4363,376 @@ ${JSON.stringify(meta)}`
 }
 
 // src/index.ts
-function extractTargetCommand(targetCommand) {
-  return targetCommand.filter((a) => a !== "--");
-}
 function requireTargetCommand(targetCommand, subcommandUsage) {
-  const target = extractTargetCommand(targetCommand);
-  if (target.length === 0) {
-    process.stderr.write(`Error: No target server command provided after '--'.
+  if (!activeTargetCommand) {
+    process.stderr.write(`Error: Target server command must be separated by '--'.
+`);
+    process.stderr.write(`This avoids option parsing conflicts.
+
 `);
     process.stderr.write(`Usage: ${subcommandUsage}
 `);
     process.exit(2);
   }
-  return target;
+  return activeTargetCommand;
+}
+var SESSION_DIR = join2(tmpdir2(), "run-mcp", "sessions");
+function getSessionPath(name) {
+  return join2(SESSION_DIR, `${name}.json`);
+}
+async function getSession(name) {
+  const path2 = getSessionPath(name);
+  if (!existsSync2(path2)) return null;
+  try {
+    const data = await readFile3(path2, "utf8");
+    const parsed = JSON.parse(data);
+    try {
+      process.kill(parsed.pid, 0);
+      return parsed;
+    } catch {
+      await rm(path2, { force: true }).catch(() => {
+      });
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}
+function sendDaemonRequest(port, request) {
+  return new Promise((resolve2, reject) => {
+    const socket = createConnection({ port });
+    let buffer = "";
+    socket.on("connect", () => {
+      socket.write(JSON.stringify(request) + "\n");
+    });
+    socket.on("data", (data) => {
+      buffer += data.toString();
+    });
+    socket.on("end", () => {
+      try {
+        const parsed = JSON.parse(buffer);
+        if (parsed.error) {
+          reject(new Error(parsed.error.message));
+        } else {
+          resolve2(parsed.result);
+        }
+      } catch (err) {
+        reject(new Error(`Failed to parse daemon response: ${err}`));
+      }
+    });
+    socket.on("error", (err) => {
+      reject(err);
+    });
+  });
+}
+async function handleHeadlessSession(sessionName, targetCommand, operation, opts, subcommandUsage) {
+  let session = await getSession(sessionName);
+  if (!session) {
+    if (!activeTargetCommand) {
+      process.stderr.write(`Error: Session "${sessionName}" is not running.
+`);
+      process.stderr.write(`Please provide a target command after '--' to start it.
+
+`);
+      process.stderr.write(`Usage: ${subcommandUsage}
+`);
+      process.exit(2);
+    }
+    const target = activeTargetCommand;
+    const binPath = resolve(import.meta.dirname, "./index.js");
+    const daemonProcess = spawn("node", [binPath, "daemon", sessionName, ...target], {
+      detached: true,
+      stdio: "ignore"
+    });
+    daemonProcess.unref();
+    let attempts = 0;
+    while (attempts < 50) {
+      session = await getSession(sessionName);
+      if (session) break;
+      await new Promise((resolve2) => setTimeout(resolve2, 100));
+      attempts++;
+    }
+    if (!session) {
+      process.stderr.write(
+        `Error: Failed to spawn background daemon for session "${sessionName}".
+`
+      );
+      process.exit(1);
+    }
+  }
+  try {
+    const response = await sendDaemonRequest(session.port, {
+      jsonrpc: "2.0",
+      method: "execute",
+      params: { operation, opts },
+      id: 1
+    });
+    process.stdout.write(`${JSON.stringify(response.result, null, 2)}
+`);
+    process.exit(response.hasError ? 1 : 0);
+  } catch (err) {
+    process.stderr.write(`Error communicating with session daemon: ${err.message}
+`);
+    process.exit(1);
+  }
 }
 function parseHeadlessOpts(opts) {
   return {
     outDir: opts.outDir,
     timeoutMs: opts.timeout ? Number.parseInt(opts.timeout, 10) : void 0,
-    raw: opts.raw
+    raw: opts.raw,
+    showStderr: opts.showStderr,
+    mediaThresholdKb: opts.mediaThreshold ? Number.parseInt(opts.mediaThreshold, 10) : void 0
   };
 }
+var activeTargetCommand;
+var argvToParse = process.argv;
+var dashDashIndex = process.argv.indexOf("--");
+if (dashDashIndex !== -1) {
+  activeTargetCommand = process.argv.slice(dashDashIndex + 1);
+  argvToParse = [...process.argv.slice(0, dashDashIndex)];
+}
 program.enablePositionalOptions();
-program.command("call").argument("<tool>", "Tool name to call").argument("[json_args]", "JSON arguments for the tool").argument("[target_command...]", "Target server command (after --)").description("Call a tool on a target MCP server and print the result as JSON").option("-o, --out-dir <path>", "Output directory for saved media").option("-t, --timeout <ms>", "Timeout in milliseconds (default: 30000)").option("--raw", "Print the full result object including metadata").allowUnknownOption().action(
+program.command("call").argument("<tool>", "Tool name to call").argument("[json_args]", "JSON arguments for the tool").argument("[target_command...]", "Target server command (after --)").description("Call a tool on a target MCP server and print the result as JSON").option("-o, --out-dir <path>", "Output directory for saved media").option("-t, --timeout <ms>", "Timeout in milliseconds (default: 30000)").option(
+  "-m, --media-threshold <kb>",
+  "Media size threshold in KB to save to disk (0 to always save, -1 to keep inline)"
+).option("--raw", "Print the full result object including metadata").option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(
   async (tool, jsonArgs, targetCommand, opts) => {
+    const operation = { type: "call", tool, args: jsonArgs };
+    const parsedOpts = parseHeadlessOpts(opts);
+    if (opts.session) {
+      await handleHeadlessSession(
+        opts.session,
+        targetCommand,
+        operation,
+        parsedOpts,
+        "run-mcp call <tool> [json_args] -- <server_command...>"
+      );
+    } else {
+      const target = requireTargetCommand(
+        activeTargetCommand ?? targetCommand,
+        "run-mcp call <tool> [json_args] -- <server_command...>"
+      );
+      await runHeadless(target, operation, parsedOpts);
+    }
+  }
+);
+program.command("list-tools").argument("[target_command...]", "Target server command (after --)").description("List all tools on a target MCP server as JSON").option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(async (targetCommand, opts) => {
+  const operation = { type: "list-tools" };
+  const parsedOpts = parseHeadlessOpts(opts);
+  if (opts.session) {
+    await handleHeadlessSession(
+      opts.session,
+      targetCommand,
+      operation,
+      parsedOpts,
+      "run-mcp list-tools -- <server_command...>"
+    );
+  } else {
     const target = requireTargetCommand(
+      activeTargetCommand ?? targetCommand,
+      "run-mcp list-tools -- <server_command...>"
+    );
+    await runHeadless(target, operation, parsedOpts);
+  }
+});
+program.command("list-resources").argument("[target_command...]", "Target server command (after --)").description("List all resources on a target MCP server as JSON").option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(async (targetCommand, opts) => {
+  const operation = { type: "list-resources" };
+  const parsedOpts = parseHeadlessOpts(opts);
+  if (opts.session) {
+    await handleHeadlessSession(
+      opts.session,
       targetCommand,
-      "run-mcp call <tool> [json_args] -- <server_command...>"
+      operation,
+      parsedOpts,
+      "run-mcp list-resources -- <server_command...>"
+    );
+  } else {
+    const target = requireTargetCommand(
+      activeTargetCommand ?? targetCommand,
+      "run-mcp list-resources -- <server_command...>"
     );
-    await runHeadless(target, { type: "call", tool, args: jsonArgs }, parseHeadlessOpts(opts));
+    await runHeadless(target, operation, parsedOpts);
   }
-);
-program.command("list-tools").argument("[target_command...]", "Target server command (after --)").description("List all tools on a target MCP server as JSON").allowUnknownOption().action(async (targetCommand) => {
-  const target = requireTargetCommand(targetCommand, "run-mcp list-tools -- <server_command...>");
-  await runHeadless(target, { type: "list-tools" });
 });
-program.command("list-resources").argument("[target_command...]", "Target server command (after --)").description("List all resources on a target MCP server as JSON").allowUnknownOption().action(async (targetCommand) => {
-  const target = requireTargetCommand(
-    targetCommand,
-    "run-mcp list-resources -- <server_command...>"
-  );
-  await runHeadless(target, { type: "list-resources" });
+program.command("list-prompts").argument("[target_command...]", "Target server command (after --)").description("List all prompts on a target MCP server as JSON").option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(async (targetCommand, opts) => {
+  const operation = { type: "list-prompts" };
+  const parsedOpts = parseHeadlessOpts(opts);
+  if (opts.session) {
+    await handleHeadlessSession(
+      opts.session,
+      targetCommand,
+      operation,
+      parsedOpts,
+      "run-mcp list-prompts -- <server_command...>"
+    );
+  } else {
+    const target = requireTargetCommand(
+      activeTargetCommand ?? targetCommand,
+      "run-mcp list-prompts -- <server_command...>"
+    );
+    await runHeadless(target, operation, parsedOpts);
+  }
 });
-program.command("list-prompts").argument("[target_command...]", "Target server command (after --)").description("List all prompts on a target MCP server as JSON").allowUnknownOption().action(async (targetCommand) => {
-  const target = requireTargetCommand(
-    targetCommand,
-    "run-mcp list-prompts -- <server_command...>"
-  );
-  await runHeadless(target, { type: "list-prompts" });
+program.command("read").argument("<uri>", "Resource URI to read").argument("[target_command...]", "Target server command (after --)").description("Read a resource by URI from a target MCP server").option(
+  "-m, --media-threshold <kb>",
+  "Media size threshold in KB to save to disk (0 to always save, -1 to keep inline)"
+).option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(async (uri, targetCommand, opts) => {
+  const operation = { type: "read", uri };
+  const parsedOpts = parseHeadlessOpts(opts);
+  if (opts.session) {
+    await handleHeadlessSession(
+      opts.session,
+      targetCommand,
+      operation,
+      parsedOpts,
+      "run-mcp read <uri> -- <server_command...>"
+    );
+  } else {
+    const target = requireTargetCommand(
+      activeTargetCommand ?? targetCommand,
+      "run-mcp read <uri> -- <server_command...>"
+    );
+    await runHeadless(target, operation, parsedOpts);
+  }
 });
-program.command("read").argument("<uri>", "Resource URI to read").argument("[target_command...]", "Target server command (after --)").description("Read a resource by URI from a target MCP server").allowUnknownOption().action(async (uri, targetCommand) => {
-  const target = requireTargetCommand(targetCommand, "run-mcp read <uri> -- <server_command...>");
-  await runHeadless(target, { type: "read", uri });
+program.command("describe").argument("<tool>", "Tool name to describe").argument("[target_command...]", "Target server command (after --)").description("Print a tool's full schema as JSON").option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(async (tool, targetCommand, opts) => {
+  const operation = { type: "describe", tool };
+  const parsedOpts = parseHeadlessOpts(opts);
+  if (opts.session) {
+    await handleHeadlessSession(
+      opts.session,
+      targetCommand,
+      operation,
+      parsedOpts,
+      "run-mcp describe <tool> -- <server_command...>"
+    );
+  } else {
+    const target = requireTargetCommand(
+      activeTargetCommand ?? targetCommand,
+      "run-mcp describe <tool> -- <server_command...>"
+    );
+    await runHeadless(target, operation, parsedOpts);
+  }
 });
-program.command("describe").argument("<tool>", "Tool name to describe").argument("[target_command...]", "Target server command (after --)").description("Print a tool's full schema as JSON").allowUnknownOption().action(async (tool, targetCommand) => {
-  const target = requireTargetCommand(
-    targetCommand,
-    "run-mcp describe <tool> -- <server_command...>"
-  );
-  await runHeadless(target, { type: "describe", tool });
+program.command("get-prompt").argument("<name>", "Prompt name").argument("[json_args]", "JSON arguments for the prompt").argument("[target_command...]", "Target server command (after --)").description("Get a prompt with optional arguments from a target MCP server").option(
+  "-m, --media-threshold <kb>",
+  "Media size threshold in KB to save to disk (0 to always save, -1 to keep inline)"
+).option("--show-stderr", "Stream target server stderr to process stderr").option("--session <name>", "Persistent session name").allowUnknownOption().action(
+  async (name, jsonArgs, targetCommand, opts) => {
+    const operation = { type: "get-prompt", name, args: jsonArgs };
+    const parsedOpts = parseHeadlessOpts(opts);
+    if (opts.session) {
+      await handleHeadlessSession(
+        opts.session,
+        targetCommand,
+        operation,
+        parsedOpts,
+        "run-mcp get-prompt <name> [json_args] -- <server_command...>"
+      );
+    } else {
+      const target = requireTargetCommand(
+        activeTargetCommand ?? targetCommand,
+        "run-mcp get-prompt <name> [json_args] -- <server_command...>"
+      );
+      await runHeadless(target, operation, parsedOpts);
+    }
+  }
+);
+program.command("daemon").argument("<session_name>", "Session name").argument("[target_command...]", "Target server command").description("Start run-mcp in background session daemon mode").allowUnknownOption().action(async (sessionName, targetCommand) => {
+  const targetCmd = activeTargetCommand ?? targetCommand;
+  if (!targetCmd || targetCmd.length === 0) {
+    process.stderr.write("Error: No target command provided for daemon.\n");
+    process.exit(1);
+  }
+  const server = createServer();
+  server.listen(0, "127.0.0.1", async () => {
+    const addr = server.address();
+    const port = addr.port;
+    const target = new TargetManager(targetCmd[0], targetCmd.slice(1));
+    const interceptor = new ResponseInterceptor();
+    try {
+      await target.connect();
+    } catch (err) {
+      process.stderr.write(`Daemon failed to connect to target: ${err.message}
+`);
+      process.exit(1);
+    }
+    await mkdir2(SESSION_DIR, { recursive: true });
+    await writeFile2(
+      getSessionPath(sessionName),
+      JSON.stringify({ port, pid: process.pid }),
+      "utf8"
+    );
+    server.on("connection", (socket) => {
+      let buffer = "";
+      socket.on("data", async (data) => {
+        buffer += data.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            const req = JSON.parse(trimmed);
+            if (req.method === "execute") {
+              const { operation, opts } = req.params;
+              const { result, hasError } = await executeOperation(
+                target,
+                interceptor,
+                operation,
+                opts
+              );
+              socket.write(
+                JSON.stringify({ jsonrpc: "2.0", result: { result, hasError }, id: req.id }) + "\n"
+              );
+              socket.end();
+            } else if (req.method === "close") {
+              socket.write(
+                JSON.stringify({ jsonrpc: "2.0", result: { ok: true }, id: req.id }) + "\n"
+              );
+              socket.end();
+              await target.close().catch(() => {
+              });
+              await rm(getSessionPath(sessionName), { force: true }).catch(() => {
+              });
+              process.exit(0);
+            }
+          } catch (err) {
+            socket.write(
+              JSON.stringify({ jsonrpc: "2.0", error: { message: err.message }, id: 1 }) + "\n"
+            );
+            socket.end();
+          }
+        }
+      });
+    });
+  });
 });
-program.command("get-prompt").argument("<name>", "Prompt name").argument("[json_args]", "JSON arguments for the prompt").argument("[target_command...]", "Target server command (after --)").description("Get a prompt with optional arguments from a target MCP server").allowUnknownOption().action(async (name, jsonArgs, targetCommand) => {
-  const target = requireTargetCommand(
-    targetCommand,
-    "run-mcp get-prompt <name> [json_args] -- <server_command...>"
-  );
-  await runHeadless(target, { type: "get-prompt", name, args: jsonArgs });
+program.command("close-session").argument("<session_name>", "Session name").description("Stop a running session daemon").action(async (sessionName) => {
+  const session = await getSession(sessionName);
+  if (!session) {
+    console.log(`Session "${sessionName}" is not running.`);
+    return;
+  }
+  try {
+    await sendDaemonRequest(session.port, {
+      jsonrpc: "2.0",
+      method: "close",
+      params: {},
+      id: 1
+    });
+    console.log(`Session "${sessionName}" stopped successfully.`);
+  } catch {
+    try {
+      process.kill(session.pid, "SIGTERM");
+      console.log(`Session "${sessionName}" stopped (SIGTERM).`);
+    } catch {
+      console.log(`Failed to stop session "${sessionName}".`);
+    }
+  }
 });
-program.name("run-mcp").description("A smart interactive REPL and live test harness for MCP servers").version("1.6.0").passThroughOptions().allowUnknownOption().argument(
+program.name("run-mcp").description("A smart interactive REPL and live test harness for MCP servers").version("1.6.1").passThroughOptions().allowUnknownOption().argument(
   "[target_command...]",
   "Command to spawn the target MCP server (starts REPL if provided, Agent server otherwise)"
 ).option("-o, --out-dir <path>", "Directory to save intercepted images and audio").option(
@@ -3798,16 +4741,19 @@ program.name("run-mcp").description("A smart interactive REPL and live test harn
 ).option(
   "--max-text <chars>",
   "Max text response length before truncation (default: 50000) (Agent Mode only)"
+).option(
+  "-m, --media-threshold <kb>",
+  "Media size threshold in KB to save to disk (0 to always save, -1 to keep inline)"
 ).option("--mcp", "Force start Agent Server mode even if run interactively without arguments").option("-s, --script <file>", "Read commands from a file instead of stdin (REPL Mode only)").addHelpText(
   "after",
   `
 Examples:
   $ run-mcp                                       # Test harness (agent mode)
-  $ run-mcp node my-server.js                     # Interactive testing (human REPL mode)
-  $ run-mcp node my-server.js -s test.txt         # Run a script in REPL mode
-  $ run-mcp npx -y some-mcp-server                # Test an npx server
+  $ run-mcp -- node my-server.js                  # Interactive testing (human REPL mode)
+  $ run-mcp -s test.txt -- node my-server.js      # Run a script in REPL mode
+  $ run-mcp -- npx -y some-mcp-server             # Test an npx server
   $ run-mcp --out-dir ./test-output               # Agent mode with options
-  $ run-mcp --out-dir ./screenshots node srv.js   # REPL mode with options
+  $ run-mcp --out-dir ./screenshots -- node srv.js # REPL mode with options
 
 Headless Commands (pipe-friendly, JSON output):
   $ run-mcp call echo '{"text":"hi"}' -- node my-server.js
@@ -3863,14 +4809,26 @@ REPL Mode Commands (once connected):
 Shortcuts: tl td tc ts rl rr rt rs ru pl pg (see help for details)`
 ).action(
   async (targetCommand, opts) => {
-    if (targetCommand && targetCommand.length > 0) {
-      await startRepl(targetCommand, { script: opts.script, outDir: opts.outDir });
+    if (targetCommand && targetCommand.length > 0 && !activeTargetCommand) {
+      process.stderr.write(
+        "Error: Target server command must be separated by '--'.\nThis avoids argument parsing ambiguity.\n\nExample:\n  run-mcp -- node my-server.js\n  run-mcp -s script.txt -- node my-server.js\n"
+      );
+      process.exit(1);
+    }
+    const target = activeTargetCommand ?? [];
+    if (target && target.length > 0) {
+      await startRepl(target, {
+        script: opts.script,
+        outDir: opts.outDir,
+        mediaThresholdKb: opts.mediaThreshold ? Number.parseInt(opts.mediaThreshold, 10) : void 0
+      });
     } else {
       if (opts.mcp || !process.stdin.isTTY) {
         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
+          maxTextLength: opts.maxText ? Number.parseInt(opts.maxText, 10) : void 0,
+          mediaThresholdKb: opts.mediaThreshold ? Number.parseInt(opts.mediaThreshold, 10) : void 0
         });
       } else {
         const selected = await pickDiscoveredServer();
@@ -3883,10 +4841,11 @@ Shortcuts: tl td tc ts rl rr rt rs ru pl pg (see help for details)`
         }
         await startRepl([selected.config.command, ...selected.config.args || []], {
           script: opts.script,
-          outDir: opts.outDir
+          outDir: opts.outDir,
+          mediaThresholdKb: opts.mediaThreshold ? Number.parseInt(opts.mediaThreshold, 10) : void 0
         });
       }
     }
   }
 );
-program.parse();
+program.parse(argvToParse);