ofw-mcp 2.10.1 → 2.11.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.10.1"
+    "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.1",
+      "version": "2.11.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -124,17 +124,6 @@ Environment variables always take priority over the `.env` file. You can also pa
 OFW_USERNAME=you@example.com OFW_PASSWORD=yourpass node dist/index.js
 ```
 
-## Hosted connector (Cloudflare Worker)
-
-Instead of running `ofw-mcp` locally, you can add it to [claude.ai](https://claude.ai) as a **remote MCP connector** — a hosted Cloudflare Worker you reach from Settings → Connectors on Claude web, desktop, or mobile (connectors sync across all three). The same tool registrars back both targets, so the tools and behaviour are identical to the local stdio install; the Worker just wraps them with [`@chrischall/mcp-connector`](https://www.npmjs.com/package/@chrischall/mcp-connector) (the shared OAuth + streamable-HTTP harness) and a per-user [Durable Object](src/cache/durable.ts) cache in place of the local SQLite file.
-
-- **How you connect.** Each person you share the connector URL with logs in through the connector's own OAuth page with their **own** OurFamilyWizard email and password. Those credentials are stored (encrypted at rest) per user because OFW bearer tokens expire after ~6h with no refresh token, so the connector must be able to re-login on its own. One user can never see another's account or cache.
-- **Attachments are inline-only.** The Worker has no local filesystem, so `ofw_download_attachment` always returns content as MCP content blocks (`OFW_INLINE_ATTACHMENTS=true`) rather than writing to disk. Spreadsheets, PDFs and Office documents come back as extracted text/CSV, so they are readable even though the host cannot render the file itself.
-- **Write mode defaults to `all`.** The hosted connector registers every tool by default, configurable per deployment via `OFW_WRITE_MODE` / `OFW_CALENDAR_WRITES` in `wrangler.jsonc` — see [Write protection](#write-protection-ofw_write_mode).
-- **Message sync is bounded and resumable.** To stay under Cloudflare's per-request subrequest cap, `ofw_sync_messages` on the hosted connector caps how many OFW requests one call makes (`OFW_SYNC_MAX_REQUESTS` in `wrangler.jsonc`, default `40`) and resumes across calls, so a large mailbox backfills over multiple `ofw_sync_messages` calls rather than one; the local stdio server is unbounded. See [`docs/DEPLOY-CONNECTOR.md`](docs/DEPLOY-CONNECTOR.md#sync--the-subrequest-limit).
-
-Standing this up requires a Cloudflare account and is a one-time setup for whoever hosts it; after that the `deploy-connector` job in `release-please.yml` deploys each release automatically (and **Actions → deploy-connector → Run workflow** deploys any ref on demand) — see [`docs/DEPLOY-CONNECTOR.md`](docs/DEPLOY-CONNECTOR.md) for the full runbook. `wrangler.jsonc` serves the Worker at a custom domain (`https://connector.ofw.nullnet.app/mcp`) plus the account's `*.workers.dev` URL; whoever hosts it uses their own domain. The local stdio / `.mcpb` install above remains the desktop-only alternative if you'd rather run it against just your own account.
-
 ## Available tools
 
 Read-only tools run automatically. Write tools ask for your confirmation first. The *Write mode* column shows the minimum `OFW_WRITE_MODE` a tool needs to be available at all — see [Write protection](#write-protection-ofw_write_mode) below.

package/dist/auth-password.js

@@ -47,7 +47,7 @@ export async function loginWithPassword(username, password) {
         // OFW rejects bad credentials by re-serving its HTML login page (Spring
         // Security re-renders the form rather than returning 401/JSON). Surface a
         // clean, actionable message instead of dumping the HTML page — this is what
-        // the hosted connector's login page shows the user on a failed sign-in.
+        // a hosted deployment's login page shows the user on a failed sign-in.
         if (contentType.includes('text/html')) {
             throw new Error('OFW login failed — your OurFamilyWizard email or password was not accepted. Check them and try again.');
         }

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.1",
+  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)",
@@ -39103,10 +39114,7 @@ var package_default = {
     dev: "node --env-file=.env dist/index.js",
     test: "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "worker:dev": "wrangler dev",
-    "worker:deploy": "wrangler deploy",
-    "worker:test": "vitest run --config vitest.workers.config.ts"
+    "test:watch": "vitest"
   },
   dependencies: {
     "@chrischall/mcp-utils": "^0.14.0",
@@ -39116,17 +39124,11 @@ var package_default = {
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@chrischall/mcp-connector": "^1.1.1",
-    "@cloudflare/vitest-pool-workers": "^0.19.1",
-    "@cloudflare/workers-oauth-provider": "^0.8.1",
-    "@cloudflare/workers-types": "^5.20260708.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
-    agents: "^0.19.0",
     esbuild: "^0.28.0",
     typescript: "^7.0.2",
-    vitest: "^4.1.7",
-    wrangler: "^4.110.0"
+    vitest: "^4.1.7"
   }
 };
 
@@ -39232,7 +39234,7 @@ var OFWClient = class {
   // Optional injected auth resolver. When set, the refresh callback uses it
   // instead of the module-level global `resolveAuth` (env-var → fetchproxy
   // priority). A hosted per-user deployment injects its own resolver so each
-  // request carries that user's credentials — see the Cloudflare Worker
+  // request carries that user's credentials — see the per-user
   // deployment. Left undefined by the stdio path, which falls back to the
   // global resolver, keeping that behaviour byte-for-byte identical.
   authResolver;
@@ -41615,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(),
@@ -41750,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(),
@@ -41759,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";
@@ -41789,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 };
       }
