ofw-mcp 2.3.2 → 2.4.0

package/dist/sync.js

@@ -1,11 +1,28 @@
 import { setMeta, upsertMessage, getMessage, deleteMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
-import { mapRecipients } from './tools/_shared.js';
+import { z } from 'zod';
+import { ApiRecipientSchema, mapRecipients } from './tools/_shared.js';
+import { parseOFW } from './validate.js';
+// Each OFW message detail returns `files: [fileId, ...]`. We fetch the metadata
+// for each file id (cheap JSON call) so the model can see filenames/mime types
+// without downloading bytes. Bytes are pulled lazily by ofw_download_attachment.
+// All sync-path schemas are validated LENIENT (issue #83): a mismatch logs a
+// structured warning to stderr and the raw response flows on through the
+// existing `??` fallbacks — a small OFW backend change degrades gracefully
+// instead of bricking sync, but no longer silently. Loose objects keep
+// unknown keys, so cached `metadata`/`listData` blobs stay verbatim.
+const FileMetaSchema = z.looseObject({
+    fileId: z.number(),
+    label: z.string().optional(),
+    fileName: z.string().optional(),
+    fileType: z.string().optional(), // MIME
+    fileSize: z.number().optional(),
+});
 // Fetches OFW attachment metadata for one file id and writes it to the cache.
 // Throws on network/HTTP errors — callers in bulk-sync paths wrap this in the
 // best-effort helper below; callers that need the result (download tool) let
 // the throw propagate.
 export async function fetchAttachmentMeta(client, fileId, messageId) {
-    const meta = await client.request('GET', `/pub/v1/myfiles/${fileId}`);
+    const meta = parseOFW(FileMetaSchema, await client.request('GET', `/pub/v1/myfiles/${fileId}`), 'GET /pub/v1/myfiles/{fileId}');
     upsertAttachmentForMessage({
         fileId: meta.fileId ?? fileId,
         fileName: meta.fileName ?? `file-${fileId}`,
@@ -23,8 +40,11 @@ export async function fetchAttachmentMetaForMessage(client, messageId, fileIds)
     // attachment doesn't break the surrounding sync.
     await Promise.allSettled(fileIds.map((fid) => fetchAttachmentMeta(client, fid, messageId)));
 }
+const FoldersSchema = z.looseObject({
+    systemFolders: z.array(z.looseObject({ id: z.string(), folderType: z.string() })).optional(),
+});
 export async function resolveFolderIds(client) {
-    const data = await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true');
+    const data = parseOFW(FoldersSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), 'GET /pub/v1/messageFolders');
     const sys = data.systemFolders ?? [];
     const find = (type) => {
         const f = sys.find((x) => x.folderType === type);
@@ -40,6 +60,22 @@ export async function resolveFolderIds(client) {
     setMeta('drafts_folder_id', ids.drafts);
     return ids;
 }
+// Required fields are the ones the sync loop reads unguarded (id keys the
+// cache; showNeverViewed drives unread semantics — per CLAUDE.md it's the
+// only reliable unread indicator, so its disappearance must warn loudly).
+const ListItemSchema = z.looseObject({
+    id: z.number(),
+    subject: z.string(),
+    date: z.looseObject({ dateTime: z.string() }),
+    from: z.looseObject({ name: z.string().optional() }).optional(),
+    showNeverViewed: z.boolean(),
+    recipients: z.array(ApiRecipientSchema).optional(),
+});
+const ListResponseSchema = z.looseObject({ data: z.array(ListItemSchema).optional() });
+const DetailResponseSchema = z.looseObject({
+    body: z.string().optional(),
+    files: z.array(z.number()).optional(),
+});
 export async function syncMessageFolder(client, folder, folderId, opts) {
     let page = 1;
     let synced = 0;
@@ -47,7 +83,7 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
     const unread = [];
     while (true) {
         const path = `/pub/v3/messages?folders=${encodeURIComponent(folderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-        const list = await client.request('GET', path);
+        const list = parseOFW(ListResponseSchema, await client.request('GET', path), `GET /pub/v3/messages?folders={${folder}}`);
         const items = list.data ?? [];
         if (items.length === 0)
             break;
@@ -65,7 +101,7 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             let fetchedBodyAt = null;
             let detailFileIds = [];
             if (shouldFetchBody) {
-                const detail = await client.request('GET', `/pub/v3/messages/${item.id}`);
+                const detail = parseOFW(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), 'GET /pub/v3/messages/{id} (sync)');
                 body = detail.body ?? '';
                 fetchedBodyAt = new Date().toISOString();
                 if (Array.isArray(detail.files) && detail.files.length > 0) {
@@ -114,10 +150,33 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
     });
     return { synced, unread };
 }
+const DraftListItemSchema = z.looseObject({
+    id: z.number(),
+    subject: z.string(),
+    date: z.looseObject({ dateTime: z.string() }),
+    replyToId: z.number().nullable().optional(),
+    recipients: z.array(ApiRecipientSchema).optional(),
+});
+const DraftListResponseSchema = z.looseObject({ data: z.array(DraftListItemSchema).optional() });
+const DraftDetailSchema = z.looseObject({
+    body: z.string().optional(),
+    subject: z.string().optional(),
+});
 export async function syncDrafts(client, draftsFolderId) {
-    const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=1&size=50&sort=date&sortDirection=desc`;
-    const list = await client.request('GET', path);
-    const items = list.data ?? [];
+    // Walk every page. The reconciliation loop at the bottom deletes any
+    // cached draft that wasn't seen in the listing, so a partial walk would
+    // wrongly evict real drafts beyond the first page.
+    const items = [];
+    let page = 1;
+    while (true) {
+        const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
+        const list = parseOFW(DraftListResponseSchema, await client.request('GET', path), 'GET /pub/v3/messages?folders={drafts}');
+        const pageItems = list.data ?? [];
+        items.push(...pageItems);
+        if (pageItems.length < 50)
+            break;
+        page++;
+    }
     const seenIds = new Set();
     let synced = 0;
     for (const item of items) {
@@ -127,7 +186,7 @@ export async function syncDrafts(client, draftsFolderId) {
         // timestamp for drafts — direct UI edits don't bump it — so we can't
         // use it to skip the detail fetch. Always re-fetch; drafts are few.
         const existing = getDraft(item.id);
-        const detail = await client.request('GET', `/pub/v3/messages/${item.id}`);
+        const detail = parseOFW(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), 'GET /pub/v3/messages/{id} (drafts sync)');
         const row = {
             id: item.id,
             subject: detail.subject ?? item.subject ?? '(no subject)',

package/dist/tools/_shared.js

@@ -1,9 +1,18 @@
 import { expandPath as expandPathUtil, rawTextResult, textResult } from '@chrischall/mcp-utils';
+import { z } from 'zod';
+import { parseOFW } from '../validate.js';
 // Pretty-printed JSON tool result. Thin wrapper over @chrischall/mcp-utils'
 // `textResult` so the rest of the codebase keeps the local name.
 export const jsonResponse = textResult;
 // Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
 export const textResponse = rawTextResult;
+// OFW API shape for `recipients[]` on message/draft list and detail
+// responses. Used wherever we validate the response of a `/pub/v3/messages*`
+// call. Loose: unknown keys pass through (and survive into cached listData).
+export const ApiRecipientSchema = z.looseObject({
+    user: z.looseObject({ id: z.number().optional(), name: z.string().optional() }).optional(),
+    viewed: z.looseObject({ dateTime: z.string() }).nullable().optional(),
+});
 // Translates OFW API recipient shape into the cache's normalized Recipient.
 // Used wherever we surface or persist recipients (sync, get_message, send,
 // save_draft) — all five call sites had near-identical inline mappings.
@@ -17,6 +26,37 @@ export function mapRecipients(items) {
 // Expand a user-provided path: ~ → home, relative → absolute. Re-exports
 // @chrischall/mcp-utils' `expandPath`.
 export const expandPath = expandPathUtil;
+/**
+ * Best-effort check that OFW actually persisted what we posted. OFW's
+ * draft-update path is known to silently no-op while echoing success in the
+ * POST response, so callers re-GET the detail and compare it to what was
+ * sent. Containment (not equality) because OFW legitimately transforms
+ * content — replies get the original message appended to the body
+ * (includeOriginal) and may get a subject prefix. Returns a WARNING string
+ * when the persisted content can't be confirmed to contain what was sent,
+ * else null.
+ */
+export function verifyWriteLanded(kind, sent, persisted) {
+    const mismatches = [];
+    if (typeof persisted.subject !== 'string' || !persisted.subject.includes(sent.subject)) {
+        mismatches.push('subject');
+    }
+    if (typeof persisted.body !== 'string' || !persisted.body.includes(sent.body)) {
+        mismatches.push('body');
+    }
+    if (mismatches.length === 0)
+        return null;
+    return `WARNING: the ${kind} re-fetched from OFW does not contain the ${mismatches.join(' and ')} that was posted — OFW may have silently dropped or altered the write. Verify the ${kind} on ourfamilywizard.com before relying on it.`;
+}
+// POST /pub/v3/messages response: minimal, `{entityId: <id>}` or legacy
+// `{id: <id>}`, sometimes an empty body (→ null). Validated STRICT: a
+// mistyped id (e.g. entityId as a string) must throw rather than silently
+// degrade into the "unconfirmed send" path when the write actually landed.
+// Absence of both ids stays legal — callers handle it with a WARNING.
+const PostMessagesResponseSchema = z.looseObject({
+    id: z.number().optional(),
+    entityId: z.number().optional(),
+}).nullable();
 /**
  * POST a payload to /pub/v3/messages, then immediately GET the detail
  * endpoint for the resulting message id. This is the only correct way to
@@ -29,18 +69,22 @@ export const expandPath = expandPathUtil;
  *    when the server silently no-ops, so the GET is also how we verify
  *    the write landed (callers compare detail.body to args.body).
  *
+ * Both responses are validated STRICT against `detailSchema` / the POST
+ * schema (this is the write-verification boundary — issue #83); `ctx`
+ * names the calling tool in the error message.
+ *
  * Returns a discriminated union so callers can narrow with
  * `if (result.id !== null)`. When id is null (no id field in the
  * response — never observed in production, but defensive), `raw`
  * carries the POST response so the caller can still surface it.
  */
-export async function postMessageAndRefetch(client, payload) {
-    const raw = await client.request('POST', '/pub/v3/messages', payload);
+export async function postMessageAndRefetch(client, payload, detailSchema, ctx) {
+    const raw = parseOFW(PostMessagesResponseSchema, await client.request('POST', '/pub/v3/messages', payload), `POST /pub/v3/messages (${ctx})`, 'strict');
     const id = typeof raw?.id === 'number' ? raw.id
         : typeof raw?.entityId === 'number' ? raw.entityId
             : null;
     if (id === null)
         return { id: null, detail: null, raw };
-    const detail = await client.request('GET', `/pub/v3/messages/${id}`);
+    const detail = parseOFW(detailSchema, await client.request('GET', `/pub/v3/messages/${id}`), `GET /pub/v3/messages/{id} (${ctx})`, 'strict');
     return { id, detail, raw };
 }

package/dist/tools/calendar.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { jsonResponse, textResponse } from './_shared.js';
+import { getWriteMode } from '../config.js';
 export function registerCalendarTools(server, client) {
+    // Calendar writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
+    const allowWrites = getWriteMode() === 'all';
     server.registerTool('ofw_list_events', {
         description: 'List OurFamilyWizard calendar events in a date range',
         annotations: { readOnlyHint: true },
@@ -14,52 +17,55 @@ export function registerCalendarTools(server, client) {
         const data = await client.request('GET', `/pub/v1/calendar/${variant}?startDate=${encodeURIComponent(args.startDate)}&endDate=${encodeURIComponent(args.endDate)}`);
         return jsonResponse(data);
     });
-    server.registerTool('ofw_create_event', {
-        description: 'Create a calendar event in OurFamilyWizard',
-        annotations: { destructiveHint: false },
-        inputSchema: {
-            title: z.string(),
-            startDate: z.string().describe('ISO datetime string'),
-            endDate: z.string().describe('ISO datetime string'),
-            allDay: z.boolean().optional(),
-            location: z.string().optional(),
-            reminder: z.string().describe('Reminder setting (e.g. "1 hour before")').optional(),
-            privateEvent: z.boolean().optional(),
-            eventFor: z.string().describe('neither | parent1 | parent2').optional(),
-            dropOffParent: z.string().optional(),
-            pickUpParent: z.string().optional(),
-            children: z.array(z.number()).describe('Array of child IDs').optional(),
-        },
-    }, async (args) => {
-        const data = await client.request('POST', '/pub/v1/calendar/events', args);
-        return jsonResponse(data);
-    });
-    server.registerTool('ofw_update_event', {
-        description: 'Update an existing OurFamilyWizard calendar event',
-        annotations: { destructiveHint: true },
-        inputSchema: {
-            eventId: z.string(),
-            title: z.string().optional(),
-            startDate: z.string().optional(),
-            endDate: z.string().optional(),
-            allDay: z.boolean().optional(),
-            location: z.string().optional(),
-            reminder: z.string().optional(),
-            privateEvent: z.boolean().optional(),
-        },
-    }, async (args) => {
-        const { eventId, ...updateData } = args;
-        const data = await client.request('PUT', `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
-        return jsonResponse(data);
-    });
-    server.registerTool('ofw_delete_event', {
-        description: 'Delete an OurFamilyWizard calendar event',
-        annotations: { destructiveHint: true },
-        inputSchema: {
-            eventId: z.string().describe('Event ID to delete'),
-        },
-    }, async (args) => {
-        await client.request('DELETE', `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
-        return textResponse(`Event ${args.eventId} deleted`);
-    });
+    if (allowWrites)
+        server.registerTool('ofw_create_event', {
+            description: 'Create a calendar event in OurFamilyWizard',
+            annotations: { destructiveHint: false },
+            inputSchema: {
+                title: z.string(),
+                startDate: z.string().describe('ISO datetime string'),
+                endDate: z.string().describe('ISO datetime string'),
+                allDay: z.boolean().optional(),
+                location: z.string().optional(),
+                reminder: z.string().describe('Reminder setting (e.g. "1 hour before")').optional(),
+                privateEvent: z.boolean().optional(),
+                eventFor: z.string().describe('neither | parent1 | parent2').optional(),
+                dropOffParent: z.string().optional(),
+                pickUpParent: z.string().optional(),
+                children: z.array(z.number()).describe('Array of child IDs').optional(),
+            },
+        }, async (args) => {
+            const data = await client.request('POST', '/pub/v1/calendar/events', args);
+            return jsonResponse(data);
+        });
+    if (allowWrites)
+        server.registerTool('ofw_update_event', {
+            description: 'Update an existing OurFamilyWizard calendar event',
+            annotations: { destructiveHint: true },
+            inputSchema: {
+                eventId: z.string(),
+                title: z.string().optional(),
+                startDate: z.string().optional(),
+                endDate: z.string().optional(),
+                allDay: z.boolean().optional(),
+                location: z.string().optional(),
+                reminder: z.string().optional(),
+                privateEvent: z.boolean().optional(),
+            },
+        }, async (args) => {
+            const { eventId, ...updateData } = args;
+            const data = await client.request('PUT', `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
+            return jsonResponse(data);
+        });
+    if (allowWrites)
+        server.registerTool('ofw_delete_event', {
+            description: 'Delete an OurFamilyWizard calendar event',
+            annotations: { destructiveHint: true },
+            inputSchema: {
+                eventId: z.string().describe('Event ID to delete'),
+            },
+        }, async (args) => {
+            await client.request('DELETE', `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
+            return textResponse(`Event ${args.eventId} deleted`);
+        });
 }

package/dist/tools/expenses.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { jsonResponse } from './_shared.js';
+import { getWriteMode } from '../config.js';
 export function registerExpenseTools(server, client) {
+    // Expense writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
+    const allowWrites = getWriteMode() === 'all';
     server.registerTool('ofw_get_expense_totals', {
         description: 'Get OurFamilyWizard expense summary totals (owed/paid)',
         annotations: { readOnlyHint: true },
@@ -12,8 +15,8 @@ export function registerExpenseTools(server, client) {
         description: 'List OurFamilyWizard expenses with pagination',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            start: z.number().describe('Start offset (default 0)').optional(),
-            max: z.number().describe('Max results (default 20)').optional(),
+            start: z.number().int().min(0).describe('Start offset (default 0)').optional(),
+            max: z.number().int().min(1).describe('Max results (default 20)').optional(),
         },
     }, async (args) => {
         const start = args.start ?? 0;
@@ -21,15 +24,16 @@ export function registerExpenseTools(server, client) {
         const data = await client.request('GET', `/pub/v2/expense/expenses?start=${start}&max=${max}`);
         return jsonResponse(data);
     });
-    server.registerTool('ofw_create_expense', {
-        description: 'Log a new expense in OurFamilyWizard',
-        annotations: { destructiveHint: false },
-        inputSchema: {
-            amount: z.number().describe('Expense amount'),
-            description: z.string().describe('Expense description'),
-        },
-    }, async (args) => {
-        const data = await client.request('POST', '/pub/v2/expense/expenses', args);
-        return jsonResponse(data);
-    });
+    if (allowWrites)
+        server.registerTool('ofw_create_expense', {
+            description: 'Log a new expense in OurFamilyWizard',
+            annotations: { destructiveHint: false },
+            inputSchema: {
+                amount: z.number().describe('Expense amount'),
+                description: z.string().describe('Expense description'),
+            },
+        }, async (args) => {
+            const data = await client.request('POST', '/pub/v2/expense/expenses', args);
+            return jsonResponse(data);
+        });
 }

package/dist/tools/journal.js

@@ -1,12 +1,15 @@
 import { z } from 'zod';
 import { jsonResponse } from './_shared.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',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            start: z.number().describe('Start offset (default 1)').optional(),
-            max: z.number().describe('Max results (default 10)').optional(),
+            start: z.number().int().min(1).describe('Start offset (default 1)').optional(),
+            max: z.number().int().min(1).describe('Max results (default 10)').optional(),
         },
     }, async (args) => {
         // Journal API uses 1-based offset (unlike expenses which start at 0)
@@ -15,15 +18,16 @@ export function registerJournalTools(server, client) {
         const data = await client.request('GET', `/pub/v1/journals?start=${start}&max=${max}`);
         return jsonResponse(data);
     });
-    server.registerTool('ofw_create_journal_entry', {
-        description: 'Create a new journal entry in OurFamilyWizard',
-        annotations: { destructiveHint: false },
-        inputSchema: {
-            title: z.string().describe('Entry title'),
-            body: z.string().describe('Entry text content'),
-        },
-    }, async (args) => {
-        const data = await client.request('POST', '/pub/v1/journals', args);
-        return jsonResponse(data);
-    });
+    if (allowWrites)
+        server.registerTool('ofw_create_journal_entry', {
+            description: 'Create a new journal entry in OurFamilyWizard',
+            annotations: { destructiveHint: false },
+            inputSchema: {
+                title: z.string().describe('Entry title'),
+                body: z.string().describe('Entry text content'),
+            },
+        }, async (args) => {
+            const data = await client.request('POST', '/pub/v1/journals', args);
+            return jsonResponse(data);
+        });
 }