@openrouter/mcp 0.0.1 → 1.0.0

package/esm/mcp-connection.js

@@ -1,15 +1,48 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-// SSEClientTransport is deprecated upstream but intentionally supported here for
-// legacy MCP servers that haven't migrated to Streamable HTTP.
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ElicitRequestSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
+// SSEClientTransport is deprecated upstream (SEP-2596) but intentionally
+// supported here for legacy MCP servers that haven't migrated to Streamable HTTP.
+import { Client, SSEClientTransport, StreamableHTTPClientTransport, UnauthorizedError, } from '@modelcontextprotocol/client';
 import { resolveAuth } from './auth/auth-resolver.js';
+import { isOAuthAuth } from './auth/auth-types.js';
+import { closeQuietly } from './close-quietly.js';
 import { makeElicitationRequestHandler } from './elicitation.js';
 import { MCPConnectionError } from './errors.js';
+import { PACKAGE_VERSION } from './version.js';
+/**
+ * Ceiling on the `server/discover` probe, in ms.
+ *
+ * The SDK falls back to the full request timeout (60s) when this is unset, which
+ * is a long time to spend on a liveness question: under the `'auto'` default the
+ * probe is the first request of every connection, and a gateway that black-holes
+ * it burns the whole budget per attempt — up to four attempts once the legacy
+ * retry re-walks the transport ladder, so minutes before `createMCPTools()`
+ * rejects on the no-configuration path.
+ *
+ * **But a probe timeout is not recoverable, so this cannot be tight.** On HTTP
+ * the SDK classifies a timed-out probe as an outage and rejects (only stdio
+ * treats it as a legacy verdict), and the legacy retry that follows sends
+ * `initialize` — which revision 2026-07-28 removed (SEP-2575). So a
+ * modern-only server slower than this ceiling fails *both* passes and does not
+ * connect at all, where the SDK's own default would have waited and succeeded.
+ * Serverless cold starts routinely exceed a few seconds, which makes an
+ * aggressive value a correctness bug rather than a latency tradeoff.
+ *
+ * 30s splits the difference: comfortably past a cold start, while keeping the
+ * probe from consuming the SDK's full 60s request budget per attempt. Note the
+ * ceiling bounds only the `'auto'` probes — the implicit legacy retry's
+ * `initialize` attempts still run under the SDK's own timeout, so the
+ * black-holed-gateway worst case on the default path is roughly
+ * 30s + 30s + 60s + 60s ≈ 3 minutes across the four attempts (vs ~2 minutes
+ * for the two attempts before this package probed at all). A caller with a
+ * harder deadline bounds the whole ladder with `signal`. Raise this with
+ * `probeTimeoutMs` for a server known to be slower; lower it when you control
+ * the server and want to fail fast.
+ */
+const DEFAULT_PROBE_TIMEOUT_MS = 30000;
+// Self-reported to every MCP server we connect to as `clientInfo`. The version
+// is generated from package.json (scripts/gen-version.mjs) so it cannot drift.
 const DEFAULT_CLIENT_INFO = {
     name: '@openrouter/mcp',
-    version: '0.1.0',
+    version: PACKAGE_VERSION,
 };
 function buildStreamableHttp(options) {
     const { headers, authProvider } = resolveAuth(options.auth);
@@ -42,51 +75,98 @@ function buildSse(options) {
         }),
     });
 }
+/** Per-call request options threaded into the SDK's `connect()`. */
+function connectRequestOptions(options) {
+    return options.signal !== undefined
+        ? {
+            signal: options.signal,
+        }
+        : undefined;
+}
 /**
- * Runtime narrowing to `Transport`. The SDK's transport classes implement the
- * interface, but their `.d.ts` types `sessionId` as `string | undefined` rather
- * than `sessionId?: string`, which `exactOptionalPropertyTypes` rejects at the
- * `connect()` call site. We confirm the structural contract at runtime instead
- * of asserting past the variance with `as`.
+ * Build the configured `Client` — negotiation mode, elicitation handler, and the
+ * `tools/list_changed` subscription — without connecting it.
+ *
+ * Exported for tests only, and deliberately not re-exported from the package
+ * entrypoint. It is the seam that lets a test drive the real handler wiring over
+ * `InMemoryTransport`: the notification method name is compile-checked (it is a
+ * `NotificationMethod` literal union, so a typo fails `tsc`), but the *dispatch*
+ * — that an inbound notification actually reaches `setToolListChangedHandler`'s
+ * callback — is only observable end to end. Without this seam, default-on
+ * `autoRefreshOnListChanged` could be silently dead with every test green.
+ *
+ * @internal
  */
