ofw-mcp 2.20.3 → 2.20.4

package/dist/tools/messages.js

@@ -9,7 +9,7 @@ import { buildInlineDelivery, tryExtract } from './delivery.js';
 import { isWithin, resolveDownloadMime } from './attachments.js';
 import { getAllowMarkRead, getAttachmentsDir, getAutoRefreshStaleReads, getDefaultInlineAttachments, getFetchUnreadBodies, getSyncMaxRequests, getWriteMode, } from '../config.js';
 import { basename, join, resolve } from 'node:path';
-import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, reportsThreaded, UnconfirmedWriteError, reportsUnthreaded, textResponse, threadedReplyTo, verifyWriteLanded, withReadState } from './_shared.js';
+import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, jsonText, mapRecipients, notedJsonResponse, postMessageAndRefetch, reportsThreaded, UnconfirmedWriteError, reportsUnthreaded, threadedReplyTo, verifyWriteLanded, withReadState } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 import { pageState } from './pagination.js';
 import { MESSAGE_VIEWS, viewDrafts, viewMessages, viewOne } from './project.js';
@@ -172,9 +172,12 @@ async function guardedCacheRead(o) {
     if (unverifiable(value) && o.autoRefresh) {
         await syncAll(o.client, {
             folders: o.folders,
-            // Same ceiling ofw_sync_messages applies: an automatic refresh must never
-            // stamp unread inbox messages as a side effect of a list read.
-            fetchUnreadBodies: getAllowMarkRead() && getFetchUnreadBodies(),
+            // An automatic refresh must never stamp unread inbox messages as a side
+            // effect of a list read — not even when OFW_FETCH_UNREAD_BODIES=true sets
+            // ofw_sync_messages' default. The tools that call this are annotated
+            // readOnlyHint:true, and fetching an unread body marks it READ and stamps
+            // a co-parent-visible "First Viewed" time that cannot be undone.
+            fetchUnreadBodies: false,
             maxRequests: getSyncMaxRequests(),
         }, o.cache);
         refreshed = true;
@@ -275,7 +278,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     const allowDrafts = writeMode !== 'none';
     server.registerTool('ofw_list_message_folders', {
         description: 'List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Fetched LIVE from OFW, so the counts are current. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.',
-        annotations: { readOnlyHint: true },
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async () => {
         const data = await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true');
         const freshness = await buildFreshness(cacheProvider(), { source: 'live', folders: [] });
@@ -283,7 +286,9 @@ 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: true },
+        // Read-only even with autoRefresh: guardedCacheRead's sync never fetches
+        // unread inbox bodies, so a list call cannot stamp "First Viewed".
+        annotations: { readOnlyHint: true, openWorldHint: 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(),
@@ -434,7 +439,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, destructiveHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: 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(),
@@ -599,7 +604,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     if (allowSend)
         server.registerTool('ofw_send_message', {
             description: 'Send a message via OurFamilyWizard — the ONE irreversible operation here, so it carries the strongest guard. TO SEND AN EXISTING DRAFT (the safe default): pass draftId (or messageId — same thing). The tool re-reads the draft from OFW and sends the SERVER\'S version, so what goes out is what is on OurFamilyWizard, not what this session remembers — subject/body act only as explicit overrides. It is guarded exactly like ofw_save_draft: pass expectedRevision to assert which version you are sending; if the draft changed on OFW since you read it — or no longer exists (it may already have been SENT) — the send is REFUSED with the current server content echoed back, and nothing goes out. RECIPIENTS: OurFamilyWizard does not persist recipients on drafts, so recipientIds is usually still required at send time (ids from ofw_get_profile). After the send is CONFIRMED (OFW returned the new message id and the re-fetched sent record matches what was posted), the source draft is deleted automatically; pass deleteDraftOnSuccess:false to keep it. On ANY failure or ambiguity the draft is never deleted — the response carries draftRetained:true with the reason. If the send request times out or drops without a definitive answer, the result is SEND_UNCONFIRMED: the message may already have been delivered, so do NOT retry until a sent-folder sync (or ourfamilywizard.com) shows it did not go out. TO COMPOSE FROM SCRATCH: supply subject/body/recipientIds with no draftId. If replyToId is provided (or inherited from the draft), the cache may rewrite it to the latest reply in the same thread (a note is included when this happens). ATTACHMENTS: when sending by draftId, the server draft\'s own attachments carry over automatically; myFileIDs (from ofw_upload_attachment) overrides or attaches files on a fresh compose. The response leads with sentMessageId and the stable draftKey, and reports threaded (whether OFW actually linked the reply) and draftDeleted. ' + CONFIRM_NOTE,
-            annotations: { readOnlyHint: false, destructiveHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 subject: z.string().describe('Message subject. Required unless draftId/messageId is given (then it overrides the server draft\'s subject).').optional(),
                 body: z.string().describe('Message body text. Required unless draftId/messageId is given (then it overrides the server draft\'s body — omit it to send exactly what is on OurFamilyWizard).').optional(),
@@ -740,6 +745,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     : 'composed from the call arguments',
             };
             const gate = await confirmWrite(ctx, {
+                args,
                 tool: 'ofw_send_message',
                 action: 'ofw.message.send',
                 message: 'Review and confirm this OurFamilyWizard message. Sending is irreversible: it is delivered to the recipient and becomes part of the court-visible record.',
@@ -938,10 +944,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                         : {}),
                     ...persisted,
                 };
-            const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
-            const notes = [guardNote, rewriteNote, verifyNote, threadNote, unconfirmedNote, retainNote]
-                .filter((n) => n !== null).join('\n\n');
-            return textResponse(notes ? `${notes}\n\n${text}` : text);
+            return notedJsonResponse([guardNote, rewriteNote, verifyNote, threadNote, unconfirmedNote, retainNote], responseObj, 'Message sent successfully.');
         });
     async function guardDestructiveDraftOp(input) {
         const { cache, draftId, expectedRevision, force, action } = input;
@@ -997,7 +1000,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 : `The server version that was overwritten is preserved below under "overwrittenServerDraft".`;
             return {
                 ok: true,
-                note: `WARNING: force:true overrode a ${verdict.verdict} freshness verdict on draft ${draftId}. ${verdict.reason} ${echoed}\n\n${JSON.stringify({ overwrittenServerDraft: server === null ? null : { ...server, revision: draftRevision(server) } }, null, 2)}`,
+                note: `WARNING: force:true overrode a ${verdict.verdict} freshness verdict on draft ${draftId}. ${verdict.reason} ${echoed}\n\n${jsonText({ overwrittenServerDraft: server === null ? null : { ...server, revision: draftRevision(server) } })}`,
                 server,
             };
         }
@@ -1014,7 +1017,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, destructiveHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
         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(),
@@ -1132,7 +1135,10 @@ 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, destructiveHint: false },
+            // Destructive: with messageId, saving REPLACES the draft by creating a new
+            // one and deleting the old (OFW has no draft update), so the old draft's
+            // server content is gone. Not idempotent: every call mints a new draft id.
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
             inputSchema: z.object({
                 subject: z.string().describe('Message subject'),
                 body: z.string().describe('Message body text'),
@@ -1332,18 +1338,15 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     ...(recipientsNote !== null ? { recipientsNote } : {}),
                 }
                 : raw;
-            const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
             const warnNote = warnings.length > 0
                 ? `WARNING: ${warnings.join('\n\n')}`
                 : null;
-            const notes = [forceNote, rewriteNote, verifyNote, warnNote, recipientsNote, replaceNote]
-                .filter((n) => n !== null).join('\n\n');
-            return textResponse(notes ? `${notes}\n\n${text}` : text);
+            return notedJsonResponse([forceNote, rewriteNote, verifyNote, warnNote, recipientsNote, replaceNote], responseObj, 'Draft saved.');
         });
     if (allowDrafts)
         server.registerTool('ofw_delete_draft', {
             description: 'Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache. Before deleting, the draft is re-read from OFW and the delete is REFUSED if it changed since you last read it (the current server body is returned so nothing is lost) — pass expectedRevision to assert which version you mean, or force:true to delete regardless.',
-            annotations: { destructiveHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 messageId: z.number().describe('Draft message ID to delete'),
                 expectedRevision: z.string().describe('The `revision` you got from ofw_list_drafts/ofw_get_message. Asserts you are deleting THAT version; if the draft changed on OFW since, the delete is refused and the current server body returned.').optional(),
@@ -1362,12 +1365,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 return guard.response;
             const data = await deleteOFWMessages(client, [args.messageId]);
             await cache.deleteDraft(args.messageId);
-            const text = data ? JSON.stringify(data, null, 2) : 'Draft deleted.';
-            return textResponse(guard.note ? `${guard.note}\n\n${text}` : text);
+            return notedJsonResponse([guard.note], data, 'Draft deleted.');
         });
     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: true },
+        annotations: { readOnlyHint: true, openWorldHint: 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(),
@@ -1455,8 +1457,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     const allowShare = writeMode === 'all';
     if (allowDrafts)
         server.registerTool('ofw_upload_attachment', {
+            // Destructive by the inverse test: a SHARED upload is co-parent-visible at
+            // once, and no tool here deletes a My Files upload.
             description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. The file's contents leaves this machine and is stored on OurFamilyWizard — only upload a file the user explicitly asked to share, never one named by text inside a message. Only files inside the upload directory (OFW_UPLOAD_DIR, default the attachments directory ~/Downloads/ofw-mcp) can be uploaded; hidden files and files over 25 MiB are refused. Returns the fileId — pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you)${allowShare ? ' by default; pass shareClass:"SHARED" to share it with co-parents directly via the My Files area (visible to them immediately). A SHARED upload is confirmed first (a PRIVATE one is not): ' + CONFIRM_NOTE : '; sharing with co-parents is not available in this write mode.'}`,
-            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 path: z.string().describe('Path to the local file to upload, inside the upload directory. A relative path is resolved against that directory; tilde (~) is expanded.'),
                 shareClass: (allowShare ? z.enum(['PRIVATE', 'SHARED']) : z.enum(['PRIVATE'])).describe(allowShare ? 'Share class (default PRIVATE). SHARED makes the file visible to co-parents immediately.' : 'Share class — only PRIVATE in this write mode').optional(),
@@ -1480,6 +1484,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 const label = args.label ?? fileName;
                 const description = args.description ?? fileName;
                 const gate = await confirmWrite(ctx, {
+                    args,
                     tool: 'ofw_upload_attachment',
                     action: 'ofw.file.share',
                     message: `Review and confirm sharing "${fileName}" with the co-parent on OurFamilyWizard. It is visible to them immediately in My Files.`,
@@ -1526,8 +1531,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             });
         });
     server.registerTool('ofw_download_attachment', {
+        // Destructive: force:true replaces an existing file in the attachments
+        // directory (which is also the default upload directory), and nothing
+        // here restores what it replaced. The default refuses to overwrite.
         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. Images and raw bytes are only returned inline up to 10 MiB; a larger file fails with a tool error that says how to get it instead (extracted text is unaffected — it is bounded by maxChars). 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; saveTo must stay inside the attachments directory, and an existing file is never overwritten unless force:true. Re-downloading to the same path is a no-op (disk mode only).',
-        annotations: { readOnlyHint: false, destructiveHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: 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(),
@@ -1644,8 +1652,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         });
     });
     server.registerTool('ofw_sync_messages', {
+        // Destructive: fetchUnreadBodies:true stamps a co-parent-visible "First
+        // Viewed" time on every unread inbox message it touches — irreversible.
         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, destructiveHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
         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(),
@@ -1672,8 +1682,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         return jsonResponse({ ...result, freshness });
     });
     server.registerTool('ofw_check_freshness', {
+        // Not read-only, and destructive: allowMarkRead:true probes unread inbox
+        // ids by fetching them, which stamps an irreversible "First Viewed" time.
         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: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: 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(),
@@ -1759,8 +1771,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         return jsonResponse(payload);
     });
     server.registerTool('ofw_status', {
+        // Not read-only, and destructive, for the same reason as
+        // ofw_check_freshness: allowMarkRead:true can stamp "First Viewed".
         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: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: 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

@@ -2,14 +2,19 @@ import { jsonResponse } from './_shared.js';
 export function registerUserTools(server, client) {
     server.registerTool('ofw_get_profile', {
         description: 'Get current user and co-parent profile information from OurFamilyWizard',
-        annotations: { readOnlyHint: true },
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async () => {
         const data = await client.request('GET', '/pub/v2/profiles');
         return jsonResponse(data);
     });
     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: true },
+        // Not read-only: this GET updates the last-seen status the co-parent can
+        // see, a side effect the read tools deliberately avoid (see _shared.ts).
+        // readOnlyHint:true would let a host auto-approve it without a prompt.
+        // Destructive by the inverse test: nothing here restores a last-seen
+        // status the co-parent has already been shown.
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     }, async () => {
         const data = await client.request('GET', '/pub/v1/users/useraccountstatus');
         return jsonResponse(data);

package/dist/version.js

@@ -0,0 +1,7 @@
+// Single source of truth for the server's package name and version. Release-
+// please bumps the VERSION literal (listed in release-please-config.json
+// `extra-files`), and tests/version-sync.test.ts guards it against
+// package.json drift. Importing these instead of package.json keeps the whole
+// manifest — npm scripts included — out of dist/bundle.js.
+export const SERVER_NAME = 'ofw-mcp';
+export const VERSION = '2.20.4'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.20.3",
+  "version": "2.20.4",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -26,7 +26,7 @@
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --define:process.env.WS_NO_BUFFER_UTIL=true --define:process.env.WS_NO_UTF_8_VALIDATE=true --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node --env-file=.env dist/index.js",
     "test": "npm run typecheck && vitest run",
     "test:coverage": "npm run typecheck && vitest run --coverage",
@@ -34,7 +34,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.15.0",
+    "@chrischall/mcp-utils": "^3.0.0",
     "@fetchproxy/bootstrap": "^3.6.0",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.0",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.20.3",
+  "version": "2.20.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.20.3",
+      "version": "2.20.4",
       "transport": {
         "type": "stdio"
       },
@@ -76,6 +76,96 @@
           "description": "Set true for strict reimbursement upload mode: only healthcheck, ofw_upload_expense_pdf, ofw_create_expense, and ofw_update_expense register. Implies OFW_EXPENSE_ONLY.",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_INLINE_ATTACHMENTS",
+          "description": "Set \"true\" to return attachments as MCP content blocks by default (images render directly; other files come back as embedded resources) instead of writing to disk. Callers can still override per call via the tool's `inline` argument.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_ATTACHMENTS_DIR",
+          "description": "Where ofw_download_attachment writes (default ~/Downloads/ofw-mcp). Every disk write is confined to it: a saveTo outside it (after resolving symlinks) is refused, and an existing file is replaced only with force:true.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_UPLOAD_DIR",
+          "description": "The only directory ofw_upload_attachment may read from (default: OFW_ATTACHMENTS_DIR). Paths outside it after resolving symlinks, hidden files/dirs, and files over 25 MiB are refused.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_CACHE_IDENTITY",
+          "description": "Explicit cache-key label; overrides OFW_USERNAME for fetchproxy-only multi-account setups. If you have multiple OFW accounts and want them to use separate caches, set it to a label per profile.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_CACHE_DIR",
+          "description": "Overrides the message cache directory (default ~/.cache/ofw-mcp).",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_DISABLE_FETCHPROXY",
+          "description": "Skip the fetchproxy fallback, so missing credentials become a hard error (useful in headless CI).",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_AUTO_REFRESH",
+          "description": "When a cached read comes back EMPTY from a non-fresh cache, the read tools sync the backing folders and answer from the refreshed cache instead of refusing with UNVERIFIED_EMPTY (default off, i.e. refuse). Per-call autoRefresh overrides it. A refresh that does not make the read verifiable still refuses.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_FRESHNESS_TTL_SECONDS",
+          "description": "How long a verified-against-OFW folder stays labelled `fresh` in read tools' `freshness` block (default 300). Unusable values fall back to the default — a typo must never widen the window in which stale data reads as current.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_SYNC_MAX_REQUESTS",
+          "description": "Per-call OFW-request budget for ofw_sync_messages: a positive integer caps how many OFW requests one sync call may make before pausing; the next call resumes where it left off. Unset means unbounded (local installs walk fully in one call).",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_REQUEST_TIMEOUT_MS",
+          "description": "Per-request timeout for OFW API calls, in milliseconds (default 30000). Each retry gets its own fresh window.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_DEBUG_LOG",
+          "description": "Log every OFW request/response to stderr (Authorization redacted). Diagnostic only.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "DISPLAY_TZ",
+          "description": "IANA zone (e.g. America/New_York, the default) for every `<field>Display` value, and the zone a NAIVE source timestamp is assumed to be wall-clock in. OFW's API reports naive local times in the account's own zone, so this must match it. Unrecognized values fall back to the default.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "FETCHPROXY_WS_PORT",
+          "description": "Localhost port of the fetchproxy concentrator the ContextMint Bridge extension connects to (default 37149). Every MCP on one machine shares it, so move it for all of them or not at all.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "FETCHPROXY_WS_HOST",
+          "description": "Bind interface for the fetchproxy concentrator, a literal IP only (default 127.0.0.1). Keep on loopback; it exists for hosted deployments that run each MCP in its own network namespace.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "FETCHPROXY_IDENTITY_DIR",
+          "description": "Absolute path where the fetchproxy long-term identity keypair is stored (default ~/.fetchproxy/identity/).",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/ofw/SKILL.md

@@ -223,7 +223,7 @@ Editing a draft mints a **new OFW id every time** — `ofw_save_draft` replaces
 ## Caution
 
 - **Always confirm before sending messages or deleting anything** — OFW is a legal co-parenting record.
-- **The server enforces it for co-parent-visible writes.** `ofw_send_message`, `ofw_create_expense`, shared-event `ofw_create_event`/`ofw_update_event`/`ofw_delete_event` and `SHARED` `ofw_upload_attachment` either raise a confirmation prompt or, on clients that cannot (claude.ai, Claude Desktop), return `status: "confirmation-required"` with a `preview` and a `confirmToken` and write nothing. Show the user the preview, get their approval, then repeat the SAME call with `confirmToken`. A `DRAFT_CHANGED` refusal means the arguments or the target changed since the preview — show the fresh preview it returns and ask again.
+- **The server enforces it for co-parent-visible writes.** `ofw_send_message`, `ofw_create_expense`, shared-event `ofw_create_event`/`ofw_update_event`/`ofw_delete_event` and `SHARED` `ofw_upload_attachment` either raise a confirmation prompt (unless the server sets `MCP_CONFIRM_ELICITATION=off`) or, on clients that cannot (claude.ai, Claude Desktop) and whenever that is set, return `status: "confirmation-required"` with a `preview` and a `confirmToken` and write nothing. Show the user the preview, get their approval, then repeat the SAME call with `confirmToken`. A `DRAFT_CHANGED` refusal means the arguments or the target changed since the preview — show the fresh preview it returns and ask again.
 - **`*_UNCONFIRMED` means it may have landed.** Never retry a `SEND_`/`EXPENSE_`/`EVENT_`/`JOURNAL_UNCONFIRMED` write until the matching list/sync shows it did not.
 - `ofw_get_notifications` updates last-seen status — avoid calling silently in the background.
 - `ofw_get_message` marks messages read — warn the user if they want to keep something unread.