zola-mcp 1.1.2 → 1.1.3

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Zola wedding planning tools for Claude Code",
-    "version": "1.1.2"
+    "version": "1.1.3"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Zola",
       "source": "./",
       "description": "Zola wedding planning tools for Claude — vendors, budget, guests, seating, events, registry, inquiries, and more via MCP",
-      "version": "1.1.2",
+      "version": "1.1.3",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zola",
   "displayName": "Zola",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Zola wedding planning tools for Claude — vendors, budget, guests, seating, events, registry, inquiries, and more via MCP",
   "author": {
     "name": "Chris Chall",

package/README.md

@@ -23,7 +23,7 @@ Ask Claude things like:
 - [Claude Desktop](https://claude.ai/download) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
 - [Node.js](https://nodejs.org) 20.6 or later
 - A [Zola](https://www.zola.com) account
-- [Google Chrome](https://www.google.com/chrome/) — used once for the scripted auth flow (optional; you can copy the cookie manually instead)
+- For the no-env-var path: the [fetchproxy 0.3.0 Chrome / Safari extension](https://github.com/chrischall/fetchproxy)
 
 ## Installation
 
@@ -89,16 +89,17 @@ Add to Claude Desktop config:
 
 ### Getting your refresh token
 
-Sign in to zola.com and capture the `usr` cookie — a ~1-year JWT that doubles as the refresh token. The token lasts ~1 year; this is a one-time setup.
+You have two options. Both produce the same `usr` cookie value — a ~1-year JWT that doubles as the refresh token.
 
-#### Option A — scripted (recommended)
+#### Option A — fetchproxy extension (recommended)
 
-```bash
-npm run auth               # prints the token to the console
-npm run auth -- .env       # writes ZOLA_REFRESH_TOKEN=<token> to .env
-```
+1. Install the [fetchproxy 0.3.0 extension](https://github.com/chrischall/fetchproxy) (Chrome Web Store or Safari `.dmg`).
+2. Sign in at [zola.com/account/login](https://www.zola.com/account/login) in that browser.
+3. Leave `ZOLA_REFRESH_TOKEN` **unset** in your Claude config.
 
-Launches Chrome with a dedicated profile at `~/.zola-mcp/chrome-profile`, waits for you to sign in at `zola.com/account/login`, captures the `usr` cookie (a ~1-year JWT), and either prints it (for pasting into Claude Desktop / MCPB / any config that doesn't read `.env`) or writes it to the file you pass. Requires Google Chrome installed locally; the script will install `puppeteer-core` on first run (~1 MB).
+On the first tool call, the MCP asks the extension for the HttpOnly `usr` cookie via `chrome.cookies.get`, then operates direct-to-API from Node. No persistent storage of the token in any env file. To re-auth (e.g. after Zola signs you out), just sign back in to zola.com.
+
+You can opt out of this fallback with `ZOLA_DISABLE_FETCHPROXY=1` (e.g. in headless / CI environments where no extension is available).
 
 #### Option B — manual (DevTools)
 
@@ -117,11 +118,10 @@ Ask Claude: *"How's wedding planning going?"* — it should show your wedding da
 
 ## Credentials
 
-Only one credential is required:
-
 | Env var | Required | Notes |
 |---------|----------|-------|
-| `ZOLA_REFRESH_TOKEN` | Yes | Refresh token JWT (~1 year lifetime). Run `npm run auth` to capture via browser login, or copy the `usr` cookie from DevTools. |
+| `ZOLA_REFRESH_TOKEN` | Conditional | Refresh token JWT (~1 year lifetime). When unset, the MCP falls back to the [fetchproxy extension](https://github.com/chrischall/fetchproxy) to read the `usr` cookie from your signed-in zola.com tab. |
+| `ZOLA_DISABLE_FETCHPROXY` | No | Set to `1` to opt out of the fetchproxy fallback (headless / CI). |
 | `ZOLA_ACCOUNT_ID` | No | Auto-resolved from API on first use |
 | `ZOLA_REGISTRY_ID` | No | Auto-resolved from API on first use |
 
@@ -198,9 +198,9 @@ Only one credential is required:
 
 ## Troubleshooting
 
-**"ZOLA_REFRESH_TOKEN must be set"** — run `npm run auth` to capture your token.
+**"Zola auth: set ZOLA_REFRESH_TOKEN, or install the fetchproxy extension…"** — either set `ZOLA_REFRESH_TOKEN` in your config or install the fetchproxy extension and sign into zola.com.
 
-**"Zola session refresh failed"** — your refresh token has expired (~1 year). Re-run `npm run auth`.
+**"Zola session refresh failed"** — your refresh token has expired (~1 year) or been revoked. Either capture a new `usr` cookie (DevTools) or sign back into zola.com with the fetchproxy extension installed.
 
 **403 from mobile API** — the `x-zola-session-id` header may be missing. Update to the latest version.
 
@@ -208,7 +208,7 @@ Only one credential is required:
 
 ## Security
 
-- The refresh token lives only in your local `.env` or config file
+- The refresh token lives only in your local `.env` or config file (when set) or in the user's browser cookie store (fetchproxy path)
 - It is passed as an environment variable and never logged
 - The server authenticates with Zola's mobile API using the same flow as the iOS app
 - Account and registry IDs are auto-resolved from the API (no manual configuration needed)

package/dist/auth.js

@@ -0,0 +1,125 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Auth resolution — Pattern A template
+// ────────────────────────────────────────────────────────────────────────────
+//
+// Mirrors the canonical "browser-bootstrap + Node-direct" shape from
+// ofw-mcp/src/auth.ts. Other MCPs in this family (resy-mcp, opentable-mcp,
+// signupgenius-mcp, …) use the same selector — keep the structure flat,
+// the path-selection explicit, and the error messages actionable.
+//
+// THE THREE PATHS, in priority order:
+//
+//   1. Env-var credential (existing behavior)
+//      ZOLA_REFRESH_TOKEN set → use it directly. This is the ~1-year JWT
+//      that doubles as the `usr` cookie on zola.com. Legacy users keep
+//      working without action.
+//
+//   2. fetchproxy fallback (new)
+//      When no token is set, lift the user's session out of their
+//      signed-in zola.com browser tab via the fetchproxy 0.3.0 extension.
+//      The `@fetchproxy/bootstrap` helper spins up a one-shot WebSocket
+//      bridge, asks the extension for the HttpOnly `usr` cookie via
+//      `chrome.cookies.get`, then closes the bridge. From there, all
+//      Zola API calls go out via plain Node `fetch()` to
+//      mobile-api.zola.com — fetchproxy is NOT in the hot path.
+//
+//      Users opt out with ZOLA_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 the env var, OR install the extension
+//      and sign in.
+//
+// Why fetchproxy is only a one-shot read:
+//   The bootstrap call snapshots the `usr` cookie and returns. The MCP
+//   then operates from Node with direct fetch — latency and reliability
+//   are not coupled to the browser bridge for normal tool calls. The
+//   captured refresh token is fed into the existing
+//   `POST /v3/sessions/refresh` flow which mints 30-min session tokens
+//   (also in pure Node).
+//
+// Testability:
+//   - `@fetchproxy/bootstrap` is mocked at the module boundary in tests.
+//   - This module exposes a single async `resolveRefreshToken()` that
+//     returns the JWT plus the source — callers (the client) treat the
+//     return value as opaque credentials.
+import { bootstrap } from '@fetchproxy/bootstrap';
+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('ZOLA_DISABLE_FETCHPROXY');
+    if (raw === undefined)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * Resolve the Zola refresh token using the three-path priority described
+ * above. Throws with an actionable error message when no path succeeds.
+ *
+ * Callers (i.e. `ZolaClient.refresh()`) should treat the return value as
+ * opaque credentials — do not branch on `source`. The field exists for
+ * logging / future cache-keying only.
+ */
+export async function resolveRefreshToken() {
+    // ── Path 1: env-var refresh token (unchanged from pre-fetchproxy behavior).
+    const envToken = readEnv('ZOLA_REFRESH_TOKEN');
+    if (envToken) {
+        return { token: envToken, source: 'env' };
+    }
+    // ── Path 2: fetchproxy fallback (new).
+    if (!fetchproxyDisabled()) {
+        try {
+            const session = await bootstrap({
+                serverName: pkg.name,
+                version: pkg.version,
+                // Zola serves www.zola.com (web app) and mobile-api.zola.com (API).
+                // The `usr` cookie lives on the web app's apex domain; the extension
+                // matches on suffix so listing the apex covers any subdomain.
+                domains: ['zola.com'],
+                declare: {
+                    // `usr` is HttpOnly → invisible to page JS, but fetchproxy 0.3.0's
+                    // read_cookies uses `chrome.cookies.get` which DOES see HttpOnly
+                    // cookies. The value IS the ~1-year refresh JWT.
+                    cookies: ['usr'],
+                    localStorage: [],
+                    sessionStorage: [],
+                    captureHeaders: [],
+                },
+            });
+            const token = session.cookies['usr'];
+            if (!token) {
+                throw new Error('zola: no `usr` cookie found. ' +
+                    'Sign into zola.com in your browser (with the fetchproxy extension installed) and retry.');
+            }
+            return { token, source: 'fetchproxy' };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Zola auth: no ZOLA_REFRESH_TOKEN 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('Zola auth: set ZOLA_REFRESH_TOKEN, ' +
+        'or install the fetchproxy extension and sign into zola.com ' +
+        '(unset ZOLA_DISABLE_FETCHPROXY if it is set).');
+}