@wrongstack/mcp 0.319.1 → 1.0.0

package/dist/client.d.ts

@@ -23,6 +23,12 @@ export interface MCPClientOptions {
      * without storing them in config.json or being scrubbed by the secret filter.
      */
     passthroughEnv?: string[] | undefined;
+    /**
+     * Resolution-bound private-network policy for HTTP transports. Default:
+     * private/LAN targets are blocked at dial time (DNS-rebinding safe); the
+     * flag opts this server in. See MCPServerConfig.allowPrivateNetworks.
+     */
+    allowPrivateNetworks?: boolean | undefined;
 }
 import type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult } from './contracts.js';
 export type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult };
@@ -56,6 +62,7 @@ export declare class MCPClient {
      */
     private readonly pending;
     private rxBuffer;
+    private rxBufferBytes;
     private _tools;
     /** Server-declared handshake metadata. Populated for stdio in the first protocol slice. */
     private _serverMetadata?;
@@ -63,6 +70,7 @@ export declare class MCPClient {
     private _toolsCache?;
     private _drainPending;
     private _lastNotifySkipped;
+    private closePromise?;
     private sseTransport?;
     private httpTransport?;
     /** Notified when the stdio child process exits so the registry can attempt reconnect. */
@@ -106,6 +114,7 @@ export declare class MCPClient {
     listPrompts(opts?: MCPPageOptions): Promise<MCPListPromptsResult>;
     getPrompt(name: string, args?: Record<string, string> | undefined, opts?: MCPRequestOptions): Promise<MCPGetPromptResult>;
     close(): Promise<void>;
+    private closeInner;
     private request;
     private requestCapability;
     private requireResourceSubscriptions;

package/dist/index.js

@@ -516,8 +516,8 @@ async function resolvePinnedAddress(url, options) {
     );
     return { address: hostname, family: literalFamily };
   }
-  const lookup2 = options.lookup ?? ((host) => dns.lookup(host, { all: true }));
-  const records = await lookup2(hostname);
+  const lookup3 = options.lookup ?? ((host) => dns.lookup(host, { all: true }));
+  const records = await lookup3(hostname);
   if (records.length === 0)
     throw new Error(`MCP OAuth discovery DNS returned no addresses for ${hostname}`);
   for (const record3 of records) {
@@ -1256,10 +1256,13 @@ var SSEReader = class {
 // src/transport-base.ts
 import * as https2 from "node:https";
 import { ConfigError as ConfigError2 } from "@wrongstack/core/types";
+import { Agent as UndiciAgent, fetch as undiciFetch } from "undici";
 
 // src/transport-security.ts
+import * as dns2 from "node:dns/promises";
 import * as net2 from "node:net";
 import { ConfigError } from "@wrongstack/core/types";
+import { isPrivateIPv4 as isPrivateIPv42, isPrivateIPv6 as isPrivateIPv62 } from "@wrongstack/core/utils";
 function isTlsUnsafeAllowed() {
   return process.env["WRONGSTACK_UNSAFE_MCP_TLS"] === "1";
 }
@@ -1315,9 +1318,108 @@ function validateTransportUrl(rawUrl) {
     }
   }
 }
+var ALLOW_MCP_PRIVATE_NETWORKS = process.env["WRONGSTACK_MCP_ALLOW_PRIVATE"] === "1";
+if (ALLOW_MCP_PRIVATE_NETWORKS && !process.env["CI"]) {
+  console.warn(
+    "[WrongStack] WARNING: WRONGSTACK_MCP_ALLOW_PRIVATE=1 is active \u2014\n  MCP HTTP transports may dial private/LAN addresses (10.x, 192.168.x,\n  172.16-31.x, ULA) when a server config sets allowPrivateNetworks. Link-local/IMDS targets stay blocked."
+  );
+}
+function classifyTransportAddress(address, family) {
+  if (family === 4) {
+    const v4 = address.toLowerCase();
+    if (v4.startsWith("169.254.")) return "blocked";
+    if (v4.startsWith("127.")) return "loopback";
+    return isPrivateIPv42(address) ? "private" : "public";
+  }
+  if (family === 6) {
+    const v6 = address.toLowerCase();
+    if (v6 === "::1") return "loopback";
+    if (/^fe[89ab]/.test(v6) || v6 === "fd00:ec2::254") return "blocked";
+    if (v6.startsWith("::ffff:")) {
+      const tail = v6.slice("::ffff:".length);
+      if (tail.includes(".")) return classifyTransportAddress(tail, 4);
+      const hextets = tail.split(":");
+      if (hextets.length === 2) {
+        const high = Number.parseInt(hextets[0], 16);
+        const low = Number.parseInt(hextets[1], 16);
+        if (Number.isFinite(high) && Number.isFinite(low)) {
+          return classifyTransportAddress(
+            `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`,
+            4
+          );
+        }
+      }
+      return "blocked";
+    }
+    return isPrivateIPv62(v6) ? "private" : "public";
+  }
+  return "blocked";
+}
+function assertTransportAddressAllowed(address, family, hostname, allowPrivateNetworks) {
+  const classification = classifyTransportAddress(address, family);
+  if (classification === "blocked") {
+    throw new ConfigError({
+      message: `MCP transport: resolved address "${address}" for "${hostname}" is link-local/IMDS \u2014 never a valid MCP target`,
+      code: "CONFIG_INVALID",
+      context: { hostname, address }
+    });
+  }
+  if (classification === "private" && !allowPrivateNetworks) {
+    throw new ConfigError({
+      message: `MCP transport: "${hostname}" resolved to private address ${address}. Private/LAN targets are blocked by default; if this server really runs on your private network, set allowPrivateNetworks: true on its config (or WRONGSTACK_MCP_ALLOW_PRIVATE=1 globally).`,
+      code: "CONFIG_INVALID",
+      context: { hostname, address }
+    });
+  }
+}
+function transportPinnedLookup(options) {
+  const lookup3 = options.lookup ?? (async (host) => dns2.lookup(host, { all: true }));
+  return (hostname, connectOptions, callback) => {
+    lookup3(hostname).then((records) => {
+      if (records.length === 0) {
+        callback(
+          Object.assign(new Error(`MCP transport: no addresses for "${hostname}"`), {
+            code: "ENOTFOUND"
+          })
+        );
+        return;
+      }
+      for (const record3 of records) {
+        assertTransportAddressAllowed(
+          record3.address,
+          record3.family,
+          hostname,
+          options.allowPrivateNetworks
+        );
+      }
+      const wanted = connectOptions?.family;
+      const filtered = wanted === 4 || wanted === 6 ? records.filter((record3) => record3.family === wanted) : records;
+      const list = filtered.length > 0 ? filtered : records;
+      if (connectOptions?.all) {
+        callback(
+          null,
+          list.map((record3) => ({ address: record3.address, family: record3.family }))
+        );
+        return;
+      }
+      const first = list[0];
+      callback(null, first.address, first.family);
+    }).catch((error) => callback(error));
+  };
+}
 
 // src/transport-base.ts
 var MAX_TRANSPORT_REDIRECTS = 5;
+var nativeGlobalFetch = globalThis.fetch;
+var pinnedAgents = /* @__PURE__ */ new Set();
+var pinnedAgentsCleanupRegistered = false;
+if (!pinnedAgentsCleanupRegistered) {
+  pinnedAgentsCleanupRegistered = true;
+  process.on("beforeExit", () => {
+    for (const agent of pinnedAgents) agent.destroy();
+    pinnedAgents.clear();
+  });
+}
 function makeAbortError(method) {
   const err = new Error(`MCP request "${method}" aborted by client`);
   err.name = "AbortError";
@@ -1335,6 +1437,7 @@ function createTimeoutSignal(parent, timeoutMs) {
     () => ctrl.abort(new Error(`MCP HTTP request timed out after ${timeoutMs}ms`)),
     timeoutMs
   );
+  timer.unref?.();
   return {
     signal: ctrl.signal,
     dispose: () => {
@@ -1354,6 +1457,10 @@ var BaseHTTPTransport = class {
   authorizationResource;
   /** Per-request TLS agent — created once from HttpTransportOptions.tls */
   tlsAgent;
+  tlsOptions;
+  allowPrivateNetworks;
+  lookup;
+  pinnedAgent;
   tools = [];
   serverMetadata;
   abortController;
@@ -1389,6 +1496,9 @@ var BaseHTTPTransport = class {
         rejectUnauthorized: opts.tls.rejectUnauthorized
       });
     }
+    this.tlsOptions = opts.tls;
+    this.allowPrivateNetworks = opts.allowPrivateNetworks === true || ALLOW_MCP_PRIVATE_NETWORKS;
+    this.lookup = opts.lookup;
   }
   getState() {
     return this.state;
@@ -1414,7 +1524,9 @@ var BaseHTTPTransport = class {
       let currentUrl = typeof input === "string" ? input : String(input);
       let hopHeaders = headers;
       for (let hop = 0; hop < MAX_TRANSPORT_REDIRECTS; hop++) {
-        const res = await fetch(currentUrl, { ...init, headers: hopHeaders, redirect: "manual" });
+        const fetchOpts = { ...init, headers: hopHeaders, redirect: "manual" };
+        this.applyPinnedDispatcher(fetchOpts);
+        const res = await this.dispatcherFetch()(currentUrl, fetchOpts);
         if (res.status !== 301 && res.status !== 302 && res.status !== 303 && res.status !== 307 && res.status !== 308) {
           return res;
         }
@@ -1509,12 +1621,48 @@ var BaseHTTPTransport = class {
       }
     }
   }
+  dispatcherFetch() {
+    return globalThis.fetch === nativeGlobalFetch ? undiciFetch : globalThis.fetch;
+  }
+  pinnedDispatcher() {
+    if (!this.pinnedAgent) {
+      const tls = this.tlsOptions;
+      this.pinnedAgent = new UndiciAgent({
+        allowH2: false,
+        connect: {
+          ...tls ? { ca: tls.ca, rejectUnauthorized: tls.rejectUnauthorized } : {},
+          lookup: transportPinnedLookup({
+            allowPrivateNetworks: this.allowPrivateNetworks,
+            lookup: this.lookup
+          })
+        }
+      });
+      pinnedAgents.add(this.pinnedAgent);
+    }
+    return this.pinnedAgent;
+  }
+  applyPinnedDispatcher(fetchOpts) {
+    fetchOpts.dispatcher = this.pinnedDispatcher();
+  }
+  /**
+   * Destroy this transport's pinned Agent and its connection pool. Idempotent.
+   * Subclasses call it from close(); the process-exit sweep is the backstop.
+   */
+  releasePinnedDispatcher() {
+    if (!this.pinnedAgent) return;
+    pinnedAgents.delete(this.pinnedAgent);
+    this.pinnedAgent.destroy();
+    this.pinnedAgent = void 0;
+  }
   /**
    * Apply the pinned TLS agent (if configured) to a `RequestInit` object.
    * Uses `HttpDispatcher` from `@wrongstack/core`'s dispatcher-types shim,
    * which declares `https.Agent` compatible with `RequestInit.dispatcher`.
    * Verified safe: https.Agent implements the `dispatch(req, opts)` method
    * that fetch requires at runtime.
+   *
+   * Superseded at fetch time by `applyPinnedDispatcher`, whose Agent embeds
+   * these same TLS options plus the resolution-bound lookup.
    */
   applyTlsAgent(fetchOpts) {
     if (this.tlsAgent) {
@@ -1775,7 +1923,8 @@ var SSETransport = class extends BaseHTTPTransport {
         sseReader.feed(chunk);
       }
     } catch {
-      if (this.state !== "disconnected" && this.state !== "failed") {
+    } finally {
+      if (!this.readerDone && this.state !== "disconnected" && this.state !== "failed") {
         this.state = "disconnected";
         this.notifyDisconnect();
       }
@@ -1809,9 +1958,13 @@ var SSETransport = class extends BaseHTTPTransport {
     try {
       const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
       if (!res.ok) {
-        const body2 = await res.text();
-        const cap = MCP_CONSTANTS.REQUEST_LOG_CAP;
-        const snippet = body2.length > cap ? `${body2.slice(0, cap)}\u2026 [${body2.length} bytes total]` : body2;
+        let snippet;
+        try {
+          snippet = await readBodyCapped(res, MCP_CONSTANTS.REQUEST_LOG_CAP);
+        } catch (err) {
+          const received = err instanceof ToolError4 && typeof err.context?.["received"] === "number" ? err.context["received"] : void 0;
+          snippet = typeof received === "number" ? `\u2026 [${received}+ bytes total]` : "\u2026 [error body unreadable]";
+        }
         throw new ToolError4({
           message: `HTTP ${res.status}: ${snippet}`,
           code: "TOOL_EXECUTION_FAILED",
@@ -1819,6 +1972,10 @@ var SSETransport = class extends BaseHTTPTransport {
           context: { transport: "sse", url: this.url, status: res.status }
         });
       }
+      if (method.startsWith("notifications/")) {
+        await readBodyCapped(res).catch(() => void 0);
+        return { jsonrpc: "2.0", id };
+      }
       let data;
       try {
         data = JSON.parse(await readBodyCapped(res));
@@ -1841,6 +1998,7 @@ var SSETransport = class extends BaseHTTPTransport {
         });
         throw makeAbortError(method);
       }
+      this.markDisconnected();
       throw err;
     } finally {
       timeoutSignal.dispose();
@@ -1897,6 +2055,10 @@ var SSETransport = class extends BaseHTTPTransport {
           }
         });
       }
+      if (method.startsWith("notifications/")) {
+        await readBodyCapped(res).catch(() => void 0);
+        return { jsonrpc: "2.0", id };
+      }
       let data;
       try {
         data = JSON.parse(await readBodyCapped(res));
@@ -1920,12 +2082,14 @@ var SSETransport = class extends BaseHTTPTransport {
         });
         throw makeAbortError(method);
       }
+      this.markDisconnected();
       throw err;
     } finally {
       timeoutSignal.dispose();
     }
   }
   async close() {
+    this.releasePinnedDispatcher();
     if (this.state === "disconnected") return;
     this.readerDone = true;
     this.readLoopAbort?.abort();
@@ -1941,10 +2105,16 @@ var SSETransport = class extends BaseHTTPTransport {
     this.disconnectHandlers.splice(0, this.disconnectHandlers.length);
     this.state = "disconnected";
   }
+  markDisconnected() {
+    if (this.state === "connected") {
+      this.state = "disconnected";
+      this.notifyDisconnect();
+    }
+  }
 };
 
 // src/transport-streamable.ts
-var StreamableHTTPTransport = class extends BaseHTTPTransport {
+var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTransport {
   _nextId = 1;
   sessionId;
   constructor(opts) {
@@ -2023,10 +2193,10 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
       const contentType = initRes.headers.get("content-type") ?? "";
       let data;
       if (contentType.includes("application/json")) {
-        const parsed = await initRes.json();
+        const parsed = JSON.parse(await readBodyCapped(initRes));
         if (isJsonRpcResult(parsed)) data = parsed;
       } else {
-        data = extractJsonRpcResults(await initRes.text())[0];
+        data = extractJsonRpcResults(await readBodyCapped(initRes))[0];
       }
       if (!data) {
         throw new Error("Could not parse initialize response");
@@ -2076,10 +2246,13 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
     try {
       const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
       if (!res.ok) {
+        if (_StreamableHTTPTransport.SESSION_FATAL_HTTP_STATUSES.has(res.status)) {
+          this.markDisconnected();
+        }
         throw new Error(`HTTP ${res.status}: ${res.statusText}`);
       }
       if (method.startsWith("notifications/")) {
-        await res.text().catch(() => void 0);
+        await readBodyCapped(res).catch(() => void 0);
         return { jsonrpc: "2.0", id };
       }
       const match = this.consumeResponseText(await readBodyCapped(res), id);
@@ -2123,10 +2296,13 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
     try {
       const res = await this.fetchWithAuthorization(this.url, fetchOpts, timeoutSignal.signal);
       if (!res.ok) {
+        if (_StreamableHTTPTransport.SESSION_FATAL_HTTP_STATUSES.has(res.status)) {
+          this.markDisconnected();
+        }
         throw new Error(`HTTP ${res.status}: ${res.statusText}`);
       }
       if (method.startsWith("notifications/")) {
-        await res.text().catch(() => void 0);
+        await readBodyCapped(res).catch(() => void 0);
         return { jsonrpc: "2.0", id };
       }
       const parsed = this.consumeResponseText(await readBodyCapped(res), id);
@@ -2168,11 +2344,26 @@ var StreamableHTTPTransport = class extends BaseHTTPTransport {
     };
   }
   async close() {
+    this.releasePinnedDispatcher();
     if (this.state === "disconnected") return;
     this.state = "disconnected";
     this.abortController?.abort();
     this.disconnectHandlers.splice(0, this.disconnectHandlers.length);
   }
+  /**
+   * HTTP statuses that mean the streamable-http session itself is gone
+   * (auth rejected, session id unknown or expired). Only these tear the
+   * connection down on the request path; transient faults (5xx, network
+   * resets) surface as call errors and keep the session alive so the next
+   * request can succeed — the contract pinned by http-fault-soak.test.ts.
+   */
+  static SESSION_FATAL_HTTP_STATUSES = /* @__PURE__ */ new Set([401, 403, 404, 410]);
+  markDisconnected() {
+    if (this.state === "connected") {
+      this.state = "disconnected";
+      this.notifyDisconnect();
+    }
+  }
 };
 
 // src/client.ts
@@ -2200,6 +2391,7 @@ var MCPClient = class _MCPClient {
    */
   pending = /* @__PURE__ */ new Map();
   rxBuffer = "";
+  rxBufferBytes = 0;
   _tools = [];
   /** Server-declared handshake metadata. Populated for stdio in the first protocol slice. */
   _serverMetadata;
@@ -2207,6 +2399,7 @@ var MCPClient = class _MCPClient {
   _toolsCache;
   _drainPending = false;
   _lastNotifySkipped = false;
+  closePromise;
   // HTTP transports
   sseTransport;
   httpTransport;
@@ -2260,15 +2453,21 @@ var MCPClient = class _MCPClient {
   async connect() {
     this.state = "connecting";
     this._serverMetadata = void 0;
-    if (this.opts.transport === "stdio") {
-      await this.connectStdio();
-    } else if (this.opts.transport === "sse") {
-      await this.connectSSE();
-    } else if (this.opts.transport === "streamable-http") {
-      await this.connectStreamableHTTP();
-    } else {
+    try {
+      if (this.opts.transport === "stdio") {
+        await this.connectStdio();
+      } else if (this.opts.transport === "sse") {
+        await this.connectSSE();
+      } else if (this.opts.transport === "streamable-http") {
+        await this.connectStreamableHTTP();
+      } else {
+        throw new Error(`Unknown transport "${this.opts.transport}"`);
+      }
+    } catch (err) {
+      await this.close().catch(() => {
+      });
       this.state = "failed";
-      throw new Error(`Unknown transport "${this.opts.transport}"`);
+      throw err;
     }
   }
   async connectStdio() {
@@ -2277,6 +2476,7 @@ var MCPClient = class _MCPClient {
       throw new Error('MCP stdio transport requires "command"');
     }
     this.rxBuffer = "";
+    this.rxBufferBytes = 0;
     const extraEnv = { ...this.opts.env };
     if (this.opts.passthroughEnv) {
       for (const name of this.opts.passthroughEnv) {
@@ -2303,6 +2503,13 @@ var MCPClient = class _MCPClient {
     })() : spawn2(this.opts.command, rawArgs, { env: spawnEnv, stdio, windowsHide: true });
     this.child = child;
     child.stdout?.on("data", (chunk) => this.onData(chunk.toString()));
+    child.stdout?.on("end", () => {
+      if (this.rxBuffer.trim()) {
+        const line = this.rxBuffer.trim();
+        this.rxBuffer = "";
+        this.onLine(line);
+      }
+    });
     child.stderr?.on("data", () => {
     });
     child.stdin?.on("error", (err) => {
@@ -2371,7 +2578,8 @@ var MCPClient = class _MCPClient {
       headers: this.opts.headers,
       startupTimeoutMs: this.opts.startupTimeoutMs,
       requestTimeoutMs: this.opts.requestTimeoutMs,
-      authorizationProvider: this.opts.authorizationProvider
+      authorizationProvider: this.opts.authorizationProvider,
+      allowPrivateNetworks: this.opts.allowPrivateNetworks
     };
     this.sseTransport = new SSETransport(httpOpts);
     this.sseTransport.onDisconnect(() => {
@@ -2421,7 +2629,8 @@ var MCPClient = class _MCPClient {
       headers: this.opts.headers,
       startupTimeoutMs: this.opts.startupTimeoutMs,
       requestTimeoutMs: this.opts.requestTimeoutMs,
-      authorizationProvider: this.opts.authorizationProvider
+      authorizationProvider: this.opts.authorizationProvider,
+      allowPrivateNetworks: this.opts.allowPrivateNetworks
     };
     this.httpTransport = new StreamableHTTPTransport(httpOpts);
     this.httpTransport.onDisconnect(() => {
@@ -2554,6 +2763,13 @@ var MCPClient = class _MCPClient {
     );
   }
   async close() {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.closeInner().finally(() => {
+      this.closePromise = void 0;
+    });
+    return this.closePromise;
+  }
+  async closeInner() {
     if (this.child) {
       const child = this.child;
       const exitPromise = new Promise((resolve) => {
@@ -2570,16 +2786,26 @@ var MCPClient = class _MCPClient {
       }
       const GRACEFUL_MS = 800;
       const FORCE_TIMEOUT_MS = 1200;
+      let gracefulTimer;
       const gracefulRace = await Promise.race([
         exitPromise.then(() => "exited"),
-        new Promise((resolve) => setTimeout(() => resolve("timeout"), GRACEFUL_MS))
+        new Promise((resolve) => {
+          gracefulTimer = setTimeout(() => resolve("timeout"), GRACEFUL_MS);
+          gracefulTimer.unref?.();
+        })
       ]);
+      if (gracefulTimer) clearTimeout(gracefulTimer);
       if (gracefulRace === "timeout") {
         forceKillTree(child);
+        let forceTimer;
         await Promise.race([
           exitPromise,
-          new Promise((resolve) => setTimeout(resolve, FORCE_TIMEOUT_MS))
+          new Promise((resolve) => {
+            forceTimer = setTimeout(resolve, FORCE_TIMEOUT_MS);
+            forceTimer.unref?.();
+          })
         ]);
+        if (forceTimer) clearTimeout(forceTimer);
       }
       child.stdout?.removeAllListeners();
       child.stderr?.removeAllListeners();
@@ -2709,49 +2935,53 @@ var MCPClient = class _MCPClient {
     this.pending.clear();
   }
   async notify(method, params) {
+    if (this._drainPending) {
+      this._lastNotifySkipped = true;
+      console.warn(
+        JSON.stringify({
+          level: "warn",
+          event: "mcp.notify_skipped_backpressure",
+          server: this.opts.name,
+          method,
+          message: "stdin buffer backpressure (already waiting for drain)",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+      return;
+    }
+    const stdin = this.child?.stdin;
+    if (!stdin || stdin.destroyed === true || stdin.writable === false) {
+      return;
+    }
     const req = { jsonrpc: "2.0", method, params };
     const encoded = JSON.stringify(req) + "\n";
     try {
-      const ok = this.child?.stdin?.write(encoded);
+      const ok = stdin.write(encoded);
       if (!ok) {
-        if (this._drainPending) {
-          this._lastNotifySkipped = true;
-          console.warn(
-            JSON.stringify({
-              level: "warn",
-              event: "mcp.notify_skipped_backpressure",
-              server: this.opts.name,
-              method,
-              message: "stdin buffer backpressure (already waiting for drain)",
-              timestamp: (/* @__PURE__ */ new Date()).toISOString()
-            })
-          );
-          return;
-        }
         this._drainPending = true;
         await new Promise((resolve, reject) => {
           const timeout = setTimeout(() => {
-            this.child?.stdin?.removeListener?.("drain", onDrain);
-            this.child?.stdin?.removeListener?.("error", onError);
+            stdin.removeListener?.("drain", onDrain);
+            stdin.removeListener?.("error", onError);
             this._drainPending = false;
             reject(new Error(`MCP notify("${method}") drain timeout`));
           }, 500);
           const onDrain = () => {
             clearTimeout(timeout);
-            this.child?.stdin?.removeListener?.("drain", onDrain);
-            this.child?.stdin?.removeListener?.("error", onError);
+            stdin.removeListener?.("drain", onDrain);
+            stdin.removeListener?.("error", onError);
             this._drainPending = false;
             resolve();
           };
           const onError = (err) => {
             clearTimeout(timeout);
-            this.child?.stdin?.removeListener?.("drain", onDrain);
-            this.child?.stdin?.removeListener?.("error", onError);
+            stdin.removeListener?.("drain", onDrain);
+            stdin.removeListener?.("error", onError);
             this._drainPending = false;
             reject(err);
           };
-          this.child?.stdin?.once("drain", onDrain);
-          this.child?.stdin?.once("error", onError);
+          stdin.once?.("drain", onDrain);
+          stdin.once?.("error", onError);
         });
       }
     } catch (err) {
@@ -2760,21 +2990,28 @@ var MCPClient = class _MCPClient {
   }
   onData(s) {
     this.rxBuffer += s;
-    if (this.rxBuffer.length > _MCPClient.MAX_RX_BUFFER_BYTES) {
-      const truncated = this.rxBuffer.length;
+    this.rxBufferBytes += Buffer.byteLength(s, "utf8");
+    if (this.rxBufferBytes > _MCPClient.MAX_RX_BUFFER_BYTES) {
+      const truncated = this.rxBufferBytes;
       this.rxBuffer = "";
+      this.rxBufferBytes = 0;
       this.failPending(
         `MCP "${this.opts.name}" rx buffer overflow (${truncated} bytes without a newline) \u2014 closing connection`
       );
       void this.close();
       return;
     }
+    let start = 0;
     let idx = this.rxBuffer.indexOf("\n");
     while (idx !== -1) {
-      const line = this.rxBuffer.slice(0, idx).trim();
-      this.rxBuffer = this.rxBuffer.slice(idx + 1);
+      const line = this.rxBuffer.slice(start, idx).trim();
+      start = idx + 1;
       if (line) this.onLine(line);
-      idx = this.rxBuffer.indexOf("\n");
+      idx = this.rxBuffer.indexOf("\n", start);
+    }
+    if (start > 0) {
+      this.rxBufferBytes -= Buffer.byteLength(this.rxBuffer.slice(0, start), "utf8");
+      this.rxBuffer = this.rxBuffer.slice(start);
     }
   }
   onLine(line) {
@@ -3091,6 +3328,8 @@ function buildConfig(input, base) {
   if (allowedTools !== void 0) cfg.allowedTools = allowedTools;
   const permission = input.permission ?? base?.permission;
   if (permission !== void 0) cfg.permission = permission;
+  const allowPrivateNetworks = input.allowPrivateNetworks ?? base?.allowPrivateNetworks;
+  if (allowPrivateNetworks !== void 0) cfg.allowPrivateNetworks = allowPrivateNetworks;
   const enabled = input.enabled ?? base?.enabled;
   if (enabled !== void 0) cfg.enabled = enabled;
   const lazy = input.lazy ?? base?.lazy;
@@ -3321,13 +3560,26 @@ function manifestConfigHash(cfg) {
     transport: cfg.transport,
     command: cfg.command ?? null,
     args: cfg.args ?? null,
-    url: cfg.url ?? null
+    url: cfg.url ?? null,
+    env: sortedEntries(cfg.env),
+    headers: sortedEntries(cfg.headers),
+    passthroughEnv: passthroughEntries(cfg.passthroughEnv)
   });
   return createHash2("sha256").update(basis).digest("hex").slice(0, 16);
 }
+function sortedEntries(values) {
+  return values ? Object.entries(values).sort(([left], [right]) => left.localeCompare(right)) : null;
+}
+function passthroughEntries(names) {
+  return names ? [...new Set(names)].sort().map((name) => [name, process.env[name] ?? null]) : null;
+}
 function manifestFile(cacheDir, name) {
   const safe = name.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return path.join(cacheDir, "mcp-tools", `${safe}.json`);
+  if (safe === name && name === name.toLowerCase()) {
+    return path.join(cacheDir, "mcp-tools", `${safe}.json`);
+  }
+  const identity = createHash2("sha256").update(name).digest("hex");
+  return path.join(cacheDir, "mcp-tools", `${safe}-${identity}.json`);
 }
 async function readManifest(cacheDir, name, configHash) {
   const manifest = await readCapabilityManifest(cacheDir, name, configHash);
@@ -3611,7 +3863,8 @@ function wrapMCPTool(serverName, mcpTool, client, permission = "confirm", observ
         const signal = opts?.signal ?? ctx?.signal;
         const res = await live.callTool(mcpTool.name, input, signal ? { signal } : void 0);
         if (res.isError) {
-          throw new Error(stringify(res.content));
+          const errText = stringify(res.content);
+          throw new Error(errText || `MCP tool "${qualifiedName}" failed`);
         }
         ok = true;
         return stringify(res.content);
@@ -3660,6 +3913,7 @@ function applySlotTools(ctx, slot, tools, client) {
       },
       onFinish: ({ durationMs, ok }) => {
         slot.operations.inFlightCalls = Math.max(0, slot.operations.inFlightCalls - 1);
+        slot.lastUsed = Date.now();
         pushBounded(slot.operations.callSamples, durationMs, MCP_OPERATION_LIMITS.LATENCY_SAMPLES);
         if (ok) {
           ctx.recordSuccess(slot);
@@ -3771,6 +4025,7 @@ async function attemptConnectSlot(ctx, slot) {
         headers: slot.cfg.headers,
         startupTimeoutMs: slot.cfg.startupTimeoutMs,
         requestTimeoutMs: slot.cfg.requestTimeoutMs,
+        allowPrivateNetworks: slot.cfg.allowPrivateNetworks,
         passthroughEnv: slot.cfg.passthroughEnv,
         authorizationProvider: ctx.authorizationProviderFactory?.(slot.cfg)
       });
@@ -3783,7 +4038,7 @@ async function attemptConnectSlot(ctx, slot) {
       client.addToolsChangedListener(ctx.onToolsChanged);
       ctx.addCatalogListeners(client);
       await client.connect();
-      if (slot.state === "disconnected" || ctx.servers.has(slot.cfg.name) && ctx.servers.get(slot.cfg.name) !== slot) {
+      if (slot.state === "disconnected" || !ctx.servers.has(slot.cfg.name) || ctx.servers.get(slot.cfg.name) !== slot) {
         client.removeExitListener(ctx.onChildExit);
         if (boundDisconnect) client.removeDisconnectListener(boundDisconnect);
         client.removeToolsChangedListener(ctx.onToolsChanged);
@@ -3886,8 +4141,28 @@ function resetDisconnectedSlotTools(slot, toolRegistry) {
   slot.resourceTemplates = void 0;
   slot.prompts = void 0;
 }
-function markLazySlotDormant(slot, events, reason) {
-  slot.client = void 0;
+function markLazySlotDormant(slot, events, reason, options) {
+  slot.reconnectPending = false;
+  if (slot.reconnectTimer) {
+    clearTimeout(slot.reconnectTimer);
+    slot.reconnectTimer = void 0;
+  }
+  if (slot.client) {
+    if (options?.onChildExit) {
+      slot.client.removeExitListener?.(options.onChildExit);
+    }
+    if (slot.onDisconnect) {
+      slot.client.removeDisconnectListener?.(slot.onDisconnect);
+    }
+    if (options?.onToolsChanged) {
+      slot.client.removeToolsChangedListener?.(options.onToolsChanged);
+    }
+    options?.removeCatalogListeners?.(slot.client);
+    slot.client.close?.().catch(() => {
+    });
+    slot.client = void 0;
+  }
+  slot.onDisconnect = void 0;
   slot.state = "dormant";
   events.emit("mcp.server.disconnected", {
     name: slot.cfg.name,
@@ -3950,17 +4225,23 @@ function buildRegistryOperationalHealth(servers, disabledServers) {
 
 // src/registry-idle.ts
 async function sleepIdleSlot(ctx, slot) {
+  if (slot.operations.inFlightCalls > 0) return;
   slot.reconnectPending = false;
   if (slot.reconnectTimer) {
     clearTimeout(slot.reconnectTimer);
     slot.reconnectTimer = void 0;
   }
   if (slot.client) {
-    slot.client.removeExitListener(ctx.onChildExit);
-    if (slot.onDisconnect) slot.client.removeDisconnectListener(slot.onDisconnect);
-    slot.client.removeToolsChangedListener(ctx.onToolsChanged);
-    ctx.removeCatalogListeners(slot.client);
-    await slot.client.close();
+    const client = slot.client;
+    client.removeExitListener?.(ctx.onChildExit);
+    if (slot.onDisconnect) client.removeDisconnectListener?.(slot.onDisconnect);
+    client.removeToolsChangedListener?.(ctx.onToolsChanged);
+    ctx.removeCatalogListeners(client);
+    try {
+      await client.close?.();
+    } catch (err) {
+      ctx.log.warn(`MCP server "${slot.cfg.name}" error during idle sleep close`, err);
+    }
     slot.client = void 0;
   }
   slot.onDisconnect = void 0;
@@ -3974,7 +4255,7 @@ async function sweepIdleSlots(ctx) {
   if (ctx.idleTimeoutMs <= 0) return false;
   const now = Date.now();
   for (const slot of ctx.servers.values()) {
-    if (slot.lazy && slot.state === "connected" && slot.client && now - slot.lastUsed > ctx.idleTimeoutMs) {
+    if (slot.lazy && slot.state === "connected" && slot.client && slot.operations.inFlightCalls === 0 && now - slot.lastUsed > ctx.idleTimeoutMs) {
       await sleepIdleSlot(ctx, slot);
     }
   }
@@ -4062,6 +4343,7 @@ function scheduleRegistryReconnect({
     slot.reconnectTimer = void 0;
     void attemptReconnect(slot);
   }, delay);
+  slot.reconnectTimer.unref?.();
 }
 
 // src/registry.ts
@@ -4209,7 +4491,7 @@ var MCPRegistry = class _MCPRegistry {
     if (!slot) throw new Error(`MCP server "${name}" not registered`);
     slot.lastUsed = Date.now();
     if (slot.client && slot.state === "connected") return slot.client;
-    const waking = slot.state === "dormant";
+    const waking = slot.state === "dormant" && !slot.connecting;
     if (waking) {
       slot.operations.wakeCount++;
       this.recordOperation(slot, "wake", "lazy-demand");
@@ -4285,22 +4567,21 @@ var MCPRegistry = class _MCPRegistry {
     }
     slot.state = "disconnected";
     if (slot.client) {
-      slot.client.removeExitListener(this.onChildExit);
-      if (slot.onDisconnect) slot.client.removeDisconnectListener(slot.onDisconnect);
-      slot.client.removeToolsChangedListener(this.onToolsChanged);
-      this.removeCatalogListeners(slot.client);
-      await slot.client.close();
+      const client = slot.client;
+      client.removeExitListener?.(this.onChildExit);
+      if (slot.onDisconnect) client.removeDisconnectListener?.(slot.onDisconnect);
+      client.removeToolsChangedListener?.(this.onToolsChanged);
+      this.removeCatalogListeners(client);
+      try {
+        await client.close?.();
+      } catch (err) {
+        this.log.warn(`MCP server "${name}" error during stop close`, err);
+      }
       slot.client = void 0;
     }
     slot.onDisconnect = void 0;
     slot.connecting = void 0;
-    for (const t of slot.toolNames) this.toolRegistry.unregister(t);
-    slot.toolNames = [];
-    slot.lazyTools = [];
-    slot.serverMetadata = void 0;
-    slot.resources = void 0;
-    slot.resourceTemplates = void 0;
-    slot.prompts = void 0;
+    resetDisconnectedSlotTools(slot, this.toolRegistry);
     slot.registeredLazy = false;
     this.recordOperation(slot, "stop", "manual");
     this.events.emit("mcp.server.disconnected", { name, reason: "stop" });
@@ -4344,8 +4625,17 @@ var MCPRegistry = class _MCPRegistry {
   }
   getCatalog(name) {
     const slot = this.servers.get(name);
-    if (!slot) return void 0;
-    return registryCatalogSnapshot(slot);
+    if (slot) {
+      return registryCatalogSnapshot(slot);
+    }
+    const disabled = this.disabledServers.get(name);
+    if (disabled) {
+      return {
+        name: disabled.name,
+        state: "idle"
+      };
+    }
+    return void 0;
   }
   async listResources(name, opts = {}) {
     const slot = this.requireSlot(name);
@@ -4502,9 +4792,16 @@ var MCPRegistry = class _MCPRegistry {
       clearInterval(this.idleTimer);
       this.idleTimer = void 0;
     }
-    for (const name of Array.from(this.servers.keys())) {
-      await this.stop(name);
-    }
+    const names = Array.from(this.servers.keys());
+    await Promise.all(
+      names.map(async (name) => {
+        try {
+          await this.stop(name);
+        } catch (err) {
+          this.log.warn(`MCP server "${name}" failed to stop during stopAll`, err);
+        }
+      })
+    );
     this.disabledServers.clear();
   }
   /**
@@ -4566,15 +4863,19 @@ var MCPRegistry = class _MCPRegistry {
     client.addPromptsChangedListener(this.onPromptsChanged);
   }
   removeCatalogListeners(client) {
-    client.removeResourcesChangedListener(this.onResourcesChanged);
-    client.removePromptsChangedListener(this.onPromptsChanged);
+    client.removeResourcesChangedListener?.(this.onResourcesChanged);
+    client.removePromptsChangedListener?.(this.onPromptsChanged);
   }
   onChildExit = (name, code, _signal) => {
     const slot = this.servers.get(name);
     if (!slot) return;
     if (slot.lazy) {
       this.recordFailure(slot, "transport", "process-exit-lazy");
-      markLazySlotDormant(slot, this.events, `exit:${code ?? "unknown"}`);
+      markLazySlotDormant(slot, this.events, `exit:${code ?? "unknown"}`, {
+        onChildExit: this.onChildExit,
+        onToolsChanged: this.onToolsChanged,
+        removeCatalogListeners: (c) => this.removeCatalogListeners(c)
+      });
       return;
     }
     resetDisconnectedSlotTools(slot, this.toolRegistry);
@@ -4589,7 +4890,11 @@ var MCPRegistry = class _MCPRegistry {
     if (!slot) return;
     if (slot.lazy) {
       this.recordFailure(slot, "transport", "http-disconnect-lazy");
-      markLazySlotDormant(slot, this.events, "http-disconnect");
+      markLazySlotDormant(slot, this.events, "http-disconnect", {
+        onChildExit: this.onChildExit,
+        onToolsChanged: this.onToolsChanged,
+        removeCatalogListeners: (c) => this.removeCatalogListeners(c)
+      });
       return;
     }
     resetDisconnectedSlotTools(slot, this.toolRegistry);
@@ -4908,6 +5213,7 @@ function serveStdio(server, opts = {}) {
   const stdin = opts.stdin ?? process.stdin;
   const stdout = opts.stdout ?? process.stdout;
   let buffer = "";
+  let bufferBytes = 0;
   let closed = false;
   let bufferTooLarge = false;
   let writeChain = Promise.resolve();
@@ -4932,10 +5238,13 @@ function serveStdio(server, opts = {}) {
   };
   const onData = (chunk) => {
     if (bufferTooLarge) return;
-    buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    if (buffer.length > HTTP_BODY_CAP) {
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    buffer += text;
+    bufferBytes += Buffer.byteLength(text, "utf8");
+    if (bufferBytes > HTTP_BODY_CAP) {
       bufferTooLarge = true;
       buffer = "";
+      bufferBytes = 0;
       console.error(
         JSON.stringify({
           level: "error",
@@ -4952,11 +5261,14 @@ function serveStdio(server, opts = {}) {
       onEnd();
       return;
     }
-    let idx = buffer.indexOf("\n");
+    let start = 0;
+    let idx = buffer.indexOf("\n", start);
     while (idx !== -1) {
-      const line = buffer.slice(0, idx);
-      buffer = buffer.slice(idx + 1);
-      idx = buffer.indexOf("\n");
+      let end = idx;
+      if (end > start && buffer.charCodeAt(end - 1) === 13) end--;
+      const line = buffer.slice(start, end);
+      start = idx + 1;
+      idx = buffer.indexOf("\n", start);
       if (!line.trim()) continue;
       const handler = server.handleMessage(line).then((res) => {
         if (res !== null) writeLine(res);
@@ -4974,6 +5286,10 @@ function serveStdio(server, opts = {}) {
       });
       inFlightHandlers.add(handler);
     }
+    if (start > 0) {
+      bufferBytes -= Buffer.byteLength(buffer.slice(0, start), "utf8");
+      buffer = buffer.slice(start);
+    }
   };
   let resolveDone;
   const done = new Promise((resolve) => {
@@ -4985,6 +5301,26 @@ function serveStdio(server, opts = {}) {
     if (closed) return;
     closed = true;
     stdin.off("data", onData);
+    if (!bufferTooLarge && buffer.trim()) {
+      const line = buffer.trim();
+      buffer = "";
+      bufferBytes = 0;
+      const handler = server.handleMessage(line).then((res) => {
+        if (res !== null) writeLine(res);
+      }).catch((err) => {
+        console.error(
+          JSON.stringify({
+            level: "error",
+            event: "mcp_server.handle_message_failed",
+            message: toErrorMessage2(err),
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          })
+        );
+      }).finally(() => {
+        inFlightHandlers.delete(handler);
+      });
+      inFlightHandlers.add(handler);
+    }
     resolveDone();
   };
   stdin.on("data", onData);
@@ -5069,18 +5405,26 @@ async function handleHttpRequest(server, req, res, token, log, boundHost) {
     return send(415, JSON.stringify({ error: "content-type must be application/json" }));
   }
   let body = "";
+  let bodyBytes = 0;
+  let aborted = false;
   req.on("data", (chunk) => {
+    if (aborted) return;
+    bodyBytes += chunk.byteLength;
     body += chunk.toString("utf8");
-    if (body.length > HTTP_BODY_CAP) {
+    if (bodyBytes > HTTP_BODY_CAP) {
+      aborted = true;
       send(413, JSON.stringify({ error: "payload too large" }));
       req.destroy();
     }
   });
   req.on("end", () => {
+    if (aborted) return;
     void server.handleMessage(body).then((out) => {
+      if (aborted) return;
       if (out === null) return send(202, "");
       return send(200, out);
     }).catch((err) => {
+      if (aborted) return;
       log?.warn?.(`MCP http handler error: ${toErrorMessage2(err)}`);
       send(500, JSON.stringify({ error: "internal error" }));
     });
@@ -5288,13 +5632,14 @@ var MCPRefreshingAuthorizationProvider = class {
     return await this.refresh(state, context.signal) !== void 0;
   }
   refresh(state, signal) {
-    if (this.refreshPromise) return this.refreshPromise;
-    this.refreshPromise = this.refreshInner(state, signal).finally(() => {
-      this.refreshPromise = void 0;
-    });
-    return this.refreshPromise;
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.refreshInner(state).finally(() => {
+        this.refreshPromise = void 0;
+      });
+    }
+    return awaitWithAbort(this.refreshPromise, signal);
   }
-  async refreshInner(state, signal) {
+  async refreshInner(state) {
     const refreshToken = state.tokenSet.refreshToken;
     if (!refreshToken) {
       this.emit("reauth_required", state);
@@ -5304,8 +5649,7 @@ var MCPRefreshingAuthorizationProvider = class {
       authorizationServer: state.authorizationServer,
       clientId: state.clientId,
       resource: state.resource,
-      refreshToken,
-      signal
+      refreshToken
     });
     const next = normalizeStoredAuthorization({
       ...state,
@@ -5351,6 +5695,18 @@ function createVaultBackedMcpAuthorizationProviderFactory(options) {
     return provider;
   };
 }
+function awaitWithAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortReason(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+function abortReason(signal) {
+  return signal.reason instanceof Error ? signal.reason : new Error("MCP token refresh aborted");
+}
 function emptyFile() {
   return { version: TOKEN_STORE_VERSION, updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(), entries: [] };
 }

package/dist/manage.d.ts

@@ -6,6 +6,7 @@ type TransportInput = 'stdio' | 'sse' | 'streamable-http' | 'http';
 export interface McpServerInput {
     name: string;
     transport?: TransportInput | string | undefined;
+    allowPrivateNetworks?: boolean | undefined;
     description?: string | undefined;
     enabled?: boolean | undefined;
     command?: string | undefined;

package/dist/manifest-cache.d.ts

@@ -13,6 +13,9 @@ export declare function manifestConfigHash(cfg: {
     command?: string | undefined;
     args?: string[] | undefined;
     url?: string | undefined;
+    env?: Record<string, string> | undefined;
+    headers?: Record<string, string> | undefined;
+    passthroughEnv?: string[] | undefined;
 }): string;
 /**
  * Read a server's cached tools. Returns null when there is no cache or when the

package/dist/registry-disconnect.d.ts

@@ -2,5 +2,12 @@ import type { EventBus } from '@wrongstack/core/kernel';
 import type { ToolRegistry } from '@wrongstack/core/registry';
 import type { ServerSlot } from './registry-slots.js';
 export declare function resetDisconnectedSlotTools(slot: ServerSlot, toolRegistry: ToolRegistry): void;
-export declare function markLazySlotDormant(slot: ServerSlot, events: EventBus, reason: string): void;
+export interface MarkLazySlotDormantOptions {
+    onChildExit?: (name: string, code: number | null, signal: string | null) => void;
+    onToolsChanged?: (name: string, tools: {
+        name: string;
+    }[]) => void;
+    removeCatalogListeners?: (client: import('./client.js').MCPClient) => void;
+}
+export declare function markLazySlotDormant(slot: ServerSlot, events: EventBus, reason: string, options?: MarkLazySlotDormantOptions): void;
 //# sourceMappingURL=registry-disconnect.d.ts.map

package/dist/transport-base.d.ts

@@ -2,6 +2,7 @@ import * as https from 'node:https';
 import { type MCPAuthorizationProvider } from './authorization.js';
 import type { ConnectionState, MCPTool } from './contracts.js';
 import type { MCPServerMetadata } from './protocol.js';
+import { type TransportDnsLookup } from './transport-security.js';
 export interface HttpTransportOptions {
     name: string;
     url: string;
@@ -27,6 +28,21 @@ export interface HttpTransportOptions {
         ca?: string | undefined;
         rejectUnauthorized?: boolean | undefined;
     };
+    /**
+     * Resolution-bound private-network policy. Default: the transport resolves
+     * the configured hostname itself and refuses dial-time addresses outside
+     * the public internet — link-local/IMDS always, other private/LAN ranges
+     * unless this flag is set. The configured hostname is still used for the
+     * Host header and TLS SNI, so certificate validation is unaffected, and
+     * plaintext http:// remains loopback-only (validateTransportUrl).
+     */
+    allowPrivateNetworks?: boolean | undefined;
+    /**
+     * DNS seam for tests and hosts with custom resolvers. Production callers
+     * omit it: dns.lookup(hostname, { all: true }) runs and every returned
+     * record is policy-checked before the dial.
+     */
+    lookup?: TransportDnsLookup | undefined;
 }
 /**
  * Abort error whose `name` is `'AbortError'` so the core executor's
@@ -52,6 +68,10 @@ export declare abstract class BaseHTTPTransport {
     protected readonly authorizationResource: string;
     /** Per-request TLS agent — created once from HttpTransportOptions.tls */
     protected readonly tlsAgent?: https.Agent | undefined;
+    private readonly tlsOptions;
+    private readonly allowPrivateNetworks;
+    private readonly lookup;
+    private pinnedAgent;
     protected readonly tools: MCPTool[];
     protected serverMetadata?: MCPServerMetadata | undefined;
     protected abortController?: AbortController | undefined;
@@ -76,12 +96,23 @@ export declare abstract class BaseHTTPTransport {
     protected notifyDisconnect(): void;
     protected notifyResourcesChanged(): void;
     protected notifyPromptsChanged(): void;
+    private dispatcherFetch;
+    private pinnedDispatcher;
+    private applyPinnedDispatcher;
+    /**
+     * Destroy this transport's pinned Agent and its connection pool. Idempotent.
+     * Subclasses call it from close(); the process-exit sweep is the backstop.
+     */
+    protected releasePinnedDispatcher(): void;
     /**
      * Apply the pinned TLS agent (if configured) to a `RequestInit` object.
      * Uses `HttpDispatcher` from `@wrongstack/core`'s dispatcher-types shim,
      * which declares `https.Agent` compatible with `RequestInit.dispatcher`.
      * Verified safe: https.Agent implements the `dispatch(req, opts)` method
      * that fetch requires at runtime.
+     *
+     * Superseded at fetch time by `applyPinnedDispatcher`, whose Agent embeds
+     * these same TLS options plus the resolution-bound lookup.
      */
     protected applyTlsAgent(fetchOpts: RequestInit): void;
     /** Generate the next JSON-RPC request id. Subclasses provide the counter. */

package/dist/transport-security.d.ts

@@ -10,4 +10,52 @@ export declare function isTlsUnsafeAllowed(): boolean;
  * the most obvious attack vectors.
  */
 export declare function validateTransportUrl(rawUrl: string): void;
+/** Global escape hatch, mirroring the fetch tool's WRONGSTACK_FETCH_ALLOW_PRIVATE. */
+export declare const ALLOW_MCP_PRIVATE_NETWORKS: boolean;
+/** One resolved DNS record for an MCP transport hostname. */
+export interface TransportDnsRecord {
+    address: string;
+    family: number;
+}
+/** DNS seam: production uses dns.lookup(host, { all: true }); tests inject. */
+export type TransportDnsLookup = (hostname: string) => Promise<readonly TransportDnsRecord[]>;
+/** Policy verdict for one resolved address. */
+export type TransportAddressClass = 'loopback' | 'private' | 'blocked' | 'public';
+/**
+ * Classify one resolved address under MCP transport policy:
+ *  - `blocked`  — link-local / IMDS (169.254/16, fe80::/10, fd00:ec2::254);
+ *                 never a valid MCP target, regardless of opt-in.
+ *  - `loopback` — 127/8, ::1; the documented local topology, always allowed.
+ *  - `private`  — other private/reserved ranges (10/8, 172.16/12, 192.168/16,
+ *                 CGNAT, ULA, ...); allowed only with allowPrivateNetworks.
+ *  - `public`   — no dial-time restriction beyond the string-level checks.
+ */
+export declare function classifyTransportAddress(address: string, family: number): TransportAddressClass;
+/**
+ * Refuse `address` unless the transport policy allows dialing it:
+ * link-local/IMDS always throws; other private ranges throw unless opted in
+ * via allowPrivateNetworks. `hostname` is the configured name the address was
+ * resolved from, kept for error context.
+ */
+export declare function assertTransportAddressAllowed(address: string, family: number, hostname: string, allowPrivateNetworks: boolean): void;
+/** Node-style DNS callback for undici Agent connect options. */
+type NodeLookupCallback = (err: NodeJS.ErrnoException | null, address?: string | readonly TransportDnsRecord[], family?: number) => void;
+export interface PinnedLookupOptions {
+    allowPrivateNetworks: boolean;
+    /** Test/host seam. Production omits it: dns.lookup(all: true). */
+    lookup?: TransportDnsLookup | undefined;
+}
+/**
+ * The lookup installed into the pinned undici Agent's connect options. It is
+ * the single DNS resolution the TCP dial performs: every returned record is
+ * classified and refused BEFORE the socket connects, so there is no rebinding
+ * window between validation and connect. Mirrors tools/_fetch-guard.ts
+ * guardedLookup with MCP policy (loopback allowed, link-local never, opt-in
+ * for other private ranges).
+ */
+export declare function transportPinnedLookup(options: PinnedLookupOptions): (hostname: string, connectOptions: {
+    family?: number | undefined;
+    all?: boolean | undefined;
+}, callback: NodeLookupCallback) => void;
+export {};
 //# sourceMappingURL=transport-security.d.ts.map

package/dist/transport-sse.d.ts

@@ -27,5 +27,6 @@ export declare class SSETransport extends BaseHTTPTransport {
         signal?: AbortSignal | undefined;
     }): Promise<JsonRpcResponse>;
     close(): Promise<void>;
+    private markDisconnected;
 }
 //# sourceMappingURL=transport-sse.d.ts.map

package/dist/transport-streamable.d.ts

@@ -23,5 +23,14 @@ export declare class StreamableHTTPTransport extends BaseHTTPTransport {
         signal?: AbortSignal | undefined;
     }): Promise<ToolCallResult>;
     close(): Promise<void>;
+    /**
+     * HTTP statuses that mean the streamable-http session itself is gone
+     * (auth rejected, session id unknown or expired). Only these tear the
+     * connection down on the request path; transient faults (5xx, network
+     * resets) surface as call errors and keep the session alive so the next
+     * request can succeed — the contract pinned by http-fault-soak.test.ts.
+     */
+    private static readonly SESSION_FATAL_HTTP_STATUSES;
+    private markDisconnected;
 }
 //# sourceMappingURL=transport-streamable.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/mcp",
-  "version": "0.319.1",
+  "version": "1.0.0",
   "license": "MIT",
   "description": "WrongStack Model Context Protocol client and registry: stdio, SSE, and streamable HTTP transports.",
   "repository": {
@@ -26,7 +26,8 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@wrongstack/core": "0.319.1"
+    "@wrongstack/core": "1.0.0",
+    "undici": "^8.10.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",