ofw-mcp 2.3.2 → 2.4.1

package/dist/bundle.js

@@ -13,7 +13,11 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -38069,8 +38073,7 @@ async function loginWithPassword(username, password) {
     headers: { ...OFW_PROTOCOL_HEADERS },
     redirect: "manual"
   });
-  const setCookie = initResponse.headers.get("set-cookie") ?? "";
-  const sessionCookie = setCookie.split(";")[0];
+  const sessionCookie = initResponse.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
   const response = await fetch(`${BASE_URL}/ofw/login`, {
     method: "POST",
     headers: {
@@ -38130,6 +38133,16 @@ function getAttachmentsDir() {
 function parseBoolEnv2(name) {
   return parseBoolEnv(name);
 }
+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;
+  console.error(
+    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
+  );
+  return "none";
+}
 function getDefaultInlineAttachments() {
   return parseBoolEnv2("OFW_INLINE_ATTACHMENTS");
 }
@@ -38137,7 +38150,8 @@ function getDefaultInlineAttachments() {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.3.2",
+  version: "2.4.1",
+  license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38146,6 +38160,9 @@ var package_default = {
     url: "git+https://github.com/chrischall/ofw-mcp.git"
   },
   type: "module",
+  engines: {
+    node: ">=22.5.0"
+  },
   bin: {
     "ofw-mcp": "dist/index.js"
   },
@@ -38244,7 +38261,26 @@ async function resolveAuth() {
   );
 }
 
+// src/env-bootstrap.ts
+var USER_CONFIG_KEYS = [
+  "OFW_USERNAME",
+  "OFW_PASSWORD",
+  "OFW_INLINE_ATTACHMENTS",
+  "OFW_ATTACHMENTS_DIR",
+  "OFW_WRITE_MODE"
+];
+function clearBlankInjectedEnv(env = process.env, keys = USER_CONFIG_KEYS) {
+  for (const key of keys) {
+    const value = env[key];
+    if (value === void 0) continue;
+    if (value.trim() === "" || value.includes("${")) {
+      delete env[key];
+    }
+  }
+}
+
 // src/client.ts
+clearBlankInjectedEnv();
 var __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join4(__dirname, "..", ".env") });
 function parseContentDispositionFilename(cd) {
@@ -38401,9 +38437,24 @@ var OFWClient = class {
 };
 var client = new OFWClient();
 
+// src/validate.ts
+function parseOFW(schema, raw, ctx, mode = "lenient") {
+  const result = schema.safeParse(raw);
+  if (result.success) return result.data;
+  const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+  const message = `OFW response for ${ctx} failed validation: ${issues}`;
+  if (mode === "strict") throw new Error(message);
+  console.error(`[ofw-mcp] WARNING: ${message} \u2014 continuing with the raw response; fields derived from it may be missing or wrong.`);
+  return raw;
+}
+
 // src/tools/_shared.ts
 var jsonResponse = textResult;
 var textResponse = rawTextResult;
+var ApiRecipientSchema = external_exports.looseObject({
+  user: external_exports.looseObject({ id: external_exports.number().optional(), name: external_exports.string().optional() }).optional(),
+  viewed: external_exports.looseObject({ dateTime: external_exports.string() }).nullable().optional()
+});
 function mapRecipients(items) {
   return (items ?? []).map((r) => ({
     userId: r.user?.id ?? 0,
@@ -38412,15 +38463,36 @@ function mapRecipients(items) {
   }));
 }
 var expandPath2 = expandPath;
-async function postMessageAndRefetch(client2, payload) {
-  const raw = await client2.request(
-    "POST",
-    "/pub/v3/messages",
-    payload
+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 \u2014 OFW may have silently dropped or altered the write. Verify the ${kind} on ourfamilywizard.com before relying on it.`;
+}
+var PostMessagesResponseSchema = external_exports.looseObject({
+  id: external_exports.number().optional(),
+  entityId: external_exports.number().optional()
+}).nullable();
+async function postMessageAndRefetch(client2, payload, detailSchema, ctx) {
+  const raw = parseOFW(
+    PostMessagesResponseSchema,
+    await client2.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 client2.request("GET", `/pub/v3/messages/${id}`);
+  const detail = parseOFW(
+    detailSchema,
+    await client2.request("GET", `/pub/v3/messages/${id}`),
+    `GET /pub/v3/messages/{id} (${ctx})`,
+    "strict"
+  );
   return { id, detail, raw };
 }
 
@@ -38789,8 +38861,20 @@ function markAttachmentDownloaded(fileId, path) {
 }
 
 // src/sync.ts
+var FileMetaSchema = external_exports.looseObject({
+  fileId: external_exports.number(),
+  label: external_exports.string().optional(),
+  fileName: external_exports.string().optional(),
+  fileType: external_exports.string().optional(),
+  // MIME
+  fileSize: external_exports.number().optional()
+});
 async function fetchAttachmentMeta(client2, fileId, messageId) {
-  const meta3 = await client2.request("GET", `/pub/v1/myfiles/${fileId}`);
+  const meta3 = parseOFW(
+    FileMetaSchema,
+    await client2.request("GET", `/pub/v1/myfiles/${fileId}`),
+    "GET /pub/v1/myfiles/{fileId}"
+  );
   upsertAttachmentForMessage({
     fileId: meta3.fileId ?? fileId,
     fileName: meta3.fileName ?? `file-${fileId}`,
@@ -38804,10 +38888,14 @@ async function fetchAttachmentMeta(client2, fileId, messageId) {
 async function fetchAttachmentMetaForMessage(client2, messageId, fileIds) {
   await Promise.allSettled(fileIds.map((fid) => fetchAttachmentMeta(client2, fid, messageId)));
 }
+var FoldersSchema = external_exports.looseObject({
+  systemFolders: external_exports.array(external_exports.looseObject({ id: external_exports.string(), folderType: external_exports.string() })).optional()
+});
 async function resolveFolderIds(client2) {
-  const data = await client2.request(
-    "GET",
-    "/pub/v1/messageFolders?includeFolderCounts=true"
+  const data = parseOFW(
+    FoldersSchema,
+    await client2.request("GET", "/pub/v1/messageFolders?includeFolderCounts=true"),
+    "GET /pub/v1/messageFolders"
   );
   const sys = data.systemFolders ?? [];
   const find = (type) => {
@@ -38823,6 +38911,19 @@ async function resolveFolderIds(client2) {
   setMeta("drafts_folder_id", ids.drafts);
   return ids;
 }
+var ListItemSchema = external_exports.looseObject({
+  id: external_exports.number(),
+  subject: external_exports.string(),
+  date: external_exports.looseObject({ dateTime: external_exports.string() }),
+  from: external_exports.looseObject({ name: external_exports.string().optional() }).optional(),
+  showNeverViewed: external_exports.boolean(),
+  recipients: external_exports.array(ApiRecipientSchema).optional()
+});
+var ListResponseSchema = external_exports.looseObject({ data: external_exports.array(ListItemSchema).optional() });
+var DetailResponseSchema = external_exports.looseObject({
+  body: external_exports.string().optional(),
+  files: external_exports.array(external_exports.number()).optional()
+});
 async function syncMessageFolder(client2, folder, folderId, opts) {
   let page = 1;
   let synced = 0;
@@ -38830,7 +38931,11 @@ async function syncMessageFolder(client2, 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 client2.request("GET", path);
+    const list = parseOFW(
+      ListResponseSchema,
+      await client2.request("GET", path),
+      `GET /pub/v3/messages?folders={${folder}}`
+    );
     const items = list.data ?? [];
     if (items.length === 0) break;
     let pageHadNewItem = false;
@@ -38845,7 +38950,11 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
       let fetchedBodyAt = null;
       let detailFileIds = [];
       if (shouldFetchBody) {
-        const detail = await client2.request("GET", `/pub/v3/messages/${item.id}`);
+        const detail = parseOFW(
+          DetailResponseSchema,
+          await client2.request("GET", `/pub/v3/messages/${item.id}`),
+          "GET /pub/v3/messages/{id} (sync)"
+        );
         body = detail.body ?? "";
         fetchedBodyAt = (/* @__PURE__ */ new Date()).toISOString();
         if (Array.isArray(detail.files) && detail.files.length > 0) {
@@ -38887,17 +38996,44 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
   });
   return { synced, unread };
 }
+var DraftListItemSchema = external_exports.looseObject({
+  id: external_exports.number(),
+  subject: external_exports.string(),
+  date: external_exports.looseObject({ dateTime: external_exports.string() }),
+  replyToId: external_exports.number().nullable().optional(),
+  recipients: external_exports.array(ApiRecipientSchema).optional()
+});
+var DraftListResponseSchema = external_exports.looseObject({ data: external_exports.array(DraftListItemSchema).optional() });
+var DraftDetailSchema = external_exports.looseObject({
+  body: external_exports.string().optional(),
+  subject: external_exports.string().optional()
+});
 async function syncDrafts(client2, draftsFolderId) {
-  const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=1&size=50&sort=date&sortDirection=desc`;
-  const list = await client2.request("GET", path);
-  const items = list.data ?? [];
+  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 client2.request("GET", path),
+      "GET /pub/v3/messages?folders={drafts}"
+    );
+    const pageItems = list.data ?? [];
+    items.push(...pageItems);
+    if (pageItems.length < 50) break;
+    page++;
+  }
   const seenIds = /* @__PURE__ */ new Set();
   let synced = 0;
   for (const item of items) {
     seenIds.add(item.id);
     const modifiedAt = item.date?.dateTime ?? (/* @__PURE__ */ new Date()).toISOString();
     const existing = getDraft(item.id);
-    const detail = await client2.request("GET", `/pub/v3/messages/${item.id}`);
+    const detail = parseOFW(
+      DraftDetailSchema,
+      await client2.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)",
@@ -38949,6 +39085,39 @@ async function syncAll(client2, opts) {
 // src/tools/messages.ts
 import { mkdirSync as mkdirSync2, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname as dirname3, extname, join as join5 } from "node:path";
+var DateSchema = external_exports.looseObject({ dateTime: external_exports.string() });
+var SentDetailSchema = external_exports.looseObject({
+  subject: external_exports.string().optional(),
+  body: external_exports.string().optional(),
+  date: DateSchema.optional(),
+  from: external_exports.looseObject({ name: external_exports.string().optional() }).optional(),
+  recipients: external_exports.array(ApiRecipientSchema).optional()
+});
+var SavedDraftDetailSchema = external_exports.looseObject({
+  subject: external_exports.string().optional(),
+  body: external_exports.string().optional(),
+  date: DateSchema.optional(),
+  replyToId: external_exports.number().nullable().optional(),
+  recipients: external_exports.array(ApiRecipientSchema).optional()
+});
+var MessageDetailSchema = external_exports.looseObject({
+  id: external_exports.number(),
+  subject: external_exports.string(),
+  body: external_exports.string().optional(),
+  date: DateSchema,
+  from: external_exports.looseObject({ name: external_exports.string().optional() }).optional(),
+  files: external_exports.array(external_exports.number()).optional(),
+  recipients: external_exports.array(ApiRecipientSchema).optional()
+});
+var DetailFilesSchema = external_exports.looseObject({ files: external_exports.array(external_exports.number()).optional() });
+var UploadedFileSchema = external_exports.looseObject({
+  fileId: external_exports.number(),
+  fileName: external_exports.string().optional(),
+  label: external_exports.string().optional(),
+  fileType: external_exports.string().optional(),
+  sizeInBytes: external_exports.number().optional(),
+  shareClass: external_exports.string().optional()
+});
 var MIME_BY_EXT = {
   ".pdf": "application/pdf",
   ".png": "image/png",
@@ -38984,6 +39153,9 @@ function listDataHintsAtFiles(listData) {
   return false;
 }
 function registerMessageTools(server, client2) {
+  const writeMode = getWriteMode();
+  const allowSend = writeMode === "all";
+  const allowDrafts = writeMode !== "none";
   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.",
     annotations: { readOnlyHint: true }
@@ -38996,8 +39168,8 @@ function registerMessageTools(server, client2) {
     annotations: { readOnlyHint: true },
     inputSchema: {
       folderId: external_exports.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
-      page: external_exports.number().describe("Page number (default 1)").optional(),
-      size: external_exports.number().describe("Messages per page (default 50)").optional(),
+      page: external_exports.number().int().min(1).describe("Page number (default 1)").optional(),
+      size: external_exports.number().int().min(1).describe("Messages per page (default 50)").optional(),
       since: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at >= since (inclusive)").optional(),
       until: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at < until (exclusive)").optional(),
       q: external_exports.string().describe("Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.").optional()
@@ -39060,7 +39232,11 @@ function registerMessageTools(server, client2) {
       let attachments2 = listAttachmentsForMessage(id);
       if (attachments2.length === 0 && listDataHintsAtFiles(cached2.listData)) {
         try {
-          const detail2 = await client2.request("GET", `/pub/v3/messages/${id}`);
+          const detail2 = parseOFW(
+            DetailFilesSchema,
+            await client2.request("GET", `/pub/v3/messages/${id}`),
+            "GET /pub/v3/messages/{id} (attachment backfill)"
+          );
           if (Array.isArray(detail2.files) && detail2.files.length > 0) {
             await fetchAttachmentMetaForMessage(client2, id, detail2.files);
             attachments2 = listAttachmentsForMessage(id);
@@ -39070,7 +39246,11 @@ function registerMessageTools(server, client2) {
       }
       return jsonResponse({ ...cached2, attachments: attachments2 });
     }
-    const detail = await client2.request("GET", `/pub/v3/messages/${encodeURIComponent(args.messageId)}`);
+    const detail = parseOFW(
+      MessageDetailSchema,
+      await client2.request("GET", `/pub/v3/messages/${encodeURIComponent(args.messageId)}`),
+      "GET /pub/v3/messages/{id} (ofw_get_message)"
+    );
     const folder = cached2?.folder ?? "inbox";
     const row = {
       id: detail.id,
@@ -39092,7 +39272,7 @@ function registerMessageTools(server, client2) {
     const attachments = listAttachmentsForMessage(detail.id);
     return jsonResponse({ ...row, attachments });
   });
-  server.registerTool("ofw_send_message", {
+  if (allowSend) server.registerTool("ofw_send_message", {
     description: "Send a message via OurFamilyWizard. To send an existing draft, pass messageId \u2014 subject/body/recipientIds become optional overrides (missing fields default to the draft's cached values) and the draft is deleted after sending. To send a fresh message, supply subject/body/recipientIds directly. draftId is the legacy spelling of messageId and works the same way. 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). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -39162,9 +39342,11 @@ function registerMessageTools(server, client2) {
       draft: false,
       includeOriginal: resolvedReplyTo !== null,
       replyToId: resolvedReplyTo
-    });
+    }, SentDetailSchema, "ofw_send_message");
     let persisted = null;
+    let verifyNote = null;
     if (newId !== null) {
+      verifyNote = verifyWriteLanded("message", { subject, body }, detail);
       persisted = {
         id: newId,
         folder: "sent",
@@ -39192,13 +39374,18 @@ function registerMessageTools(server, client2) {
         });
       }
     }
-    if (draftRef !== void 0) {
+    let unconfirmedNote = null;
+    if (newId === null) {
+      const draftClause = draftRef !== void 0 ? `Draft ${draftRef} was NOT deleted \u2014 check` : "Check";
+      unconfirmedNote = `WARNING: OFW's send response did not include a message id, so the send could not be confirmed. ${draftClause} ourfamilywizard.com to see whether the message went out before retrying.`;
+    } else if (draftRef !== void 0) {
       await deleteOFWMessages(client2, [draftRef]);
       deleteDraft(draftRef);
     }
     const responseObj = persisted ?? raw;
     const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Message sent successfully.";
-    return textResponse(rewriteNote ? `${rewriteNote}
+    const notes = [rewriteNote, verifyNote, unconfirmedNote].filter((n) => n !== null).join("\n\n");
+    return textResponse(notes ? `${notes}
 
 ${text}` : text);
   });
@@ -39206,8 +39393,8 @@ ${text}` : text);
     description: "List draft messages from the local OurFamilyWizard cache. Call ofw_sync_messages first if the cache is empty.",
     annotations: { readOnlyHint: true },
     inputSchema: {
-      page: external_exports.number().describe("Page number (default 1)").optional(),
-      size: external_exports.number().describe("Drafts per page (default 50)").optional()
+      page: external_exports.number().int().min(1).describe("Page number (default 1)").optional(),
+      size: external_exports.number().int().min(1).describe("Drafts per page (default 50)").optional()
     }
   }, async (args) => {
     const page = args.page ?? 1;
@@ -39216,7 +39403,7 @@ ${text}` : text);
     const payload = drafts.length === 0 ? { drafts: [], note: "Cache empty. Call ofw_sync_messages to populate." } : { drafts };
     return jsonResponse(payload);
   });
-  server.registerTool("ofw_save_draft", {
+  if (allowDrafts) server.registerTool("ofw_save_draft", {
     description: "Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft \u2014 note that under the hood this creates a NEW draft and deletes the old one (OFW's update-in-place endpoint silently no-ops while echoing the posted body, so we don't use it); the response.id will be the NEW id, not the messageId you passed, and the change is documented in a transparency NOTE in the response. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After saving, the tool re-fetches the draft from OFW to populate the local cache from authoritative server state.",
     annotations: { readOnlyHint: false },
     inputSchema: {
@@ -39247,10 +39434,17 @@ ${text}` : text);
       includeOriginal: resolvedReplyTo !== null,
       replyToId: resolvedReplyTo
     };
-    const { id: newId, detail, raw } = await postMessageAndRefetch(client2, payload);
+    const { id: newId, detail, raw } = await postMessageAndRefetch(
+      client2,
+      payload,
+      SavedDraftDetailSchema,
+      "ofw_save_draft"
+    );
     let persisted = null;
     let replaceNote = null;
+    let verifyNote = null;
     if (newId !== null) {
+      verifyNote = verifyWriteLanded("draft", { subject: args.subject, body: args.body }, detail);
       persisted = {
         id: newId,
         subject: detail.subject ?? args.subject,
@@ -39273,12 +39467,12 @@ ${text}` : text);
     }
     const responseObj = persisted ?? raw;
     const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Draft saved.";
-    const notes = [rewriteNote, replaceNote].filter((n) => n !== null).join("\n\n");
+    const notes = [rewriteNote, verifyNote, replaceNote].filter((n) => n !== null).join("\n\n");
     return textResponse(notes ? `${notes}
 
 ${text}` : text);
   });
-  server.registerTool("ofw_delete_draft", {
+  if (allowDrafts) server.registerTool("ofw_delete_draft", {
     description: "Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache.",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -39293,8 +39487,8 @@ ${text}` : text);
     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: external_exports.number().describe("Page (default 1)").optional(),
-      size: external_exports.number().describe("Per page (default 50)").optional()
+      page: external_exports.number().int().min(1).describe("Page (default 1)").optional(),
+      size: external_exports.number().int().min(1).describe("Per page (default 50)").optional()
     }
   }, async (args) => {
     const page = args.page ?? 1;
@@ -39315,7 +39509,7 @@ ${text}` : text);
     }
     return jsonResponse(unread);
   });
-  server.registerTool("ofw_upload_attachment", {
+  if (allowDrafts) server.registerTool("ofw_upload_attachment", {
     description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. Returns the fileId \u2014 pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you) by default; pass shareClass:"SHARED" to share with co-parents directly via the My Files area.`,
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -39337,7 +39531,12 @@ ${text}` : text);
     form.append("label", args.label ?? fileName);
     form.append("fileName", fileName);
     form.append("shareClass", args.shareClass ?? "PRIVATE");
-    const meta3 = await client2.request("POST", "/pub/v3/myfiles/multipart", form);
+    const meta3 = parseOFW(
+      UploadedFileSchema,
+      await client2.request("POST", "/pub/v3/myfiles/multipart", form),
+      "POST /pub/v3/myfiles/multipart (ofw_upload_attachment)",
+      "strict"
+    );
     upsertAttachmentForMessage({
       fileId: meta3.fileId,
       fileName: meta3.fileName ?? fileName,
@@ -39462,6 +39661,7 @@ async function deleteOFWMessages(client2, ids) {
 
 // src/tools/calendar.ts
 function registerCalendarTools(server, client2) {
+  const allowWrites = getWriteMode() === "all";
   server.registerTool("ofw_list_events", {
     description: "List OurFamilyWizard calendar events in a date range",
     annotations: { readOnlyHint: true },
@@ -39478,7 +39678,7 @@ function registerCalendarTools(server, client2) {
     );
     return jsonResponse(data);
   });
-  server.registerTool("ofw_create_event", {
+  if (allowWrites) server.registerTool("ofw_create_event", {
     description: "Create a calendar event in OurFamilyWizard",
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -39498,7 +39698,7 @@ function registerCalendarTools(server, client2) {
     const data = await client2.request("POST", "/pub/v1/calendar/events", args);
     return jsonResponse(data);
   });
-  server.registerTool("ofw_update_event", {
+  if (allowWrites) server.registerTool("ofw_update_event", {
     description: "Update an existing OurFamilyWizard calendar event",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -39516,7 +39716,7 @@ function registerCalendarTools(server, client2) {
     const data = await client2.request("PUT", `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
     return jsonResponse(data);
   });
-  server.registerTool("ofw_delete_event", {
+  if (allowWrites) server.registerTool("ofw_delete_event", {
     description: "Delete an OurFamilyWizard calendar event",
     annotations: { destructiveHint: true },
     inputSchema: {
@@ -39530,6 +39730,7 @@ function registerCalendarTools(server, client2) {
 
 // src/tools/expenses.ts
 function registerExpenseTools(server, client2) {
+  const allowWrites = getWriteMode() === "all";
   server.registerTool("ofw_get_expense_totals", {
     description: "Get OurFamilyWizard expense summary totals (owed/paid)",
     annotations: { readOnlyHint: true }
@@ -39541,8 +39742,8 @@ function registerExpenseTools(server, client2) {
     description: "List OurFamilyWizard expenses with pagination",
     annotations: { readOnlyHint: true },
     inputSchema: {
-      start: external_exports.number().describe("Start offset (default 0)").optional(),
-      max: external_exports.number().describe("Max results (default 20)").optional()
+      start: external_exports.number().int().min(0).describe("Start offset (default 0)").optional(),
+      max: external_exports.number().int().min(1).describe("Max results (default 20)").optional()
     }
   }, async (args) => {
     const start = args.start ?? 0;
@@ -39550,7 +39751,7 @@ function registerExpenseTools(server, client2) {
     const data = await client2.request("GET", `/pub/v2/expense/expenses?start=${start}&max=${max}`);
     return jsonResponse(data);
   });
-  server.registerTool("ofw_create_expense", {
+  if (allowWrites) server.registerTool("ofw_create_expense", {
     description: "Log a new expense in OurFamilyWizard",
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -39565,12 +39766,13 @@ function registerExpenseTools(server, client2) {
 
 // src/tools/journal.ts
 function registerJournalTools(server, client2) {
+  const allowWrites = getWriteMode() === "all";
   server.registerTool("ofw_list_journal_entries", {
     description: "List OurFamilyWizard journal entries",
     annotations: { readOnlyHint: true },
     inputSchema: {
-      start: external_exports.number().describe("Start offset (default 1)").optional(),
-      max: external_exports.number().describe("Max results (default 10)").optional()
+      start: external_exports.number().int().min(1).describe("Start offset (default 1)").optional(),
+      max: external_exports.number().int().min(1).describe("Max results (default 10)").optional()
     }
   }, async (args) => {
     const start = args.start ?? 1;
@@ -39578,7 +39780,7 @@ function registerJournalTools(server, client2) {
     const data = await client2.request("GET", `/pub/v1/journals?start=${start}&max=${max}`);
     return jsonResponse(data);
   });
-  server.registerTool("ofw_create_journal_entry", {
+  if (allowWrites) server.registerTool("ofw_create_journal_entry", {
     description: "Create a new journal entry in OurFamilyWizard",
     annotations: { destructiveHint: false },
     inputSchema: {
@@ -39604,7 +39806,7 @@ process.emit = function(event, ...args) {
 };
 await runMcp({
   name: "ofw",
-  version: "2.3.2",
+  version: "2.4.1",
   // x-release-please-version
   deps: client,
   tools: [

package/dist/client.js

@@ -4,7 +4,13 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveAuth } from './auth.js';
 import { parseBoolEnv } from './config.js';
+import { clearBlankInjectedEnv } from './env-bootstrap.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
+// When the plugin runs via a host that maps creds from optional
+// `${user_config.*}` fields, an unset field can be injected as a blank /
+// placeholder env value. Clear those first so the next step's .env (and the
+// shell env) can still populate them — a filled field keeps its real value.
+clearBlankInjectedEnv();
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
 // missing dotenv module, matching the prior inline try/catch exactly.

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