ofw-mcp 2.14.0 → 2.15.1

package/dist/index.js

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

package/dist/tools/_shared.js

@@ -1,18 +1,28 @@
-import { expandPath as expandPathUtil, rawTextResult, textResult } from '@chrischall/mcp-utils';
+import { expandPath as expandPathUtil, minifiedResult, rawTextResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
 import { parseLenient } from '@chrischall/mcp-utils';
 import { normalizeTimestampsInValue } from '../timestamps.js';
-// Pretty-printed JSON tool result. Thin wrapper over @chrischall/mcp-utils'
-// `textResult`, with one addition: every timestamp in the payload is rewritten
-// to ISO-8601 with an explicit offset and paired with a `<field>Display`
-// sibling in the operator's zone.
+// JSON tool result, with NO formatting whitespace. Thin wrapper over
+// @chrischall/mcp-utils' `minifiedResult`, with one addition: every timestamp
+// in the payload is rewritten to ISO-8601 with an explicit offset and paired
+// with a `<field>Display` sibling in the operator's zone.
 //
 // This is the single seam every structured tool response passes through, which
 // is the point — normalizing here rather than at each call site is what makes
 // it impossible for a tool to reintroduce the naive-local values that had
 // `sentAt` and `fetchedBodyAt` silently disagreeing by the UTC offset.
+//
+// Minified rather than `JSON.stringify(data, null, 2)`: indentation was 23% of
+// a 135 KB message page — about 8,000 tokens a call — and nothing downstream
+// reads it. This server has no `raw` rung (see tools/project.ts), so every
+// response is `compact` or `full` and every response is minified.
+//
+// Whitespace INSIDE a value is untouched. A message body's blank lines are
+// content, and `JSON.stringify` never touches them; the rule is pinned by
+// tests here and in mcp-utils, so do not replace this with a text-level
+// minifier.
 export function jsonResponse(data) {
-    return textResult(normalizeTimestampsInValue(data));
+    return minifiedResult(normalizeTimestampsInValue(data));
 }
 // Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
 export const textResponse = rawTextResult;

package/dist/tools/messages.js

@@ -11,6 +11,8 @@ import { basename, join } from 'node:path';
 import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, reportsThreaded, reportsUnthreaded, textResponse, 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';
+import { resolveView, viewParam } 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.
 const DateSchema = z.looseObject({ dateTime: z.string() });
@@ -266,11 +268,15 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             q: z.string().describe('Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.').optional(),
             sort: z.enum(['newest', 'oldest']).describe('Result order: "newest" (default, newest first) or "oldest" (oldest first). This decides which end a truncated page keeps — with "newest" page 1 of a wide date range holds its most RECENT slice, with "oldest" its earliest. Use "oldest" to start at the old end of a range instead of paging to it.').optional(),
             autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
+            view: viewParam(MESSAGE_VIEWS, {
+                note: 'compact omits OurFamilyWizard\'s raw `listData` echo, which duplicates this record\'s own id, subject, sentAt, recipients and read flag; the sender is promoted to `from`, and `files`/`replied` are kept. Pass "full" for the echo.',
+            }),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
         const sort = args.sort ?? 'newest';
+        const view = resolveView(args.view, MESSAGE_VIEWS);
         const folderArg = args.folderId ?? 'both';
         let folder;
         if (folderArg === 'inbox')
@@ -372,7 +378,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             payload.autoRefreshed = true;
         }
         payload.freshness = freshness;
