zola-mcp 1.1.2 → 1.2.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.2.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.2.3",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zola",
   "displayName": "Zola",
-  "version": "1.1.2",
+  "version": "1.2.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,29 @@ 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)
+
+## Acknowledgement of Terms
+
+By using this MCP server, you acknowledge and agree to the following:
+
+**1. This server accesses your own Zola account.** Auth happens via your own credentials. It does not — and cannot — access anyone else's wedding website, registry, or guest list.
+
+**2. [Zola's Terms of Use](https://www.zola.com/terms) govern your use of this server**, just as they govern your direct use of zola.com. The clauses most relevant here:
+
+> [You may not use] any hardware or software intended to surreptitiously intercept or otherwise obtain any information… including but not limited to the use of any "scraping" or other data mining techniques, robots or similar data gathering and extraction tools.
+
+And, critically, on agent-acting-as-you: *"You are responsible for maintaining the confidentiality of your account and password… You accept full responsibility for all activities that occur under your account and password, **even if such actions are undertaken by your Authorized Agent or other third party**."*
+
+You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Zola's ToU is explicit: this MCP acting as your Authorized Agent counts as you.
+
+**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Zola, Inc. It is a personal automation tool for one couple to manage their own wedding website, registry, vendor research, and guest list. Do not use it to bulk-extract Zola's vendor directory, scrape registries, or compete with Zola.
+
+**4. Stability is not guaranteed.** This server may call internal Zola endpoints that change without notice. It may break.
+
+**5. You accept full responsibility** for any consequences of using this server in connection with your Zola account — rate limiting, account warnings, suspension, or any enforcement action. Per Zola's ToU, anything this MCP does under your account is your action — review guest list edits, registry changes, and inquiries before confirming. If Zola objects to your use, stop using this server.
+
+This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Zola's actual ToU.
 
 ## Installation
 
@@ -89,16 +111,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.
+
+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.
 
-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).
+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 +140,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 +220,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 +230,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).');
+}