creditkarma-mcp 2.0.10 → 2.2.0

package/README.md

@@ -23,6 +23,28 @@ Ask Claude things like:
 - A Credit Karma account
 - For the no-env-var path: the [fetchproxy 0.3.0 Chrome / Safari extension](https://github.com/chrischall/fetchproxy)
 
+## Acknowledgement of Terms
+
+By using this MCP server, you acknowledge and agree to the following:
+
+**1. This server accesses your own Credit Karma account.** Every request is dispatched through your own signed-in browser tab via the fetchproxy extension. **You** are the one logged in. It does not — and cannot — access anyone else's account.
+
+**2. [Credit Karma's Terms](https://www.creditkarma.com/about/terms) govern your use of this server**, just as they govern your direct use of creditkarma.com. The clauses most relevant here:
+
+> You must not sell, transfer, or assign your account to anyone else… you may not allow anyone else to log into our Services as you.
+
+CK does contemplate third-party data retrieval at the user's direction (Section 3.7). There is no explicit anti-scraping clause in the membership agreement; Section 4.1 restricts copying or distributing CK content without express prior written consent.
+
+You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Critically: this server runs **as you**, not as a third party logging in on your behalf. You direct the tool.
+
+**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Intuit, Credit Karma, or any financial institution. It is a personal automation tool that reads your transaction history, spending categories, and account snapshots — the same data Credit Karma already shows you in their app. Do not use it on someone else's account, do not redistribute their content, and do not use it to make trading or lending decisions on behalf of others.
+
+**4. This server may break.** Credit Karma rotates its internal endpoints; what works today may 404 tomorrow. This is the nature of unofficial integrations.
+
+**5. You accept full responsibility** for any consequences of using this server in connection with your Credit Karma account — rate limiting, account warnings, suspension, or any enforcement action Intuit takes. If Credit Karma objects to your use, stop using this server. **Do not commit your `.env` to git** — your CK session/auth artifacts are credentials, and the Membership Agreement holds you responsible for their confidentiality.
+
+This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Credit Karma's actual Membership Agreement.
+
 ## Installation
 
 ### 1. Clone and build

package/dist/auth.js

@@ -58,6 +58,7 @@
 //     `src/tools/auth.ts` extracts the CKAT JWTs the same way it does
 //     today.
 import { bootstrap } from '@fetchproxy/bootstrap';
+import { classifyBridgeError } from '@fetchproxy/server';
 import pkg from '../package.json' with { type: 'json' };
 import { extractCookieValue } from './client.js';
 /**
@@ -143,6 +144,18 @@ export async function resolveAuth() {
             return { cookies, source: 'fetchproxy' };
         }
         catch (e) {
+            // 0.8.0+ typed-error discrimination. The fetchproxy server already
+            // retries once on SW eviction (bridgeReviveDelayMs=2000 default), so
+            // a thrown FetchproxyBridgeDownError means the retry also failed —
+            // the extension's service worker is genuinely down and the user
+            // needs to wake it. The `.hint` is the actionable copy
+            // ("click the extension toolbar icon...") that we'd otherwise have
+            // to hand-write here. Surface it verbatim so users in path 3 get
+            // the same self-service guidance as path 4.
+            if (classifyBridgeError(e) === 'bridge_down') {
+                const downErr = e;
+                throw new Error(`CK auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`);
+            }
             const msg = e instanceof Error ? e.message : String(e);
             throw new Error(`CK auth: no CK_COOKIES set, and fetchproxy fallback failed: ${msg}`);
         }

package/dist/bundle.js

@@ -7658,6 +7658,10 @@ var require_receiver = __commonJS({
        *     extensions
        * @param {Boolean} [options.isServer=false] Specifies whether to operate in
        *     client or server mode
+       * @param {Number} [options.maxBufferedChunks=0] The maximum number of
+       *     buffered data chunks
+       * @param {Number} [options.maxFragments=0] The maximum number of message
+       *     fragments
        * @param {Number} [options.maxPayload=0] The maximum allowed message length
        * @param {Boolean} [options.skipUTF8Validation=false] Specifies whether or
        *     not to skip UTF-8 validation for text and close messages
@@ -7668,6 +7672,8 @@ var require_receiver = __commonJS({
         this._binaryType = options.binaryType || BINARY_TYPES[0];
         this._extensions = options.extensions || {};
         this._isServer = !!options.isServer;
+        this._maxBufferedChunks = options.maxBufferedChunks | 0;
+        this._maxFragments = options.maxFragments | 0;
         this._maxPayload = options.maxPayload | 0;
         this._skipUTF8Validation = !!options.skipUTF8Validation;
         this[kWebSocket] = void 0;
@@ -7697,6 +7703,18 @@ var require_receiver = __commonJS({
        */
       _write(chunk, encoding, cb) {
         if (this._opcode === 8 && this._state == GET_INFO) return cb();
+        if (this._maxBufferedChunks > 0 && this._buffers.length >= this._maxBufferedChunks) {
+          cb(
+            this.createError(
+              RangeError,
+              "Too many buffered chunks",
+              false,
+              1008,
+              "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+            )
+          );
+          return;
+        }
         this._bufferedBytes += chunk.length;
         this._buffers.push(chunk);
         this.startLoop(cb);
@@ -8026,6 +8044,17 @@ var require_receiver = __commonJS({
           return;
         }
         if (data.length) {
+          if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
+            const error51 = this.createError(
+              RangeError,
+              "Too many message fragments",
+              false,
+              1008,
+              "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+            );
+            cb(error51);
+            return;
+          }
           this._messageLength = this._totalPayloadLength;
           this._fragments.push(data);
         }
@@ -8055,6 +8084,17 @@ var require_receiver = __commonJS({
               cb(error51);
               return;
             }
+            if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
+              const error51 = this.createError(
+                RangeError,
+                "Too many message fragments",
+                false,
+                1008,
+                "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+              );
+              cb(error51);
+              return;
+            }
             this._fragments.push(buf);
           }
           this.dataMessage(cb);
@@ -9261,6 +9301,10 @@ var require_websocket = __commonJS({
        *     multiple times in the same tick
        * @param {Function} [options.generateMask] The function used to generate the
        *     masking key
+       * @param {Number} [options.maxBufferedChunks=0] The maximum number of
+       *     buffered data chunks
+       * @param {Number} [options.maxFragments=0] The maximum number of message
+       *     fragments
        * @param {Number} [options.maxPayload=0] The maximum allowed message size
        * @param {Boolean} [options.skipUTF8Validation=false] Specifies whether or
        *     not to skip UTF-8 validation for text and close messages
@@ -9272,6 +9316,8 @@ var require_websocket = __commonJS({
           binaryType: this.binaryType,
           extensions: this._extensions,
           isServer: this._isServer,
+          maxBufferedChunks: options.maxBufferedChunks,
+          maxFragments: options.maxFragments,
           maxPayload: options.maxPayload,
           skipUTF8Validation: options.skipUTF8Validation
         });
@@ -9571,6 +9617,8 @@ var require_websocket = __commonJS({
         autoPong: true,
         closeTimeout: CLOSE_TIMEOUT,
         protocolVersion: protocolVersions[1],
+        maxBufferedChunks: 1024 * 1024,
+        maxFragments: 128 * 1024,
         maxPayload: 100 * 1024 * 1024,
         skipUTF8Validation: false,
         perMessageDeflate: true,
@@ -9813,6 +9861,8 @@ var require_websocket = __commonJS({
         websocket.setSocket(socket, head, {
           allowSynchronousEvents: opts.allowSynchronousEvents,
           generateMask: opts.generateMask,
+          maxBufferedChunks: opts.maxBufferedChunks,
+          maxFragments: opts.maxFragments,
           maxPayload: opts.maxPayload,
           skipUTF8Validation: opts.skipUTF8Validation
         });
@@ -10155,6 +10205,10 @@ var require_websocket_server = __commonJS({
        *     called
        * @param {Function} [options.handleProtocols] A hook to handle protocols
        * @param {String} [options.host] The hostname where to bind the server
+       * @param {Number} [options.maxBufferedChunks=1048576] The maximum number of
+       *     buffered data chunks
+       * @param {Number} [options.maxFragments=131072] The maximum number of message
+       *     fragments
        * @param {Number} [options.maxPayload=104857600] The maximum allowed message
        *     size
        * @param {Boolean} [options.noServer=false] Enable no server mode
@@ -10176,6 +10230,8 @@ var require_websocket_server = __commonJS({
         options = {
           allowSynchronousEvents: true,
           autoPong: true,
+          maxBufferedChunks: 1024 * 1024,
+          maxFragments: 128 * 1024,
           maxPayload: 100 * 1024 * 1024,
           skipUTF8Validation: false,
           perMessageDeflate: false,
@@ -10455,6 +10511,8 @@ var require_websocket_server = __commonJS({
         socket.removeListener("error", socketOnError);
         ws.setSocket(socket, head, {
           allowSynchronousEvents: this.options.allowSynchronousEvents,
+          maxBufferedChunks: this.options.maxBufferedChunks,
+          maxFragments: this.options.maxFragments,
           maxPayload: this.options.maxPayload,
           skipUTF8Validation: this.options.skipUTF8Validation
         });
@@ -34974,6 +35032,7 @@ function registerAuthTools(server, ctx) {
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
 var PROTOCOL_VERSION = 2;
+var HKDF_SESSION_INFO = "fetchproxy/1.0.0/session";
 var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "fetch",
   "read_cookies",
@@ -35048,7 +35107,7 @@ var ProtocolError = class extends Error {
 var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 var BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 var SCOPE_KEY_RE = /^[A-Za-z0-9_.\-]{1,256}$/;
-var SCOPE_KEY_GLOB_RE = /^[A-Za-z0-9_.\-]{1,255}\*?$/;
+var SCOPE_KEY_GLOB_RE = /^[A-Za-z0-9_.\-]{1,256}\*?$/;
 var HEADER_NAME_RE = /^[A-Za-z0-9_\-]{1,128}$/;
 var HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
 function assertObject(x, label) {
@@ -35177,7 +35236,7 @@ function assertStoragePointersArray(value, label, declaredKeys) {
     if (entry.jsonPointer === void 0) {
       throw new ProtocolError(`${label}[${i}].jsonPointer: missing`);
     }
-    if (typeof entry.key !== "string" || !SCOPE_KEY_GLOB_RE.test(entry.key)) {
+    if (typeof entry.key !== "string" || !SCOPE_KEY_RE.test(entry.key)) {
       throw new ProtocolError(`${label}[${i}].key: invalid key ${JSON.stringify(entry.key)}`);
     }
     if (typeof entry.jsonPointer !== "string" || !isValidJsonPointer(entry.jsonPointer)) {
@@ -35276,6 +35335,8 @@ function validateFrame(raw) {
     return validateReady(raw);
   if (t === "frame")
     return validateEncrypted(raw);
+  if (t === "pair-pending")
+    return validatePairPending(raw);
   throw new ProtocolError(`unknown frame type: ${String(t)}`);
 }
 function validateHello(raw) {
@@ -35377,6 +35438,17 @@ function validateEncrypted(raw) {
   assertBase64(raw.ciphertext, "frame.ciphertext");
   return raw;
 }
+var PAIR_CODE_RE = /^\d{3}-\d{3}$/;
+function validatePairPending(raw) {
+  assertString(raw.mcpId, "pair-pending.mcpId");
+  if (!isValidMcpId(raw.mcpId))
+    throw new ProtocolError("pair-pending.mcpId: invalid format");
+  assertString(raw.pairCode, "pair-pending.pairCode");
+  if (!PAIR_CODE_RE.test(raw.pairCode)) {
+    throw new ProtocolError(`pair-pending.pairCode: must match XXX-XXX, got ${String(raw.pairCode)}`);
+  }
+  return { type: "pair-pending", mcpId: raw.mcpId, pairCode: raw.pairCode };
+}
 function validateInnerFrame(raw) {
   assertObject(raw, "inner");
   const t = raw.type;
@@ -35959,15 +36031,22 @@ async function startHost(opts) {
   let extensionWs = null;
   const peers = /* @__PURE__ */ new Map();
   const ownInnerListeners = [];
+  const disconnectListeners = [];
+  const pendingPairListeners = [];
   let ownSession = null;
+  let ownPendingPairCode = null;
   let resolveOwnSession;
   let rejectOwnSession;
-  const ownSessionReady = new Promise((resolve, reject) => {
-    resolveOwnSession = resolve;
-    rejectOwnSession = reject;
-  });
-  ownSessionReady.catch(() => {
-  });
+  let ownSessionReady;
+  function resetSessionPromise() {
+    ownSessionReady = new Promise((resolve, reject) => {
+      resolveOwnSession = resolve;
+      rejectOwnSession = reject;
+    });
+    ownSessionReady.catch(() => {
+    });
+  }
+  resetSessionPromise();
   let extensionHello = null;
   wss.on("connection", (ws) => {
     let identified = null;
@@ -36036,11 +36115,12 @@ async function startHost(opts) {
             }
             const extPub = fromB64(frame.extensionSessionPub);
             const shared = await ecdhX25519(opts.ownIdentity.x25519Priv, extPub);
-            const key = await hkdfSha256(shared, ownSessionNonce, enc2.encode("fetchproxy/0.1.0/session"), 32);
-            if (!ownSession) {
-              ownSession = new SessionState(key);
-              resolveOwnSession(ownSession);
-            }
+            const key = await hkdfSha256(shared, ownSessionNonce, enc2.encode(HKDF_SESSION_INFO), 32);
+            if (extensionWs !== ws)
+              return;
+            ownSession = new SessionState(key);
+            ownPendingPairCode = null;
+            resolveOwnSession(ownSession);
           } else {
             const slot = peers.get(frame.mcpId);
             if (slot)
@@ -36067,6 +36147,16 @@ async function startHost(opts) {
               extensionWs.send(JSON.stringify(frame));
           }
         }
+        if (frame.type === "pair-pending" && identified === "extension") {
+          if (frame.mcpId === opts.ownMcpId) {
+            ownPendingPairCode = frame.pairCode;
+            pendingPairListeners.forEach((cb) => cb(frame.pairCode));
+          } else {
+            const slot = peers.get(frame.mcpId);
+            if (slot)
+              slot.ws.send(JSON.stringify(frame));
+          }
+        }
       } catch (e) {
         console.error("[fetchproxy] host: message handler error:", e);
         try {
@@ -36082,6 +36172,9 @@ async function startHost(opts) {
         if (!ownSession) {
           rejectOwnSession(new Error("extension disconnected before ready"));
         }
+        ownSession = null;
+        resetSessionPromise();
+        disconnectListeners.forEach((cb) => cb());
       }
       if (identified === "peer" && peerMcpId)
         peers.delete(peerMcpId);
@@ -36106,7 +36199,14 @@ async function startHost(opts) {
     },
     onOwnInner: (cb) => {
       ownInnerListeners.push(cb);
-    }
+    },
+    onExtensionDisconnect: (cb) => {
+      disconnectListeners.push(cb);
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => ownPendingPairCode
   };
 }
 
@@ -36136,36 +36236,57 @@ async function startPeer(opts) {
   const sessionNonce = fromB64(hello.sessionNonce);
   ws.send(JSON.stringify(hello));
   const innerListeners = [];
+  const renegotiateListeners = [];
+  const pendingPairListeners = [];
   let session = null;
+  let pendingPairCode = null;
+  let resolveFirstReady;
+  let rejectFirstReady;
   const sessionPromise = new Promise((resolve, reject) => {
-    const onMessage = async (data) => {
-      try {
-        const raw = JSON.parse(data.toString());
-        const frame = validateFrame(raw);
-        if (frame.type === "ready" && frame.mcpId === opts.mcpId) {
-          const extPub = fromB64(frame.extensionSessionPub);
-          const shared = await ecdhX25519(opts.identity.x25519Priv, extPub);
-          const sessionKey = await hkdfSha256(shared, sessionNonce, enc3.encode("fetchproxy/0.1.0/session"), 32);
-          session = new SessionState(sessionKey);
-          resolve(session);
-          return;
+    resolveFirstReady = resolve;
+    rejectFirstReady = reject;
+  });
+  const onMessage = async (data) => {
+    try {
+      const raw = JSON.parse(data.toString());
+      const frame = validateFrame(raw);
+      if (frame.type === "ready" && frame.mcpId === opts.mcpId) {
+        const extPub = fromB64(frame.extensionSessionPub);
+        const shared = await ecdhX25519(opts.identity.x25519Priv, extPub);
+        const sessionKey = await hkdfSha256(shared, sessionNonce, enc3.encode(HKDF_SESSION_INFO), 32);
+        const isRenegotiation = session !== null;
+        session = new SessionState(sessionKey);
+        pendingPairCode = null;
+        if (isRenegotiation) {
+          renegotiateListeners.forEach((cb) => cb());
+        } else {
+          resolveFirstReady(session);
         }
-        if (frame.type === "frame" && frame.mcpId === opts.mcpId) {
-          if (!session)
-            return;
-          if (!session.acceptInboundSeq(frame.seq))
-            return;
+        return;
+      }
+      if (frame.type === "pair-pending" && frame.mcpId === opts.mcpId) {
+        pendingPairCode = frame.pairCode;
+        pendingPairListeners.forEach((cb) => cb(frame.pairCode));
+        return;
+      }
+      if (frame.type === "frame" && frame.mcpId === opts.mcpId) {
+        if (!session)
+          return;
+        if (!session.acceptInboundSeq(frame.seq))
+          return;
+        try {
           const inner = await openEncryptedFrame(session.sessionKey, frame);
           innerListeners.forEach((cb) => cb(inner));
+        } catch {
         }
-      } catch (e) {
-        reject(e instanceof Error ? e : new Error(String(e)));
       }
-    };
-    ws.on("message", onMessage);
-    ws.once("close", () => {
-      reject(new Error("peer WS closed before ready"));
-    });
+    } catch (e) {
+      rejectFirstReady(e instanceof Error ? e : new Error(String(e)));
+    }
+  };
+  ws.on("message", onMessage);
+  ws.once("close", () => {
+    rejectFirstReady(new Error("peer WS closed before ready"));
   });
   sessionPromise.catch(() => {
   });
@@ -36173,13 +36294,21 @@ async function startPeer(opts) {
     ws,
     session: sessionPromise,
     sendInner: async (inner) => {
-      const s = await sessionPromise;
+      await sessionPromise;
+      const s = session;
       const sealed = await sealInnerFrame(s.sessionKey, opts.mcpId, s.nextOutboundSeq(), inner);
       ws.send(JSON.stringify(sealed));
     },
     onInner: (cb) => {
       innerListeners.push(cb);
     },
+    onRenegotiate: (cb) => {
+      renegotiateListeners.push(cb);
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => pendingPairCode,
     close: () => ws.close()
   };
   return handle;
@@ -36236,6 +36365,32 @@ async function loadOrCreateIdentity(serverName, dir = defaultIdentityDir()) {
   return id;
 }
 
+// node_modules/@fetchproxy/server/dist/error-kind.js
+function classifyFetchError(error51) {
+  if (/Could not establish connection/i.test(error51) || /Receiving end does not exist/i.test(error51)) {
+    return "content_script_unreachable";
+  }
+  if (/^tab fetch failed:/.test(error51)) {
+    return "tab_fetch_failed";
+  }
+  if (/^fetch threw:/.test(error51)) {
+    return "tab_fetch_failed";
+  }
+  if (/^no tab matching /.test(error51)) {
+    return "no_tab";
+  }
+  if (/not in domains \[/.test(error51)) {
+    return "domain_denied";
+  }
+  if (/^capability .+ not granted/.test(error51)) {
+    return "capability_denied";
+  }
+  if (/^(request|response) body too large:/.test(error51)) {
+    return "body_too_large";
+  }
+  return "other";
+}
+
 // node_modules/@fetchproxy/server/dist/ws-server.js
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
@@ -36251,6 +36406,52 @@ var FetchproxyHttpError = class extends Error {
     this.name = "FetchproxyHttpError";
   }
 };
+var FetchproxyBridgeDownError = class extends FetchproxyProtocolError {
+  originalError;
+  retryAttempted;
+  op;
+  url;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time (the same port `listen()` bound to). */
+  port;
+  hint;
+  constructor(args) {
+    const retryAttempted = args.retryAttempted ?? false;
+    const op = args.op ?? "fetch";
+    const retryClause = retryAttempted ? `Server already burned a one-shot lazy-revive retry; SW is still down. ` : `Server lazy-revive retry was disabled (bridgeReviveDelayMs unset/0). `;
+    const hint = `the fetchproxy extension's service worker is not responding ("${args.originalError}"). Chrome evicts extension service workers after ~30s idle by default. ${retryClause}Wake it by clicking the fetchproxy extension toolbar icon, then retry. If it keeps happening, reload the extension from chrome://extensions.`;
+    super(`fetchproxy bridge down during ${op}${args.url ? ` (${args.url})` : ""}. ${hint}`);
+    this.name = "FetchproxyBridgeDownError";
+    this.originalError = args.originalError;
+    this.retryAttempted = retryAttempted;
+    this.op = op;
+    if (args.url !== void 0)
+      this.url = args.url;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.hint = hint;
+  }
+};
+var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
+  url;
+  timeoutMs;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time. */
+  port;
+  /** 0.8.0+: actual elapsed milliseconds when the timer won the race. */
+  elapsedMs;
+  constructor(args) {
+    super(`fetchproxy: ${args.url} did not respond within ${args.timeoutMs}ms`);
+    this.name = "FetchproxyTimeoutError";
+    this.url = args.url;
+    this.timeoutMs = args.timeoutMs;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.elapsedMs = args.elapsedMs ?? args.timeoutMs;
+  }
+};
 var SUBDOMAIN_LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
 function assertSubdomainLabel(label) {
   if (!SUBDOMAIN_LABEL_RE.test(label)) {
@@ -36278,12 +36479,28 @@ function assertUrlInDomains(field, url2, domains) {
 }
 var DEFAULT_JSON_OK_STATUSES = [200, 201, 202, 204];
 var FetchproxyServer = class {
-  /** Set after `listen()` succeeds. Null while not listening. */
+  /**
+   * Bridge role. `null` until the first verb call (or an explicit
+   * `connect()`) — `listen()` no longer triggers the role election
+   * as of 0.5.3+. Reset to `null` on `close()`.
+   */
   role = null;
   opts;
   hostHandle = null;
   peerHandle = null;
   nextRequestId = 1;
+  // 0.8.0+: process-wide freshness counters surfaced via bridgeHealth().
+  // Replaces the local copies every downstream MCP was rolling on top
+  // of its own transport adapter — see realty-mcp cohort drift notes.
+  // Updated by recordSuccess / recordFailure from fetch + capture paths.
+  // `lastExtensionMessageAt` (#23 ask 4) is updated whenever any inner
+  // frame from the extension arrives — gives extension-side liveness
+  // distinct from per-call success/failure.
+  lastSuccessAt = null;
+  lastFailureAt = null;
+  lastFailureReason = null;
+  consecutiveFailures = 0;
+  lastExtensionMessageAt = null;
   pending = /* @__PURE__ */ new Map();
   // Separate pending map for read_cookies so the response shape (cookies
   // string vs status/body) doesn't have to share a union type with fetch.
@@ -36300,6 +36517,12 @@ var FetchproxyServer = class {
   pendingIdb = /* @__PURE__ */ new Map();
   mcpId = null;
   identity = null;
+  // 0.5.3+: in-flight role-election / handle-start promise. Set the
+  // first time a verb call runs `ensureConnected`, awaited by concurrent
+  // callers, cleared once the connection is up. Single source of truth
+  // for "we're connecting right now" so two parallel first-calls don't
+  // race the port bind.
+  connectingPromise = null;
   constructor(opts) {
     if (!Array.isArray(opts.domains) || opts.domains.length === 0) {
       throw new Error("FetchproxyServer: opts.domains must be a non-empty array of hostnames");
@@ -36346,28 +36569,98 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
+      // adapter was about to set these to the same numbers anyway; the
+      // back-door is `0` (explicit opt-out) if a caller genuinely wants
+      // the legacy hang-forever / fail-once-on-SW-eviction behavior.
+      fetchTimeoutMs: opts.fetchTimeoutMs ?? 3e4,
+      bridgeReviveDelayMs: opts.bridgeReviveDelayMs ?? 2e3,
       identityDir: opts.identityDir,
       onPairCode: opts.onPairCode
     };
   }
   /**
-   * Start the WebSocket bridge. Loads the long-term identity keypair
-   * from disk (creating it on first call), elects the host-vs-peer
-   * role by attempting to bind the configured port, and stands up the
-   * matching handshake machinery. Idempotent only insofar as it leaves
-   * `role` non-null on success; calling `listen()` twice without an
-   * intervening `close()` is a programming error.
+   * Prepare the bridge for use. Loads the long-term identity keypair
+   * from disk (creating it on first call) and computes this instance's
+   * `mcpId`. Does NOT bind the bridge port or dial any WebSocket — the
+   * connection is established lazily on the first verb call (see
+   * `ensureConnected` / `getOrConnect`).
+   *
+   * Pre-0.5.3 behavior: `listen()` also did role election and started
+   * the host/peer immediately, which meant every configured-but-unused
+   * MCP claimed bridge resources at MCP-client boot. Several MCPs
+   * starting in parallel under Claude Desktop also produced noisy
+   * `ERR_CONNECTION_REFUSED` errors in the extension if it raced ahead
+   * of the first MCP's port bind. Deferring keeps boot quiet and
+   * leaves the port unowned until something actually needs it.
+   *
+   * Calling `listen()` twice without an intervening `close()` is a
+   * no-op (the second call's identity load is idempotent).
    */
   async listen() {
-    this.identity = await loadOrCreateIdentity(this.opts.serverName, this.opts.identityDir);
-    this.mcpId = generateMcpId(this.opts.serverName, this.opts.version);
+    if (!this.identity) {
+      this.identity = await loadOrCreateIdentity(this.opts.serverName, this.opts.identityDir);
+    }
+    if (!this.mcpId) {
+      this.mcpId = generateMcpId(this.opts.serverName, this.opts.version);
+    }
+  }
+  /**
+   * Force an eager bridge connection (role-election + host/peer handle
+   * start + listener wiring) without waiting for the first verb call.
+   * Useful for callers that want to surface the role / connection
+   * outcome at boot, or for tests whose harness dials a mock extension
+   * immediately after server construction. Production MCPs that just
+   * answer tool calls should NOT call this — the lazy connect via
+   * `ensureConnected` will do the right thing on first use, keeping
+   * boot cheap and avoiding port-bind contention for MCPs that never
+   * actually get invoked.
+   *
+   * Idempotent: a second call after the first has resolved is a no-op
+   * (the existing handle is reused). Throws if `listen()` was never
+   * called.
+   */
+  async connect() {
+    await this.ensureConnected();
+  }
+  /**
+   * Establish the bridge connection (role-election + host/peer handle
+   * start + listener wiring) the first time a verb is invoked.
+   * Idempotent after the connection is up; concurrent first-callers
+   * share the same in-flight promise so only one election happens.
+   *
+   * Throws if `listen()` was never called — the contract is that the
+   * MCP author still must wire `transport.start()` at boot to load
+   * identity / set mcpId, even though the WS doesn't open until a
+   * verb runs.
+   */
+  async ensureConnected() {
+    if (this.hostHandle || this.peerHandle)
+      return;
+    if (this.connectingPromise) {
+      await this.connectingPromise;
+      return;
+    }
+    if (!this.identity || !this.mcpId) {
+      throw new Error("FetchproxyServer: ensureConnected called before listen() \u2014 call listen() at MCP boot to load identity");
+    }
+    this.connectingPromise = this.doConnect();
+    try {
+      await this.connectingPromise;
+    } finally {
+      this.connectingPromise = null;
+    }
+  }
+  async doConnect() {
+    const identity = this.identity;
+    const mcpId = this.mcpId;
     const el = await electRole({ host: this.opts.host, port: this.opts.port });
     if (el.role === "host") {
       this.role = "host";
       this.hostHandle = await startHost({
         httpServer: el.server,
-        ownIdentity: this.identity,
-        ownMcpId: this.mcpId,
+        ownIdentity: identity,
+        ownMcpId: mcpId,
         ownServerName: this.opts.serverName,
         ownVersion: this.opts.version,
         ownDomains: this.opts.domains,
@@ -36382,13 +36675,17 @@ var FetchproxyServer = class {
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
+      this.hostHandle.onExtensionDisconnect(() => this.rejectAllPending());
+      this.hostHandle.onPendingPair((code) => {
+        this.rejectAllPending(this.pairingErrorMessage(code));
+      });
     } else {
       this.role = "peer";
       this.peerHandle = await startPeer({
         host: this.opts.host,
         port: this.opts.port,
-        identity: this.identity,
-        mcpId: this.mcpId,
+        identity,
+        mcpId,
         serverName: this.opts.serverName,
         version: this.opts.version,
         domains: this.opts.domains,
@@ -36402,8 +36699,19 @@ var FetchproxyServer = class {
         sessionStoragePointers: this.opts.sessionStoragePointers
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
+      this.peerHandle.onRenegotiate(() => this.rejectAllPending());
+      this.peerHandle.onPendingPair((code) => {
+        this.rejectAllPending(this.pairingErrorMessage(code));
+      });
+      if (this.opts.onPairCode) {
+        const cb = this.opts.onPairCode;
+        this.peerHandle.onPendingPair((code) => cb(code));
+      }
     }
   }
+  pairingErrorMessage(code) {
+    return `fetchproxy transport error: pairing required for ${this.opts.serverName}. Tell the user to open the Transporter browser extension popup and approve the pair request. The pair code is: ${code} \u2014 display this code to the user so they can verify it matches.`;
+  }
   /**
    * Raw single-shot fetch through the bridge. Most callers should prefer
    * the verb shortcuts (`get` / `post` / `getJson` / `postJson` / `getHtml`)
@@ -36419,9 +36727,75 @@ var FetchproxyServer = class {
    * offline, etc.).
    */
   async fetch(init) {
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.fetch called before listen() \u2014 not listening");
+    await this.ensureConnected();
+    const pendingCode = this.currentPendingPairCode();
+    if (pendingCode !== null) {
+      const error51 = this.pairingErrorMessage(pendingCode);
+      return {
+        ok: false,
+        error: error51,
+        kind: classifyFetchError(error51),
+        retryAttempted: false
+      };
     }
+    const first = await this._fetchOnceWithTimeout(init);
+    const reviveMs = this.opts.bridgeReviveDelayMs;
+    let final = first;
+    if (!first.ok && first.kind === "content_script_unreachable" && reviveMs !== void 0 && reviveMs > 0) {
+      await new Promise((r) => setTimeout(r, reviveMs));
+      const second = await this._fetchOnceWithTimeout(init);
+      if (second.ok)
+        this.recordSuccess();
+      else
+        this.recordFailure(`${second.kind ?? "other"}: ${second.error}`);
+      return { ...second, retryAttempted: true };
+    }
+    if (first.ok)
+      this.recordSuccess();
+    else
+      this.recordFailure(`${first.kind ?? "other"}: ${first.error}`);
+    return { ...first, retryAttempted: false };
+  }
+  /**
+   * 0.8.0+: snapshot of the bridge's process-wide freshness counters,
+   * suitable for surfacing through a downstream MCP's healthcheck tool.
+   * Counters reset on a success (consecutiveFailures), accumulate
+   * across the process lifetime otherwise. Replaces the per-MCP
+   * duplication the realty cohort had been rolling in their adapters.
+   * `lastExtensionMessageAt` is updated whenever ANY inner frame
+   * arrives from the extension — gives extension-side liveness
+   * distinct from server-side success/failure of the user-visible
+   * call (addresses #23 ask 4).
+   */
+  bridgeHealth() {
+    return {
+      role: this.role,
+      port: this.opts.port,
+      serverVersion: this.opts.version,
+      fetchTimeoutMs: this.opts.fetchTimeoutMs ?? 0,
+      bridgeReviveDelayMs: this.opts.bridgeReviveDelayMs ?? 0,
+      lastSuccessAt: this.lastSuccessAt,
+      lastFailureAt: this.lastFailureAt,
+      lastFailureReason: this.lastFailureReason,
+      consecutiveFailures: this.consecutiveFailures,
+      lastExtensionMessageAt: this.lastExtensionMessageAt
+    };
+  }
+  recordSuccess() {
+    this.lastSuccessAt = Date.now();
+    this.consecutiveFailures = 0;
+  }
+  recordFailure(reason) {
+    this.lastFailureAt = Date.now();
+    this.lastFailureReason = reason;
+    this.consecutiveFailures += 1;
+  }
+  /**
+   * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
+   * On timeout returns the `{ok:false, kind:'timeout'}` envelope —
+   * the throwing surface is the convenience methods.
+   */
+  async _fetchOnceWithTimeout(init) {
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
     const pending = new Promise((resolve) => {
@@ -36432,7 +36806,61 @@ var FetchproxyServer = class {
     } else if (this.peerHandle) {
       await this.peerHandle.sendInner(inner);
     }
-    return pending;
+    const timeoutMs = this.opts.fetchTimeoutMs;
+    if (timeoutMs === void 0 || timeoutMs <= 0)
+      return pending;
+    let timer;
+    const start = Date.now();
+    try {
+      return await Promise.race([
+        pending,
+        new Promise((resolve) => {
+          timer = setTimeout(() => {
+            this.pending.delete(id);
+            const elapsedMs = Date.now() - start;
+            const error51 = `fetchproxy: ${init.url} did not respond within ${timeoutMs}ms`;
+            resolve({
+              ok: false,
+              error: error51,
+              kind: "timeout",
+              retryAttempted: false,
+              elapsedMs
+            });
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
+  /**
+   * Map an `ok:false` fetch result to its typed throwable. Centralizes
+   * the kind-to-error-class switch so `request()` and (via the same
+   * logic re-implemented inline) `captureRequestHeader()` agree on what
+   * to throw.
+   */
+  _typedErrorFor(result, url2, op, retryAttempted) {
+    if (result.kind === "timeout") {
+      return new FetchproxyTimeoutError({
+        url: url2,
+        timeoutMs: this.opts.fetchTimeoutMs ?? 0,
+        role: this.role,
+        port: this.opts.port,
+        elapsedMs: result.elapsedMs
+      });
+    }
+    if (result.kind === "content_script_unreachable") {
+      return new FetchproxyBridgeDownError({
+        originalError: result.error,
+        retryAttempted,
+        op,
+        url: url2,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+    return new FetchproxyProtocolError(result.error);
   }
   /**
    * Convenience wrapper around `fetch()`. Builds the URL from a path
@@ -36455,8 +36883,18 @@ var FetchproxyServer = class {
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
-    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
-    const url2 = path.startsWith("http://") || path.startsWith("https://") ? path : `https://${host}${path}`;
+    const isAbsolute = path.startsWith("http://") || path.startsWith("https://");
+    let host;
+    if (isAbsolute) {
+      try {
+        host = new URL(path).host;
+      } catch {
+        throw new Error(`FetchproxyServer.request: absolute path is not a valid URL: ${JSON.stringify(path)}`);
+      }
+    } else {
+      host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    }
+    const url2 = isAbsolute ? path : `https://${host}${path}`;
     assertUrlInDomains("request url", url2, this.opts.domains);
     const init = {
       url: url2,
@@ -36467,7 +36905,7 @@ var FetchproxyServer = class {
     };
     const result = await this.fetch(init);
     if (!result.ok) {
-      throw new FetchproxyProtocolError(result.error);
+      throw this._typedErrorFor(result, init.url, "fetch", result.retryAttempted ?? false);
     }
     const response = {
       status: result.status,
@@ -36561,9 +36999,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("read_cookies")) {
       throw new Error('FetchproxyServer.readCookies(): MCP did not declare "read_cookies" in capabilities \u2014 add it to FetchproxyServerOpts.capabilities to enable this verb');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.readCookies called before listen() \u2014 not listening");
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
@@ -36620,9 +37057,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes(op)) {
       throw new Error(`FetchproxyServer.${op === "read_local_storage" ? "readLocalStorage" : "readSessionStorage"}(): MCP did not declare ${JSON.stringify(op)} in capabilities`);
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error(`FetchproxyServer.${op} called before listen() \u2014 not listening`);
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
       throw new Error(`FetchproxyServer.${op}: opts.keys must be a non-empty array`);
     }
@@ -36677,13 +37113,75 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("capture_request_header")) {
       throw new Error('FetchproxyServer.captureRequestHeader(): MCP did not declare "capture_request_header" in capabilities');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.captureRequestHeader called before listen() \u2014 not listening");
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    const decls = this.opts.captureHeaders;
+    let resolved;
+    if (opts?.urlPattern !== void 0 && opts?.headerName !== void 0) {
+      const found = decls.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
+      if (!found) {
+        throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+      }
+      resolved = found;
+    } else if (opts?.urlPattern === void 0 && opts?.headerName === void 0) {
+      if (decls.length === 0) {
+        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {urlPattern, headerName} explicitly");
+      }
+      if (decls.length > 1) {
+        const list = decls.map((d) => `${JSON.stringify(d.urlPattern)}/${JSON.stringify(d.headerName)}`).join(", ");
+        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {urlPattern, headerName} to disambiguate`);
+      }
+      resolved = decls[0];
+    } else {
+      throw new Error("FetchproxyServer.captureRequestHeader: pass both urlPattern AND headerName, or neither (which defaults to the single declared entry)");
     }
-    const declared = this.opts.captureHeaders.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
-    if (!declared) {
-      throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+    const callOpts = { ...resolved, ...opts?.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} };
+    try {
+      const result = await this._captureRequestHeaderOnce(callOpts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`capture_request_header: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._captureRequestHeaderOnce(callOpts);
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`capture_request_header: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`capture_request_header bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "capture_request_header",
+            url: resolved.urlPattern,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`capture_request_header bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "capture_request_header",
+        url: resolved.urlPattern,
+        role: this.role,
+        port: this.opts.port
+      });
     }
+  }
+  async _captureRequestHeaderOnce(opts) {
     const id = this.nextRequestId++;
     const inner = {
       type: "request",
@@ -36720,9 +37218,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("read_indexed_db")) {
       throw new Error('FetchproxyServer.readIndexedDb(): MCP did not declare "read_indexed_db" in capabilities');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.readIndexedDb called before listen() \u2014 not listening");
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
       throw new Error("FetchproxyServer.readIndexedDb: opts.keys must be a non-empty array");
     }
@@ -36793,17 +37290,35 @@ var FetchproxyServer = class {
   onInner(inner) {
     if (inner.type !== "response")
       return;
+    this.lastExtensionMessageAt = Date.now();
     const fetchCb = this.pending.get(inner.id);
     if (fetchCb) {
       this.pending.delete(inner.id);
       if (inner.ok) {
         if (inner.op === void 0 || inner.op === "fetch") {
-          fetchCb({ ok: true, status: inner.status, url: inner.url, body: inner.body });
+          fetchCb({
+            ok: true,
+            status: inner.status,
+            url: inner.url,
+            body: inner.body,
+            retryAttempted: false
+          });
         } else {
-          fetchCb({ ok: false, error: `unexpected ${inner.op} response on fetch awaiter` });
+          const error51 = `unexpected ${inner.op} response on fetch awaiter`;
+          fetchCb({
+            ok: false,
+            error: error51,
+            kind: classifyFetchError(error51),
+            retryAttempted: false
+          });
         }
       } else {
-        fetchCb({ ok: false, error: inner.error });
+        fetchCb({
+          ok: false,
+          error: inner.error,
+          kind: classifyFetchError(inner.error),
+          retryAttempted: false
+        });
       }
       return;
     }
@@ -36870,6 +37385,57 @@ var FetchproxyServer = class {
       }
     }
   }
+  rejectAllPending(reason = "extension disconnected") {
+    const err = new FetchproxyProtocolError(reason);
+    for (const cb of this.pending.values()) {
+      cb({
+        ok: false,
+        error: err.message,
+        kind: classifyFetchError(err.message),
+        retryAttempted: false
+      });
+    }
+    this.pending.clear();
+    for (const cb of this.pendingReadCookies.values()) {
+      cb({ ok: false, error: err.message });
+    }
+    this.pendingReadCookies.clear();
+    for (const { reject } of this.pendingStorage.values())
+      reject(err);
+    this.pendingStorage.clear();
+    for (const { reject } of this.pendingCapture.values())
+      reject(err);
+    this.pendingCapture.clear();
+    for (const { reject } of this.pendingIdb.values())
+      reject(err);
+    this.pendingIdb.clear();
+  }
+  /**
+   * 0.5.2+: read the current pair-pending pair code from whichever handle
+   * is active, returning null when none is pending. Public verbs call this
+   * at the top so that a tool invoked while the bridge is waiting on user
+   * approval fails fast with the actionable error rather than hanging on a
+   * sealed frame the extension will never process.
+   */
+  currentPendingPairCode() {
+    if (this.hostHandle)
+      return this.hostHandle.pendingPairCode();
+    if (this.peerHandle)
+      return this.peerHandle.pendingPairCode();
+    return null;
+  }
+  /**
+   * 0.5.2+: throw `FetchproxyProtocolError` with the actionable pair-code
+   * message if the bridge is waiting on user approval. Used by the verb
+   * methods (readCookies, readLocalStorage, etc.) that surface errors via
+   * thrown exceptions rather than `ok:false` discriminated unions.
+   */
+  throwIfPendingPair() {
+    const code = this.currentPendingPairCode();
+    if (code !== null) {
+      throw new FetchproxyProtocolError(this.pairingErrorMessage(code));
+    }
+  }
   /**
    * Shut down the bridge. Host: terminates the WebSocket server and any
    * still-attached extension/peer clients. Peer: closes the upstream
@@ -36877,6 +37443,10 @@ var FetchproxyServer = class {
    * twice in a row.
    */
   async close() {
+    this.rejectAllPending();
+    if (this.connectingPromise) {
+      await this.connectingPromise.catch(() => void 0);
+    }
     if (this.hostHandle)
       await this.hostHandle.close();
     if (this.peerHandle)
@@ -36884,9 +37454,23 @@ var FetchproxyServer = class {
     this.hostHandle = null;
     this.peerHandle = null;
     this.role = null;
+    this.connectingPromise = null;
   }
 };
 
+// node_modules/@fetchproxy/server/dist/classify-bridge-error.js
+function classifyBridgeError(err) {
+  if (err instanceof FetchproxyTimeoutError)
+    return "timeout";
+  if (err instanceof FetchproxyBridgeDownError)
+    return "bridge_down";
+  if (err instanceof FetchproxyHttpError)
+    return "http";
+  if (err instanceof FetchproxyProtocolError)
+    return "protocol";
+  return "other";
+}
+
 // node_modules/@fetchproxy/bootstrap/dist/index.js
 var defaultFactory = (opts) => new FetchproxyServer(opts);
 async function bootstrap(opts) {
@@ -36941,7 +37525,11 @@ async function bootstrap(opts) {
       key: p.storageKey,
       jsonPointer: p.jsonPointer
     })),
-    onPairCode: opts.onPairCode
+    onPairCode: opts.onPairCode,
+    // 0.8.0+ pass-through. Only forwarded when the caller set them;
+    // unset → server defaults apply (30000 / 2000 in 0.8.0).
+    ...opts.fetchTimeoutMs !== void 0 ? { fetchTimeoutMs: opts.fetchTimeoutMs } : {},
+    ...opts.bridgeReviveDelayMs !== void 0 ? { bridgeReviveDelayMs: opts.bridgeReviveDelayMs } : {}
   });
   const storageDomainOpts = {};
   if (opts.storageDomain !== void 0)
@@ -36972,8 +37560,7 @@ async function bootstrap(opts) {
       for (const p of localStoragePointers) {
         pointers[p.outputKey] = { storageKey: p.storageKey, jsonPointer: p.jsonPointer };
       }
-      const stub = server;
-      localStorage = await stub.readLocalStorage({
+      localStorage = await server.readLocalStorage({
         keys: allKeys,
         ...storageDomainOpts,
         ...localStoragePointers.length > 0 ? { pointers } : {}
@@ -36986,8 +37573,7 @@ async function bootstrap(opts) {
       for (const p of sessionStoragePointers) {
         pointers[p.outputKey] = { storageKey: p.storageKey, jsonPointer: p.jsonPointer };
       }
-      const stub = server;
-      sessionStorage = await stub.readSessionStorage({
+      sessionStorage = await server.readSessionStorage({
         keys: allKeys,
         ...storageDomainOpts,
         ...sessionStoragePointers.length > 0 ? { pointers } : {}
@@ -37010,9 +37596,6 @@ async function bootstrap(opts) {
     }
     const indexedDbBucket = {};
     for (const d of indexedDb) {
-      if (!server.readIndexedDb) {
-        throw new Error("bootstrap: server factory does not implement readIndexedDb (declared indexedDb but server stub omits it)");
-      }
       const values = await server.readIndexedDb({
         database: d.database,
         store: d.store,
@@ -37049,7 +37632,7 @@ var BootstrapDisabledError = class extends Error {
 // package.json
 var package_default = {
   name: "creditkarma-mcp",
-  version: "2.0.10",
+  version: "2.2.0",
   mcpName: "io.github.chrischall/creditkarma-mcp",
   description: "MCP server for Credit Karma \u2014 natural-language access to your transactions, spending, and accounts",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -37093,17 +37676,18 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.4.2",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    dotenv: "^17.4.0",
-    zod: "^4.3.6"
+    dotenv: "^17.4.2",
+    zod: "^4.4.3"
   },
   devDependencies: {
-    "@types/node": "^25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
-    typescript: "^6.0.2",
-    vitest: "^4.1.2"
+    typescript: "^6.0.3",
+    vitest: "^4.1.7"
   }
 };
 
@@ -37163,6 +37747,12 @@ async function resolveAuth() {
       const cookies = `CKTRKID=${cktrkid}; CKAT=${ckat}`;
       return { cookies, source: "fetchproxy" };
     } catch (e) {
+      if (classifyBridgeError(e) === "bridge_down") {
+        const downErr = e;
+        throw new Error(
+          `CK auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+        );
+      }
       const msg = e instanceof Error ? e.message : String(e);
       throw new Error(
         `CK auth: no CK_COOKIES set, and fetchproxy fallback failed: ${msg}`
@@ -37623,7 +38213,8 @@ async function main() {
     mcpJsonPath
   };
   const server = new McpServer(
-    { name: "creditkarma-mcp", version: "2.0.10" }
+    { name: "creditkarma-mcp", version: "2.2.0" }
+    // x-release-please-version
   );
   registerAuthTools(server, ctx);
   registerSyncTools(server, ctx);

package/dist/index.js

@@ -63,7 +63,8 @@ async function main() {
         db,
         mcpJsonPath
     };
-    const server = new McpServer({ name: 'creditkarma-mcp', version: '2.0.10' });
+    const server = new McpServer({ name: 'creditkarma-mcp', version: '2.2.0' } // x-release-please-version
+    );
     registerAuthTools(server, ctx);
     registerSyncTools(server, ctx);
     registerQueryTools(server, ctx);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "creditkarma-mcp",
-  "version": "2.0.10",
+  "version": "2.2.0",
   "mcpName": "io.github.chrischall/creditkarma-mcp",
-  "description": "MCP server for Credit Karma \u2014 natural-language access to your transactions, spending, and accounts",
+  "description": "MCP server for Credit Karma — natural-language access to your transactions, spending, and accounts",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
   "repository": {
     "type": "git",
@@ -44,16 +44,17 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.4.2",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "dotenv": "^17.4.0",
-    "zod": "^4.3.6"
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/creditkarma-mcp",
     "source": "github"
   },
-  "version": "2.0.10",
+  "version": "2.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "creditkarma-mcp",
-      "version": "2.0.10",
+      "version": "2.2.0",
       "transport": {
         "type": "stdio"
       },