-        payload.messages = messages;
+        // Projected HERE, at the last possible moment, so `returned`, `complete`
+        // and every note above are computed from the rows themselves — a
+        // projection must never be able to change what the response claims about
+        // its own contents.
+        payload.messages = viewMessages(view, messages);
         return jsonResponse(payload);
     });
     server.registerTool('ofw_get_message', {
@@ -381,9 +391,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         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(),
+            view: viewParam(MESSAGE_VIEWS, {
+                note: 'compact omits OurFamilyWizard\'s raw `listData` echo, which duplicates this record\'s own id, subject, sentAt, recipients and read flag; the sender is promoted to `from`, and `files`/`replied` are kept. Pass "full" for the echo.',
+            }),
         },
     }, async (args) => {
         const id = Number(args.messageId);
+        const view = resolveView(args.view, MESSAGE_VIEWS);
         const cache = cacheProvider();
         // Draft routing: if this id is in the drafts cache, return a
         // MessageRow-shaped synthesis built from the draft. The drafts table
@@ -403,7 +417,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 id: draftRow.id,
                 folder: 'drafts',
                 subject: draftRow.subject,
-                fromUser: '',
+                // One tool, one sender key per rung. `compact` names the sender `from`
+                // everywhere else, so emitting `fromUser` here would mean the same
+                // tool's compact rung used two different key names depending on
+                // whether the id happened to be a draft. `null` rather than '' because
+                // a draft has no sender yet — it is unsent, and an empty string reads
+                // as a sender whose name we failed to find.
+                ...(view === 'compact' ? { from: null } : { fromUser: '' }),
                 sentAt: draftRow.modifiedAt,
                 recipients: draftRow.recipients,
                 body: draftRow.body,
@@ -413,7 +433,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 fetchedBodyAt: draftRow.modifiedAt,
                 replyToId: draftRow.replyToId,
                 chainRootId: null,
-                listData: draftRow.listData,
+                // OFW's raw echo, on `full` only. Everything above it is derived from
+                // the DRAFTS table, which is the source of truth for a draft id — the
+                // echo duplicates it and adds a stale copy of nothing else.
+                ...(view === 'compact' ? {} : { listData: draftRow.listData }),
                 attachments: [],
                 // Concurrency token — pass as expectedRevision to ofw_save_draft /
                 // ofw_delete_draft / ofw_send_message to assert you are acting on
@@ -479,7 +502,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             // this call may have re-hit detail for view status, the message content
             // itself was not re-verified, so report the folder's cache freshness.
             const freshness = await buildFreshness(cache, { source: 'cache', folders: [row.folder] });
-            return jsonResponse({ ...withReadState(row), attachments, freshness });
+            return jsonResponse({ ...viewOne(view, 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
@@ -524,7 +547,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         const attachments = await cache.listAttachmentsForMessage(detail.id);
         // Fetched live from OFW in this call — current by construction.
         const freshness = await buildFreshness(cache, { source: 'live', folders: [folder] });
-        return jsonResponse({ ...withReadState(row), attachments, freshness });
+        return jsonResponse({ ...viewOne(view, withReadState(row)), attachments, freshness });
     });
     if (allowSend)
         server.registerTool('ofw_send_message', {
@@ -873,10 +896,14 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             size: z.number().int().min(1).describe('Drafts per page (default 50)').optional(),
             verify: z.boolean().describe('Default true: when the drafts cache is not verified-fresh, run a drafts sync first (cheap — one list page plus one detail per draft) so the response is server-confirmed in one call. Set false to serve straight from the local cache with no OFW requests.').optional(),
             autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
+            view: viewParam(MESSAGE_VIEWS, {
+                note: 'compact omits OurFamilyWizard\'s raw `listData` echo, which duplicates this draft\'s own id, subject, modifiedAt and recipients. `revision`, `draftKey` and `cacheStatus` are kept on both rungs.',
+            }),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
+        const view = resolveView(args.view, MESSAGE_VIEWS);
         const cache = cacheProvider();
         // Auto-verify (default on): drafts change rarely but INVISIBLY — a web-app
         // edit bumps no timestamp — so an aged cache used to answer "unverified,
@@ -975,7 +1002,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             payload.verifyNote = verifyNote;
         }
         payload.freshness = freshness;
-        payload.drafts = drafts;
+        payload.drafts = viewDrafts(view, drafts);
         return jsonResponse(payload);
     });
     if (allowDrafts)
@@ -1221,6 +1248,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             page: z.number().int().min(1).describe('Page (default 1)').optional(),
             size: z.number().int().min(1).describe('Per page (default 50)').optional(),
             autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
+            // No `view` here, deliberately. This tool never emitted a cache row: it
+            // builds a VERDICT list of `{id, subject, sentAt, unreadBy}`, which is
+            // already narrower than anything the compact projection would produce.
+            // A parameter offering a rung that changes nothing is the no-op schema
+            // `viewParam` exists to refuse.
         },
     }, async (args) => {
         const page = args.page ?? 1;

package/dist/tools/project.js

@@ -0,0 +1,196 @@
+import { projectOrRaw, pruneUndefined } from '@chrischall/mcp-utils';
+/**
+ * The compact projection (`docs` — fleet convention "Response shape", and
+ * `@chrischall/mcp-utils`' `view` vocabulary).
+ *
+ * A default `ofw_list_messages()` is 50 messages, and it used to weigh 135 KB
+ * — roughly 34,000 tokens for one call. Measured against a real 1,335-row
+ * cache, `listData` was 58% of that, and 78% of `listData` duplicated fields
+ * the same object already emitted at the top level:
+ *
+ * - `listData.date` is 421 bytes per message: ELEVEN pre-formatted renderings
+ *   of one timestamp (`displayDate`, `threeCharMonthWeekdayTimeNoYear`, …)
+ *   sitting beside the `sentAt` + `sentAtDisplay` that `timestamps.ts` already
+ *   derives — and `normalizeTimestampsInValue` then adds a twelfth inside it.
+ * - `listData.recipients[].user` carries eight fields per person, including
+ *   `color` and `displayInitials`, next to the three-field recipients the row
+ *   already normalised.
+ * - `listData.read` / `.showNeverViewed` are FORCED to agree with the derived
+ *   `read` before they are emitted (`withReadState`), so the copy cannot even
+ *   disagree usefully.
+ * - `listData.preview` is a truncation of the body in the same object.
+ *
+ * What compact keeps is everything a caller can act on. What it drops is what
+ * the response says twice, what is near-constant across every row, and what
+ * `folder` already answers. `full` returns the row untouched.
+ *
+ * There is no `raw` rung. A message here is ASSEMBLED — the list endpoint
+ * supplies `listData`, the detail GET supplies `body` and the real `viewedAt`,
+ * and `timestamps.ts` rewrites both — so there is no single upstream payload
+ * to hand back, and a `raw` that skipped normalisation would put naive local
+ * times back beside UTC ones on the one rung a caller reaches for when
+ * something already looks wrong.
+ */
+export const MESSAGE_VIEWS = ['compact', 'full'];
+const LABEL = 'ofw-mcp';
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+}
+/**
+ * Who sent it.
+ *
+ * `fromUser` is the empty string on all 1,335 rows of a real cache — inbox and
+ * sent alike — because OFW names the sender in the LIST payload's `author` and
+ * nowhere else. So this is not a nicety: deleting `listData` without promoting
+ * it would have taken the sender's name off every message, and compact is
+ * where a field that has never worked starts working.
+ */
+function senderOf(row) {
+    if (typeof row.fromUser === 'string' && row.fromUser !== '')
+        return row.fromUser;
+    const author = asRecord(asRecord(row.listData)?.author);
+    const name = author?.name;
+    return typeof name === 'string' && name !== '' ? name : null;
+}
+/**
+ * How many attachments — as a NUMBER, from a field OFW sends two ways (`1`, or
+ * `[]` on the nine live rows that have no files).
+ *
+ * `undefined` when OFW reported nothing, and the caller then sees no `files`
+ * key at all. Defaulting to 0 there would turn "we did not see a count" into
+ * "there are none", which is the shape that reads as a verified absence — the
+ * failure every guard in this server exists to prevent.
+ */
+function fileCountOf(row) {
+    const files = asRecord(row.listData)?.files;
+    if (typeof files === 'number')
+        return files;
+    if (Array.isArray(files))
+        return files.length;
+    return undefined;
+}
+/** Whether this message has been replied to. Varies on 442 of 1,335 live rows. */
+function repliedOf(row) {
+    const replied = asRecord(row.listData)?.replied;
+    return typeof replied === 'boolean' ? replied : undefined;
+}
+/**
+ * One cached message row, projected.
+ *
+ * Key order matches the row's, so a caller reading either rung sees the same
+ * fields in the same places. `undefined` values are dropped by
+ * `JSON.stringify`, which is how the optional keys above stay absent rather
+ * than becoming nulls that claim more than we know.
+ */
+export function compactMessage(row) {
+    const { listData: _drop, fromUser: _dropFrom, ...rest } = row;
+    // `pruneUndefined`, not just `JSON.stringify`'s own dropping of undefined:
+    // an optional field must be ABSENT from the object a test or an in-process
+    // caller inspects, not present-and-undefined. "We did not see a count" and
+    // "there are none" have to be different facts at every layer, not only after
+    // serialisation.
+    return pruneUndefined({
+        id: rest.id,
+        folder: rest.folder,
+        subject: rest.subject,
+        from: senderOf(row),
+        sentAt: rest.sentAt,
+        recipients: rest.recipients,
+        read: rest.read,
+        replied: repliedOf(row),
+        files: fileCountOf(row),
+        replyToId: rest.replyToId,
+        chainRootId: rest.chainRootId,
+        body: rest.body,
+        fetchedBodyAt: rest.fetchedBodyAt,
+        // Anything a TOOL added on top of the cache row — `attachments`,
+        // `revision`, `cacheStatus`, `serverConfirmed`, `freshness` — is kept
+        // wholesale. Those are this server's own answers, never OFW's echo, and a
+        // projection that dropped one would be removing the thing the caller
+        // asked for rather than the thing they got twice.
+        ...omitKnown(rest, MESSAGE_ROW_KEYS),
+    });
+}
+/**
+ * Each projector's OWN columns — the ones it names explicitly above — so the
+ * spread adds only what a tool supplied on top of the cache row.
+ *
+ * Two sets rather than one union. A shared set is the union of `MessageRow` and
+ * `DraftRow`, so each projector would silently swallow any tool-supplied extra
+ * that happened to be named after the OTHER shape's column: a message carrying
+ * a `modifiedAt`, a draft carrying a `folder`. Nothing supplies those today,
+ * which is exactly what makes it the kind of trap that is only found once
+ * something does — and it would have quietly contradicted the "kept wholesale"
+ * promise below.
+ */
+const MESSAGE_ROW_KEYS = new Set([
+    'id', 'folder', 'subject', 'sentAt', 'recipients', 'read', 'replyToId', 'chainRootId', 'body', 'fetchedBodyAt',
+]);
+const DRAFT_ROW_KEYS = new Set(['id', 'subject', 'recipients', 'replyToId', 'modifiedAt', 'body']);
+function omitKnown(rest, own) {
+    const out = {};
+    for (const [key, value] of Object.entries(rest))
+        if (!own.has(key))
+            out[key] = value;
+    return out;
+}
+/**
+ * One cached draft row, projected.
+ *
+ * `revision`, `draftKey` and `cacheStatus` are added by the tool rather than
+ * the cache and survive untouched — they are the concurrency token, the
+ * identity that outlives the create-then-delete churn, and the statement of
+ * whether a walk actually compared this row against OFW. Losing any of them to
+ * a projection would break every guarded write in this server.
+ */
+export function compactDraft(row) {
+    const { listData: _drop, ...rest } = row;
+    return pruneUndefined({
+        id: rest.id,
+        subject: rest.subject,
+        recipients: rest.recipients,
+        replyToId: rest.replyToId,
+        modifiedAt: rest.modifiedAt,
+        body: rest.body,
+        ...omitKnown(rest, DRAFT_ROW_KEYS),
+    });
+}
+/**
+ * Project a page of messages, or hand it back whole.
+ *
+ * The array is projected as ONE unit on purpose. Row-at-a-time would let a
+ * single unexpected row come back projected-to-nothing among 49 good ones —
+ * a hole in the middle of an answer, which is worse than a fat page and
+ * indistinguishable from a message with no content. It also means one stderr
+ * line per page rather than fifty.
+ */
+export function viewMessages(view, rows) {
+    if (view !== 'compact')
+        return rows;
+    return projectOrRaw(rows, (rs) => rs.map((r) => compactMessage(r)), {
+        label: LABEL,
+        context: 'the cached message rows',
+    });
+}
+/** As {@link viewMessages}, for drafts. */
+export function viewDrafts(view, rows) {
+    if (view !== 'compact')
+        return rows;
+    return projectOrRaw(rows, (rs) => rs.map((r) => compactDraft(r)), {
+        label: LABEL,
+        context: 'the cached draft rows',
+    });
+}
+/**
+ * One message, projected — `ofw_get_message`'s single-record path.
+ *
+ * Same fallback as the array form: a row this projector cannot read comes back
+ * whole. A detail read is the call a caller makes when they need everything
+ * about one message, so answering it with a record that has holes in it is the
+ * worst place in this server to get a projection wrong.
+ */
+export function viewOne(view, row) {
+    if (view !== 'compact')
+        return row;
+    return projectOrRaw(row, (r) => compactMessage(r), { label: LABEL, context: 'a cached message row' });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.14.0",
+  "version": "2.15.1",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -34,7 +34,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.19.3",
+    "@chrischall/mcp-utils": "^0.21.0",
     "@fetchproxy/bootstrap": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",

package/server.json

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

package/skills/ofw/SKILL.md

@@ -92,11 +92,11 @@ 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?, sort?, page?, size?, autoRefresh?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. `sort:"oldest"` starts at the old end of a range instead of paging to it (default `"newest"`). Returns `complete` for the RESULT SET plus **`nextPage`** (null when done) — and the paging keys come FIRST in the JSON, before `messages`. `returned` carries the record count as a scalar, beside `total`. An **empty** result from a non-fresh cache is refused (`UNVERIFIED_EMPTY`) — pass `autoRefresh:true` to sync and answer instead. |
-| `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_list_messages(folderId?, since?, until?, q?, sort?, page?, size?, autoRefresh?, view?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. `sort:"oldest"` starts at the old end of a range instead of paging to it (default `"newest"`). Returns `complete` for the RESULT SET plus **`nextPage`** (null when done) — and the paging keys come FIRST in the JSON, before `messages`. `returned` carries the record count as a scalar, beside `total`. An **empty** result from a non-fresh cache is refused (`UNVERIFIED_EMPTY`) — pass `autoRefresh:true` to sync and answer instead. |
+| `ofw_get_message(messageId, allowMarkRead?, view?)` | 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(draftId?, subject?, body?, recipientIds?, replyToId?, expectedRevision?, deleteDraftOnSuccess?, myFileIDs?, force?)` | Send a message — **the one irreversible operation**. Preferred path: pass `draftId` (+ `expectedRevision`) to send an existing draft **as it exists on the server** — the tool re-reads it from OFW first and refuses if it changed since you read it (or was already sent/deleted); `subject`/`body` become optional overrides. `recipientIds` is usually still required: OFW does not store recipients on drafts. After a **confirmed** send the draft is auto-deleted (`deleteDraftOnSuccess:false` to keep it); on any failure or ambiguity it is retained and the response says why (`draftRetained`). Response leads with `sentMessageId`, `draftKey`, `threaded`, `draftDeleted`. Compose from scratch by passing `subject`/`body`/`recipientIds` with no `draftId`. |
 | `ofw_get_unread_sent(page?, size?, autoRefresh?)` | Sent messages your co-parent hasn't read yet (from cache). Leads with `complete`/`hasMore`/`nextPage`, then `scanned`/`total`, then `unread`; an empty sent cache that is not fresh is refused rather than reported as "nothing sent". |
-| `ofw_list_drafts(page?, size?, verify?, autoRefresh?)` | Leads with `complete`/`hasMore`/`nextPage`; `drafts` comes last. List saved drafts, **auto-verified**: when the cache is not verified-fresh a cheap drafts sync runs first (default `verify:true`), so one call answers server-confirmed. `verify:false` serves straight from cache. Each draft carries `serverConfirmed`, `revision` and `draftKey`. Returns `complete` — **check it before saying "you have N drafts"**. See [Freshness](#freshness). |
+| `ofw_list_drafts(page?, size?, verify?, autoRefresh?, view?)` | Leads with `complete`/`hasMore`/`nextPage`; `drafts` comes last. List saved drafts, **auto-verified**: when the cache is not verified-fresh a cheap drafts sync runs first (default `verify:true`), so one call answers server-confirmed. `verify:false` serves straight from cache. Each draft carries `serverConfirmed`, `revision` and `draftKey`. Returns `complete` — **check it before saying "you have N drafts"**. See [Freshness](#freshness). |
 | `ofw_save_draft(subject, body, recipientIds?, messageId?, replyToId?, myFileIDs?, expectedRevision?, force?)` | 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 leads with `draftKey`, which stays the same across every edit — **track that, not the id**. Note: OFW does **not** store recipients on drafts — `recipientIds` are accepted but come back empty (a one-line NOTE says so; supply them at send time instead). Threading warnings fire only on genuine drops — a draft echoing `inReplyTo`/`showContext` IS threaded. |
 | `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`. |
@@ -125,6 +125,39 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 | `ofw_list_journal_entries(start?, max?)` | 1-based offset; default max 10 |
 | `ofw_create_journal_entry(title, body)` | Create a new entry |
 
+## Response shape (`view`)
+
+`ofw_list_messages`, `ofw_get_message` and `ofw_list_drafts` take
+`view: "compact" | "full"`, and **`compact` is the default** — you get the slim
+shape without asking. It measured 135.1 KB → 41.1 KB on a real 50-message page.
+
+What compact drops is `listData`, OFW's echo of the list payload. That blob was
+58% of the response and 78% of it duplicated fields the same object already
+emits at the top level — eleven pre-formatted renderings of one timestamp,
+eight fields per recipient beside the three the row already normalised, and a
+`preview` that is a truncation of the `body` in the same object.
+
+**Two things about compact that will surprise you if you don't know them:**
+
+- **The sender is `from`, not `fromUser`.** `fromUser` is the empty string on
+  every row — inbox and sent alike — because OFW names the sender only inside
+  `listData.author`. So compact promotes it. Dropping `listData` without that
+  would have taken the sender off every message; this is the one field the fat
+  blob was carrying alone.
+- **On a draft, `ofw_get_message` returns `from: null`** — a draft is unsent, so
+  there is no sender, and `""` would read as one we failed to find.
+
+Pass `view: "full"` when you need a field compact dropped — `listData` and
+everything in it. There is deliberately **no `raw` rung**: a message here is
+assembled from a list item, a detail GET and derived fields, so there is no
+single upstream payload to hand back, and a rung that skipped normalisation
+would put naive local times back beside UTC ones on exactly the rung you reach
+for when something already looks wrong.
+
+`ofw_get_unread_sent` takes no `view`: it emits a verdict list
+(`{id, subject, sentAt, unreadBy}`) that is already narrower than the
+projection.
+
 ## Freshness, completeness, and lifecycle
 
 Message and draft reads come from a local cache, so **a result can be stale without looking stale**. Three separate questions, three separate signals — do not substitute one for another: