ofw-mcp 2.0.4 → 2.0.6

package/dist/tools/messages.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { syncAll } from '../sync.js';
+import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, } from '../cache.js';
 export function registerMessageTools(server, client) {
     server.registerTool('ofw_list_message_folders', {
         description: 'List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.',
@@ -8,60 +10,146 @@ export function registerMessageTools(server, client) {
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('ofw_list_messages', {
-        description: 'List messages in an OurFamilyWizard folder. Call ofw_list_message_folders first to get folder IDs. Returns actual message content.',
+        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. Call ofw_sync_messages first if the cache is empty or stale.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            folderId: z.string().describe('Folder ID (get from ofw_list_message_folders)'),
+            folderId: z.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
             page: z.number().describe('Page number (default 1)').optional(),
             size: z.number().describe('Messages per page (default 50)').optional(),
+            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(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        const path = `/pub/v3/messages?folders=${encodeURIComponent(args.folderId)}&page=${page}&size=${size}&sort=date&sortDirection=desc`;
-        const data = await client.request('GET', path);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        const folderArg = args.folderId ?? 'both';
+        let folder;
+        if (folderArg === 'inbox')
+            folder = 'inbox';
+        else if (folderArg === 'sent')
+            folder = 'sent';
+        else if (folderArg === 'both')
+            folder = undefined;
+        else {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            messages: [],
+                            note: 'folderId must be "inbox", "sent", or "both". Numeric OFW folder IDs are not supported by the cache.',
+                        }, null, 2),
+                    }],
+            };
+        }
+        const filter = { folder, since: args.since, until: args.until, q: args.q };
+        const total = countMessages(filter);
+        const messages = 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.';
+        }
+        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.`;
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     });
     server.registerTool('ofw_get_message', {
-        description: 'Get a single OurFamilyWizard message by ID. Note: reading an unread message marks it as read.',
+        description: 'Get a single OurFamilyWizard message by ID. Reads from local cache when available; otherwise fetches from OFW (which will mark unread inbox messages as read on OFW).',
         annotations: { readOnlyHint: false },
         inputSchema: {
             messageId: z.string().describe('Message ID'),
         },
     }, async (args) => {
-        const data = await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        const id = Number(args.messageId);
+        const cached = getMessage(id);
+        if (cached && cached.body !== null) {
+            return { content: [{ type: 'text', text: JSON.stringify(cached, null, 2) }] };
+        }
+        const detail = await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`);
+        const recipients = (detail.recipients ?? []).map((r) => ({
+            userId: r.user.id, name: r.user.name, viewedAt: r.viewed?.dateTime ?? null,
+        }));
+        const folder = cached?.folder ?? 'inbox';
+        const row = {
+            id: detail.id,
+            folder,
+            subject: detail.subject,
+            fromUser: detail.from?.name ?? '',
+            sentAt: detail.date.dateTime,
+            recipients,
+            body: detail.body ?? '',
+            fetchedBodyAt: new Date().toISOString(),
+            replyToId: cached?.replyToId ?? null,
+            chainRootId: cached?.chainRootId ?? null,
+            listData: cached?.listData ?? detail,
+        };
+        upsertMessage(row);
+        return { content: [{ type: 'text', text: JSON.stringify(row, null, 2) }] };
     });
     server.registerTool('ofw_send_message', {
-        description: 'Send a message via OurFamilyWizard. If sending from a draft, pass draftId to automatically delete the draft after sending.',
+        description: 'Send a message via OurFamilyWizard. If sending from a draft, pass draftId to delete the draft after sending. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens).',
         annotations: { destructiveHint: true },
         inputSchema: {
             subject: z.string().describe('Message subject'),
             body: z.string().describe('Message body text'),
             recipientIds: z.array(z.number()).describe('Array of recipient user IDs (get from ofw_get_profile)'),
-            replyToId: z.number().describe('ID of the message being replied to. When provided, the original message thread is included (like a standard email reply).').optional(),
+            replyToId: z.number().describe('ID of the message being replied to').optional(),
             draftId: z.number().describe('ID of the draft to delete after sending (omit if not sending from a draft)').optional(),
         },
     }, async (args) => {
-        const replyToId = args.replyToId ?? null;
+        const requestedReplyTo = args.replyToId ?? null;
+        let resolvedReplyTo = requestedReplyTo;
+        let chainRootId = null;
+        let rewriteNote = null;
+        if (requestedReplyTo !== null) {
+            resolvedReplyTo = 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);
+            chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
+        }
         const data = await client.request('POST', '/pub/v3/messages', {
             subject: args.subject,
             body: args.body,
             recipientIds: args.recipientIds,
             attachments: { myFileIDs: [] },
             draft: false,
-            includeOriginal: replyToId !== null,
-            replyToId,
+            includeOriginal: resolvedReplyTo !== null,
+            replyToId: resolvedReplyTo,
         });
+        if (data && typeof data.id === 'number') {
+            const recipients = (data.recipients ?? []).map((r) => ({
+                userId: r.user.id, name: r.user.name, viewedAt: r.viewed?.dateTime ?? null,
+            }));
+            const row = {
+                id: data.id,
+                folder: 'sent',
+                subject: data.subject ?? args.subject,
+                fromUser: data.from?.name ?? '',
+                sentAt: data.date?.dateTime ?? new Date().toISOString(),
+                recipients,
+                body: data.body ?? args.body,
+                fetchedBodyAt: new Date().toISOString(),
+                replyToId: resolvedReplyTo,
+                chainRootId,
+                listData: data,
+            };
+            upsertMessage(row);
+        }
         if (args.draftId !== undefined) {
             const form = new FormData();
             form.append('messageIds', String(args.draftId));
             await client.request('DELETE', '/pub/v1/messages', form);
+            deleteDraft(args.draftId);
         }
-        return { content: [{ type: 'text', text: data ? JSON.stringify(data, null, 2) : 'Message sent successfully.' }] };
+        const text = data ? JSON.stringify(data, null, 2) : 'Message sent successfully.';
+        const finalText = rewriteNote ? `${rewriteNote}\n\n${text}` : text;
+        return { content: [{ type: 'text', text: finalText }] };
     });
     server.registerTool('ofw_list_drafts', {
-        description: 'List all draft messages in OurFamilyWizard',
+        description: 'List draft messages from the local OurFamilyWizard cache. Call ofw_sync_messages first if the cache is empty.',
         annotations: { readOnlyHint: true },
         inputSchema: {
             page: z.number().describe('Page number (default 1)').optional(),
@@ -70,39 +158,64 @@ export function registerMessageTools(server, client) {
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        // 13471259 is the system Drafts folder (folderType: DRAFTS)
-        const path = `/pub/v3/messages?folders=13471259&page=${page}&size=${size}&sort=date&sortDirection=desc`;
-        const data = await client.request('GET', path);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        const drafts = listDrafts({ page, size });
+        const payload = drafts.length === 0
+            ? { drafts: [], note: 'Cache empty. Call ofw_sync_messages to populate.' }
+            : { drafts };
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     });
     server.registerTool('ofw_save_draft', {
-        description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional — a draft can be saved without them. To update an existing draft, provide its messageId.',
+        description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. To update an existing draft, provide its messageId. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response).',
         annotations: { readOnlyHint: false },
         inputSchema: {
             subject: z.string().describe('Message subject'),
             body: z.string().describe('Message body text'),
             recipientIds: z.array(z.number()).describe('Array of recipient user IDs (optional for drafts)').optional(),
             messageId: z.number().describe('ID of an existing draft to update (omit to create a new draft)').optional(),
-            replyToId: z.number().describe('ID of the message this draft is replying to (omit for new messages)').optional(),
+            replyToId: z.number().describe('ID of the message this draft replies to').optional(),
         },
     }, async (args) => {
-        const replyToId = args.replyToId ?? null;
+        const requestedReplyTo = args.replyToId ?? null;
+        let resolvedReplyTo = requestedReplyTo;
+        let rewriteNote = null;
+        if (requestedReplyTo !== null) {
+            resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+            if (resolvedReplyTo !== requestedReplyTo) {
+                rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
+            }
+        }
         const payload = {
             subject: args.subject,
             body: args.body,
             recipientIds: args.recipientIds ?? [],
             attachments: { myFileIDs: [] },
             draft: true,
-            includeOriginal: replyToId !== null,
-            replyToId,
+            includeOriginal: resolvedReplyTo !== null,
+            replyToId: resolvedReplyTo,
         };
         if (args.messageId !== undefined)
             payload.messageId = args.messageId;
         const data = await client.request('POST', '/pub/v3/messages', payload);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        if (data && typeof data.id === 'number') {
+            const draft = {
+                id: data.id,
+                subject: data.subject ?? args.subject,
+                body: data.body ?? args.body,
+                recipients: (data.recipients ?? []).map((r) => ({
+                    userId: r.user.id, name: r.user.name, viewedAt: r.viewed?.dateTime ?? null,
+                })),
+                replyToId: data.replyToId ?? resolvedReplyTo,
+                modifiedAt: data.date?.dateTime ?? new Date().toISOString(),
+                listData: data,
+            };
+            upsertDraft(draft);
+        }
+        const text = data ? JSON.stringify(data, null, 2) : 'Draft saved.';
+        const finalText = rewriteNote ? `${rewriteNote}\n\n${text}` : text;
+        return { content: [{ type: 'text', text: finalText }] };
     });
     server.registerTool('ofw_delete_draft', {
-        description: 'Delete a draft message from OurFamilyWizard',
+        description: 'Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache.',
         annotations: { destructiveHint: true },
         inputSchema: {
             messageId: z.number().describe('Draft message ID to delete'),
@@ -111,49 +224,53 @@ export function registerMessageTools(server, client) {
         const form = new FormData();
         form.append('messageIds', String(args.messageId));
         const data = await client.request('DELETE', '/pub/v1/messages', form);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        deleteDraft(args.messageId);
+        return { content: [{ type: 'text', text: data ? JSON.stringify(data, null, 2) : 'Draft deleted.' }] };
     });
     server.registerTool('ofw_get_unread_sent', {
-        description: 'List sent messages that have not been read by one or more recipients. Fetches sent messages page by page and returns only those with unread recipients.',
+        description: 'List sent messages that have not been read by one or more recipients. Reads from local cache; call ofw_sync_messages first if cache is stale.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            page: z.number().describe('Page of sent messages to scan (default 1)').optional(),
-            size: z.number().describe('Number of sent messages per page, max 50 (default 20)').optional(),
+            page: z.number().describe('Page (default 1)').optional(),
+            size: z.number().describe('Per page (default 50)').optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
-        const size = args.size ?? 20;
-        // Step 1: find the sent folder
-        const foldersData = await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true');
-        const sentFolder = (foldersData.systemFolders ?? []).find((f) => f.folderType === 'SENT_MESSAGES');
-        if (!sentFolder)
-            throw new Error('Sent folder not found');
-        // Step 2: list sent messages (the list endpoint already includes per-recipient viewed status)
-        const listPath = `/pub/v3/messages?folders=${encodeURIComponent(sentFolder.id)}&page=${page}&size=${size}&sort=date&sortDirection=desc`;
-        const listData = await client.request('GET', listPath);
-        const messages = listData.data ?? [];
-        // Step 3: filter to unread using showNeverViewed (avoids N+1 detail fetches
-        // and the detail endpoint's inconsistent viewed field which can return null
-        // for read messages instead of the epoch sentinel the list endpoint uses)
+        const size = args.size ?? 50;
+        const sent = listMessages({ folder: 'sent', page, size });
+        if (sent.length === 0) {
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            note: 'Sent cache is empty. Call ofw_sync_messages to populate.',
+                        }, null, 2) }] };
+        }
         const unread = [];