-function isTransport(value) {
-    return (typeof value.start === 'function' &&
-        typeof value.send === 'function' &&
-        typeof value.close === 'function');
+export function makeClientForTest(options, onListChanged) {
+    return makeClient(options, {
+        handler: onListChanged,
+    });
 }
 function makeClient(options, listChanged) {
     const client = new Client(options.clientInfo ?? DEFAULT_CLIENT_INFO, {
         capabilities: {
             elicitation: {},
         },
+        // The SDK defaults to 'legacy'; we default to 'auto' so callers reach both
+        // 2025-era and 2026-07-28 servers without configuring anything.
+        //
+        // `inputRequired` is deliberately left unset: its defaults (auto-fulfil on,
+        // 10 rounds) are what we want, and pinning them here would freeze values
+        // the SDK may tune.
+        versionNegotiation: {
+            mode: options.protocolNegotiation ?? 'auto',
+            probe: {
+                timeoutMs: options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+            },
+        },
     });
-    client.setRequestHandler(ElicitRequestSchema, makeElicitationRequestHandler(options.onElicitation));
-    client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+    // Method-name-first in SDK v2; spec methods supply their own schema. This one
+    // handler serves both protocol eras: on 2025-era connections the server sends
+    // `elicitation/create` directly, and on 2026-07-28 the multi-round-trip driver
+    // dispatches `input_required` through this same handler, then retries the
+    // original call with the collected `inputResponses`.
+    client.setRequestHandler('elicitation/create', makeElicitationRequestHandler(options.onElicitation));
+    // Kept as a notification handler rather than `ClientOptions.listChanged`: the
+    // latter re-lists tools itself, duplicating the handle's own `refresh()` and
+    // its cache write. Notification handlers are era-transparent.
+    client.setNotificationHandler('notifications/tools/list_changed', () => {
         listChanged.handler?.();
     });
     return client;
 }
-async function connectWith(client, transport) {
-    if (!isTransport(transport)) {
-        throw new MCPConnectionError('MCP transport does not implement the Transport contract');
-    }
-    await client.connect(transport);
-}
 /**
- * Connect a `Client` to the MCP server. Defaults to Streamable HTTP and falls
- * back to SSE on connection failure (legacy servers), unless a transport is
- * pinned explicitly. Auth, the elicitation handler, and the list_changed
- * subscription are wired into the single connected client so they apply to
- * discovery and every tool call.
+ * Connect a `Client` to the MCP server.
+ *
+ * Defaults to Streamable HTTP and falls back to SSE on connection failure
+ * (legacy servers), unless a transport is pinned explicitly. Auth, the
+ * elicitation handler, and the list_changed subscription are wired into the
+ * single connected client so they apply to discovery and every tool call.
+ *
+ * When the caller does not set `protocolNegotiation`, a failed connect is
+ * retried once with `'legacy'` — see {@link connect} below, which owns that
+ * policy; this function performs exactly one negotiation mode.
  */
-export async function connect(options) {
+async function connectWithNegotiation(options) {
     const preferred = options.transport ?? 'streamableHttp';
     const listChanged = {
         handler: undefined,
     };
     if (preferred === 'sse') {
         const client = makeClient(options, listChanged);
-        await connectWith(client, buildSse(options));
+        try {
+            await client.connect(buildSse(options), connectRequestOptions(options));
+        }
+        catch (sseErr) {
+            // Same transport-release reason as the Streamable HTTP path below.
+            await closeQuietly(client);
+            // Wrapped like every other path. Rethrowing raw here made the error type a
+            // caller sees depend on whether `protocolNegotiation` happened to be set —
+            // unset, the outer retry aggregated it into an `MCPConnectionError`; set, the
+            // transport error escaped. Same server, same failure, different `catch`.
+            throw new MCPConnectionError('Failed to connect over SSE', {
+                cause: sseErr,
+            });
+        }
         return wrap({
             client,
             transport: 'sse',
@@ -97,7 +177,7 @@ export async function connect(options) {
     const client = makeClient(options, listChanged);
     try {
         const http = buildStreamableHttp(options);
-        await connectWith(client, http);
+        await client.connect(http, connectRequestOptions(options));
         return wrap({
             client,
             transport: 'streamableHttp',
@@ -108,15 +188,42 @@ export async function connect(options) {
         });
     }
     catch (httpErr) {
-        if (options.transport === 'streamableHttp') {
+        // Release the failed client's transport. The SDK cleans up after a failed
+        // probe or `initialize` handshake, but not when `transport.start()` itself
+        // throws: the base connect stores the transport before starting it and
+        // propagates without teardown, leaving a keep-alive socket open. Releasing
+        // unconditionally is safe on the paths the SDK already handles — see
+        // `closeQuietly`, which tolerates any close outcome rather than depending on
+        // what the SDK does internally.
+        await closeQuietly(client);
+        if (options.transport === 'streamableHttp' || isAuthFailure(httpErr, options.auth)) {
+            // Auth failures stop here rather than falling through. The SSE attempt
+            // would carry the same `authProvider` into the SDK's auth path — a second
+            // `redirectToAuthorization`, a second `saveCodeVerifier` overwriting the
+            // first — which is the duplicated side effect `connect()`'s retry guard
+            // exists to prevent. Guarding one and not the other left the hazard inside
+            // a single pass, where it is arguably worse: the caller did not even opt
+            // into a second negotiation mode.
+            throw new MCPConnectionError('Failed to connect over Streamable HTTP', {
+                cause: httpErr,
+            });
+        }
+        // An aborted caller gets no fallback: the same signal rides into the SSE
+        // attempt, but whether it interrupts `transport.start()` promptly is the
+        // SDK's business — checking here makes "abort means stop dialling"
+        // deterministic instead of dependent on where the SDK polls the signal.
+        if (options.signal?.aborted === true) {
             throw new MCPConnectionError('Failed to connect over Streamable HTTP', {
                 cause: httpErr,
             });
         }
         // Fall back to SSE on a fresh client (the failed one may be half-initialized).
+        // Under `'auto'` this re-probes, so a probe-hostile server fails here too —
+        // which is why `connect()` retries the whole thing under `'legacy'` when the
+        // caller did not pin a negotiation mode.
         const sseClient = makeClient(options, listChanged);
         try {
-            await connectWith(sseClient, buildSse(options));
+            await sseClient.connect(buildSse(options), connectRequestOptions(options));
             return wrap({
                 client: sseClient,
                 transport: 'sse',
@@ -124,8 +231,231 @@ export async function connect(options) {
             });
         }
         catch (sseErr) {
+            await closeQuietly(sseClient);
+            // Both failures are kept. `sseErr` is the `cause` because it is the last
+            // thing tried, but discarding `httpErr` loses information the caller needs:
+            // an `UnauthorizedError` from the HTTP attempt is what tells `connect()` not
+            // to retry, and a 404/405 from an endpoint that simply isn't an SSE URL
+            // would otherwise hide it. `errors` matches `AggregateError`'s shape so the
+            // pair is discoverable without a bespoke field.
             throw new MCPConnectionError('Failed to connect over Streamable HTTP and SSE', {
                 cause: sseErr,
+                errors: [
+                    httpErr,
+                    sseErr,
+                ],
+            });
+        }
+    }
+}
+/**
+ * Reduce one pass's failure to the list of attempts behind it.
+ *
+ * A pass that tried both transports is already an `MCPConnectionError` carrying
+ * them in `errors`; unwrapping keeps `errors` a flat list of real attempts rather
+ * than a tree of wrappers, so a caller can iterate it without recursing. A pass
+ * that tried one transport contributes itself.
+ */
+function flattenAttempts(err) {
+    if (err instanceof MCPConnectionError) {
+        if (err.errors.length > 0) {
+            return err.errors;
+        }
+        // A single-transport pass wraps its one failure with only `cause` set, so
+        // returning it as-is would put an opaque wrapper in a list documented as
+        // holding real attempts — and a caller scanning for a rejected token would
+        // have to know to dig through `cause` on some entries but not others.
+        if (err.cause !== undefined) {
+            return [
+                err.cause,
+            ];
+        }
+    }
+    return [
+        err,
+    ];
+}
+/**
+ * Does this error carry an HTTP status that means "your credentials were the
+ * problem"?
+ *
+ * 401 only, deliberately. The suppression this feeds exists to avoid re-driving
+ * OAuth side effects, and in SDK v2 those side effects (`saveCodeVerifier`,
+ * `redirectToAuthorization`) live exclusively behind the transport's
+ * `status === 401 && this._authProvider` branch — a 403 never enters the OAuth
+ * flow at all. Meanwhile proxies and WAFs commonly answer an unknown method
+ * like `server/discover` with 403 without consulting credentials, so treating
+ * 403 as a credential rejection made exactly the deployments the legacy retry
+ * exists to rescue permanently unreachable, for OAuth users only. A 403 retry
+ * re-drives nothing; a 401 retry re-drives the flow. Match the side effect,
+ * not the status class.
+ *
+ * Read via a duck-typed `status` rather than `instanceof SdkHttpError` plus an
+ * `SdkErrorCode` comparison: the numeric status is the stable half of that
+ * contract, and it also catches a gateway surfacing 401 in some other error
+ * shape.
+ *
+ * Only consulted when the caller configured OAuth — see {@link isAuthFailure}.
+ */
+function isAuthStatus(err) {
+    // Errors only. A plain object carrying a `status` is far more likely to be a
+    // response, a log record, or some other payload that happens to travel in a
+    // `cause` than an authoritative rejection — the SDK itself builds log entries
+    // with `status: 0`, and treating one of those as a credential failure would
+    // silently suppress the retry and make a probe-hostile server unreachable.
+    if (!(err instanceof Error) || !('status' in err)) {
+        return false;
+    }
+    const { status } = err;
+    return status === 401;
+}
+/**
+ * Did any attempt behind this failure end in the server rejecting our
+ * credentials?
+ *
+ * Searches the whole tree rather than the `cause` spine, because a single
+ * `connect()` can fail more than once: `connectWithNegotiation` wraps transport
+ * errors in `MCPConnectionError`, and on the two-transport path it records both
+ * attempts in `errors`. Checking only `cause` would miss an `UnauthorizedError`
+ * from the Streamable HTTP attempt whenever the SSE fallback then failed for an
+ * unrelated reason — a URL that isn't an SSE endpoint answering 404 never
+ * reaches the auth path — and the retry would re-drive the OAuth flow anyway.
+ *
+ * Depth-capped: a cyclic `cause` would otherwise hang, and real chains here are
+ * two or three links.
+ *
+ * Exported for `rehydrateMCPTools`, whose fallback-to-`freshConnect` is a third
+ * reconnect layer with the same duplicated-OAuth hazard; deliberately not
+ * re-exported from the package entrypoint.
+ */
+export function isAuthFailure(err, auth, depth = 0) {
+    if (depth >= 8) {
+        return false;
+    }
+    // `UnauthorizedError` is unconditional: the SDK only throws it from the
+    // provider-wrapped fetch and the authorization flow itself, so it inherently
+    // means an OAuth provider is in play and its flow would be re-driven.
+    if (err instanceof UnauthorizedError) {
+        return true;
+    }
+    // A bare 401 status counts only when the caller configured OAuth — the one
+    // auth kind where a 401 retry has side effects (a second
+    // `redirectToAuthorization`, an overwritten PKCE verifier). 403 never
+    // suppresses, even under OAuth: the SDK's PKCE writes live exclusively behind
+    // its 401 branch, so a 403 retry re-drives nothing — while proxies and WAFs
+    // commonly answer an unknown method like `server/discover` with 403, exactly
+    // the probe-hostile infrastructure the retry exists to rescue. With bearer,
+    // headers, or no auth, no status suppresses.
+    if (isOAuthAuth(auth) && isAuthStatus(err)) {
+        return true;
+    }
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    // Covers our own `errors` and `AggregateError`'s alike — Node's
+    // happy-eyeballs path and some fetch implementations report a 401 as an
+    // `AggregateError` member rather than as a `cause`, which a spine-only walk
+    // would miss.
+    const { errors } = err;
+    if (Array.isArray(errors)) {
+        for (const nested of errors) {
+            if (isAuthFailure(nested, auth, depth + 1)) {
+                return true;
+            }
+        }
+    }
+    return err.cause !== undefined && isAuthFailure(err.cause, auth, depth + 1);
+}
+/**
+ * Connect a `Client` to the MCP server, degrading to the 2025-era handshake if
+ * protocol negotiation gets in the way.
+ *
+ * We default `protocolNegotiation` to `'auto'` where the SDK defaults to
+ * `'legacy'`, so every connection's first request is a `server/discover` probe.
+ * On its own that would be a connectivity regression: a proxy, WAF, or strict
+ * gateway that hangs or 5xx's on an unknown method takes a server from working
+ * to failing, and the SSE fallback re-probes and fails identically — so the
+ * two-transport fallback, which looks like defense in depth, collapses to a
+ * single point of failure against exactly the infrastructure it should rescue.
+ *
+ * So when the caller left `protocolNegotiation` unset, a failed connect is
+ * retried once with `'legacy'`. That makes `'auto'` strictly additive: modern
+ * servers get the new revision, everything else lands exactly where it did
+ * before this package started probing. The cost is one extra attempt on a path
+ * that is already failing, which is where latency matters least.
+ *
+ * The retry fires on **any** failure rather than only on ones that look like
+ * probe timeouts. Inspecting the cause would avoid a wasted attempt against a
+ * genuinely dead server, but it would couple this to SDK error codes — and a
+ * reshaped error would silently disable the degradation, which is the failure
+ * mode this package keeps getting bitten by.
+ *
+ * Two bounds keep the retry from making a bad situation worse:
+ *
+ * 1. **It is skipped on an auth failure.** `UnauthorizedError` means the
+ *    transport reached the server and the credentials were rejected — nothing a
+ *    different protocol revision changes. Retrying would re-drive the OAuth
+ *    provider's authorization flow: a second `redirectToAuthorization`, a second
+ *    saved PKCE verifier overwriting the first. Replaying a failure that had
+ *    side effects is worse than not retrying.
+ * 2. **It re-walks the same transport ladder the first pass did.** An earlier
+ *    revision pinned Streamable HTTP to cap the attempt count, which broke the
+ *    case this whole mechanism exists for: a legacy server reachable *only* over
+ *    SSE, behind infrastructure that chokes on the probe, would fail under
+ *    `'auto'` and then never be offered SSE again. Correctness wins over the
+ *    attempt count here — a server that used to connect must still connect.
+ *
+ * So the worst case for a genuinely unreachable server is four `connect()`
+ * calls, two per negotiation mode. That is the honest cost of guaranteeing no
+ * working setup regresses, and it is paid only on a path that was already going
+ * to fail. The bound that matters is that it is a fixed multiple rather than a
+ * retry loop.
+ *
+ * An **explicit** `protocolNegotiation` is honoured exactly, including
+ * `'auto'`: asking for a mode means asking for its failures too, and silently
+ * ignoring a caller's `{ pin }` would defeat the point of pinning.
+ */
+export async function connect(options) {
+    if (options.protocolNegotiation !== undefined) {
+        return connectWithNegotiation(options);
+    }
+    try {
+        return await connectWithNegotiation(options);
+    }
+    catch (autoErr) {
+        // A caller-initiated abort is not a server problem: retrying under
+        // `'legacy'` would immediately re-abort (or worse, outlive the caller's
+        // deadline). Surface the abort as-is.
+        if (options.signal?.aborted === true) {
+            throw autoErr;
+        }
+        if (isAuthFailure(autoErr, options.auth)) {
+            throw autoErr;
+        }
+        // Not inspecting the error for *whether* the probe was at fault: that would
+        // couple us to SDK error codes, and a reshaped error would silently disable
+        // the whole degradation. `UnauthorizedError` above is the one exception,
+        // because there the cost of retrying is a duplicated side effect rather than
+        // a wasted dial — and if that check ever stops matching we merely retry,
+        // which is the pre-existing behavior rather than a silent loss of function.
+        try {
+            return await connectWithNegotiation({
+                ...options,
+                protocolNegotiation: 'legacy',
+            });
+        }
+        catch (legacyErr) {
+            // Carry both passes. Letting `legacyErr` propagate untouched would drop
+            // everything the `'auto'` pass learned — up to half the attempts, and any
+            // auth-shaped rejection that `isAuthFailure` did not match — which would
+            // also make `MCPConnectionError.errors` a lie about being every failure in
+            // attempt order.
+            throw new MCPConnectionError('Failed to connect over any transport or protocol revision', {
+                cause: legacyErr,
+                errors: [
+                    ...flattenAttempts(autoErr),
+                    ...flattenAttempts(legacyErr),
+                ],
             });
         }
     }

package/esm/mcp-connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-connection.js","sourceRoot":"","sources":["../src/mcp-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,iFAAiF;AACjF,+DAA+D;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAEnG,OAAO,EACL,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,mBAAmB,GAAG;IAC1B,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,OAAO;CACjB,CAAC;AA2BF,SAAS,mBAAmB,CAAC,OAAuB;IAClD,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,IAAI,6BAA6B,CAAC,OAAO,CAAC,GAAG,EAAE;QACpD,WAAW,EAAE;YACX,OAAO;SACR;QACD,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI;YAChC,YAAY;SACb,CAAC;QACF,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI;YACjC,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC;QACF,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI;YACrC,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC;KACH,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,OAAuB;IACvC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,GAAG,EAAE;QACzC,WAAW,EAAE;YACX,OAAO;SACR;QACD,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI;YAChC,YAAY;SACb,CAAC;QACF,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI;YACjC,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC;KACH,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,KAAwD;IAC3E,OAAO,CACL,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU;QACjC,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU;QAChC,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,CAClC,CAAC;AACJ,CAAC;AAMD,SAAS,UAAU,CAAC,OAAuB,EAAE,WAA+B;IAC1E,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,mBAAmB,EAAE;QACnE,YAAY,EAAE;YACZ,WAAW,EAAE,EAAE;SAChB;KACF,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CACtB,mBAAmB,EACnB,6BAA6B,CAAC,OAAO,CAAC,aAAa,CAAC,CACrD,CAAC;IAEF,MAAM,CAAC,sBAAsB,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACpE,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,MAAc,EACd,SAA6D;IAE7D,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,kBAAkB,CAAC,yDAAyD,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAuB;IACnD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAC;IACxD,MAAM,WAAW,GAAuB;QACtC,OAAO,EAAE,SAAS;KACnB,CAAC;IAEF,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAChD,MAAM,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;YACV,MAAM;YACN,SAAS,EAAE,KAAK;YAChB,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;IAED,uEAAuE;IACvE,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;YACV,MAAM;YACN,SAAS,EAAE,gBAAgB;YAC3B,WAAW;YACX,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI;gBAClC,SAAS,EAAE,IAAI,CAAC,SAAS;aAC1B,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,OAAO,EAAE,CAAC;QACjB,IAAI,OAAO,CAAC,SAAS,KAAK,gBAAgB,EAAE,CAAC;YAC3C,MAAM,IAAI,kBAAkB,CAAC,wCAAwC,EAAE;gBACrE,KAAK,EAAE,OAAO;aACf,CAAC,CAAC;QACL,CAAC;QACD,+EAA+E;QAC/E,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC;gBACV,MAAM,EAAE,SAAS;gBACjB,SAAS,EAAE,KAAK;gBAChB,WAAW;aACZ,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,kBAAkB,CAAC,gDAAgD,EAAE;gBAC7E,KAAK,EAAE,MAAM;aACd,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC;AASD,SAAS,IAAI,CAAC,IAAc;IAC1B,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3D,OAAO;QACL,MAAM;QACN,SAAS;QACT,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI;YAC7B,SAAS;SACV,CAAC;QACF,yBAAyB,EAAE,CAAC,OAAmB,EAAE,EAAE;YACjD,WAAW,CAAC,OAAO,GAAG,OAAO,CAAC;QAChC,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mcp-connection.js","sourceRoot":"","sources":["../src/mcp-connection.ts"],"names":[],"mappings":"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"}

package/esm/rehydrate.d.ts

@@ -2,7 +2,7 @@ import type { MCPAuth } from './auth/auth-types.js';
 import type { MCPCacheStore } from './cache/cache-store.js';
 import type { SerializedMCPServer } from './cache/cache-types.js';
 import type { UnconvertibleSchemaMode } from './schema/json-schema-to-zod.js';
-import type { ElicitationHandler, MCPToolsHandle, ResourcesOption } from './types.js';
+import type { CreateMCPToolsOptions, ElicitationHandler, MCPProtocolNegotiation, MCPToolsHandle, ResourcesOption } from './types.js';
 export interface RehydrateMCPToolsOptions {
     snapshot: SerializedMCPServer;
     /** Required when the snapshot carries no cached credentials. */
@@ -11,18 +11,49 @@ export interface RehydrateMCPToolsOptions {
     onUnconvertibleSchema?: UnconvertibleSchemaMode;
     onElicitation?: ElicitationHandler;
     signal?: AbortSignal;
-    /** Cache to refresh on reconnect/fallback. */
+    /** Protocol-revision negotiation policy; defaults to `'auto'`. */
+    protocolNegotiation?: MCPProtocolNegotiation;
+    /** Ceiling on the `server/discover` probe, in ms; defaults to 30000. */
+    probeTimeoutMs?: number;
+    /** Re-list tools instead of replaying a snapshot older than this. */
+    staleness?: {
+        maxAgeMs?: number;
+    };
+    /**
+     * Cache to refresh on reconnect/fallback.
+     *
+     * A successful replay does **not** write here — the snapshot it would write is
+     * the one you passed in, so the write is skipped as a no-op. The store is
+     * written when something genuinely new exists: a `refresh()`, a
+     * `tools/list_changed` auto-refresh, or the fresh-connect fallback. To seed a
+     * store from a snapshot obtained elsewhere, write it yourself
+     * (`store.set(key, snapshot)`) or call `handle.refresh()` after rehydrating.
+     */
     cache?: {
         store: MCPCacheStore;
         key?: string;
     };
-    /** On expiry / missing creds / connection failure, do a full reconnect. Default true. */
+    /**
+     * On expired cached tokens, missing credentials, an over-age snapshot
+     * (`staleness.maxAgeMs`), or a replay connection failure, transparently fall
+     * back to a full fresh connect. Default true.
+     *
+     * The fallback is skipped when the replay's connect ended in a credential
+     * rejection (the SDK's `UnauthorizedError`, or a 401 status when an OAuth
+     * provider is configured): the fallback reuses the same auth, so retrying
+     * cannot succeed and would re-drive an OAuth authorization flow. Those
+     * failures reject with `MCPCacheError` instead. A 403 does not skip it — the
+     * SDK's OAuth side effects only occur on 401, and gateways commonly answer
+     * unknown methods with 403.
+     */
     reconnectOnExpiry?: boolean;
     toolNamePrefix?: string;
     includeTools?: readonly string[];
     excludeTools?: readonly string[];
     resources?: ResourcesOption;
     emitProgress?: boolean;
+    /** Doom-loop identities for wrapped tools, keyed by unprefixed MCP name. */
+    loopKeys?: CreateMCPToolsOptions['loopKeys'];
     autoRefreshOnListChanged?: boolean;
     cacheCredentials?: boolean;
     clientInfo?: {
@@ -34,8 +65,12 @@ export interface RehydrateMCPToolsOptions {
  * Rebuild an {@link MCPToolsHandle} from a cached snapshot. On the happy path we
  * reconnect the transport and rebuild tools directly from the snapshot —
  * skipping `listTools()`. If cached tokens are expired, credentials are missing,
- * or the connection fails, we transparently fall back to a full
- * {@link createMCPTools} (unless `reconnectOnExpiry` is false).
+ * the snapshot is older than `staleness.maxAgeMs`, or the replay connection
+ * fails, we transparently fall back to a fresh connect (unless
+ * `reconnectOnExpiry` is false) — with one exception: a credential rejection is
+ * not retried, because the fallback reuses the same auth and re-attempting
+ * would re-drive an OAuth authorization flow. See {@link
+ * RehydrateMCPToolsOptions.reconnectOnExpiry}.
  */
 export declare function rehydrateMCPTools(options: RehydrateMCPToolsOptions): Promise<MCPToolsHandle>;
 //# sourceMappingURL=rehydrate.d.ts.map

package/esm/rehydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../src/rehydrate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAKlE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,KAAK,EAEV,kBAAkB,EAClB,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;IAChD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8CAA8C;IAC9C,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,aAAa,CAAC;QACrB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAG5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AA2GD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,CA+DzB"}
+{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../src/rehydrate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAOlE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;IAChD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;IAC7C,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,SAAS,CAAC,EAAE;QACV,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,aAAa,CAAC;QACrB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAG5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC7C,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAoaD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,CAgHzB"}