@wrongstack/mcp 1.0.10 → 1.0.11

package/dist/index.js

@@ -5,6 +5,14 @@ import * as http from "node:http";
 import * as https from "node:https";
 import * as net from "node:net";
 import { isPrivateIPv4, isPrivateIPv6 } from "@wrongstack/core/utils";
+var MCPOAuthHttpError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+  status;
+  name = "MCPOAuthHttpError";
+};
 function canonicalMcpResource(rawUrl) {
   let url;
   try {
@@ -299,7 +307,8 @@ async function exchangeMcpAuthorizationCode(options) {
     timeoutMs: options.timeoutMs,
     maxResponseBytes: options.maxResponseBytes,
     lookup: options.lookup,
-    allowedLoopbackHostname: loopbackHostnameForResource(resource)
+    allowedLoopbackHostname: loopbackHostnameForResource(resource),
+    label: "token endpoint"
   });
   if (response === void 0) throw new Error("MCP OAuth token endpoint returned no response");
   return parseTokenResponse(response, resource);
@@ -321,7 +330,8 @@ async function refreshMcpAccessToken(options) {
     timeoutMs: options.timeoutMs,
     maxResponseBytes: options.maxResponseBytes,
     lookup: options.lookup,
-    allowedLoopbackHostname: loopbackHostnameForResource(resource)
+    allowedLoopbackHostname: loopbackHostnameForResource(resource),
+    label: "token endpoint"
   });
   if (response === void 0) throw new Error("MCP OAuth token endpoint returned no response");
   const parsed = parseTokenResponse(response, resource);