@@ -41806,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,
@@ -41817,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", {
@@ -42268,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,
@@ -42287,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", {
@@ -42518,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.`;
     }
@@ -42528,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", {
@@ -43046,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",
@@ -43075,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",
@@ -43302,7 +43409,7 @@ var OFWCacheCore = class {
   }
   /**
    * Batch upsert every row in a single transaction — one round-trip's worth of
-   * work (crucial on the Durable Object backend, where each RPC is a subrequest).
+   * work (crucial where each round trip is a billed request).
    * Empty array is a no-op (no transaction opened).
    */
   upsertMessages(rows) {
@@ -43341,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]
     );
@@ -43445,8 +43553,8 @@ var OFWCacheCore = class {
     return r ? lineageFromDb(r) : null;
   }
   /**
-   * Batch read — one query for a whole page of drafts. On the Durable Object
-   * backend each cache call is a subrequest, so a per-draft lookup would spend
+   * Batch read — one query for a whole page of drafts. Where the cache is
+   * remote each cache call is a subrequest, so a per-draft lookup would spend
    * the caller's sync budget on bookkeeping.
    */
   getDraftLineageByIds(ids) {
@@ -43730,7 +43838,7 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.10.1",
+  version: "2.11.0",
   // x-release-please-version
   deps: client,
   tools: [

package/dist/cache/node.js

@@ -5,8 +5,8 @@ import { OFWCacheCore, LocalCacheStore } from './store.js';
 // The `node:sqlite` backend for the OFW message cache — a local on-disk SQLite
 // file used by the stdio/desktop server. The query logic lives in OFWCacheCore
 // (src/cache/store.ts); this file only adapts `node:sqlite` to the SqlDriver
-// surface and manages the file handle + permissions. (The hosted Cloudflare
-// connector uses a Durable Object backend instead — a later task.)
+// surface and manages the file handle + permissions. Another deployment can
+// adapt a different driver to the same surface.
 /** Adapts a `node:sqlite` DatabaseSync to the driver surface the core needs. */
 export class NodeSqlDriver {
     db;

package/dist/cache/store.js

@@ -3,9 +3,9 @@
 // All message reads (list/get/drafts/unread-sent) are served from this cache;
 // only ofw_sync_messages walks OFW for new content. The SQL lives here ONCE,
 // over a tiny synchronous {@link SqlDriver}, so the same schema/queries back
-// both engines: `node:sqlite` on the stdio/desktop server (src/cache/node.ts)
-// and a Durable Object's SQLite on the hosted Cloudflare connector (a later
-// task). This module imports nothing platform-specific.
+// any engine: `node:sqlite` is the one that ships (src/cache/node.ts), and
+// another deployment can adapt a different driver to the same surface. This
+// module imports nothing platform-specific.
 function rowFromDb(r) {
     return {
         id: r.id,
@@ -131,7 +131,7 @@ export const SCHEMA_STATEMENTS = [
  * every open. SQLite has no `ADD COLUMN IF NOT EXISTS`, so each statement runs
  * inside a try/catch — re-running against an already-migrated DB throws
  * "duplicate column name", which is swallowed. Driver-agnostic: both
- * `node:sqlite` and the Durable Object's SQLite raise synchronously.
+ * `node:sqlite` raises synchronously, as any conforming driver must.
  */
 export const MIGRATIONS = [
     // Resumable deep-sync cursor. Absent/NULL → SyncState.resumePage null.
@@ -222,7 +222,7 @@ export class OFWCacheCore {
     }
     /**
      * Batch upsert every row in a single transaction — one round-trip's worth of
-     * work (crucial on the Durable Object backend, where each RPC is a subrequest).
+     * work (crucial where each round trip is a billed request).
      * Empty array is a no-op (no transaction opened).
      */
     upsertMessages(rows) {
@@ -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);
     }
@@ -351,8 +356,8 @@ export class OFWCacheCore {
         return r ? lineageFromDb(r) : null;
     }
     /**
-     * Batch read — one query for a whole page of drafts. On the Durable Object
-     * backend each cache call is a subrequest, so a per-draft lookup would spend
+     * Batch read — one query for a whole page of drafts. Where the cache is
+     * remote each cache call is a subrequest, so a per-draft lookup would spend
      * the caller's sync budget on bookkeeping.
      */
     getDraftLineageByIds(ids) {
@@ -463,7 +468,7 @@ export class OFWCacheCore {
 }
 /**
  * Adapts a synchronous {@link OFWCacheCore} to the async {@link CacheStore}
- * interface. Used by the in-process node backend; the Durable Object backend
+ * interface. Used by the in-process node backend; a remote backend
  * implements CacheStore over a real RPC boundary instead.
  */
 export class LocalCacheStore {

package/dist/client.js

@@ -6,16 +6,16 @@ import { resolveAuth } from './auth.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
-// missing dotenv module. The try/catch additionally guards the Cloudflare
-// Worker runtime, where `import.meta.url` is undefined and
-// `fileURLToPath(undefined)` would otherwise throw at module init (Worker
+// missing dotenv module. The try/catch additionally guards a runtime where
+// `import.meta.url` is undefined and `fileURLToPath(undefined)` would
+// otherwise throw at module init (a failure at
 // startup validation) — there is no filesystem / .env to load there anyway.
 try {
     const dir = dirname(fileURLToPath(import.meta.url));
     await loadDotenvSafely({ path: join(dir, '..', '.env') });
 }
 catch {
-    /* v8 ignore next -- only reached in a non-Node runtime (Workers): no .env to load */
+    /* v8 ignore next -- only reached in a non-Node runtime: no .env to load */
 }
 // Parse a Content-Disposition header for a filename. Prefers RFC 6266
 // `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
