ofw-mcp 2.0.8 → 2.0.9

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/bundle.js

@@ -2980,7 +2980,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve.call(this, root, ref);
+      let _sch = resolve2.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3007,7 +3007,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve(root, ref) {
+    function resolve2(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3582,7 +3582,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve(baseURI, relativeURI, options) {
+    function resolve2(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -3809,7 +3809,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve,
+      resolve: resolve2,
       resolveComponent,
       equal,
       serialize,
@@ -12700,7 +12700,7 @@ var Doc = class {
 var version = {
   major: 4,
   minor: 4,
-  patch: 2
+  patch: 3
 };
 
 // node_modules/zod/v4/core/schemas.js
@@ -14299,6 +14299,7 @@ var $ZodFile = /* @__PURE__ */ $constructor("$ZodFile", (inst, def) => {
 });
 var $ZodTransform = /* @__PURE__ */ $constructor("$ZodTransform", (inst, def) => {
   $ZodType.init(inst, def);
+  inst._zod.optin = "optional";
   inst._zod.parse = (payload, ctx) => {
     if (ctx.direction === "backward") {
       throw new $ZodEncodeError(inst.constructor.name);
@@ -14308,6 +14309,7 @@ var $ZodTransform = /* @__PURE__ */ $constructor("$ZodTransform", (inst, def) =>
       const output = _out instanceof Promise ? _out : Promise.resolve(_out);
       return output.then((output2) => {
         payload.value = output2;
+        payload.fallback = true;
         return payload;
       });
     }
@@ -14315,11 +14317,12 @@ var $ZodTransform = /* @__PURE__ */ $constructor("$ZodTransform", (inst, def) =>
       throw new $ZodAsyncError();
     }
     payload.value = _out;
+    payload.fallback = true;
     return payload;
   };
 });
 function handleOptionalResult(result, input) {
-  if (result.issues.length && input === void 0) {
+  if (input === void 0 && (result.issues.length || result.fallback)) {
     return { issues: [], value: void 0 };
   }
   return result;
@@ -14337,10 +14340,11 @@ var $ZodOptional = /* @__PURE__ */ $constructor("$ZodOptional", (inst, def) => {
   });
   inst._zod.parse = (payload, ctx) => {
     if (def.innerType._zod.optin === "optional") {
+      const input = payload.value;
       const result = def.innerType._zod.run(payload, ctx);
       if (result instanceof Promise)
-        return result.then((r) => handleOptionalResult(r, payload.value));
-      return handleOptionalResult(result, payload.value);
+        return result.then((r) => handleOptionalResult(r, input));
+      return handleOptionalResult(result, input);
     }
     if (payload.value === void 0) {
       return payload;
@@ -14456,7 +14460,7 @@ var $ZodSuccess = /* @__PURE__ */ $constructor("$ZodSuccess", (inst, def) => {
 });
 var $ZodCatch = /* @__PURE__ */ $constructor("$ZodCatch", (inst, def) => {
   $ZodType.init(inst, def);
-  defineLazy(inst._zod, "optin", () => def.innerType._zod.optin);
+  inst._zod.optin = "optional";
   defineLazy(inst._zod, "optout", () => def.innerType._zod.optout);
   defineLazy(inst._zod, "values", () => def.innerType._zod.values);
   inst._zod.parse = (payload, ctx) => {
@@ -14476,6 +14480,7 @@ var $ZodCatch = /* @__PURE__ */ $constructor("$ZodCatch", (inst, def) => {
             input: payload.value
           });
           payload.issues = [];
+          payload.fallback = true;
         }
         return payload;
       });
@@ -14490,6 +14495,7 @@ var $ZodCatch = /* @__PURE__ */ $constructor("$ZodCatch", (inst, def) => {
         input: payload.value
       });
       payload.issues = [];
+      payload.fallback = true;
     }
     return payload;
   };
@@ -14535,7 +14541,7 @@ function handlePipeResult(left, next, ctx) {
     left.aborted = true;
     return left;
   }
-  return next._zod.run({ value: left.value, issues: left.issues }, ctx);
+  return next._zod.run({ value: left.value, issues: left.issues, fallback: left.fallback }, ctx);
 }
 var $ZodCodec = /* @__PURE__ */ $constructor("$ZodCodec", (inst, def) => {
   $ZodType.init(inst, def);
@@ -14589,8 +14595,6 @@ function handleCodecTxResult(left, value, nextSchema, ctx) {
 }
 var $ZodPreprocess = /* @__PURE__ */ $constructor("$ZodPreprocess", (inst, def) => {
   $ZodPipe.init(inst, def);
-  defineLazy(inst._zod, "optin", () => def.out._zod.optin);
-  defineLazy(inst._zod, "optout", () => def.out._zod.optout);
 });
 var $ZodReadonly = /* @__PURE__ */ $constructor("$ZodReadonly", (inst, def) => {
   $ZodType.init(inst, def);
@@ -24541,10 +24545,12 @@ var ZodTransform = /* @__PURE__ */ $constructor("ZodTransform", (inst, def) => {
     if (output instanceof Promise) {
       return output.then((output2) => {
         payload.value = output2;
+        payload.fallback = true;
         return payload;
       });
     }
     payload.value = output;
+    payload.fallback = true;
     return payload;
   };
 });
@@ -28734,7 +28740,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -28751,7 +28757,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -28829,7 +28835,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve(parseResult.data);
+            resolve2(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -29090,12 +29096,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve, interval);
+      const timeoutId = setTimeout(resolve2, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -30195,7 +30201,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -30844,12 +30850,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve();
+        resolve2();
       } else {
-        this._stdout.once("drain", resolve);
+        this._stdout.once("drain", resolve2);
       }
     });
   }
@@ -30887,6 +30893,52 @@ var OFWClient = class {
     await this.ensureAuthenticated();
     return this.doRequest(method, path, body, false);
   }
+  /** Like `request`, but returns the raw bytes plus Content-Type/-Disposition metadata. */
+  async requestBinary(method, path) {
+    await this.ensureAuthenticated();
+    return this.doRequestBinary(method, path, false);
+  }
+  async doRequestBinary(method, path, isRetry) {
+    const headers = {
+      "ofw-client": "WebApplication",
+      "ofw-version": "1.0.0",
+      Accept: "application/octet-stream",
+      Authorization: `Bearer ${this.token}`
+    };
+    const response = await fetch(`${BASE_URL}${path}`, { method, headers });
+    if (response.status === 401 && !isRetry) {
+      this.token = null;
+      this.tokenExpiry = null;
+      await this.ensureAuthenticated();
+      return this.doRequestBinary(method, path, true);
+    }
+    if (response.status === 429 && !isRetry) {
+      await new Promise((r) => setTimeout(r, 2e3));
+      return this.doRequestBinary(method, path, true);
+    }
+    if (!response.ok) {
+      throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+    }
+    const buf = Buffer.from(await response.arrayBuffer());
+    const cd = response.headers.get("content-disposition") ?? "";
+    let suggestedFileName = null;
+    const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
+    if (extMatch) {
+      try {
+        suggestedFileName = decodeURIComponent(extMatch[1].trim().replace(/^"|"$/g, ""));
+      } catch {
+        suggestedFileName = extMatch[1];
+      }
+    } else {
+      const m = /filename="?([^";]+)"?/i.exec(cd);
+      if (m) suggestedFileName = m[1];
+    }
+    return {
+      body: buf,
+      contentType: response.headers.get("content-type"),
+      suggestedFileName
+    };
+  }
   async doRequest(method, path, body, isRetry) {
     const isFormData = body instanceof FormData;
     const headers = {
@@ -31015,6 +31067,13 @@ function getCacheDbPath() {
   const hash2 = createHash("sha256").update(username).digest("hex").slice(0, 16);
   return join2(getCacheDir(), `${hash2}.db`);
 }
+function getAttachmentsDir() {
+  const override = process.env.OFW_ATTACHMENTS_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  const username = readUsername();
+  const hash2 = createHash("sha256").update(username).digest("hex").slice(0, 16);
+  return join2(getCacheDir(), "attachments", hash2);
+}
 
 // src/cache.ts
 var instance = null;
@@ -31057,9 +31116,26 @@ CREATE TABLE IF NOT EXISTS meta (
   value TEXT NOT NULL
 );
 `;
+var SCHEMA_V2 = `
+CREATE TABLE IF NOT EXISTS attachments (
+  file_id INTEGER PRIMARY KEY,
+  file_name TEXT NOT NULL,
+  label TEXT NOT NULL,
+  mime_type TEXT NOT NULL,
+  size_bytes INTEGER,
+  metadata_json TEXT NOT NULL,
+  message_ids_json TEXT NOT NULL,  -- JSON array of message ids that reference this file
+  downloaded_path TEXT,             -- absolute path on disk if/when downloaded
+  downloaded_at TEXT,
+  fetched_metadata_at TEXT NOT NULL
+);
+`;
 function migrate(db) {
   db.exec(SCHEMA_V1);
-  db.prepare("INSERT OR IGNORE INTO meta(key, value) VALUES(?, ?)").run("schema_version", "1");
+  db.exec(SCHEMA_V2);
+  db.prepare(
+    "INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value"
+  ).run("schema_version", "2");
 }
 function openCache() {
   if (instance) return instance;
@@ -31273,8 +31349,95 @@ function findLatestReplyTip(replyToId) {
   ).get(chainRoot);
   return tip ? tip.id : replyToId;
 }
+function attachmentFromDb(r) {
+  return {
+    fileId: r.file_id,
+    fileName: r.file_name,
+    label: r.label,
+    mimeType: r.mime_type,
+    sizeBytes: r.size_bytes,
+    metadata: JSON.parse(r.metadata_json),
+    messageIds: JSON.parse(r.message_ids_json),
+    downloadedPath: r.downloaded_path,
+    downloadedAt: r.downloaded_at
+  };
+}
+function getAttachment(fileId) {
+  const { db } = openCache();
+  const r = db.prepare("SELECT * FROM attachments WHERE file_id = ?").get(fileId);
+  return r ? attachmentFromDb(r) : null;
+}
+function listAttachmentsForMessage(messageId) {
+  const { db } = openCache();
+  const rows = db.prepare(
+    `SELECT * FROM attachments
+     WHERE EXISTS (SELECT 1 FROM json_each(message_ids_json) WHERE value = ?)
+     ORDER BY file_id`
+  ).all(messageId);
+  return rows.map(attachmentFromDb);
+}
+function upsertAttachmentForMessage(input) {
+  const { db } = openCache();
+  const existing = db.prepare("SELECT message_ids_json FROM attachments WHERE file_id = ?").get(input.fileId);
+  let messageIds;
+  if (existing) {
+    const arr = JSON.parse(existing.message_ids_json);
+    messageIds = arr.includes(input.messageId) ? arr : [...arr, input.messageId];
+  } else {
+    messageIds = [input.messageId];
+  }
+  db.prepare(
+    `INSERT INTO attachments (
+       file_id, file_name, label, mime_type, size_bytes,
+       metadata_json, message_ids_json, fetched_metadata_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(file_id) DO UPDATE SET
+       file_name=excluded.file_name,
+       label=excluded.label,
+       mime_type=excluded.mime_type,
+       size_bytes=excluded.size_bytes,
+       metadata_json=excluded.metadata_json,
+       message_ids_json=excluded.message_ids_json,
+       fetched_metadata_at=excluded.fetched_metadata_at`
+  ).run(
+    input.fileId,
+    requireString("attachments.fileName", input.fileName),
+    requireString("attachments.label", input.label),
+    requireString("attachments.mimeType", input.mimeType),
+    nullish3(input.sizeBytes),
+    JSON.stringify(input.metadata ?? null),
+    JSON.stringify(messageIds),
+    (/* @__PURE__ */ new Date()).toISOString()
+  );
+}
+function markAttachmentDownloaded(fileId, path) {
+  const { db } = openCache();
+  db.prepare(
+    "UPDATE attachments SET downloaded_path = ?, downloaded_at = ? WHERE file_id = ?"
+  ).run(path, (/* @__PURE__ */ new Date()).toISOString(), fileId);
+}
 
 // src/sync.ts
+async function fetchAndCacheAttachmentMeta(client2, fileId, messageId) {
+  try {
+    const meta3 = await client2.request("GET", `/pub/v1/myfiles/${fileId}`);
+    upsertAttachmentForMessage({
+      fileId: meta3.fileId ?? fileId,
+      fileName: meta3.fileName ?? `file-${fileId}`,
+      label: meta3.label ?? meta3.fileName ?? `file-${fileId}`,
+      mimeType: meta3.fileType ?? "application/octet-stream",
+      sizeBytes: typeof meta3.fileSize === "number" ? meta3.fileSize : null,
+      metadata: meta3,
+      messageId
+    });
+  } catch {
+  }
+}
+async function fetchAttachmentMetaForMessage(client2, messageId, fileIds) {
+  for (const fid of fileIds) {
+    await fetchAndCacheAttachmentMeta(client2, fid, messageId);
+  }
+}
 async function resolveFolderIds(client2) {
   const data = await client2.request(
     "GET",
@@ -31321,10 +31484,14 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
       const shouldFetchBody = !isInboxUnread || opts.fetchUnreadBodies;
       let body = null;
       let fetchedBodyAt = null;
+      let detailFileIds = [];
       if (shouldFetchBody) {
         const detail = await client2.request("GET", `/pub/v3/messages/${item.id}`);
         body = detail.body ?? "";
         fetchedBodyAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (Array.isArray(detail.files) && detail.files.length > 0) {
+          detailFileIds = detail.files;
+        }
       } else {
         unread.push({
           id: item.id,
@@ -31348,6 +31515,9 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
       };
       upsertMessage(row);
       synced++;
+      if (detailFileIds.length > 0) {
+        await fetchAttachmentMetaForMessage(client2, item.id, detailFileIds);
+      }
     }
     if (!opts.deep && !pageHadNewItem) break;
     page++;
@@ -31422,6 +31592,8 @@ async function syncAll(client2, opts) {
 }
 
 // src/tools/messages.ts
+import { mkdirSync as mkdirSync2, writeFileSync } from "node:fs";
+import { dirname as dirname3, join as join3, isAbsolute, resolve } from "node:path";
 function registerMessageTools(server2, client2) {
   server2.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.",
@@ -31481,7 +31653,8 @@ function registerMessageTools(server2, client2) {
     const id = Number(args.messageId);
     const cached2 = getMessage(id);
     if (cached2 && cached2.body !== null) {
-      return { content: [{ type: "text", text: JSON.stringify(cached2, null, 2) }] };
+      const attachments2 = listAttachmentsForMessage(id);
+      return { content: [{ type: "text", text: JSON.stringify({ ...cached2, attachments: attachments2 }, null, 2) }] };
     }
     const detail = await client2.request("GET", `/pub/v3/messages/${encodeURIComponent(args.messageId)}`);
     const recipients = (detail.recipients ?? []).map((r) => ({
@@ -31495,7 +31668,7 @@ function registerMessageTools(server2, client2) {
       folder,
       subject: detail.subject,
       fromUser: detail.from?.name ?? "",
-      sentAt: detail.date.dateTime,
+      sentAt: detail.date?.dateTime ?? (/* @__PURE__ */ new Date()).toISOString(),
       recipients,
       body: detail.body ?? "",
       fetchedBodyAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -31504,7 +31677,11 @@ function registerMessageTools(server2, client2) {
       listData: cached2?.listData ?? detail
     };
     upsertMessage(row);
-    return { content: [{ type: "text", text: JSON.stringify(row, null, 2) }] };
+    if (Array.isArray(detail.files) && detail.files.length > 0) {
+      await fetchAttachmentMetaForMessage(client2, detail.id, detail.files);
+    }
+    const attachments = listAttachmentsForMessage(detail.id);
+    return { content: [{ type: "text", text: JSON.stringify({ ...row, attachments }, null, 2) }] };
   });
   server2.registerTool("ofw_send_message", {
     description: "Send a message via OurFamilyWizard. If sending from a draft, pass draftId to delete the draft after sending. 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).",
@@ -31681,6 +31858,63 @@ ${text}` : text;
     }
     return { content: [{ type: "text", text: JSON.stringify(unread, null, 2) }] };
   });
+  server2.registerTool("ofw_download_attachment", {
+    description: "Download an OFW message attachment by fileId. Bytes are saved to disk; the tool returns the absolute path, mime type, and size so the caller can then read/analyze the file. fileId comes from the attachments array on ofw_get_message. Saves under ~/.cache/ofw-mcp/attachments/<hash>/ by default (override via OFW_ATTACHMENTS_DIR or the saveTo argument). Re-downloading is a no-op if the file is already on disk.",
+    annotations: { readOnlyHint: false },
+    inputSchema: {
+      fileId: external_exports.number().describe("Attachment file id (from ofw_get_message \u2192 attachments[].fileId)"),
+      saveTo: external_exports.string().describe("Absolute path or directory to write to. If a directory, the OFW filename is used. Default: ~/.cache/ofw-mcp/attachments/<hash>/<fileId>-<filename>").optional(),
+      force: external_exports.boolean().describe("Re-download even if already on disk. Default false.").optional()
+    }
+  }, async (args) => {
+    const fileId = args.fileId;
+    let cached2 = getAttachment(fileId);
+    if (!cached2) {
+      const meta3 = await client2.request("GET", `/pub/v1/myfiles/${fileId}`);
+      upsertAttachmentForMessage({
+        fileId: meta3.fileId ?? fileId,
+        fileName: meta3.fileName ?? `file-${fileId}`,
+        label: meta3.label ?? meta3.fileName ?? `file-${fileId}`,
+        mimeType: meta3.fileType ?? "application/octet-stream",
+        sizeBytes: typeof meta3.fileSize === "number" ? meta3.fileSize : null,
+        metadata: meta3,
+        messageId: 0
+        // placeholder; will be cleaned up if a real message references it
+      });
+      cached2 = getAttachment(fileId);
+      if (!cached2) throw new Error(`failed to fetch metadata for fileId ${fileId}`);
+    }
+    let dest;
+    if (args.saveTo) {
+      const expanded = args.saveTo.startsWith("~/") ? join3(process.env.HOME ?? "", args.saveTo.slice(2)) : args.saveTo;
+      const abs = isAbsolute(expanded) ? expanded : resolve(expanded);
+      const isDirArg = expanded.endsWith("/") || expanded.endsWith("\\");
+      dest = isDirArg ? join3(abs, `${fileId}-${cached2.fileName}`) : abs;
+    } else {
+      dest = join3(getAttachmentsDir(), `${fileId}-${cached2.fileName}`);
+    }
+    if (!args.force && cached2.downloadedPath === dest) {
+      return { content: [{ type: "text", text: JSON.stringify({
+        fileId,
+        path: dest,
+        mimeType: cached2.mimeType,
+        sizeBytes: cached2.sizeBytes,
+        fileName: cached2.fileName,
+        note: "already downloaded"
+      }, null, 2) }] };
+    }
+    const response = await client2.requestBinary("GET", `/pub/v1/myfiles/${fileId}/data`);
+    mkdirSync2(dirname3(dest), { recursive: true });
+    writeFileSync(dest, response.body);
+    markAttachmentDownloaded(fileId, dest);
+    return { content: [{ type: "text", text: JSON.stringify({
+      fileId,
+      path: dest,
+      mimeType: response.contentType ?? cached2.mimeType,
+      sizeBytes: response.body.length,
+      fileName: response.suggestedFileName ?? cached2.fileName
+    }, null, 2) }] };
+  });
   server2.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 },
@@ -31841,7 +32075,7 @@ process.emit = function(event, ...args) {
   }
   return originalEmit(event, ...args);
 };
-var server = new McpServer({ name: "ofw", version: "2.0.8" });
+var server = new McpServer({ name: "ofw", version: "2.0.9" });
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/dist/cache.js

@@ -42,9 +42,25 @@ CREATE TABLE IF NOT EXISTS meta (
   value TEXT NOT NULL
 );
 `;
+// v2: add attachments table. Idempotent — IF NOT EXISTS.
+const SCHEMA_V2 = `
+CREATE TABLE IF NOT EXISTS attachments (
+  file_id INTEGER PRIMARY KEY,
+  file_name TEXT NOT NULL,
+  label TEXT NOT NULL,
+  mime_type TEXT NOT NULL,
+  size_bytes INTEGER,
+  metadata_json TEXT NOT NULL,
+  message_ids_json TEXT NOT NULL,  -- JSON array of message ids that reference this file
+  downloaded_path TEXT,             -- absolute path on disk if/when downloaded
+  downloaded_at TEXT,
+  fetched_metadata_at TEXT NOT NULL
+);
+`;
 function migrate(db) {
     db.exec(SCHEMA_V1);
-    db.prepare('INSERT OR IGNORE INTO meta(key, value) VALUES(?, ?)').run('schema_version', '1');
+    db.exec(SCHEMA_V2);
+    db.prepare('INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run('schema_version', '2');
 }
 export function openCache() {
     if (instance)
@@ -249,3 +265,58 @@ export function findLatestReplyTip(replyToId) {
      ORDER BY id DESC LIMIT 1`).get(chainRoot);
     return tip ? tip.id : replyToId;
 }
+function attachmentFromDb(r) {
+    return {
+        fileId: r.file_id,
+        fileName: r.file_name,
+        label: r.label,
+        mimeType: r.mime_type,
+        sizeBytes: r.size_bytes,
+        metadata: JSON.parse(r.metadata_json),
+        messageIds: JSON.parse(r.message_ids_json),
+        downloadedPath: r.downloaded_path,
+        downloadedAt: r.downloaded_at,
+    };
+}
+export function getAttachment(fileId) {
+    const { db } = openCache();
+    const r = db.prepare('SELECT * FROM attachments WHERE file_id = ?').get(fileId);
+    return r ? attachmentFromDb(r) : null;
+}
+export function listAttachmentsForMessage(messageId) {
+    const { db } = openCache();
+    // SQLite JSON1 contains check
+    const rows = db.prepare(`SELECT * FROM attachments
+     WHERE EXISTS (SELECT 1 FROM json_each(message_ids_json) WHERE value = ?)
+     ORDER BY file_id`).all(messageId);
+    return rows.map(attachmentFromDb);
+}
+export function upsertAttachmentForMessage(input) {
+    const { db } = openCache();
+    const existing = db.prepare('SELECT message_ids_json FROM attachments WHERE file_id = ?')
+        .get(input.fileId);
+    let messageIds;
+    if (existing) {
+        const arr = JSON.parse(existing.message_ids_json);
+        messageIds = arr.includes(input.messageId) ? arr : [...arr, input.messageId];
+    }
+    else {
+        messageIds = [input.messageId];
+    }
+    db.prepare(`INSERT INTO attachments (
+       file_id, file_name, label, mime_type, size_bytes,
+       metadata_json, message_ids_json, fetched_metadata_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(file_id) DO UPDATE SET
+       file_name=excluded.file_name,
+       label=excluded.label,
+       mime_type=excluded.mime_type,
+       size_bytes=excluded.size_bytes,
+       metadata_json=excluded.metadata_json,
+       message_ids_json=excluded.message_ids_json,
+       fetched_metadata_at=excluded.fetched_metadata_at`).run(input.fileId, requireString('attachments.fileName', input.fileName), requireString('attachments.label', input.label), requireString('attachments.mimeType', input.mimeType), nullish(input.sizeBytes), JSON.stringify(input.metadata ?? null), JSON.stringify(messageIds), new Date().toISOString());
+}
+export function markAttachmentDownloaded(fileId, path) {
+    const { db } = openCache();
+    db.prepare('UPDATE attachments SET downloaded_path = ?, downloaded_at = ? WHERE file_id = ?').run(path, new Date().toISOString(), fileId);
+}

package/dist/client.js

@@ -41,6 +41,56 @@ export class OFWClient {
         await this.ensureAuthenticated();
         return this.doRequest(method, path, body, false);
     }
+    /** Like `request`, but returns the raw bytes plus Content-Type/-Disposition metadata. */
+    async requestBinary(method, path) {
+        await this.ensureAuthenticated();
+        return this.doRequestBinary(method, path, false);
+    }
+    async doRequestBinary(method, path, isRetry) {
+        const headers = {
+            'ofw-client': 'WebApplication',
+            'ofw-version': '1.0.0',
+            Accept: 'application/octet-stream',
+            Authorization: `Bearer ${this.token}`,
+        };
+        const response = await fetch(`${BASE_URL}${path}`, { method, headers });
+        if (response.status === 401 && !isRetry) {
+            this.token = null;
+            this.tokenExpiry = null;
+            await this.ensureAuthenticated();
+            return this.doRequestBinary(method, path, true);
+        }
+        if (response.status === 429 && !isRetry) {
+            await new Promise((r) => setTimeout(r, 2000));
+            return this.doRequestBinary(method, path, true);
+        }
+        if (!response.ok) {
+            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+        }
+        const buf = Buffer.from(await response.arrayBuffer());
+        const cd = response.headers.get('content-disposition') ?? '';
+        // RFC 6266: filename*=UTF-8''… takes priority; fall back to filename="…"
+        let suggestedFileName = null;
+        const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
+        if (extMatch) {
+            try {
+                suggestedFileName = decodeURIComponent(extMatch[1].trim().replace(/^"|"$/g, ''));
+            }
+            catch {
+                suggestedFileName = extMatch[1];
+            }
+        }
+        else {
+            const m = /filename="?([^";]+)"?/i.exec(cd);
+            if (m)
+                suggestedFileName = m[1];
+        }
+        return {
+            body: buf,
+            contentType: response.headers.get('content-type'),
+            suggestedFileName,
+        };
+    }
     async doRequest(method, path, body, isRetry) {
         const isFormData = body instanceof FormData;
         const headers = {

package/dist/config.js

@@ -19,3 +19,12 @@ export function getCacheDbPath() {
     const hash = createHash('sha256').update(username).digest('hex').slice(0, 16);
     return join(getCacheDir(), `${hash}.db`);
 }
+export function getAttachmentsDir() {
+    const override = process.env.OFW_ATTACHMENTS_DIR;
+    if (override && override.trim().length > 0)
+        return override.trim();
+    // Sibling to the cache db: ~/.cache/ofw-mcp/attachments/<hash>/
+    const username = readUsername();
+    const hash = createHash('sha256').update(username).digest('hex').slice(0, 16);
+    return join(getCacheDir(), 'attachments', hash);
+}

package/dist/index.js

@@ -17,7 +17,7 @@ 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.0.8' });
+const server = new McpServer({ name: 'ofw', version: '2.0.9' });
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/dist/sync.js

@@ -1,4 +1,28 @@
-import { setMeta, upsertMessage, getMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, } from './cache.js';
+import { setMeta, upsertMessage, getMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
+export async function fetchAndCacheAttachmentMeta(client, fileId, messageId) {
+    try {
+        const meta = await client.request('GET', `/pub/v1/myfiles/${fileId}`);
+        upsertAttachmentForMessage({
+            fileId: meta.fileId ?? fileId,
+            fileName: meta.fileName ?? `file-${fileId}`,
+            label: meta.label ?? meta.fileName ?? `file-${fileId}`,
+            mimeType: meta.fileType ?? 'application/octet-stream',
+            sizeBytes: typeof meta.fileSize === 'number' ? meta.fileSize : null,
+            metadata: meta,
+            messageId,
+        });
+    }
+    catch {
+        // Attachment metadata failures shouldn't break the surrounding sync.
+        // The file ids stay in the message's listData; the model can retry later
+        // via ofw_download_attachment, which will surface the actual error.
+    }
+}
+export async function fetchAttachmentMetaForMessage(client, messageId, fileIds) {
+    for (const fid of fileIds) {
+        await fetchAndCacheAttachmentMeta(client, fid, messageId);
+    }
+}
 export async function resolveFolderIds(client) {
     const data = await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true');
     const sys = data.systemFolders ?? [];
@@ -46,10 +70,14 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             const shouldFetchBody = !isInboxUnread || opts.fetchUnreadBodies;
             let body = null;
             let fetchedBodyAt = null;
+            let detailFileIds = [];
             if (shouldFetchBody) {
                 const detail = await client.request('GET', `/pub/v3/messages/${item.id}`);
                 body = detail.body ?? '';
                 fetchedBodyAt = new Date().toISOString();
+                if (Array.isArray(detail.files) && detail.files.length > 0) {
+                    detailFileIds = detail.files;
+                }
             }
             else {
                 unread.push({
@@ -74,6 +102,9 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             };
             upsertMessage(row);
             synced++;
+            if (detailFileIds.length > 0) {
+                await fetchAttachmentMetaForMessage(client, item.id, detailFileIds);
+            }
         }
         // Stop heuristic: a page with no new items means we've reached cached
         // history (OFW returns date-desc). A page with even ONE new item could

package/dist/tools/messages.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
-import { syncAll } from '../sync.js';
-import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, } from '../cache.js';
+import { syncAll, fetchAttachmentMetaForMessage } from '../sync.js';
+import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, listAttachmentsForMessage, getAttachment, upsertAttachmentForMessage, markAttachmentDownloaded, } from '../cache.js';
+import { getAttachmentsDir } from '../config.js';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, isAbsolute, resolve } from 'node:path';
 export function registerMessageTools(server, client) {
     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.',
@@ -64,7 +67,8 @@ export function registerMessageTools(server, client) {
         const id = Number(args.messageId);
         const cached = getMessage(id);
         if (cached && cached.body !== null) {
-            return { content: [{ type: 'text', text: JSON.stringify(cached, null, 2) }] };
+            const attachments = listAttachmentsForMessage(id);
+            return { content: [{ type: 'text', text: JSON.stringify({ ...cached, attachments }, null, 2) }] };
         }
         const detail = await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`);
         const recipients = (detail.recipients ?? []).map((r) => ({
@@ -76,7 +80,7 @@ export function registerMessageTools(server, client) {
             folder,
             subject: detail.subject,
             fromUser: detail.from?.name ?? '',
-            sentAt: detail.date.dateTime,
+            sentAt: detail.date?.dateTime ?? new Date().toISOString(),
             recipients,
             body: detail.body ?? '',
             fetchedBodyAt: new Date().toISOString(),
@@ -85,7 +89,11 @@ export function registerMessageTools(server, client) {
             listData: cached?.listData ?? detail,
         };
         upsertMessage(row);
-        return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
+        if (Array.isArray(detail.files) && detail.files.length > 0) {
+            await fetchAttachmentMetaForMessage(client, detail.id, detail.files);
+        }
+        const attachments = listAttachmentsForMessage(detail.id);
+        return { content: [{ type: 'text', text: JSON.stringify({ ...row, attachments }, null, 2) }] };
     });
     server.registerTool('ofw_send_message', {
         description: 'Send a message via OurFamilyWizard. If sending from a draft, pass draftId to delete the draft after sending. 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).',
@@ -257,6 +265,69 @@ export function registerMessageTools(server, client) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(unread, null, 2) }] };
     });
+    server.registerTool('ofw_download_attachment', {
+        description: 'Download an OFW message attachment by fileId. Bytes are saved to disk; the tool returns the absolute path, mime type, and size so the caller can then read/analyze the file. fileId comes from the attachments array on ofw_get_message. Saves under ~/.cache/ofw-mcp/attachments/<hash>/ by default (override via OFW_ATTACHMENTS_DIR or the saveTo argument). Re-downloading is a no-op if the file is already on disk.',
+        annotations: { readOnlyHint: false },
+        inputSchema: {
+            fileId: z.number().describe('Attachment file id (from ofw_get_message → attachments[].fileId)'),
+            saveTo: z.string().describe('Absolute path or directory to write to. If a directory, the OFW filename is used. Default: ~/.cache/ofw-mcp/attachments/<hash>/<fileId>-<filename>').optional(),
+            force: z.boolean().describe('Re-download even if already on disk. Default false.').optional(),
+        },
+    }, async (args) => {
+        const fileId = args.fileId;
+        let cached = getAttachment(fileId);
+        if (!cached) {
+            // Metadata not in cache — fetch on the fly.
+            const meta = await client.request('GET', `/pub/v1/myfiles/${fileId}`);
+            // Store with a sentinel "metadata-only, no message link" — we don't know which message asked.
+            // We'll re-link if a message later references it during sync.
+            upsertAttachmentForMessage({
+                fileId: meta.fileId ?? fileId,
+                fileName: meta.fileName ?? `file-${fileId}`,
+                label: meta.label ?? meta.fileName ?? `file-${fileId}`,
+                mimeType: meta.fileType ?? 'application/octet-stream',
+                sizeBytes: typeof meta.fileSize === 'number' ? meta.fileSize : null,
+                metadata: meta,
+                messageId: 0, // placeholder; will be cleaned up if a real message references it
+            });
+            cached = getAttachment(fileId);
+            if (!cached)
+                throw new Error(`failed to fetch metadata for fileId ${fileId}`);
+        }
+        // Decide destination path
+        let dest;
+        if (args.saveTo) {
+            const expanded = args.saveTo.startsWith('~/')
+                ? join(process.env.HOME ?? '', args.saveTo.slice(2))
+                : args.saveTo;
+            const abs = isAbsolute(expanded) ? expanded : resolve(expanded);
+            // If it looks like a directory (ends with /) OR is an existing directory, treat as dir.
+            const isDirArg = expanded.endsWith('/') || expanded.endsWith('\\');
+            dest = isDirArg ? join(abs, `${fileId}-${cached.fileName}`) : abs;
+        }
+        else {
+            dest = join(getAttachmentsDir(), `${fileId}-${cached.fileName}`);
+        }
+        // Short-circuit if already downloaded to this path
+        if (!args.force && cached.downloadedPath === dest) {
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            fileId, path: dest, mimeType: cached.mimeType, sizeBytes: cached.sizeBytes,
+                            fileName: cached.fileName, note: 'already downloaded',
+                        }, null, 2) }] };
+        }
+        // Fetch bytes
+        const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, response.body);
+        markAttachmentDownloaded(fileId, dest);
+        return { content: [{ type: 'text', text: JSON.stringify({
+                        fileId,
+                        path: dest,
+                        mimeType: response.contentType ?? cached.mimeType,
+                        sizeBytes: response.body.length,
+                        fileName: response.suggestedFileName ?? cached.fileName,
+                    }, null, 2) }] };
+    });
     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 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "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>",

package/server.json

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