-        for (const msg of messages) {
-            if (!msg.showNeverViewed)
-                continue;
-            const unreadRecipients = (msg.recipients ?? [])
-                .filter((r) => !r.viewed)
-                .map((r) => r.user.name);
-            if (unreadRecipients.length > 0) {
-                unread.push({
-                    id: msg.id,
-                    subject: msg.subject,
-                    sentAt: msg.date.dateTime,
-                    unreadBy: unreadRecipients,
-                });
+        for (const msg of sent) {
+            const unreadBy = msg.recipients.filter((r) => r.viewedAt === null).map((r) => r.name);
+            if (unreadBy.length > 0) {
+                unread.push({ id: msg.id, subject: msg.subject, sentAt: msg.sentAt, unreadBy });
             }
         }
         if (unread.length === 0) {
-            return { content: [{ type: 'text', text: JSON.stringify({ message: 'All scanned sent messages have been read.' }, null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            message: 'All scanned sent messages have been read.',
+                        }, null, 2) }] };
         }
         return { content: [{ type: 'text', text: JSON.stringify(unread, null, 2) }] };
     });
+    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).',
+        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(),
+        },
+    }, async (args) => {
+        const result = await syncAll(client, {
+            folders: args.folders,
+            fetchUnreadBodies: args.fetchUnreadBodies,
+            deep: args.deep,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -29,7 +29,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.2"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",

package/server.json

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