ofw-mcp 2.5.0 → 2.6.3

package/dist/tools/messages.js

@@ -1,10 +1,7 @@
 import { z } from 'zod';
 import { syncAll, fetchAttachmentMeta, fetchAttachmentMetaForMessage } from '../sync.js';
-import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, listAttachmentsForMessage, getAttachment, upsertAttachmentForMessage, markAttachmentDownloaded, getDraft, } from '../cache.js';
-import { getAttachmentsDir, getDefaultInlineAttachments, getWriteMode } from '../config.js';
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, extname, join } from 'node:path';
-import { fileBlob } from '@chrischall/mcp-utils';
+import { getAttachmentsDir, getDefaultInlineAttachments, getSyncMaxRequests, getWriteMode } from '../config.js';
+import { basename, join } from 'node:path';
 import { ApiRecipientSchema, expandPath, hasRealView, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
@@ -38,6 +35,10 @@ const MessageDetailSchema = z.looseObject({
     from: z.looseObject({ name: z.string().optional() }).optional(),
     files: z.array(z.number()).optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // The detail payload carries its own owning folder ({id, name}). We read the
+    // id to label a live-fetched message sent-vs-inbox instead of blindly
+    // defaulting to inbox — see the folder derivation in ofw_get_message.
+    folder: z.looseObject({ id: z.number() }).optional(),
 });
 // Attachment-backfill detail fetch reads only `files`.
 const DetailFilesSchema = z.looseObject({ files: z.array(z.number()).optional() });
@@ -51,33 +52,6 @@ const UploadedFileSchema = z.looseObject({
     sizeInBytes: z.number().optional(),
     shareClass: z.string().optional(),
 });
-// Lightweight mime sniff from extension. OFW re-derives mime from the filename
-// server-side anyway, so this is just a polite Content-Type for the Blob.
-const MIME_BY_EXT = {
-    '.pdf': 'application/pdf',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.heic': 'image/heic',
-    '.txt': 'text/plain',
-    '.md': 'text/markdown',
-    '.csv': 'text/csv',
-    '.html': 'text/html', '.htm': 'text/html',
-    '.json': 'application/json',
-    '.xml': 'application/xml',
-    '.doc': 'application/msword',
-    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    '.xls': 'application/vnd.ms-excel',
-    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    '.ppt': 'application/vnd.ms-powerpoint',
-    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-    '.zip': 'application/zip',
-    '.ics': 'text/calendar',
-};
-function mimeFromName(name) {
-    return MIME_BY_EXT[extname(name).toLowerCase()] ?? 'application/octet-stream';
-}
 // The list endpoint payload (cached as `listData`) reports attachments via
 // `files: <count>` (a number) — the actual fileIds only appear on the detail
 // endpoint as `files: [number, ...]`. Some intermediate shapes return an
@@ -92,7 +66,7 @@ function listDataHintsAtFiles(listData) {
         return ld.files.length > 0;
     return false;
 }
-export function registerMessageTools(server, client) {
+export function registerMessageTools(server, client, cacheProvider, attachmentIO) {
     // OFW_WRITE_MODE gate (see config.ts). Send lands on the court-visible
     // record, so it is 'all'-only; draft-level writes (save/delete drafts,
     // upload attachments) also register under 'drafts'. Read/sync/download
@@ -135,9 +109,10 @@ export function registerMessageTools(server, client) {
                 note: 'folderId must be "inbox", "sent", or "both". Numeric OFW folder IDs are not supported by the cache.',
             });
         }
+        const cache = cacheProvider();
         const filter = { folder, since: args.since, until: args.until, q: args.q };
-        const total = countMessages(filter);
-        const messages = listMessages({ ...filter, page, size });
+        const total = await cache.countMessages(filter);
+        const messages = await cache.listMessages({ ...filter, page, size });
         const payload = { messages, total, page, size };
         if (total === 0) {
             payload.note = 'No messages match these filters. If you expected results, check ofw_sync_messages was run, or relax the filters.';
@@ -155,13 +130,14 @@ export function registerMessageTools(server, client) {
         },
     }, async (args) => {
         const id = Number(args.messageId);
+        const cache = cacheProvider();
         // Draft routing: if this id is in the drafts cache, return a
         // MessageRow-shaped synthesis built from the draft. The drafts table
         // is the source of truth for draft bodies (sync keeps it fresh);
         // the messages-table cache for the same id is stale by construction
         // when ofw_get_message was called on a draft id before sync caught
         // up — see syncDrafts, which also evicts these stale rows.
-        const draftRow = getDraft(id);
+        const draftRow = await cache.getDraft(id);
         if (draftRow !== null) {
             return jsonResponse({
                 id: draftRow.id,
@@ -181,7 +157,7 @@ export function registerMessageTools(server, client) {
                 attachments: [],
             });
         }
-        const cached = getMessage(id);
+        const cached = await cache.getMessage(id);
         if (cached && cached.body !== null) {
             let row = cached;
             // Refresh view status for a sent message we still believe is unviewed:
@@ -203,13 +179,13 @@ export function registerMessageTools(server, client) {
                         recipients,
                         listData: { ...cached.listData, showNeverViewed: !hasRealView(recipients) },
                     };
-                    upsertMessage(row);
+                    await cache.upsertMessage(row);
                 }
                 catch {
                     // Best-effort: fall back to the cached row on any fetch/parse error.
                 }
             }
-            let attachments = listAttachmentsForMessage(id);
+            let attachments = await cache.listAttachmentsForMessage(id);
             // Lazy attachment backfill. The list-endpoint payload (stored in
             // listData) hints at attachments via `files: <count>` but doesn't
             // expose the fileIds — those live only on /pub/v3/messages/{id}.
@@ -221,8 +197,8 @@ export function registerMessageTools(server, client) {
                 try {
                     const detail = parseLenient(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (attachment backfill)' });
                     if (Array.isArray(detail.files) && detail.files.length > 0) {
-                        await fetchAttachmentMetaForMessage(client, id, detail.files);
-                        attachments = listAttachmentsForMessage(id);
+                        await fetchAttachmentMetaForMessage(client, id, detail.files, cache);
+                        attachments = await cache.listAttachmentsForMessage(id);
                     }
                 }
                 catch {
@@ -232,7 +208,20 @@ export function registerMessageTools(server, client) {
             return jsonResponse({ ...row, attachments });
         }
         const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (ofw_get_message)' });
-        const folder = cached?.folder ?? 'inbox';
+        // Derive the folder for a live-fetched message. A cached row (reached here
+        // only when its body was NULL) already knows its folder, so keep it.
+        // Otherwise use the detail's own folder id, matched against the sent folder
+        // id persisted by the last resolveFolderIds — a sent message must not be
+        // mislabeled 'inbox' (which would also hide it from ofw_get_unread_sent and
+        // a sent-scoped ofw_list_messages). When that mapping isn't known yet (no
+        // sync has run in this cache), fall back to 'inbox' as before.
+        let folder = cached?.folder ?? 'inbox';
+        if (!cached) {
+            const sentFolderId = await cache.getMeta('sent_folder_id');
+            if (sentFolderId !== null && detail.folder?.id != null && String(detail.folder.id) === sentFolderId) {
+                folder = 'sent';
+            }
+        }
         const row = {
             id: detail.id,
             folder,
@@ -246,11 +235,11 @@ export function registerMessageTools(server, client) {
             chainRootId: cached?.chainRootId ?? null,
             listData: cached?.listData ?? detail,
         };
-        upsertMessage(row);
+        await cache.upsertMessage(row);
         if (Array.isArray(detail.files) && detail.files.length > 0) {
-            await fetchAttachmentMetaForMessage(client, detail.id, detail.files);
+            await fetchAttachmentMetaForMessage(client, detail.id, detail.files, cache);
         }
-        const attachments = listAttachmentsForMessage(detail.id);
+        const attachments = await cache.listAttachmentsForMessage(detail.id);
         return jsonResponse({ ...row, attachments });
     });
     if (allowSend)
@@ -271,6 +260,7 @@ export function registerMessageTools(server, client) {
                 throw new Error(`messageId (${args.messageId}) and draftId (${args.draftId}) refer to different drafts; pass only one.`);
             }
             const draftRef = args.messageId ?? args.draftId;
+            const cache = cacheProvider();
             // Best-effort draft lookup: when draftRef points at a cached draft, use
             // its stored fields (including replyToId) as defaults for anything the
             // caller didn't supply. The "missing draft" case only matters when we
@@ -284,7 +274,7 @@ export function registerMessageTools(server, client) {
             let draftFound = false;
             if (draftRef !== undefined) {
                 draftLookupAttempted = true;
-                const draft = getDraft(draftRef);
+                const draft = await cache.getDraft(draftRef);
                 if (draft !== null) {
                     draftFound = true;
                     subject = subject ?? draft.subject;
@@ -312,11 +302,11 @@ export function registerMessageTools(server, client) {
             let chainRootId = null;
             let rewriteNote = null;
             if (requestedReplyTo !== null) {
-                resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+                resolvedReplyTo = await cache.findLatestReplyTip(requestedReplyTo);
                 if (resolvedReplyTo !== requestedReplyTo) {
                     rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
                 }
-                const parent = getMessage(resolvedReplyTo);
+                const parent = await cache.getMessage(resolvedReplyTo);
                 chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
             }
             const myFileIDs = args.myFileIDs ?? [];
@@ -346,13 +336,13 @@ export function registerMessageTools(server, client) {
                     chainRootId,
                     listData: detail,
                 };
-                upsertMessage(persisted);
+                await cache.upsertMessage(persisted);
                 // Link attached files to the new message in the attachments cache.
                 // We may not have full metadata if the upload happened in a prior
                 // session — fall back to what we know.
                 for (const fileId of myFileIDs) {
-                    const existing = getAttachment(fileId);
-                    upsertAttachmentForMessage({
+                    const existing = await cache.getAttachment(fileId);
+                    await cache.upsertAttachmentForMessage({
                         fileId,
                         fileName: existing?.fileName ?? `file-${fileId}`,
                         label: existing?.label ?? existing?.fileName ?? `file-${fileId}`,
@@ -375,7 +365,7 @@ export function registerMessageTools(server, client) {
             }
             else if (draftRef !== undefined) {
                 await deleteOFWMessages(client, [draftRef]);
-                deleteDraft(draftRef);
+                await cache.deleteDraft(draftRef);
             }
             const responseObj = persisted ?? raw;
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
@@ -392,7 +382,7 @@ export function registerMessageTools(server, client) {
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        const drafts = listDrafts({ page, size });
+        const drafts = await cacheProvider().listDrafts({ page, size });
         const payload = drafts.length === 0
             ? { drafts: [], note: 'Cache empty. Call ofw_sync_messages to populate.' }
             : { drafts };
@@ -411,11 +401,12 @@ export function registerMessageTools(server, client) {
                 myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment)').optional(),
             },
         }, async (args) => {
+            const cache = cacheProvider();
             const requestedReplyTo = args.replyToId ?? null;
             let resolvedReplyTo = requestedReplyTo;
             let rewriteNote = null;
             if (requestedReplyTo !== null) {
-                resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+                resolvedReplyTo = await cache.findLatestReplyTip(requestedReplyTo);
                 if (resolvedReplyTo !== requestedReplyTo) {
                     rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
                 }
@@ -451,13 +442,13 @@ export function registerMessageTools(server, client) {
                     modifiedAt: detail.date?.dateTime ?? new Date().toISOString(),
                     listData: detail,
                 };
-                upsertDraft(persisted);
+                await cache.upsertDraft(persisted);
                 // Replace-path: caller passed messageId, so they want the old draft
                 // gone. Delete it after the new one is safely created+cached.
                 if (args.messageId !== undefined && args.messageId !== newId) {
                     try {
                         await deleteOFWMessages(client, [args.messageId]);
-                        deleteDraft(args.messageId);
+                        await cache.deleteDraft(args.messageId);
                         replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.)`;
                     }
                     catch (e) {
@@ -479,7 +470,7 @@ export function registerMessageTools(server, client) {
             },
         }, async (args) => {
             const data = await deleteOFWMessages(client, [args.messageId]);
-            deleteDraft(args.messageId);
+            await cacheProvider().deleteDraft(args.messageId);
             return data ? jsonResponse(data) : textResponse('Draft deleted.');
         });
     server.registerTool('ofw_get_unread_sent', {
@@ -492,7 +483,7 @@ export function registerMessageTools(server, client) {
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        const sent = listMessages({ folder: 'sent', page, size });
+        const sent = await cacheProvider().listMessages({ folder: 'sent', page, size });
         if (sent.length === 0) {
             return jsonResponse({ note: 'Sent cache is empty. Call ofw_sync_messages to populate.' });
         }
@@ -519,16 +510,12 @@ export function registerMessageTools(server, client) {
                 description: z.string().describe('Description shown in OFW My Files (default: filename)').optional(),
             },
         }, async (args) => {
-            const abs = expandPath(args.path);
-            const stat = statSync(abs); // throws if missing
-            if (!stat.isFile())
-                throw new Error(`Not a file: ${abs}`);
-            const fileName = basename(abs);
-            const mime = mimeFromName(fileName);
+            // Resolve the upload source through the injected attachment-I/O boundary
+            // (disk read on node; an in-memory source on the hosted connector).
+            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();
-            // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
-            form.append('file', await fileBlob(abs, { type: mime }), fileName);
+            form.append('file', blob, fileName);
             form.append('source', 'message');
             form.append('description', args.description ?? fileName);
             form.append('label', args.label ?? fileName);
@@ -538,12 +525,12 @@ export function registerMessageTools(server, client) {
             // Cache metadata so subsequent ofw_get_message calls can surface it and
             // ofw_download_attachment can short-circuit. messageId is 0 (the
             // not-yet-linked sentinel) until a message actually references this file.
-            upsertAttachmentForMessage({
+            await cacheProvider().upsertAttachmentForMessage({
                 fileId: meta.fileId,
                 fileName: meta.fileName ?? fileName,
                 label: meta.label ?? args.label ?? fileName,
                 mimeType: meta.fileType ?? mime,
-                sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : stat.size,
+                sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : sizeBytes,
                 metadata: meta,
                 messageId: 0,
             });
@@ -551,7 +538,7 @@ export function registerMessageTools(server, client) {
                 fileId: meta.fileId,
                 fileName: meta.fileName ?? fileName,
                 mimeType: meta.fileType ?? mime,
-                sizeBytes: meta.sizeInBytes ?? stat.size,
+                sizeBytes: meta.sizeInBytes ?? sizeBytes,
                 shareClass: meta.shareClass ?? args.shareClass ?? 'PRIVATE',
                 note: 'Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it.',
             });
@@ -567,13 +554,14 @@ export function registerMessageTools(server, client) {
         },
     }, async (args) => {
         const fileId = args.fileId;
+        const cache = cacheProvider();
         const inline = args.inline ?? getDefaultInlineAttachments();
-        let cached = getAttachment(fileId);
+        let cached = await cache.getAttachment(fileId);
         if (!cached) {
             // Not in cache. Fetch metadata and store under the messageId=0
             // sentinel — gets re-linked if a message later references this file.
-            await fetchAttachmentMeta(client, fileId, 0);
-            cached = getAttachment(fileId);
+            await fetchAttachmentMeta(client, fileId, 0, cache);
+            cached = await cache.getAttachment(fileId);
             /* v8 ignore next -- fetchAttachmentMeta persists the row it just fetched; a still-null read here is an unreachable storage failure */
             if (!cached)
                 throw new Error(`failed to fetch metadata for fileId ${fileId}`);
@@ -584,10 +572,7 @@ export function registerMessageTools(server, client) {
             let mimeType = cached.mimeType;
             let fileName = cached.fileName;
             if (cached.downloadedPath) {
-                try {
-                    bytes = readFileSync(cached.downloadedPath);
-                }
-                catch { /* on-disk copy missing; fall through */ }
+                bytes = attachmentIO.readDownloaded(cached.downloadedPath);
             }
             if (bytes === null) {
                 const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
@@ -630,9 +615,8 @@ export function registerMessageTools(server, client) {
             });
         }
         const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, response.body);
-        markAttachmentDownloaded(fileId, dest);
+        attachmentIO.writeDownload(dest, response.body);
+        await cache.markAttachmentDownloaded(fileId, dest);
         return jsonResponse({
             fileId,
             path: dest,
@@ -642,19 +626,21 @@ export function registerMessageTools(server, client) {
         });
     });
     server.registerTool('ofw_sync_messages', {
-        description: 'Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps).',
+        description: 'Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note — call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true).',
         annotations: { readOnlyHint: false },
         inputSchema: {
             folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).describe('Folders to sync (default: all three)').optional(),
             fetchUnreadBodies: z.boolean().describe('If true, also fetch bodies for unread inbox messages (will mark them as read on OFW). Default false.').optional(),
             deep: z.boolean().describe('If true, walk every OFW page until empty regardless of cache state. Use to backfill gaps. Default false.').optional(),
+            maxRequests: z.number().int().min(1).describe('Maximum OFW requests this single call may make before pausing. When hit, the response reports done:false — call again with the same arguments to continue. Omit to use the server default (OFW_SYNC_MAX_REQUESTS, or unbounded on local installs).').optional(),
         },
     }, async (args) => {
         const result = await syncAll(client, {
             folders: args.folders,
             fetchUnreadBodies: args.fetchUnreadBodies,
             deep: args.deep,
-        });
+            maxRequests: args.maxRequests ?? getSyncMaxRequests(),
+        }, cacheProvider());
         return jsonResponse(result);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.5.0",
+  "version": "2.6.3",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -29,7 +29,10 @@
     "dev": "node --env-file=.env dist/index.js",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "worker:dev": "wrangler dev",
+    "worker:deploy": "wrangler deploy",
+    "worker:test": "vitest run --config vitest.workers.config.ts"
   },
   "dependencies": {
     "@chrischall/mcp-utils": "^0.13.0",
@@ -39,10 +42,16 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@chrischall/mcp-connector": "^0.1.0",
+    "@cloudflare/vitest-pool-workers": "^0.18.4",
+    "@cloudflare/workers-oauth-provider": "^0.0.11",
+    "@cloudflare/workers-types": "^5.20260708.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
+    "agents": "^0.17.3",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.7",
+    "wrangler": "^4.110.0"
   }
 }

package/server.json

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

package/skills/ofw/SKILL.md

@@ -10,6 +10,8 @@ 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
 
 ### Option A — Claude Code (direct MCP, no mcporter)