ofw-mcp 2.19.4 → 2.20.0

package/dist/tools/healthcheck.js

@@ -62,7 +62,7 @@ resolve = resolveAuth) {
                 kind: 'transport',
                 // The upstream `.hint` rides along in `error.message` — it carries
                 // the actionable "click the toolbar icon" copy this cannot know.
-                hint: 'The fetchproxy bridge is down, so the browser path could not be tried. This is ' +
+                hint: 'ContextMint Bridge is down, so the browser path could not be tried. This is ' +
                     'not a credential problem: OFW_USERNAME/OFW_PASSWORD, if set, were not reached ' +
                     'either. See error.message for the extension-specific fix.',
             }
@@ -71,7 +71,7 @@ resolve = resolveAuth) {
             // Now means exactly what it says: nothing is set up. A configured path
             // that was tried and failed no longer lands here.
             no_credential: 'No OFW credential is configured. Either set OFW_USERNAME + OFW_PASSWORD, or install ' +
-                'the fetchproxy extension and sign in to ourfamilywizard.com in a tab (unsetting ' +
+                'ContextMint Bridge and sign in to ourfamilywizard.com in a tab (unsetting ' +
                 'OFW_DISABLE_FETCHPROXY if you set it).',
             credential_rejected: 'OurFamilyWizard rejected the credential. If it came from `env`, the password changed or ' +
                 'the account is locked; if from `fetchproxy`, the browser session expired — sign in again ' +

package/dist/tools/messages.js

@@ -1526,7 +1526,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             });
         });
     server.registerTool('ofw_download_attachment', {
-        description: 'Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT — per-sheet CSV, per-page/slide text, document text — in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing — a saveTo path never costs you the content. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo; saveTo must stay inside the attachments directory, and an existing file is never overwritten unless force:true. Re-downloading to the same path is a no-op (disk mode only).',
+        description: 'Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT — per-sheet CSV, per-page/slide text, document text — in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. Images and raw bytes are only returned inline up to 10 MiB; a larger file fails with a tool error that says how to get it instead (extracted text is unaffected — it is bounded by maxChars). The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing — a saveTo path never costs you the content. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo; saveTo must stay inside the attachments directory, and an existing file is never overwritten unless force:true. Re-downloading to the same path is a no-op (disk mode only).',
         annotations: { readOnlyHint: false, destructiveHint: false },
         inputSchema: z.object({
             fileId: z.number().describe('Attachment file id (from ofw_get_message → attachments[].fileId)'),
@@ -1581,6 +1581,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             // ends up holding something readable.
             return await buildInlineDelivery({
                 fileId, fileName, mimeType, bytes, forcedInline, options: deliveryOptions,
+                diskAvailable: attachmentIO.supportsDisk,
             });
         }
         let dest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.19.4",
+  "version": "2.20.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -34,8 +34,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.6.0",
-    "@fetchproxy/bootstrap": "^3.2.0",
+    "@chrischall/mcp-utils": "^2.8.0",
+    "@fetchproxy/bootstrap": "^3.4.1",
     "@modelcontextprotocol/server": "^2.0.0",
     "dotenv": "^18.0.0",
     "zod": "^4.6.5"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.19.4",
+  "version": "2.20.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.19.4",
+      "version": "2.20.0",
       "transport": {
         "type": "stdio"
       },
@@ -64,6 +64,18 @@
           "description": "Absolute path for the session cache file. Defaults to $MCP_DATA_DIR/.ofw-mcp/session.json.",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_EXPENSE_ONLY",
+          "description": "Set true to register only healthcheck plus expense tools. All profile/dashboard, message, calendar, and journal tools are structurally absent.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_EXPENSE_UPLOAD_ONLY",
+          "description": "Set true for strict reimbursement upload mode: only healthcheck, ofw_upload_expense_pdf, ofw_create_expense, and ofw_update_expense register. Implies OFW_EXPENSE_ONLY.",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/ofw/SKILL.md

@@ -100,7 +100,7 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 | `ofw_save_draft(subject, body, recipientIds?, messageId?, replyToId?, myFileIDs?, expectedRevision?, force?)` | Create a new draft. Pass `messageId` to **replace** an existing draft: the tool creates a fresh draft and deletes the old one (OFW's update-in-place endpoint silently no-ops). The returned `id` is the NEW id; the response leads with `draftKey`, which stays the same across every edit — **track that, not the id**. Note: OFW does **not** store recipients on drafts — `recipientIds` are accepted but come back empty (a one-line NOTE says so; supply them at send time instead). Threading warnings fire only on genuine drops — a draft echoing `inReplyTo`/`showContext` IS threaded. |
 | `ofw_delete_draft(messageId)` | Delete a draft. |
 | `ofw_upload_attachment(path, shareClass?, label?, description?)` | Upload a local file to My Files; returns a fileId to pass into `myFileIDs`. Only files inside the upload directory (`OFW_UPLOAD_DIR`, default `~/Downloads/ofw-mcp`) can be uploaded; hidden files are refused. `shareClass:"SHARED"` needs write mode `all`. |
-| `ofw_download_attachment(fileId, inline?, saveTo?, force?, extract?, maxChars?, parts?)` | Download an attachment. Inline delivery returns the first rung that works: image → `ImageContent`; .xlsx/.csv/.pdf/.docx/.pptx/text → **extracted content** under `extracted` (per-sheet CSV, per-page/slide text); anything else → raw bytes. Default writes to `~/Downloads/ofw-mcp/` (add `extract:true` for content too). Use `parts:"1-2"` / a sheet name and `maxChars` on large files. |
+| `ofw_download_attachment(fileId, inline?, saveTo?, force?, extract?, maxChars?, parts?)` | Download an attachment. Inline delivery returns the first rung that works: image → `ImageContent`; .xlsx/.csv/.pdf/.docx/.pptx/text → **extracted content** under `extracted` (per-sheet CSV, per-page/slide text); anything else → raw bytes. Default writes to `~/Downloads/ofw-mcp/` (add `extract:true` for content too). Use `parts:"1-2"` / a sheet name and `maxChars` on large files. Images and raw bytes over 10 MiB are not returned inline (tool error) — use disk mode or open the file in OFW. |
 | `ofw_check_freshness(folders?, messageIds?, allowMarkRead?)` | Cheap live check that the cache still matches OFW — one request for folder counts plus one per id, no bodies, no sync. Each id gets a live `state` (`draft`/`sent`/`received`/`deleted`/`unknown`) plus `folder` and `sentAt`. Probes ids cached as drafts, as sent, or as already-read inbox messages freely; anything else needs `allowMarkRead:true` (it would mark an inbox message read). |
 | `ofw_status(ids?, draftKeys?, includeDraftInventory?, allowMarkRead?)` | **The status call.** One live round trip. With no arguments: the full, server-verified draft inventory. With `ids`/`draftKeys`: each one's live lifecycle state. Top-level `complete` is true only when every part was verified live. |
 
@@ -112,12 +112,19 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 | `ofw_update_event(eventId, ...)` | Partial update — only pass fields to change |
 | `ofw_delete_event(eventId)` | Permanent delete |
 
+### Restricted expense deployments
+
+When `OFW_EXPENSE_ONLY=true`, only the healthcheck and expense tools exist. When `OFW_EXPENSE_UPLOAD_ONLY=true`, only `ofw_healthcheck`, `ofw_upload_expense_pdf`, `ofw_create_expense`, and `ofw_update_expense` exist. Do not suggest message/calendar/journal/profile tools in those deployments; they are structurally unregistered.
+
 ### Expenses
 | Tool | Notes |
 |------|-------|
 | `ofw_get_expense_totals` | Summary of owed/paid totals |
-| `ofw_list_expenses(start?, max?)` | Paginated; default max 20 |
-| `ofw_create_expense(amount, description)` | Log a new expense |
+| `ofw_list_expenses(page?, size?)` | Paginated (1-based page); default size 20; follow `nextPage` |
+| `ofw_list_expense_categories` | Category ids and split metadata (use the id in create/update) |
+| `ofw_upload_expense_pdf(path \| url, fileName?, label?, description?)` | Upload one receipt PDF to My Files (SHARED, co-parent-visible even on a private expense) for later attachment; confirm-gated; mode `all` only |
+| `ofw_create_expense(title, amount, purchaseDate, categoryId, payerId, children, description?, privateExpense?, receiptFileId?)` | Log a new expense; confirm-gated; optionally private with one receipt |
+| `ofw_update_expense(expenseId, …only the fields to change…)` | Reads the expense and keeps every field you omit; `privateExpense:false` publishes a private expense; `receiptFileId` replaces all receipts, `null` clears it or `description`; refuses as `EXPENSE_FIELDS_UNREADABLE` (naming the fields) rather than erase one it can't read; confirm-gated |
 
 ### Journal
 | Tool | Notes |
@@ -166,7 +173,7 @@ Message and draft reads come from a local cache, so **a result can be stale with
 |---|---|
 | How old is this data? | `freshness` — `staleness` (`fresh`/`unverified`/`stale`), `asOf`, `ageSeconds`, a quotable `warning` |
 | Is this the WHOLE answer? | `complete` on `ofw_list_messages` / `ofw_list_drafts` / `ofw_get_unread_sent` / `ofw_status` |
-| If not, how do I get the rest? | `nextPage` (message tools) or `nextStart` (`ofw_list_expenses` / `ofw_list_journal_entries`) — null means there is no more |
+| If not, how do I get the rest? | `nextPage` (message tools and `ofw_list_expenses`) or `nextStart` (`ofw_list_journal_entries`) — null means there is no more |
 | Is this entity still what I think it is? | `state` from `ofw_status` / `ofw_check_freshness` |
 
 Rules:

package/skills/ofw-fpx/SKILL.md

@@ -33,13 +33,16 @@ dry-run/confirm here — curl just does it. Treat every write like the MCP's
 npm install -g @fetchproxy/cli                                       # provides `fpx`
 fpx profile add ofw --domain ourfamilywizard.com
 fpx profile declare ofw --local-storage auth --local-storage tokenExpiry
-fpx pair -p ofw                                                       # prints a pair code → approve in Transporter
+fpx pair -p ofw                                                       # prints a pair code → approve in ContextMint Bridge
 ```
 
-Requirements: the **Transporter** browser extension installed, with an
+Requirements: the **ContextMint Bridge** browser extension installed
+([releases](https://github.com/nullnet-app/contextmint-bridge/releases) —
+Chrome: load the Chrome zip unpacked; Safari isn't available yet, so use Chrome for now), with an
 open, signed-in `ofw.ourfamilywizard.com` (or `www.ourfamilywizard.com`)
 tab, and its Chrome **Site access** allowing `ourfamilywizard.com`. Pairing
 persists across invocations.
+ContextMint Bridge is the fetchproxy extension renamed, same maintainer (see https://github.com/chrischall/fetchproxy#extension); source at https://github.com/nullnet-app/contextmint-bridge — build it, or verify a release zip with `shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256`.
 
 ## Capture the token (once per shell / whenever it goes stale)
 

package/skills/ofw-fpx/references/requests.md

@@ -197,18 +197,72 @@ curl -s -X DELETE "https://ofw.ourfamilywizard.com/pub/v1/calendar/events/${EVEN
 curl -s 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses/totals' "${AUTH_HEADERS[@]}" | jq .
 ```
 
-**List expenses** (offset-based, 0-indexed `start`):
+**List expenses** (page-based, 1-indexed `page`):
+
+OFW currently ignores the legacy `start`/`max` query parameters and returns
+page 1 repeatedly. Use `page`/`size` and follow the response metadata's
+`last` flag / `currentPage`.
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses?page=1&size=20' "${AUTH_HEADERS[@]}" | jq .
+```
+
+**Upload a receipt PDF** (write to My Files). It must be `SHARED` — that is the
+share class OFW accepts in an expense's `fileIds` — and a SHARED file is
+visible to the co-parent in My Files as soon as it lands:
 
 ```sh
-curl -s 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses?start=0&max=20' "${AUTH_HEADERS[@]}" | jq .
+curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v3/myfiles/multipart' \
+  "${AUTH_HEADERS[@]}" \
+  -F "file=@/path/to/receipt.pdf;type=application/pdf" \
+  -F 'source=expense' \
+  -F 'description=receipt.pdf' \
+  -F 'label=receipt.pdf' \
+  -F 'fileName=receipt.pdf' \
+  -F 'shared=true' \
+  -F 'shareClass=SHARED' | jq .
 ```
 
+Use the returned `fileId` as `receiptFileId` when creating the expense.
+
 **Create an expense** (write):
 
+The current OFW expense form requires a complete expense record. In addition to
+the amount, send the expense title, purchase date, category id, parent who owes
+(`payerId`), and at least one child user id. Description, visibility, and a
+single receipt file are optional.
+
+```sh
+curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v2/expense' \
+  "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' \
+  --data '{
+    "title":"Soccer cleats",
+    "amount":45.00,
+    "purchaseDate":"2026-09-28",
+    "categoryId":1,
+    "payerId":<PAYER_USER_ID>,
+    "children":[<CHILD_USER_ID>],
+    "description":"Cleats for soccer",
+    "isPrivate":false,
+    "fileIds":[<RECEIPT_FILE_ID>]
+  }' | jq .
+```
+
+Use OFW numeric ids, not display labels, for `categoryId`, `payerId`, and
+`children`. For a private expense (visible only to you), send `isPrivate:true`;
+the MCP tools expose this as `privateExpense`. The MCP tools attach at most one
+receipt, sent as a one-element `fileIds` array.
+
+**Update an expense** (write; full payload, not a patch — e.g. publish a
+private expense by sending `isPrivate:false`). A field left out of the PUT is
+erased, so GET the expense first and send back every field you are not
+changing (the MCP's `ofw_update_expense` does this for you):
+
 ```sh
-curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses' \
+curl -s "https://ofw.ourfamilywizard.com/pub/v2/expense/expenses/${EXPENSE_ID}" "${AUTH_HEADERS[@]}" | jq .
+curl -s -X PUT "https://ofw.ourfamilywizard.com/pub/v2/expense/expenses/${EXPENSE_ID}" \
   "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' \
-  --data '{"amount": 45.00, "description": "Cleats for soccer"}' | jq .
+  --data '{ …every current field…, "isPrivate":false }' | jq .
 ```
 
 ## 8. Journal