ofw-mcp 2.10.2 → 2.12.0

package/mint.yaml

@@ -0,0 +1,143 @@
+version: 1
+name: OurFamilyWizard
+slug: ofw
+summary: >-
+  OurFamilyWizard co-parenting tools for Claude — messages, calendar,
+  expenses, and journal
+#
+# Hosting note (a comment, not user-facing summary text): this is a
+# BROWSER-BRIDGE MCP — it reaches its site through the user's signed-in
+# tab via the fetchproxy bridge. A bridged registration also needs runtime
+# `fly-shared`, `bridge: true` and a `bridgePortEnv`, which are registration
+# fields this manifest has no schema for (set them over the control API).
+# `state.dataDir` below is required for `bridge`.
+env:
+  - name: OFW_USERNAME
+    required: false
+    help: >-
+      Your OurFamilyWizard login email address. Optional — if omitted, the
+      server falls back to the fetchproxy browser extension (requires being
+      signed in to ourfamilywizard.com).
+  - name: OFW_PASSWORD
+    secret: true
+    required: false
+    help: >-
+      Your OurFamilyWizard password. Optional — see OFW_USERNAME.
+  - name: OFW_WRITE_MODE
+    required: false
+    help: >-
+      Write-tool gate: "none" registers no write tools; "drafts" registers
+      draft-level writes only (save/delete drafts, upload attachments); "all"
+      registers everything (default). Unrecognized values fail closed to "none".
+  - name: OFW_CALENDAR_WRITES
+    required: false
+    help: >-
+      Set to "true" to register calendar write tools (create/update/delete
+      event) in "drafts" write mode. Events have no draft stage but are
+      reversible. Never overrides "none".
+  - name: OFW_ALLOW_MARK_READ
+    required: false
+    help: >-
+      Default "true". Set "false" to forbid any tool from marking a message read
+      on OurFamilyWizard - reading a body for the first time stamps a
+      co-parent-visible "First Viewed" time that cannot be undone. A ceiling: no
+      per-call argument can raise it.
+  - name: OFW_FETCH_UNREAD_BODIES
+    required: false
+    help: >-
+      Default "false". Whether ofw_sync_messages fetches unread inbox bodies by
+      default (each fetch stamps a First Viewed time). Capped by
+      OFW_ALLOW_MARK_READ.
+  - name: OFW_INLINE_ATTACHMENTS
+    required: false
+    help: >-
+      When on, ofw_download_attachment returns bytes inline as MCP content
+      (images render directly; other files come back as embedded resources)
+      instead of writing to disk. Recommended for sandboxed hosts like Claude
+      Desktop where the model cannot read files written to ~/Downloads. Callers
+      can still override per-call via the tool's `inline` argument.
+  - name: OFW_ATTACHMENTS_DIR
+    required: false
+    help: >-
+      Directory where ofw_download_attachment writes files when not returning
+      inline. Defaults to ~/Downloads/ofw-mcp/. Pick a directory that is
+      readable by your MCP host.
+  - name: DISPLAY_TZ
+    required: false
+    help: >-
+      IANA time zone (e.g. America/New_York) that every rendered *…Display*
+      field uses, and the zone a naive OFW timestamp is assumed to be in. Must
+      match the OFW account's own zone. Never a fixed offset — that would be an
+      hour wrong for half the year.
+  - name: OFW_DEBUG_LOG
+    required: false
+    help: >-
+      Set to 1 to write verbose request/response diagnostics to stderr. Off by
+      default; useful when a read is failing and you need to see the upstream
+      exchange.
+  - name: OFW_AUTO_REFRESH
+    required: false
+    help: >-
+      Set to true and read tools sync the backing folders themselves and answer
+      from the refreshed cache, instead of refusing a stale read. The refusal
+      still fires if the refresh does not make the read verifiable.
+  - name: OFW_CACHE_DIR
+    required: false
+    help: >-
+      Directory for persisted session/cache state. Relates to state.dataDir
+      below; leave unset to use the default under $HOME.
+  - name: OFW_CACHE_IDENTITY
+    required: false
+    help: >-
+      Labels the per-user SQLite cache file. Useful when authenticating via the
+      browser bridge, where OFW_USERNAME is not set and the cache would
+      otherwise fall back to a shared default name.
+  - name: OFW_DISABLE_FETCHPROXY
+    required: false
+    help: >-
+      Set to 1 to disable the browser-bridge fallback, making missing
+      credentials a hard error. Recommended for a hosted registration, which has
+      no browser to fall back to.
+  - name: OFW_FRESHNESS_TTL_SECONDS
+    required: false
+    help: >-
+      Age in seconds past which a read result's freshness block downgrades to
+      "unverified" and grows a warning (default 300). Unset means never
+      downgrade.
+  - name: OFW_REQUEST_TIMEOUT_MS
+    required: false
+    help: >-
+      Per-request timeout in milliseconds. Raise it if calls time out on slow
+      upstream responses.
+  - name: OFW_SYNC_MAX_REQUESTS
+    required: false
+    help: >-
+      Caps the OFW requests one ofw_sync_messages call may make before pausing;
+      the next call resumes where it left off. Set a positive integer when
+      hosted, where a per-call request cap can otherwise truncate a deep
+      backfill.
+  - name: OFW_SESSION_CACHE
+    required: false
+    help: >-
+      Set to false to disable the on-disk session cache and re-authenticate on
+      every process start. Defaults to enabled.
+  - name: OFW_SESSION_FILE
+    required: false
+    help: >-
+      Absolute path for the session cache file. Defaults to
+      $MCP_DATA_DIR/.ofw-mcp/session.json.
+state:
+  dataDir: true
+  reason: >-
+    Two things live here. The fetchproxy identity is at
+    $HOME/.fetchproxy/identity/<name>.json and the pair code derives from it —
+    without a persistent $HOME every cold start mints a fresh identity and
+    re-prompts pairing in the browser, and the API refuses bridge without it.
+    The session token is cached at $MCP_DATA_DIR/.ofw-mcp/session.json (0600);
+    OFW has no refresh grant, so without it every cold start re-runs the full
+    login for a token that was still good for up to six hours.
+egress:
+  allow:
+    # Only hosts the SERVER process actually fetches. Hosts that appear
+    # solely in a URL this server BUILDS and returns are excluded.
+    - ofw.ourfamilywizard.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.10.2",
+  "version": "2.12.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -21,18 +21,20 @@
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node --env-file=.env dist/index.js",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test": "npm run typecheck && vitest run",
+    "test:coverage": "npm run typecheck && vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.18.0",
     "@fetchproxy/bootstrap": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.10.2",
