ofw-mcp 2.7.0 → 2.8.0

package/dist/tools/messages.js

@@ -3,10 +3,11 @@ import { syncAll, fetchAttachmentMeta, fetchAttachmentMetaForMessage, getDraftsC
 import { buildFreshness } from './freshness.js';
 import { checkDraftFreshness, draftRevision, fetchServerDraft, staleDraftPayload, } from './draft-freshness.js';
 import { getFolderVerifiedAt } from '../sync.js';
-import { isHostRenderableImage, resolveDownloadMime } from './attachments.js';
-import { getAttachmentsDir, getDefaultInlineAttachments, getSyncMaxRequests, getWriteMode } from '../config.js';
+import { buildInlineDelivery, tryExtract } from './delivery.js';
+import { resolveDownloadMime } from './attachments.js';
+import { getAllowMarkRead, getAttachmentsDir, getDefaultInlineAttachments, getFetchUnreadBodies, getSyncMaxRequests, getWriteMode, } from '../config.js';
 import { basename, join } from 'node:path';
-import { ApiRecipientSchema, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded, withReadState } from './_shared.js';
+import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded, withReadState } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
@@ -28,6 +29,8 @@ const SavedDraftDetailSchema = z.looseObject({
     date: DateSchema.optional(),
     replyToId: z.number().nullable().optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // Read to audit whether requested myFileIDs actually attached (Defect 3).
+    files: z.array(z.number()).optional(),
 });
 // ofw_get_message's uncached detail fetch — lenient: a mismatch warns to
 // stderr and the existing ?? fallbacks keep the tool serving.
@@ -123,6 +126,48 @@ async function draftsFreshness(cache) {
         : 'unverified';
     return { freshness, serverConfirmed: cacheStatus === 'fresh', cacheStatus };
 }
+/**
+ * Decide whether fetching this message's body from OFW would stamp the record,
+ * and refuse when the caller (or the deployment) has opted out of that.
+ *
+ * Returns null to proceed, or a structured refusal to return as-is.
+ *
+ * Only ONE case actually stamps: fetching the body of an UNREAD INBOX message.
+ * Everything else is waved through, because refusing a read that changes
+ * nothing would be friction with no safety to show for it:
+ *   - a SENT message — the "First Viewed" times on it belong to the recipient,
+ *     and our own fetch never writes one;
+ *   - an already-read inbox message — the stamp exists; re-reading cannot add
+ *     a second one (`deriveRead` is monotonic, so this cannot flip back);
+ *   - a cached body — this function is never reached, the cache served it.
+ *
+ * An id with NO cached row is refused: whether it would stamp is exactly what
+ * we cannot know without making the request that stamps it. Syncing first
+ * (which reads list pages, not bodies) resolves it.
+ */
+export function markReadVerdict(cached, requested) {
+    const ceiling = getAllowMarkRead();
+    if (ceiling && (requested ?? true))
+        return null;
+    const wouldStamp = cached === null
+        || (cached.folder === 'inbox' && !deriveRead(cached));
+    if (!wouldStamp)
+        return null;
+    const because = ceiling
+        ? 'you passed allowMarkRead:false'
+        : 'this server runs with OFW_ALLOW_MARK_READ=false';
+    return jsonErrorResponse({
+        error: 'MARK_READ_BLOCKED',
+        messageId: cached?.id ?? null,
+        reason: cached === null
+            ? 'This id is not in the cache, so whether reading it would mark it read is unknowable without making the request that would.'
+            : 'This is an unread inbox message; fetching its body would mark it read on OurFamilyWizard.',
+        note: `Refused because ${because}. Reading a message for the first time stamps a "First Viewed" timestamp that your co-parent can see and that forms part of the record — it cannot be undone. To read it anyway, call again with allowMarkRead:true${ceiling ? '' : ' (which this deployment does not permit — clear OFW_ALLOW_MARK_READ to re-enable)'}.`,
+        ...(cached === null
+            ? { hint: 'Run ofw_sync_messages first: it walks list pages, not bodies, so it can tell you what this id is without stamping anything.' }
+            : { subject: cached.subject, fromUser: cached.fromUser, sentAt: cached.sentAt }),
+    });
+}
 export function registerMessageTools(server, client, cacheProvider, attachmentIO) {
     // OFW_WRITE_MODE gate (see config.ts). Send lands on the court-visible
     // record, so it is 'all'-only; draft-level writes (save/delete drafts,
@@ -199,10 +244,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         return jsonResponse(payload);
     });
     server.registerTool('ofw_get_message', {
-        description: 'Get a single OurFamilyWizard message OR draft by ID. Reads from local cache when available; otherwise fetches from OFW (which will mark unread inbox messages as read on OFW). For ids that match a draft (in the drafts cache), the response carries folder="drafts" and the body/subject/recipients reflect the drafts cache (which ofw_sync_messages keeps fresh) — drafts have no `fromUser`, and `sentAt`/`fetchedBodyAt` mirror the draft\'s `modifiedAt`. For inbox/sent messages, folder is "inbox" or "sent" as before.',
+        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 },
         inputSchema: {
             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(),
         },
     }, async (args) => {
         const id = Number(args.messageId);
@@ -297,6 +343,14 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             const freshness = await buildFreshness(cache, { source: 'cache', folders: [row.folder] });
             return jsonResponse({ ...withReadState(row), attachments, freshness });
         }