@@ -69,7 +69,7 @@ export class OFWClient {
     // Optional injected auth resolver. When set, the refresh callback uses it
     // instead of the module-level global `resolveAuth` (env-var → fetchproxy
     // priority). A hosted per-user deployment injects its own resolver so each
-    // request carries that user's credentials — see the Cloudflare Worker
+    // request carries that user's credentials — see the per-user
     // deployment. Left undefined by the stdio path, which falls back to the
     // global resolver, keeping that behaviour byte-for-byte identical.
     authResolver;

package/dist/config.js

@@ -144,16 +144,16 @@ export function getAutoRefreshStaleReads() {
 }
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
-// MCP content blocks by default (skipping disk) — useful on sandboxed MCP
-// hosts where filesystem reads back to the model aren't available.
+// MCP content blocks by default (skipping disk) — necessary wherever the
+// caller cannot read the server's filesystem.
 export function getDefaultInlineAttachments() {
     return parseBoolEnv('OFW_INLINE_ATTACHMENTS');
 }
 /**
  * Per-invocation OFW-request budget for ofw_sync_messages.
  *
- * The hosted Cloudflare Worker connector enforces a subrequest cap per request
- * (every OFW API fetch and every Durable-Object cache RPC counts), so a deep
+ * A hosted deployment may enforce a request cap per call
+ * (every OFW API fetch and every cache round trip counts), so a deep
  * backfill must be bounded and resumable there. Set OFW_SYNC_MAX_REQUESTS to a
  * positive integer to cap the number of OFW requests one sync call may make
  * before pausing; the next call resumes the walk (deep or not) where it left off.

package/dist/extract/inflate.js

@@ -12,7 +12,7 @@
 // decompressed stream chunk by chunk, and abort the moment the running total
 // passes the limit. Peak memory is then bounded by the limit rather than by
 // whatever the file felt like claiming.
-/** 32 MiB. Sized to fit comfortably inside the Worker's memory budget. */
+/** 32 MiB. Sized to fit comfortably inside a constrained memory budget. */
 export const MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
 /**
  * Thrown when decompression is aborted for exceeding its cap. Distinct from a
@@ -31,7 +31,7 @@ export class DecompressionLimitError extends Error {
  *
  * `deflate-raw` is the ZIP member format; `deflate` is the zlib-wrapped form a
  * PDF `/FlateDecode` stream uses. Both go through the WHATWG
- * `DecompressionStream` so this runs unchanged on Node and workerd.
+ * `DecompressionStream` so this runs unchanged wherever the standard exists.
  */
 export async function inflateBounded(data, format, limit, label) {
     const stream = new Blob([data]).stream()

package/dist/extract/xml.js

@@ -2,7 +2,7 @@
 //
 // The office formats are machine-generated XML with a known, flat shape per
 // part (rows of cells, runs of text), so a scanning reader beats pulling in a
-// DOM parser that has to run in both Node and workerd. The one rule this file
+// DOM parser that has to run anywhere. The one rule this file
 // exists to enforce is that a tag match is anchored on the FULL tag name:
 // naively scanning for `<w:p` also matches `<w:pPr>`, which silently turns
 // paragraph properties into paragraphs.

package/dist/extract/zip.js

@@ -4,9 +4,10 @@
 // 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
+// `DecompressionStream` — a web standard available in Node ≥18 and in
+// sandboxed runtimes alike, so the
+// same code runs on the stdio server and a hosted deployment. Using
+// `node:zlib` here would tie this to Node; adding a userland inflate
 // dependency would bloat it. Neither is necessary.
 import { inflateBounded, MAX_DECOMPRESSED_BYTES } from './inflate.js';
 const EOCD_SIG = 0x06054b50;
@@ -16,7 +17,7 @@ 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.
+ * memory budget of a constrained runtime 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

package/dist/index.js

@@ -21,9 +21,9 @@ import { getCacheDbPath } from './config.js';
 import { NodeAttachmentIO } from './tools/attachments.js';
 // The stdio server backs the message cache with a local `node:sqlite` file,
 // opened lazily on first use (so the server still boots and answers the host's
-// install-time tools/list probe when no cache path is configured). The hosted
-// Cloudflare connector (a later task) injects a Durable-Object-backed
-// CacheStore + a filesystem-free AttachmentIO into the same registrar instead.
+// install-time tools/list probe when no cache path is configured). Both the
+// CacheStore and the AttachmentIO are injected, so a deployment with no usable
+// disk supplies its own implementations to the same registrar instead.
 let nodeCache;
 const nodeCacheProvider = () => (nodeCache ??= OFWCache.open(getCacheDbPath()));
 const nodeAttachmentIO = new NodeAttachmentIO();
@@ -35,7 +35,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.10.1', // x-release-please-version
+    version: '2.11.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -227,8 +227,8 @@ async function walkPages(client, folder, folderId, opts, store) {
             }
         }
         // 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.
