ofw-mcp 2.2.0 → 2.3.1

package/dist/bundle.js

@@ -7395,14 +7395,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");
@@ -7702,7 +7702,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(
@@ -7716,8 +7716,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);
       }
       /**
@@ -9991,8 +9991,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;
@@ -10004,8 +10004,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();
       }
     }
@@ -10108,14 +10108,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);
@@ -10342,10 +10342,10 @@ var require_websocket_server = __commonJS({
             process.nextTick(emitClose, this);
           }
         } else {
-          const server2 = this._server;
+          const server = this._server;
           this._removeListeners();
           this._removeListeners = this._server = null;
-          server2.close(() => {
+          server.close(() => {
             emitClose(this);
           });
         }
@@ -10530,17 +10530,17 @@ var require_websocket_server = __commonJS({
       }
     };
     module.exports = WebSocketServer2;
-    function addListeners(server2, map2) {
-      for (const event of Object.keys(map2)) server2.on(event, map2[event]);
+    function addListeners(server, map2) {
+      for (const event of Object.keys(map2)) server.on(event, map2[event]);
       return function removeListeners() {
         for (const event of Object.keys(map2)) {
-          server2.removeListener(event, map2[event]);
+          server.removeListener(event, map2[event]);
         }
       };
     }
-    function emitClose(server2) {
-      server2._state = CLOSED;
-      server2.emit("close");
+    function emitClose(server) {
+      server._state = CLOSED;
+      server.emit("close");
     }
     function socketOnError() {
       this.destroy();
@@ -10559,11 +10559,11 @@ var require_websocket_server = __commonJS({
 ` + Object.keys(headers).map((h) => `${h}: ${headers[h]}`).join("\r\n") + "\r\n\r\n" + message
       );
     }
-    function abortHandshakeOrEmitwsClientError(server2, req, socket, code, message, headers) {
-      if (server2.listenerCount("wsClientError")) {
+    function abortHandshakeOrEmitwsClientError(server, req, socket, code, message, headers) {
+      if (server.listenerCount("wsClientError")) {
         const err = new Error(message);
         Error.captureStackTrace(err, abortHandshakeOrEmitwsClientError);
-        server2.emit("wsClientError", err, socket, req);
+        server.emit("wsClientError", err, socket, req);
       } else {
         abortHandshake(socket, code, message, headers);
       }
@@ -32189,11 +32189,11 @@ var Protocol = class {
    *
    * The Protocol object assumes ownership of the Transport, replacing any callbacks that have already been set, and expects that it is the only user of the Transport instance going forward.
    */
