ofw-mcp 2.10.2 → 2.11.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/bundle.js

@@ -36996,6 +36996,17 @@ function classifyBridgeError(err) {
 }
 
 // node_modules/@fetchproxy/server/dist/ws-server.js
+function envWsPort() {
+  const raw = process.env.FETCHPROXY_WS_PORT;
+  if (raw === void 0 || raw.trim() === "")
+    return void 0;
+  if (!/^\d+$/.test(raw.trim()))
+    return void 0;
+  const port = Number(raw.trim());
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    return void 0;
+  return port;
+}
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
     super(message);
@@ -37243,7 +37254,7 @@ var FetchproxyServer = class {
       }
     }
     this.opts = {
-      port: opts.port ?? 37149,
+      port: opts.port ?? envWsPort() ?? 37149,
       host: opts.host ?? "127.0.0.1",
       serverName: opts.serverName,
       version: opts.version,
@@ -39074,7 +39085,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.10.2",
+  version: "2.11.0",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -41606,6 +41617,53 @@ async function buildInlineDelivery(input) {
 
 // src/tools/messages.ts
 import { basename as basename2, join as join6 } from "node:path";
+
+// src/tools/pagination.ts
+function pageState(input) {
+  const hasMore = input.page * input.size < input.total;
+  return { hasMore, nextPage: hasMore ? input.page + 1 : null };
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function recordArray(root) {
+  if (Array.isArray(root.data)) return root.data;
+  for (const value of Object.values(root)) {
+    if (Array.isArray(value)) return value;
+  }
+  return null;
+}
+function readUpstreamPaging(payload) {
+  const root = asRecord(payload);
+  const rows = root === null ? null : recordArray(root);
+  const meta3 = root === null ? null : asRecord(root.metadata);
+  const total = meta3 !== null && typeof meta3.totalElements === "number" && Number.isFinite(meta3.totalElements) ? meta3.totalElements : null;
+  const last = meta3 !== null && typeof meta3.last === "boolean" ? meta3.last : null;
+  return { returned: rows?.length ?? 0, total, last };
+}
+function offsetState(input) {
+  const last = input.last ?? null;
+  const consumed = input.start - input.base + input.returned;
+  const hasMore = last !== null ? !last : input.total !== null ? consumed < input.total : input.returned >= input.max;
+  return { hasMore, nextStart: hasMore ? input.start + input.max : null };
+}
+function withPaginationFirst(input) {
+  const body = asRecord(input.payload);
+  if (body === null) return null;
+  const scope = input.total !== null ? ` of ${input.total}` : "";
+  const head = {
+    hasMore: input.state.hasMore,
+    nextStart: input.state.nextStart,
+    start: input.start,
+    max: input.max,
+    returned: input.returned,
+    ...input.total !== null ? { total: input.total } : {},
+    paginationNote: input.state.hasMore ? `PARTIAL: this response holds ${input.returned} record(s) starting at ${input.start}${scope}. ${input.hint} Do not state a total or an absence from this response alone.` : `This response reaches the end of the list${scope === "" ? "" : ` (${input.total} record(s) in total)`}.`
+  };
+  return { ...head, ...body, ...head };
+}
+
+// src/tools/messages.ts
 var DateSchema = external_exports.looseObject({ dateTime: external_exports.string() });
 var SentDetailSchema = external_exports.looseObject({
   subject: external_exports.string().optional(),
@@ -41741,7 +41799,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     return jsonResponse({ folders: data, freshness });
   });
   server.registerTool("ofw_list_messages", {
-    description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based but if you know what you want (a date range, a topic), prefer the filters over walking pages \u2014 the cache may have 1000+ messages. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" \u2014 check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
+    description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based (1-based `page`) but if you know what you want (a date range, a topic), prefer the filters over walking pages \u2014 the cache may have 1000+ messages. Results are newest-first by default; `sort:"oldest"` starts at the old end of a range instead of paging to it. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" \u2014 check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
     annotations: { readOnlyHint: false },
     inputSchema: {
       folderId: external_exports.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
@@ -41750,11 +41808,13 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       since: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at >= since (inclusive)").optional(),
       until: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at < until (exclusive)").optional(),
       q: external_exports.string().describe("Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.").optional(),
+      sort: external_exports.enum(["newest", "oldest"]).describe('Result order: "newest" (default, newest first) or "oldest" (oldest first). This decides which end a truncated page keeps \u2014 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: external_exports.boolean().describe(AUTO_REFRESH_DESC).optional()
     }
   }, async (args) => {
     const page = args.page ?? 1;
     const size = args.size ?? 50;
+    const sort = args.sort ?? "newest";
     const folderArg = args.folderId ?? "both";
     let folder;
     if (folderArg === "inbox") folder = "inbox";
@@ -41780,7 +41840,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       isEmpty: (v) => v.total === 0,
       read: async () => {
         const total2 = await cache.countMessages(filter);
-        const messages2 = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
+        const messages2 = (await cache.listMessages({ ...filter, page, size, sort })).map((m) => withReadState(m));
         const freshness2 = await buildFreshness(cache, { source: "cache", folders });
         return { messages: messages2, total: total2, freshness: freshness2 };
       }
@@ -41797,7 +41857,19 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     const { messages, total, freshness } = value;
     const fullSlice = page === 1 && messages.length === total;
     const complete = fullSlice && freshness.staleness === "fresh" && freshness.historyComplete;
-    const payload = { messages, total, page, size, complete, freshness };
+    const { hasMore, nextPage } = pageState({ page, size, total });
+    const payload = {
+      complete,
+      hasMore,
+      nextPage,
+      // The honest record count, as a scalar and ahead of the array — a
+      // consumer never has to reach `messages` to learn how many came back.
+      returned: messages.length,
+      total,
+      page,
+      size,
+      sort
+    };
     if (!complete) {
       payload.completeNote = [
         !fullSlice ? `this page holds ${messages.length} of ${total} matching cached messages` : null,
@@ -41808,11 +41880,13 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     if (total === 0) {
       payload.note = 'No messages match these filters, and the cache IS verified-fresh for these folders \u2014 so this is a real "nothing matched", not a stale-cache artefact. If you expected results, relax the filters.';
     } else if (page * size < total) {
-      payload.note = `Showing ${(page - 1) * size + 1}\u2013${(page - 1) * size + messages.length} of ${total}. Increase 'page' to see more, or narrow with since/until/q.`;
+      payload.note = `Showing ${(page - 1) * size + 1}\u2013${(page - 1) * size + messages.length} of ${total}, ${sort} first. Increase 'page' to see more, narrow with since/until/q, or set sort:"${sort === "newest" ? "oldest" : "newest"}" to start from the other end.`;
     }
     if (refreshed) {
       payload.autoRefreshed = true;
     }
+    payload.freshness = freshness;
+    payload.messages = messages;
     return jsonResponse(payload);
   });
   server.registerTool("ofw_get_message", {
@@ -42259,7 +42333,16 @@ ${JSON.stringify(
     const { drafts, total, freshness, serverConfirmed } = value;
     const fullSlice = page === 1 && drafts.length === total;
     const complete = serverConfirmed && fullSlice;
-    const payload = { drafts, total, page, size, complete, freshness };
+    const { hasMore, nextPage } = pageState({ page, size, total });
+    const payload = {
+      complete,
+      hasMore,
+      nextPage,
+      returned: drafts.length,
+      total,
+      page,
+      size
+    };
     if (!complete) {
       payload.completeNote = [
         !fullSlice ? `this page holds ${drafts.length} of ${total} cached drafts` : null,
@@ -42278,6 +42361,8 @@ ${JSON.stringify(
     if (verifyNote !== null) {
       payload.verifyNote = verifyNote;
     }
+    payload.freshness = freshness;
+    payload.drafts = drafts;
     return jsonResponse(payload);
   });
   if (allowDrafts) server.registerTool("ofw_save_draft", {
@@ -42509,7 +42594,16 @@ ${text}` : text);
         unread.push({ id: msg.id, subject: msg.subject, sentAt: msg.sentAt, unreadBy });
       }
     }
-    const payload = { unread, scanned: sent.length, total, complete, freshness };
+    const { hasMore, nextPage } = pageState({ page, size, total });
+    const payload = {
+      complete,
+      hasMore,
+      nextPage,
+      total,
+      scanned: sent.length,
+      page,
+      size
+    };
     if (!complete) {
       payload.completeNote = `This verdict covers the ${sent.length} of ${total} cached sent messages on this page${freshness.staleness === "fresh" ? "" : `, from a cache that is "${freshness.staleness}"`}. It is not a statement about every message you have sent.`;
     }
@@ -42519,6 +42613,8 @@ ${text}` : text);
     if (refreshed) {
       payload.autoRefreshed = true;
     }
+    payload.freshness = freshness;
+    payload.unread = unread;
     return jsonResponse(payload);
   });
   if (allowDrafts) server.registerTool("ofw_upload_attachment", {
@@ -43037,17 +43133,27 @@ function registerExpenseTools(server, client2) {
     return jsonResponse(data);
   });
   server.registerTool("ofw_list_expenses", {
-    description: "List OurFamilyWizard expenses with pagination",
+    description: "List OurFamilyWizard expenses. Offset-paged via start/max. The response leads with its paging state \u2014 `hasMore` and `nextStart` (null when the list is exhausted) \u2014 BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an expense total or an absence from one page.",
     annotations: { readOnlyHint: true },
     inputSchema: {
-      start: external_exports.number().int().min(0).describe("Start offset (default 0)").optional(),
+      start: external_exports.number().int().min(0).describe("Start offset, 0-based (default 0). To continue a listing, pass the `nextStart` from the previous response.").optional(),
       max: external_exports.number().int().min(1).describe("Max results (default 20)").optional()
     }
   }, async (args) => {
     const start = args.start ?? 0;
     const max = args.max ?? 20;
     const data = await client2.request("GET", `/pub/v2/expense/expenses?start=${start}&max=${max}`);
-    return jsonResponse(data);
+    const { returned, total, last } = readUpstreamPaging(data);
+    const wrapped = withPaginationFirst({
+      state: offsetState({ start, max, returned, total, last, base: 0 }),
+      start,
+      max,
+      returned,
+      total,
+      hint: `Re-call ofw_list_expenses with start:${start + max}.`,
+      payload: data
+    });
+    return jsonResponse(wrapped ?? data);
   });
   if (allowWrites) server.registerTool("ofw_create_expense", {
     description: "Log a new expense in OurFamilyWizard",
@@ -43066,17 +43172,27 @@ function registerExpenseTools(server, client2) {
 function registerJournalTools(server, client2) {
   const allowWrites = getWriteMode() === "all";
   server.registerTool("ofw_list_journal_entries", {
-    description: "List OurFamilyWizard journal entries",
+    description: "List OurFamilyWizard journal entries. Offset-paged via start/max (1-based). The response leads with its paging state \u2014 `hasMore` and `nextStart` (null when the list is exhausted) \u2014 BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an entry count or an absence from one page.",
     annotations: { readOnlyHint: true },
     inputSchema: {
-      start: external_exports.number().int().min(1).describe("Start offset (default 1)").optional(),
+      start: external_exports.number().int().min(1).describe("Start offset, 1-based (default 1). To continue a listing, pass the `nextStart` from the previous response.").optional(),
       max: external_exports.number().int().min(1).describe("Max results (default 10)").optional()
     }
   }, async (args) => {
     const start = args.start ?? 1;
     const max = args.max ?? 10;
     const data = await client2.request("GET", `/pub/v1/journals?start=${start}&max=${max}`);
-    return jsonResponse(data);
+    const { returned, total, last } = readUpstreamPaging(data);
+    const wrapped = withPaginationFirst({
+      state: offsetState({ start, max, returned, total, last, base: 1 }),
+      start,
+      max,
+      returned,
+      total,
+      hint: `Re-call ofw_list_journal_entries with start:${start + max}.`,
+      payload: data
+    });
+    return jsonResponse(wrapped ?? data);
   });
   if (allowWrites) server.registerTool("ofw_create_journal_entry", {
     description: "Create a new journal entry in OurFamilyWizard",
@@ -43332,9 +43448,10 @@ var OFWCacheCore = class {
   listMessages(opts) {
     const { where, params } = buildMessageFilter(opts);
     const offset = (opts.page - 1) * opts.size;
+    const dir = opts.sort === "oldest" ? "ASC" : "DESC";
     const rows = this.db.all(
       `SELECT * FROM messages ${where}
-       ORDER BY sent_at DESC, id DESC
+       ORDER BY sent_at ${dir}, id ${dir}
        LIMIT ? OFFSET ?`,
       [...params, opts.size, offset]
     );
@@ -43721,7 +43838,7 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.10.2",
+  version: "2.11.0",
   // x-release-please-version
   deps: client,
   tools: [

package/dist/cache/store.js

@@ -261,8 +261,13 @@ export class OFWCacheCore {
     listMessages(opts) {
         const { where, params } = buildMessageFilter(opts);
         const offset = (opts.page - 1) * opts.size;
+        // Direction comes from a closed set of literals, never from caller input.
+        // `id` tiebreaks in the SAME direction as `sent_at` so paging stays a total
+        // order: rows sharing a timestamp keep a stable relative position, and none
+        // is skipped or repeated at a page boundary.
+        const dir = opts.sort === 'oldest' ? 'ASC' : 'DESC';
         const rows = this.db.all(`SELECT * FROM messages ${where}
-       ORDER BY sent_at DESC, id DESC
+       ORDER BY sent_at ${dir}, id ${dir}
        LIMIT ? OFFSET ?`, [...params, opts.size, offset]);
         return rows.map(rowFromDb);
     }

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.10.2', // x-release-please-version
+    version: '2.11.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/tools/expenses.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { jsonResponse } from './_shared.js';
+import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerExpenseTools(server, client) {
     // Expense writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
@@ -12,17 +13,34 @@ export function registerExpenseTools(server, client) {
         return jsonResponse(data);
     });
     server.registerTool('ofw_list_expenses', {
-        description: 'List OurFamilyWizard expenses with pagination',
+        description: 'List OurFamilyWizard expenses. Offset-paged via start/max. The response leads with its paging state — `hasMore` and `nextStart` (null when the list is exhausted) — BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an expense total or an absence from one page.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            start: z.number().int().min(0).describe('Start offset (default 0)').optional(),
+            start: z.number().int().min(0).describe('Start offset, 0-based (default 0). To continue a listing, pass the `nextStart` from the previous response.').optional(),
             max: z.number().int().min(1).describe('Max results (default 20)').optional(),
         },
     }, async (args) => {
         const start = args.start ?? 0;
         const max = args.max ?? 20;
         const data = await client.request('GET', `/pub/v2/expense/expenses?start=${start}&max=${max}`);
-        return jsonResponse(data);
+        // Paging state FIRST, records after — a partial read of a spilled response
+        // must reach "there are more" before it reaches the records. See
+        // src/tools/pagination.ts for why the order is load-bearing.
+        //
+        // OFW wraps these listings as {data, metadata} and its metadata carries a
+        // `last` boolean, so "is there another page" is answered by the server
+        // rather than inferred from a full page (verified live).
+        const { returned, total, last } = readUpstreamPaging(data);
+        const wrapped = withPaginationFirst({
+            state: offsetState({ start, max, returned, total, last, base: 0 }),
+            start, max, returned, total,
+            hint: `Re-call ofw_list_expenses with start:${start + max}.`,
+            payload: data,
+        });
+        // A payload that is not a plain object cannot carry the paging keys at all.
+        // Pass it through untouched rather than relocating it — an added field is
+        // never worth changing a response's top-level shape.
+        return jsonResponse(wrapped ?? data);
     });
     if (allowWrites)
         server.registerTool('ofw_create_expense', {

package/dist/tools/journal.js

@@ -1,14 +1,15 @@
 import { z } from 'zod';
 import { jsonResponse } from './_shared.js';
+import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerJournalTools(server, client) {
     // Journal writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
     const allowWrites = getWriteMode() === 'all';
     server.registerTool('ofw_list_journal_entries', {
-        description: 'List OurFamilyWizard journal entries',
+        description: 'List OurFamilyWizard journal entries. Offset-paged via start/max (1-based). The response leads with its paging state — `hasMore` and `nextStart` (null when the list is exhausted) — BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an entry count or an absence from one page.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            start: z.number().int().min(1).describe('Start offset (default 1)').optional(),
+            start: z.number().int().min(1).describe('Start offset, 1-based (default 1). To continue a listing, pass the `nextStart` from the previous response.').optional(),
             max: z.number().int().min(1).describe('Max results (default 10)').optional(),
         },
     }, async (args) => {
@@ -16,7 +17,24 @@ export function registerJournalTools(server, client) {
         const start = args.start ?? 1;
         const max = args.max ?? 10;
         const data = await client.request('GET', `/pub/v1/journals?start=${start}&max=${max}`);
-        return jsonResponse(data);
+        // Paging state FIRST, records after — a partial read of a spilled response
+        // must reach "there are more" before it reaches the records. See
+        // src/tools/pagination.ts for why the order is load-bearing.
+        //
+        // OFW wraps these listings as {data, metadata} and its metadata carries a
+        // `last` boolean, so "is there another page" is answered by the server
+        // rather than inferred from a full page (verified live).
+        const { returned, total, last } = readUpstreamPaging(data);
+        const wrapped = withPaginationFirst({
+            state: offsetState({ start, max, returned, total, last, base: 1 }),
+            start, max, returned, total,
+            hint: `Re-call ofw_list_journal_entries with start:${start + max}.`,
+            payload: data,
+        });
+        // A payload that is not a plain object cannot carry the paging keys at all.
+        // Pass it through untouched rather than relocating it — an added field is
+        // never worth changing a response's top-level shape.
+        return jsonResponse(wrapped ?? data);
     });
     if (allowWrites)
         server.registerTool('ofw_create_journal_entry', {

package/dist/tools/messages.js

@@ -10,6 +10,7 @@ import { getAllowMarkRead, getAttachmentsDir, getAutoRefreshStaleReads, getDefau
 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';
 // 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() });
@@ -254,7 +255,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         return jsonResponse({ folders: data, freshness });
     });
     server.registerTool('ofw_list_messages', {
-        description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
+        description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based (1-based `page`) but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Results are newest-first by default; `sort:"oldest"` starts at the old end of a range instead of paging to it. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
         annotations: { readOnlyHint: false },
         inputSchema: {
             folderId: z.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
@@ -263,11 +264,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             since: z.string().describe('ISO date or datetime — only messages with sent_at >= since (inclusive)').optional(),
             until: z.string().describe('ISO date or datetime — only messages with sent_at < until (exclusive)').optional(),
             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(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
+        const sort = args.sort ?? 'newest';
         const folderArg = args.folderId ?? 'both';
         let folder;
         if (folderArg === 'inbox')
@@ -303,7 +306,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 // can be stale (a message read after it was first scraped), so `read`
                 // is derived from the record's own `viewedAt`/`fetchedBodyAt` and
                 // `listData` is forced to agree — see withReadState.
-                const messages = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
+                const messages = (await cache.listMessages({ ...filter, page, size, sort })).map((m) => withReadState(m));
                 // Served from the local cache, so the result must say how old it is and
                 // whether anything vouches for it — a caller cannot state current state
                 // from this payload without either re-reading or surfacing the caveat.
@@ -328,7 +331,28 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // needs one boolean to check before saying "you have N messages".
         const fullSlice = page === 1 && messages.length === total;
         const complete = fullSlice && freshness.staleness === 'fresh' && freshness.historyComplete;
-        const payload = { messages, total, page, size, complete, freshness };
+        const { hasMore, nextPage } = pageState({ page, size, total });
+        // Key ORDER is load-bearing, not cosmetic. These responses are large enough
+        // that a client may spill them to a file and a script may pull out only the
+        // fields it thought to name — which is how a correct `complete:false` next
+        // to a correct `completeNote` was dropped, and a 60-of-391 slice was
+        // reported as "October 1-28 is unreachable". Paging state and freshness are
+        // emitted BEFORE `messages` so a head, a preview, or a truncated read hits
+        // "this is a slice, fetch page 2" before it hits the first message body.
+        // The bulk goes last. See tests asserting this order — a refactor that
+        // rebuilds this literal silently undoes it.
+        const payload = {
+            complete,
+            hasMore,
+            nextPage,
+            // The honest record count, as a scalar and ahead of the array — a
+            // consumer never has to reach `messages` to learn how many came back.
+            returned: messages.length,
+            total,
+            page,
+            size,
+            sort,
+        };
         if (!complete) {
             payload.completeNote = [
                 !fullSlice ? `this page holds ${messages.length} of ${total} matching cached messages` : null,
@@ -342,11 +366,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             payload.note = 'No messages match these filters, and the cache IS verified-fresh for these folders — so this is a real "nothing matched", not a stale-cache artefact. If you expected results, relax the filters.';
         }
         else if (page * size < total) {
-            payload.note = `Showing ${(page - 1) * size + 1}–${(page - 1) * size + messages.length} of ${total}. Increase 'page' to see more, or narrow with since/until/q.`;
+            payload.note = `Showing ${(page - 1) * size + 1}–${(page - 1) * size + messages.length} of ${total}, ${sort} first. Increase 'page' to see more, narrow with since/until/q, or set sort:"${sort === 'newest' ? 'oldest' : 'newest'}" to start from the other end.`;
         }
         if (refreshed) {
             payload.autoRefreshed = true;
         }
+        payload.freshness = freshness;
+        payload.messages = messages;
         return jsonResponse(payload);
     });
     server.registerTool('ofw_get_message', {
@@ -916,7 +942,18 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // against OFW inside the freshness window AND not a slice of a larger list.
         const fullSlice = page === 1 && drafts.length === total;
         const complete = serverConfirmed && fullSlice;
-        const payload = { drafts, total, page, size, complete, freshness };
+        const { hasMore, nextPage } = pageState({ page, size, total });
+        // Paging state and freshness ahead of the bulk — see the note in
+        // ofw_list_messages.
+        const payload = {
+            complete,
+            hasMore,
+            nextPage,
+            returned: drafts.length,
+            total,
+            page,
+            size,
+        };
         if (!complete) {
             payload.completeNote = [
                 !fullSlice ? `this page holds ${drafts.length} of ${total} cached drafts` : null,
@@ -937,6 +974,8 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (verifyNote !== null) {
             payload.verifyNote = verifyNote;
         }
+        payload.freshness = freshness;
+        payload.drafts = drafts;
         return jsonResponse(payload);
     });
     if (allowDrafts)
@@ -1226,7 +1265,20 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 unread.push({ id: msg.id, subject: msg.subject, sentAt: msg.sentAt, unreadBy });
             }
         }
-        const payload = { unread, scanned: sent.length, total, complete, freshness };
+        const { hasMore, nextPage } = pageState({ page, size, total });
+        // Paging state ahead of the bulk — see the note in ofw_list_messages. Note
+        // `unread` is a VERDICT list, not the scanned set: it is routinely empty
+        // while the scan itself is truncated, which is what `scanned`/`total`/
+        // `complete` are for.
+        const payload = {
+            complete,
+            hasMore,
+            nextPage,
+            total,
+            scanned: sent.length,
+            page,
+            size,
+        };
         if (!complete) {
             payload.completeNote = `This verdict covers the ${sent.length} of ${total} cached sent messages on this page${freshness.staleness === 'fresh' ? '' : `, from a cache that is "${freshness.staleness}"`}. It is not a statement about every message you have sent.`;
         }
@@ -1236,6 +1288,8 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (refreshed) {
             payload.autoRefreshed = true;
         }
+        payload.freshness = freshness;
+        payload.unread = unread;
         return jsonResponse(payload);
     });
     if (allowDrafts)

package/dist/tools/pagination.js

@@ -0,0 +1,120 @@
+/**
+ * Pagination state that survives lossy consumption.
+ *
+ * The failure this module exists to prevent: a correct response was ignored.
+ * Three wide date-range reads each returned `complete:false` alongside a `note`
+ * and a `completeNote` spelling out that the page held 60 of 391 and how to get
+ * the rest. The responses were large, so the client spilled them to a JSON file
+ * and a script pulled out `total` and `messages` — dropping every field that
+ * said "this is a slice". The caller then reported October 1-28 as unreachable.
+ *
+ * The tool cannot fix a cherry-picking script. It can stop being easy to
+ * cherry-pick wrongly, which is what these helpers encode:
+ *
+ *  - **State before bulk.** Callers place the paging/freshness keys ahead of the
+ *    data array, so a `head`, a truncated preview, or a partial read reaches
+ *    "this is 60 of 391" before it reaches the first message body. Key order in
+ *    JSON is free — an object literal's insertion order is what JSON.stringify
+ *    emits — so this costs nothing and is pure upside.
+ *  - **The remedy is a value, not an inference.** `complete:false` tells a
+ *    reader something is wrong; `nextPage: 2` tells it what to do. A reader that
+ *    understands neither prose nor booleans can still act on an integer.
+ *  - **The honest count is a scalar, not the array's length.** `returned` sits
+ *    in the header beside `total`, so a consumer never has to reach the array
+ *    to learn how many records came back.
+ */
+/**
+ * Compute paging state for a 1-based `page`/`size` read.
+ *
+ * `hasMore` is decided from the OFFSET, not from `returned < total`: on a page
+ * past the end of the result set, `returned` is 0 while `total` is large, and
+ * comparing those two would advertise a `nextPage` that returns nothing forever.
+ */
+export function pageState(input) {
+    const hasMore = input.page * input.size < input.total;
+    return { hasMore, nextPage: hasMore ? input.page + 1 : null };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Read the paging facts out of an OFW `{data, metadata}` list envelope. */
+function recordArray(root) {
+    // `data` is the envelope both endpoints actually use, so it wins outright.
+    // Falling back to the first array-valued key matters because the alternative
+    // is silently publishing `returned: 0` and a "reaches the end of the list"
+    // note ALONGSIDE real records — the precise shape of lie this file exists to
+    // prevent, reintroduced by a backend rename.
+    if (Array.isArray(root.data))
+        return root.data;
+    for (const value of Object.values(root)) {
+        if (Array.isArray(value))
+            return value;
+    }
+    return null;
+}
+export function readUpstreamPaging(payload) {
+    const root = asRecord(payload);
+    const rows = root === null ? null : recordArray(root);
+    const meta = root === null ? null : asRecord(root.metadata);
+    const total = meta !== null && typeof meta.totalElements === 'number' && Number.isFinite(meta.totalElements)
+        ? meta.totalElements
+        : null;
+    const last = meta !== null && typeof meta.last === 'boolean' ? meta.last : null;
+    return { returned: rows?.length ?? 0, total, last };
+}
+/**
+ * Compute paging state for a `start`/`max` read, best evidence first.
+ *
+ * OFW's own `metadata.last` is authoritative and used whenever present. Failing
+ * that, a reported total settles it. Failing both, a FULL page is treated as
+ * probably-more: the bias is one-directional on purpose, because a `nextStart`
+ * that returns an empty page costs one wasted call, while a null that hides a
+ * further page reproduces the bug this file exists for — a slice narrated as
+ * the whole.
+ */
+export function offsetState(input) {
+    const last = input.last ?? null;
+    const consumed = input.start - input.base + input.returned;
+    const hasMore = last !== null
+        ? !last
+        : input.total !== null
+            ? consumed < input.total
+            : input.returned >= input.max;
+    return { hasMore, nextStart: hasMore ? input.start + input.max : null };
+}
+/**
+ * Prepend paging state to an OFW list envelope, renaming and dropping nothing.
+ *
+ * The upstream object is spread in BEHIND the paging keys, so every key it had
+ * stays exactly where a caller expects to find it — only the order changes.
+ * The head is then spread a SECOND time: a plain `{...head, ...body}` lets an
+ * upstream `hasMore`/`nextStart`/`paginationNote` overwrite the computed value
+ * while keeping the head's key position, which is worse than either — a paging
+ * field sitting in the paging slot, reading as ours, sourced from elsewhere.
+ * Re-spreading restores our values; keys keep their first-insertion position,
+ * so the order is unchanged.
+ * Returns null when the payload is not a plain object and therefore cannot
+ * carry sibling keys at all; the caller then passes it through untouched rather
+ * than relocating it, so this can never change a response's top-level shape.
+ */
+export function withPaginationFirst(input) {
+    const body = asRecord(input.payload);
+    if (body === null)
+        return null;
+    const scope = input.total !== null ? ` of ${input.total}` : '';
+    const head = {
+        hasMore: input.state.hasMore,
+        nextStart: input.state.nextStart,
+        start: input.start,
+        max: input.max,
+        returned: input.returned,
+        ...(input.total !== null ? { total: input.total } : {}),
+        paginationNote: input.state.hasMore
+            ? `PARTIAL: this response holds ${input.returned} record(s) starting at ${input.start}${scope}. `
+                + `${input.hint} Do not state a total or an absence from this response alone.`
+            : `This response reaches the end of the list${scope === '' ? '' : ` (${input.total} record(s) in total)`}.`,
+    };
+    return { ...head, ...body, ...head };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.10.2",
+  "version": "2.11.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.10.2",
+  "version": "2.11.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.10.2",
+      "version": "2.11.0",
       "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?, page?, size?, autoRefresh?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. Returns `complete` for the RESULT SET. An **empty** result from a non-fresh cache is refused (`UNVERIFIED_EMPTY`) — pass `autoRefresh:true` to sync and answer instead. |
+| `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_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). Reports `scanned`/`total`/`complete`; an empty sent cache that is not fresh is refused rather than reported as "nothing sent". |
-| `ofw_list_drafts(page?, size?, verify?, autoRefresh?)` | 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_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_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`. |
@@ -133,6 +133,7 @@ Message and draft reads come from a local cache, so **a result can be stale with
 |---|---|
 | How old is this data? | `freshness` — `staleness` (`fresh`/`unverified`/`stale`), `asOf`, `ageSeconds`, a quotable `warning` |
 | Is this the WHOLE answer? | `complete` on `ofw_list_messages` / `ofw_list_drafts` / `ofw_get_unread_sent` / `ofw_status` |
+| If not, how do I get the rest? | `nextPage` (message tools) or `nextStart` (`ofw_list_expenses` / `ofw_list_journal_entries`) — null means there is no more |
 | Is this entity still what I think it is? | `state` from `ofw_status` / `ofw_check_freshness` |
 
 Rules: