ofw-mcp 2.3.1 → 2.4.0

package/dist/cache.js

@@ -1,5 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, chmodSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { getCacheDbPath } from './config.js';
 let instance = null;
@@ -62,15 +62,33 @@ function migrate(db) {
     db.exec(SCHEMA_V2);
     db.prepare('INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run('schema_version', '2');
 }
+// The cache holds full co-parenting message history — keep it private to the
+// owning user. Modes are asserted on every open (not just creation): mkdirSync
+// `mode` and SQLite's default file mode only apply when the path is first
+// created, so a pre-existing dir/db keeps whatever (world-readable) mode it
+// had. The -wal/-shm siblings appear and disappear with WAL checkpoints, hence
+// the existence check.
+function enforceCachePermissions(dbPath) {
+    chmodSync(dirname(dbPath), 0o700);
+    chmodSync(dbPath, 0o600);
+    for (const sibling of [`${dbPath}-wal`, `${dbPath}-shm`]) {
+        if (existsSync(sibling))
+            chmodSync(sibling, 0o600);
+    }
+}
 export function openCache() {
     if (instance)
         return instance;
     const path = getCacheDbPath();
     mkdirSync(dirname(path), { recursive: true });
     const db = new DatabaseSync(path);
+    // First pass: lock down dir + db before WAL siblings exist.
+    enforceCachePermissions(path);
     db.exec('PRAGMA journal_mode = WAL');
     db.exec('PRAGMA foreign_keys = ON');
     migrate(db);
+    // Second pass: the migration writes created -wal/-shm — lock those down too.
+    enforceCachePermissions(path);
     instance = { db };
     return instance;
 }

package/dist/client.js

@@ -1,4 +1,5 @@
 import { loadDotenvSafely } 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';
@@ -51,12 +52,44 @@ function getRequestTimeoutMs() {
     const n = Number(raw.trim());
     return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
 }
+// Sentinel "refresh token" handed to the shared TokenManager. OFW has no
+// OAuth-style refresh token — every renewal re-runs the full `resolveAuth()`
+// (password POST or fetchproxy snapshot). The TokenManager only refuses to
+// refresh when its refresh token is `undefined`, so a non-empty placeholder
+// keeps the single-flight refresh path live; the refresh callback ignores it.
+const OFW_REFRESH_SENTINEL = 'ofw';
 export class OFWClient {
-    token = null;
-    tokenExpiry = null;
+    // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
+    // (proactive refresh inside the skew window, single-flight refresh so a burst
+    // of concurrent callers coalesces onto ONE `resolveAuth()`, and a 401-replay
+    // guarded against double-refresh). It is created lazily, seeded with an
+    // already-expired placeholder token so the first request drives the refresh
+    // callback — i.e. the original "log in on first request" behavior.
+    tokenManager;
+    getTokenManager() {
+        if (!this.tokenManager) {
+            this.tokenManager = new TokenManager({
+                initial: { accessToken: '', refreshToken: OFW_REFRESH_SENTINEL, expiresAt: 0 },
+                skewMs: OFW_TOKEN_EXPIRY_SKEW_MS,
+                // Map OFW's mint/refresh onto the refresh callback. `resolveAuth()`
+                // returns a token and a best-effort expiry; when the fetchproxy path
+                // can't supply one we fall back to the same 6h estimate the password
+                // path uses (the 401-replay covers a wrong guess). We re-arm the
+                // sentinel so the manager can refresh again later.
+                refresh: async () => {
+                    const { token, expiresAt } = await resolveAuth();
+                    return {
+                        accessToken: token,
+                        refreshToken: OFW_REFRESH_SENTINEL,
+                        expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime(),
+                    };
+                },
+            });
+        }
+        return this.tokenManager;
+    }
     async request(method, path, body) {
-        await this.ensureAuthenticated();
-        const response = await this.fetchWithRetry(method, path, body, 'application/json', false);
+        const response = await this.fetchAuthed(method, path, body, 'application/json');
         const text = await response.text();
         if (debugLogEnabled()) {
             console.error(`[ofw-debug] response body: ${text || '<empty>'}`);
@@ -65,23 +98,45 @@ export class OFWClient {
     }
     /** Like `request`, but returns the raw bytes plus Content-Type/-Disposition metadata. */
     async requestBinary(method, path) {
-        await this.ensureAuthenticated();
-        const response = await this.fetchWithRetry(method, path, undefined, 'application/octet-stream', false);
+        const response = await this.fetchAuthed(method, path, undefined, 'application/octet-stream');
         return {
             body: Buffer.from(await response.arrayBuffer()),
             contentType: response.headers.get('content-type'),
             suggestedFileName: parseContentDispositionFilename(response.headers.get('content-disposition') ?? ''),
         };
     }
-    // Single fetch+retry scaffold for both JSON and binary callers. Handles
-    // 401 (re-auth and replay once), 429 (wait 2s and replay once), and
-    // turns any other non-2xx into a thrown Error.
-    async fetchWithRetry(method, path, body, accept, isRetry) {
+    // Authenticated fetch for both JSON and binary callers. Auth (proactive
+    // refresh inside the skew window + one 401-replay, guarded against a
+    // double-refresh under concurrency) is delegated to the shared TokenManager's
+    // `withAuth`. The 429 wait-and-replay and the non-2xx → throw remain here.
+    async fetchAuthed(method, path, body, accept) {
+        // `withAuth` invokes `call` once, and again after a refresh on a 401. The
+        // second invocation is the replay — mark it `(retry)` in the debug log,
+        // preserving the prior bespoke-loop diagnostic.
+        let attempt = 0;
+        let response = await this.getTokenManager().withAuth((token) => this.fetchOnce(method, path, body, accept, token, attempt++ > 0));
+        if (response.status === 429) {
+            await new Promise((r) => setTimeout(r, 2000));
+            response = await this.getTokenManager().withAuth((token) => this.fetchOnce(method, path, body, accept, token, true));
+            if (response.status === 429)
+                throw new Error('Rate limited by OFW API');
+        }
+        if (!response.ok) {
+            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+        }
+        return response;
+    }
+    // A single OFW API fetch with the bearer token supplied by `withAuth`.
+    // Carries the per-request timeout (AbortController + setTimeout so vitest
+    // fake timers can drive it and we attach a clear error message) and the
+    // OFW_DEBUG_LOG instrumentation. Returns the raw Response — 401/429/non-2xx
+    // handling lives in the callers (`withAuth` and `fetchAuthed`).
+    async fetchOnce(method, path, body, accept, token, isRetry = false) {
         const isFormData = body instanceof FormData;
         const headers = {
             ...OFW_PROTOCOL_HEADERS,
             Accept: accept,
-            Authorization: `Bearer ${this.token}`,
+            Authorization: `Bearer ${token}`,
         };
         if (body !== undefined && !isFormData)
             headers['Content-Type'] = 'application/json';
@@ -131,46 +186,7 @@ export class OFWClient {
         if (debugLogEnabled()) {
             console.error(`[ofw-debug] ← ${response.status} ${response.statusText} (${Date.now() - startedAt}ms)`);
         }
-        if (response.status === 401 && !isRetry) {
-            this.token = null;
-            this.tokenExpiry = null;
-            await this.ensureAuthenticated();
-            return this.fetchWithRetry(method, path, body, accept, true);
-        }
-        if (response.status === 429) {
-            if (!isRetry) {
-                await new Promise((r) => setTimeout(r, 2000));
-                return this.fetchWithRetry(method, path, body, accept, true);
-            }
-            throw new Error('Rate limited by OFW API');
-        }
-        if (!response.ok) {
-            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
-        }
         return response;
     }
-    async ensureAuthenticated() {
-        if (!this.isTokenExpiredSoon())
-            return;
-        await this.login();
-    }
-    // Auth resolution is delegated to `./auth.ts`. This client doesn't care
-    // whether the token came from a password POST or from a one-shot
-    // fetchproxy session-snapshot — it just consumes the result.
-    //
-    // If `expiresAt` is missing (the fetchproxy path on a tab whose
-    // browser didn't persist tokenExpiry), we fall back to the same 6h
-    // estimate the password path uses. The 401-replay path covers us if
-    // the estimate is wrong.
-    async login() {
-        const { token, expiresAt } = await resolveAuth();
-        this.token = token;
-        this.tokenExpiry = expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS);
-    }
-    isTokenExpiredSoon() {
-        if (!this.token || !this.tokenExpiry)
-            return true;
-        return this.tokenExpiry.getTime() - Date.now() < OFW_TOKEN_EXPIRY_SKEW_MS;
-    }
 }
 export const client = new OFWClient();

package/dist/config.js

@@ -54,6 +54,32 @@ export function getAttachmentsDir() {
 export function parseBoolEnv(name) {
     return parseBoolEnvUtil(name);
 }
+/**
+ * Gate for write-tool registration, read at registration time (startup).
+ *
+ *   none    No write tools are registered — pure read/sync/search surface.
+ *   drafts  Draft-level writes only (ofw_save_draft, ofw_delete_draft,
+ *           ofw_upload_attachment). Nothing that lands on the court-visible
+ *           record (send, calendar/expense/journal writes) is registered —
+ *           the only way to send remains a human in the OFW web UI.
+ *   all     Every tool registers (the default; fully backward compatible).
+ *
+ * Unregistered tools cannot be invoked by any host permission setting or
+ * injected instruction — the gate is structural, not behavioral. An
+ * unrecognized value fails closed to 'none': this is a safety control, so a
+ * typo must never silently grant write access.
+ */
+export function getWriteMode() {
+    const raw = process.env.OFW_WRITE_MODE;
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return 'all';
+    const mode = raw.trim().toLowerCase();
+    if (mode === 'none' || mode === 'drafts' || mode === 'all')
+        return mode;
+    // stdio transport: stderr only — stdout is reserved for JSON-RPC.
+    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';
+}
 // 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.3.1', // x-release-please-version
+    version: '2.4.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

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);
+        });
 }