+  "version": "2.12.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.10.2",
+      "version": "2.12.0",
       "transport": {
         "type": "stdio"
       },
@@ -52,6 +52,18 @@
           "description": "Default \"false\". Whether ofw_sync_messages fetches unread inbox bodies by default (each fetch stamps a First Viewed time). Capped by OFW_ALLOW_MARK_READ.",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_SESSION_CACHE",
+          "description": "Set to false to disable the on-disk session cache and re-authenticate on every process start. Defaults to enabled.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_SESSION_FILE",
+          "description": "Absolute path for the session cache file. Defaults to $MCP_DATA_DIR/.ofw-mcp/session.json.",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/ofw/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ofw-mcp
+name: ofw
 description: This skill should be used when the user asks about OurFamilyWizard (OFW) co-parenting data. Triggers on phrases like "check OFW", "OurFamilyWizard inbox", "OFW messages", "OFW calendar", "OFW expenses", "what did my co-parent say", "log an expense in OFW", "OFW journal", or any request involving co-parenting messages, calendar events, shared expenses, or journal entries.
 ---
 
@@ -92,11 +92,11 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 |------|-------|
 | `ofw_sync_messages(folders?, deep?, fetchUnreadBodies?)` | Sync OFW → local cache. **Call first if the cache might be stale.** Returns unread inbox hints (bodies not fetched, to avoid mark-as-read). |
 | `ofw_list_message_folders` | List OFW folders with unread counts. Most reads use the cache; this is mainly for folder IDs and live unread counts. |