+        // page held nothing new: where the cache is remote this call is a round
+        // trip, counting 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)
@@ -294,7 +294,7 @@ export async function syncMessageFolder(client, folder, folderId, opts, store) {
             // This was a real starvation bug. `fwd.nextPage` is just the start page
             // (1) when nothing was fetched, so the `Math.min` below would silently
             // reset a deep backfill — e.g. resumePage 87 → 1 — discarding 86 pages
-            // of progress. On the hosted Worker (OFW_SYNC_MAX_REQUESTS=40) a user
+            // of progress. Under a request budget (OFW_SYNC_MAX_REQUESTS) a user
             // with enough drafts to consume the whole budget, with drafts running
             // first, hit this on EVERY call: inbox/sent never got budget, their
             // cursor was reset every time, and the backfill could never advance.
@@ -502,7 +502,7 @@ export async function syncAll(client, opts, store) {
     // Drafts go FIRST. They are the only folder a destructive tool
     // (ofw_save_draft / ofw_delete_draft) reads as its base, and they are cheap
     // and bounded — one list page plus one detail per draft. Running them last,
-    // behind inbox and sent, meant a bounded call (the Worker's
+    // behind inbox and sent, meant a bounded call (the
     // OFW_SYNC_MAX_REQUESTS=40) spent its whole budget backfilling history and
     // deferred drafts on every single call, so server-side draft edits stayed
     // invisible indefinitely while the response reported `drafts: 0`.

package/dist/tools/attachments.js

@@ -4,8 +4,8 @@
 // writes downloaded bytes to disk (and reads them back for the inline-reuse
 // path). Those are the ONLY node:fs touch points in the message tools — they
 // live behind this {@link AttachmentIO} interface so the stdio server can use
-// the disk-backed {@link NodeAttachmentIO} while the hosted Cloudflare
-// connector (a later task) injects an inline, filesystem-free implementation.
+// the disk-backed {@link NodeAttachmentIO} while a deployment with no usable
+// disk injects an inline, filesystem-free implementation.
 // Keeping the interface here means src/tools/messages.ts imports nothing from
 // node:fs.
 import { readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs';

package/dist/tools/draft-freshness.js

@@ -7,7 +7,7 @@ export class DraftFreshnessError extends Error {
 // FNV-1a (64-bit) over a canonical encoding. Not cryptographic — this is a
 // change detector, and it is never the sole guard: an unsupplied token falls
 // back to a full field-by-field comparison against the cached base.
-// BigInt keeps it byte-identical on node and on the Workers runtime.
+// BigInt keeps it byte-identical across runtimes.
 const FNV_OFFSET = 0xcbf29ce484222325n;
 const FNV_PRIME = 0x100000001b3n;
 const MASK64 = 0xffffffffffffffffn;

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/lifecycle.js

@@ -164,10 +164,10 @@ function stateNote(state, cachedAsDraft, folderName) {
  * request for the map plus one per probed id.
  */
 export async function probeIds(client, store, ids, opts) {
-    // THREE cache reads for the whole batch, not three per id. On the Durable
-    // Object backend every cache call is a subrequest counting against the same
-    // hosting cap as the OFW fetches, so a per-id lookup would spend the caller's
-    // budget on bookkeeping before a single probe ran.
+    // THREE cache reads for the whole batch, not three per id. Where the cache
+    // is remote every call is a subrequest counting against the same hosting cap
+    // as the OFW fetches, so a per-id lookup would spend the caller's budget on
+    // bookkeeping before a single probe ran.
     const draftsById = new Map((await store.getDrafts(ids)).map((d) => [d.id, d]));
     const messagesById = new Map((await store.getMessages(ids)).map((m) => [m.id, m]));
     const prepared = ids.map((id) => {
@@ -294,9 +294,9 @@ export async function resolveDraftKey(store, draftKey) {
     return { currentId: chain[chain.length - 1].id, ids: chain.map((r) => r.id) };
 }
 /**
- * Mint a new stable draft identity. Uses the Web Crypto global, which both
- * Node ≥19 and the Workers runtime provide — a `node:crypto` import would not
- * bundle for the hosted connector.
+ * Mint a new stable draft identity. Uses the Web Crypto global, which Node ≥19
+ * provides natively — a `node:crypto` import would not bundle for a hosted
+ * deployment.
  */
 export function newDraftKey() {
     return `dk_${crypto.randomUUID()}`;

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() });
@@ -81,7 +82,7 @@ const FolderCountsSchema = z.looseObject({
 /**
  * Cap on per-id probes in one ofw_check_freshness call.
  *
- * Each id costs one OFW request, and on the hosted Worker every request counts
+ * Each id costs one OFW request, and under a request budget every one counts
  * against the subrequest cap (see OFW_SYNC_MAX_REQUESTS). The check has to stay
  * cheap enough that a caller reaches for it freely — that is the entire point
  * of it existing — so it truncates loudly rather than turning into a sync.
@@ -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', {
@@ -885,7 +911,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 const { freshness, serverConfirmed, cacheStatus } = await draftsFreshness(cache);
                 const rows = await cache.listDrafts({ page, size });
                 const total = await cache.countDrafts();
-                // One batch lookup for the whole page — on the Durable Object backend a
+                // One batch lookup for the whole page — where the cache is remote a
                 // per-draft lineage read would be a subrequest each.
                 const keyById = new Map((await cache.getDraftLineageByIds(rows.map((d) => d.id))).map((l) => [l.id, l.draftKey]));
                 // Every draft carries the concurrency token to echo back on a write, its
@@ -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)
@@ -1250,7 +1304,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             },
         }, async (args) => {
             // Resolve the upload source through the injected attachment-I/O boundary
-            // (disk read on node; an in-memory source on the hosted connector).
+            // (disk read on node; an in-memory source on a hosted deployment).
             const { blob, fileName, mimeType: mime, sizeBytes } = await attachmentIO.resolveUpload(args.path);
             // Build the multipart payload matching the OFW web UI's request shape.
             const form = new FormData();
@@ -1298,7 +1352,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         const fileId = args.fileId;
         const cache = cacheProvider();
         const requestedInline = args.inline ?? getDefaultInlineAttachments();
-        // When the deployment has no filesystem (hosted connector), inline is the
+        // When the deployment has no filesystem, inline is the
         // ONLY path to the bytes — force it rather than erroring on a disk write.
         // `forcedInline` records that we overrode an explicit `inline:false` so the
         // response is honest about it instead of silently ignoring the argument.

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.1",
+  "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)",
@@ -29,10 +29,7 @@
     "dev": "node --env-file=.env dist/index.js",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "worker:dev": "wrangler dev",
-    "worker:deploy": "wrangler deploy",
-    "worker:test": "vitest run --config vitest.workers.config.ts"
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@chrischall/mcp-utils": "^0.14.0",
@@ -42,16 +39,10 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@chrischall/mcp-connector": "^1.1.1",
-    "@cloudflare/vitest-pool-workers": "^0.19.1",
-    "@cloudflare/workers-oauth-provider": "^0.8.1",
-    "@cloudflare/workers-types": "^5.20260708.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
-    "agents": "^0.19.0",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.7",
-    "wrangler": "^4.110.0"
+    "vitest": "^4.1.7"
   }
 }

package/server.json

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

package/skills/ofw/SKILL.md

@@ -10,7 +10,6 @@ MCP server for OurFamilyWizard — provides read/write access to messages, calen
 - **npm:** [npmjs.com/package/ofw-mcp](https://www.npmjs.com/package/ofw-mcp)
 - **Source:** [github.com/chrischall/ofw-mcp](https://github.com/chrischall/ofw-mcp)
 
-> These tools are also available via the hosted [claude.ai](https://claude.ai) remote connector (a Cloudflare Worker) — the tool set and behaviour are identical to the local stdio install. See the repo's `docs/DEPLOY-CONNECTOR.md`.
 
 ## Setup
 
@@ -93,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`. |
@@ -134,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:

package/dist/ofw-auth.js

@@ -1,26 +0,0 @@
-import { loginWithPassword } from './auth-password.js';
-/**
- * `ConnectorAuth` for the OurFamilyWizard remote connector: the login page
- * collects the user's own OFW email/username + password, verifies them via the
- * same Spring Security form login the stdio server uses (`loginWithPassword` in
- * `auth-password.js`), and stores `{ username, password }` as the OAuth props
- * that `worker.ts`'s `buildClient` turns into a per-user `OFWClient` capable of
- * re-authenticating when its 6h token expires.
- */
-export const ofwAuth = {
-    service: 'OurFamilyWizard',
-    accent: '#00A9A5',
-    privacyNote: 'Your OFW email and password are stored encrypted and used only to sign in to OurFamilyWizard on your behalf ' +
-        '(OFW sign-in tokens expire every few hours, so your password is needed to renew them).',
-    fields: [
-        { name: 'username', label: 'OFW email or username' },
-        { name: 'password', label: 'OFW password', type: 'password' },
-    ],
-    async login(fields) {
-        // Verify the credentials up front — a bad password throws here, which the
-        // connector surfaces back on the login page. We deliberately discard the
-        // returned token: the per-user client logs in again from the stored creds.
-        await loginWithPassword(fields.username, fields.password);
-        return { username: fields.username, password: fields.password };
-    },
-};