ofw-mcp 2.11.0 → 2.13.0

package/dist/client.js

@@ -3,6 +3,7 @@ import { TokenManager } from '@chrischall/mcp-utils/session';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveAuth } from './auth.js';
+import { createSessionCache, reportCacheWriteFailure } from './session-cache.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
@@ -62,9 +63,9 @@ export class OFWClient {
     // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
     // (proactive refresh inside the skew window, single-flight refresh so a burst
     // of concurrent callers coalesces onto ONE `resolveAuth()`, and a 401-replay
-    // guarded against double-refresh). It is created lazily, seeded with an
-    // already-expired placeholder token so the first request drives the refresh
-    // callback — i.e. the original "log in on first request" behavior.
+    // guarded against double-refresh). It is created lazily, and mints on first
+    // use through the function form of `initial` — see `mint` below for why that
+    // form rather than a seeded placeholder.
     tokenManager;
     // Optional injected auth resolver. When set, the refresh callback uses it
     // instead of the module-level global `resolveAuth` (env-var → fetchproxy
@@ -78,22 +79,33 @@ export class OFWClient {
     }
     getTokenManager() {
         if (!this.tokenManager) {
+            // Minting and renewing are the SAME operation here — OFW has no refresh
+            // grant — so one function serves as both `initial` and `refresh`. It has
+            // to be the function form: the eager object form skips persistence, so
+            // the expired placeholder that used to sit here would have meant the
+            // cache was written but never read.
+            const mint = async () => {
+                const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
+                return {
+                    accessToken: token,
+                    refreshToken: OFW_REFRESH_SENTINEL,
+                    expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime(),
+                };
+            };
             this.tokenManager = new TokenManager({
-                initial: { accessToken: '', refreshToken: OFW_REFRESH_SENTINEL, expiresAt: 0 },
+                initial: mint,
+                persistence: createSessionCache({ injectedResolver: this.authResolver !== undefined }) ?? undefined,
+                onPersistError: reportCacheWriteFailure,
+                // A failed renewal IS a failed login here, so the library's
+                // re-mint-on-revoked recovery would just repeat the call that failed.
+                isRefreshRevoked: () => false,
                 skewMs: OFW_TOKEN_EXPIRY_SKEW_MS,
                 // Map OFW's mint/refresh onto the refresh callback. `resolveAuth()`
                 // returns a token and a best-effort expiry; when the fetchproxy path
                 // can't supply one we fall back to the same 6h estimate the password
                 // path uses (the 401-replay covers a wrong guess). We re-arm the
                 // sentinel so the manager can refresh again later.
-                refresh: async () => {
-                    const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
-                    return {
-                        accessToken: token,
-                        refreshToken: OFW_REFRESH_SENTINEL,
-                        expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime(),
-                    };
-                },
+                refresh: mint,
             });
         }
         return this.tokenManager;

package/dist/index.js

@@ -35,7 +35,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.11.0', // x-release-please-version
+    version: '2.13.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/session-cache.js

@@ -0,0 +1,78 @@
+import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { readEnvVar, parseBoolEnv } from '@chrischall/mcp-utils';
+/**
+ * Where the OFW session token is cached between runs.
+ *
+ * OFW has no OAuth refresh token — every renewal re-runs the full
+ * `resolveAuth()` (a password POST, or a fetchproxy snapshot). The token itself
+ * is good for six hours (`OFW_TOKEN_TTL_MS`), so on a scale-to-zero host, where
+ * children idle out after ten minutes and every start is a cold one, the same
+ * six-hour token was being re-minted many times over. Caching it turns those
+ * restarts into zero-cost ones; an expired token still costs exactly what it did
+ * before.
+ */
+export function sessionCachePath(env = process.env) {
+    return resolveStateFile({
+        env,
+        envVar: 'OFW_SESSION_FILE',
+        subdir: '.ofw-mcp',
+        fileName: 'session.json',
+    });
+}
+/** Only a token pair is ever stored — never the username or password. */
+function isTokens(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const t = raw;
+    return (typeof t.accessToken === 'string' &&
+        t.accessToken !== '' &&
+        typeof t.expiresAt === 'number' &&
+        (t.refreshToken === undefined || typeof t.refreshToken === 'string'));
+}
+/**
+ * The session cache, or `null` when it must not be used.
+ *
+ * Three ways it comes back `null`, each deliberate:
+ *
+ *  - `OFW_SESSION_CACHE=false` — the operator opted out.
+ *  - **A caller-injected auth resolver.** That is the per-user hosted path, and
+ *    this registration declares no `identity.perUserChild`, so one process can
+ *    serve several people. A single cache file would hand one user's session to
+ *    the next; until the child is per-user, that path simply does not cache.
+ *  - **No env credentials.** The fetchproxy path authenticates from a signed-in
+ *    browser tab rather than a stored secret, so there is nothing stable to bind
+ *    a cached token to — and it is local-only, where cold starts are rare.
+ *
+ * When it is used, the record is bound to the credentials that minted it, so
+ * rotating either discards it. Only a salted digest is written.
+ */
+export function createSessionCache(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (opts.injectedResolver === true)
+        return null;
+    if (!parseBoolEnv('OFW_SESSION_CACHE', { env, default: true }))
+        return null;
+    const username = readEnvVar('OFW_USERNAME', { env });
+    const password = readEnvVar('OFW_PASSWORD', { env });
+    if (username === undefined || password === undefined)
+        return null;
+    return createFileStatePersistence({
+        filePath: sessionCachePath(env),
+        // Joined on a NUL, written as an escape rather than a literal byte: a
+        // password may contain spaces, so a space-joined pair could collide with
+        // a different pair by shifting the boundary between the two halves.
+        boundTo: [username.trim().toLowerCase(), password].join('\u0000'),
+        validate: (raw) => (isTokens(raw) ? raw : null),
+    });
+}
+/**
+ * Report a cache write that failed. Not fatal: OFW tokens are re-mintable from
+ * the credentials in the environment, so a lost write costs the next start a
+ * login rather than access. Still worth saying — a read-only data dir otherwise
+ * looks exactly like a server that never caches. stderr only; stdout is JSON-RPC.
+ */
+export function reportCacheWriteFailure(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`[ofw-mcp] could not cache the session token (${detail}); continuing without the ` +
+        'cache — every restart will re-authenticate until this is fixed.');
+}

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.11.0",
+  "version": "2.13.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -21,19 +21,21 @@
     ".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",
-    "@fetchproxy/bootstrap": "^2.0.0",
+    "@chrischall/mcp-utils": "^0.18.0",
+    "@fetchproxy/bootstrap": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

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