@@ -412,7 +422,8 @@ async function discoverFirst(candidates, fetchJson, signal, parse, label) {
   throw new Error(`MCP ${label} discovery failed (${failures.join("; ")})`);
 }
 async function requestPinnedJson(rawUrl, options) {
-  const url = secureOAuthUrl(rawUrl, "discovery URL");
+  const label = options.label ?? "discovery";
+  const url = secureOAuthUrl(rawUrl, `${label} URL`);
   const target = await resolvePinnedAddress(url, options);
   const timeoutMs = options.timeoutMs ?? 1e4;
   const maxBytes = options.maxResponseBytes ?? 64 * 1024;
@@ -456,12 +467,12 @@ async function requestPinnedJson(rawUrl, options) {
       }
       if (status >= 300 && status < 400) {
         response.resume();
-        finish(new Error("MCP OAuth discovery redirects are not allowed"));
+        finish(new Error(`MCP OAuth ${label} redirects are not allowed`));
         return;
       }
       if (status < 200 || status >= 300) {
         response.resume();
-        finish(new Error(`MCP OAuth discovery HTTP ${status}`));
+        finish(new MCPOAuthHttpError(`MCP OAuth ${label} HTTP ${status}`, status));
         return;
       }
       const contentType = response.headers["content-type"] ?? "";
@@ -1127,6 +1138,34 @@ function parseGetPromptResult(value) {
 }
 
 // src/tool-schema.ts
+var MAX_TOOL_PAGES = 100;
+var MAX_TOOLS = 1e4;
+async function listAllTools(requestPage) {
+  const tools = [];
+  const seenCursors = /* @__PURE__ */ new Set();
+  let cursor;
+  for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+    let response;
+    try {
+      response = await requestPage(cursor ? { cursor } : {});
+    } catch (err) {
+      if (page === 0) throw err;
+      break;
+    }
+    if (response.error) {
+      if (page === 0) return null;
+      break;
+    }
+    const result = response.result;
+    tools.push(...normalizeMCPTools(result?.tools));
+    const next = result?.nextCursor;
+    if (typeof next !== "string" || next.length === 0) break;
+    if (seenCursors.has(next) || tools.length >= MAX_TOOLS) break;
+    seenCursors.add(next);
+    cursor = next;
+  }
+  return tools.slice(0, MAX_TOOLS);
+}
 function normalizeMCPTools(value) {
   if (!Array.isArray(value)) return [];
   const tools = [];
@@ -1164,6 +1203,20 @@ var SSE_READER_MAX_DATA_LINES = 1024;
 var SSEReader = class {
   buffer = "";
   dataLines = [];
+  eventName = "";
+  endpointListeners = [];
+  /**
+   * Legacy HTTP+SSE transport: the server's first event is
+   * `event: endpoint` whose data is the (relative) URL to POST requests to.
+   * Its payload is a URL, not JSON, so it is dispatched separately.
+   */
+  onEndpoint(cb) {
+    this.endpointListeners.push(cb);
+    return () => {
+      const idx = this.endpointListeners.indexOf(cb);
+      if (idx >= 0) this.endpointListeners.splice(idx, 1);
+    };
+  }
   listeners = [];
   onMessage(cb) {
     this.listeners.push(cb);
@@ -1216,6 +1269,7 @@ var SSEReader = class {
     let value = colonIdx === -1 ? "" : line.slice(colonIdx + 1);
     if (value.startsWith(" ")) value = value.slice(1);
     if (field === "event") {
+      this.eventName = value;
     } else if (field === "data") {
       if (this.dataLines.length >= SSE_READER_MAX_DATA_LINES) {
         throw new ToolError({
@@ -1233,12 +1287,23 @@ var SSEReader = class {
     }
   }
   flush() {
+    const eventName = this.eventName;
+    this.eventName = "";
     if (this.dataLines.length === 0) {
       return;
     }
     const data = this.dataLines.join("\n").trim();
     this.dataLines = [];
     if (!data) return;
+    if (eventName === "endpoint") {
+      for (const cb of this.endpointListeners) {
+        try {
+          cb(data);
+        } catch {
+        }
+      }
+      return;
+    }
     try {
       const parsed = JSON.parse(data);
       this.dispatch(parsed);
@@ -1256,7 +1321,9 @@ var SSEReader = class {
   reset() {
     this.buffer = "";
     this.dataLines = [];
+    this.eventName = "";
     this.listeners = [];
+    this.endpointListeners = [];
   }
 };
 
@@ -1688,6 +1755,11 @@ var BaseHTTPTransport = class {
 
 // src/transport-jsonrpc.ts
 import { ToolError as ToolError2 } from "@wrongstack/core/types";
+function encodeJsonRpcMessage(id, method, params) {
+  return JSON.stringify(
+    method.startsWith("notifications/") ? { jsonrpc: "2.0", method, params } : { jsonrpc: "2.0", id, method, params }
+  );
+}
 function isJsonRpcResult(v) {
   if (typeof v !== "object" || v === null) return false;
   const r = v;
@@ -1813,11 +1885,20 @@ async function readBodyCapped(res, maxBytes = MAX_MCP_HTTP_BODY_BYTES) {
 }
 
 // src/transport-sse.ts
+var ENDPOINT_WAIT_MS = 1e3;
+var SESSION_FATAL_HTTP_STATUSES = /* @__PURE__ */ new Set([401, 403, 404, 410]);
 var SSETransport = class extends BaseHTTPTransport {
   _nextId = 1;
   readerDone = false;
+  closed = false;
   readLoopAbort;
   reader;
+  /** POST target announced by the server's `endpoint` event. */
+  endpointUrl;
+  /** Wakes connect() once the endpoint is known (or will not arrive). */
+  streamSignal;
+  /** Requests whose response is expected over the event stream, keyed by id. */
+  streamPending = /* @__PURE__ */ new Map();
   constructor(opts) {
     super(opts, "SSETransport");
   }
@@ -1829,18 +1910,13 @@ var SSETransport = class extends BaseHTTPTransport {
   /** Refresh tool list when server sends notifications/tools/list_changed. */
   async handleToolsListChanged() {
     try {
-      const res = await this.httpPost("tools/list", {});
-      if (!res.error) {
-        this.tools.splice(
-          0,
-          this.tools.length,
-          ...normalizeMCPTools(res.result?.tools)
-        );
-        for (const cb of this.toolsChangedListeners) {
-          try {
-            cb([...this.tools]);
-          } catch {
-          }
+      const tools = await listAllTools((params) => this.httpPost("tools/list", params));
+      if (!tools) return;
+      this.tools.splice(0, this.tools.length, ...tools);
+      for (const cb of this.toolsChangedListeners) {
+        try {
+          cb([...this.tools]);
+        } catch {
         }
       }
     } catch {
@@ -1848,6 +1924,8 @@ var SSETransport = class extends BaseHTTPTransport {
   }
   async connect() {
     this.readerDone = false;
+    this.closed = false;
+    this.endpointUrl = void 0;
     this.state = "connecting";
     this.serverMetadata = void 0;
     this.abortController = new AbortController();
@@ -1856,7 +1934,7 @@ var SSETransport = class extends BaseHTTPTransport {
     try {
       const sseUrl = this.buildSSEUrl();
       const fetchOpts = {
-        headers: this.headers,
+        headers: { Accept: "text/event-stream", ...this.headers },
         signal
       };
       this.applyTlsAgent(fetchOpts);
@@ -1880,7 +1958,15 @@ var SSETransport = class extends BaseHTTPTransport {
       const textDecoder = new TextDecoder();
       const sseReader = new SSEReader();
       this.readLoopAbort = new AbortController();
+      const streamReady = new Promise((resolve) => {
+        this.streamSignal = resolve;
+      });
+      sseReader.onEndpoint((endpoint) => {
+        this.acceptEndpoint(endpoint);
+        this.streamSignal?.();
+      });
       sseReader.onMessage((msg) => {
+        this.streamSignal?.();
         if (msg.method && !msg.id) {
           if (msg.method === "notifications/tools/list_changed") {
             void this.handleToolsListChanged();
@@ -1889,6 +1975,14 @@ var SSETransport = class extends BaseHTTPTransport {
           } else if (msg.method === "notifications/prompts/list_changed") {
             this.notifyPromptsChanged();
           }
+          return;
+        }
+        if (!msg.method && isJsonRpcResult(msg)) {
+          const pending = this.streamPending.get(msg.id);
+          if (pending) {
+            this.streamPending.delete(msg.id);
+            pending.resolve(msg);
+          }
         }
       });
       const reader = response.body.getReader();
@@ -1896,10 +1990,13 @@ var SSETransport = class extends BaseHTTPTransport {
         cancel: () => reader.cancel(),
         releaseLock: () => reader.releaseLock()
       };
-      this.readSSEBody(reader, textDecoder, sseReader);
+      void this.readSSEBody(reader, textDecoder, sseReader);
+      await this.waitForStream(streamReady, signal);
       const initRes = await this.httpPost("initialize", {
         protocolVersion: MCP_CONSTANTS.PROTOCOL_VERSION,
-        capabilities: { tools: {} },
+        // Client capabilities (roots/sampling/elicitation) — none are offered.
+        // `tools` is a SERVER capability and never belonged here.
+        capabilities: {},
         clientInfo: MCP_CONSTANTS.CLIENT_INFO
       });
       if (initRes.error) {
@@ -1916,13 +2013,8 @@ var SSETransport = class extends BaseHTTPTransport {
         await this.httpPost("notifications/initialized", {});
       } catch {
       }
-      const toolsRes = await this.httpPost("tools/list", {});
-      if (toolsRes.error) {
-        this.tools.splice(0, this.tools.length);
-      } else {
-        const result = toolsRes.result;
-        this.tools.splice(0, this.tools.length, ...normalizeMCPTools(result?.tools));
-      }
+      const tools = await listAllTools((params) => this.httpPost("tools/list", params));
+      this.tools.splice(0, this.tools.length, ...tools ?? []);
       this.state = "connected";
       clearTimeout(startupTimer);
     } catch (err) {
@@ -1930,6 +2022,43 @@ var SSETransport = class extends BaseHTTPTransport {
       this.state = "failed";
       this.abortController.abort();
       throw err;
+    } finally {
+      this.streamSignal = void 0;
+    }
+  }
+  /** Resolve once the stream announced its endpoint, emitted anything, ended, or the cap passed. */
+  async waitForStream(ready, signal) {
+    let timer;
+    let onAbort;
+    try {
+      await Promise.race([
+        ready,
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, Math.min(ENDPOINT_WAIT_MS, this.timeout));
+          timer.unref?.();
+        }),
+        new Promise((resolve) => {
+          onAbort = resolve;
+          signal.addEventListener("abort", onAbort, { once: true });
+        })
+      ]);
+    } finally {
+      clearTimeout(timer);
+      if (onAbort) signal.removeEventListener("abort", onAbort);
+    }
+  }
+  /**
+   * Adopt the server's POST endpoint. It must stay on the configured origin:
+   * a cross-origin endpoint would move every request — Authorization header
+   * included — to a host that never passed configuration review.
+   */
+  acceptEndpoint(endpoint) {
+    try {
+      const next = new URL(endpoint, this.url);
+      if (next.origin !== new URL(this.url).origin) return;
+      validateTransportUrl(next.toString());
+      this.endpointUrl = next.toString();
+    } catch {
     }
   }
   async readSSEBody(reader, decoder, sseReader) {
@@ -1942,12 +2071,21 @@ var SSETransport = class extends BaseHTTPTransport {
       }
     } catch {
     } finally {
+      this.streamSignal?.();
+      this.rejectStreamPending("SSE stream closed");
       if (!this.readerDone && this.state !== "disconnected" && this.state !== "failed") {
         this.state = "disconnected";
         this.notifyDisconnect();
       }
     }
   }
+  rejectStreamPending(reason) {
+    if (this.streamPending.size === 0) return;
+    const err = new Error(`MCP "${this.name}": ${reason}`);
+    const pending = [...this.streamPending.values()];
+    this.streamPending.clear();
+    for (const entry of pending) entry.reject(err);
+  }
   buildSSEUrl() {
     try {
       const url = new URL(this.url);
@@ -1957,12 +2095,37 @@ var SSETransport = class extends BaseHTTPTransport {
       return this.url;
     }
   }
-  async httpPost(method, params, opts) {
+  /** Register interest in a stream-delivered response before the POST goes out. */
+  awaitStreamResponse(id, signal) {
+    const promise = new Promise((resolve, reject) => {
+      const onAbort = () => reject(signal.reason instanceof Error ? signal.reason : new Error("MCP request aborted"));
+      this.streamPending.set(id, {
+        resolve: (result) => {
+          signal.removeEventListener("abort", onAbort);
+          resolve(result);
+        },
+        reject: (err) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(err);
+        }
+      });
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    });
+    promise.catch(() => void 0);
+    return promise;
+  }
+  httpPost(method, params, opts) {
+    return this.postJsonRpc(method, params, this.requestTimeout, opts);
+  }
+  async postJsonRpc(method, params, timeoutMs, opts) {
     const id = this.genId();
-    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    const isNotification = method.startsWith("notifications/");
+    const body = encodeJsonRpcMessage(id, method, params);
     const external = opts?.signal;
     const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
-    const timeoutSignal = createTimeoutSignal(parent, this.requestTimeout);
+    const timeoutSignal = createTimeoutSignal(parent, timeoutMs);
+    const streamed = isNotification ? void 0 : this.awaitStreamResponse(id, timeoutSignal.signal);
     const fetchOpts = {
       method: "POST",
       headers: {
@@ -1974,8 +2137,19 @@ var SSETransport = class extends BaseHTTPTransport {
     };
     this.applyTlsAgent(fetchOpts);
     try {
-      const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
+      let res;
+      try {
+        res = await this.fetchWithAuthorization(
+          this.endpointUrl ?? this.url,
+          fetchOpts,
+          timeoutSignal.signal
+        );
+      } catch (err) {
+        if (!timeoutSignal.signal.aborted) this.markDisconnected();
+        throw err;
+      }
       if (!res.ok) {
+        if (SESSION_FATAL_HTTP_STATUSES.has(res.status)) this.markDisconnected();
         let snippet;
         try {
           snippet = await readBodyCapped(res, MCP_CONSTANTS.REQUEST_LOG_CAP);
@@ -1990,25 +2164,28 @@ var SSETransport = class extends BaseHTTPTransport {
           context: { transport: "sse", url: this.url, status: res.status }
         });
       }
-      if (method.startsWith("notifications/")) {
+      if (isNotification || !streamed) {
         await readBodyCapped(res).catch(() => void 0);
         return { jsonrpc: "2.0", id };
       }
+      let text;
+      try {
+        text = await readBodyCapped(res);
+      } catch (err) {
+        throw invalidResponse(method, this.url, err);
+      }
+      if (res.status === 202 || text.trim() === "") {
+        return await streamed;
+      }
       let data;
       try {
-        data = JSON.parse(await readBodyCapped(res));
+        data = JSON.parse(text);
       } catch (err) {
-        throw new ToolError4({
-          message: `Invalid JSON-RPC response: ${err instanceof Error ? err.message : "parse failed"}`,
-          code: "TOOL_EXECUTION_FAILED",
-          toolName: method,
-          context: { transport: "sse", url: this.url, phase: "parse-json" },
-          cause: err
-        });
+        throw invalidResponse(method, this.url, err);
       }
       return assertMatchingJsonRpcResult(data, id, method);
     } catch (err) {
-      if (external?.aborted && !method.startsWith("notifications/")) {
+      if (external?.aborted && !isNotification) {
         void this.httpPost("notifications/cancelled", {
           requestId: id,
           reason: "client aborted"
@@ -2016,9 +2193,13 @@ var SSETransport = class extends BaseHTTPTransport {
         });
         throw makeAbortError(method);
       }
-      this.markDisconnected();
       throw err;
     } finally {
+      const pending = this.streamPending.get(id);
+      if (pending) {
+        this.streamPending.delete(id);
+        pending.reject(new Error("MCP request settled"));
+      }
       timeoutSignal.dispose();
     }
   }
@@ -2043,73 +2224,16 @@ var SSETransport = class extends BaseHTTPTransport {
   }
   /** Generic JSON-RPC request — used by MCPClient.request() for SSE transports. */
   async request(method, params, timeoutMs, opts) {
-    const id = this.genId();
-    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
-    const external = opts?.signal;
-    const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
-    const timeoutSignal = createTimeoutSignal(parent, timeoutMs ?? this.requestTimeout);
-    const fetchOpts = {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...this.headers
-      },
-      body,
-      signal: timeoutSignal.signal
-    };
-    this.applyTlsAgent(fetchOpts);
-    try {
-      const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
-      if (!res.ok) {
-        throw new ToolError4({
-          message: `HTTP ${res.status}: ${res.statusText}`,
-          code: "TOOL_EXECUTION_FAILED",
-          toolName: method,
-          context: {
-            transport: "sse",
-            url: this.url,
-            status: res.status,
-            statusText: res.statusText
-          }
-        });
-      }
-      if (method.startsWith("notifications/")) {
-        await readBodyCapped(res).catch(() => void 0);
-        return { jsonrpc: "2.0", id };
-      }
-      let data;
-      try {
-        data = JSON.parse(await readBodyCapped(res));
-      } catch (err) {
-        throw new ToolError4({
-          message: `Invalid JSON-RPC response: ${err instanceof Error ? err.message : "parse failed"}`,
-          code: "TOOL_EXECUTION_FAILED",
-          toolName: method,
-          context: { transport: "sse", url: this.url, phase: "parse-json" },
-          cause: err
-        });
-      }
-      const result = assertMatchingJsonRpcResult(data, id, method);
-      return { jsonrpc: "2.0", id, result: result.result, error: result.error };
-    } catch (err) {
-      if (external?.aborted && !method.startsWith("notifications/")) {
-        void this.httpPost("notifications/cancelled", {
-          requestId: id,
-          reason: "client aborted"
-        }).catch(() => {
-        });
-        throw makeAbortError(method);
-      }
-      this.markDisconnected();
-      throw err;
-    } finally {
-      timeoutSignal.dispose();
-    }
+    const result = await this.postJsonRpc(method, params, timeoutMs ?? this.requestTimeout, opts);
+    return { jsonrpc: "2.0", id: result.id, result: result.result, error: result.error };
   }
   async close() {
     this.releasePinnedDispatcher();
-    if (this.state === "disconnected") return;
+    const alreadyClosed = this.closed;
+    this.closed = true;
     this.readerDone = true;
+    this.state = "disconnected";
+    if (alreadyClosed) return;
     this.readLoopAbort?.abort();
     try {
       this.reader?.cancel();
@@ -2120,8 +2244,8 @@ var SSETransport = class extends BaseHTTPTransport {
     } catch {
     }
     this.abortController?.abort();
+    this.rejectStreamPending("transport closed");
     this.disconnectHandlers.splice(0, this.disconnectHandlers.length);
-    this.state = "disconnected";
   }
   markDisconnected() {
     if (this.state === "connected") {
@@ -2130,10 +2254,20 @@ var SSETransport = class extends BaseHTTPTransport {
     }
   }
 };
+function invalidResponse(method, url, err) {
+  return new ToolError4({
+    message: `Invalid JSON-RPC response: ${err instanceof Error ? err.message : "parse failed"}`,
+    code: "TOOL_EXECUTION_FAILED",
+    toolName: method,
+    context: { transport: "sse", url, phase: "parse-json" },
+    cause: err
+  });
+}
 
 // src/transport-streamable.ts
 var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTransport {
   _nextId = 1;
+  closed = false;
   sessionId;
   constructor(opts) {
     super(opts, "StreamableHTTP");
@@ -2164,11 +2298,8 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
   }
   async refreshTools() {
     try {
-      const response = await this.postRaw("tools/list", {});
-      if (response.error) return;
-      const tools = normalizeMCPTools(
-        response.result?.tools
-      );
+      const tools = await listAllTools((params) => this.postRaw("tools/list", params));
+      if (!tools) return;
       this.tools.splice(0, this.tools.length, ...tools);
       for (const listener of this.toolsChangedListeners) {
         try {
@@ -2180,6 +2311,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
     }
   }
   async connect() {
+    this.closed = false;
     this.state = "connecting";
     this.serverMetadata = void 0;
     this.abortController = new AbortController();
@@ -2200,7 +2332,8 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
           method: "initialize",
           params: {
             protocolVersion: MCP_CONSTANTS.PROTOCOL_VERSION,
-            capabilities: { tools: {} },
+            // Client capabilities — none offered (`tools` is a server capability).
+            capabilities: {},
             clientInfo: MCP_CONSTANTS.CLIENT_INFO
           }
         }),
@@ -2230,13 +2363,8 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
       this.protocolVersion = this.serverMetadata.protocolVersion;
       this.sessionId = initRes.headers.get("mcp-session-id") ?? void 0;
       await this.postRaw("notifications/initialized", {});
-      const toolsRes = await this.postRaw("tools/list", {});
-      if (toolsRes.error) {
-        this.tools.splice(0, this.tools.length);
-      } else {
-        const result = toolsRes.result;
-        this.tools.splice(0, this.tools.length, ...normalizeMCPTools(result?.tools));
-      }
+      const tools = await listAllTools((params) => this.postRaw("tools/list", params));
+      this.tools.splice(0, this.tools.length, ...tools ?? []);
       this.state = "connected";
       clearTimeout(startupTimer);
     } catch (err) {
@@ -2248,7 +2376,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
   }
   async postRaw(method, params, opts) {
     const id = this.genId();
-    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    const body = encodeJsonRpcMessage(id, method, params);
     const external = opts?.signal;
     const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
     const timeoutSignal = createTimeoutSignal(parent, this.requestTimeout);
@@ -2298,7 +2426,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
   /** Generic JSON-RPC request — used by MCPClient.request() for SSE/streamable-http transports. */
   async request(method, params, timeoutMs, opts) {
     const id = this.genId();
-    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    const body = encodeJsonRpcMessage(id, method, params);
     const external = opts?.signal;
     const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
     const timeoutSignal = createTimeoutSignal(parent, timeoutMs ?? this.requestTimeout);
@@ -2328,11 +2456,12 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
       }
       const parsed = this.consumeResponseText(await readBodyCapped(res), id);
       if (parsed) {
+        const matched = assertMatchingJsonRpcResult(parsed, id, method);
         return {
           jsonrpc: "2.0",
           id,
-          result: parsed.result,
-          error: parsed.error
+          result: matched.result,
+          error: matched.error
         };
       }
       throw new Error("Could not parse response as JSON-RPC");
@@ -2366,8 +2495,10 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
   }
   async close() {
     this.releasePinnedDispatcher();
-    if (this.state === "disconnected") return;
+    const alreadyClosed = this.closed;
+    this.closed = true;
     this.state = "disconnected";
+    if (alreadyClosed) return;
     this.abortController?.abort();
     this.disconnectHandlers.splice(0, this.disconnectHandlers.length);
   }
@@ -2525,12 +2656,18 @@ var MCPClient = class _MCPClient {
       return spawn2(shim.command, shim.args, {
         env: spawnEnv,
         stdio,
+        ...this.opts.cwd ? { cwd: this.opts.cwd } : {},
         windowsVerbatimArguments: shim.windowsVerbatimArguments,
         // Without this every MCP server spawned from a console-less host
         // (WebUI server, scheduled runs) opens a visible console window.
         windowsHide: true
       });
-    })() : spawn2(this.opts.command, rawArgs, { env: spawnEnv, stdio, windowsHide: true });
+    })() : spawn2(this.opts.command, rawArgs, {
+      env: spawnEnv,
+      stdio,
+      windowsHide: true,
+      ...this.opts.cwd ? { cwd: this.opts.cwd } : {}
+    });
     this.child = child;
     child.stdout?.on("data", (chunk) => this.onData(chunk.toString()));
     child.stdout?.on("end", () => {
@@ -2565,7 +2702,9 @@ var MCPClient = class _MCPClient {
       "initialize",
       {
         protocolVersion: MCP_CONSTANTS.PROTOCOL_VERSION,
-        capabilities: { tools: {} },
+        // Client capabilities (roots/sampling/elicitation) — none offered.
+        // `tools` is a SERVER capability and never belonged here.
+        capabilities: {},
         clientInfo: MCP_CONSTANTS.CLIENT_INFO
       },
       this.opts.startupTimeoutMs ?? 1e4
@@ -2587,13 +2726,7 @@ var MCPClient = class _MCPClient {
         '[MCP] notify("notifications/initialized") failed for "' + this.opts.name + '": ' + toErrorMessage(err)
       );
     }
-    const toolsRes = await this.request("tools/list", {});
-    if (toolsRes.error) {
-      this._tools = [];
-    } else {
-      const result = toolsRes.result;
-      this._tools = normalizeMCPTools(result?.tools);
-    }
+    this._tools = await listAllTools((params) => this.request("tools/list", params)) ?? [];
     this._toolsCache = this._tools;
     this.state = "connected";
   }
@@ -2843,8 +2976,7 @@ var MCPClient = class _MCPClient {
       this.child = void 0;
     }
     this.failPending(`MCP "${this.opts.name}" closed`);
-    this.sseTransport?.close();
-    this.httpTransport?.close();
+    await Promise.allSettled([this.sseTransport?.close(), this.httpTransport?.close()]);
     this.state = "disconnected";
   }
   request(method, params, timeoutMs = this.opts.requestTimeoutMs ?? 6e4, opts) {
@@ -3085,11 +3217,13 @@ var MCPClient = class _MCPClient {
     }
   }
   handleServerRequest(request3) {
-    const message = request3.method === "sampling/createMessage" ? "Client sampling is disabled by policy" : `Method not found: ${request3.method}`;
-    const response = {
+    const response = request3.method === "ping" ? { jsonrpc: "2.0", id: request3.id, result: {} } : {
       jsonrpc: "2.0",
       id: request3.id,
-      error: { code: -32601, message }
+      error: {
+        code: -32601,
+        message: request3.method === "sampling/createMessage" ? "Client sampling is disabled by policy" : `Method not found: ${request3.method}`
+      }
     };
     try {
       this.child?.stdin?.write(`${JSON.stringify(response)}
@@ -3105,10 +3239,8 @@ var MCPClient = class _MCPClient {
    */
   async handleToolsListChanged() {
     try {
-      const toolsRes = await this.request("tools/list", {});
-      const tools = normalizeMCPTools(
-        toolsRes.result?.tools
-      );
+      const tools = await listAllTools((params) => this.request("tools/list", params));
+      if (!tools) return;
       this._tools = tools;
       this._toolsCache = tools;
       for (const listener of this.toolsChangedListeners) {
@@ -3446,7 +3578,7 @@ async function updateMcp(input, deps) {
   servers[input.name] = cfg;
   await persist(deps.configPath, full, servers);
   if (cfg.enabled !== false) {
-    return startServer(input.name, cfg, deps, `Server "${input.name}" updated`, { restart: true });
+    return startServer(input.name, cfg, deps, `Server "${input.name}" updated`);
   }
   await safeStop(input.name, deps);
   trackDisabled(deps.registry, cfg);
@@ -3483,7 +3615,7 @@ async function enableMcp(name, deps) {
   cfg.enabled = true;
   servers[name] = cfg;
   await persist(deps.configPath, full, servers);
-  return startServer(name, cfg, deps, `Server "${name}" enabled`, { restart: true });
+  return startServer(name, cfg, deps, `Server "${name}" enabled`);
 }
 async function disableMcp(name, deps) {
   if (!name) return { ok: false, message: "Server name is required" };
@@ -3526,12 +3658,19 @@ async function restartMcp(name, deps) {
   }
   const cfg = servers[name];
   if (!cfg) return { ok: false, message: `Server "${name}" is not in config.` };
-  return startServer(name, { ...cfg, name }, deps, `Server "${name}" started`, { restart: true });
+  return startServer(name, { ...cfg, name }, deps, `Server "${name}" started`);
 }
 async function discoverMcp(name, deps) {
   if (!name) return { ok: false, message: "Server name is required" };
   const result = await restartMcp(name, deps);
   if (!result.ok) return result;
+  if (liveState(name, deps.registry).state === "dormant") {
+    try {
+      await deps.registry.ensureConnected(name);
+    } catch (err) {
+      return { ok: false, message: `Failed to discover "${name}": ${errMessage(err)}` };
+    }
+  }
   const { state, tools } = liveState(name, deps.registry);
   return {
     ok: true,
@@ -3540,15 +3679,13 @@ async function discoverMcp(name, deps) {
     tools
   };
 }
-async function startServer(name, cfg, deps, okMessage, opts) {
+async function startServer(name, cfg, deps, okMessage) {
   try {
     const alreadyRegistered = deps.registry.list().some((s) => s.name === name);
-    if (alreadyRegistered && opts?.restart) {
-      await deps.registry.restart(name);
-    } else if (alreadyRegistered) {
-      await deps.registry.restart(name);
+    if (alreadyRegistered) {
+      await deps.registry.restart(name, { ...cfg, name, enabled: true });
     } else {
-      await deps.registry.start({ ...cfg, enabled: true });
+      await deps.registry.start({ ...cfg, name, enabled: true });
     }
     const { state, tools } = liveState(name, deps.registry);
     return {
@@ -3905,14 +4042,37 @@ function wrapMCPTool(serverName, mcpTool, client, permission = "confirm", observ
     }
   };
 }
+function renderContentBlock(item) {
+  const type = item["type"];
+  if (type === "text") return typeof item["text"] === "string" ? item["text"] : "";
+  if (type === "image" || type === "audio") {
+    const mime = typeof item["mimeType"] === "string" ? item["mimeType"] : "unknown type";
+    const data = typeof item["data"] === "string" ? item["data"] : "";
+    const kb = Math.max(1, Math.round(data.length * 3 / 4 / 1024));
+    return `[${type} content: ${mime}, ~${kb} KB \u2014 binary payload not inlined]`;
+  }
+  if (type === "resource" && item["resource"] && typeof item["resource"] === "object") {
+    const resource = item["resource"];
+    const uri = typeof resource["uri"] === "string" ? resource["uri"] : "unknown";
+    if (typeof resource["text"] === "string") return `[resource ${uri}]
+${resource["text"]}`;
+    if (typeof resource["blob"] === "string") {
+      const mime = typeof resource["mimeType"] === "string" ? `${resource["mimeType"]}, ` : "";
+      return `[resource ${uri}: ${mime}binary payload not inlined]`;
+    }
+    return JSON.stringify(item);
+  }
+  if (type === "resource_link" && typeof item["uri"] === "string") {
+    return `[resource link: ${item["uri"]}]`;
+  }
+  return JSON.stringify(item);
+}
 function stringify(c) {
   if (typeof c === "string") return c;
   if (Array.isArray(c)) {
     return c.map((item) => {
       if (item && typeof item === "object") {
-        const t = item.type;
-        if (t === "text") return item.text ?? "";
-        return JSON.stringify(item);
+        return renderContentBlock(item);
       }
       return String(item);
     }).join("\n");
@@ -3928,9 +4088,14 @@ function stringify(c) {
 
 // src/registry-connect-loop.ts
 function applySlotTools(ctx, slot, tools, client) {
-  if (slot.lazy && slot.registeredLazy && !ctx.lazyMode) return;
+  slot.discoveredTools = tools;
   const allowed = slot.cfg.allowedTools;
   const filtered = tools.filter((t) => !allowed || allowed.includes(t.name));
+  const signature = JSON.stringify(
+    filtered.map((t) => [t.name, t.description ?? null, t.inputSchema ?? null])
+  );
+  const lazyWrappersCurrent = slot.lazy && slot.toolSignature === signature && slot.lazyTools.length === filtered.length && (slot.registeredLazy || ctx.lazyMode);
+  if (lazyWrappersCurrent) return;
   const clientArg = slot.lazy ? () => ctx.ensureConnected(slot.cfg.name) : expectDefined(client);
   const wrapped = filtered.map(
     (t) => wrapMCPTool(slot.cfg.name, t, clientArg, slot.cfg.permission ?? "confirm", {
@@ -3956,9 +4121,16 @@ function applySlotTools(ctx, slot, tools, client) {
     })
   );
   slot.lazyTools = wrapped;
-  if (ctx.lazyMode) {
-    return;
+  slot.toolSignature = signature;
+  const wasActive = slot.toolNames.length > 0;
+  if (ctx.lazyMode && !wasActive) return;
+  for (const name of slot.toolNames) {
+    try {
+      ctx.toolRegistry.unregister(name);
+    } catch {
+    }
   }
+  slot.toolNames = [];
   for (const tool of wrapped) {
     try {
       ctx.toolRegistry.register(tool, `mcp:${slot.cfg.name}`);
@@ -3967,7 +4139,7 @@ function applySlotTools(ctx, slot, tools, client) {
       ctx.log.warn(`MCP tool "${tool.name}" not registered`, err);
     }
   }
-  if (slot.lazy && wrapped.length > 0) slot.registeredLazy = true;
+  if (slot.lazy && !ctx.lazyMode && wrapped.length > 0) slot.registeredLazy = true;
 }
 async function discoverSlotCapabilities(ctx, slot, client) {
   const startedAt = Date.now();
@@ -4019,15 +4191,17 @@ async function discoverSlotCapabilities(ctx, slot, client) {
 async function persistSlotCapabilityManifest(cacheDir, slot) {
   if (!slot.lazy || !cacheDir) return;
   const previous = slot.manifestWrite ?? Promise.resolve();
-  const pending = previous.then(
-    () => writeCapabilityManifest(cacheDir, slot.cfg.name, manifestConfigHash(slot.cfg), {
-      tools: slot.client?.listTools() ?? [],
+  const pending = previous.then(() => {
+    const tools = slot.discoveredTools ?? slot.client?.listTools();
+    if (!tools) return;
+    return writeCapabilityManifest(cacheDir, slot.cfg.name, manifestConfigHash(slot.cfg), {
+      tools,
       serverMetadata: slot.serverMetadata,
       resources: slot.resources,
       resourceTemplates: slot.resourceTemplates,
       prompts: slot.prompts
-    })
-  );
+    });
+  });
   slot.manifestWrite = pending;
   await pending;
   if (slot.manifestWrite === pending) slot.manifestWrite = void 0;
@@ -4036,7 +4210,7 @@ async function attemptConnectSlot(ctx, slot) {
   const MAX_ATTEMPTS = MCP_CONSTANTS.RECONNECT.MAX_ATTEMPTS;
   let attempt = 0;
   while (attempt < MAX_ATTEMPTS) {
-    if (ctx.servers.has(slot.cfg.name) && ctx.servers.get(slot.cfg.name) !== slot) {
+    if (ctx.servers.get(slot.cfg.name) !== slot) {
       return;
     }
     attempt++;
@@ -4056,6 +4230,7 @@ async function attemptConnectSlot(ctx, slot) {
         headers: slot.cfg.headers,
         startupTimeoutMs: slot.cfg.startupTimeoutMs,
         requestTimeoutMs: slot.cfg.requestTimeoutMs,
+        cwd: ctx.cwd,
         allowPrivateNetworks: slot.cfg.allowPrivateNetworks,
         passthroughEnv: slot.cfg.passthroughEnv,
         authorizationProvider: ctx.authorizationProviderFactory?.(slot.cfg)
@@ -4095,6 +4270,7 @@ async function attemptConnectSlot(ctx, slot) {
       slot.reconnectCycles = 0;
       const mc = client;
       const discovered = mc.listTools();
+      slot.discoveredTools = discovered;
       await discoverSlotCapabilities(ctx, slot, mc);
       await persistSlotCapabilityManifest(ctx.cacheDir, slot);
       applySlotTools(ctx, slot, discovered, mc);
@@ -4150,7 +4326,7 @@ async function attemptConnectSlot(ctx, slot) {
       }
       const delay = 500 * 2 ** attempt;
       await new Promise((r) => setTimeout(r, delay));
-      if (slot.state === "disconnected" || ctx.servers.has(slot.cfg.name) && ctx.servers.get(slot.cfg.name) !== slot) {
+      if (slot.state === "disconnected" || ctx.servers.get(slot.cfg.name) !== slot) {
         return;
       }
     }
@@ -4167,6 +4343,7 @@ function resetDisconnectedSlotTools(slot, toolRegistry) {
   }
   slot.toolNames = [];
   slot.lazyTools = [];
+  slot.toolSignature = void 0;
   slot.serverMetadata = void 0;
   slot.resources = void 0;
   slot.resourceTemplates = void 0;
@@ -4387,6 +4564,7 @@ var MCPRegistry = class _MCPRegistry {
   log;
   lazyMode;
   cacheDir;
+  cwd;
   idleTimeoutMs;
   authorizationProviderFactory;
   authorizationManager;
@@ -4399,6 +4577,7 @@ var MCPRegistry = class _MCPRegistry {
     this.log = opts.log;
     this.lazyMode = opts.lazyMode ?? false;
     this.cacheDir = opts.cacheDir;
+    this.cwd = opts.cwd;
     this.idleTimeoutMs = opts.idleTimeoutMs ?? MCP_CONSTANTS.IDLE.DEFAULT_TIMEOUT_MS;
     this.authorizationProviderFactory = opts.authorizationProviderFactory;
     this.authorizationManager = opts.authorizationManager;
@@ -4558,7 +4737,6 @@ var MCPRegistry = class _MCPRegistry {
       }
     }
     this.log.info(`MCP server "${name}" activated (${slot.toolNames.length} tools)`);
-    this.events.emit("mcp.server.connected", { name, toolCount: slot.toolNames.length });
   }
   /**
    * Unregister all tools for a given server from the tool registry.
@@ -4578,9 +4756,27 @@ var MCPRegistry = class _MCPRegistry {
     }
     slot.toolNames = [];
     this.log.info(`MCP server "${name}" deactivated (${count} tools removed)`);
-    this.events.emit("mcp.server.disconnected", { name, reason: "deactivate" });
     return count;
   }
+  /**
+   * The tools a server offers — bare names, descriptions and input schemas —
+   * without activating, registering or waking it. In token-saving mode the
+   * model reaches MCP only through `mcp_use`, which needs the bare tool name
+   * and its input shape; before this there was no way to learn either short
+   * of guessing and reading the error. Honors `allowedTools`. Returns
+   * `undefined` for an unknown server, `[]` when nothing was discovered yet.
+   */
+  describeTools(name) {
+    const slot = this.servers.get(name);
+    if (!slot) return void 0;
+    const allowed = slot.cfg.allowedTools;
+    const tools = slot.discoveredTools ?? slot.client?.listTools() ?? [];
+    return tools.filter((tool) => !allowed || allowed.includes(tool.name)).map((tool) => ({
+      name: tool.name,
+      ...tool.description !== void 0 ? { description: tool.description } : {},
+      inputSchema: structuredClone(tool.inputSchema)
+    }));
+  }
   /**
    * Check whether a server's tools are currently registered.
    */
@@ -4617,12 +4813,52 @@ var MCPRegistry = class _MCPRegistry {
     this.recordOperation(slot, "stop", "manual");
     this.events.emit("mcp.server.disconnected", { name, reason: "stop" });
   }
-  async restart(name) {
+  /**
+   * Stop and start a registered server. Pass `nextCfg` to apply an edited
+   * configuration: without it the slot reconnects with the config it was
+   * started with, so an update/enable routed through restart() silently kept
+   * the old command, url, env, permission and lazy flag until the next boot.
+   */
+  /**
+   * Put a running server to sleep while keeping its configuration enabled.
+   *
+   * A lazy server goes `dormant`: the process stops but its tools stay
+   * registered and the next call wakes it. Surfaces previously used stop() for
+   * this, which unregistered a lazy server's tools — "sleep" silently became
+   * "unreachable until restarted". Eager servers have no dormant state, so
+   * for them sleep is a stop.
+   */
+  async sleep(name) {
+    const slot = this.requireSlot(name);
+    if (!slot.lazy) {
+      await this.stop(name);
+      return;
+    }
+    if (slot.state === "dormant") return;
+    if (slot.operations.inFlightCalls > 0) {
+      throw new Error(`MCP server "${name}" has tool calls in flight \u2014 try again when they finish`);
+    }
+    await sleepIdleSlot(this.idleContext(), slot);
+  }
+  async restart(name, nextCfg) {
     const slot = this.servers.get(name);
     if (!slot) throw new Error(`MCP server "${name}" not registered`);
+    if (nextCfg && nextCfg.name !== name) {
+      throw new Error(`MCP restart config names "${nextCfg.name}", expected "${name}"`);
+    }
+    if (nextCfg?.enabled === false) {
+      await this.stop(name);
+      this.markDisabled(nextCfg);
+      return;
+    }
     slot.operations.restartCount++;
     this.recordOperation(slot, "restart", "manual");
     await this.stop(name);
+    if (nextCfg) {
+      slot.cfg = nextCfg;
+      slot.lazy = !!nextCfg.lazy && !!this.cacheDir;
+      slot.discoveredTools = void 0;
+    }
     slot.attempts = 0;
     slot.reconnectCycles = 0;
     if (slot.lazy) {
@@ -4744,6 +4980,7 @@ var MCPRegistry = class _MCPRegistry {
       log: this.log,
       lazyMode: this.lazyMode,
       cacheDir: this.cacheDir,
+      cwd: this.cwd,
       authorizationProviderFactory: this.authorizationProviderFactory,
       operationListeners: this.operationListeners,
       ensureConnected: (name) => this.ensureConnected(name),
@@ -4855,21 +5092,9 @@ var MCPRegistry = class _MCPRegistry {
   onToolsChanged = (name, _tools) => {
     const slot = this.servers.get(name);
     if (!slot?.client) return;
-    for (const t of slot.toolNames) {
-      try {
-        this.toolRegistry.unregister(t);
-      } catch {
-      }
-    }
-    slot.toolNames = [];
-    slot.registeredLazy = false;
     const discovered = slot.client.listTools();
     this.applyTools(slot, discovered, slot.client);
     void this.persistCapabilityManifest(slot);
-    this.events.emit("mcp.server.connected", {
-      name: slot.cfg.name,
-      toolCount: slot.toolNames.length
-    });
     this.log.info(
       `MCP server "${slot.cfg.name}" tools refreshed (${this.toolNamesForSlot(slot).length} active)`
     );
@@ -4899,7 +5124,7 @@ var MCPRegistry = class _MCPRegistry {
   }
   onChildExit = (name, code, _signal) => {
     const slot = this.servers.get(name);
-    if (!slot) return;
+    if (slot?.state !== "connected") return;
     if (slot.lazy) {
       this.recordFailure(slot, "transport", "process-exit-lazy");
       markLazySlotDormant(slot, this.events, `exit:${code ?? "unknown"}`, {
@@ -4918,7 +5143,7 @@ var MCPRegistry = class _MCPRegistry {
   /** Handles SSE / streamable-http disconnect — same recovery as stdio child exit. */
   onTransportDisconnect = (name) => {
     const slot = this.servers.get(name);
-    if (!slot) return;
+    if (slot?.state !== "connected") return;
     if (slot.lazy) {
       this.recordFailure(slot, "transport", "http-disconnect-lazy");
       markLazySlotDormant(slot, this.events, "http-disconnect", {
@@ -4954,7 +5179,7 @@ var MCPRegistry = class _MCPRegistry {
     slot.reconnectCycles++;
     slot.operations.reconnectCount++;
     this.recordOperation(slot, "reconnect", "automatic");
-    await this.attemptConnect(slot);
+    await this.singleFlightConnect(slot);
   }
   recordSuccess(slot, resetFailures = true) {
     recordRegistrySuccess(slot, resetFailures);
@@ -5639,6 +5864,8 @@ var MCPRefreshingAuthorizationProvider = class {
   }
   options;
   refreshPromise;
+  /** Refresh token the authorization server rejected; cleared by a new authorization. */
+  rejectedRefreshToken;
   resource;
   refreshSkewMs;
   async getAccessToken(context) {
@@ -5676,16 +5903,28 @@ var MCPRefreshingAuthorizationProvider = class {
   }
   async refreshInner(state) {
     const refreshToken = state.tokenSet.refreshToken;
-    if (!refreshToken) {
-      this.emit("reauth_required", state);
+    if (!refreshToken || refreshToken === this.rejectedRefreshToken) {
+      if (!refreshToken) this.emit("reauth_required", state);
       return void 0;
     }
-    const tokenSet = await refreshMcpAccessToken({
-      authorizationServer: state.authorizationServer,
-      clientId: state.clientId,
-      resource: state.resource,
-      refreshToken
-    });
+    let tokenSet;
+    try {
+      tokenSet = await refreshMcpAccessToken({
+        authorizationServer: state.authorizationServer,
+        clientId: state.clientId,
+        resource: state.resource,
+        refreshToken
+      });
+    } catch (err) {
+      const current = await this.options.store.load(this.options.serverName, this.resource).catch(() => void 0);
+      if (current && current.tokenSet.refreshToken !== refreshToken) return current;
+      if (err instanceof MCPOAuthHttpError && err.status >= 400 && err.status < 500) {
+        this.rejectedRefreshToken = refreshToken;
+        this.emit("reauth_required", state);
+        return void 0;
+      }
+      throw err;
+    }
     const next = normalizeStoredAuthorization({
       ...state,
       tokenSet,