-| `ofw_list_messages(folderId?, since?, until?, q?, page?, size?, autoRefresh?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. Returns `complete` for the RESULT SET. An **empty** result from a non-fresh cache is refused (`UNVERIFIED_EMPTY`) — pass `autoRefresh:true` to sync and answer instead. |
+| `ofw_list_messages(folderId?, since?, until?, q?, sort?, page?, size?, autoRefresh?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. `sort:"oldest"` starts at the old end of a range instead of paging to it (default `"newest"`). Returns `complete` for the RESULT SET plus **`nextPage`** (null when done) — and the paging keys come FIRST in the JSON, before `messages`. `returned` carries the record count as a scalar, beside `total`. An **empty** result from a non-fresh cache is refused (`UNVERIFIED_EMPTY`) — pass `autoRefresh:true` to sync and answer instead. |
 | `ofw_get_message(messageId, allowMarkRead?)` | Read a message OR draft body. Cache-first. Ids in the drafts cache return `folder: "drafts"`. ⚠️ Falls through to OFW for unread inbox messages, which marks them read AND stamps a "First Viewed" time the co-parent can see — irreversible. Pass `allowMarkRead:false` to refuse that fetch instead; cached, sent and already-read messages are unaffected. |
 | `ofw_send_message(draftId?, subject?, body?, recipientIds?, replyToId?, expectedRevision?, deleteDraftOnSuccess?, myFileIDs?, force?)` | Send a message — **the one irreversible operation**. Preferred path: pass `draftId` (+ `expectedRevision`) to send an existing draft **as it exists on the server** — the tool re-reads it from OFW first and refuses if it changed since you read it (or was already sent/deleted); `subject`/`body` become optional overrides. `recipientIds` is usually still required: OFW does not store recipients on drafts. After a **confirmed** send the draft is auto-deleted (`deleteDraftOnSuccess:false` to keep it); on any failure or ambiguity it is retained and the response says why (`draftRetained`). Response leads with `sentMessageId`, `draftKey`, `threaded`, `draftDeleted`. Compose from scratch by passing `subject`/`body`/`recipientIds` with no `draftId`. |
-| `ofw_get_unread_sent(page?, size?, autoRefresh?)` | Sent messages your co-parent hasn't read yet (from cache). Reports `scanned`/`total`/`complete`; an empty sent cache that is not fresh is refused rather than reported as "nothing sent". |
-| `ofw_list_drafts(page?, size?, verify?, autoRefresh?)` | List saved drafts, **auto-verified**: when the cache is not verified-fresh a cheap drafts sync runs first (default `verify:true`), so one call answers server-confirmed. `verify:false` serves straight from cache. Each draft carries `serverConfirmed`, `revision` and `draftKey`. Returns `complete` — **check it before saying "you have N drafts"**. See [Freshness](#freshness). |
+| `ofw_get_unread_sent(page?, size?, autoRefresh?)` | Sent messages your co-parent hasn't read yet (from cache). Leads with `complete`/`hasMore`/`nextPage`, then `scanned`/`total`, then `unread`; an empty sent cache that is not fresh is refused rather than reported as "nothing sent". |
+| `ofw_list_drafts(page?, size?, verify?, autoRefresh?)` | Leads with `complete`/`hasMore`/`nextPage`; `drafts` comes last. List saved drafts, **auto-verified**: when the cache is not verified-fresh a cheap drafts sync runs first (default `verify:true`), so one call answers server-confirmed. `verify:false` serves straight from cache. Each draft carries `serverConfirmed`, `revision` and `draftKey`. Returns `complete` — **check it before saying "you have N drafts"**. See [Freshness](#freshness). |
 | `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`. |
@@ -133,6 +133,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 |
 | Is this entity still what I think it is? | `state` from `ofw_status` / `ofw_check_freshness` |
 
 Rules: