ofw-mcp 2.0.13 → 2.0.15

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.0.13"
+    "version": "2.0.15"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "OurFamilyWizard",
       "source": "./",
       "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
-      "version": "2.0.13",
+      "version": "2.0.15",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ofw",
   "displayName": "OurFamilyWizard",
-  "version": "2.0.13",
+  "version": "2.0.15",
   "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
   "author": {
     "name": "Chris Chall"

package/README.md

@@ -66,9 +66,15 @@ Quit completely (Cmd+Q on Mac, not just close the window) and relaunch.
 
 Ask Claude: *"What does my OFW dashboard look like?"* — it should show your unread message count, upcoming events, and outstanding expenses.
 
-## Credentials
+## Authentication
 
-Credentials are read from environment variables, with two ways to provide them:
+`ofw-mcp` tries three auth paths in order; whichever succeeds first is used. Existing setups keep working unchanged.
+
+1. **Env-var credentials (legacy, recommended for Claude Desktop).** Set `OFW_USERNAME` + `OFW_PASSWORD` and the server logs in via OFW's form endpoint. This is the path shown in the Claude Desktop config above.
+2. **fetchproxy fallback (no env vars needed).** When the credentials are absent, the server reads `localStorage["auth"]` once at startup from your already-signed-in `ourfamilywizard.com` tab via the [fetchproxy](https://github.com/chrischall/fetchproxy) browser extension. After that one read, all OFW API calls go directly from Node — the extension is **not** in the request hot path. Install the fetchproxy extension (Chrome Web Store / Safari `.dmg`), sign into OurFamilyWizard once, and the MCP just works. If you have multiple OFW accounts and want them to use separate caches, set `OFW_CACHE_IDENTITY` to a label per profile.
+3. **Error.** If neither path is available, the server tells you exactly which fix to apply. Set `OFW_DISABLE_FETCHPROXY=1` to skip the fetchproxy fallback entirely (turns missing credentials into a hard error — useful in headless CI).
+
+### Credential options (env-var path)
 
 **Option A — env block in Claude Desktop config** (shown above, recommended):
 
@@ -121,7 +127,9 @@ Read-only tools run automatically. Write tools ask for your confirmation first.
 
 **"0 messages"** — Claude may have read the notification counts rather than the actual messages. Ask explicitly: *"List the messages in my OFW inbox"* or *"Use ofw_list_message_folders then ofw_list_messages"*.
 
-**"OFW_USERNAME and OFW_PASSWORD must be set"** — credentials are missing. Check the `env` block in your Claude Desktop config or your `.env` file.
+**"OFW auth: set OFW_USERNAME + OFW_PASSWORD, or install the fetchproxy extension…"** — neither auth path is configured. Either fill in the `env` block in your Claude Desktop config, or install the [fetchproxy extension](https://github.com/chrischall/fetchproxy) and sign into `ourfamilywizard.com` in your browser.
+
+**"fetchproxy fallback failed"** — the env-var path wasn't configured and the extension couldn't be reached. Confirm the fetchproxy extension is installed, signed into OFW, and that it's running (open the extension popup). If you want to disable the fallback entirely, set `OFW_DISABLE_FETCHPROXY=1`.
 
 **403 Forbidden** — wrong credentials. Verify your username/password at [ofw.ourfamilywizard.com](https://ofw.ourfamilywizard.com).
 
@@ -162,14 +170,17 @@ tests/
 
 ### Auth flow
 
-OFW uses Spring Security form login:
+Auth resolution lives in `src/auth.ts`. Three paths, in priority order:
+
+1. **Env vars present** → `src/auth-password.ts` does the legacy OFW Spring Security form login:
+   1. `GET /ofw/login.form` — establishes a session cookie
+   2. `POST /ofw/login` — submits credentials, returns `{ auth: "<token>" }`
+2. **Env vars absent (and `OFW_DISABLE_FETCHPROXY` unset)** → `@fetchproxy/bootstrap` reads `localStorage["auth"]` + `localStorage["tokenExpiry"]` once from the user's signed-in `ourfamilywizard.com` tab, then closes the bridge.
+3. **Nothing configured** → throws with both fixes spelled out.
 
-1. `GET /ofw/login.form` — establishes a session cookie
-2. `POST /ofw/login` — submits credentials, returns `{ auth: "<token>" }`
-3. All API calls use `Authorization: Bearer <token>`
-4. On 401, re-authenticates automatically and retries once
+Either path returns a Bearer token to `OFWClient`, which then operates from Node with `Authorization: Bearer <token>` — fetchproxy is **not** in the request hot path. On 401 the client re-resolves auth and replays once. Tokens are cached for 6h (env-var path) or until `tokenExpiry` (fetchproxy path).
 
-Tokens are cached for 6 hours.
+Also see the [fetchproxy README](https://github.com/chrischall/fetchproxy) for extension install instructions.
 
 ## License
 

package/dist/auth-password.js

@@ -0,0 +1,57 @@
+// OFW's existing password-login path.
+//
+// `POST /ofw/login` is Spring Security form-urlencoded; it requires a SESSION
+// cookie that we capture from `GET /ofw/login.form` first. The response body
+// is JSON `{ auth: "<Bearer token>", redirectUrl: "..." }`. OFW does not return
+// a token expiry, so we synthesize a 6h lifetime — long enough to be useful,
+// short enough that a 401 re-auth replay is rare.
+//
+// This file exists as a standalone helper (not a method on `OFWClient`) so
+// `resolveAuth()` in `./auth.ts` can call it without a Client instance, and
+// so tests can mock it at the module boundary.
+const BASE_URL = 'https://ofw.ourfamilywizard.com';
+const OFW_PROTOCOL_HEADERS = {
+    'ofw-client': 'WebApplication',
+    'ofw-version': '1.0.0',
+};
+export async function loginWithPassword(username, password) {
+    // Step 1: get a SESSION cookie (Spring Security refuses the POST without it).
+    const initResponse = await fetch(`${BASE_URL}/ofw/login.form`, {
+        headers: { ...OFW_PROTOCOL_HEADERS },
+        redirect: 'manual',
+    });
+    const setCookie = initResponse.headers.get('set-cookie') ?? '';
+    const sessionCookie = setCookie.split(';')[0];
+    // Step 2: submit the form.
+    const response = await fetch(`${BASE_URL}/ofw/login`, {
+        method: 'POST',
+        headers: {
+            ...OFW_PROTOCOL_HEADERS,
+            Accept: 'application/json',
+            'Content-Type': 'application/x-www-form-urlencoded',
+            ...(sessionCookie ? { Cookie: sessionCookie } : {}),
+        },
+        body: new URLSearchParams({
+            submit: 'Sign In',
+            _eventId: 'submit',
+            username,
+            password,
+        }).toString(),
+    });
+    if (!response.ok) {
+        throw new Error(`OFW login failed: ${response.status} ${response.statusText}`);
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+        const body = await response.text();
+        throw new Error(`OFW login returned unexpected response (${contentType}): ${body.substring(0, 200)}`);
+    }
+    const data = (await response.json());
+    return {
+        token: data.auth,
+        // OFW's login endpoint omits expiry. 6h is the empirical TTL and matches
+        // the historical behavior of this client (a single 401 → re-auth + replay
+        // covers the edge case where this estimate is wrong).
+        expiresAt: new Date(Date.now() + 6 * 60 * 60 * 1000),
+    };
+}

package/dist/auth.js

@@ -0,0 +1,135 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Auth resolution — Pattern A template
+// ────────────────────────────────────────────────────────────────────────────
+//
+// This file is the canonical shape for "browser-bootstrap + Node-direct"
+// auth used across our MCP servers. The other six MCPs in this family
+// (resy-mcp, opentable-mcp, splitwise-mcp, …) will model their auth
+// resolution after this one — keep the structure flat, the path-selection
+// explicit, and the error messages actionable.
+//
+// THE THREE PATHS, in priority order:
+//
+//   1. Env-var credentials (existing behavior)
+//      OFW_USERNAME + OFW_PASSWORD set → POST the login form, get a token.
+//      This is the legacy path. It runs unchanged when both vars are set
+//      so existing users (Claude Desktop with mcpb env config, etc.) are
+//      not disrupted.
+//
+//   2. fetchproxy fallback (new)
+//      When credentials are absent, we try to lift the user's session
+//      out of their signed-in browser tab via the fetchproxy extension.
+//      The `@fetchproxy/bootstrap` helper spins up a one-shot WebSocket
+//      bridge, asks the extension for `localStorage["auth"]` and
+//      `localStorage["tokenExpiry"]` from any ourfamilywizard.com tab,
+//      then closes the bridge. From here on, all OFW API calls go out
+//      via plain Node `fetch()` — fetchproxy is NOT in the hot path.
+//
+//      Users opt out with OFW_DISABLE_FETCHPROXY=1 (anyone who wants the
+//      old behavior of "fail loudly when creds are missing").
+//
+//   3. Error
+//      Nothing to authenticate with. We throw a message that tells the
+//      user exactly what to do: set creds, OR install the extension and
+//      sign in.
+//
+// Why fetchproxy is only a one-shot read:
+//   The bootstrap call snapshots the session blob and returns. The MCP
+//   then operates from Node with direct fetch + Authorization header,
+//   so latency and reliability are not coupled to the browser bridge
+//   for normal tool calls. Pre-PR mcp-chrome and tab-routing concerns
+//   (see opentable-mcp/CLAUDE.md "Bridge selection") do not apply here.
+//
+// Testability:
+//   - `@fetchproxy/bootstrap` is mocked at the module boundary in tests.
+//   - `./auth-password.js` (loginWithPassword) is a separate module
+//     specifically so it can be mocked here too. This keeps the
+//     selection logic independent of either implementation.
+import { bootstrap } from '@fetchproxy/bootstrap';
+import { loginWithPassword } from './auth-password.js';
+import pkg from '../package.json' with { type: 'json' };
+/**
+ * Read an env var, trim, and treat blank / `${UNEXPANDED}` placeholders as
+ * unset. Defends against MCP hosts that pass `.mcp.json` env blocks through
+ * without variable expansion.
+ */
+function readEnv(key) {
+    const raw = process.env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === 'undefined' || trimmed === 'null')
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+/** True if the user has explicitly disabled the fetchproxy fallback. */
+function fetchproxyDisabled() {
+    const raw = readEnv('OFW_DISABLE_FETCHPROXY');
+    if (raw === undefined)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * Resolve OFW auth using the three-path priority described at the top of
+ * this file. Throws with an actionable error message when no path succeeds.
+ *
+ * Callers (i.e. `OFWClient.login()`) treat the return value as opaque
+ * credentials — they should not branch on `source`. The field exists for
+ * logging / future cache-keying only.
+ */
+export async function resolveAuth() {
+    // ── Path 1: env-var credentials (unchanged from pre-fetchproxy behavior).
+    const username = readEnv('OFW_USERNAME');
+    const password = readEnv('OFW_PASSWORD');
+    if (username && password) {
+        const { token, expiresAt } = await loginWithPassword(username, password);
+        return { token, expiresAt, source: 'env' };
+    }
+    // ── Path 2: fetchproxy fallback (new).
+    if (!fetchproxyDisabled()) {
+        try {
+            const session = await bootstrap({
+                serverName: pkg.name,
+                version: pkg.version,
+                // OFW serves both ofw.ourfamilywizard.com and www.ourfamilywizard.com;
+                // the API + auth token live on the apex. The extension matches on
+                // suffix, so listing the apex covers both.
+                domains: ['ourfamilywizard.com'],
+                declare: {
+                    cookies: [],
+                    // The web app stores the Bearer token in localStorage["auth"] and
+                    // its expiry (ISO string) in localStorage["tokenExpiry"]. Mirroring
+                    // both means our 401-replay logic can be slightly smarter, and the
+                    // expiry surfaces correctly in diagnostics.
+                    localStorage: ['auth', 'tokenExpiry'],
+                    sessionStorage: [],
+                    captureHeaders: [],
+                },
+            });
+            const token = session.localStorage['auth'];
+            const expiryRaw = session.localStorage['tokenExpiry'];
+            if (!token) {
+                throw new Error('localStorage["auth"] missing on ourfamilywizard.com. ' +
+                    'Sign into OFW in your browser (with the fetchproxy extension installed) and retry.');
+            }
+            return {
+                token,
+                expiresAt: expiryRaw ? new Date(expiryRaw) : undefined,
+                source: 'fetchproxy',
+            };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`OFW auth: no OFW_USERNAME/OFW_PASSWORD set, and fetchproxy fallback failed: ${msg}`);
+        }
+    }
+    // ── Path 3: nothing configured. Surface both fixes side-by-side so the
+    //    user can pick whichever fits their setup.
+    throw new Error('OFW auth: set OFW_USERNAME + OFW_PASSWORD, ' +
+        'or install the fetchproxy extension and sign into ourfamilywizard.com ' +
+        '(unset OFW_DISABLE_FETCHPROXY if it is set).');
+}