ofw-mcp 2.18.0 → 2.19.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/auth-password.js

@@ -9,6 +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.
+import { currentCallSignal } from '@chrischall/mcp-utils';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, assertOfwUrl } from './protocol.js';
 export async function loginWithPassword(username, password) {
     // Step 1: get a SESSION cookie (Spring Security refuses the POST without it).
@@ -17,6 +18,10 @@ export async function loginWithPassword(username, password) {
     const initResponse = await fetch(initUrl, {
         headers: { ...OFW_PROTOCOL_HEADERS },
         redirect: 'manual',
+        // Honour a caller who has given up (mcp-utils `cancel`). A sign-in
+        // nobody is waiting for should not keep hitting OFW, which counts
+        // failed attempts against the account.
+        signal: currentCallSignal(),
     });
     // headers.get('set-cookie') folds multiple Set-Cookie headers into one
     // comma-joined string; getSetCookie() preserves them individually. Echo
@@ -30,6 +35,7 @@ export async function loginWithPassword(username, password) {
     assertOfwUrl(loginUrl);
     const response = await fetch(loginUrl, {
         method: 'POST',
+        signal: currentCallSignal(),
         headers: {
             ...OFW_PROTOCOL_HEADERS,
             Accept: 'application/json',

package/dist/bundle.js

@@ -3710,6 +3710,24 @@ var require_websocket_server = __commonJS({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/cancel/index.js
+import { AsyncLocalStorage } from "node:async_hooks";
+var storage = new AsyncLocalStorage();
+function withCallSignal(signal, fn) {
+  return signal ? storage.run({ signal }, fn) : fn();
+}
+function currentCallSignal() {
+  return storage.getStore()?.signal;
+}
+function withAmbientCancellation(own2) {
+  const ambient = currentCallSignal();
+  if (!ambient)
+    return own2;
+  if (!own2)
+    return ambient;
+  return AbortSignal.any([own2, ambient]);
+}
+
 // node_modules/@modelcontextprotocol/server/dist/chunk-Br0eD_fh.mjs
 var __create2 = Object.create;
 var __defProp2 = Object.defineProperty;
@@ -38155,17 +38173,41 @@ Hint: ${err.hint}`);
   }
   throw err;
 }
+function callSignalFrom(args) {
+  const ctx = args.at(-1);
+  if (typeof ctx !== "object" || ctx === null)
+    return void 0;
+  const req = ctx.mcpReq;
+  if (typeof req !== "object" || req === null)
+    return void 0;
+  const signal = req.signal;
+  return signal instanceof AbortSignal ? signal : void 0;
+}
 function surfaceToolHints(server) {
   const register2 = server.registerTool.bind(server);
-  server.registerTool = (name, config2, cb) => register2(name, config2, (...args) => {
-    let result;
-    try {
-      result = cb(...args);
-    } catch (err) {
-      return hintResultOrRethrow(err);
-    }
-    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
-  });
+  server.registerTool = (name, config2, cb) => register2(name, config2, (...args) => (
+    // THE CALLER'S CANCELLATION, made ambient for the whole handler
+    // (`cancel/index.ts`). The SDK delivers it and the fleet ignored it:
+    // measured against @modelcontextprotocol/server 2.0.0, a cancelled
+    // call aborts `ctx.mcpReq.signal` with the caller's reason and the
+    // handler runs to completion regardless — so the HTTP request stays
+    // in flight, the child keeps burning metered CPU, and the upstream
+    // keeps being hit for somebody who has gone. claude.ai sent 101
+    // cancellations in the week to 2026-09-20.
+    //
+    // Here because this is the one wrapper every tool already passes
+    // through: threading the signal by hand would mean editing several
+    // hundred handlers and missing exactly the ones nobody edits.
+    withCallSignal(callSignalFrom(args), () => {
+      let result;
+      try {
+        result = cb(...args);
+      } catch (err) {
+        return hintResultOrRethrow(err);
+      }
+      return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+    })
+  ));
 }
 async function createMcpServer(opts) {
   const server = new McpServer({ name: opts.name, version: opts.version }, { supportedProtocolVersions: [...SERVER_PROTOCOL_VERSIONS] });
@@ -43922,13 +43964,18 @@ async function loginWithPassword(username, password) {
   assertOfwUrl(initUrl);
   const initResponse = await fetch(initUrl, {
     headers: { ...OFW_PROTOCOL_HEADERS },
-    redirect: "manual"
+    redirect: "manual",
+    // Honour a caller who has given up (mcp-utils `cancel`). A sign-in
+    // nobody is waiting for should not keep hitting OFW, which counts
+    // failed attempts against the account.
+    signal: currentCallSignal()
   });
   const sessionCookie = initResponse.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
   const loginUrl = `${BASE_URL}/ofw/login`;
   assertOfwUrl(loginUrl);
   const response = await fetch(loginUrl, {
     method: "POST",
+    signal: currentCallSignal(),
     headers: {
       ...OFW_PROTOCOL_HEADERS,
       Accept: "application/json",
@@ -43965,7 +44012,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.18.0",
+  version: "2.19.1",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -43999,10 +44046,10 @@ var package_default = {
     typecheck: "tsc -p tsconfig.json --noEmit"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^1.0.0",
+    "@chrischall/mcp-utils": "^2.0.0",
     "@fetchproxy/bootstrap": "^3.0.1",
     "@modelcontextprotocol/server": "^2.0.0",
-    dotenv: "^17.4.2",
+    dotenv: "^18.0.0",
     zod: "^4.6.2"
   },
   devDependencies: {
@@ -44278,7 +44325,15 @@ var OFWClient = class {
       response = await fetch(url2, {
         method,
         headers,
-        signal: ac.signal,
+        // THE CALLER'S CANCELLATION, folded in with our timeout (mcp-utils
+        // `cancel`). Until this the only thing that could stop an OFW
+        // request was the timeout below, so a cancelled tool call held it
+        // open for the full budget while the child burned the CPU
+        // mcp-host meters it on. The timeout diagnosis below is unaffected
+        // because it asks `ac.signal`, OUR controller — a caller's abort
+        // falls through to the generic path rather than being reported as
+        // OFW being slow.
+        signal: withAmbientCancellation(ac.signal),
         ...body !== void 0 ? { body: isFormData ? body : JSON.stringify(body) } : {}
       });
     } catch (err) {
@@ -44603,7 +44658,7 @@ function registerUserTools(server, client2) {
   });
   server.registerTool("ofw_get_notifications", {
     description: "Get OurFamilyWizard dashboard summary: unread message count, upcoming events, outstanding expenses. Note: updates your last-seen status.",
-    annotations: { readOnlyHint: false }
+    annotations: { readOnlyHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v1/users/useraccountstatus");
     return jsonResponse(data);
@@ -46888,7 +46943,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   });
   server.registerTool("ofw_list_messages", {
     description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based (1-based `page`) but if you know what you want (a date range, a topic), prefer the filters over walking pages \u2014 the cache may have 1000+ messages. Results are newest-first by default; `sort:"oldest"` starts at the old end of a range instead of paging to it. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" \u2014 check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: true },
     inputSchema: external_exports.object({
       folderId: external_exports.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
       page: external_exports.number().int().min(1).describe("Page number (default 1)").optional(),
@@ -46983,7 +47038,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   });
   server.registerTool("ofw_get_message", {
     description: 'Get a single OurFamilyWizard message OR draft by ID. Reads from local cache when available; otherwise fetches from OFW \u2014 and for an UNREAD INBOX message that fetch marks it read and stamps a "First Viewed" time the co-parent can see, which is part of the record and cannot be undone. Pass allowMarkRead:false to refuse such a fetch instead (cached bodies, sent messages and already-read messages are unaffected, because none of them stamp anything). 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 },
+    annotations: { readOnlyHint: false, destructiveHint: true },
     inputSchema: external_exports.object({
       messageId: external_exports.string().describe("Message ID (also accepts draft IDs \u2014 drafts are routed via the drafts cache)"),
       allowMarkRead: external_exports.boolean().describe("Default true (the long-standing behaviour). Set false to refuse a fetch that would mark an unread INBOX message as READ on OurFamilyWizard \u2014 an irreversible, co-parent-visible change to the record. Reads that cannot stamp anything (a cached body, a sent message, an already-read message) still succeed. The server-wide OFW_ALLOW_MARK_READ=false is a ceiling this argument cannot raise.").optional(),
@@ -47378,7 +47433,7 @@ ${JSON.stringify(
   }
   server.registerTool("ofw_list_drafts", {
     description: 'List draft messages, verified against OurFamilyWizard in ONE call: when the local drafts cache is not verified-fresh, a cheap drafts sync runs first by default (verify:true), so the answer is server-confirmed without a second call. Pass verify:false to answer purely from the cache (no OFW requests). Returns an explicit `complete` boolean describing the RESULT SET: true means "these are ALL the drafts on OurFamilyWizard as of freshness.asOf" \u2014 check it before saying "you have N drafts". Each draft carries its `draftKey` (stable across the create-then-delete churn of editing) when one is known. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY"); pass autoRefresh:true to sync and answer instead.',
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: false },
     inputSchema: external_exports.object({
       page: external_exports.number().int().min(1).describe("Page number (default 1)").optional(),
       size: external_exports.number().int().min(1).describe("Drafts per page (default 50)").optional(),
@@ -47476,7 +47531,7 @@ ${JSON.stringify(
   });
   if (allowDrafts) server.registerTool("ofw_save_draft", {
     description: "Save a message as a draft in OurFamilyWizard. RECIPIENTS: OurFamilyWizard does NOT persist recipients on drafts \u2014 recipientIds are accepted but the saved draft comes back with none (documented OFW behavior, noted once in the response, not warned about; supply recipientIds at send time instead). IDENTITY: the response leads with `draftKey`, the stable identity that survives editing \u2014 key off it, because the `id` changes on EVERY edit (replacing a draft creates a NEW draft and deletes the old one; OFW's update-in-place endpoint silently no-ops, so we never use it). Pass messageId to replace an existing draft; the response.id will be the NEW id, and a transparency NOTE documents the swap and which fields were carried over. THREADING: if replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included). The threading verdict is read from OFW's full echo (replyToId/inReplyTo/showContext) \u2014 a warning appears ONLY when the reply linkage was genuinely dropped or re-targeted, and the response's top-level replyToId/inReplyTo always agree with its listData. Attach files via myFileIDs (from ofw_upload_attachment). After saving, the tool re-fetches the draft from OFW, and the returned `revision` reflects that authoritative state (so it will match on your next edit). SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if its subject/body/recipients changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). A pure replyToId normalization by OFW is NOT treated as a conflict. The refusal returns the current server body under serverBody \u2014 merge your edit into it and retry with expectedRevision.",
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: false },
     inputSchema: external_exports.object({
       subject: external_exports.string().describe("Message subject"),
       body: external_exports.string().describe("Message body text"),
@@ -47657,7 +47712,7 @@ ${text}` : text);
   });
   server.registerTool("ofw_get_unread_sent", {
     description: 'List sent messages that have not been read by one or more recipients. Reads from local cache. Returns `complete` describing whether every sent message was scanned. An empty SENT cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as "nothing sent"; pass autoRefresh:true to sync and answer instead.',
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: true },
     inputSchema: external_exports.object({
       page: external_exports.number().int().min(1).describe("Page (default 1)").optional(),
       size: external_exports.number().int().min(1).describe("Per page (default 50)").optional(),
@@ -47774,7 +47829,7 @@ ${text}` : text);
   });
   server.registerTool("ofw_download_attachment", {
     description: "Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT \u2014 per-sheet CSV, per-page/slide text, document text \u2014 in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing \u2014 a saveTo path never costs you the content. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo. Re-downloading to the same path is a no-op (disk mode only).",
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: true },
     inputSchema: external_exports.object({
       fileId: external_exports.number().describe("Attachment file id (from ofw_get_message \u2192 attachments[].fileId)"),
       inline: external_exports.boolean().describe("If true, return content inline as MCP content blocks and skip the disk write. If false, write to disk and return the path \u2014 except on a hosted deployment with no filesystem, where inline is forced (forcedInline:true) so the content is still returned. If omitted, falls back to the OFW_INLINE_ATTACHMENTS env var (default: false = disk).").optional(),
@@ -47861,7 +47916,7 @@ ${text}` : text);
   });
   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. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note \u2014 call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true).",
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: false },
     inputSchema: external_exports.object({
       folders: external_exports.array(external_exports.enum(["inbox", "sent", "drafts"])).min(1).describe("Folders to sync (default: all three). Must be non-empty if given \u2014 an empty list would sync nothing while reporting success.").optional(),
       fetchUnreadBodies: external_exports.boolean().describe('If true, also fetch bodies for unread inbox messages \u2014 which marks each one READ on OurFamilyWizard and stamps a co-parent-visible "First Viewed" time that cannot be undone. Defaults to the OFW_FETCH_UNREAD_BODIES env var (false unless set), and is forced off entirely when OFW_ALLOW_MARK_READ=false.').optional(),
@@ -47887,7 +47942,7 @@ ${text}` : text);
   });
   server.registerTool("ofw_check_freshness", {
     description: 'Cheaply confirm whether the local cache still matches OurFamilyWizard, WITHOUT running a full sync. Use this before asserting anything about current state \u2014 especially "draft X is still sitting unsent". Costs one OFW request for the folder check plus one per messageId. For each folder it returns the live server count next to the cached count. For each id it returns a LIVE lifecycle `state` \u2014 "draft" | "sent" | "received" | "deleted" | "unknown" \u2014 alongside `folder`, `sentAt`, `existsOnServer` and a content comparison. `state` is the field that answers "is this still a draft?": a draft that has been SENT still exists on the server, so existsOnServer:true never distinguished the two. A cached draft whose state is no longer "draft" reports inSync:false even when its text is byte-identical. Content is compared by revision hash, because OFW draft timestamps do NOT change when a draft is edited in the web app. Does not fetch bodies into the cache, does not touch attachments, and does not depend on sync state. For draftKeys, or a full live draft inventory, use ofw_status.',
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: true },
     inputSchema: external_exports.object({
       folders: external_exports.array(external_exports.enum(["inbox", "sent", "drafts"])).min(1).describe("Folders to compare cached vs live counts for. Defaults to all three when messageIds is not given. Must be non-empty if given.").optional(),
       messageIds: external_exports.array(external_exports.number()).describe(`Specific ids to verify against OFW (max ${MAX_FRESHNESS_IDS}). Ids cached as drafts, as sent messages, or as already-read inbox messages are probed freely \u2014 none of those can stamp the record. Anything else is skipped \u2014 see allowMarkRead.`).optional(),
@@ -47946,7 +48001,7 @@ ${text}` : text);
   });
   server.registerTool("ofw_status", {
     description: 'ONE live call that answers "where does everything stand?". This is the call that should back any status summary about drafts or specific messages \u2014 never session memory, and never a cached read alone. With no arguments it returns the FULL current draft inventory, verified against OurFamilyWizard. Pass ids and/or draftKeys to get each one\'s live lifecycle `state` ("draft" | "sent" | "received" | "deleted" | "unknown") with `sentAt` and `viewedAt`. A draftKey is the stable identity ofw_save_draft returns: editing a draft mints a new OFW id every time (create-then-delete), so the key is the only way to ask "what happened to the thing I was working on?" \u2014 it resolves to the chain\'s current id and keeps resolving after the draft is SENT (state:"sent" with sentMessageId). The top-level `complete` is true ONLY when every part of this snapshot was verified live; if it is false, do not state a draft count or a lifecycle claim from this payload.',
-    annotations: { readOnlyHint: false },
+    annotations: { readOnlyHint: true },
     inputSchema: external_exports.object({
       ids: external_exports.array(external_exports.number()).describe(`Message/draft ids to resolve to a live state (combined with draftKeys, max ${MAX_FRESHNESS_IDS} probes per call).`).optional(),
       draftKeys: external_exports.array(external_exports.string()).describe("Stable draft keys (from ofw_save_draft / ofw_list_drafts) to resolve to their CURRENT id and state.").optional(),
@@ -48952,7 +49007,7 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.18.0",
+  version: "2.19.1",
   // x-release-please-version
   deps: client,
   tools: [

package/dist/client.js

@@ -1,4 +1,4 @@
-import { loadDotenvSafely, parseBoolEnv, redactSecrets } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, parseBoolEnv, redactSecrets, withAmbientCancellation } from '@chrischall/mcp-utils';
 import { TokenManager } from '@chrischall/mcp-utils/session';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
@@ -190,7 +190,15 @@ export class OFWClient {
             response = await fetch(url, {
                 method,
                 headers,
-                signal: ac.signal,
+                // THE CALLER'S CANCELLATION, folded in with our timeout (mcp-utils
+                // `cancel`). Until this the only thing that could stop an OFW
+                // request was the timeout below, so a cancelled tool call held it
+                // open for the full budget while the child burned the CPU
+                // mcp-host meters it on. The timeout diagnosis below is unaffected
+                // because it asks `ac.signal`, OUR controller — a caller's abort
+                // falls through to the generic path rather than being reported as
+                // OFW being slow.
+                signal: withAmbientCancellation(ac.signal),
                 ...(body !== undefined ? { body: isFormData ? body : JSON.stringify(body) } : {}),
             });
         }

package/dist/index.js

@@ -36,7 +36,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.18.0', // x-release-please-version
+    version: '2.19.1', // x-release-please-version
     deps: client,
     tools: [
         registerHealthcheckTools,

package/dist/tools/messages.js

@@ -258,7 +258,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     server.registerTool('ofw_list_messages', {
         description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based (1-based `page`) but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Results are newest-first by default; `sort:"oldest"` starts at the old end of a range instead of paging to it. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
         inputSchema: z.object({
             folderId: z.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
             page: z.number().int().min(1).describe('Page number (default 1)').optional(),
@@ -387,7 +387,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     server.registerTool('ofw_get_message', {
         description: 'Get a single OurFamilyWizard message OR draft by ID. Reads from local cache when available; otherwise fetches from OFW — and for an UNREAD INBOX message that fetch marks it read and stamps a "First Viewed" time the co-parent can see, which is part of the record and cannot be undone. Pass allowMarkRead:false to refuse such a fetch instead (cached bodies, sent messages and already-read messages are unaffected, because none of them stamp anything). 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 },
+        annotations: { readOnlyHint: false, destructiveHint: true },
         inputSchema: z.object({
             messageId: z.string().describe('Message ID (also accepts draft IDs — drafts are routed via the drafts cache)'),
             allowMarkRead: z.boolean().describe('Default true (the long-standing behaviour). Set false to refuse a fetch that would mark an unread INBOX message as READ on OurFamilyWizard — an irreversible, co-parent-visible change to the record. Reads that cannot stamp anything (a cached body, a sent message, an already-read message) still succeed. The server-wide OFW_ALLOW_MARK_READ=false is a ceiling this argument cannot raise.').optional(),
@@ -890,7 +890,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     }
     server.registerTool('ofw_list_drafts', {
         description: 'List draft messages, verified against OurFamilyWizard in ONE call: when the local drafts cache is not verified-fresh, a cheap drafts sync runs first by default (verify:true), so the answer is server-confirmed without a second call. Pass verify:false to answer purely from the cache (no OFW requests). Returns an explicit `complete` boolean describing the RESULT SET: true means "these are ALL the drafts on OurFamilyWizard as of freshness.asOf" — check it before saying "you have N drafts". Each draft carries its `draftKey` (stable across the create-then-delete churn of editing) when one is known. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY"); pass autoRefresh:true to sync and answer instead.',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: false },
         inputSchema: z.object({
             page: z.number().int().min(1).describe('Page number (default 1)').optional(),
             size: z.number().int().min(1).describe('Drafts per page (default 50)').optional(),
@@ -1008,7 +1008,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     if (allowDrafts)
         server.registerTool('ofw_save_draft', {
             description: 'Save a message as a draft in OurFamilyWizard. RECIPIENTS: OurFamilyWizard does NOT persist recipients on drafts — recipientIds are accepted but the saved draft comes back with none (documented OFW behavior, noted once in the response, not warned about; supply recipientIds at send time instead). IDENTITY: the response leads with `draftKey`, the stable identity that survives editing — key off it, because the `id` changes on EVERY edit (replacing a draft creates a NEW draft and deletes the old one; OFW\'s update-in-place endpoint silently no-ops, so we never use it). Pass messageId to replace an existing draft; the response.id will be the NEW id, and a transparency NOTE documents the swap and which fields were carried over. THREADING: if replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included). The threading verdict is read from OFW\'s full echo (replyToId/inReplyTo/showContext) — a warning appears ONLY when the reply linkage was genuinely dropped or re-targeted, and the response\'s top-level replyToId/inReplyTo always agree with its listData. Attach files via myFileIDs (from ofw_upload_attachment). After saving, the tool re-fetches the draft from OFW, and the returned `revision` reflects that authoritative state (so it will match on your next edit). SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if its subject/body/recipients changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). A pure replyToId normalization by OFW is NOT treated as a conflict. The refusal returns the current server body under serverBody — merge your edit into it and retry with expectedRevision.',
-            annotations: { readOnlyHint: false },
+            annotations: { readOnlyHint: false, destructiveHint: false },
             inputSchema: z.object({
                 subject: z.string().describe('Message subject'),
                 body: z.string().describe('Message body text'),
@@ -1243,7 +1243,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         });
     server.registerTool('ofw_get_unread_sent', {
         description: 'List sent messages that have not been read by one or more recipients. Reads from local cache. Returns `complete` describing whether every sent message was scanned. An empty SENT cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as "nothing sent"; pass autoRefresh:true to sync and answer instead.',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
         inputSchema: z.object({
             page: z.number().int().min(1).describe('Page (default 1)').optional(),
             size: z.number().int().min(1).describe('Per page (default 50)').optional(),
@@ -1370,7 +1370,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         });
     server.registerTool('ofw_download_attachment', {
         description: 'Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT — per-sheet CSV, per-page/slide text, document text — in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing — a saveTo path never costs you the content. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo. Re-downloading to the same path is a no-op (disk mode only).',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
         inputSchema: z.object({
             fileId: z.number().describe('Attachment file id (from ofw_get_message → attachments[].fileId)'),
             inline: z.boolean().describe('If true, return content inline as MCP content blocks and skip the disk write. If false, write to disk and return the path — except on a hosted deployment with no filesystem, where inline is forced (forcedInline:true) so the content is still returned. If omitted, falls back to the OFW_INLINE_ATTACHMENTS env var (default: false = disk).').optional(),
@@ -1477,7 +1477,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     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. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note — call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true).',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: false },
         inputSchema: z.object({
             folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).min(1).describe('Folders to sync (default: all three). Must be non-empty if given — an empty list would sync nothing while reporting success.').optional(),
             fetchUnreadBodies: z.boolean().describe('If true, also fetch bodies for unread inbox messages — which marks each one READ on OurFamilyWizard and stamps a co-parent-visible "First Viewed" time that cannot be undone. Defaults to the OFW_FETCH_UNREAD_BODIES env var (false unless set), and is forced off entirely when OFW_ALLOW_MARK_READ=false.').optional(),
@@ -1505,7 +1505,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     server.registerTool('ofw_check_freshness', {
         description: 'Cheaply confirm whether the local cache still matches OurFamilyWizard, WITHOUT running a full sync. Use this before asserting anything about current state — especially "draft X is still sitting unsent". Costs one OFW request for the folder check plus one per messageId. For each folder it returns the live server count next to the cached count. For each id it returns a LIVE lifecycle `state` — "draft" | "sent" | "received" | "deleted" | "unknown" — alongside `folder`, `sentAt`, `existsOnServer` and a content comparison. `state` is the field that answers "is this still a draft?": a draft that has been SENT still exists on the server, so existsOnServer:true never distinguished the two. A cached draft whose state is no longer "draft" reports inSync:false even when its text is byte-identical. Content is compared by revision hash, because OFW draft timestamps do NOT change when a draft is edited in the web app. Does not fetch bodies into the cache, does not touch attachments, and does not depend on sync state. For draftKeys, or a full live draft inventory, use ofw_status.',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
         inputSchema: z.object({
             folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).min(1).describe('Folders to compare cached vs live counts for. Defaults to all three when messageIds is not given. Must be non-empty if given.').optional(),
             messageIds: z.array(z.number()).describe(`Specific ids to verify against OFW (max ${MAX_FRESHNESS_IDS}). Ids cached as drafts, as sent messages, or as already-read inbox messages are probed freely — none of those can stamp the record. Anything else is skipped — see allowMarkRead.`).optional(),
@@ -1592,7 +1592,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     server.registerTool('ofw_status', {
         description: 'ONE live call that answers "where does everything stand?". This is the call that should back any status summary about drafts or specific messages — never session memory, and never a cached read alone. With no arguments it returns the FULL current draft inventory, verified against OurFamilyWizard. Pass ids and/or draftKeys to get each one\'s live lifecycle `state` ("draft" | "sent" | "received" | "deleted" | "unknown") with `sentAt` and `viewedAt`. A draftKey is the stable identity ofw_save_draft returns: editing a draft mints a new OFW id every time (create-then-delete), so the key is the only way to ask "what happened to the thing I was working on?" — it resolves to the chain\'s current id and keeps resolving after the draft is SENT (state:"sent" with sentMessageId). The top-level `complete` is true ONLY when every part of this snapshot was verified live; if it is false, do not state a draft count or a lifecycle claim from this payload.',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
         inputSchema: z.object({
             ids: z.array(z.number()).describe(`Message/draft ids to resolve to a live state (combined with draftKeys, max ${MAX_FRESHNESS_IDS} probes per call).`).optional(),
             draftKeys: z.array(z.string()).describe('Stable draft keys (from ofw_save_draft / ofw_list_drafts) to resolve to their CURRENT id and state.').optional(),

package/dist/tools/user.js

@@ -9,7 +9,7 @@ export function registerUserTools(server, client) {
     });
     server.registerTool('ofw_get_notifications', {
         description: 'Get OurFamilyWizard dashboard summary: unread message count, upcoming events, outstanding expenses. Note: updates your last-seen status.',
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/pub/v1/users/useraccountstatus');
         return jsonResponse(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.18.0",
+  "version": "2.19.1",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -34,10 +34,10 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^1.0.0",
+    "@chrischall/mcp-utils": "^2.0.0",
     "@fetchproxy/bootstrap": "^3.0.1",
     "@modelcontextprotocol/server": "^2.0.0",
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.0",
     "zod": "^4.6.2"
   },
   "devDependencies": {

package/server.json

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