+        // Everything above this line was served without asking OFW for a body.
+        // This is the one path that fetches one — and fetching the body of an
+        // unread INBOX message marks it read on OFW, stamping a "First Viewed"
+        // time the co-parent can see. That is a court-visible, irreversible change
+        // made as a side effect of an ordinary read, so it gets an explicit gate.
+        const markReadCheck = markReadVerdict(cached, args.allowMarkRead);
+        if (markReadCheck !== null)
+            return markReadCheck;
         const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (ofw_get_message)' });
         // Derive the folder for a live-fetched message. A cached row (reached here
         // only when its body was NULL) already knows its folder, so keep it.
@@ -478,10 +532,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             server = await fetchServerDraft(client, draftId);
         }
         catch (e) {
-            // fetchServerDraft funnels every non-404 failure into DraftFreshnessError,
-            // so anything landing here means the check could not RUN. That is not
-            // permission to proceed: a transient 5xx must not degrade into a blind
-            // overwrite.
+            // Anything landing here means the check could not RUN. Most failures
+            // arrive as DraftFreshnessError from fetchServerDraft, but not all of
+            // them: a strict parseLenient mismatch on the server draft throws
+            // McpToolError instead. Both are caught, and both abort — which is the
+            // point. A failed check is not permission to proceed: a transient 5xx
+            // must not degrade into a blind overwrite. (The cast below only reads
+            // `.message`, which every Error carries.)
             const reason = e.message;
             if (force) {
                 return { ok: true, note: `WARNING: force:true — proceeded with ${action} on draft ${draftId} even though its current state could not be read from OurFamilyWizard (${reason}). Any newer server-side version was destroyed and is NOT recoverable from this response.` };
@@ -497,8 +554,15 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             };
         }
         const verdict = checkDraftFreshness({ server, cached, expectedRevision });
