creditkarma-mcp 2.2.0 → 2.2.2

package/dist/bundle.js

@@ -7394,14 +7394,14 @@ var require_permessage_deflate = __commonJS({
       }
     };
     module.exports = PerMessageDeflate2;
-    function deflateOnData(chunk) {
-      this[kBuffers].push(chunk);
-      this[kTotalLength] += chunk.length;
+    function deflateOnData(chunk2) {
+      this[kBuffers].push(chunk2);
+      this[kTotalLength] += chunk2.length;
     }
-    function inflateOnData(chunk) {
-      this[kTotalLength] += chunk.length;
+    function inflateOnData(chunk2) {
+      this[kTotalLength] += chunk2.length;
       if (this[kPerMessageDeflate]._maxPayload < 1 || this[kTotalLength] <= this[kPerMessageDeflate]._maxPayload) {
-        this[kBuffers].push(chunk);
+        this[kBuffers].push(chunk2);
         return;
       }
       this[kError] = new RangeError("Max payload size exceeded");
@@ -7701,7 +7701,7 @@ var require_receiver = __commonJS({
        * @param {Function} cb Callback
        * @private
        */
-      _write(chunk, encoding, cb) {
+      _write(chunk2, encoding, cb) {
         if (this._opcode === 8 && this._state == GET_INFO) return cb();
         if (this._maxBufferedChunks > 0 && this._buffers.length >= this._maxBufferedChunks) {
           cb(
@@ -7715,8 +7715,8 @@ var require_receiver = __commonJS({
           );
           return;
         }
-        this._bufferedBytes += chunk.length;
-        this._buffers.push(chunk);
+        this._bufferedBytes += chunk2.length;
+        this._buffers.push(chunk2);
         this.startLoop(cb);
       }
       /**
@@ -9990,8 +9990,8 @@ var require_websocket = __commonJS({
       this.removeListener("end", socketOnEnd);
       websocket._readyState = WebSocket2.CLOSING;
       if (!this._readableState.endEmitted && !websocket._closeFrameReceived && !websocket._receiver._writableState.errorEmitted && this._readableState.length !== 0) {
-        const chunk = this.read(this._readableState.length);
-        websocket._receiver.write(chunk);
+        const chunk2 = this.read(this._readableState.length);
+        websocket._receiver.write(chunk2);
       }
       websocket._receiver.end();
       this[kWebSocket] = void 0;
@@ -10003,8 +10003,8 @@ var require_websocket = __commonJS({
         websocket._receiver.on("finish", receiverOnFinish);
       }
     }
-    function socketOnData(chunk) {
-      if (!this[kWebSocket]._receiver.write(chunk)) {
+    function socketOnData(chunk2) {
+      if (!this[kWebSocket]._receiver.write(chunk2)) {
         this.pause();
       }
     }
@@ -10107,14 +10107,14 @@ var require_stream = __commonJS({
       duplex._read = function() {
         if (ws.isPaused) ws.resume();
       };
-      duplex._write = function(chunk, encoding, callback) {
+      duplex._write = function(chunk2, encoding, callback) {
         if (ws.readyState === ws.CONNECTING) {
           ws.once("open", function open() {
-            duplex._write(chunk, encoding, callback);
+            duplex._write(chunk2, encoding, callback);
           });
           return;
         }
-        ws.send(chunk, callback);
+        ws.send(chunk2, callback);
       };
       duplex.on("end", duplexOnEnd);
       duplex.on("error", duplexOnError);
@@ -34546,8 +34546,8 @@ import process3 from "node:process";
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
 var ReadBuffer = class {
-  append(chunk) {
-    this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
+  append(chunk2) {
+    this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk2]) : chunk2;
   }
   readMessage() {
     if (!this._buffer) {
@@ -34579,8 +34579,8 @@ var StdioServerTransport = class {
     this._stdout = _stdout;
     this._readBuffer = new ReadBuffer();
     this._started = false;
-    this._ondata = (chunk) => {
-      this._readBuffer.append(chunk);
+    this._ondata = (chunk2) => {
+      this._readBuffer.append(chunk2);
       this.processReadBuffer();
     };
     this._onerror = (error51) => {
@@ -34633,6 +34633,139 @@ var StdioServerTransport = class {
   }
 };
 
+// node_modules/@chrischall/mcp-utils/dist/server/index.js
+async function createMcpServer(opts) {
+  const server = new McpServer({ name: opts.name, version: opts.version });
+  if (opts.banner !== void 0) {
+    console.error(opts.banner);
+  }
+  const deps = opts.deps;
+  for (const register of opts.tools) {
+    await register(server, deps);
+  }
+  return server;
+}
+function withGracefulShutdown(server, opts = {}) {
+  const shouldExit = opts.exit ?? true;
+  let shuttingDown = false;
+  const handler = (signal) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    void (async () => {
+      try {
+        if (opts.onSignal)
+          await opts.onSignal(signal);
+        await server.close();
+      } catch (err) {
+        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
+      } finally {
+        if (shouldExit)
+          process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGINT", () => handler("SIGINT"));
+  process.on("SIGTERM", () => handler("SIGTERM"));
+}
+async function runMcp(opts) {
+  const server = await createMcpServer(opts);
+  const shutdown = opts.shutdown ?? true;
+  if (shutdown !== false) {
+    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
+  }
+  const spec = opts.transport ?? "stdio";
+  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
+  await server.connect(transport);
+  return server;
+}
+
+// node_modules/@chrischall/mcp-utils/dist/response/index.js
+function textResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function rawTextResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+// node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var DEFAULT_ERROR_MESSAGE_MAX = 500;
+var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
+var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
+function redactSecrets(text) {
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
+}
+function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
+  const str = text === null || text === void 0 ? "" : String(text);
+  const redacted = redactSecrets(str);
+  if (redacted.length <= max)
+    return redacted;
+  return `${redacted.slice(0, max)}\u2026 [truncated]`;
+}
+
+// node_modules/@chrischall/mcp-utils/dist/config/index.js
+var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
+function readEnvVar(key, opts = {}) {
+  const env = opts.env ?? process.env;
+  const raw = env[key];
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length > 0 && trimmed !== "undefined" && trimmed !== "null" && !PLACEHOLDER_RE.test(trimmed)) {
+      return trimmed;
+    }
+  }
+  return opts.default;
+}
+var TRUE_TOKENS = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var FALSE_TOKENS = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+function parseBoolEnv(key, opts = {}) {
+  const fallback = opts.default ?? false;
+  const raw = readEnvVar(key, { env: opts.env });
+  if (raw === void 0)
+    return fallback;
+  const token = raw.toLowerCase();
+  if (TRUE_TOKENS.has(token))
+    return true;
+  if (FALSE_TOKENS.has(token))
+    return false;
+  return fallback;
+}
+async function loadDotenvSafely(opts = {}) {
+  try {
+    const mod = await import(
+      /* @vite-ignore */
+      "dotenv"
+    );
+    const result = mod.config({
+      ...opts.path !== void 0 ? { path: opts.path } : {},
+      override: opts.override ?? false,
+      quiet: true
+    });
+    return result.error === void 0;
+  } catch {
+    return false;
+  }
+}
+
+// node_modules/@chrischall/mcp-utils/dist/zod/index.js
+var PositiveInt = external_exports.number().int().positive();
+var NonNegInt = external_exports.number().int().nonnegative();
+var NonEmptyString = external_exports.string().min(1);
+var IsoDate = external_exports.iso.date();
+var IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30");
+var schemaOrigin = external_exports.string().optional().describe("Portal origin (e.g. https://<vendor>.example.co) selecting which active session to use. Optional when only one session is active.");
+var schemaConfirm = external_exports.boolean().optional().describe("Must be true to proceed. Without this, the tool returns a preview.");
+var paginationSchema = {
+  offset: NonNegInt.default(0).describe("Number of items to skip (0-based)."),
+  limit: external_exports.number().int().min(1).max(200).default(50).describe("Maximum number of items to return (1-200).")
+};
+var pageSchema = {
+  page_num: PositiveInt.default(1).describe("1-based page number."),
+  page_size: external_exports.number().int().min(1).max(200).default(50).describe("Number of items per page (1-200).")
+};
+
 // src/index.ts
 import { homedir as homedir2 } from "os";
 import { join as join4, dirname as dirname4 } from "path";
@@ -34650,6 +34783,8 @@ var CreditKarmaClient = class {
   tokenSetAt = null;
   refreshToken = null;
   cookies = null;
+  /** In-flight refresh, shared across concurrent callers (see refreshAccessToken). */
+  refreshInFlight = null;
   constructor(token, refreshToken, cookies) {
     if (token) this.setToken(token);
     if (refreshToken) this.refreshToken = refreshToken;
@@ -34693,17 +34828,31 @@ var CreditKarmaClient = class {
         variables: buildVariables(afterCursor)
       });
       if (retry.status === 401) throw new Error("TOKEN_EXPIRED");
-      if (!retry.ok) throw new Error(`HTTP ${retry.status}`);
+      if (!retry.ok) throw new Error(await httpErrorMessage(retry));
       return parseTransactionPage(await retry.json());
     }
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    if (!response.ok) throw new Error(await httpErrorMessage(response));
     return parseTransactionPage(await response.json());
   }
   /**
    * Refresh the access token using CK's native refresh endpoint.
    * Requires a refresh token and session cookies (captured after login).
+   *
+   * Concurrent callers share a single in-flight request: the first call starts
+   * the refresh and stores its promise; overlapping callers (e.g. a multi-page
+   * sync that 401s on several pages at once) await that same promise instead of
+   * firing duplicate POSTs to /member/oauth2/refresh (wasted quota, rate-limit
+   * risk). The slot is cleared in `finally`, so a later expiry refreshes anew.
    */
-  async refreshAccessToken() {
+  refreshAccessToken() {
+    if (this.refreshInFlight) return this.refreshInFlight;
+    const p = this.doRefreshAccessToken().finally(() => {
+      this.refreshInFlight = null;
+    });
+    this.refreshInFlight = p;
+    return p;
+  }
+  async doRefreshAccessToken() {
     if (!this.refreshToken) throw new Error("NO_REFRESH_TOKEN: Call ck_set_session first.");
     const headers = {
       "content-type": "application/json",
@@ -34766,6 +34915,11 @@ function isJwtExpired(token) {
   if (!p || typeof p.exp !== "number") return false;
   return p.exp * 1e3 < Date.now();
 }
+function warnIfRefreshTokenExpired(refreshToken) {
+  if (refreshToken && isJwtExpired(refreshToken)) {
+    console.error("[creditkarma-mcp] Warning: refresh token in CK_COOKIES has expired. Sign back into creditkarma.com (with the fetchproxy extension installed) or call ck_set_session with a fresh Cookie header.");
+  }
+}
 function extractGlidFromJwt(token) {
   const p = decodeJwtPayload(token);
   const glid = p?.glid;
@@ -34799,6 +34953,16 @@ function parseTransactionPage(json2) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function httpErrorMessage(res) {
+  let body = "";
+  try {
+    body = typeof res.text === "function" ? await res.text() : "";
+  } catch {
+    body = "";
+  }
+  const safe = truncateErrorMessage(body, 200).trim();
+  return safe.length > 0 ? `HTTP ${res.status}: ${safe}` : `HTTP ${res.status}`;
+}
 
 // src/db.ts
 import { DatabaseSync } from "node:sqlite";
@@ -35025,7 +35189,7 @@ function registerAuthTools(server, ctx) {
     },
     async (args) => {
       const result = await handleSetSession(args, ctx);
-      return { content: [{ type: "text", text: result }] };
+      return rawTextResult(result);
     }
   );
 }
@@ -35186,6 +35350,16 @@ function assertScopeKeyArray(value, label) {
     seen.add(k);
   }
 }
+var CAPTURE_PATH_RE = /^\/[A-Za-z0-9._~%\-/]*\*?$/;
+function hostMatchesAnyDomain(host, domains) {
+  const h = host.toLowerCase();
+  for (const d of domains) {
+    const dom = d.toLowerCase();
+    if (h === dom || h.endsWith("." + dom))
+      return true;
+  }
+  return false;
+}
 function assertCaptureHeadersArray(value, label) {
   if (!Array.isArray(value)) {
     throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
@@ -35194,14 +35368,25 @@ function assertCaptureHeadersArray(value, label) {
   for (let i = 0; i < value.length; i++) {
     const entry = value[i];
     assertObject(entry, `${label}[${i}]`);
-    if (entry.urlPattern === void 0) {
-      throw new ProtocolError(`${label}[${i}].urlPattern: missing`);
+    if (entry.host === void 0) {
+      throw new ProtocolError(`${label}[${i}].host: missing`);
     }
     if (entry.headerName === void 0) {
       throw new ProtocolError(`${label}[${i}].headerName: missing`);
     }
-    if (typeof entry.urlPattern !== "string") {
-      throw new ProtocolError(`${label}[${i}].urlPattern: expected string, got ${typeof entry.urlPattern}`);
+    if (typeof entry.host !== "string") {
+      throw new ProtocolError(`${label}[${i}].host: expected string, got ${typeof entry.host}`);
+    }
+    if (!HOSTNAME_RE.test(entry.host)) {
+      throw new ProtocolError(`${label}[${i}].host: invalid hostname ${JSON.stringify(entry.host)}`);
+    }
+    if (entry.path !== void 0) {
+      if (typeof entry.path !== "string") {
+        throw new ProtocolError(`${label}[${i}].path: expected string, got ${typeof entry.path}`);
+      }
+      if (!CAPTURE_PATH_RE.test(entry.path)) {
+        throw new ProtocolError(`${label}[${i}].path: must start with '/' ${JSON.stringify(entry.path)}`);
+      }
     }
     if (typeof entry.headerName !== "string") {
       throw new ProtocolError(`${label}[${i}].headerName: expected string, got ${typeof entry.headerName}`);
@@ -35209,19 +35394,29 @@ function assertCaptureHeadersArray(value, label) {
     if (!HEADER_NAME_RE.test(entry.headerName)) {
       throw new ProtocolError(`${label}[${i}].headerName: invalid name ${JSON.stringify(entry.headerName)}`);
     }
-    assertCaptureUrlPattern(entry.urlPattern, `${label}[${i}].urlPattern`);
-    const key = `${entry.urlPattern}\0${entry.headerName}`;
+    const normalizedPath = entry.path ?? "/*";
+    const key = `${entry.host}\0${normalizedPath}\0${entry.headerName}`;
     if (seen.has(key)) {
-      throw new ProtocolError(`${label}: duplicate ${JSON.stringify({ urlPattern: entry.urlPattern, headerName: entry.headerName })}`);
+      throw new ProtocolError(`${label}: duplicate ${JSON.stringify({ host: entry.host, path: normalizedPath, headerName: entry.headerName })}`);
     }
     seen.add(key);
     for (const k of Object.keys(entry)) {
-      if (k !== "urlPattern" && k !== "headerName") {
+      if (k !== "host" && k !== "path" && k !== "headerName") {
         throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
       }
     }
   }
 }
+function validateCaptureHeaderDecls(value, domains, label = "captureHeaders") {
+  assertCaptureHeadersArray(value, label);
+  const arr = value;
+  for (let i = 0; i < arr.length; i++) {
+    const host = arr[i].host;
+    if (!hostMatchesAnyDomain(host, domains)) {
+      throw new ProtocolError(`${label}[${i}].host: ${JSON.stringify(host)} is not a declared domain or subdomain of [${domains.join(", ")}]`);
+    }
+  }
+}
 function assertStoragePointersArray(value, label, declaredKeys) {
   if (!Array.isArray(value)) {
     throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
@@ -35309,23 +35504,6 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
-function assertCaptureUrlPattern(pattern, label) {
-  if (!pattern.startsWith("https://")) {
-    throw new ProtocolError(`${label}: must start with https:// (got ${JSON.stringify(pattern)})`);
-  }
-  const afterScheme = pattern.slice("https://".length);
-  const slash = afterScheme.indexOf("/");
-  const host = slash === -1 ? afterScheme : afterScheme.slice(0, slash);
-  if (host.length === 0) {
-    throw new ProtocolError(`${label}: missing host (got ${JSON.stringify(pattern)})`);
-  }
-  if (host.includes("*")) {
-    throw new ProtocolError(`${label}: wildcards not permitted in host (got ${JSON.stringify(pattern)})`);
-  }
-  if (!HOSTNAME_RE.test(host)) {
-    throw new ProtocolError(`${label}: invalid host ${JSON.stringify(host)} in ${JSON.stringify(pattern)}`);
-  }
-}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35390,7 +35568,7 @@ function validateHello(raw) {
       assertScopeKeyArray(raw.sessionStorageKeys, "hello.sessionStorageKeys");
     }
     if (raw.captureHeaders !== void 0) {
-      assertCaptureHeadersArray(raw.captureHeaders, "hello.captureHeaders");
+      validateCaptureHeaderDecls(raw.captureHeaders, raw.domains, "hello.captureHeaders");
     }
     if (raw.indexedDbScopes !== void 0) {
       assertIndexedDbScopesArray(raw.indexedDbScopes, "hello.indexedDbScopes");
@@ -35558,19 +35736,28 @@ function validateInnerRequest(raw) {
   }
   if (raw.op === "capture_request_header") {
     assertObject(raw.init, "inner.init");
-    if (raw.init.urlPattern === void 0) {
-      throw new ProtocolError("inner.init.urlPattern: missing");
+    if (raw.init.host === void 0) {
+      throw new ProtocolError("inner.init.host: missing");
     }
     if (raw.init.headerName === void 0) {
       throw new ProtocolError("inner.init.headerName: missing");
     }
-    assertString(raw.init.urlPattern, "inner.init.urlPattern");
+    assertString(raw.init.host, "inner.init.host");
+    if (!HOSTNAME_RE.test(raw.init.host)) {
+      throw new ProtocolError(`inner.init.host: invalid hostname ${JSON.stringify(raw.init.host)}`);
+    }
+    if (raw.init.path !== void 0) {
+      assertString(raw.init.path, "inner.init.path");
+      if (!CAPTURE_PATH_RE.test(raw.init.path)) {
+        throw new ProtocolError(`inner.init.path: must start with '/' ${JSON.stringify(raw.init.path)}`);
+      }
+    }
     assertString(raw.init.headerName, "inner.init.headerName");
     if (raw.init.timeoutMs !== void 0) {
       assertPositiveInt(raw.init.timeoutMs, "inner.init.timeoutMs");
     }
     for (const k of Object.keys(raw.init)) {
-      if (k !== "urlPattern" && k !== "headerName" && k !== "timeoutMs") {
+      if (k !== "host" && k !== "path" && k !== "headerName" && k !== "timeoutMs") {
         throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on capture_request_header`);
       }
     }
@@ -35950,7 +36137,8 @@ async function buildServerHello(opts) {
   }
   if (opts.captureHeaders && opts.captureHeaders.length > 0) {
     hello.captureHeaders = opts.captureHeaders.map((d) => ({
-      urlPattern: d.urlPattern,
+      host: d.host,
+      ...d.path !== void 0 ? { path: d.path } : {},
       headerName: d.headerName
     }));
   }
@@ -36188,7 +36376,9 @@ async function startHost(opts) {
         } catch {
         }
       }
-      wss.close(() => resolve());
+      wss.close(() => {
+        opts.httpServer.close(() => resolve());
+      });
     }),
     sendOwnInner: async (inner) => {
       const session = await ownSessionReady;
@@ -36238,6 +36428,7 @@ async function startPeer(opts) {
   const innerListeners = [];
   const renegotiateListeners = [];
   const pendingPairListeners = [];
+  const closeListeners = [];
   let session = null;
   let pendingPairCode = null;
   let resolveFirstReady;
@@ -36287,6 +36478,7 @@ async function startPeer(opts) {
   ws.on("message", onMessage);
   ws.once("close", () => {
     rejectFirstReady(new Error("peer WS closed before ready"));
+    closeListeners.forEach((cb) => cb());
   });
   sessionPromise.catch(() => {
   });
@@ -36309,6 +36501,9 @@ async function startPeer(opts) {
       pendingPairListeners.push(cb);
     },
     pendingPairCode: () => pendingPairCode,
+    onClose: (cb) => {
+      closeListeners.push(cb);
+    },
     close: () => ws.close()
   };
   return handle;
@@ -36391,6 +36586,19 @@ function classifyFetchError(error51) {
   return "other";
 }
 
+// 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/server/dist/ws-server.js
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
@@ -36420,7 +36628,7 @@ var FetchproxyBridgeDownError = class extends FetchproxyProtocolError {
     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.`;
+    const hint = `the fetchproxy extension's service worker is not responding ("${args.originalError}"). Chrome evicts extension service workers after ~30s idle by default. ${retryClause}Make sure a tab for this domain is open, fully loaded, and signed in (the bridge fetches through that tab) \u2014 then retry. If it keeps happening, reload the extension from chrome://extensions and reload the tab.`;
     super(`fetchproxy bridge down during ${op}${args.url ? ` (${args.url})` : ""}. ${hint}`);
     this.name = "FetchproxyBridgeDownError";
     this.originalError = args.originalError;
@@ -36442,6 +36650,14 @@ var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
   port;
   /** 0.8.0+: actual elapsed milliseconds when the timer won the race. */
   elapsedMs;
+  /**
+   * 0.11.0+ (#90/#91): true when the server's lazy-revive retry path
+   * fired for this timeout (a cold-start `timeout` symptom followed by
+   * a warm-and-retry that also timed out). False when the retry was
+   * disabled (`bridgeReviveDelayMs` unset/0) so the timeout surfaced on
+   * the first attempt.
+   */
+  retryAttempted;
   constructor(args) {
     super(`fetchproxy: ${args.url} did not respond within ${args.timeoutMs}ms`);
     this.name = "FetchproxyTimeoutError";
@@ -36450,6 +36666,7 @@ var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
     this.role = args.role ?? null;
     this.port = args.port ?? 0;
     this.elapsedMs = args.elapsedMs ?? args.timeoutMs;
+    this.retryAttempted = args.retryAttempted ?? false;
   }
 };
 var SUBDOMAIN_LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
@@ -36488,6 +36705,12 @@ var FetchproxyServer = class {
   opts;
   hostHandle = null;
   peerHandle = null;
+  // 0.13.0+: true from the start of `close()` until the next `doConnect()`.
+  // Distinguishes an intentional shutdown (whose WS close we must ignore)
+  // from the host process dying (which strands a peer and must trigger
+  // re-election). The WS `close` event fires asynchronously, so this stays
+  // latched across `close()` rather than being reset in its tail.
+  closing = false;
   nextRequestId = 1;
   // 0.8.0+: process-wide freshness counters surfaced via bridgeHealth().
   // Replaces the local copies every downstream MCP was rolling on top
@@ -36523,6 +36746,25 @@ var FetchproxyServer = class {
   // for "we're connecting right now" so two parallel first-calls don't
   // race the port bind.
   connectingPromise = null;
+  // 0.8.1+ (#67): server-initiated keep-alive ping. Active when
+  // `keepAliveIntervalMs` is set AND we've seen recent activity
+  // (fetch/capture success or failure, or markActive()) within
+  // `keepAliveMaxIdleMs`. The interval handle is created lazily on
+  // first activity and torn down on close() / extension disconnect.
+  keepAliveTimer = null;
+  lastActiveAt = null;
+  // 0.10.0+ (#73): observability counters surfaced via
+  // bridgeHealth().keepAlive / .swEviction. Monotonic across the process
+  // lifetime so a downstream healthcheck tool can verify the keep-alive
+  // is actually preventing SW eviction. `lastPingAt` and `totalPings`
+  // are stamped from `startKeepaliveIfIdle`'s tick. `lazyRevive*` and
+  // `lastEvictionDetectedAt` are stamped from the lazy-revive code path
+  // in fetch() / captureRequestHeader().
+  lastPingAt = null;
+  totalPings = 0;
+  lazyReviveAttempts = 0;
+  lazyReviveSuccesses = 0;
+  lastEvictionDetectedAt = 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");
@@ -36541,6 +36783,14 @@ var FetchproxyServer = class {
       }
       capabilities = [...opts.capabilities];
     }
+    if (opts.captureHeaders !== void 0) {
+      try {
+        validateCaptureHeaderDecls(opts.captureHeaders, opts.domains);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error("FetchproxyServer: invalid captureHeaders \u2014 " + message);
+      }
+    }
     this.opts = {
       port: opts.port ?? 37149,
       host: opts.host ?? "127.0.0.1",
@@ -36552,7 +36802,8 @@ var FetchproxyServer = class {
       localStorageKeys: [...opts.localStorageKeys ?? []],
       sessionStorageKeys: [...opts.sessionStorageKeys ?? []],
       captureHeaders: (opts.captureHeaders ?? []).map((d) => ({
-        urlPattern: d.urlPattern,
+        host: d.host,
+        ...d.path !== void 0 ? { path: d.path } : {},
         headerName: d.headerName
       })),
       indexedDbScopes: (opts.indexedDbScopes ?? []).map((d) => ({
@@ -36575,6 +36826,22 @@ var FetchproxyServer = class {
       // the legacy hang-forever / fail-once-on-SW-eviction behavior.
       fetchTimeoutMs: opts.fetchTimeoutMs ?? 3e4,
       bridgeReviveDelayMs: opts.bridgeReviveDelayMs ?? 2e3,
+      // 0.10.0+ (#72): keep-alive defaults to 25s — round-3 #71 cohort
+      // wave showed every Pattern A consumer was opting into this same
+      // value. Pass `0` to disable; the existing `<= 0` guards in
+      // `startKeepaliveIfIdle` / `noteActivityForKeepalive` honour that.
+      //
+      // #90 (P1-1): tightened to 20s. 25s left only ~5s of slack under
+      // Chrome's ~30s SW-eviction window — slack that timer drift, a
+      // busy host event loop (CPU-bound response parsing between calls),
+      // and the ping's own round-trip latency routinely ate, so the SW
+      // evicted before the next ping landed and the next call cold-
+      // started. 20s restores real margin. (The extension
+      // `chrome.alarms` backstop is clamped by Chrome to a 30s minimum
+      // period, firing *at* the edge — it can't rescue a sub-30s race;
+      // the server ping is the real defense.)
+      keepAliveIntervalMs: opts.keepAliveIntervalMs ?? 2e4,
+      keepAliveMaxIdleMs: opts.keepAliveMaxIdleMs ?? 5 * 60 * 1e3,
       identityDir: opts.identityDir,
       onPairCode: opts.onPairCode
     };
@@ -36654,6 +36921,7 @@ var FetchproxyServer = class {
   async doConnect() {
     const identity = this.identity;
     const mcpId = this.mcpId;
+    this.closing = false;
     const el = await electRole({ host: this.opts.host, port: this.opts.port });
     if (el.role === "host") {
       this.role = "host";
@@ -36675,7 +36943,10 @@ var FetchproxyServer = class {
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
-      this.hostHandle.onExtensionDisconnect(() => this.rejectAllPending());
+      this.hostHandle.onExtensionDisconnect(() => {
+        this.stopKeepalive();
+        this.rejectAllPending();
+      });
       this.hostHandle.onPendingPair((code) => {
         this.rejectAllPending(this.pairingErrorMessage(code));
       });
@@ -36699,7 +36970,10 @@ var FetchproxyServer = class {
         sessionStoragePointers: this.opts.sessionStoragePointers
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
-      this.peerHandle.onRenegotiate(() => this.rejectAllPending());
+      this.peerHandle.onRenegotiate(() => {
+        this.stopKeepalive();
+        this.rejectAllPending();
+      });
       this.peerHandle.onPendingPair((code) => {
         this.rejectAllPending(this.pairingErrorMessage(code));
       });
@@ -36707,6 +36981,14 @@ var FetchproxyServer = class {
         const cb = this.opts.onPairCode;
         this.peerHandle.onPendingPair((code) => cb(code));
       }
+      this.peerHandle.onClose(() => {
+        if (this.closing || this.peerHandle === null)
+          return;
+        this.stopKeepalive();
+        this.rejectAllPending();
+        this.peerHandle = null;
+        this.role = null;
+      });
     }
   }
   pairingErrorMessage(code) {
@@ -36740,13 +37022,18 @@ var FetchproxyServer = class {
     }
     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) {
+    const isColdStartSymptom = !first.ok && (first.kind === "content_script_unreachable" || first.kind === "timeout");
+    if (isColdStartSymptom) {
+      this.lastEvictionDetectedAt = Date.now();
+    }
+    if (isColdStartSymptom && reviveMs !== void 0 && reviveMs > 0) {
+      this.lazyReviveAttempts += 1;
       await new Promise((r) => setTimeout(r, reviveMs));
       const second = await this._fetchOnceWithTimeout(init);
-      if (second.ok)
+      if (second.ok) {
+        this.lazyReviveSuccesses += 1;
         this.recordSuccess();
-      else
+      } else
         this.recordFailure(`${second.kind ?? "other"}: ${second.error}`);
       return { ...second, retryAttempted: true };
     }
@@ -36768,6 +37055,9 @@ var FetchproxyServer = class {
    * call (addresses #23 ask 4).
    */
   bridgeHealth() {
+    const intervalMs = this.opts.keepAliveIntervalMs;
+    const maxIdleMs = this.opts.keepAliveMaxIdleMs;
+    const idleSinceMs = this.lastActiveAt === null ? null : Date.now() - this.lastActiveAt;
     return {
       role: this.role,
       port: this.opts.port,
@@ -36778,17 +37068,85 @@ var FetchproxyServer = class {
       lastFailureAt: this.lastFailureAt,
       lastFailureReason: this.lastFailureReason,
       consecutiveFailures: this.consecutiveFailures,
-      lastExtensionMessageAt: this.lastExtensionMessageAt
+      lastExtensionMessageAt: this.lastExtensionMessageAt,
+      keepAlive: {
+        enabled: intervalMs > 0,
+        intervalMs,
+        maxIdleMs,
+        lastPingAt: this.lastPingAt,
+        totalPings: this.totalPings,
+        idleSinceMs
+      },
+      swEviction: {
+        lazyReviveAttempts: this.lazyReviveAttempts,
+        lazyReviveSuccesses: this.lazyReviveSuccesses,
+        lastEvictionDetectedAt: this.lastEvictionDetectedAt
+      }
     };
   }
   recordSuccess() {
     this.lastSuccessAt = Date.now();
     this.consecutiveFailures = 0;
+    this.noteActivityForKeepalive();
   }
   recordFailure(reason) {
     this.lastFailureAt = Date.now();
     this.lastFailureReason = reason;
     this.consecutiveFailures += 1;
+    this.noteActivityForKeepalive();
+  }
+  /**
+   * 0.8.1+ (#67): caller-side hint that work is happening or about to
+   * happen — bumps the keep-alive idle gate so the server keeps pinging
+   * the extension. Useful for MCPs that do a chain of side-effectful
+   * work between bridge calls and don't want the SW to evict in the
+   * gap (e.g. server-side parsing of a previous response that takes
+   * tens of seconds). No-op when `keepAliveIntervalMs` is `0`.
+   */
+  markActive() {
+    this.noteActivityForKeepalive();
+  }
+  noteActivityForKeepalive() {
+    const intervalMs = this.opts.keepAliveIntervalMs;
+    if (intervalMs <= 0)
+      return;
+    this.lastActiveAt = Date.now();
+    this.startKeepaliveIfIdle();
+  }
+  startKeepaliveIfIdle() {
+    if (this.keepAliveTimer !== null)
+      return;
+    const intervalMs = this.opts.keepAliveIntervalMs;
+    if (intervalMs <= 0)
+      return;
+    this.keepAliveTimer = setInterval(() => {
+      const now = Date.now();
+      if (this.lastActiveAt === null || now - this.lastActiveAt > this.opts.keepAliveMaxIdleMs) {
+        this.stopKeepalive();
+        return;
+      }
+      this.totalPings += 1;
+      this.lastPingAt = now;
+      void this.sendKeepalivePing();
+    }, intervalMs);
+  }
+  async sendKeepalivePing() {
+    try {
+      const inner = { type: "ping" };
+      if (this.hostHandle) {
+        await this.hostHandle.sendOwnInner(inner);
+      } else if (this.peerHandle) {
+        await this.peerHandle.sendInner(inner);
+      }
+    } catch (e) {
+      console.error("[fetchproxy] keepalive ping send failed:", e);
+    }
+  }
+  stopKeepalive() {
+    if (this.keepAliveTimer !== null) {
+      clearInterval(this.keepAliveTimer);
+      this.keepAliveTimer = null;
+    }
   }
   /**
    * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
@@ -36847,7 +37205,8 @@ var FetchproxyServer = class {
         timeoutMs: this.opts.fetchTimeoutMs ?? 0,
         role: this.role,
         port: this.opts.port,
-        elapsedMs: result.elapsedMs
+        elapsedMs: result.elapsedMs,
+        retryAttempted
       });
     }
     if (result.kind === "content_script_unreachable") {
@@ -36978,6 +37337,108 @@ var FetchproxyServer = class {
     const response = await this.get(path, this.applyJsonDefaults(opts));
     return response.body;
   }
+  /**
+   * 0.11.0+: method-generic JSON convenience helper. Generalizes the
+   * `fetchJson<T>(path, { method, headers, body })` that
+   * zillow/redfin/compass/homes hand-rolled char-for-char in their
+   * `src/client.ts`:
+   *
+   *  - sets `Accept: application/json`;
+   *  - adds `Content-Type: application/json` only for a non-GET request
+   *    that carries a `body` (and only if the caller didn't set one);
+   *  - `JSON.stringify`s the body (GET / no-body sends nothing);
+   *  - treats a `204` or an empty body as `data: null` (no parse);
+   *  - otherwise `JSON.parse`s the body.
+   *
+   * Scope is serialization + header defaults + 204-handling +
+   * JSON.parse ONLY. It deliberately does NOT assert on the HTTP status
+   * or look for a sign-in interstitial — those guards differ per site
+   * (Zillow's `captcha-delivery`, Redfin's AWS-WAF challenge, …), so it
+   * returns BOTH the parsed `data` and the raw `FetchResult` and leaves
+   * the consumer to run its own `throwIfNotOk` / `throwIfSignInPage`
+   * over `result`.
+   *
+   * Bridge-level failures (no signed-in tab, SW down, timeout) still
+   * throw the typed errors via `request()`, exactly like the verb
+   * helpers — only successful round-trips (any HTTP status) return.
+   */
+  async requestJson(method, path, opts = {}) {
+    const isGet = method.toUpperCase() === "GET";
+    const sendBody = !isGet && opts.body !== void 0;
+    const headers = {
+      Accept: "application/json",
+      ...sendBody && !this.hasContentType(opts.headers ?? {}) ? { "Content-Type": "application/json" } : {},
+      ...opts.headers ?? {}
+    };
+    const response = await this.request(method, path, {
+      headers,
+      body: sendBody ? JSON.stringify(opts.body) : void 0,
+      ...opts.subdomain !== void 0 ? { subdomain: opts.subdomain } : {},
+      ...opts.domain !== void 0 ? { domain: opts.domain } : {}
+    });
+    const result = {
+      ok: true,
+      status: response.status,
+      url: response.url,
+      body: response.body
+    };
+    if (response.status === 204 || response.body === "") {
+      return { data: null, result };
+    }
+    let data;
+    try {
+      data = JSON.parse(response.body);
+    } catch (e) {
+      throw new Error(`fetchproxy ${method} ${path} \u2014 response was not JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { data, result };
+  }
+  /**
+   * 0.11.0+: run a single healthcheck probe through `fetchFn`, measure
+   * the elapsed round-trip, classify any thrown error, and project the
+   * post-probe `bridgeHealth()` into a snake-cased `bridge` sub-object.
+   *
+   * This is the transport half of the probe loop zillow/redfin/homes
+   * had duplicated verbatim in `src/tools/healthcheck.ts`. The MCP
+   * supplies its own probe call (`(path) => client.fetchHtml(path)`)
+   * and probe path (e.g. `'/robots.txt'`); the tool registration and
+   * the site-specific plain-English hint text STAY in the consumer.
+   *
+   * `bridgeHealth()` is read AFTER the probe so its freshness counters
+   * (`lastSuccessAt` / `consecutiveFailures` / …) reflect this very
+   * round-trip rather than a stale pre-probe snapshot.
+   */
+  async runProbe(fetchFn, probePath) {
+    const start = Date.now();
+    let ok = false;
+    let error51;
+    try {
+      await fetchFn(probePath);
+      ok = true;
+    } catch (e) {
+      error51 = {
+        kind: classifyBridgeError(e),
+        message: e instanceof Error ? e.message : String(e)
+      };
+    }
+    const elapsed_ms = Date.now() - start;
+    const health = this.bridgeHealth();
+    return {
+      ok,
+      elapsed_ms,
+      bridge: {
+        role: health.role,
+        port: health.port,
+        server_version: health.serverVersion,
+        fetch_timeout_ms: health.fetchTimeoutMs,
+        last_success_at: health.lastSuccessAt,
+        last_failure_at: health.lastFailureAt,
+        last_failure_reason: health.lastFailureReason,
+        consecutive_failures: health.consecutiveFailures
+      },
+      ...error51 ? { error: error51 } : {}
+    };
+  }
   /**
    * Snapshot the user's non-HttpOnly cookies for the chosen domain.
    *
@@ -37102,12 +37563,12 @@ var FetchproxyServer = class {
   /**
    * 0.3.0+: snapshot the next outgoing request's named header. Single-
    * shot: the extension registers a one-time `webRequest` listener
-   * filtered on `urlPattern`, captures the named header on the first
-   * match, removes itself, and resolves with the value. Times out
-   * after `timeoutMs` (default 30s on the extension).
+   * filtered on `https://${host}${path ?? '/*'}`, captures the named
+   * header on the first match, removes itself, and resolves with the
+   * value. Times out after `timeoutMs` (default 30s on the extension).
    *
-   * `(urlPattern, headerName)` must exactly match a declared entry in
-   * `FetchproxyServerOpts.captureHeaders`.
+   * `(host, path?, headerName)` must match a declared entry in
+   * `FetchproxyServerOpts.captureHeaders` (omitted path ≡ `/*`).
    */
   async captureRequestHeader(opts) {
     if (!this.opts.capabilities.includes("capture_request_header")) {
@@ -37116,24 +37577,25 @@ var FetchproxyServer = class {
     await this.ensureConnected();
     this.throwIfPendingPair();
     const decls = this.opts.captureHeaders;
+    const normPath = (p) => p ?? "/*";
     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 (opts?.host !== void 0 && opts?.headerName !== void 0) {
+      const found = decls.find((d) => d.host === opts.host && normPath(d.path) === normPath(opts.path) && 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`);
+        throw new Error(`FetchproxyServer.captureRequestHeader: (host=${JSON.stringify(opts.host)}, path=${JSON.stringify(normPath(opts.path))}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
       }
       resolved = found;
-    } else if (opts?.urlPattern === void 0 && opts?.headerName === void 0) {
+    } else if (opts?.host === 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");
+        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {host, 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`);
+        const list = decls.map((d) => `${JSON.stringify(d.host)}${JSON.stringify(normPath(d.path))}/${JSON.stringify(d.headerName)}`).join(", ");
+        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {host, 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)");
+      throw new Error("FetchproxyServer.captureRequestHeader: pass both host AND headerName, or neither (which defaults to the single declared entry)");
     }
     const callOpts = { ...resolved, ...opts?.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} };
     try {
@@ -37146,11 +37608,14 @@ var FetchproxyServer = class {
         this.recordFailure(`capture_request_header: ${err.message ?? String(err)}`);
         throw err;
       }
+      this.lastEvictionDetectedAt = Date.now();
       const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
       if (reviveMs > 0) {
+        this.lazyReviveAttempts += 1;
         await new Promise((r) => setTimeout(r, reviveMs));
         try {
           const result = await this._captureRequestHeaderOnce(callOpts);
+          this.lazyReviveSuccesses += 1;
           this.recordSuccess();
           return result;
         } catch (retryErr) {
@@ -37164,7 +37629,7 @@ var FetchproxyServer = class {
             originalError: retryErr.message,
             retryAttempted: true,
             op: "capture_request_header",
-            url: resolved.urlPattern,
+            url: `https://${resolved.host}${resolved.path ?? "/*"}`,
             role: this.role,
             port: this.opts.port
           });
@@ -37175,7 +37640,7 @@ var FetchproxyServer = class {
         originalError: err.message,
         retryAttempted: false,
         op: "capture_request_header",
-        url: resolved.urlPattern,
+        url: `https://${resolved.host}${resolved.path ?? "/*"}`,
         role: this.role,
         port: this.opts.port
       });
@@ -37188,7 +37653,8 @@ var FetchproxyServer = class {
       id,
       op: "capture_request_header",
       init: {
-        urlPattern: opts.urlPattern,
+        host: opts.host,
+        ...opts.path !== void 0 ? { path: opts.path } : {},
         headerName: opts.headerName,
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
@@ -37443,6 +37909,8 @@ var FetchproxyServer = class {
    * twice in a row.
    */
   async close() {
+    this.closing = true;
+    this.stopKeepalive();
     this.rejectAllPending();
     if (this.connectingPromise) {
       await this.connectingPromise.catch(() => void 0);
@@ -37458,19 +37926,6 @@ var FetchproxyServer = class {
   }
 };
 
-// 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) {
@@ -37582,15 +38037,11 @@ async function bootstrap(opts) {
     const capturedHeaders = {};
     for (const h of opts.declare.captureHeaders) {
       if (opts.onWaiting) {
-        try {
-          const url2 = new URL(h.urlPattern.replace(/\*+/g, "placeholder"));
-          opts.onWaiting(`waiting for next request to ${url2.host} to capture ${h.headerName} \u2014 interact with the page in your browser`);
-        } catch {
-          opts.onWaiting(`waiting to capture ${h.headerName} \u2014 interact with the page in your browser`);
-        }
+        opts.onWaiting(`waiting for next request to ${h.host} to capture ${h.headerName} \u2014 interact with the page in your browser`);
       }
       capturedHeaders[h.headerName] = await server.captureRequestHeader({
-        urlPattern: h.urlPattern,
+        host: h.host,
+        ...h.path !== void 0 ? { path: h.path } : {},
         headerName: h.headerName
       });
     }
@@ -37632,7 +38083,7 @@ var BootstrapDisabledError = class extends Error {
 // package.json
 var package_default = {
   name: "creditkarma-mcp",
-  version: "2.2.0",
+  version: "2.2.2",
   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>",
@@ -37676,8 +38127,9 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.8.0",
-    "@fetchproxy/server": "^0.8.0",
+    "@chrischall/mcp-utils": "^0.5.0",
+    "@fetchproxy/bootstrap": "^1.0.0",
+    "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -37692,22 +38144,11 @@ var package_default = {
 };
 
 // src/auth.ts
-function readEnv(key) {
-  const raw = process.env[key];
-  if (typeof raw !== "string") return void 0;
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) return void 0;
-  if (trimmed === "undefined" || trimmed === "null") return void 0;
-  if (/^\$\{[^}]*\}$/.test(trimmed)) return void 0;
-  return trimmed;
-}
 function fetchproxyDisabled() {
-  const raw = readEnv("CK_DISABLE_FETCHPROXY");
-  if (raw === void 0) return false;
-  return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+  return parseBoolEnv("CK_DISABLE_FETCHPROXY", { default: false });
 }
 async function resolveAuth() {
-  const envCookies = readEnv("CK_COOKIES");
+  const envCookies = readEnvVar("CK_COOKIES");
   if (envCookies) {
     return { cookies: envCookies, source: "env" };
   }
@@ -37889,7 +38330,7 @@ function registerSyncTools(server, ctx) {
     },
     async (args) => {
       const result = await handleSyncTransactions(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
 }
@@ -38078,7 +38519,7 @@ function registerQueryTools(server, ctx) {
     },
     async (args) => {
       const result = await handleListTransactions(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
   server.registerTool(
@@ -38092,7 +38533,7 @@ function registerQueryTools(server, ctx) {
     },
     async (args) => {
       const result = await handleGetRecentTransactions(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
   server.registerTool(
@@ -38108,7 +38549,7 @@ function registerQueryTools(server, ctx) {
     },
     async (args) => {
       const result = await handleGetSpendingByCategory(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
   server.registerTool(
@@ -38125,7 +38566,7 @@ function registerQueryTools(server, ctx) {
     },
     async (args) => {
       const result = await handleGetSpendingByMerchant(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
   server.registerTool(
@@ -38140,7 +38581,7 @@ function registerQueryTools(server, ctx) {
     },
     async (args) => {
       const result = await handleGetAccountSummary(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
 }
@@ -38166,31 +38607,18 @@ function registerSqlTools(server, ctx) {
     },
     async (args) => {
       const result = await handleQuerySql(args, ctx);
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      return textResult(result);
     }
   );
 }
 
 // src/index.ts
-function readVar(key) {
-  const raw = process.env[key];
-  if (typeof raw !== "string") return void 0;
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) return void 0;
-  if (trimmed === "undefined" || trimmed === "null") return void 0;
-  if (/^\$\{[^}]*\}$/.test(trimmed)) return void 0;
-  return trimmed;
-}
 var __dirname = dirname4(fileURLToPath2(import.meta.url));
-try {
-  const { config: config2 } = await import("dotenv");
-  config2({ path: join4(__dirname, "..", ".env"), override: false, quiet: true });
-} catch {
-}
+await loadDotenvSafely({ path: join4(__dirname, "..", ".env") });
 async function main() {
-  const dbPath = readVar("CK_DB_PATH") || join4(homedir2(), ".creditkarma-mcp", "transactions.db");
+  const dbPath = readEnvVar("CK_DB_PATH") || join4(homedir2(), ".creditkarma-mcp", "transactions.db");
   const mcpJsonPath = join4(__dirname, "..", ".mcp.json");
-  const cookies = readVar("CK_COOKIES") || void 0;
+  const cookies = readEnvVar("CK_COOKIES") || void 0;
   let token;
   let refreshToken;
   if (cookies) {
@@ -38199,9 +38627,7 @@ async function main() {
     token = parts[0]?.trim() || void 0;
     refreshToken = parts[1]?.trim() || void 0;
   }
-  if (refreshToken && isJwtExpired(refreshToken)) {
-    console.error("[creditkarma-mcp] Warning: refresh token in CK_COOKIES has expired. Sign back into creditkarma.com (with the fetchproxy extension installed) or call ck_set_session with a fresh Cookie header.");
-  }
+  warnIfRefreshTokenExpired(refreshToken);
   const db = initDb(dbPath);
   const repaired = backfillAccountIds(db);
   if (repaired.txsUpdated > 0) {
@@ -38212,15 +38638,17 @@ async function main() {
     db,
     mcpJsonPath
   };
-  const server = new McpServer(
-    { name: "creditkarma-mcp", version: "2.2.0" }
+  await runMcp({
+    name: "creditkarma-mcp",
+    version: "2.2.2",
     // x-release-please-version
-  );
-  registerAuthTools(server, ctx);
-  registerSyncTools(server, ctx);
-  registerQueryTools(server, ctx);
-  registerSqlTools(server, ctx);
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+    deps: ctx,
+    tools: [
+      registerAuthTools,
+      registerSyncTools,
+      registerQueryTools,
+      registerSqlTools
+    ]
+  });
 }
 main().catch(console.error);