-  async connect(transport2) {
+  async connect(transport) {
     if (this._transport) {
       throw new Error("Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.");
     }
-    this._transport = transport2;
+    this._transport = transport;
     const _onclose = this.transport?.onclose;
     this._transport.onclose = () => {
       _onclose?.();
@@ -33783,8 +33783,8 @@ var McpServer = class {
    *
    * The `server` object assumes ownership of the Transport, replacing any callbacks that have already been set, and expects that it is the only user of the Transport instance going forward.
    */
-  async connect(transport2) {
-    return await this.server.connect(transport2);
+  async connect(transport) {
+    return await this.server.connect(transport);
   }
   /**
    * Closes the connection.
@@ -34547,8 +34547,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) {
@@ -34580,8 +34580,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) => {
@@ -34634,8 +34634,152 @@ 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/config/index.js
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+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;
+}
+function expandPath(p) {
+  let expanded = p;
+  if (p === "~") {
+    expanded = homedir();
+  } else if (p.startsWith("~/")) {
+    expanded = join(homedir(), p.slice(2));
+  }
+  return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+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/fs/index.js
+import { openAsBlob } from "node:fs";
+async function fileBlob(path, opts = {}) {
+  let blob;
+  try {
+    blob = await openAsBlob(path, opts.type !== void 0 ? { type: opts.type } : void 0);
+  } catch {
+    throw new Error(`Cannot read file for upload: ${path}`);
+  }
+  if (opts.maxBytes !== void 0 && blob.size > opts.maxBytes) {
+    throw new Error(`${opts.label ?? "File"} is ${blob.size} bytes, over the ${opts.maxBytes}-byte limit: ${path}`);
+  }
+  return blob;
+}
+
+// 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/client.ts
-import { dirname, join as join3 } from "path";
+import { dirname, join as join4 } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
@@ -35494,13 +35638,13 @@ async function openEncryptedFrame(sessionKey, frame) {
 // node_modules/@fetchproxy/server/dist/election.js
 import { createServer, Server as HttpServer } from "node:http";
 async function electRole(opts) {
-  const server2 = createServer();
+  const server = createServer();
   return new Promise((resolve2, reject) => {
     const onError = (e) => {
-      server2.removeListener("listening", onListening);
+      server.removeListener("listening", onListening);
       if (e.code === "EADDRINUSE") {
         try {
-          server2.close();
+          server.close();
         } catch {
         }
         resolve2({ role: "peer" });
@@ -35509,12 +35653,12 @@ async function electRole(opts) {
       }
     };
     const onListening = () => {
-      server2.removeListener("error", onError);
-      resolve2({ role: "host", server: server2 });
+      server.removeListener("error", onError);
+      resolve2({ role: "host", server });
     };
-    server2.once("error", onError);
-    server2.once("listening", onListening);
-    server2.listen(opts.port, opts.host);
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(opts.port, opts.host);
   });
 }
 
@@ -35924,19 +36068,19 @@ async function startPeer(opts) {
 
 // node_modules/@fetchproxy/server/dist/identity.js
 import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
-import { join } from "node:path";
-import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
 var SAFE_PLAIN = /^[A-Za-z0-9._-]+$/;
 var SAFE_SCOPED = /^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 function defaultIdentityDir() {
-  return join(homedir(), ".fetchproxy", "identity");
+  return join2(homedir2(), ".fetchproxy", "identity");
 }
 async function loadOrCreateIdentity(serverName, dir = defaultIdentityDir()) {
   if (!serverName || serverName === ".." || serverName.includes("..") || !SAFE_PLAIN.test(serverName) && !SAFE_SCOPED.test(serverName)) {
     throw new Error(`unsafe serverName for identity file: ${JSON.stringify(serverName)}`);
   }
   const safeFile = serverName.replace(/\//g, "_");
-  const path = join(dir, `${safeFile}.json`);
+  const path = join2(dir, `${safeFile}.json`);
   await mkdir(dir, { recursive: true, mode: 448 });
   try {
     const raw = await readFile(path, "utf8");
@@ -35999,6 +36143,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) {
@@ -36028,7 +36185,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;
@@ -36050,6 +36207,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";
@@ -36058,6 +36223,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;
@@ -36131,6 +36297,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");
@@ -36183,6 +36368,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
     };
@@ -36283,7 +36484,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));
       });
@@ -36307,7 +36511,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));
       });
@@ -36348,13 +36555,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 };
     }
@@ -36376,6 +36588,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,
@@ -36386,17 +36601,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.
@@ -36455,7 +36738,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") {
@@ -36586,6 +36870,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.
    *
@@ -36754,11 +37140,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) {
@@ -37051,6 +37440,7 @@ var FetchproxyServer = class {
    * twice in a row.
    */
   async close() {
+    this.stopKeepalive();
     this.rejectAllPending();
     if (this.connectingPromise) {
       await this.connectingPromise.catch(() => void 0);
@@ -37066,19 +37456,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) {
@@ -37110,7 +37487,7 @@ async function bootstrap(opts) {
   const sessionStorageKeys = new Set(opts.declare.sessionStorage);
   for (const p of sessionStoragePointers)
     sessionStorageKeys.add(p.storageKey);
-  const server2 = factory({
+  const server = factory({
     serverName: opts.serverName,
     version: opts.version,
     domains: [...opts.domains],
@@ -37145,10 +37522,10 @@ async function bootstrap(opts) {
   if (opts.storageSubdomain !== void 0)
     storageDomainOpts.subdomain = opts.storageSubdomain;
   try {
-    await server2.listen();
+    await server.listen();
     const cookies = {};
     if (opts.declare.cookies.length > 0) {
-      const joined = await server2.readCookies({
+      const joined = await server.readCookies({
         keys: opts.declare.cookies,
         ...storageDomainOpts
       });
@@ -37168,7 +37545,7 @@ async function bootstrap(opts) {
       for (const p of localStoragePointers) {
         pointers[p.outputKey] = { storageKey: p.storageKey, jsonPointer: p.jsonPointer };
       }
-      localStorage = await server2.readLocalStorage({
+      localStorage = await server.readLocalStorage({
         keys: allKeys,
         ...storageDomainOpts,
         ...localStoragePointers.length > 0 ? { pointers } : {}
@@ -37181,7 +37558,7 @@ async function bootstrap(opts) {
       for (const p of sessionStoragePointers) {
         pointers[p.outputKey] = { storageKey: p.storageKey, jsonPointer: p.jsonPointer };
       }
-      sessionStorage = await server2.readSessionStorage({
+      sessionStorage = await server.readSessionStorage({
         keys: allKeys,
         ...storageDomainOpts,
         ...sessionStoragePointers.length > 0 ? { pointers } : {}
@@ -37197,14 +37574,14 @@ async function bootstrap(opts) {
           opts.onWaiting(`waiting to capture ${h.headerName} \u2014 interact with the page in your browser`);
         }
       }
-      capturedHeaders[h.headerName] = await server2.captureRequestHeader({
+      capturedHeaders[h.headerName] = await server.captureRequestHeader({
         urlPattern: h.urlPattern,
         headerName: h.headerName
       });
     }
     const indexedDbBucket = {};
     for (const d of indexedDb) {
-      const values = await server2.readIndexedDb({
+      const values = await server.readIndexedDb({
         database: d.database,
         store: d.store,
         keys: [...d.keys],
@@ -37221,7 +37598,7 @@ async function bootstrap(opts) {
     };
   } finally {
     try {
-      await server2.close();
+      await server.close();
     } catch {
     }
   }
@@ -37286,8 +37663,8 @@ async function loginWithPassword(username, password) {
 
 // src/config.ts
 import { createHash } from "node:crypto";
-import { homedir as homedir2 } from "node:os";
-import { join as join2 } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
 function readCacheIdentity() {
   const explicit = process.env.OFW_CACHE_IDENTITY;
   if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
@@ -37298,31 +37675,29 @@ function readCacheIdentity() {
 function getCacheDir() {
   const override = process.env.OFW_CACHE_DIR;
   if (override && override.trim().length > 0) return override.trim();
-  return join2(homedir2(), ".cache", "ofw-mcp");
+  return join3(homedir3(), ".cache", "ofw-mcp");
 }
 function getCacheDbPath() {
   const identity = readCacheIdentity();
   const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
-  return join2(getCacheDir(), `${hash2}.db`);
+  return join3(getCacheDir(), `${hash2}.db`);
 }
 function getAttachmentsDir() {
   const override = process.env.OFW_ATTACHMENTS_DIR;
   if (override && override.trim().length > 0) return override.trim();
-  return join2(homedir2(), "Downloads", "ofw-mcp");
+  return join3(homedir3(), "Downloads", "ofw-mcp");
 }
-function parseBoolEnv(name) {
-  const raw = process.env[name];
-  if (typeof raw !== "string") return false;
-  return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
+function parseBoolEnv2(name) {
+  return parseBoolEnv(name);
 }
 function getDefaultInlineAttachments() {
-  return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
+  return parseBoolEnv2("OFW_INLINE_ATTACHMENTS");
 }
 
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.2.0",
+  version: "2.3.1",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -37346,11 +37721,12 @@ var package_default = {
     bundle: `esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js`,
     dev: "node --env-file=.env dist/index.js",
     test: "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.8.0",
-    "@fetchproxy/server": "^0.8.0",
+    "@chrischall/mcp-utils": "^0.4.0",
+    "@fetchproxy/bootstrap": "^0.11.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -37366,16 +37742,10 @@ 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;
+  return readEnvVar(key);
 }
 function fetchproxyDisabled() {
-  return parseBoolEnv("OFW_DISABLE_FETCHPROXY");
+  return parseBoolEnv2("OFW_DISABLE_FETCHPROXY");
 }
 async function resolveAuth() {
   const username = readEnv("OFW_USERNAME");
@@ -37435,12 +37805,8 @@ async function resolveAuth() {
 }
 
 // src/client.ts
-try {
-  const { config: config2 } = await import("dotenv");
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  config2({ path: join3(__dirname, "..", ".env"), override: false, quiet: true });
-} catch {
-}
+var __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join4(__dirname, "..", ".env") });
 function parseContentDispositionFilename(cd) {
   const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
   if (extMatch) {
@@ -37455,7 +37821,7 @@ function parseContentDispositionFilename(cd) {
   return m ? m[1] : null;
 }
 function debugLogEnabled() {
-  return parseBoolEnv("OFW_DEBUG_LOG");
+  return parseBoolEnv2("OFW_DEBUG_LOG");
 }
 function redactHeaders(h) {
   const out = { ...h };
@@ -37584,13 +37950,8 @@ var OFWClient = class {
 var client = new OFWClient();
 
 // src/tools/_shared.ts
-import { isAbsolute, join as join4, resolve } from "node:path";
-function jsonResponse(payload) {
-  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
-}
-function textResponse(text) {
-  return { content: [{ type: "text", text }] };
-}
+var jsonResponse = textResult;
+var textResponse = rawTextResult;
 function mapRecipients(items) {
   return (items ?? []).map((r) => ({
     userId: r.user?.id ?? 0,
@@ -37598,10 +37959,7 @@ function mapRecipients(items) {
     viewedAt: r.viewed?.dateTime ?? null
   }));
 }
-function expandPath(p) {
-  const expanded = p.startsWith("~/") ? join4(process.env.HOME ?? "", p.slice(2)) : p;
-  return isAbsolute(expanded) ? expanded : resolve(expanded);
-}
+var expandPath2 = expandPath;
 async function postMessageAndRefetch(client2, payload) {
   const raw = await client2.request(
     "POST",
@@ -37615,15 +37973,15 @@ async function postMessageAndRefetch(client2, payload) {
 }
 
 // src/tools/user.ts
-function registerUserTools(server2, client2) {
-  server2.registerTool("ofw_get_profile", {
+function registerUserTools(server, client2) {
+  server.registerTool("ofw_get_profile", {
     description: "Get current user and co-parent profile information from OurFamilyWizard",
     annotations: { readOnlyHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v2/profiles");
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_get_notifications", {
+  server.registerTool("ofw_get_notifications", {
     description: "Get OurFamilyWizard dashboard summary: unread message count, upcoming events, outstanding expenses. Note: updates your last-seen status.",
     annotations: { readOnlyHint: false }
   }, async () => {
@@ -38164,15 +38522,15 @@ function listDataHintsAtFiles(listData) {
   if (Array.isArray(ld.files)) return ld.files.length > 0;
   return false;
 }
-function registerMessageTools(server2, client2) {
-  server2.registerTool("ofw_list_message_folders", {
+function registerMessageTools(server, client2) {
+  server.registerTool("ofw_list_message_folders", {
     description: "List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.",
     annotations: { readOnlyHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v1/messageFolders?includeFolderCounts=true");
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_list_messages", {
+  server.registerTool("ofw_list_messages", {
     description: "List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based but if you know what you want (a date range, a topic), prefer the filters over walking pages \u2014 the cache may have 1000+ messages. Call ofw_sync_messages first if the cache is empty or stale.",
     annotations: { readOnlyHint: true },
     inputSchema: {
@@ -38208,7 +38566,7 @@ function registerMessageTools(server2, client2) {
     }
     return jsonResponse(payload);
   });
-  server2.registerTool("ofw_get_message", {
+  server.registerTool("ofw_get_message", {
     description: 'Get a single OurFamilyWizard message OR draft by ID. Reads from local cache when available; otherwise fetches from OFW (which will mark unread inbox messages as read on OFW). For ids that match a draft (in the drafts cache), the response carries folder="drafts" and the body/subject/recipients reflect the drafts cache (which ofw_sync_messages keeps fresh) \u2014 drafts have no `fromUser`, and `sentAt`/`fetchedBodyAt` mirror the draft\'s `modifiedAt`. For inbox/sent messages, folder is "inbox" or "sent" as before.',
     annotations: { readOnlyHint: false },
     inputSchema: {
@@ -38273,7 +38631,7 @@ function registerMessageTools(server2, client2) {
     const attachments = listAttachmentsForMessage(detail.id);
     return jsonResponse({ ...row, attachments });
   });
-  server2.registerTool("ofw_send_message", {
+  server.registerTool("ofw_send_message", {
     description: "Send a message via OurFamilyWizard. To send an existing draft, pass messageId \u2014 subject/body/recipientIds become optional overrides (missing fields default to the draft's cached values) and the draft is deleted after sending. To send a fresh message, supply subject/body/recipientIds directly. draftId is the legacy spelling of messageId and works the same way. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -38383,7 +38741,7 @@ function registerMessageTools(server2, client2) {
 
 ${text}` : text);
   });
-  server2.registerTool("ofw_list_drafts", {
+  server.registerTool("ofw_list_drafts", {
     description: "List draft messages from the local OurFamilyWizard cache. Call ofw_sync_messages first if the cache is empty.",
     annotations: { readOnlyHint: true },
     inputSchema: {
@@ -38397,7 +38755,7 @@ ${text}` : text);
     const payload = drafts.length === 0 ? { drafts: [], note: "Cache empty. Call ofw_sync_messages to populate." } : { drafts };
     return jsonResponse(payload);
   });
-  server2.registerTool("ofw_save_draft", {
+  server.registerTool("ofw_save_draft", {
     description: "Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft \u2014 note that under the hood this creates a NEW draft and deletes the old one (OFW's update-in-place endpoint silently no-ops while echoing the posted body, so we don't use it); the response.id will be the NEW id, not the messageId you passed, and the change is documented in a transparency NOTE in the response. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After saving, the tool re-fetches the draft from OFW to populate the local cache from authoritative server state.",
     annotations: { readOnlyHint: false },
     inputSchema: {
@@ -38459,7 +38817,7 @@ ${text}` : text);
 
 ${text}` : text);
   });
-  server2.registerTool("ofw_delete_draft", {
+  server.registerTool("ofw_delete_draft", {
     description: "Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache.",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -38470,7 +38828,7 @@ ${text}` : text);
     deleteDraft(args.messageId);
     return data ? jsonResponse(data) : textResponse("Draft deleted.");
   });
-  server2.registerTool("ofw_get_unread_sent", {
+  server.registerTool("ofw_get_unread_sent", {
     description: "List sent messages that have not been read by one or more recipients. Reads from local cache; call ofw_sync_messages first if cache is stale.",
     annotations: { readOnlyHint: true },
     inputSchema: {
@@ -38496,7 +38854,7 @@ ${text}` : text);
     }
     return jsonResponse(unread);
   });
-  server2.registerTool("ofw_upload_attachment", {
+  server.registerTool("ofw_upload_attachment", {
     description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. Returns the fileId \u2014 pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you) by default; pass shareClass:"SHARED" to share with co-parents directly via the My Files area.`,
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -38506,14 +38864,13 @@ ${text}` : text);
       description: external_exports.string().describe("Description shown in OFW My Files (default: filename)").optional()
     }
   }, async (args) => {
-    const abs = expandPath(args.path);
+    const abs = expandPath2(args.path);
     const stat = statSync(abs);
     if (!stat.isFile()) throw new Error(`Not a file: ${abs}`);
-    const buf = readFileSync(abs);
     const fileName = basename(abs);
     const mime = mimeFromName(fileName);
     const form = new FormData();
-    form.append("file", new Blob([new Uint8Array(buf)], { type: mime }), fileName);
+    form.append("file", await fileBlob(abs, { type: mime }), fileName);
     form.append("source", "message");
     form.append("description", args.description ?? fileName);
     form.append("label", args.label ?? fileName);
@@ -38525,7 +38882,7 @@ ${text}` : text);
       fileName: meta3.fileName ?? fileName,
       label: meta3.label ?? args.label ?? fileName,
       mimeType: meta3.fileType ?? mime,
-      sizeBytes: typeof meta3.sizeInBytes === "number" ? meta3.sizeInBytes : buf.length,
+      sizeBytes: typeof meta3.sizeInBytes === "number" ? meta3.sizeInBytes : stat.size,
       metadata: meta3,
       messageId: 0
     });
@@ -38533,12 +38890,12 @@ ${text}` : text);
       fileId: meta3.fileId,
       fileName: meta3.fileName ?? fileName,
       mimeType: meta3.fileType ?? mime,
-      sizeBytes: meta3.sizeInBytes ?? buf.length,
+      sizeBytes: meta3.sizeInBytes ?? stat.size,
       shareClass: meta3.shareClass ?? args.shareClass ?? "PRIVATE",
       note: "Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it."
     });
   });
-  server2.registerTool("ofw_download_attachment", {
+  server.registerTool("ofw_download_attachment", {
     description: 'Download an OFW message attachment by fileId. By default, bytes are saved to disk (~/Downloads/ofw-mcp/) and the response carries the absolute path, mime type, and size for the caller to read back. Pass inline:true to skip disk entirely and return the bytes as MCP content blocks \u2014 images come back as ImageContent (the model sees them directly); other files come back as an EmbeddedResource blob. Use inline for small files where you want the model to read content immediately and the host is sandboxed; use disk for large files or when you want a persistent local copy. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var (set to "true" to make inline the default). fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo. Re-downloading to the same path is a no-op (disk mode only).',
     annotations: { readOnlyHint: false },
     inputSchema: {
@@ -38592,7 +38949,7 @@ ${text}` : text);
     let dest;
     if (args.saveTo) {
       const isDirArg = args.saveTo.endsWith("/") || args.saveTo.endsWith("\\");
-      const abs = expandPath(args.saveTo);
+      const abs = expandPath2(args.saveTo);
       dest = isDirArg ? join5(abs, `${fileId}-${cached2.fileName}`) : abs;
     } else {
       dest = join5(getAttachmentsDir(), `${fileId}-${cached2.fileName}`);
@@ -38619,7 +38976,7 @@ ${text}` : text);
       fileName: response.suggestedFileName ?? cached2.fileName
     });
   });
-  server2.registerTool("ofw_sync_messages", {
+  server.registerTool("ofw_sync_messages", {
     description: "Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps).",
     annotations: { readOnlyHint: false },
     inputSchema: {
@@ -38643,8 +39000,8 @@ async function deleteOFWMessages(client2, ids) {
 }
 
 // src/tools/calendar.ts
-function registerCalendarTools(server2, client2) {
-  server2.registerTool("ofw_list_events", {
+function registerCalendarTools(server, client2) {
+  server.registerTool("ofw_list_events", {
     description: "List OurFamilyWizard calendar events in a date range",
     annotations: { readOnlyHint: true },
     inputSchema: {
@@ -38660,7 +39017,7 @@ function registerCalendarTools(server2, client2) {
     );
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_create_event", {
+  server.registerTool("ofw_create_event", {
     description: "Create a calendar event in OurFamilyWizard",
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -38680,7 +39037,7 @@ function registerCalendarTools(server2, client2) {
     const data = await client2.request("POST", "/pub/v1/calendar/events", args);
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_update_event", {
+  server.registerTool("ofw_update_event", {
     description: "Update an existing OurFamilyWizard calendar event",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -38698,7 +39055,7 @@ function registerCalendarTools(server2, client2) {
     const data = await client2.request("PUT", `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_delete_event", {
+  server.registerTool("ofw_delete_event", {
     description: "Delete an OurFamilyWizard calendar event",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -38711,15 +39068,15 @@ function registerCalendarTools(server2, client2) {
 }
 
 // src/tools/expenses.ts
-function registerExpenseTools(server2, client2) {
-  server2.registerTool("ofw_get_expense_totals", {
+function registerExpenseTools(server, client2) {
+  server.registerTool("ofw_get_expense_totals", {
     description: "Get OurFamilyWizard expense summary totals (owed/paid)",
     annotations: { readOnlyHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v2/expense/expenses/totals");
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_list_expenses", {
+  server.registerTool("ofw_list_expenses", {
     description: "List OurFamilyWizard expenses with pagination",
     annotations: { readOnlyHint: true },
     inputSchema: {
@@ -38732,7 +39089,7 @@ function registerExpenseTools(server2, client2) {
     const data = await client2.request("GET", `/pub/v2/expense/expenses?start=${start}&max=${max}`);
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_create_expense", {
+  server.registerTool("ofw_create_expense", {
     description: "Log a new expense in OurFamilyWizard",
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -38746,8 +39103,8 @@ function registerExpenseTools(server2, client2) {
 }
 
 // src/tools/journal.ts
-function registerJournalTools(server2, client2) {
-  server2.registerTool("ofw_list_journal_entries", {
+function registerJournalTools(server, client2) {
+  server.registerTool("ofw_list_journal_entries", {
     description: "List OurFamilyWizard journal entries",
     annotations: { readOnlyHint: true },
     inputSchema: {
@@ -38760,7 +39117,7 @@ function registerJournalTools(server2, client2) {
     const data = await client2.request("GET", `/pub/v1/journals?start=${start}&max=${max}`);
     return jsonResponse(data);
   });
-  server2.registerTool("ofw_create_journal_entry", {
+  server.registerTool("ofw_create_journal_entry", {
     description: "Create a new journal entry in OurFamilyWizard",
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -38784,12 +39141,17 @@ process.emit = function(event, ...args) {
   }
   return originalEmit(event, ...args);
 };
-var server = new McpServer({ name: "ofw", version: "2.2.0" });
-registerUserTools(server, client);
-registerMessageTools(server, client);
-registerCalendarTools(server, client);
-registerExpenseTools(server, client);
-registerJournalTools(server, client);
-console.error("[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.");
-var transport = new StdioServerTransport();
-await server.connect(transport);
+await runMcp({
+  name: "ofw",
+  version: "2.3.1",
+  // x-release-please-version
+  deps: client,
+  tools: [
+    registerUserTools,
+    registerMessageTools,
+    registerCalendarTools,
+    registerExpenseTools,
+    registerJournalTools
+  ],
+  banner: "[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion."
+});