-        if (verdict.verdict === 'FRESH')
-            return { ok: true, note: null };
+        if (verdict.verdict === 'FRESH') {
+            // A metadata-only "conflict" is the connector's own post-save replyToId
+            // normalization catching up — safe to proceed, but say so rather than
+            // pretending nothing moved.
+            const note = verdict.metadataOnly
+                ? `NOTE: draft ${draftId} was treated as current for this ${action}. Since you read it, OurFamilyWizard normalized connector-authored metadata (${verdict.changedFields.join(', ')}); the subject, body and recipients are unchanged, so this is not a conflict.`
+                : null;
+            return { ok: true, note };
+        }
         if (force) {
             // Loud, and the overwritten content rides along in the response so it is
             // recoverable from the tool result itself.
@@ -560,7 +624,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 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. SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if it 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). The refusal returns the current server body under serverBody — merge your edit into it and retry with expectedRevision.',
+            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 that also lists which fields (subject/body/recipients/replyToId/attachments) were carried over. 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, and the returned `revision` reflects that authoritative state (so it will match on your next edit). FIELD PRESERVATION: the response echoes the effective threading (replyToId/inReplyTo) and, whenever OFW did not carry over a requested replyToId, recipient or attachment, a `warnings[]` entry naming what was dropped — never a silent null. 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 },
             inputSchema: {
                 subject: z.string().describe('Message subject'),
@@ -619,26 +683,72 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let replaceNote = null;
             let verifyNote = null;
             let newRevision = null;
+            // Fields accepted on the write that the saved draft must carry — or their
+            // loss must be reported. Never a silent drop (Defect 3).
+            const warnings = [];
             if (newId !== null) {
                 verifyNote = verifyWriteLanded('draft', { subject: args.subject, body: args.body }, detail);
+                // Trust the re-fetched server detail as the source of truth for the stored
+                // replyToId — NOT `resolvedReplyTo` (what we intended to post). OFW
+                // normalizes/drops threading after a save, and masking that with our own
+                // intent (the old `detail.replyToId ?? resolvedReplyTo`) both returned a
+                // revision that was stale on arrival (Defect 1) and hid a dropped reply
+                // link (Defect 3). `?? null` keeps a genuinely-echoed value and reflects a
+                // null/absent one honestly.
+                const effectiveReplyTo = detail.replyToId ?? null;
+                const storedRecipients = mapRecipients(detail.recipients);
                 persisted = {
                     id: newId,
                     subject: detail.subject ?? args.subject,
                     body: detail.body ?? '',
-                    recipients: mapRecipients(detail.recipients),
-                    replyToId: detail.replyToId ?? resolvedReplyTo,
+                    recipients: storedRecipients,
+                    replyToId: effectiveReplyTo,
                     modifiedAt: detail.date?.dateTime ?? new Date().toISOString(),
                     listData: detail,
                 };
                 await cache.upsertDraft(persisted);
+                // The revision is now computed from the server-authoritative detail, so it
+                // is the value a subsequent read/verify will observe (Defect 1).
                 newRevision = draftRevision(persisted);
+                // Audit every field the caller supplied against what actually landed, so a
+                // silent normalization becomes a visible warning rather than a surprise.
+                if (resolvedReplyTo !== null && effectiveReplyTo !== resolvedReplyTo) {
+                    const rewrittenFrom = requestedReplyTo !== resolvedReplyTo ? ` (rewritten from ${requestedReplyTo})` : '';
+                    // Two different outcomes reach this branch, and they need different
+                    // warnings. OFW either DROPPED the link (null) or RE-TARGETED it to
+                    // another message in the thread. Describing both as "did not thread
+                    // this draft (its inReplyTo/showContext will be empty)" contradicted
+                    // the non-null inReplyTo the same response echoes — and a warning the
+                    // caller can see is false is a warning it learns to skip.
+                    const outcome = effectiveReplyTo === null
+                        ? 'OurFamilyWizard did not thread this draft (its inReplyTo/showContext will be empty). The subject and body were saved; only the reply linkage was dropped.'
+                        : `OurFamilyWizard re-targeted the reply to message ${effectiveReplyTo} instead. The draft IS threaded — to that message, not the one requested — and the inReplyTo in this response reflects where it actually landed.`;
+                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo === null ? 'null' : effectiveReplyTo} — ${outcome} If threading matters, verify on ourfamilywizard.com.`);
+                }
+                // Only warn on recipients/attachments when the detail actually reported
+                // them — an omitted array is "not echoed", not "dropped", and crying wolf
+                // there would desensitize the caller to the real drops.
+                if (args.recipientIds !== undefined && Array.isArray(detail.recipients)) {
+                    const requested = [...new Set(args.recipientIds)].sort((a, b) => a - b);
+                    const stored = [...new Set(storedRecipients.map((r) => r.userId))].sort((a, b) => a - b);
+                    if (requested.join(',') !== stored.join(',')) {
+                        warnings.push(`recipientIds were requested as [${requested.join(', ')}] but the saved draft has [${stored.join(', ')}]. Verify the recipients on ourfamilywizard.com.`);
+                    }
+                }
+                if (myFileIDs.length > 0 && Array.isArray(detail.files)) {
+                    const storedFiles = new Set(detail.files);
+                    const missing = myFileIDs.filter((id) => !storedFiles.has(id));
+                    if (missing.length > 0) {
+                        warnings.push(`Attachment fileId(s) ${missing.join(', ')} were requested in myFileIDs but are not attached to the saved draft. Re-upload or re-attach if needed.`);
+                    }
+                }
                 // 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]);
                         await cache.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.)`;
+                        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.) Fields carried over to the new draft: subject, body, recipients (${persisted.recipients.length}), replyToId (${persisted.replyToId === null ? 'none' : persisted.replyToId}), attachments (${myFileIDs.length}).${warnings.length > 0 ? ' See warnings above for any field OurFamilyWizard did not carry over.' : ''}`;
                     }
                     catch (e) {
                         // Partial-failure safety: the new draft is already created and
@@ -650,12 +760,24 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             }
             // The draft was just re-fetched from OFW by postMessageAndRefetch, so this
             // one row IS server-confirmed regardless of the drafts folder's overall
-            // cache freshness.
+            // cache freshness. `inReplyTo` echoes the effective threading alongside the
+            // volatile `id`, and `warnings` names any requested field that did not land.
             const responseObj = persisted !== null
-                ? { ...persisted, revision: newRevision, cacheStatus: 'fresh', serverConfirmed: true }
+                ? {
+                    ...persisted,
+                    inReplyTo: persisted.replyToId,
+                    revision: newRevision,
+                    cacheStatus: 'fresh',
+                    serverConfirmed: true,
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                }
                 : raw;
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
-            const notes = [forceNote, rewriteNote, verifyNote, replaceNote].filter((n) => n !== null).join('\n\n');
+            const warnNote = warnings.length > 0
+                ? `WARNING: ${warnings.join('\n\n')}`
+                : null;
+            const notes = [forceNote, rewriteNote, verifyNote, warnNote, replaceNote]
+                .filter((n) => n !== null).join('\n\n');
             return textResponse(notes ? `${notes}\n\n${text}` : text);
         });
     if (allowDrafts)
@@ -767,13 +889,16 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             });
         });
     server.registerTool('ofw_download_attachment', {
-        description: 'Download an OFW message attachment by fileId. By default, bytes are saved to disk (~/Downloads/ofw-mcp/) and the response carries the absolute path, mime type, and size for the caller to read back. Pass inline:true to skip disk entirely and return the bytes as MCP content blocks — host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent (the model sees them directly); every other file comes back as an EmbeddedResource blob carrying the bytes. Reported mime types are always normalized to a bare media type (no charset/name parameters). Use inline for small files where you want the model to read content immediately and the host is sandboxed; use disk for large files or when you want a persistent local copy. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var (set to "true" to make inline the default). On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (the response is marked forcedInline:true) rather than failing. 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).',
+        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 },
         inputSchema: {
             fileId: z.number().describe('Attachment file id (from ofw_get_message → attachments[].fileId)'),
-            inline: z.boolean().describe('If true, return bytes inline as MCP content (ImageContent for host-renderable images, embedded resource blob otherwise) 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 bytes are still returned. If omitted, falls back to the OFW_INLINE_ATTACHMENTS env var (default: false = disk).').optional(),
+            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(),
             saveTo: z.string().describe('Absolute path or directory to write to. If a directory, the OFW filename is used. Default: ~/Downloads/ofw-mcp/<fileId>-<filename>. Ignored when inline is in effect.').optional(),
             force: z.boolean().describe('Re-download even if already on disk. Default false. Ignored when inline:true (inline always fetches fresh bytes, or reuses an on-disk copy if present).').optional(),
+            extract: z.boolean().describe('Whether to extract readable content from the file. Default: on for inline delivery of any non-image type, off in disk mode. Set false to get the raw bytes inline instead of extracted text (e.g. to hash or re-upload the file); set true in disk mode to get both the saved path and the extracted content.').optional(),
+            maxChars: z.number().int().min(500).max(500_000).describe('Ceiling on extracted characters (default 50000). Over it, content is clipped on a row/line boundary, `truncated` is set, and anything dropped whole is listed in `extracted.omitted`.').optional(),
+            parts: z.string().describe('Which sheets / slides / pages to extract, e.g. "1-3,5" (1-based positions) or a sheet name like "2026". A bare number matches either a position or a name. Omit for everything. Unselected parts are listed in `extracted.omitted`.').optional(),
         },
     }, async (args) => {
         const fileId = args.fileId;
@@ -785,6 +910,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // response is honest about it instead of silently ignoring the argument.
         const inline = requestedInline || !attachmentIO.supportsDisk;
         const forcedInline = inline && !requestedInline;
+        const deliveryOptions = { extract: args.extract, maxChars: args.maxChars, parts: args.parts };
         let cached = await cache.getAttachment(fileId);
         if (!cached) {
             // Not in cache. Fetch metadata and store under the messageId=0
@@ -813,25 +939,12 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             // charset onto binaries), then fall back to the stripped header, then the
             // extension. A parameter suffix would make the host reject an image.
             const mimeType = resolveDownloadMime(bytes, headerMime, fileName);
-            const base64 = bytes.toString('base64');
-            const meta = {
-                fileId, fileName, mimeType, sizeBytes: bytes.length, mode: 'inline',
-            };
-            if (forcedInline)
-                meta.forcedInline = true;
-            const metaBlock = { type: 'text', text: JSON.stringify(meta, null, 2) };
-            // Only host-renderable image types go back as ImageContent (with the bare
-            // media type the renderer accepts); everything else — non-renderable
-            // images included — goes back as an EmbeddedResource so the caller always
-            // gets the bytes.
-            if (isHostRenderableImage(mimeType)) {
-                return { content: [metaBlock, { type: 'image', data: base64, mimeType }] };
-            }
-            return { content: [metaBlock, { type: 'resource', resource: {
-                            uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
-                            mimeType,
-                            blob: base64,
-                        } }] };
+            // The ladder decides between rendering, extracted content, and raw bytes
+            // — see src/tools/delivery.ts. Whatever the host can draw, the caller
+            // ends up holding something readable.
+            return await buildInlineDelivery({
+                fileId, fileName, mimeType, bytes, forcedInline, options: deliveryOptions,
+            });
         }
         let dest;
         // The filename comes from OFW file metadata — i.e. it is controlled by the
@@ -848,25 +961,38 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         else {
             dest = join(getAttachmentsDir(), `${fileId}-${safeName}`);
         }
+        // Disk mode extracts only on request: the caller already has a real file to
+        // open, so extraction is an add-on here rather than the point.
+        const extractOnDisk = args.extract === true;
         if (!args.force && cached.downloadedPath === dest) {
-            return jsonResponse({
-                // No bytes on hand for the no-op case: normalize the cached/extension
-                // MIME (empty buffer sniffs nothing) so a stored `image/png;charset=…`
-                // still reports bare.
-                fileId, path: dest, mimeType: resolveDownloadMime(Buffer.alloc(0), cached.mimeType, cached.fileName),
-                sizeBytes: cached.sizeBytes, fileName: cached.fileName, note: 'already downloaded',
-            });
+            // Nothing was re-fetched, so an extraction has to come off the copy on
+            // disk. If that copy has gone missing, fall through and download again
+            // rather than answering "already downloaded" with no content.
+            const onDisk = extractOnDisk ? attachmentIO.readDownloaded(dest) : null;
+            if (!extractOnDisk || onDisk) {
+                // No bytes on hand for the plain no-op case: normalize the
+                // cached/extension MIME (an empty buffer sniffs nothing) so a stored
+                // `image/png;charset=…` still reports bare.
+                const mimeType = resolveDownloadMime(onDisk ?? Buffer.alloc(0), cached.mimeType, cached.fileName);
+                return jsonResponse({
+                    fileId, path: dest, mimeType,
+                    sizeBytes: cached.sizeBytes, fileName: cached.fileName, note: 'already downloaded',
+                    ...(onDisk ? await tryExtract(onDisk, mimeType, cached.fileName, deliveryOptions) : {}),
+                });
+            }
         }
         const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
         attachmentIO.writeDownload(dest, response.body);
         await cache.markAttachmentDownloaded(fileId, dest);
         const fileName = response.suggestedFileName ?? cached.fileName;
+        const mimeType = resolveDownloadMime(response.body, response.contentType ?? cached.mimeType, fileName);
         return jsonResponse({
             fileId,
             path: dest,
-            mimeType: resolveDownloadMime(response.body, response.contentType ?? cached.mimeType, fileName),
+            mimeType,
             sizeBytes: response.body.length,
             fileName,
+            ...(extractOnDisk ? await tryExtract(response.body, mimeType, fileName, deliveryOptions) : {}),
         });
     });
     server.registerTool('ofw_sync_messages', {
@@ -874,7 +1000,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         annotations: { readOnlyHint: false },
         inputSchema: {
             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 (will mark them as read on OFW). Default false.').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(),
             deep: z.boolean().describe('If true, walk every OFW page until empty regardless of cache state. Use to backfill gaps. Default false.').optional(),
             maxRequests: z.number().int().min(1).describe('Maximum OFW requests this single call may make before pausing. When hit, the response reports done:false — call again with the same arguments to continue. Omit to use the server default (OFW_SYNC_MAX_REQUESTS, or unbounded on local installs).').optional(),
         },
@@ -882,7 +1008,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         const cache = cacheProvider();
         const result = await syncAll(client, {
             folders: args.folders,
-            fetchUnreadBodies: args.fetchUnreadBodies,
+            // Default from OFW_FETCH_UNREAD_BODIES (false unless set), and capped by
+            // the OFW_ALLOW_MARK_READ ceiling — fetching those bodies is exactly what
+            // stamps a First Viewed time on every unread message it touches.
+            fetchUnreadBodies: getAllowMarkRead() && (args.fetchUnreadBodies ?? getFetchUnreadBodies()),
             deep: args.deep,
             maxRequests: args.maxRequests ?? getSyncMaxRequests(),
         }, cache);
@@ -904,7 +1033,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         },
     }, async (args) => {
         const cache = cacheProvider();
-        const allowMarkRead = args.allowMarkRead ?? false;
+        // The server-wide ceiling wins: a per-call allowMarkRead:true (or an
+        // instruction injected into one) must not be able to stamp the record on a
+        // deployment configured to never do so.
+        const allowMarkRead = getAllowMarkRead() && (args.allowMarkRead ?? false);
         const requestedIds = args.messageIds ?? [];
         const ids = requestedIds.slice(0, MAX_FRESHNESS_IDS);
         // Folders default to "all three" only when the caller asked about nothing
@@ -924,7 +1056,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     ? (await cache.listDraftIds()).length
                     : await cache.countMessages({ folder });
                 const state = await cache.getSyncState(folder);
-                const historyComplete = state !== null && state.resumePage === null;
+                // Never synced at all is a DIFFERENT state from "backfill in progress",
+                // and both leave historyComplete false. Conflating them told the caller
+                // that older history was still being backfilled for a folder whose
+                // backfill had never started — advice that reads as "wait it out" when
+                // the real answer is "run a sync".
+                const neverSynced = state === null;
+                const historyComplete = !neverSynced && state.resumePage === null;
                 // A partially backfilled folder legitimately holds fewer messages than
                 // the server, so a count mismatch there proves nothing. Report both
                 // numbers and leave the verdict null rather than crying wolf for the
@@ -943,7 +1081,9 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     ...(inSync === null
                         ? { note: serverCount === null
                                 ? 'OFW did not report a count for this folder, so cached-vs-server cannot be compared. Use the per-id check instead.'
-                                : 'Older history is still being backfilled, so a lower cachedCount is expected and does not indicate drift.' }
+                                : neverSynced
+                                    ? 'This folder has never been synced, so the cache holds nothing to compare. Run ofw_sync_messages.'
+                                    : 'Older history is still being backfilled, so a lower cachedCount is expected and does not indicate drift.' }
                         : {}),
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -42,13 +42,13 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@chrischall/mcp-connector": "^1.0.0",
+    "@chrischall/mcp-connector": "^1.1.1",
     "@cloudflare/vitest-pool-workers": "^0.18.4",
     "@cloudflare/workers-oauth-provider": "^0.8.1",
     "@cloudflare/workers-types": "^5.20260708.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
-    "agents": "^0.17.3",
+    "agents": "^0.19.0",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.7",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.7.0",
+  "version": "2.8.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.7.0",
+      "version": "2.8.0",
       "transport": {
         "type": "stdio"
       },
@@ -40,6 +40,18 @@
           "description": "Set to \"true\" to register calendar write tools (create/update/delete event) in \"drafts\" write mode. Events have no draft stage but are reversible. Never overrides \"none\".",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_ALLOW_MARK_READ",
+          "description": "Default \"true\". Set \"false\" to forbid any tool from marking a message read on OurFamilyWizard - reading a body for the first time stamps a co-parent-visible \"First Viewed\" time that cannot be undone. A ceiling: no per-call argument can raise it.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_FETCH_UNREAD_BODIES",
+          "description": "Default \"false\". Whether ofw_sync_messages fetches unread inbox bodies by default (each fetch stamps a First Viewed time). Capped by OFW_ALLOW_MARK_READ.",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/ofw/SKILL.md

@@ -94,14 +94,14 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 | `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_get_message(messageId, allowMarkRead?)` | 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 read AND stamps a "First Viewed" time the co-parent can see — irreversible. Pass `allowMarkRead:false` to refuse that fetch instead; cached, sent and already-read messages are unaffected. |
 | `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). Each draft carries `serverConfirmed` — see [Freshness](#freshness). |
 | `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/`. |
+| `ofw_download_attachment(fileId, inline?, saveTo?, force?, extract?, maxChars?, parts?)` | Download an attachment. Inline delivery returns the first rung that works: image → `ImageContent`; .xlsx/.csv/.pdf/.docx/.pptx/text → **extracted content** under `extracted` (per-sheet CSV, per-page/slide text); anything else → raw bytes. Default writes to `~/Downloads/ofw-mcp/` (add `extract:true` for content too). Use `parts:"1-2"` / a sheet name and `maxChars` on large files. |
 | `ofw_check_freshness(folders?, messageIds?, allowMarkRead?)` | Cheap live check that the cache still matches OFW — one request for folder counts plus one per id, no bodies, no sync. Use before asserting current state. Only probes ids in the drafts cache unless `allowMarkRead:true` (probing others marks inbox messages read). |
 
 ### Calendar