ofw-mcp 2.4.3 → 2.5.0

package/dist/client.js

@@ -1,9 +1,8 @@
-import { loadDotenvSafely } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, parseBoolEnv, redactSecrets } from '@chrischall/mcp-utils';
 import { TokenManager } from '@chrischall/mcp-utils/session';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveAuth } from './auth.js';
-import { parseBoolEnv } from './config.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
@@ -32,13 +31,6 @@ function parseContentDispositionFilename(cd) {
 function debugLogEnabled() {
     return parseBoolEnv('OFW_DEBUG_LOG');
 }
-function redactHeaders(h) {
-    const out = { ...h };
-    /* v8 ignore next -- request headers always carry Authorization (set in request()); the guard is defensive for arbitrary header maps */
-    if (out.Authorization)
-        out.Authorization = `Bearer ${out.Authorization.slice(7, 17)}…`;
-    return out;
-}
 // Per-request timeout. Overridable via OFW_REQUEST_TIMEOUT_MS. The default
 // (30s) is comfortably above OFW's typical p99 but low enough that a stuck
 // upstream fails fast instead of burning the MCP client-side budget — which
@@ -148,7 +140,9 @@ export class OFWClient {
                     ? `<FormData entries=${Array.from(body.keys()).join(',')}>`
                     : JSON.stringify(body);
             console.error(`[ofw-debug] → ${method} ${url}${isRetry ? ' (retry)' : ''}`);
-            console.error(`[ofw-debug]   headers: ${JSON.stringify(redactHeaders(headers))}`);
+            // redactSecrets scrubs the Bearer token (and any other secret shapes)
+            // from the serialized header map — shared fleet redaction, never bespoke.
+            console.error(`[ofw-debug]   headers: ${redactSecrets(JSON.stringify(headers))}`);
             console.error(`[ofw-debug]   body: ${bodyPreview}`);
         }
         // AbortController + setTimeout (not AbortSignal.timeout) so vitest fake

package/dist/config.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { parseBoolEnv as parseBoolEnvUtil } from '@chrischall/mcp-utils';
+import { parseBoolEnv, readEnvVar } from '@chrischall/mcp-utils';
 // Cache identity drives the per-user SQLite DB filename. Order of preference:
 //   1. OFW_CACHE_IDENTITY — explicit override for users who want to label the
 //      cache themselves (e.g. when authing via fetchproxy and OFW_USERNAME is
@@ -11,13 +11,7 @@ import { parseBoolEnv as parseBoolEnvUtil } from '@chrischall/mcp-utils';
 //      Single-user installs are fine on this; multi-account users should set
 //      OFW_CACHE_IDENTITY explicitly so their caches don't collide.
 function readCacheIdentity() {
-    const explicit = process.env.OFW_CACHE_IDENTITY;
-    if (typeof explicit === 'string' && explicit.trim().length > 0)
-        return explicit.trim();
-    const username = process.env.OFW_USERNAME;
-    if (typeof username === 'string' && username.trim().length > 0)
-        return username.trim();
-    return '_default';
+    return readEnvVar('OFW_CACHE_IDENTITY') ?? readEnvVar('OFW_USERNAME') ?? '_default';
 }
 export function getCacheDir() {
     const override = process.env.OFW_CACHE_DIR;
@@ -41,19 +35,6 @@ export function getAttachmentsDir() {
     // location across macOS/Linux/Windows.
     return join(homedir(), 'Downloads', 'ofw-mcp');
 }
-/**
- * True when a boolean-shaped env var is set to "1", "true", "yes", or "on"
- * (case-insensitive, trimmed). Anything else — unset, empty, or other
- * values — is false. Used for OFW_INLINE_ATTACHMENTS, OFW_DISABLE_FETCHPROXY,
- * OFW_DEBUG_LOG, etc.
- *
- * Delegates to @chrischall/mcp-utils' `parseBoolEnv` (which also recognizes
- * the falsy set 0/false/no/off — behavior-equivalent here since callers only
- * care about the truthy case and everything else defaults to false).
- */
-export function parseBoolEnv(name) {
-    return parseBoolEnvUtil(name);
-}
 /**
  * Gate for write-tool registration, read at registration time (startup).
  *
@@ -80,6 +61,27 @@ export function getWriteMode() {
     console.error(`[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" — failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`);
     return 'none';
 }
+/**
+ * Calendar-write opt-in for 'drafts' deployments.
+ *
+ * Messages have a draft stage (the human sends from the web UI), so 'drafts'
+ * mode keeps a human between model output and the court-visible record.
+ * Calendar events have no draft stage — but unlike a sent message they are
+ * fully reversible (editable and deletable), so a drafts-mode user may accept
+ * direct calendar writes without accepting sends. Setting
+ * OFW_CALENDAR_WRITES=true registers the calendar write tools
+ * (ofw_create_event, ofw_update_event, ofw_delete_event) alongside the
+ * draft-level message writes.
+ *
+ * The flag never overrides 'none': that mode is the hard read-only guarantee,
+ * including the fail-closed result of an unrecognized OFW_WRITE_MODE.
+ */
+export function getCalendarWritesAllowed() {
+    const mode = getWriteMode();
+    if (mode === 'all')
+        return true;
+    return mode === 'drafts' && parseBoolEnv('OFW_CALENDAR_WRITES');
+}
 // 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

package/dist/index.js

@@ -24,7 +24,7 @@ import { registerJournalTools } from './tools/journal.js';
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.4.3', // x-release-please-version
+    version: '2.5.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -1,7 +1,7 @@
 import { setMeta, upsertMessage, getMessage, deleteMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
 import { z } from 'zod';
-import { ApiRecipientSchema, mapRecipients } from './tools/_shared.js';
-import { parseOFW } from './validate.js';
+import { ApiRecipientSchema, hasRealView, mapRecipients } from './tools/_shared.js';
+import { parseLenient } from '@chrischall/mcp-utils';
 // 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.
@@ -22,7 +22,7 @@ const FileMetaSchema = z.looseObject({
 // best-effort helper below; callers that need the result (download tool) let
 // the throw propagate.
 export async function fetchAttachmentMeta(client, fileId, messageId) {
-    const meta = parseOFW(FileMetaSchema, await client.request('GET', `/pub/v1/myfiles/${fileId}`), 'GET /pub/v1/myfiles/{fileId}');
+    const meta = parseLenient(FileMetaSchema, await client.request('GET', `/pub/v1/myfiles/${fileId}`), { label: 'ofw-mcp', context: 'GET /pub/v1/myfiles/{fileId}' });
     upsertAttachmentForMessage({
         fileId: meta.fileId ?? fileId,
         fileName: meta.fileName ?? `file-${fileId}`,
@@ -44,7 +44,7 @@ const FoldersSchema = z.looseObject({
     systemFolders: z.array(z.looseObject({ id: z.string(), folderType: z.string() })).optional(),
 });
 export async function resolveFolderIds(client) {
-    const data = parseOFW(FoldersSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), 'GET /pub/v1/messageFolders');
+    const data = parseLenient(FoldersSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), { label: 'ofw-mcp', context: 'GET /pub/v1/messageFolders' });
     const sys = data.systemFolders ?? [];
     const find = (type) => {
         const f = sys.find((x) => x.folderType === type);
@@ -75,6 +75,9 @@ const ListResponseSchema = z.looseObject({ data: z.array(ListItemSchema).optiona
 const DetailResponseSchema = z.looseObject({
     body: z.string().optional(),
     files: z.array(z.number()).optional(),
+    // The detail endpoint carries the REAL recipient view timestamps (the list
+    // endpoint only has an epoch placeholder) — used by the view-status refresh.
+    recipients: z.array(ApiRecipientSchema).optional(),
 });
 export async function syncMessageFolder(client, folder, folderId, opts) {
     let page = 1;
@@ -83,7 +86,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 = parseOFW(ListResponseSchema, await client.request('GET', path), `GET /pub/v3/messages?folders={${folder}}`);
+        const list = parseLenient(ListResponseSchema, await client.request('GET', path), { label: 'ofw-mcp', context: `GET /pub/v3/messages?folders={${folder}}` });
         const items = list.data ?? [];
         if (items.length === 0)
             break;
@@ -92,8 +95,21 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             if (newestId === null || item.id > newestId)
                 newestId = item.id;
             const existing = getMessage(item.id);
-            if (existing)
+            if (existing) {
+                // A sent message's read status changes AFTER it's first cached, when
+                // the recipient opens it — so we can't just skip existing rows. The
+                // list item carries the reliable `showNeverViewed` boolean but only an
+                // epoch placeholder for the timestamp; the real "First Viewed" time is
+                // on the detail endpoint. So when a sent message has flipped to read
+                // and we don't yet hold a real viewed time, re-fetch detail to capture
+                // it (no body re-fetch — only the recipient view fields can change).
+                if (folder === 'sent' && item.showNeverViewed === false && !hasRealView(existing.recipients)) {
+                    const detail = parseLenient(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (view-status refresh)' });
+                    upsertMessage({ ...existing, recipients: mapRecipients(detail.recipients), listData: item });
+                    synced++;
+                }
                 continue;
+            }
             pageHadNewItem = true;
             const isInboxUnread = folder === 'inbox' && item.showNeverViewed === true;
             const shouldFetchBody = !isInboxUnread || opts.fetchUnreadBodies;
@@ -101,7 +117,7 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             let fetchedBodyAt = null;
             let detailFileIds = [];
             if (shouldFetchBody) {
-                const detail = parseOFW(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), 'GET /pub/v3/messages/{id} (sync)');
+                const detail = parseLenient(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (sync)' });
                 body = detail.body ?? '';
                 fetchedBodyAt = new Date().toISOString();
                 if (Array.isArray(detail.files) && detail.files.length > 0) {
@@ -170,7 +186,7 @@ export async function syncDrafts(client, draftsFolderId) {
     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 list = parseLenient(DraftListResponseSchema, await client.request('GET', path), { label: 'ofw-mcp', context: 'GET /pub/v3/messages?folders={drafts}' });
         const pageItems = list.data ?? [];
         items.push(...pageItems);
         if (pageItems.length < 50)
@@ -186,7 +202,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 = parseOFW(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), 'GET /pub/v3/messages/{id} (drafts sync)');
+        const detail = parseLenient(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: '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,6 +1,6 @@
 import { expandPath as expandPathUtil, rawTextResult, textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { parseOFW } from '../validate.js';
+import { parseLenient } from '@chrischall/mcp-utils';
 // 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;
@@ -15,13 +15,30 @@ export const ApiRecipientSchema = z.looseObject({
 });
 // 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.
+// save_draft).
+//
+// `viewedAt` is the recipient's true "First Viewed" time, or null if not yet
+// viewed. Only the DETAIL endpoint (/pub/v3/messages/{id}) carries a real
+// timestamp; the LIST endpoint returns an epoch-zero PLACEHOLDER
+// ("1970-01-01T00:00:00") in the SAME field even for read messages (on the
+// list, read status lives in `showNeverViewed`, not the timestamp). So treat
+// the epoch placeholder as "no real view time" — otherwise a list-sourced row
+// reports a bogus 1970 read time. A detail re-fetch is what fills in the truth.
 export function mapRecipients(items) {
-    return (items ?? []).map((r) => ({
-        userId: r.user?.id ?? 0,
-        name: r.user?.name ?? '',
-        viewedAt: r.viewed?.dateTime ?? null,
-    }));
+    return (items ?? []).map((r) => {
+        const dt = r.viewed?.dateTime;
+        const viewedAt = typeof dt === 'string' && !dt.startsWith('1970-01-01') ? dt : null;
+        return { userId: r.user?.id ?? 0, name: r.user?.name ?? '', viewedAt };
+    });
+}
+// True if any recipient has a *real* "First Viewed" time — i.e. present and
+// not the epoch-zero placeholder. After mapRecipients a fresh `viewedAt` is
+// only ever a real timestamp or null, but a cache row written by older code
+// (which trusted the list endpoint's `viewed`) may still hold the literal
+// "1970-01-01T00:00:00". Treating that as "not viewed" lets sync/get_message
+// re-fetch detail and self-heal the stale row to the real timestamp.
+export function hasRealView(recipients) {
+    return recipients.some((r) => r.viewedAt !== null && !r.viewedAt.startsWith('1970-01-01'));
 }
 // Expand a user-provided path: ~ → home, relative → absolute. Re-exports
 // @chrischall/mcp-utils' `expandPath`.
@@ -77,14 +94,23 @@ const PostMessagesResponseSchema = z.looseObject({
  * `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.
+ *
+ * The generic is parametrized on the schema's OUTPUT type `T`
+ * (`detailSchema: z.ZodType<T>`, `detail: T`) rather than on the schema
+ * type itself. This mirrors `parseLenient`'s own signature
+ * (`<T>(schema: ZodType<T>, …): T`) exactly, so `T` is inferred straight
+ * from the schema and flows into the return type with no `as` cast — the
+ * compiler verifies that `detail` matches `detailSchema`'s output. (A
+ * `<S extends z.ZodType>` constraint would widen the output to `unknown`
+ * and force a cast at this call site.)
  */
 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 raw = parseLenient(PostMessagesResponseSchema, await client.request('POST', '/pub/v3/messages', payload), { label: 'ofw-mcp', context: `POST /pub/v3/messages (${ctx})`, mode: '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 = parseOFW(detailSchema, await client.request('GET', `/pub/v3/messages/${id}`), `GET /pub/v3/messages/{id} (${ctx})`, 'strict');
+    const detail = parseLenient(detailSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: `GET /pub/v3/messages/{id} (${ctx})`, mode: 'strict' });
     return { id, detail, raw };
 }

package/dist/tools/calendar.js

@@ -1,9 +1,113 @@
 import { z } from 'zod';
 import { jsonResponse, textResponse } from './_shared.js';
-import { getWriteMode } from '../config.js';
+import { getCalendarWritesAllowed } from '../config.js';
+import { parseLenient } from '@chrischall/mcp-utils';
+// OFW's real event-write API (reverse-engineered from the web app bundle):
+//   POST   /pub/v3/events                       create — 201 with the full event
+//   GET    /pub/v3/events/{eventRecurrenceId}   detail
+//   PUT    /pub/v3/events/{eventRecurrenceId}   update — full payload, not a patch
+//   DELETE /pub/v3/events/{eventRecurrenceId}?includeFuture=<bool>
+// The id in every URL is `eventRecurrenceId` — the same value calendar
+// listings expose as `id`. (`eventId` in the response is a different,
+// internal identifier; never put it in a URL.)
+// Payload gotchas: dates are `YYYY-MM-DD` with separate `HH:mm` times;
+// privacy is `publicFlag` (true = shared with co-parent); parent ids must be
+// OMITTED when unset — the web form's "0" placeholders draw a 409
+// "Must be a parent" from the API.
+const ofwDate = z.looseObject({ dateTime: z.string() });
+const userRef = z.looseObject({ userId: z.number() });
+const eventDetailSchema = z.looseObject({
+    eventRecurrenceId: z.number(),
+    title: z.string(),
+    allDay: z.boolean(),
+    publicFlag: z.boolean(),
+    startDate: ofwDate,
+    endDate: ofwDate,
+    location: z.string().nullish(),
+    notes: z.string().nullish(),
+    reminderMinutes: z.number().nullish(),
+    children: z.array(userRef).nullish(),
+    eventParent: userRef.nullish(),
+    dropOffParent: userRef.nullish(),
+    pickUpParent: userRef.nullish(),
+});
+const eventWriteFields = {
+    startDate: z.string().describe('Start date YYYY-MM-DD'),
+    endDate: z.string().describe('End date YYYY-MM-DD (default: startDate)').optional(),
+    startTime: z.string().describe('Start time HH:mm, 24-hour (required unless allDay)').optional(),
+    endTime: z.string().describe('End time HH:mm, 24-hour (required unless allDay)').optional(),
+    allDay: z.boolean().optional(),
+    privateEvent: z.boolean().describe('true = visible only to you; default false = shared with co-parent').optional(),
+    location: z.string().optional(),
+    notes: z.string().optional(),
+    reminderMinutes: z.number().int().min(0).optional(),
+    children: z.array(z.number()).describe('Child userIds to tag (see ofw_get_profile)').optional(),
+    eventParentId: z.number().describe("userId of the parent the event is 'for'").optional(),
+    dropOffParentId: z.number().describe('userId of the drop-off parent').optional(),
+    pickUpParentId: z.number().describe('userId of the pick-up parent').optional(),
+};
+function buildEventPayload(a) {
+    const allDay = a.allDay ?? false;
+    if (!allDay && (!a.startTime || !a.endTime)) {
+        throw new Error('startTime and endTime (HH:mm) are required unless allDay is true');
+    }
+    const payload = {
+        title: a.title,
+        startDate: a.startDate,
+        endDate: a.endDate ?? a.startDate,
+        // The web form always sends times; for all-day events it uses 01:00/02:00
+        // placeholders that OFW ignores.
+        startTime: a.startTime ?? '01:00',
+        endTime: a.endTime ?? '02:00',
+        allDay,
+        publicFlag: !(a.privateEvent ?? false),
+    };
+    if (a.location)
+        payload.location = a.location;
+    if (a.notes)
+        payload.notes = a.notes;
+    if (a.reminderMinutes !== undefined)
+        payload.reminderMinutes = String(a.reminderMinutes);
+    // Omitted `children` PRESERVES existing tags on PUT; an explicit [] CLEARS
+    // them (verified live 2026-07-13) — so send the array whenever it's defined.
+    if (a.children !== undefined)
+        payload.children = a.children;
+    if (a.eventParentId !== undefined)
+        payload.eventParentId = String(a.eventParentId);
+    if (a.dropOffParentId !== undefined)
+        payload.dropOffParentId = String(a.dropOffParentId);
+    if (a.pickUpParentId !== undefined)
+        payload.pickUpParentId = String(a.pickUpParentId);
+    return payload;
+}
+// Map a detail response back onto write-args so ofw_update_event can send the
+// full payload OFW's PUT expects while the caller only names the changes.
+function detailToWriteArgs(d) {
+    const [startDate, startClock] = d.startDate.dateTime.split('T');
+    const [endDate, endClock] = d.endDate.dateTime.split('T');
+    return {
+        title: d.title,
+        startDate,
+        endDate,
+        startTime: (startClock ?? '01:00:00').slice(0, 5),
+        endTime: (endClock ?? '02:00:00').slice(0, 5),
+        allDay: d.allDay,
+        privateEvent: !d.publicFlag,
+        location: d.location ?? undefined,
+        notes: d.notes ?? undefined,
+        reminderMinutes: d.reminderMinutes ?? undefined,
+        // Untagged (nullish or empty) → undefined, so the merged PUT omits the
+        // field (omission preserves; only a CALLER-supplied [] should clear).
+        children: d.children?.length ? d.children.map((c) => c.userId) : undefined,
+        eventParentId: d.eventParent?.userId,
+        dropOffParentId: d.dropOffParent?.userId,
+        pickUpParentId: d.pickUpParent?.userId,
+    };
+}
 export function registerCalendarTools(server, client) {
-    // Calendar writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
-    const allowWrites = getWriteMode() === 'all';
+    // Calendar writes land on the court-visible record with no draft stage, but
+    // events are reversible — 'all' mode, or 'drafts' + OFW_CALENDAR_WRITES=true.
+    const allowWrites = getCalendarWritesAllowed();
     server.registerTool('ofw_list_events', {
         description: 'List OurFamilyWizard calendar events in a date range',
         annotations: { readOnlyHint: true },
@@ -19,53 +123,65 @@ export function registerCalendarTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_event', {
-            description: 'Create a calendar event in OurFamilyWizard',
+            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage.',
             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(),
+                ...eventWriteFields,
             },
         }, async (args) => {
-            const data = await client.request('POST', '/pub/v1/calendar/events', args);
-            return jsonResponse(data);
+            const raw = await client.request('POST', '/pub/v3/events', buildEventPayload(args));
+            const event = parseLenient(eventDetailSchema, raw, { label: 'ofw-mcp', context: 'POST /pub/v3/events', mode: 'strict' });
+            return jsonResponse({
+                note: `Event created. Use eventRecurrenceId ${event.eventRecurrenceId} as eventId for ofw_update_event/ofw_delete_event.`,
+                event,
+            });
         });
     if (allowWrites)
         server.registerTool('ofw_update_event', {
-            description: 'Update an existing OurFamilyWizard calendar event',
+            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update).',
             annotations: { destructiveHint: true },
             inputSchema: {
-                eventId: z.string(),
+                eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
                 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(),
+                startDate: eventWriteFields.startDate.optional(),
+                endDate: eventWriteFields.endDate,
+                startTime: eventWriteFields.startTime,
+                endTime: eventWriteFields.endTime,
+                allDay: eventWriteFields.allDay,
+                privateEvent: eventWriteFields.privateEvent,
+                location: eventWriteFields.location,
+                notes: eventWriteFields.notes,
+                reminderMinutes: eventWriteFields.reminderMinutes,
+                children: z.array(z.number()).describe('Child userIds to tag; pass [] to remove all child tags (omit to keep current tags)').optional(),
+                eventParentId: eventWriteFields.eventParentId,
+                dropOffParentId: eventWriteFields.dropOffParentId,
+                pickUpParentId: eventWriteFields.pickUpParentId,
             },
         }, async (args) => {
-            const { eventId, ...updateData } = args;
-            const data = await client.request('PUT', `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
-            return jsonResponse(data);
+            const { eventId, ...changes } = args;
+            const id = encodeURIComponent(eventId);
+            const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
+            const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId}`, mode: 'strict' });
+            const defined = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
+            const merged = { ...detailToWriteArgs(current), ...defined };
+            await client.request('PUT', `/pub/v3/events/${id}`, buildEventPayload(merged));
+            // PUT responses aren't documented — re-fetch the detail as authoritative state.
+            const rawAfter = await client.request('GET', `/pub/v3/events/${id}`);
+            const event = parseLenient(eventDetailSchema, rawAfter, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId} (post-update)`, mode: 'strict' });
+            return jsonResponse({ note: 'Event updated; returning re-fetched event state.', event });
         });
     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'),
+                eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
+                includeFuture: z.boolean().describe('For repeating events: also delete future occurrences (default false)').optional(),
             },
         }, async (args) => {
-            await client.request('DELETE', `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
+            const includeFuture = args.includeFuture ?? false;
+            await client.request('DELETE', `/pub/v3/events/${encodeURIComponent(args.eventId)}?includeFuture=${includeFuture}`);
             return textResponse(`Event ${args.eventId} deleted`);
         });
 }

package/dist/tools/messages.js

@@ -5,8 +5,8 @@ import { getAttachmentsDir, getDefaultInlineAttachments, getWriteMode } from '..
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
 import { fileBlob } from '@chrischall/mcp-utils';
-import { ApiRecipientSchema, expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
-import { parseOFW } from '../validate.js';
+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
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
 const DateSchema = z.looseObject({ dateTime: z.string() });
@@ -183,6 +183,32 @@ export function registerMessageTools(server, client) {
         }
         const cached = getMessage(id);
         if (cached && cached.body !== null) {
+            let row = cached;
+            // Refresh view status for a sent message we still believe is unviewed:
+            // the recipient may have opened it since the last sync, and the detail
+            // endpoint carries the real "First Viewed" timestamp (a list-synced row
+            // only knows the showNeverViewed boolean / epoch placeholder). Best-
+            // effort and one-way — once a real viewed time is cached we stop re-
+            // fetching. Sent-only: re-hitting an unread INBOX detail would mark it
+            // read on OFW.
+            if (cached.folder === 'sent' && !hasRealView(cached.recipients)) {
+                try {
+                    const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (view-status refresh)' });
+                    const recipients = mapRecipients(detail.recipients);
+                    // Keep the raw listData read-flag in step with the refreshed
+                    // recipients so `showNeverViewed` can't contradict `viewedAt`.
+                    // (Spreading a null/absent listData is a no-op, so no guard needed.)
+                    row = {
+                        ...cached,
+                        recipients,
+                        listData: { ...cached.listData, showNeverViewed: !hasRealView(recipients) },
+                    };
+                    upsertMessage(row);
+                }
+                catch {
+                    // Best-effort: fall back to the cached row on any fetch/parse error.
+                }
+            }
             let attachments = listAttachmentsForMessage(id);
             // Lazy attachment backfill. The list-endpoint payload (stored in
             // listData) hints at attachments via `files: <count>` but doesn't
@@ -191,9 +217,9 @@ export function registerMessageTools(server, client) {
             // attachments table is empty even though OFW has files. Re-hit
             // detail to harvest fileIds (idempotent: body is already cached so
             // OFW state isn't changing).
-            if (attachments.length === 0 && listDataHintsAtFiles(cached.listData)) {
+            if (attachments.length === 0 && listDataHintsAtFiles(row.listData)) {
                 try {
-                    const detail = parseOFW(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), 'GET /pub/v3/messages/{id} (attachment backfill)');
+                    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);
@@ -203,9 +229,9 @@ export function registerMessageTools(server, client) {
                     // Backfill is best-effort. Fall through with whatever we have.
                 }
             }
-            return jsonResponse({ ...cached, attachments });
+            return jsonResponse({ ...row, attachments });
         }
-        const detail = parseOFW(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), 'GET /pub/v3/messages/{id} (ofw_get_message)');
+        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';
         const row = {
             id: detail.id,
@@ -508,7 +534,7 @@ export function registerMessageTools(server, client) {
             form.append('label', args.label ?? fileName);
             form.append('fileName', fileName);
             form.append('shareClass', args.shareClass ?? 'PRIVATE');
-            const meta = parseOFW(UploadedFileSchema, await client.request('POST', '/pub/v3/myfiles/multipart', form), 'POST /pub/v3/myfiles/multipart (ofw_upload_attachment)', 'strict');
+            const meta = parseLenient(UploadedFileSchema, await client.request('POST', '/pub/v3/myfiles/multipart', form), { label: 'ofw-mcp', context: 'POST /pub/v3/myfiles/multipart (ofw_upload_attachment)', mode: 'strict' });
             // 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.
@@ -583,14 +609,19 @@ export function registerMessageTools(server, client) {
                         } }] };
         }
         let dest;
+        // The filename comes from OFW file metadata — i.e. it is controlled by the
+        // co-parent who uploaded the attachment. basename() it before interpolating
+        // into a path so a crafted `../…` name can't escape the target directory
+        // (the upload path at :549 already applies basename to its input).
+        const safeName = basename(cached.fileName);
         if (args.saveTo) {
             // Treat saveTo as a directory if it ends with a separator; otherwise as a full path.
             const isDirArg = args.saveTo.endsWith('/') || args.saveTo.endsWith('\\');
             const abs = expandPath(args.saveTo);
-            dest = isDirArg ? join(abs, `${fileId}-${cached.fileName}`) : abs;
+            dest = isDirArg ? join(abs, `${fileId}-${safeName}`) : abs;
         }
         else {
-            dest = join(getAttachmentsDir(), `${fileId}-${cached.fileName}`);
+            dest = join(getAttachmentsDir(), `${fileId}-${safeName}`);
         }
         if (!args.force && cached.downloadedPath === dest) {
             return jsonResponse({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -32,17 +32,17 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.10.3",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   }
 }