ofw-mcp

MCP server for OurFamilyWizard — provides read/write access to messages, calendar, expenses, and journal.

• npm: npmjs.com/package/ofw-mcp
• Source: github.com/chrischall/ofw-mcp

Setup

Option A — Claude Code (direct MCP, no mcporter)

Add to .mcp.json in your project or ~/.claude/mcp.json:

{
  "mcpServers": {
    "ofw": {
      "command": "npx",
      "args": ["-y", "ofw-mcp"],
      "env": {
        "OFW_USERNAME": "[email protected]",
        "OFW_PASSWORD": "yourpassword"
      }
    }
  }
}

Option B — mcporter

#### 1. Install

npm install -g ofw-mcp

Or from source:

git clone https://github.com/chrischall/ofw-mcp
cd ofw-mcp
npm install && npm run build

#### 2. Configure credentials

cp .env.example .env
# Edit .env: set OFW_USERNAME and OFW_PASSWORD

#### 3. Register with mcporter

mcporter config add ofw \
  --command "ofw-mcp" \
  --env "[email protected]" \
  --env "OFW_PASSWORD=yourpassword" \
  --config ~/.mcporter/mcporter.json

#### 4. Verify

mcporter list --config ~/.mcporter/mcporter.json
mcporter call ofw.ofw_get_profile --config ~/.mcporter/mcporter.json

Calling tools (mcporter)

mcporter call ofw.<tool_name> [key=value ...] --config ~/.mcporter/mcporter.json

Always pass --config ~/.mcporter/mcporter.json unless a local config/mcporter.json exists.

Tools

User

Messages

Calendar

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

Recording reimbursement (not sending money)

Use ofw_mark_expense_reimbursed only after the user explicitly says the FULL remaining balance was reimbursed outside OFW. Require expectedRemainingAmount in currency units and exact cents, matching amount.leftToPay, not amount.total or a guessed half. Show the tool's complete preview and irreversible warning, confirm the author/payer ids refer to the intended parents, and wait for explicit approval before returning the single-use confirmToken with identical args. This is a status-only record: it never pays anyone or accesses payment/bank endpoints and supports no partial reimbursement. It is absent in upload-only mode and in write modes none/drafts.

The tool refuses pending/unknown statuses or unreadable financial details, binds the full current detail to confirmation, re-GETs immediately before writing, and verifies paid/zero/external-marker plus unchanged expense fields afterward. An already paid zero balance is a no-op, not a new reimbursement. On EXPENSE_REIMBURSEMENT_UNCONFIRMED (mayHaveLanded=true), inspect the expense in the OFW web app; never automatically replay or roll back. Pre-write checks are best-effort, not atomic against concurrent edits. See README's external reimbursement section for the exact endpoint and verification contract.

Journal

Response shape (view)

ofw_list_messages, ofw_get_message and ofw_list_drafts take view: "compact" | "full", and `compact` is the default — you get the slim shape without asking. It measured 135.1 KB → 41.1 KB on a real 50-message page.

What compact drops is listData, OFW's echo of the list payload. That blob was 58% of the response and 78% of it duplicated fields the same object already emits at the top level — eleven pre-formatted renderings of one timestamp, eight fields per recipient beside the three the row already normalised, and a preview that is a truncation of the body in the same object.

Two things about compact that will surprise you if you don't know them:

• The sender is `from`, not `fromUser`. fromUser is the empty string on

every row — inbox and sent alike — because OFW names the sender only inside listData.author. So compact promotes it. Dropping listData without that would have taken the sender off every message; this is the one field the fat blob was carrying alone.

• On a draft, `ofw_get_message` returns `from: null` — a draft is unsent, so

there is no sender, and "" would read as one we failed to find.

Pass view: "full" when you need a field compact dropped — listData and everything in it. There is deliberately no `raw` rung: a message here is assembled from a list item, a detail GET and derived fields, so there is no single upstream payload to hand back, and a rung that skipped normalisation would put naive local times back beside UTC ones on exactly the rung you reach for when something already looks wrong.

ofw_get_unread_sent takes no view: it emits a verdict list ({id, subject, sentAt, unreadBy}) that is already narrower than the projection.

Freshness, completeness, and lifecycle

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:

• 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

Check inbox:

1. ofw_list_message_folders → find inbox folder ID
2. ofw_list_messages(folderId) → list messages
3. ofw_get_message(messageId) → read a specific message

Send a message:

1. ofw_get_profile → get co-parent's user ID
2. ofw_send_message(subject, body, [coParentId])

Reply to a message (with thread history):

1. ofw_get_message(messageId) → read the message to reply to
2. ofw_send_message(subject, body, [coParentId], replyToId: messageId) — original message is included in the thread

Draft before sending (sensitive messages):

1. ofw_save_draft(subject, body) → review with user; note the returned draftKey and revision
2. ofw_send_message(draftId, recipientIds, expectedRevision) after approval — sends the server's copy of the draft (no body re-supply), refuses if it changed since review, and deletes the draft only after the send is confirmed

Check what's coming up:

• ofw_get_notifications for a quick summary
• ofw_list_events(today, +30days) for calendar detail

Caution

• Always confirm before sending messages or deleting anything — OFW is a legal co-parenting record.
• The server enforces it for co-parent-visible writes. ofw_send_message, ofw_create_expense, shared-event ofw_create_event/ofw_update_event/ofw_delete_event and SHARED ofw_upload_attachment either raise a confirmation prompt (unless the server sets MCP_CONFIRM_ELICITATION=off) or, on clients that cannot (claude.ai, Claude Desktop) and whenever that is set, return status: "confirmation-required" with a preview and a confirmToken and write nothing. Show the user the preview, get their approval, then repeat the SAME call with confirmToken. A DRAFT_CHANGED refusal means the arguments or the target changed since the preview — show the fresh preview it returns and ask again.
• *`_UNCONFIRMED means it may have landed.** Never retry a SEND_/EXPENSE_/EVENT_/JOURNAL_UNCONFIRMED` write until the matching list/sync shows it did not.
• 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. 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.