ofw-mcp 2.19.5 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "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 — developed and maintained by AI (Claude Code)",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.19.5",
+  "version": "2.20.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.19.5",
+      "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

@@ -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/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