ofw-mcp 2.7.1 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.7.1",
+  "version": "2.9.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.7.1",
+  "version": "2.9.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.7.1",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },
@@ -40,6 +40,18 @@
           "description": "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\".",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_ALLOW_MARK_READ",
+          "description": "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.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "OFW_FETCH_UNREAD_BODIES",
+          "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"
         }
       ]
     }

package/skills/ofw/SKILL.md

@@ -93,16 +93,17 @@ 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?)` | Cache-backed list. Supports folder ("inbox"/"sent"/"both"), date range, and substring search. |
-| `ofw_get_message(messageId)` | 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 as read. |
+| `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_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(subject, body, recipientIds[], replyToId?, draftId?, myFileIDs?)` | Send a message. Pass `replyToId` to thread original history. Pass `draftId` to auto-delete the draft after sending. Pass `myFileIDs` (from `ofw_upload_attachment`) to attach files. |
-| `ofw_get_unread_sent` | Sent messages your co-parent hasn't read yet (from cache). |
-| `ofw_list_drafts` | List saved drafts (cache-backed). Each draft carries `serverConfirmed` — see [Freshness](#freshness). |
-| `ofw_save_draft(subject, body, recipientIds?, messageId?, replyToId?, myFileIDs?)` | 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 includes a `NOTE` documenting the swap. |
+| `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?, autoRefresh?)` | List saved drafts (cache-backed). Each draft carries `serverConfirmed`, `revision` and `draftKey`. Returns `complete` — **check it before saying "you have N drafts"**. An empty result from a non-fresh cache is refused. 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 includes a `NOTE` documenting the swap. It also returns a `draftKey` that stays the same across every edit — **track that, not the id**. |
 | `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`. |
-| `ofw_download_attachment(fileId, inline?, saveTo?, force?)` | Download an attachment. `inline:true` returns bytes as MCP content; default writes to `~/Downloads/ofw-mcp/`. |
-| `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. Use before asserting current state. Only probes ids in the drafts cache unless `allowMarkRead:true` (probing others marks inbox messages read). |
+| `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_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. |
 
 ### Calendar
 | Tool | Notes |
@@ -125,18 +126,36 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 | `ofw_list_journal_entries(start?, max?)` | 1-based offset; default max 10 |
 | `ofw_create_journal_entry(title, body)` | Create a new entry |
 
-## Freshness
+## Freshness, completeness, and lifecycle
 
-Message and draft reads come from a local cache, so **a result can be stale without looking stale**. Every read tool returns a `freshness` block: `staleness` (`fresh`/`unverified`/`stale`), `asOf`, `ageSeconds`, and a `warning` whenever it is not `fresh`. Drafts additionally carry `serverConfirmed`.
+Message and draft reads come from a local cache, so **a result can be stale without looking stale**. Three separate questions, three separate signals — do not substitute one for another:
 
-Rules for using it:
+| Question | Signal |
+|---|---|
+| 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` |
+| Is this entity still what I think it is? | `state` from `ofw_status` / `ofw_check_freshness` |
 
-- **Never state current state from memory.** If you saved a draft earlier in the session, that is not evidence it still exists unsent now — the user may have sent or deleted it in the web app since.
-- **`serverConfirmed: false` means "remembered, not known."** Do not say a draft "is still sitting unsent" on that basis. Call `ofw_check_freshness(messageIds: [id])` first, or say plainly that you are reporting cached state and give its age.
-- **If `freshness.staleness` is not `fresh`, either re-read or surface the caveat** in your answer. The `warning` string is written to be quotable.
-- OFW does **not** bump a draft's timestamp when it is edited in the web app, which is why freshness is tracked separately and compared by content revision. "Nothing changed" and "we didn't look" are otherwise indistinguishable.
+Rules:
+
+- **Verification is cheaper than recollection. Use it.** Any status summary about drafts costs exactly one `ofw_status()` call. There is no situation in which recalling an earlier tool result is the better option.
+- **Never state current state from memory.** A draft you saved earlier in the session is not evidence it still exists unsent now — the user may have sent, edited or deleted it in the web app since. This has gone wrong twice: drafts described as "still sitting unsent" that had already been sent.
+- **`existsOnServer` does not mean "still a draft".** A draft that was SENT still exists on the server. Only `state` distinguishes them.
+- **Check `complete` before quoting a count.** `complete: false` means the result set is a slice, or unverified, or both — `completeNote` says which. "You have 3 drafts" requires `complete: true`.
+- **`serverConfirmed: false` means "remembered, not known."** Call `ofw_status` / `ofw_check_freshness` first, or say plainly that you are reporting cached state and give its age.
+- **A refusal is a good outcome.** `result: "UNVERIFIED_EMPTY"` means the tool declined to report an absence it could not verify. Do the `remedy` — never re-report it as "nothing found". A wrong "no, that was never sent" is far costlier here than one extra call.
+- **`state: "unknown"` is not "fine".** It means the question was not answered.
+- OFW does **not** bump a draft's timestamp when it is edited in the web app, which is why freshness is compared by content revision. "Nothing changed" and "we didn't look" are otherwise indistinguishable.
 - A missing folder count in `ofw_sync_messages` output means that folder was **not checked** — it is never "no changes". Check `notRefreshed`.
 
+### Draft identity (`draftKey`)
+
+Editing a draft mints a **new OFW id every time** — `ofw_save_draft` replaces by create-then-delete, so one message can burn through ten ids in a session. Track the `draftKey` it returns, not the id:
+
+- `ofw_status(draftKeys: ["dk_…"])` resolves the key to the chain's **current** id and state.
+- The key keeps resolving after the draft is sent: `state: "sent"` with `sentMessageId` and `sentAt`.
+- `draftKey: null` on a draft means it was authored outside this tool; it is adopted into a chain the first time you save over it.
+
 
 ## Workflows
 
@@ -166,4 +185,4 @@ Rules for using it:
 - **Always confirm before sending messages or deleting anything** — OFW is a legal co-parenting record.
 - `ofw_get_notifications` updates last-seen status — avoid calling silently in the background.
 - `ofw_get_message` marks messages read — warn the user if they want to keep something unread.
-- **Do not narrate cached state as present fact.** Check `freshness`/`serverConfirmed` before saying what "is" true on OFW right now, and prefer `ofw_check_freshness` over guessing — it is one cheap call.
+- **Do not narrate cached state as present fact.** Before saying what "is" true on OFW right now, call `ofw_status` — one live round trip that answers drafts, ids and draft keys at once. Never assemble a status summary from earlier tool results in the conversation; re-read.