ofw-mcp 2.7.1 → 2.8.0

package/dist/extract/zip.js

@@ -0,0 +1,110 @@
+// A minimal, dependency-free ZIP reader.
+//
+// OOXML attachments (.xlsx/.docx/.pptx) are ZIP containers of XML parts, so
+// reading one is the first step of every office-document extractor. This is
+// deliberately not a general ZIP library: it reads the central directory,
+// slices an entry's bytes, and inflates DEFLATE members via the WHATWG
+// `DecompressionStream` — which exists in BOTH Node ≥18 and workerd, so the
+// same code runs on the stdio server and the hosted connector. Using
+// `node:zlib` here would break the Worker build; adding a userland inflate
+// dependency would bloat it. Neither is necessary.
+import { inflateBounded, MAX_DECOMPRESSED_BYTES } from './inflate.js';
+const EOCD_SIG = 0x06054b50;
+const CENTRAL_SIG = 0x02014b50;
+const LOCAL_SIG = 0x04034b50;
+const ZIP64_SENTINEL = 0xffffffff;
+/**
+ * Hard ceiling on a single decompressed member (32 MiB). An attachment is a
+ * co-parent-supplied file, so a zip bomb is a real (if unlikely) input, and the
+ * Worker's memory budget is what is being protected.
+ *
+ * The cap is enforced on the bytes as they arrive ({@link inflateBounded}), NOT
+ * on the size the archive declares for itself. The declared size is checked too
+ * — it rejects an HONEST oversized member without inflating anything — but it
+ * is an optimization, not the guarantee: a central directory is free to claim
+ * 1 KB in front of a member that expands to a gigabyte.
+ */
+export const ZIP_MAX_UNCOMPRESSED_BYTES = MAX_DECOMPRESSED_BYTES;
+/** Locate the end-of-central-directory record, scanning back past any comment. */
+function findEocd(bytes) {
+    // The comment field is a uint16, so the record starts at most 22+65535 bytes
+    // from the end. Scan backwards for the signature.
+    const earliest = Math.max(0, bytes.length - (22 + 0xffff));
+    for (let i = bytes.length - 22; i >= earliest; i--) {
+        if (bytes.readUInt32LE(i) === EOCD_SIG)
+            return i;
+    }
+    throw new Error('not a ZIP archive (no end-of-central-directory record)');
+}
+export async function readZip(bytes, opts = {}) {
+    const limit = opts.maxUncompressedBytes ?? ZIP_MAX_UNCOMPRESSED_BYTES;
+    const eocd = findEocd(bytes);
+    const count = bytes.readUInt16LE(eocd + 10);
+    const cdOffset = bytes.readUInt32LE(eocd + 16);
+    if (cdOffset === ZIP64_SENTINEL || count === 0xffff) {
+        throw new Error('ZIP64 archives are not supported');
+    }
+    const entries = new Map();
+    let p = cdOffset;
+    for (let i = 0; i < count; i++) {
+        if (bytes.readUInt32LE(p) !== CENTRAL_SIG) {
+            throw new Error(`corrupt ZIP central directory at offset ${p}`);
+        }
+        const nameLen = bytes.readUInt16LE(p + 28);
+        const extraLen = bytes.readUInt16LE(p + 30);
+        const commentLen = bytes.readUInt16LE(p + 32);
+        const name = bytes.toString('utf8', p + 46, p + 46 + nameLen);
+        entries.set(name, {
+            name,
+            method: bytes.readUInt16LE(p + 10),
+            compressedSize: bytes.readUInt32LE(p + 20),
+            uncompressedSize: bytes.readUInt32LE(p + 24),
+            localOffset: bytes.readUInt32LE(p + 42),
+        });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    const cache = new Map();
+    async function read(name) {
+        const cached = cache.get(name);
+        if (cached)
+            return cached;
+        const entry = entries.get(name);
+        if (!entry)
+            return null;
+        // Cheap pre-check for an honest oversized member. A lying header falls
+        // through to the streaming cap below, which is the real guarantee.
+        if (entry.uncompressedSize > limit) {
+            throw new Error(`ZIP member ${name} is too large to extract (${entry.uncompressedSize} bytes)`);
+        }
+        // The central directory records the local header's offset, but the local
+        // header carries its OWN name/extra lengths (they can differ from the
+        // central copy), so the data offset must be computed from it.
+        const lo = entry.localOffset;
+        if (bytes.readUInt32LE(lo) !== LOCAL_SIG) {
+            throw new Error(`corrupt ZIP local header for ${name}`);
+        }
+        const start = lo + 30 + bytes.readUInt16LE(lo + 26) + bytes.readUInt16LE(lo + 28);
+        const raw = bytes.subarray(start, start + entry.compressedSize);
+        let out;
+        if (entry.method === 0)
+            out = Buffer.from(raw);
+        else if (entry.method === 8)
+            out = await inflateBounded(raw, 'deflate-raw', limit, `ZIP member ${name}`);
+        else
+            throw new Error(`unsupported ZIP compression method ${entry.method} for ${name}`);
+        cache.set(name, out);
+        return out;
+    }
+    return {
+        names: () => [...entries.keys()],
+        has: (name) => entries.has(name),
+        read,
+        async readText(name) {
+            const buf = await read(name);
+            if (!buf)
+                return null;
+            const text = buf.toString('utf8');
+            return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+        },
+    };
+}

package/dist/index.js

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

package/dist/sync.js

@@ -222,8 +222,13 @@ async function walkPages(client, folder, folderId, opts, store) {
                 await fetchAttachmentMetaBudgeted(client, item.id, detailFileIds, store, budget);
             }
         }
-        // Flush the page's rows in one transaction/RPC. Empty array is a no-op.
-        await store.upsertMessages(toUpsert);
+        // Flush the page's rows in one transaction/RPC. Skipped entirely when the
+        // page held nothing new: on the Worker this call is a Durable-Object RPC,
+        // and a DO RPC counts against the same subrequest budget as an OFW fetch.
+        // A deep re-walk crosses page after page of already-cached messages, so an
+        // unconditional "no-op" write spends the caller's budget to store nothing.
+        if (toUpsert.length > 0)
+            await store.upsertMessages(toUpsert);
         if (pageBudgetHit) {
             // Paused mid-page. Resume at THIS page: the partial rows are cached, so
             // getMessages skips them next time and upserts are idempotent.

package/dist/tools/delivery.js

@@ -0,0 +1,99 @@
+// The attachment delivery ladder.
+//
+// A successful fetch must always produce retrievable content. "The host cannot
+// render this type" is a DISPLAY limit, and letting it become a DATA limit is
+// the bug this module exists to close: `ofw_download_attachment` used to fetch
+// a 10 KB custody-schedule spreadsheet, hand back an EmbeddedResource, and have
+// the host reject it with "Resources of type '…spreadsheetml.sheet' are not
+// currently supported" — leaving the caller holding nothing at all.
+//
+// Every inline delivery now walks the same rungs and returns the first that
+// works:
+//
+//   1. host-renderable image  → ImageContent (the model sees the picture)
+//   2. extractable document   → the FILE'S TEXT, as text (see src/extract)
+//   3. raw bytes              → base64 EmbeddedResource, as before
+//
+// Rung 3 never disappears, so nothing regresses; rung 2 is what makes a
+// spreadsheet, PDF, Word or PowerPoint attachment readable at all. When a rung
+// is skipped or fails, the response says so by name in `deliveryAttempts` —
+// a caller must never be left guessing why it got bytes instead of content.
+import { extractAttachment } from '../extract/index.js';
+import { isHostRenderableImage } from './attachments.js';
+/**
+ * Attempt extraction, converting every failure into a REASON rather than an
+ * exception: a format we cannot read must still be delivered as bytes, and the
+ * caller is owed the explanation either way.
+ */
+export async function tryExtract(bytes, mimeType, fileName, opts) {
+    try {
+        const extracted = await extractAttachment(bytes, mimeType, fileName, {
+            maxChars: opts.maxChars,
+            parts: opts.parts,
+        });
+        if (!extracted) {
+            return { reason: `no text extractor for ${mimeType} (${fileName})` };
+        }
+        return { extracted, truncated: extracted.truncated ?? false };
+    }
+    catch (err) {
+        // A malformed .xlsx is still an .xlsx: report why it could not be read and
+        // fall through to the bytes, rather than failing the whole call.
+        return { reason: `extraction failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Build the content blocks for an inline download by walking the ladder.
+ * The first block is always a JSON meta block naming `deliveredVia`, so the
+ * caller can tell how the content arrived without inspecting block types.
+ */
+export async function buildInlineDelivery(input) {
+    const { fileId, fileName, mimeType, bytes, forcedInline, options } = input;
+    const meta = {
+        fileId, fileName, mimeType, sizeBytes: bytes.length, mode: 'inline',
+    };
+    if (forcedInline)
+        meta.forcedInline = true;
+    const block = () => ({ type: 'text', text: JSON.stringify(meta, null, 2) });
+    // Rung 1 — the host renders these itself, and a picture beats a description.
+    if (isHostRenderableImage(mimeType)) {
+        meta.deliveredVia = 'image';
+        return { content: [block(), { type: 'image', data: bytes.toString('base64'), mimeType }] };
+    }
+    // Rung 2 — extraction. Skipped only when the caller explicitly opts out.
+    const attempts = [];
+    if (options.extract === false) {
+        attempts.push('extraction skipped (extract:false)');
+    }
+    else {
+        const outcome = await tryExtract(bytes, mimeType, fileName, options);
+        if (outcome.extracted) {
+            meta.deliveredVia = 'extracted';
+            meta.extracted = outcome.extracted;
+            meta.truncated = outcome.truncated;
+            // The bytes are deliberately NOT also attached: the extracted text is the
+            // readable form, and a duplicate base64 blob would be the very payload
+            // the host rejects — plus double the response size.
+            meta.note = 'Content extracted from the file. Pass extract:false to get the raw bytes instead.';
+            return { content: [block()] };
+        }
+        /* v8 ignore next -- tryExtract always sets `reason` when it returns no extraction */
+        attempts.push(outcome.reason ?? 'extraction produced no content');
+    }
+    // Rung 3 — the bytes themselves. Always available, so a fetch that succeeded
+    // never ends with the caller holding nothing.
+    meta.deliveredVia = 'blob';
+    meta.deliveryAttempts = attempts;
+    meta.note = 'Returned as raw bytes. Some hosts cannot render an embedded resource of this type; '
+        + 'if it came back unreadable, the file has no text extractor here (see deliveryAttempts).';
+    return {
+        content: [block(), {
+                type: 'resource',
+                resource: {
+                    uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
+                    mimeType,
+                    blob: bytes.toString('base64'),
+                },
+            }],
+    };
+}

package/dist/tools/draft-freshness.js

@@ -47,8 +47,13 @@ function isNotFound(e) {
  * Read a draft's AUTHORITATIVE state straight from OFW, bypassing the cache.
  *
  * Returns `null` when the draft no longer exists (404). Any other failure
- * throws `DraftFreshnessError`: a freshness check that could not run must
- * abort the write, never wave it through — see the callers in messages.ts.
+ * throws, and the callers in messages.ts abort on ALL of them: a freshness
+ * check that could not run must never wave the write through.
+ *
+ * Most failures throw `DraftFreshnessError` from this function, but not all —
+ * a strict `parseLenient` mismatch on the response throws `McpToolError`
+ * instead. Callers must not assume the narrower type (the catch blocks read
+ * only `.message`, which every Error carries).
  */
 export async function fetchServerDraft(client, id) {
     let raw;

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.
@@ -125,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,
@@ -201,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);
@@ -299,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.
@@ -480,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.` };
@@ -659,7 +714,16 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 // silent normalization becomes a visible warning rather than a surprise.
                 if (resolvedReplyTo !== null && effectiveReplyTo !== resolvedReplyTo) {
                     const rewrittenFrom = requestedReplyTo !== resolvedReplyTo ? ` (rewritten from ${requestedReplyTo})` : '';
-                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo === null ? 'null' : effectiveReplyTo} — OurFamilyWizard did not thread this draft (its inReplyTo/showContext will be empty). The subject and body were saved; only the reply linkage was dropped. If threading matters, verify on ourfamilywizard.com.`);
+                    // 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
@@ -825,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;
@@ -843,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
@@ -871,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
@@ -906,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', {
@@ -932,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(),
         },
@@ -940,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);
@@ -962,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
@@ -982,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
@@ -1001,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.1",
+  "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)",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.7.1",
+  "version": "2.8.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.7.1",
+      "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