ofw-mcp: Instructions file for Claude Code

ofw-mcp

MCP server for OurFamilyWizard (OFW). Reads/writes messages, calendar, expenses, and journal; backs message tools with a local SQLite cache. stdio transport.

Commands

npm run build        # tsc → dist/, then esbuild bundle → dist/bundle.js
npm test             # tsc typecheck + vitest run (all tests)
npm run test:watch   # vitest in watch mode
npm run dev          # node --env-file=.env dist/index.js (requires built dist)

dist/ is gitignored — it is produced at build/release time and shipped in the npm package (package.json files).

Session cache

src/session-cache.ts caches the bearer token at $MCP_DATA_DIR/.ofw-mcp/session.json (0600, OFW_SESSION_FILE overrides) via createFileStatePersistence + resolveStateFile (@chrischall/mcp-utils/session).

OFW has no refresh grant — renewing IS logging in — so mint() serves as both initial and refresh on the TokenManager, and isRefreshRevoked: () => false turns off the library's re-mint-after-a-failed-refresh recovery, which here would just repeat the call that failed. The token lasts six hours, so on a scale-to-zero host the cache turns most cold starts into zero-cost ones.

Because nothing in the TokenManager remembers a failed mint, loginWithPassword latches a definitive credential rejection (OFW re-rendering its HTML login page): it keeps a SHA-256 of the rejected username+password pair in memory and refuses that pair locally with CredentialsRejectedError until the env values change or the process restarts. OFW counts failed sign-ins against the account, so a stale password must not be re-POSTed on every tool call. Transient failures (5xx, timeouts) do not latch. tests/_setup.ts resets the latch between tests.

The cache is disabled in three cases, each deliberate: OFW_SESSION_CACHE=false; an injected resolveAuth (the per-user hosted path — this registration declares no identity.perUserChild, so one process can serve several people and a shared file would hand one user's session to the next); and no env credentials (the fetchproxy path authenticates from a browser tab, with nothing stable to bind a record to).