ofw-mcp 2.19.5 → 2.20.0

package/dist/bundle.js

@@ -25787,11 +25787,11 @@ var rev2025Codec = {
   },
   encodeResult(method, result) {
     if (method !== "tools/list") return result;
-    const tools = result.tools;
-    if (!Array.isArray(tools) || !tools.some((t) => toolNeedsLegacyWrap(t))) return result;
+    const tools2 = result.tools;
+    if (!Array.isArray(tools2) || !tools2.some((t) => toolNeedsLegacyWrap(t))) return result;
     return {
       ...result,
-      tools: tools.map((t) => toolNeedsLegacyWrap(t) ? {
+      tools: tools2.map((t) => toolNeedsLegacyWrap(t) ? {
         ...t,
         outputSchema: wrapOutputSchemaForLegacy(t.outputSchema)
       } : t)
@@ -27019,8 +27019,8 @@ function enforceDeletedFields(method, result) {
     }
     return next;
   };
-  const tools = result.tools;
-  if (method === "tools/list" && Array.isArray(tools) && tools.some((tool) => isPlainObject$4(tool) && "execution" in tool)) copy().tools = tools.map((tool) => {
+  const tools2 = result.tools;
+  if (method === "tools/list" && Array.isArray(tools2) && tools2.some((tool) => isPlainObject$4(tool) && "execution" in tool)) copy().tools = tools2.map((tool) => {
     if (!isPlainObject$4(tool) || !("execution" in tool)) return tool;
     const rest = { ...tool };
     delete rest["execution"];
@@ -45679,7 +45679,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.19.5",
+  version: "2.20.0",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -45958,7 +45958,11 @@ var OFWClient = class {
       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}`);
+      const errorBody = await response.text();
+      const safeBody = redactSecrets(errorBody).replace(/\s+/g, " ").trim().slice(0, 4e3);
+      throw new Error(
+        `OFW API error: ${response.status} ${response.statusText} for ${method} ${path}` + (safeBody ? ` \u2014 ${safeBody}` : "")
+      );
     }
     return response;
   }
@@ -46348,11 +46352,12 @@ async function requestWrite(client2, method, path, body) {
   }
 }
 function unconfirmedWriteResponse(e, opts) {
+  const fallback = /ourfamilywizard\.com/i.test(opts.checkWith) ? "" : " (or on ourfamilywizard.com)";
   return jsonErrorResponse({
     result: opts.result,
     mayHaveLanded: true,
     reason: `The request to ${opts.what} failed without a definitive answer from OFW: ${e.message}. It MAY HAVE BEEN APPLIED on OurFamilyWizard.`,
-    remedy: `Do NOT retry blindly \u2014 a second attempt can put a duplicate on the co-parent-visible record. First check with ${opts.checkWith} (or on ourfamilywizard.com), and retry only once you have confirmed it did not land.`
+    remedy: `Do NOT retry blindly \u2014 a second attempt can put a duplicate on the co-parent-visible record. First check with ${opts.checkWith}${fallback}, and retry only once you have confirmed it did not land.`
   });
 }
 async function postMessageAndRefetch(client2, payload, detailSchema, ctx) {
@@ -46894,6 +46899,23 @@ function getUploadDir() {
   if (override && override.trim().length > 0) return override.trim();
   return getAttachmentsDir();
 }
+function restrictiveBoolEnv(name) {
+  const raw = process.env[name];
+  if (typeof raw !== "string" || raw.trim().length === 0) return false;
+  const value = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(value)) return true;
+  if (["0", "false", "no", "off"].includes(value)) return false;
+  console.error(
+    `[ofw-mcp] Unrecognized ${name} "${raw.trim()}" \u2014 failing closed to "true" (restriction enabled). Valid values: true, false.`
+  );
+  return true;
+}
+function getExpenseUploadOnly() {
+  return restrictiveBoolEnv("OFW_EXPENSE_UPLOAD_ONLY");
+}
+function getExpenseOnly() {
+  return getExpenseUploadOnly() || restrictiveBoolEnv("OFW_EXPENSE_ONLY");
+}
 function getWriteMode() {
   const raw = process.env.OFW_WRITE_MODE;
   if (typeof raw !== "string" || raw.trim().length === 0) return "all";
@@ -50349,75 +50371,474 @@ function registerCalendarTools(server, client2) {
 }
 
 // src/tools/expenses.ts
-function registerExpenseTools(server, client2) {
-  const allowWrites = getWriteMode() === "all";
-  server.registerTool("ofw_get_expense_totals", {
+var UploadedExpenseFileSchema = 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 PDF_MIME = "application/pdf";
+var MAX_REMOTE_PDF_BYTES = MAX_UPLOAD_BYTES;
+var MAX_REMOTE_REDIRECTS = 5;
+var REMOTE_FETCH_TIMEOUT_MS = 3e4;
+function isPdf(bytes) {
+  return bytes.byteLength >= 5 && bytes[0] === 37 && bytes[1] === 80 && bytes[2] === 68 && bytes[3] === 70 && bytes[4] === 45;
+}
+function assertReceiptUrl(url2) {
+  if (url2.protocol !== "https:") {
+    throw new Error("Remote expense receipt URLs must use HTTPS.");
+  }
+  if (!url2.hostname.toLowerCase().endsWith(".oaiusercontent.com")) {
+    throw new Error("Remote expense receipt URLs must be signed oaiusercontent.com file URLs.");
+  }
+}
+async function readCapped(response, cap) {
+  const tooLarge = () => new Error(`Expense receipt exceeds ${cap} bytes.`);
+  const declared = Number(response.headers.get("content-length") ?? 0);
+  if (Number.isFinite(declared) && declared > cap) throw tooLarge();
+  const chunks = [];
+  let total = 0;
+  if (response.body) {
+    const reader = response.body.getReader();
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > cap) {
+        await reader.cancel();
+        throw tooLarge();
+      }
+      chunks.push(value);
+    }
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk2 of chunks) {
+    bytes.set(chunk2, offset);
+    offset += chunk2.byteLength;
+  }
+  return bytes;
+}
+async function resolveRemotePdf(urlValue, fileNameValue) {
+  const fileName = fileNameValue?.trim() || "receipt.pdf";
+  if (!fileName.toLowerCase().endsWith(".pdf")) {
+    throw new Error(`Expense receipts must use a .pdf filename; received ${fileName}`);
+  }
+  let url2 = new URL(urlValue);
+  let response;
+  for (let hop = 0; ; hop++) {
+    assertReceiptUrl(url2);
+    response = await fetch(url2, { redirect: "manual", signal: AbortSignal.timeout(REMOTE_FETCH_TIMEOUT_MS) });
+    const location = response.headers.get("location");
+    if (response.status < 300 || response.status >= 400 || location === null) break;
+    if (hop >= MAX_REMOTE_REDIRECTS) {
+      throw new Error(`Remote expense receipt redirected more than ${MAX_REMOTE_REDIRECTS} times.`);
+    }
+    url2 = new URL(location, url2);
+  }
+  if (!response.ok) {
+    throw new Error(`Unable to fetch remote expense receipt: HTTP ${response.status}`);
+  }
+  const bytes = await readCapped(response, MAX_REMOTE_PDF_BYTES);
+  if (!isPdf(bytes)) {
+    throw new Error("Remote expense receipt is not a valid PDF file.");
+  }
+  return {
+    blob: new Blob([bytes], { type: PDF_MIME }),
+    fileName,
+    mimeType: PDF_MIME,
+    sizeBytes: bytes.byteLength
+  };
+}
+function expenseParties(args) {
+  return {
+    payerUserId: args.payerId,
+    categoryId: args.categoryId,
+    childUserIds: args.children,
+    idsNote: "payerUserId is the parent this claim is billed to; confirm it names the right parent before approving (ofw_get_profile, where registered, or the OFW web app). categoryId is from ofw_list_expense_categories."
+  };
+}
+var EXPENSE_FIELDS = [
+  "title",
+  "amount",
+  "purchaseDate",
+  "categoryId",
+  "payerId",
+  "children",
+  "isPrivate",
+  "description",
+  "fileIds"
+];
+var ARG_FOR = {
+  title: "title",
+  amount: "amount",
+  purchaseDate: "purchaseDate",
+  categoryId: "categoryId",
+  payerId: "payerId",
+  children: "children",
+  isPrivate: "privateExpense",
+  description: "description",
+  fileIds: "receiptFileId"
+};
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var positiveInt = (v) => typeof v === "number" && Number.isInteger(v) && v > 0 ? v : void 0;
+var refId = (v, key) => positiveInt(v) ?? (isRecord2(v) ? positiveInt(v[key]) ?? positiveInt(v.id) : void 0);
+var idList = (v, key) => {
+  if (!Array.isArray(v)) return void 0;
+  const ids = v.map((x) => refId(x, key));
+  return ids.every((id) => id !== void 0) ? ids : void 0;
+};
+function readExpenseState(raw) {
+  const d = isRecord2(raw) && isRecord2(raw.data) ? raw.data : raw;
+  if (!isRecord2(d)) return {};
+  const out = {};
+  if (typeof d.title === "string" && d.title.trim()) out.title = d.title;
+  const amount = typeof d.amount === "string" ? Number(d.amount) : d.amount;
+  if (typeof amount === "number" && Number.isFinite(amount) && amount > 0) out.amount = amount;
+  const dateRaw = isRecord2(d.purchaseDate) ? d.purchaseDate.dateTime : d.purchaseDate;
+  if (typeof dateRaw === "string" && /^\d{4}-\d{2}-\d{2}/.test(dateRaw)) out.purchaseDate = dateRaw.slice(0, 10);
+  const categoryId = positiveInt(d.categoryId) ?? (isRecord2(d.category) ? positiveInt(d.category.id) : void 0);
+  if (categoryId !== void 0) out.categoryId = categoryId;
+  const payerId = positiveInt(d.payerId) ?? refId(d.payer, "userId");
+  if (payerId !== void 0) out.payerId = payerId;
+  const children = idList(d.children, "userId");
+  if (children !== void 0 && children.length > 0) out.children = children;
+  const isPrivate = typeof d.isPrivate === "boolean" ? d.isPrivate : d.private;
+  if (typeof isPrivate === "boolean") out.isPrivate = isPrivate;
+  if ("description" in d) {
+    if (d.description === null || d.description === "") out.description = null;
+    else if (typeof d.description === "string") out.description = d.description;
+  }
+  for (const key of ["fileIds", "files"]) {
+    if (!(key in d)) continue;
+    const ids = d[key] === null ? [] : idList(d[key], "fileId");
+    if (ids !== void 0) out.fileIds = ids;
+    break;
+  }
+  return out;
+}
+function registerExpenseTools(server, client2, attachmentIO) {
+  const writeMode = getWriteMode();
+  const uploadOnly = getExpenseUploadOnly();
+  const checkIn = uploadOnly ? "the Expenses log on ourfamilywizard.com (ofw_list_expenses is not available in this deployment)" : "ofw_list_expenses";
+  const allowWrites = writeMode === "all";
+  const allowReceiptUploads = allowWrites && attachmentIO !== void 0;
+  if (!uploadOnly) server.registerTool("ofw_get_expense_totals", {
     description: "Get OurFamilyWizard expense summary totals (owed/paid)",
     annotations: { readOnlyHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v2/expense/expenses/totals");
     return jsonResponse(data);
   });
-  server.registerTool("ofw_list_expenses", {
-    description: "List OurFamilyWizard expenses. Offset-paged via start/max. The response leads with its paging state \u2014 `hasMore` and `nextStart` (null when the list is exhausted) \u2014 BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an expense total or an absence from one page.",
+  if (!uploadOnly) server.registerTool("ofw_list_expense_categories", {
+    description: "List OurFamilyWizard expense categories, including preset and custom categories with their responsibility split metadata. Read-only.",
+    annotations: { readOnlyHint: true }
+  }, async () => {
+    const data = await client2.request("GET", "/pub/v2/expense/categories");
+    return jsonResponse(data);
+  });
+  if (!uploadOnly) server.registerTool("ofw_list_expenses", {
+    description: "List OurFamilyWizard expenses. OFW pages this endpoint with 1-based page/size parameters; its older start/max parameters are ignored and repeatedly return page 1. The response leads with hasMore and nextPage (null when exhausted) before the records. Continue by passing nextPage.",
     annotations: { readOnlyHint: true },
     inputSchema: external_exports.object({
-      start: external_exports.number().int().min(0).describe("Start offset, 0-based (default 0). To continue a listing, pass the `nextStart` from the previous response.").optional(),
-      max: external_exports.number().int().min(1).describe("Max results (default 20)").optional()
+      page: external_exports.number().int().min(1).describe("1-based page number (default 1). To continue, pass the nextPage returned by the previous response.").optional(),
+      size: external_exports.number().int().min(1).max(100).describe("Requested page size (default 20). OFW may cap or normalize this value.").optional()
     })
   }, async (args) => {
-    const start = args.start ?? 0;
-    const max = args.max ?? 20;
-    const data = await client2.request("GET", `/pub/v2/expense/expenses?start=${start}&max=${max}`);
+    const page = args.page ?? 1;
+    const size = args.size ?? 20;
+    const data = await client2.request("GET", `/pub/v2/expense/expenses?page=${page}&size=${size}`);
     const { returned, total, last } = readUpstreamPaging(data);
-    const wrapped = withPaginationFirst({
-      state: offsetState({ start, max, returned, total, last, base: 0 }),
-      start,
-      max,
+    const body = typeof data === "object" && data !== null && !Array.isArray(data) ? data : null;
+    if (body === null) return jsonResponse(data);
+    const metadata = typeof body.metadata === "object" && body.metadata !== null && !Array.isArray(body.metadata) ? body.metadata : null;
+    const upstreamPage = metadata !== null && typeof metadata.currentPage === "number" ? metadata.currentPage : metadata !== null && typeof metadata.page === "number" ? metadata.page : page;
+    const upstreamSize = metadata !== null && typeof metadata.perPage === "number" ? metadata.perPage : size;
+    const hasMore = last !== null ? !last : total !== null ? upstreamPage * upstreamSize < total : returned >= upstreamSize;
+    const nextPage = hasMore ? upstreamPage + 1 : null;
+    const scope = total !== null ? ` of ${total}` : "";
+    const head = {
+      hasMore,
+      nextPage,
+      page: upstreamPage,
+      size: upstreamSize,
       returned,
-      total,
-      hint: `Re-call ofw_list_expenses with start:${start + max}.`,
-      payload: data
+      ...total !== null ? { total } : {},
+      paginationNote: hasMore ? `PARTIAL: this response holds ${returned} record(s) on page ${upstreamPage}${scope}. Re-call ofw_list_expenses with page:${nextPage}. Do not state a total or an absence from this response alone.` : `This response reaches the end of the expense list${scope === "" ? "" : ` (${total} record(s) in total)`}.`
+    };
+    return jsonResponse({ ...head, ...body, ...head });
+  });
+  if (allowReceiptUploads) server.registerTool("ofw_upload_expense_pdf", {
+    description: "Upload a PDF to OurFamilyWizard My Files for later attachment to an expense. Accepts either a local path or a signed ChatGPT/oaiusercontent HTTPS URL plus fileName. Exactly one of path or url must be supplied. This tool accepts PDF files only and uploads them using the same SHARED file metadata as the OFW expense form so the returned fileId can be attached to an expense. A SHARED file is visible to the co-parent in My Files immediately, whatever the visibility of the expense it is later attached to (that is set separately by ofw_create_expense privateExpense). " + CONFIRM_NOTE,
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    inputSchema: external_exports.object({
+      path: external_exports.string().describe("Path to a local PDF file inside the upload directory (OFW_UPLOAD_DIR). Tilde (~) is expanded by the configured attachment I/O implementation. Mutually exclusive with url.").optional(),
+      url: external_exports.string().describe("Signed HTTPS oaiusercontent.com URL for a PDF supplied by the ChatGPT host. Mutually exclusive with path.").optional(),
+      fileName: external_exports.string().describe("Filename to use for a remote URL upload. Must end in .pdf. Defaults to receipt.pdf.").optional(),
+      label: external_exports.string().describe("Display label for the file in OFW (default: filename)").optional(),
+      description: external_exports.string().describe("Description shown in OFW My Files (default: filename)").optional(),
+      confirmToken: confirmTokenParam
+    })
+  }, async (args, ctx) => {
+    const io = attachmentIO;
+    if ((args.path ? 1 : 0) + (args.url ? 1 : 0) !== 1) {
+      throw new Error("Pass exactly one of path or url to ofw_upload_expense_pdf.");
+    }
+    const { blob, fileName, mimeType, sizeBytes } = args.url ? await resolveRemotePdf(args.url, args.fileName) : await io.resolveUpload(args.path);
+    if (!fileName.toLowerCase().endsWith(".pdf") || mimeType !== PDF_MIME) {
+      throw new Error(`Expense receipts must be PDF files; received ${fileName} (${mimeType})`);
+    }
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    if (!isPdf(bytes)) {
+      throw new Error(`Expense receipts must be PDF files; ${fileName} does not start with a PDF header.`);
+    }
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    const sha2562 = Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("");
+    const label = args.label ?? fileName;
+    const description = args.description ?? fileName;
+    const gate = await confirmWrite(ctx, {
+      tool: "ofw_upload_expense_pdf",
+      action: "ofw.file.share",
+      message: `Review and confirm uploading the receipt "${fileName}" to OurFamilyWizard. It is uploaded SHARED, so the co-parent can see it in My Files immediately \u2014 even if the expense it is attached to is private.`,
+      target: `file:${fileName}`,
+      payload: { fileName, sizeBytes, sha256: sha2562, label, description, shareClass: "SHARED", source: "expense" },
+      preview: {
+        action: "Upload and SHARE an expense receipt on OurFamilyWizard",
+        fileName,
+        sizeBytes,
+        mimeType,
+        label,
+        description,
+        shareClass: "SHARED",
+        from: args.url ? `hosted file (${new URL(args.url).hostname})` : "local file",
+        warning: "Visible to the co-parent immediately in My Files, whatever the visibility of the expense it is attached to; the file becomes part of the court-visible record."
+      },
+      confirmToken: args.confirmToken
+    });
+    if (gate) return gate;
+    const form = new FormData();
+    form.append("file", blob, fileName);
+    form.append("source", "expense");
+    form.append("description", args.description ?? fileName);
+    form.append("label", args.label ?? fileName);
+    form.append("fileName", fileName);
+    form.append("shared", "true");
+    form.append("shareClass", "SHARED");
+    const meta3 = parseLenient(
+      UploadedExpenseFileSchema,
+      await client2.request("POST", "/pub/v3/myfiles/multipart", form),
+      { label: "ofw-mcp", context: "POST /pub/v3/myfiles/multipart (ofw_upload_expense_pdf)", mode: "strict" }
+    );
+    return jsonResponse({
+      fileId: meta3.fileId,
+      fileName: meta3.fileName ?? fileName,
+      mimeType: meta3.fileType ?? mimeType,
+      sizeBytes: meta3.sizeInBytes ?? sizeBytes,
+      shareClass: meta3.shareClass ?? "SHARED",
+      note: "Pass fileId to ofw_create_expense as receiptFileId. Expense visibility is controlled separately by privateExpense."
+    });
+  });
+  if (allowWrites) server.registerTool("ofw_update_expense", {
+    description: `Change an existing OurFamilyWizard expense. Pass expenseId plus ONLY the fields you want to change; every field you omit keeps its current value. The tool reads the expense from OFW first and sends the merged result, because OFW's update replaces the whole expense and a field left out would otherwise be erased. If a field you did not pass cannot be read back from OFW, the update is refused as EXPENSE_FIELDS_UNREADABLE and names the field; pass it explicitly (description:null or receiptFileId:null to send none). receiptFileId REPLACES all current receipts; omit it to keep them. Set privateExpense=false to publish a private expense to the co-parent. The confirmation is bound to the expense exactly as read, so if it changes on OFW in between, the update is refused instead of overwriting that change. If the request fails without a definitive answer the result is EXPENSE_UNCONFIRMED: the update may already have been applied, so check ${checkIn} before retrying. ` + CONFIRM_NOTE,
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    inputSchema: external_exports.object({
+      expenseId: external_exports.number().int().positive().describe("Existing OFW expense entity id"),
+      title: external_exports.string().trim().min(1).describe("New title (omit to keep)").optional(),
+      amount: external_exports.number().positive().describe("New full expense amount (omit to keep)").optional(),
+      purchaseDate: external_exports.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("New expense date, YYYY-MM-DD (omit to keep)").optional(),
+      categoryId: external_exports.number().int().positive().describe("New OFW expense category id (omit to keep)").optional(),
+      payerId: external_exports.number().int().positive().describe("New payer: the userId of the parent who owes (omit to keep)").optional(),
+      children: external_exports.array(external_exports.number().int().positive()).min(1).describe("New child userIds, replacing the current list (omit to keep)").optional(),
+      description: external_exports.string().trim().min(1).nullable().describe("New description; null removes it (omit to keep)").optional(),
+      privateExpense: external_exports.boolean().describe("true = visible only to you; false = shared with the co-parent (omit to keep)").optional(),
+      receiptFileId: external_exports.number().int().positive().nullable().describe("Receipt fileId that REPLACES all current receipts; null removes them (omit to keep)").optional(),
+      confirmToken: confirmTokenParam
+    })
+  }, async (args, ctx) => {
+    const { expenseId, confirmToken } = args;
+    const path = `/pub/v2/expense/expenses/${expenseId}`;
+    const supplied = {};
+    if (args.title !== void 0) supplied.title = args.title;
+    if (args.amount !== void 0) supplied.amount = args.amount;
+    if (args.purchaseDate !== void 0) supplied.purchaseDate = args.purchaseDate;
+    if (args.categoryId !== void 0) supplied.categoryId = args.categoryId;
+    if (args.payerId !== void 0) supplied.payerId = args.payerId;
+    if (args.children !== void 0) supplied.children = args.children;
+    if (args.privateExpense !== void 0) supplied.isPrivate = args.privateExpense;
+    if (args.description !== void 0) supplied.description = args.description;
+    if (args.receiptFileId !== void 0) supplied.fileIds = args.receiptFileId === null ? [] : [args.receiptFileId];
+    if (Object.keys(supplied).length === 0) {
+      return jsonErrorResponse({
+        result: "NO_CHANGES",
+        expenseId,
+        remedy: "Pass the fields to change alongside expenseId (for example privateExpense:false to publish it). Nothing was sent."
+      });
+    }
+    let current = {};
+    let readError;
+    try {
+      const raw = await client2.request("GET", path);
+      current = readExpenseState(parseLenient(external_exports.looseObject({}), raw, { label: "ofw-mcp", context: `GET ${path}` }));
+    } catch (e) {
+      readError = e instanceof Error ? e.message : String(e);
+    }
+    const merged = { ...current, ...supplied };
+    const missing = EXPENSE_FIELDS.filter((f) => merged[f] === void 0);
+    if (missing.length > 0) {
+      return jsonErrorResponse({
+        result: "EXPENSE_FIELDS_UNREADABLE",
+        expenseId,
+        missing: missing.map((f) => ARG_FOR[f]),
+        reason: readError !== void 0 ? `Could not read expense ${expenseId} from OFW (${readError}), so the fields you did not pass have no known value.` : `OFW's copy of expense ${expenseId} did not include a readable value for these fields.`,
+        remedy: `OFW replaces the whole expense on update, so sending without these would erase them. Pass them explicitly (description:null or receiptFileId:null if the expense should have none). Nothing was sent.`
+      });
+    }
+    const next = merged;
+    const payload = {
+      title: next.title,
+      amount: next.amount,
+      purchaseDate: next.purchaseDate,
+      categoryId: next.categoryId,
+      payerId: next.payerId,
+      children: next.children,
+      isPrivate: next.isPrivate
+    };
+    if (next.description !== null) payload.description = next.description;
+    if (next.fileIds.length > 0) payload.fileIds = next.fileIds;
+    const changes = {};
+    for (const f of Object.keys(supplied)) {
+      const from = current[f];
+      if (JSON.stringify(from) !== JSON.stringify(next[f])) {
+        changes[ARG_FOR[f]] = { from: from === void 0 ? "unknown (not readable from OFW)" : from, to: next[f] };
+      }
+    }
+    const baseRead = readError === void 0;
+    if (baseRead && Object.keys(changes).length === 0) {
+      return jsonErrorResponse({
+        result: "NO_CHANGES",
+        expenseId,
+        remedy: "Every field you passed already has that value on OFW, so there is nothing to update. Nothing was sent."
+      });
+    }
+    const gate = await confirmWrite(ctx, {
+      tool: "ofw_update_expense",
+      action: "ofw.expense.update",
+      message: next.isPrivate ? `Review and confirm this update to the private OurFamilyWizard expense "${next.title}".` : `Review and confirm this update to the OurFamilyWizard expense "${next.title}". The expense will be SHARED: it appears in the ledger the co-parent sees immediately, and cannot be deleted through this server.`,
+      target: `expense:${expenseId}`,
+      ...baseRead ? { revision: stateRevision(current) } : {},
+      payload,
+      preview: {
+        action: next.isPrivate ? "Update private OurFamilyWizard expense" : "Update shared OurFamilyWizard expense",
+        expenseId,
+        changes,
+        after: {
+          title: next.title,
+          amount: next.amount,
+          purchaseDate: next.purchaseDate,
+          ...expenseParties(next),
+          description: next.description,
+          visibility: next.isPrivate ? "private (only you)" : "shared with the co-parent",
+          receiptFileIds: next.fileIds
+        },
+        ...baseRead ? {} : { baseNote: `The current expense could not be read from OFW (${readError}); every field comes from this call, and nothing is carried over.` },
+        ...next.isPrivate ? {} : { warning: "Visible to the co-parent immediately as a claim in the shared expense ledger; part of the court-visible record." }
+      },
+      confirmToken
+    });
+    if (gate) return gate;
+    let data;
+    try {
+      data = await requestWrite(client2, "PUT", path, payload);
+    } catch (e) {
+      if (!(e instanceof UnconfirmedWriteError)) throw e;
+      return unconfirmedWriteResponse(e, {
+        result: "EXPENSE_UNCONFIRMED",
+        what: `update expense ${expenseId}`,
+        checkWith: `${checkIn} (compare this expense against the values you sent)`
+      });
+    }
+    const warnings = [];
+    try {
+      const after = readExpenseState(await client2.request("GET", path));
+      for (const f of EXPENSE_FIELDS) {
+        if (after[f] !== void 0 && JSON.stringify(after[f]) !== JSON.stringify(next[f])) {
+          warnings.push(`OFW reports ${ARG_FOR[f]} as ${JSON.stringify(after[f])} after the update, not the ${JSON.stringify(next[f])} that was sent.`);
+        }
+      }
+    } catch (e) {
+      warnings.push(`The update was accepted but could not be read back to verify it (${e instanceof Error ? e.message : String(e)}); check ${checkIn}.`);
+    }
+    return jsonResponse({
+      result: "EXPENSE_UPDATED",
+      expenseId,
+      changed: Object.keys(changes),
+      kept: EXPENSE_FIELDS.filter((f) => supplied[f] === void 0).map((f) => ARG_FOR[f]),
+      ...warnings.length > 0 ? { warnings } : {},
+      response: data
     });
-    return jsonResponse(wrapped ?? data);
   });
   if (allowWrites) server.registerTool("ofw_create_expense", {
-    description: "Log a new expense in OurFamilyWizard. The expense is a money claim that appears in the shared ledger in front of the co-parent immediately, and this server cannot delete it. If the request fails without a definitive answer the result is EXPENSE_UNCONFIRMED: the expense may already exist, so do NOT retry until ofw_list_expenses shows it did not land. " + CONFIRM_NOTE,
-    // Not a harmless local write: the claim is co-parent-visible at once and
-    // this server has no way to take it back. destructiveHint keeps a host
+    description: `Log a new expense in OurFamilyWizard using the current web-app expense contract. Required fields are title, amount, purchaseDate, categoryId, payerId (the parent who owes), and at least one child user id. Supports one previously-uploaded receipt PDF and private entries. privateExpense=true creates an expense visible only to you; false/default creates the normal shared expense. receiptFileId should come from ofw_upload_expense_pdf. A shared expense is a money claim that appears in the ledger in front of the co-parent immediately, and this server cannot delete it. If the request fails without a definitive answer the result is EXPENSE_UNCONFIRMED: the expense may already exist, so do NOT retry until ${checkIn} shows it did not land. ` + CONFIRM_NOTE,
+    // Not a harmless local write: a shared claim is co-parent-visible at once
+    // and this server has no way to take it back. destructiveHint keeps a host
     // that auto-approves "non-destructive" tools from running it silently.
     annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
-      amount: external_exports.number().describe("Expense amount"),
-      description: external_exports.string().describe("Expense description"),
+      title: external_exports.string().trim().min(1).describe("Expense title/name shown in the OFW expense log"),
+      amount: external_exports.number().positive().describe("Full expense amount before OFW applies the category split"),
+      purchaseDate: external_exports.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("Date the expense was incurred, YYYY-MM-DD"),
+      categoryId: external_exports.number().int().positive().describe("OFW expense category id (for example General is commonly id 1; use the id from OFW, not the category display name)"),
+      payerId: external_exports.number().int().positive().describe("OFW userId of the parent who owes/reimburses this expense"),
+      children: external_exports.array(external_exports.number().int().positive()).min(1).describe("One or more OFW child userIds associated with the expense"),
+      description: external_exports.string().trim().min(1).describe("Optional supporting description/details for the expense").optional(),
+      privateExpense: external_exports.boolean().describe("true = visible only to you; false/default = shared with co-parent").optional(),
+      receiptFileId: external_exports.number().int().positive().describe("Single OFW My Files fileId to attach as the receipt, normally returned by ofw_upload_expense_pdf").optional(),
       confirmToken: confirmTokenParam
     })
   }, async (args, ctx) => {
-    const { confirmToken, ...payload } = args;
+    const payload = {
+      title: args.title,
+      amount: args.amount,
+      purchaseDate: args.purchaseDate,
+      categoryId: args.categoryId,
+      payerId: args.payerId,
+      children: args.children
+    };
+    if (args.description !== void 0) payload.description = args.description;
+    if (args.privateExpense !== void 0) payload.isPrivate = args.privateExpense;
+    if (args.receiptFileId !== void 0) payload.fileIds = [args.receiptFileId];
+    const isPrivate = args.privateExpense === true;
     const gate = await confirmWrite(ctx, {
       tool: "ofw_create_expense",
       action: "ofw.expense.create",
-      message: "Review and confirm this OurFamilyWizard expense. It is logged in the shared ledger the co-parent sees immediately, and cannot be deleted through this server.",
+      message: isPrivate ? "Review and confirm this private OurFamilyWizard expense (visible only to you)." : "Review and confirm this OurFamilyWizard expense. It is logged in the shared ledger the co-parent sees immediately, and cannot be deleted through this server.",
       target: "expense:new",
       payload,
       preview: {
-        action: "Log OurFamilyWizard expense",
-        amount: payload.amount,
-        description: payload.description,
-        warning: "Visible to the co-parent immediately as a claim in the shared expense ledger; part of the court-visible record."
+        action: isPrivate ? "Log private OurFamilyWizard expense" : "Log OurFamilyWizard expense",
+        title: args.title,
+        amount: args.amount,
+        purchaseDate: args.purchaseDate,
+        ...expenseParties(args),
+        ...args.description !== void 0 ? { description: args.description } : {},
+        visibility: isPrivate ? "private (only you)" : "shared with the co-parent",
+        ...args.receiptFileId !== void 0 ? { receiptFileId: args.receiptFileId } : {},
+        ...isPrivate ? {} : { warning: "Visible to the co-parent immediately as a claim in the shared expense ledger; part of the court-visible record." }
       },
-      confirmToken
+      confirmToken: args.confirmToken
     });
     if (gate) return gate;
     let data;
     try {
-      data = await requestWrite(client2, "POST", "/pub/v2/expense/expenses", payload);
+      data = await requestWrite(client2, "POST", "/pub/v2/expense", payload);
     } catch (e) {
       if (!(e instanceof UnconfirmedWriteError)) throw e;
       return unconfirmedWriteResponse(e, {
         result: "EXPENSE_UNCONFIRMED",
         what: "log this expense",
-        checkWith: "ofw_list_expenses (look for this amount and description among the newest expenses)"
+        checkWith: `${checkIn} (look for this title and amount among the newest expenses)`
       });
     }
     return jsonResponse(data);
@@ -51088,6 +51509,12 @@ var OFWCache = class _OFWCache extends LocalCacheStore {
   }
 };
 
+// src/tool-surface.ts
+function selectToolRegistrars(r) {
+  if (getExpenseOnly()) return [r.healthcheck, r.expenses];
+  return [r.healthcheck, r.user, r.messages, r.calendar, r.expenses, r.journal];
+}
+
 // src/index.ts
 var originalEmit = process.emit.bind(process);
 process.emit = function(event, ...args) {
@@ -51102,19 +51529,22 @@ process.emit = function(event, ...args) {
 var nodeCache;
 var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
+var expenseRegistrar = (server, deps) => registerExpenseTools(server, deps, nodeAttachmentIO);
+var messageRegistrar = (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO);
+var tools = selectToolRegistrars({
+  healthcheck: registerHealthcheckTools,
+  user: registerUserTools,
+  messages: messageRegistrar,
+  calendar: registerCalendarTools,
+  expenses: expenseRegistrar,
+  journal: registerJournalTools
+});
 await runMcp({
   name: "ofw",
-  version: "2.19.5",
+  version: "2.20.0",
   // x-release-please-version
   deps: client,
-  tools: [
-    registerHealthcheckTools,
-    registerUserTools,
-    (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO),
-    registerCalendarTools,
-    registerExpenseTools,
-    registerJournalTools
-  ],
+  tools,
   banner: "[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion."
 });
 /*! Bundled license information:

package/dist/client.js

@@ -144,7 +144,10 @@ export class OFWClient {
                 throw new Error('Rate limited by OFW API');
         }
         if (!response.ok) {
-            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+            const errorBody = await response.text();
+            const safeBody = redactSecrets(errorBody).replace(/\s+/g, ' ').trim().slice(0, 4000);
+            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}` +
+                (safeBody ? ` — ${safeBody}` : ''));
         }
         return response;
     }