ofw-mcp 2.3.0 → 2.3.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.3.0"
+    "version": "2.3.1"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "OurFamilyWizard",
       "source": "./",
       "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
-      "version": "2.3.0",
+      "version": "2.3.1",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ofw",
   "displayName": "OurFamilyWizard",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
   "author": {
     "name": "Chris Chall"

package/dist/auth.js

@@ -45,28 +45,21 @@
 //   - `./auth-password.js` (loginWithPassword) is a separate module
 //     specifically so it can be mocked here too. This keeps the
 //     selection logic independent of either implementation.
+import { readEnvVar } from '@chrischall/mcp-utils';
 import { bootstrap } from '@fetchproxy/bootstrap';
-import { classifyBridgeError } from '@fetchproxy/server';
+import { classifyBridgeError } from '@chrischall/mcp-utils/fetchproxy';
 import { loginWithPassword } from './auth-password.js';
 import { parseBoolEnv } from './config.js';
 import pkg from '../package.json' with { type: 'json' };
 /**
  * Read an env var, trim, and treat blank / `${UNEXPANDED}` placeholders as
  * unset. Defends against MCP hosts that pass `.mcp.json` env blocks through
- * without variable expansion.
+ * without variable expansion. Delegates to @chrischall/mcp-utils' `readEnvVar`,
+ * which applies the identical sanitization (blank, `undefined`/`null`,
+ * `${...}` placeholder → unset).
  */
 function readEnv(key) {
-    const raw = process.env[key];
-    if (typeof raw !== 'string')
-        return undefined;
-    const trimmed = raw.trim();
-    if (trimmed.length === 0)
-        return undefined;
-    if (trimmed === 'undefined' || trimmed === 'null')
-        return undefined;
-    if (/^\$\{[^}]*\}$/.test(trimmed))
-        return undefined;
-    return trimmed;
+    return readEnvVar(key);
 }
 /** True if the user has explicitly disabled the fetchproxy fallback. */
 function fetchproxyDisabled() {

package/dist/bundle.js

@@ -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.
@@ -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");
@@ -37343,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],
@@ -37378,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
       });
@@ -37401,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 } : {}
@@ -37414,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 } : {}
@@ -37430,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],
@@ -37454,7 +37598,7 @@ async function bootstrap(opts) {
     };
   } finally {
     try {
-      await server2.close();
+      await server.close();
     } catch {
     }
   }
