ofw-mcp 2.0.16 → 2.0.18

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.0.16"
+    "version": "2.0.18"
   },
   "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.16",
+      "version": "2.0.18",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -18,9 +18,31 @@ Ask Claude things like:
 ## Requirements
 
 - [Claude Desktop](https://claude.ai/download)
-- [Node.js](https://nodejs.org) 18 or later
+- [Node.js](https://nodejs.org) 22.5 or later (`node:sqlite` is the cache backend)
 - An active OurFamilyWizard account
 
+## Acknowledgement of Terms
+
+By using this MCP server, you acknowledge and agree to the following:
+
+**1. This server accesses your own OurFamilyWizard account.** Auth happens via your own credentials. It does not — and cannot — access your co-parent's account, your children's accounts, or anyone else's.
+
+**2. [OurFamilyWizard's Terms](https://www.ourfamilywizard.com/legal/terms) govern your use of this server**, just as they govern your direct use of OFW. There is no explicit anti-scraping clause; the governing language is broader:
+
+> Users may not obtain or attempt to obtain any materials or information through any means not intentionally made available.
+
+And on credentials: *"You are solely responsible for (1) maintaining the strict confidentiality of assigned Authentication Methods, (2) instructing any individual to whom the assigned Authentication Method is shared ('Authorized User') to not allow another person to use the Authentication Method."* OFW does contemplate "Authorized Users" and third-party-enabled integrations — but the account holder remains responsible.
+
+You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server.
+
+**3. Personal, family use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with OurFamilyWizard, LLC or its parent. It is a personal automation tool for the named account holder. Do not use it on behalf of a co-parent without their consent, do not share credentials with anyone, and do not use it to bulk-extract another family's data.
+
+**4. OFW is a court-of-record platform.** Messages, expenses, calendar entries, and journal entries on OFW may be entered into legal proceedings — including custody, divorce, and parenting-plan-modification cases. Anything this server writes to OFW (drafts you save, events you create, expenses you log) will appear with the same legal weight as if you had typed it yourself. **Do not let this MCP send a message, create an event, or log an expense that you have not read and approved.** Review every write operation before confirming.
+
+**5. You accept full responsibility** for any consequences — both technical (account warnings, suspension) and legal (anything OFW records about your account activity). The MCP author is not your attorney; if you're using OFW in connection with an active legal matter, talk to your actual attorney before automating anything.
+
+This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede OurFamilyWizard's actual ToS.
+
 ## Installation
 
 ### 1. Clone and build
@@ -147,25 +169,32 @@ Read-only tools run automatically. Write tools ask for your confirmation first.
 ## Development
 
 ```bash
-npm test        # run the test suite
-npm run build   # compile TypeScript → dist/
+npm test         # run the vitest suite
+npm run build    # tsc → dist/, then esbuild bundle → dist/bundle.js
+npm run dev      # node --env-file=.env dist/index.js (requires built dist)
 ```
 
+Main is protected. All changes land via PR — open with `gh pr create --label <release-notes-label>` and add `ready-to-merge` once you're satisfied with the auto-review feedback. See `CLAUDE.md` for the full PR + release flow.
+
 ### Project structure
 
 ```
 src/
-  client.ts       OFW auth and HTTP client
-  index.ts        MCP server entry point
-  tools/
-    user.ts       ofw_get_profile, ofw_get_notifications
-    messages.ts   folders, list, get, send
-    calendar.ts   list, create, update, delete events
-    expenses.ts   totals, list, create
-    journal.ts    list, create entries
-tests/
-  client.test.ts
+  index.ts          MCP server entry (McpServer + StdioServerTransport)
+  client.ts         OFW HTTP client with Bearer token + 401/429 retry
+  auth.ts           resolveAuth(): env-var creds → fetchproxy → error
+  auth-password.ts  Spring Security form login (legacy env-var path)
+  cache.ts          SQLite cache (messages, drafts, attachments, sync state)
+  sync.ts           Folder ID resolution + per-folder sync logic
+  config.ts         Cache dir, attachment dir, env parsing
   tools/
+    _shared.ts      Recipient mapping, response helpers, path expansion
+    user.ts         ofw_get_profile, ofw_get_notifications
+    messages.ts     Folders, list, get, send, drafts, sync, attachments
+    calendar.ts     List, create, update, delete events
+    expenses.ts     Totals, list, create
+    journal.ts      List, create entries
+tests/              Mirrors src/; mocks OFWClient.request via vi.spyOn
 ```
 
 ### Auth flow

package/dist/auth-password.js

@@ -9,11 +9,7 @@
 // This file exists as a standalone helper (not a method on `OFWClient`) so
 // `resolveAuth()` in `./auth.ts` can call it without a Client instance, and
 // so tests can mock it at the module boundary.
-const BASE_URL = 'https://ofw.ourfamilywizard.com';
-const OFW_PROTOCOL_HEADERS = {
-    'ofw-client': 'WebApplication',
-    'ofw-version': '1.0.0',
-};
+import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS } from './protocol.js';
 export async function loginWithPassword(username, password) {
     // Step 1: get a SESSION cookie (Spring Security refuses the POST without it).
     const initResponse = await fetch(`${BASE_URL}/ofw/login.form`, {
@@ -49,9 +45,6 @@ export async function loginWithPassword(username, password) {
     const data = (await response.json());
     return {
         token: data.auth,
-        // OFW's login endpoint omits expiry. 6h is the empirical TTL and matches
-        // the historical behavior of this client (a single 401 → re-auth + replay
-        // covers the edge case where this estimate is wrong).
-        expiresAt: new Date(Date.now() + 6 * 60 * 60 * 1000),
+        expiresAt: new Date(Date.now() + OFW_TOKEN_TTL_MS),
     };
 }

package/dist/auth.js

@@ -47,6 +47,7 @@
 //     selection logic independent of either implementation.
 import { bootstrap } from '@fetchproxy/bootstrap';
 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
@@ -68,10 +69,7 @@ function readEnv(key) {
 }
 /** True if the user has explicitly disabled the fetchproxy fallback. */
 function fetchproxyDisabled() {
-    const raw = readEnv('OFW_DISABLE_FETCHPROXY');
-    if (raw === undefined)
-        return false;
-    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+    return parseBoolEnv('OFW_DISABLE_FETCHPROXY');
 }
 /**
  * Resolve OFW auth using the three-path priority described at the top of

package/dist/bundle.js

@@ -34490,7 +34490,7 @@ var StdioServerTransport = class {
 };
 
 // src/client.ts
-import { dirname, join as join2 } from "path";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
@@ -36567,12 +36567,16 @@ var BootstrapDisabledError = class extends Error {
   }
 };
 
-// src/auth-password.ts
+// src/protocol.ts
 var BASE_URL = "https://ofw.ourfamilywizard.com";
 var OFW_PROTOCOL_HEADERS = {
   "ofw-client": "WebApplication",
   "ofw-version": "1.0.0"
 };
+var OFW_TOKEN_TTL_MS = 6 * 60 * 60 * 1e3;
+var OFW_TOKEN_EXPIRY_SKEW_MS = 5 * 60 * 1e3;
+
+// src/auth-password.ts
 async function loginWithPassword(username, password) {
   const initResponse = await fetch(`${BASE_URL}/ofw/login.form`, {
     headers: { ...OFW_PROTOCOL_HEADERS },
@@ -36606,17 +36610,49 @@ async function loginWithPassword(username, password) {
   const data = await response.json();
   return {
     token: data.auth,
-    // OFW's login endpoint omits expiry. 6h is the empirical TTL and matches
-    // the historical behavior of this client (a single 401 → re-auth + replay
-    // covers the edge case where this estimate is wrong).
-    expiresAt: new Date(Date.now() + 6 * 60 * 60 * 1e3)
+    expiresAt: new Date(Date.now() + OFW_TOKEN_TTL_MS)
   };
 }
 
+// src/config.ts
+import { createHash } from "node:crypto";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+function readCacheIdentity() {
+  const explicit = process.env.OFW_CACHE_IDENTITY;
+  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
+  const username = process.env.OFW_USERNAME;
+  if (typeof username === "string" && username.trim().length > 0) return username.trim();
+  return "_default";
+}
+function getCacheDir() {
+  const override = process.env.OFW_CACHE_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join2(homedir2(), ".cache", "ofw-mcp");
+}
+function getCacheDbPath() {
+  const identity = readCacheIdentity();
+  const hash2 = createHash("sha256").update(identity).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();
+  return join2(homedir2(), "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 getDefaultInlineAttachments() {
+  return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
+}
+
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.0.16",
+  version: "2.0.18",
   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>",
@@ -36668,9 +36704,7 @@ function readEnv(key) {
   return trimmed;
 }
 function fetchproxyDisabled() {
-  const raw = readEnv("OFW_DISABLE_FETCHPROXY");
-  if (raw === void 0) return false;
-  return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+  return parseBoolEnv("OFW_DISABLE_FETCHPROXY");
 }
 async function resolveAuth() {
   const username = readEnv("OFW_USERNAME");
@@ -36727,14 +36761,9 @@ async function resolveAuth() {
 try {
   const { config: config2 } = await import("dotenv");
   const __dirname = dirname(fileURLToPath(import.meta.url));
-  config2({ path: join2(__dirname, "..", ".env"), override: false, quiet: true });
+  config2({ path: join3(__dirname, "..", ".env"), override: false, quiet: true });
 } catch {
 }
-var BASE_URL2 = "https://ofw.ourfamilywizard.com";
-var OFW_PROTOCOL_HEADERS2 = {
-  "ofw-client": "WebApplication",
-  "ofw-version": "1.0.0"
-};
 function parseContentDispositionFilename(cd) {
   const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
   if (extMatch) {
@@ -36749,8 +36778,7 @@ function parseContentDispositionFilename(cd) {
   return m ? m[1] : null;
 }
 function debugLogEnabled() {
-  const v = process.env.OFW_DEBUG_LOG;
-  return v === "1" || v === "true" || v === "yes" || v === "on";
+  return parseBoolEnv("OFW_DEBUG_LOG");
 }
 function redactHeaders(h) {
   const out = { ...h };
@@ -36785,12 +36813,12 @@ var OFWClient = class {
   async fetchWithRetry(method, path, body, accept, isRetry) {
     const isFormData = body instanceof FormData;
     const headers = {
-      ...OFW_PROTOCOL_HEADERS2,
+      ...OFW_PROTOCOL_HEADERS,
       Accept: accept,
       Authorization: `Bearer ${this.token}`
     };
     if (body !== void 0 && !isFormData) headers["Content-Type"] = "application/json";
-    const url2 = `${BASE_URL2}${path}`;
+    const url2 = `${BASE_URL}${path}`;
     if (debugLogEnabled()) {
       const bodyPreview = body === void 0 ? "<none>" : isFormData ? `<FormData entries=${Array.from(body.keys()).join(",")}>` : JSON.stringify(body);
       console.error(`[ofw-debug] \u2192 ${method} ${url2}${isRetry ? " (retry)" : ""}`);
@@ -36838,17 +36866,17 @@ var OFWClient = class {
   async login() {
     const { token, expiresAt } = await resolveAuth();
     this.token = token;
-    this.tokenExpiry = expiresAt ?? new Date(Date.now() + 6 * 60 * 60 * 1e3);
+    this.tokenExpiry = expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS);
   }
   isTokenExpiredSoon() {
     if (!this.token || !this.tokenExpiry) return true;
-    return this.tokenExpiry.getTime() - Date.now() < 5 * 60 * 1e3;
+    return this.tokenExpiry.getTime() - Date.now() < OFW_TOKEN_EXPIRY_SKEW_MS;
   }
 };
 var client = new OFWClient();
 
 // src/tools/_shared.ts
-import { isAbsolute, join as join3, resolve } from "node:path";
+import { isAbsolute, join as join4, resolve } from "node:path";
 function jsonResponse(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
@@ -36863,9 +36891,20 @@ function mapRecipients(items) {
   }));
 }
 function expandPath(p) {
-  const expanded = p.startsWith("~/") ? join3(process.env.HOME ?? "", p.slice(2)) : p;
+  const expanded = p.startsWith("~/") ? join4(process.env.HOME ?? "", p.slice(2)) : p;
   return isAbsolute(expanded) ? expanded : resolve(expanded);
 }
+async function postMessageAndRefetch(client2, payload) {
+  const raw = await client2.request(
+    "POST",
+    "/pub/v3/messages",
+    payload
+  );
+  const id = typeof raw?.id === "number" ? raw.id : typeof raw?.entityId === "number" ? raw.entityId : null;
+  if (id === null) return { id: null, detail: null, raw };
+  const detail = await client2.request("GET", `/pub/v3/messages/${id}`);
+  return { id, detail, raw };
+}
 
 // src/tools/user.ts
 function registerUserTools(server2, client2) {
@@ -36889,40 +36928,6 @@ function registerUserTools(server2, client2) {
 import { DatabaseSync } from "node:sqlite";
 import { mkdirSync } from "node:fs";
 import { dirname as dirname2 } from "node:path";
-
-// src/config.ts
-import { createHash } from "node:crypto";
-import { homedir as homedir2 } from "node:os";
-import { join as join4 } from "node:path";
-function readCacheIdentity() {
-  const explicit = process.env.OFW_CACHE_IDENTITY;
-  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
-  const username = process.env.OFW_USERNAME;
-  if (typeof username === "string" && username.trim().length > 0) return username.trim();
-  return "_default";
-}
-function getCacheDir() {
-  const override = process.env.OFW_CACHE_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join4(homedir2(), ".cache", "ofw-mcp");
-}
-function getCacheDbPath() {
-  const identity = readCacheIdentity();
-  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
-  return join4(getCacheDir(), `${hash2}.db`);
-}
-function getAttachmentsDir() {
-  const override = process.env.OFW_ATTACHMENTS_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join4(homedir2(), "Downloads", "ofw-mcp");
-}
-function getDefaultInlineAttachments() {
-  const raw = process.env.OFW_INLINE_ATTACHMENTS;
-  if (typeof raw !== "string") return false;
-  return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
-}
-
-// src/cache.ts
 var instance = null;
 var SCHEMA_V1 = `
 CREATE TABLE IF NOT EXISTS messages (
@@ -37056,6 +37061,10 @@ function getMessage(id) {
   const r = db.prepare("SELECT * FROM messages WHERE id = ?").get(id);
   return r ? rowFromDb(r) : null;
 }
+function deleteMessage(id) {
+  const { db } = openCache();
+  db.prepare("DELETE FROM messages WHERE id = ?").run(id);
+}
 function buildMessageFilter(opts) {
   const wheres = [];
   const params = [];
@@ -37266,12 +37275,7 @@ async function fetchAttachmentMeta(client2, fileId, messageId) {
   });
 }
 async function fetchAttachmentMetaForMessage(client2, messageId, fileIds) {
-  for (const fid of fileIds) {
-    try {
-      await fetchAttachmentMeta(client2, fid, messageId);
-    } catch {
-    }
-  }
+  await Promise.allSettled(fileIds.map((fid) => fetchAttachmentMeta(client2, fid, messageId)));
 }
 async function resolveFolderIds(client2) {
   const data = await client2.request(
@@ -37377,6 +37381,7 @@ async function syncDrafts(client2, draftsFolderId) {
       listData: item
     };
     upsertDraft(row);
+    if (getMessage(item.id)) deleteMessage(item.id);
     if (!existing || existing.body !== row.body || existing.subject !== row.subject || existing.replyToId !== row.replyToId) {
       synced++;
     }
@@ -37496,13 +37501,33 @@ function registerMessageTools(server2, client2) {
     return jsonResponse(payload);
   });
   server2.registerTool("ofw_get_message", {
-    description: "Get a single OurFamilyWizard message by ID. Reads from local cache when available; otherwise fetches from OFW (which will mark unread inbox messages as read on OFW).",
+    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: {
-      messageId: external_exports.string().describe("Message ID")
+      messageId: external_exports.string().describe("Message ID (also accepts draft IDs \u2014 drafts are routed via the drafts cache)")
     }
   }, async (args) => {
     const id = Number(args.messageId);
+    const draftRow = getDraft(id);
+    if (draftRow !== null) {
+      return jsonResponse({
+        id: draftRow.id,
+        folder: "drafts",
+        subject: draftRow.subject,
+        fromUser: "",
+        sentAt: draftRow.modifiedAt,
+        recipients: draftRow.recipients,
+        body: draftRow.body,
+        // Best approximation: drafts don't separately track when the body
+        // was last *fetched* — we last wrote it on the last sync, which
+        // also updates modifiedAt.
+        fetchedBodyAt: draftRow.modifiedAt,
+        replyToId: draftRow.replyToId,
+        chainRootId: null,
+        listData: draftRow.listData,
+        attachments: []
+      });
+    }
     const cached2 = getMessage(id);
     if (cached2 && cached2.body !== null) {
       let attachments2 = listAttachmentsForMessage(id);
@@ -37565,7 +37590,7 @@ function registerMessageTools(server2, client2) {
       chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
     }
     const myFileIDs = args.myFileIDs ?? [];
-    const data = await client2.request("POST", "/pub/v3/messages", {
+    const { id: newId, detail, raw } = await postMessageAndRefetch(client2, {
       subject: args.subject,
       body: args.body,
       recipientIds: args.recipientIds,
@@ -37574,10 +37599,8 @@ function registerMessageTools(server2, client2) {
       includeOriginal: resolvedReplyTo !== null,
       replyToId: resolvedReplyTo
     });
-    const newId = typeof data?.id === "number" ? data.id : typeof data?.entityId === "number" ? data.entityId : null;
     let persisted = null;
     if (newId !== null) {
-      const detail = await client2.request("GET", `/pub/v3/messages/${newId}`);
       persisted = {
         id: newId,
         folder: "sent",
@@ -37609,7 +37632,7 @@ function registerMessageTools(server2, client2) {
       await deleteOFWMessages(client2, [args.draftId]);
       deleteDraft(args.draftId);
     }
-    const responseObj = persisted ?? data;
+    const responseObj = persisted ?? raw;
     const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Message sent successfully.";
     return textResponse(rewriteNote ? `${rewriteNote}
 
@@ -37630,13 +37653,13 @@ ${text}` : text);
     return jsonResponse(payload);
   });
   server2.registerTool("ofw_save_draft", {
-    description: "Save a message as a draft in OurFamilyWizard. Recipients are optional. To update an existing draft, provide its messageId. 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 and verify what was actually persisted; if OFW silently no-ops an update (a known issue with repeated updates to the same draft), the response includes a WARNING note with a workaround.",
+    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: {
       subject: external_exports.string().describe("Message subject"),
       body: external_exports.string().describe("Message body text"),
       recipientIds: external_exports.array(external_exports.number()).describe("Array of recipient user IDs (optional for drafts)").optional(),
-      messageId: external_exports.number().describe("ID of an existing draft to update (omit to create a new draft)").optional(),
+      messageId: external_exports.number().describe("ID of an existing draft to replace (the new draft will have a new id; the old is deleted)").optional(),
       replyToId: external_exports.number().describe("ID of the message this draft replies to").optional(),
       myFileIDs: external_exports.array(external_exports.number()).describe("Attachment file ids (from ofw_upload_attachment)").optional()
     }
@@ -37660,13 +37683,10 @@ ${text}` : text);
       includeOriginal: resolvedReplyTo !== null,
       replyToId: resolvedReplyTo
     };
-    if (args.messageId !== void 0) payload.messageId = args.messageId;
-    const data = await client2.request("POST", "/pub/v3/messages", payload);
-    const newId = typeof data?.id === "number" ? data.id : typeof data?.entityId === "number" ? data.entityId : null;
+    const { id: newId, detail, raw } = await postMessageAndRefetch(client2, payload);
     let persisted = null;
-    let noOpWarning = null;
+    let replaceNote = null;
     if (newId !== null) {
-      const detail = await client2.request("GET", `/pub/v3/messages/${newId}`);
       persisted = {
         id: newId,
         subject: detail.subject ?? args.subject,
@@ -37677,13 +37697,19 @@ ${text}` : text);
         listData: detail
       };
       upsertDraft(persisted);
-      if (args.messageId !== void 0 && persisted.body !== args.body) {
-        noOpWarning = "WARNING: OFW reported success but the draft body it returned does not match the requested update. The OFW POST /pub/v3/messages endpoint can silently no-op on subsequent updates to the same draft. Workaround: delete this draft (ofw_delete_draft) and create a new one (ofw_save_draft without messageId).";
+      if (args.messageId !== void 0 && args.messageId !== newId) {
+        try {
+          await deleteOFWMessages(client2, [args.messageId]);
+          deleteDraft(args.messageId);
+          replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.)`;
+        } catch (e) {
+          replaceNote = `WARNING: New draft ${newId} created successfully, but failed to delete the old draft (${args.messageId}): ${e.message}. You may want to clean it up manually with ofw_delete_draft.`;
+        }
       }
     }
-    const responseObj = persisted ?? data;
+    const responseObj = persisted ?? raw;
     const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Draft saved.";
-    const notes = [rewriteNote, noOpWarning].filter((n) => n !== null).join("\n\n");
+    const notes = [rewriteNote, replaceNote].filter((n) => n !== null).join("\n\n");
     return textResponse(notes ? `${notes}
 
 ${text}` : text);
@@ -37911,7 +37937,7 @@ function registerCalendarTools(server2, client2) {
   });
   server2.registerTool("ofw_update_event", {
     description: "Update an existing OurFamilyWizard calendar event",
-    annotations: { destructiveHint: false },
+    annotations: { destructiveHint: true },
     inputSchema: {
       eventId: external_exports.string(),
       title: external_exports.string().optional(),
@@ -38013,7 +38039,7 @@ process.emit = function(event, ...args) {
   }
   return originalEmit(event, ...args);
 };
-var server = new McpServer({ name: "ofw", version: "2.0.16" });
+var server = new McpServer({ name: "ofw", version: "2.0.18" });
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/dist/cache.js

@@ -131,6 +131,16 @@ export function getMessage(id) {
     const r = db.prepare('SELECT * FROM messages WHERE id = ?').get(id);
     return r ? rowFromDb(r) : null;
 }
+/**
+ * Remove a row from the `messages` table. Used by syncDrafts to evict
+ * stale rows that were cached when a draft was previously read through
+ * `ofw_get_message` (which would have wrongly classified it as `inbox`)
+ * — the drafts table is the authoritative source for that id now.
+ */
+export function deleteMessage(id) {
+    const { db } = openCache();
+    db.prepare('DELETE FROM messages WHERE id = ?').run(id);
+}
 // Build the WHERE clause + bound params for message queries. listMessages and
 // countMessages share this so the filter semantics can't drift.
 function buildMessageFilter(opts) {

package/dist/client.js

@@ -1,6 +1,8 @@
 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');
@@ -10,11 +12,6 @@ try {
 catch {
     // not available — rely on process.env (mcpb sets credentials via mcp_config.env)
 }
-const BASE_URL = 'https://ofw.ourfamilywizard.com';
-const OFW_PROTOCOL_HEADERS = {
-    'ofw-client': 'WebApplication',
-    'ofw-version': '1.0.0',
-};
 // Parse a Content-Disposition header for a filename. Prefers RFC 6266
 // `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
 function parseContentDispositionFilename(cd) {
@@ -35,8 +32,7 @@ function parseContentDispositionFilename(cd) {
 // stderr. Authorization is redacted. Bodies are logged in full — set this
 // only when debugging, never in normal use.
 function debugLogEnabled() {
-    const v = process.env.OFW_DEBUG_LOG;
-    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+    return parseBoolEnv('OFW_DEBUG_LOG');
 }
 function redactHeaders(h) {
     const out = { ...h };
@@ -131,12 +127,12 @@ export class OFWClient {
     async login() {
         const { token, expiresAt } = await resolveAuth();
         this.token = token;
-        this.tokenExpiry = expiresAt ?? new Date(Date.now() + 6 * 60 * 60 * 1000);
+        this.tokenExpiry = expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS);
     }
     isTokenExpiredSoon() {
         if (!this.token || !this.tokenExpiry)
             return true;
-        return this.tokenExpiry.getTime() - Date.now() < 5 * 60 * 1000;
+        return this.tokenExpiry.getTime() - Date.now() < OFW_TOKEN_EXPIRY_SKEW_MS;
     }
 }
 export const client = new OFWClient();

package/dist/config.js

@@ -40,14 +40,22 @@ export function getAttachmentsDir() {
     // location across macOS/Linux/Windows.
     return join(homedir(), 'Downloads', 'ofw-mcp');
 }
+/**
+ * True when a boolean-shaped env var is set to "1", "true", "yes", or "on"
+ * (case-insensitive, trimmed). Anything else — unset, empty, or other
+ * values — is false. Used for OFW_INLINE_ATTACHMENTS, OFW_DISABLE_FETCHPROXY,
+ * OFW_DEBUG_LOG, etc.
+ */
+export function parseBoolEnv(name) {
+    const raw = process.env[name];
+    if (typeof raw !== 'string')
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+}
 // 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
 // MCP content blocks by default (skipping disk) — useful on sandboxed MCP
 // hosts where filesystem reads back to the model aren't available.
-// Accepts: "1", "true", "yes", "on" (case-insensitive) → true; anything else → false.
 export function getDefaultInlineAttachments() {
-    const raw = process.env.OFW_INLINE_ATTACHMENTS;
-    if (typeof raw !== 'string')
-        return false;
-    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+    return parseBoolEnv('OFW_INLINE_ATTACHMENTS');
 }

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.16' });
+const server = new McpServer({ name: 'ofw', version: '2.0.18' }); // x-release-please-version
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/dist/protocol.js

@@ -0,0 +1,17 @@
+// Wire-level constants shared by client.ts (general API calls) and
+// auth-password.ts (form-login). Kept in a leaf module to avoid an import
+// cycle between client.ts → auth.ts → auth-password.ts.
+export const BASE_URL = 'https://ofw.ourfamilywizard.com';
+// Required on every OFW API request. `ofw-version` is the OFW protocol
+// version, not this package's version — do NOT bump it during a release.
+export const OFW_PROTOCOL_HEADERS = {
+    'ofw-client': 'WebApplication',
+    'ofw-version': '1.0.0',
+};
+// OFW doesn't return a token expiry, so we synthesize one. Six hours is
+// empirically long enough to be useful and short enough that the 401
+// re-auth replay path stays a rare event rather than the common case.
+export const OFW_TOKEN_TTL_MS = 6 * 60 * 60 * 1000;
+// How early we treat a token as expiring. Re-auth before this skew so a
+// long-running request doesn't get a stale token mid-flight.
+export const OFW_TOKEN_EXPIRY_SKEW_MS = 5 * 60 * 1000;

package/dist/sync.js

@@ -1,4 +1,4 @@
-import { setMeta, upsertMessage, getMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
+import { setMeta, upsertMessage, getMessage, deleteMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
 import { mapRecipients } from './tools/_shared.js';
 // Fetches OFW attachment metadata for one file id and writes it to the cache.
 // Throws on network/HTTP errors — callers in bulk-sync paths wrap this in the
@@ -17,15 +17,11 @@ export async function fetchAttachmentMeta(client, fileId, messageId) {
     });
 }
 export async function fetchAttachmentMetaForMessage(client, messageId, fileIds) {
-    for (const fid of fileIds) {
-        // Best-effort: a single bad attachment shouldn't break the surrounding
-        // sync. The file id stays in the message's listData; the model can
-        // retry later via ofw_download_attachment, which surfaces the real error.
-        try {
-            await fetchAttachmentMeta(client, fid, messageId);
-        }
-        catch { /* swallow */ }
-    }
+    // Fan out in parallel — each fetch is independent and the file id stays
+    // in listData on failure (model can retry via ofw_download_attachment,
+    // which surfaces the real error). Promise.allSettled so one bad
+    // attachment doesn't break the surrounding sync.
+    await Promise.allSettled(fileIds.map((fid) => fetchAttachmentMeta(client, fid, messageId)));
 }
 export async function resolveFolderIds(client) {
     const data = await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true');
@@ -142,6 +138,12 @@ export async function syncDrafts(client, draftsFolderId) {
             listData: item,
         };
         upsertDraft(row);
+        // If a stale `messages` row exists for this id (cached by a prior
+        // ofw_get_message call before the drafts table knew about this id),
+        // evict it. The drafts table is the source of truth for drafts; we
+        // don't want ofw_get_message returning a stale messages-table copy.
+        if (getMessage(item.id))
+            deleteMessage(item.id);
         if (!existing
             || existing.body !== row.body
             || existing.subject !== row.subject

package/dist/tools/_shared.js

@@ -20,3 +20,30 @@ export function expandPath(p) {
     const expanded = p.startsWith('~/') ? join(process.env.HOME ?? '', p.slice(2)) : p;
     return isAbsolute(expanded) ? expanded : resolve(expanded);
 }
+/**
+ * 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
+ * populate the cache after `ofw_send_message` or `ofw_save_draft`:
+ *
+ *  - OFW's POST response is minimal (typically just `{entityId: <id>}`
+ *    or sometimes legacy `{id: <id>}`), so we can't build a full row
+ *    from it directly.
+ *  - Worse, on draft updates OFW returns the same success shape even
+ *    when the server silently no-ops, so the GET is also how we verify
+ *    the write landed (callers compare detail.body to args.body).
+ *
+ * Returns a discriminated union so callers can narrow with
+ * `if (result.id !== null)`. When id is null (no id field in the
+ * response — never observed in production, but defensive), `raw`
+ * carries the POST response so the caller can still surface it.
+ */
+export async function postMessageAndRefetch(client, payload) {
+    const raw = await client.request('POST', '/pub/v3/messages', payload);
+    const id = typeof raw?.id === 'number' ? raw.id
+        : typeof raw?.entityId === 'number' ? raw.entityId
+            : null;
+    if (id === null)
+        return { id: null, detail: null, raw };
+    const detail = await client.request('GET', `/pub/v3/messages/${id}`);
+    return { id, detail, raw };
+}

package/dist/tools/calendar.js

@@ -36,7 +36,7 @@ export function registerCalendarTools(server, client) {
     });
     server.registerTool('ofw_update_event', {
         description: 'Update an existing OurFamilyWizard calendar event',
-        annotations: { destructiveHint: false },
+        annotations: { destructiveHint: true },
         inputSchema: {
             eventId: z.string(),
             title: z.string().optional(),

package/dist/tools/messages.js

@@ -1,10 +1,10 @@
 import { z } from 'zod';
 import { syncAll, fetchAttachmentMeta, fetchAttachmentMetaForMessage } from '../sync.js';
-import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, listAttachmentsForMessage, getAttachment, upsertAttachmentForMessage, markAttachmentDownloaded, } from '../cache.js';
+import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, listAttachmentsForMessage, getAttachment, upsertAttachmentForMessage, markAttachmentDownloaded, getDraft, } from '../cache.js';
 import { getAttachmentsDir, getDefaultInlineAttachments } from '../config.js';
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
-import { expandPath, jsonResponse, mapRecipients, textResponse } from './_shared.js';
+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.
 const MIME_BY_EXT = {
@@ -95,13 +95,39 @@ export function registerMessageTools(server, client) {
         return jsonResponse(payload);
     });
     server.registerTool('ofw_get_message', {
-        description: 'Get a single OurFamilyWizard message by ID. Reads from local cache when available; otherwise fetches from OFW (which will mark unread inbox messages as read on OFW).',
+        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) — 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: {
-            messageId: z.string().describe('Message ID'),
+            messageId: z.string().describe('Message ID (also accepts draft IDs — drafts are routed via the drafts cache)'),
         },
     }, async (args) => {
         const id = Number(args.messageId);
+        // Draft routing: if this id is in the drafts cache, return a
+        // MessageRow-shaped synthesis built from the draft. The drafts table
+        // is the source of truth for draft bodies (sync keeps it fresh);
+        // the messages-table cache for the same id is stale by construction
+        // when ofw_get_message was called on a draft id before sync caught
+        // up — see syncDrafts, which also evicts these stale rows.
+        const draftRow = getDraft(id);
+        if (draftRow !== null) {
+            return jsonResponse({
+                id: draftRow.id,
+                folder: 'drafts',
+                subject: draftRow.subject,
+                fromUser: '',
+                sentAt: draftRow.modifiedAt,
+                recipients: draftRow.recipients,
+                body: draftRow.body,
+                // Best approximation: drafts don't separately track when the body
+                // was last *fetched* — we last wrote it on the last sync, which
+                // also updates modifiedAt.
+                fetchedBodyAt: draftRow.modifiedAt,
+                replyToId: draftRow.replyToId,
+                chainRootId: null,
+                listData: draftRow.listData,
+                attachments: [],
+            });
+        }
         const cached = getMessage(id);
         if (cached && cached.body !== null) {
             let attachments = listAttachmentsForMessage(id);
@@ -173,10 +199,7 @@ export function registerMessageTools(server, client) {
             chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
         }
         const myFileIDs = args.myFileIDs ?? [];
-        // OFW's POST /pub/v3/messages response is minimal — typically just
-        // `{entityId: <id>}` — so the cache write needs to fetch detail
-        // afterwards (same shape as ofw_save_draft).
-        const data = await client.request('POST', '/pub/v3/messages', {
+        const { id: newId, detail, raw } = await postMessageAndRefetch(client, {
             subject: args.subject,
             body: args.body,
             recipientIds: args.recipientIds,
@@ -185,12 +208,8 @@ export function registerMessageTools(server, client) {
             includeOriginal: resolvedReplyTo !== null,
             replyToId: resolvedReplyTo,
         });
-        const newId = typeof data?.id === 'number' ? data.id
-            : typeof data?.entityId === 'number' ? data.entityId
-                : null;
         let persisted = null;
         if (newId !== null) {
-            const detail = await client.request('GET', `/pub/v3/messages/${newId}`);
             persisted = {
                 id: newId,
                 folder: 'sent',
@@ -225,7 +244,7 @@ export function registerMessageTools(server, client) {
             await deleteOFWMessages(client, [args.draftId]);
             deleteDraft(args.draftId);
         }
-        const responseObj = persisted ?? data;
+        const responseObj = persisted ?? raw;
         const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
         return textResponse(rewriteNote ? `${rewriteNote}\n\n${text}` : text);
     });
@@ -246,13 +265,13 @@ export function registerMessageTools(server, client) {
         return jsonResponse(payload);
     });
     server.registerTool('ofw_save_draft', {
-        description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. To update an existing draft, provide its messageId. 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 and verify what was actually persisted; if OFW silently no-ops an update (a known issue with repeated updates to the same draft), the response includes a WARNING note with a workaround.',
+        description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft — 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: {
             subject: z.string().describe('Message subject'),
             body: z.string().describe('Message body text'),
             recipientIds: z.array(z.number()).describe('Array of recipient user IDs (optional for drafts)').optional(),
-            messageId: z.number().describe('ID of an existing draft to update (omit to create a new draft)').optional(),
+            messageId: z.number().describe('ID of an existing draft to replace (the new draft will have a new id; the old is deleted)').optional(),
             replyToId: z.number().describe('ID of the message this draft replies to').optional(),
             myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment)').optional(),
         },
@@ -267,6 +286,12 @@ export function registerMessageTools(server, client) {
             }
         }
         const myFileIDs = args.myFileIDs ?? [];
+        // Deliberately do NOT pass `args.messageId` to OFW's POST payload.
+        // OFW's update-by-messageId path silently no-ops on subsequent
+        // updates while echoing the posted body in the immediate GET — so
+        // there is no honest way to detect a failure from the response.
+        // We always create a fresh draft; if the caller provided a
+        // messageId, we delete the old draft afterward (the "replace" path).
         const payload = {
             subject: args.subject,
             body: args.body,
@@ -276,22 +301,10 @@ export function registerMessageTools(server, client) {
             includeOriginal: resolvedReplyTo !== null,
             replyToId: resolvedReplyTo,
         };
-        if (args.messageId !== undefined)
-            payload.messageId = args.messageId;
-        // OFW's POST /pub/v3/messages response for drafts is minimal — typically
-        // just `{entityId: <id>}` — and worse, it returns the same success shape
-        // even when the server silently no-ops on a subsequent update to the
-        // same draft. Don't trust the POST response: extract the id from it,
-        // then GET the detail endpoint to repopulate the cache from
-        // authoritative server state.
-        const data = await client.request('POST', '/pub/v3/messages', payload);
-        const newId = typeof data?.id === 'number' ? data.id
-            : typeof data?.entityId === 'number' ? data.entityId
-                : null;
+        const { id: newId, detail, raw } = await postMessageAndRefetch(client, payload);
         let persisted = null;
-        let noOpWarning = null;
+        let replaceNote = null;
         if (newId !== null) {
-            const detail = await client.request('GET', `/pub/v3/messages/${newId}`);
             persisted = {
                 id: newId,
                 subject: detail.subject ?? args.subject,
@@ -302,17 +315,22 @@ export function registerMessageTools(server, client) {
                 listData: detail,
             };
             upsertDraft(persisted);
-            // If this was an update (messageId provided) and OFW's reported body
-            // doesn't match what we asked it to save, the server silently
-            // dropped the change. Warn the caller so the model can take the
-            // create-then-delete fallback.
-            if (args.messageId !== undefined && persisted.body !== args.body) {
-                noOpWarning = 'WARNING: OFW reported success but the draft body it returned does not match the requested update. The OFW POST /pub/v3/messages endpoint can silently no-op on subsequent updates to the same draft. Workaround: delete this draft (ofw_delete_draft) and create a new one (ofw_save_draft without messageId).';
+            // Replace-path: caller passed messageId, so they want the old draft
+            // gone. Delete it after the new one is safely created+cached.
+            if (args.messageId !== undefined && args.messageId !== newId) {
+                try {
+                    await deleteOFWMessages(client, [args.messageId]);
+                    deleteDraft(args.messageId);
+                    replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.)`;
+                }
+                catch (e) {
+                    replaceNote = `WARNING: New draft ${newId} created successfully, but failed to delete the old draft (${args.messageId}): ${e.message}. You may want to clean it up manually with ofw_delete_draft.`;
+                }
             }
         }
-        const responseObj = persisted ?? data;
+        const responseObj = persisted ?? raw;
         const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
-        const notes = [rewriteNote, noOpWarning].filter((n) => n !== null).join('\n\n');
+        const notes = [rewriteNote, replaceNote].filter((n) => n !== null).join('\n\n');
         return textResponse(notes ? `${notes}\n\n${text}` : text);
     });
     server.registerTool('ofw_delete_draft', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "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,26 +6,26 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.0.16",
+  "version": "2.0.18",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.0.16",
+      "version": "2.0.18",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
           "name": "OFW_USERNAME",
-          "description": "Your OurFamilyWizard login email address",
-          "isRequired": true,
+          "description": "Your OurFamilyWizard login email address. Optional — if omitted, the server falls back to the fetchproxy browser extension (requires being signed in to ourfamilywizard.com).",
+          "isRequired": false,
           "format": "string"
         },
         {
           "name": "OFW_PASSWORD",
-          "description": "Your OurFamilyWizard password",
-          "isRequired": true,
+          "description": "Your OurFamilyWizard password. Optional — see OFW_USERNAME.",
+          "isRequired": false,
           "format": "string",
           "isSecret": true
         }

package/skills/ofw/SKILL.md

@@ -89,13 +89,17 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 ### Messages
 | Tool | Notes |
 |------|-------|
-| `ofw_list_message_folders` | Get folder IDs (inbox, sent, etc.) — call this first |
-| `ofw_list_messages(folderId)` | List messages in a folder |
-| `ofw_get_message(messageId)` | Read a message. ⚠️ Marks unread messages as read. |
-| `ofw_send_message(subject, body, recipientIds[], replyToId?, draftId?)` | Send a message. Pass `replyToId` to thread the original message history (like email reply). Pass `draftId` to auto-delete the draft after sending. |
-| `ofw_list_drafts` | List saved drafts |
-| `ofw_save_draft(subject, body, recipientIds?, messageId?, replyToId?)` | Create or update a draft |
-| `ofw_delete_draft(messageId)` | Delete a draft |
+| `ofw_sync_messages(folders?, deep?, fetchUnreadBodies?)` | Sync OFW → local cache. **Call first if the cache might be stale.** Returns unread inbox hints (bodies not fetched, to avoid mark-as-read). |
+| `ofw_list_message_folders` | List OFW folders with unread counts. Most reads use the cache; this is mainly for folder IDs and live unread counts. |
+| `ofw_list_messages(folderId?, since?, until?, q?, page?, size?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. |
+| `ofw_get_message(messageId)` | Read a message OR draft body. Cache-first. Ids in the drafts cache return `folder: "drafts"`. ⚠️ Falls through to OFW for unread inbox messages, which marks them as read. |
+| `ofw_send_message(subject, body, recipientIds[], replyToId?, draftId?, myFileIDs?)` | Send a message. Pass `replyToId` to thread original history. Pass `draftId` to auto-delete the draft after sending. Pass `myFileIDs` (from `ofw_upload_attachment`) to attach files. |
+| `ofw_get_unread_sent` | Sent messages your co-parent hasn't read yet (from cache). |
+| `ofw_list_drafts` | List saved drafts (cache-backed). |
+| `ofw_save_draft(subject, body, recipientIds?, messageId?, replyToId?, myFileIDs?)` | Create a new draft. Pass `messageId` to **replace** an existing draft: the tool creates a fresh draft and deletes the old one (OFW's update-in-place endpoint silently no-ops). The returned `id` is the NEW id; the response includes a `NOTE` documenting the swap. |
+| `ofw_delete_draft(messageId)` | Delete a draft. |
+| `ofw_upload_attachment(path, shareClass?, label?, description?)` | Upload a local file to My Files; returns a fileId to pass into `myFileIDs`. |
+| `ofw_download_attachment(fileId, inline?, saveTo?, force?)` | Download an attachment. `inline:true` returns bytes as MCP content; default writes to `~/Downloads/ofw-mcp/`. |
 
 ### Calendar
 | Tool | Notes |