@@ -37519,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();
@@ -37531,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.3.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>",
@@ -37579,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: {
+    "@chrischall/mcp-utils": "^0.4.0",
     "@fetchproxy/bootstrap": "^0.11.0",
-    "@fetchproxy/server": "^0.11.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -37599,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");
@@ -37668,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) {
@@ -37688,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 };
@@ -37817,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,
@@ -37831,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",
@@ -37848,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 () => {
@@ -38397,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: {
@@ -38441,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: {
@@ -38506,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: {
@@ -38616,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: {
@@ -38630,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: {
@@ -38692,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: {
@@ -38703,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: {
@@ -38729,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: {
@@ -38739,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);
@@ -38758,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
     });
@@ -38766,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: {
@@ -38825,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}`);
@@ -38852,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: {
@@ -38876,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: {
@@ -38893,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: {
@@ -38913,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: {
@@ -38931,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: {
@@ -38944,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: {
@@ -38965,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: {
@@ -38979,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: {
@@ -38993,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: {
@@ -39017,12 +39141,17 @@ process.emit = function(event, ...args) {
   }
   return originalEmit(event, ...args);
 };
-var server = new McpServer({ name: "ofw", version: "2.3.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."
+});

package/dist/cache.js

@@ -182,6 +182,7 @@ export function countMessages(opts) {
     const { where, params } = buildMessageFilter(opts);
     const r = db.prepare(`SELECT COUNT(*) as n FROM messages ${where}`)
         .get(...params);
+    /* v8 ignore next -- SELECT COUNT(*) always returns exactly one row; the ?./?? are defensive */
     return r?.n ?? 0;
 }
 function draftFromDb(r) {

package/dist/client.js

@@ -1,17 +1,14 @@
+import { loadDotenvSafely } from '@chrischall/mcp-utils';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveAuth } from './auth.js';
 import { parseBoolEnv } from './config.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
-// Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb bundle)
-try {
-    const { config } = await import('dotenv');
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    config({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
-}
-catch {
-    // not available — rely on process.env (mcpb sets credentials via mcp_config.env)
-}
+// Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
+// bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
+// missing dotenv module, matching the prior inline try/catch exactly.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join(__dirname, '..', '.env') });
 // Parse a Content-Disposition header for a filename. Prefers RFC 6266
 // `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
 function parseContentDispositionFilename(cd) {
@@ -36,6 +33,7 @@ function debugLogEnabled() {
 }
 function redactHeaders(h) {
     const out = { ...h };
+    /* v8 ignore next -- request headers always carry Authorization (set in request()); the guard is defensive for arbitrary header maps */
     if (out.Authorization)
         out.Authorization = `Bearer ${out.Authorization.slice(7, 17)}…`;
     return out;

package/dist/config.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { parseBoolEnv as parseBoolEnvUtil } from '@chrischall/mcp-utils';
 // Cache identity drives the per-user SQLite DB filename. Order of preference:
 //   1. OFW_CACHE_IDENTITY — explicit override for users who want to label the
 //      cache themselves (e.g. when authing via fetchproxy and OFW_USERNAME is
@@ -45,12 +46,13 @@ export function getAttachmentsDir() {
  * (case-insensitive, trimmed). Anything else — unset, empty, or other
  * values — is false. Used for OFW_INLINE_ATTACHMENTS, OFW_DISABLE_FETCHPROXY,
  * OFW_DEBUG_LOG, etc.
+ *
+ * Delegates to @chrischall/mcp-utils' `parseBoolEnv` (which also recognizes
+ * the falsy set 0/false/no/off — behavior-equivalent here since callers only
+ * care about the truthy case and everything else defaults to false).
  */
 export function parseBoolEnv(name) {
-    const raw = process.env[name];
-    if (typeof raw !== 'string')
-        return false;
-    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+    return parseBoolEnvUtil(name);
 }
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as

package/dist/index.js

@@ -9,20 +9,29 @@ process.emit = function (event, ...args) {
     }
     return originalEmit(event, ...args);
 };
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { runMcp } from '@chrischall/mcp-utils';
 import { client } from './client.js';
 import { registerUserTools } from './tools/user.js';
 import { registerMessageTools } from './tools/messages.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerJournalTools } from './tools/journal.js';
-const server = new McpServer({ name: 'ofw', version: '2.3.0' }); // x-release-please-version
-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.');
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// runMcp builds the McpServer, applies the registrars (with `client` threaded
+// through as deps), prints the banner to stderr, wires SIGINT/SIGTERM graceful
+// shutdown, and connects the stdio transport. The deferred-config-error pattern
+// is preserved: `client` is constructed at module load in ./client.js (auth is
+// resolved lazily on the first tool call), so the host's initial tools/list
+// always succeeds before any credential check runs.
+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.',
+});

package/dist/tools/_shared.js

@@ -1,10 +1,9 @@
-import { isAbsolute, join, resolve } from 'node:path';
-export function jsonResponse(payload) {
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
-}
-export function textResponse(text) {
-    return { content: [{ type: 'text', text }] };
-}
+import { expandPath as expandPathUtil, rawTextResult, textResult } from '@chrischall/mcp-utils';
+// Pretty-printed JSON tool result. Thin wrapper over @chrischall/mcp-utils'
+// `textResult` so the rest of the codebase keeps the local name.
+export const jsonResponse = textResult;
+// Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
+export const textResponse = rawTextResult;
 // Translates OFW API recipient shape into the cache's normalized Recipient.
 // Used wherever we surface or persist recipients (sync, get_message, send,
 // save_draft) — all five call sites had near-identical inline mappings.
@@ -15,11 +14,9 @@ export function mapRecipients(items) {
         viewedAt: r.viewed?.dateTime ?? null,
     }));
 }
-// Expand a user-provided path: ~ → $HOME, relative → absolute.
-export function expandPath(p) {
-    const expanded = p.startsWith('~/') ? join(process.env.HOME ?? '', p.slice(2)) : p;
-    return isAbsolute(expanded) ? expanded : resolve(expanded);
-}
+// Expand a user-provided path: ~ → home, relative → absolute. Re-exports
+// @chrischall/mcp-utils' `expandPath`.
+export const expandPath = expandPathUtil;
 /**
  * POST a payload to /pub/v3/messages, then immediately GET the detail
  * endpoint for the resulting message id. This is the only correct way to

package/dist/tools/messages.js

@@ -4,6 +4,7 @@ import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, ups
 import { getAttachmentsDir, getDefaultInlineAttachments } from '../config.js';
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
+import { fileBlob } from '@chrischall/mcp-utils';
 import { expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse } from './_shared.js';
 // Lightweight mime sniff from extension. OFW re-derives mime from the filename
 // server-side anyway, so this is just a polite Content-Type for the Blob.
@@ -425,12 +426,12 @@ export function registerMessageTools(server, client) {
         const stat = statSync(abs); // throws if missing
         if (!stat.isFile())
             throw new Error(`Not a file: ${abs}`);
-        const buf = readFileSync(abs);
         const fileName = basename(abs);
         const mime = mimeFromName(fileName);
         // Build the multipart payload matching the OFW web UI's request shape.
         const form = new FormData();
-        form.append('file', new Blob([new Uint8Array(buf)], { type: mime }), fileName);
+        // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
+        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);
@@ -445,7 +446,7 @@ export function registerMessageTools(server, client) {
             fileName: meta.fileName ?? fileName,
             label: meta.label ?? args.label ?? fileName,
             mimeType: meta.fileType ?? mime,
-            sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : buf.length,
+            sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : stat.size,
             metadata: meta,
             messageId: 0,
         });
@@ -453,7 +454,7 @@ export function registerMessageTools(server, client) {
             fileId: meta.fileId,
             fileName: meta.fileName ?? fileName,
             mimeType: meta.fileType ?? mime,
-            sizeBytes: meta.sizeInBytes ?? buf.length,
+            sizeBytes: meta.sizeInBytes ?? stat.size,
             shareClass: meta.shareClass ?? args.shareClass ?? 'PRIVATE',
             note: 'Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it.',
         });
@@ -476,6 +477,7 @@ export function registerMessageTools(server, client) {
             // sentinel — gets re-linked if a message later references this file.
             await fetchAttachmentMeta(client, fileId, 0);
             cached = getAttachment(fileId);
+            /* v8 ignore next -- fetchAttachmentMeta persists the row it just fetched; a still-null read here is an unreachable storage failure */
             if (!cached)
                 throw new Error(`failed to fetch metadata for fileId ${fileId}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,11 +24,12 @@
     "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": {
+    "@chrischall/mcp-utils": "^0.4.0",
     "@fetchproxy/bootstrap": "^0.11.0",
-    "@fetchproxy/server": "^0.11.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

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