zola-mcp 1.2.3 → 1.3.1

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Zola wedding planning tools for Claude Code",
-    "version": "1.2.3"
+    "version": "1.3.1"
   },
   "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.2.3",
+      "version": "1.3.1",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

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

package/dist/auth.js

@@ -45,6 +45,7 @@
 //     returns the JWT plus the source — callers (the client) treat the
 //     return value as opaque credentials.
 import { bootstrap } from '@fetchproxy/bootstrap';
+import { classifyBridgeError } from '@fetchproxy/server';
 import pkg from '../package.json' with { type: 'json' };
 /**
  * Read an env var, trim, and treat blank / `${UNEXPANDED}` placeholders as
@@ -113,6 +114,18 @@ export async function resolveRefreshToken() {
             return { token, source: 'fetchproxy' };
         }
         catch (e) {
+            // 0.8.0+ typed-error discrimination. The fetchproxy server already
+            // retries once on SW eviction (bridgeReviveDelayMs=2000 default), so
+            // a thrown FetchproxyBridgeDownError means the retry also failed —
+            // the extension's service worker is genuinely down and the user
+            // needs to wake it. The `.hint` is the actionable copy
+            // ("click the extension toolbar icon...") that we'd otherwise have
+            // to hand-write here. Surface it verbatim so users in path 2 get
+            // the same self-service guidance as path 3.
+            if (classifyBridgeError(e) === 'bridge_down') {
+                const downErr = e;
+                throw new Error(`Zola auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`);
+            }
             const msg = e instanceof Error ? e.message : String(e);
             throw new Error(`Zola auth: no ZOLA_REFRESH_TOKEN set, and fetchproxy fallback failed: ${msg}`);
         }

package/dist/bundle.js

@@ -35178,6 +35178,52 @@ var FetchproxyHttpError = class extends Error {
     this.name = "FetchproxyHttpError";
   }
 };
+var FetchproxyBridgeDownError = class extends FetchproxyProtocolError {
+  originalError;
+  retryAttempted;
+  op;
+  url;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time (the same port `listen()` bound to). */
+  port;
+  hint;
+  constructor(args) {
+    const retryAttempted = args.retryAttempted ?? false;
+    const op = args.op ?? "fetch";
+    const retryClause = retryAttempted ? `Server already burned a one-shot lazy-revive retry; SW is still down. ` : `Server lazy-revive retry was disabled (bridgeReviveDelayMs unset/0). `;
+    const hint = `the fetchproxy extension's service worker is not responding ("${args.originalError}"). Chrome evicts extension service workers after ~30s idle by default. ${retryClause}Wake it by clicking the fetchproxy extension toolbar icon, then retry. If it keeps happening, reload the extension from chrome://extensions.`;
+    super(`fetchproxy bridge down during ${op}${args.url ? ` (${args.url})` : ""}. ${hint}`);
+    this.name = "FetchproxyBridgeDownError";
+    this.originalError = args.originalError;
+    this.retryAttempted = retryAttempted;
+    this.op = op;
+    if (args.url !== void 0)
+      this.url = args.url;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.hint = hint;
+  }
+};
+var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
+  url;
+  timeoutMs;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time. */
+  port;
+  /** 0.8.0+: actual elapsed milliseconds when the timer won the race. */
+  elapsedMs;
+  constructor(args) {
+    super(`fetchproxy: ${args.url} did not respond within ${args.timeoutMs}ms`);
+    this.name = "FetchproxyTimeoutError";
+    this.url = args.url;
+    this.timeoutMs = args.timeoutMs;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.elapsedMs = args.elapsedMs ?? args.timeoutMs;
+  }
+};
 var SUBDOMAIN_LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
 function assertSubdomainLabel(label) {
   if (!SUBDOMAIN_LABEL_RE.test(label)) {
@@ -35215,6 +35261,18 @@ var FetchproxyServer = class {
   hostHandle = null;
   peerHandle = null;
   nextRequestId = 1;
+  // 0.8.0+: process-wide freshness counters surfaced via bridgeHealth().
+  // Replaces the local copies every downstream MCP was rolling on top
+  // of its own transport adapter — see realty-mcp cohort drift notes.
+  // Updated by recordSuccess / recordFailure from fetch + capture paths.
+  // `lastExtensionMessageAt` (#23 ask 4) is updated whenever any inner
+  // frame from the extension arrives — gives extension-side liveness
+  // distinct from per-call success/failure.
+  lastSuccessAt = null;
+  lastFailureAt = null;
+  lastFailureReason = null;
+  consecutiveFailures = 0;
+  lastExtensionMessageAt = null;
   pending = /* @__PURE__ */ new Map();
   // Separate pending map for read_cookies so the response shape (cookies
   // string vs status/body) doesn't have to share a union type with fetch.
@@ -35283,6 +35341,12 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
+      // adapter was about to set these to the same numbers anyway; the
+      // back-door is `0` (explicit opt-out) if a caller genuinely wants
+      // the legacy hang-forever / fail-once-on-SW-eviction behavior.
+      fetchTimeoutMs: opts.fetchTimeoutMs ?? 3e4,
+      bridgeReviveDelayMs: opts.bridgeReviveDelayMs ?? 2e3,
       identityDir: opts.identityDir,
       onPairCode: opts.onPairCode
     };
@@ -35418,7 +35482,7 @@ var FetchproxyServer = class {
     }
   }
   pairingErrorMessage(code) {
-    return `fetchproxy: pairing required for ${this.opts.serverName} \u2014 open the fetchproxy extension popup in Chrome and approve the pair request. Verify the pair code matches: ${code}`;
+    return `fetchproxy transport error: pairing required for ${this.opts.serverName}. Tell the user to open the Transporter browser extension popup and approve the pair request. The pair code is: ${code} \u2014 display this code to the user so they can verify it matches.`;
   }
   /**
    * Raw single-shot fetch through the bridge. Most callers should prefer
@@ -35439,8 +35503,71 @@ var FetchproxyServer = class {
     const pendingCode = this.currentPendingPairCode();
     if (pendingCode !== null) {
       const error48 = this.pairingErrorMessage(pendingCode);
-      return { ok: false, error: error48, kind: classifyFetchError(error48) };
+      return {
+        ok: false,
+        error: error48,
+        kind: classifyFetchError(error48),
+        retryAttempted: false
+      };
     }
+    const first = await this._fetchOnceWithTimeout(init);
+    const reviveMs = this.opts.bridgeReviveDelayMs;
+    let final = first;
+    if (!first.ok && first.kind === "content_script_unreachable" && reviveMs !== void 0 && reviveMs > 0) {
+      await new Promise((r) => setTimeout(r, reviveMs));
+      const second = await this._fetchOnceWithTimeout(init);
+      if (second.ok)
+        this.recordSuccess();
+      else
+        this.recordFailure(`${second.kind ?? "other"}: ${second.error}`);
+      return { ...second, retryAttempted: true };
+    }
+    if (first.ok)
+      this.recordSuccess();
+    else
+      this.recordFailure(`${first.kind ?? "other"}: ${first.error}`);
+    return { ...first, retryAttempted: false };
+  }
+  /**
+   * 0.8.0+: snapshot of the bridge's process-wide freshness counters,
+   * suitable for surfacing through a downstream MCP's healthcheck tool.
+   * Counters reset on a success (consecutiveFailures), accumulate
+   * across the process lifetime otherwise. Replaces the per-MCP
+   * duplication the realty cohort had been rolling in their adapters.
+   * `lastExtensionMessageAt` is updated whenever ANY inner frame
+   * arrives from the extension — gives extension-side liveness
+   * distinct from server-side success/failure of the user-visible
+   * call (addresses #23 ask 4).
+   */
+  bridgeHealth() {
+    return {
+      role: this.role,
+      port: this.opts.port,
+      serverVersion: this.opts.version,
+      fetchTimeoutMs: this.opts.fetchTimeoutMs ?? 0,
+      bridgeReviveDelayMs: this.opts.bridgeReviveDelayMs ?? 0,
+      lastSuccessAt: this.lastSuccessAt,
+      lastFailureAt: this.lastFailureAt,
+      lastFailureReason: this.lastFailureReason,
+      consecutiveFailures: this.consecutiveFailures,
+      lastExtensionMessageAt: this.lastExtensionMessageAt
+    };
+  }
+  recordSuccess() {
+    this.lastSuccessAt = Date.now();
+    this.consecutiveFailures = 0;
+  }
+  recordFailure(reason) {
+    this.lastFailureAt = Date.now();
+    this.lastFailureReason = reason;
+    this.consecutiveFailures += 1;
+  }
+  /**
+   * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
+   * On timeout returns the `{ok:false, kind:'timeout'}` envelope —
+   * the throwing surface is the convenience methods.
+   */
+  async _fetchOnceWithTimeout(init) {
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
     const pending = new Promise((resolve) => {
@@ -35451,7 +35578,61 @@ var FetchproxyServer = class {
     } else if (this.peerHandle) {
       await this.peerHandle.sendInner(inner);
     }
-    return pending;
+    const timeoutMs = this.opts.fetchTimeoutMs;
+    if (timeoutMs === void 0 || timeoutMs <= 0)
+      return pending;
+    let timer;
+    const start = Date.now();
+    try {
+      return await Promise.race([
+        pending,
+        new Promise((resolve) => {
+          timer = setTimeout(() => {
+            this.pending.delete(id);
+            const elapsedMs = Date.now() - start;
+            const error48 = `fetchproxy: ${init.url} did not respond within ${timeoutMs}ms`;
+            resolve({
+              ok: false,
+              error: error48,
+              kind: "timeout",
+              retryAttempted: false,
+              elapsedMs
+            });
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
+  /**
+   * Map an `ok:false` fetch result to its typed throwable. Centralizes
+   * the kind-to-error-class switch so `request()` and (via the same
+   * logic re-implemented inline) `captureRequestHeader()` agree on what
+   * to throw.
+   */
+  _typedErrorFor(result, url2, op, retryAttempted) {
+    if (result.kind === "timeout") {
+      return new FetchproxyTimeoutError({
+        url: url2,
+        timeoutMs: this.opts.fetchTimeoutMs ?? 0,
+        role: this.role,
+        port: this.opts.port,
+        elapsedMs: result.elapsedMs
+      });
+    }
+    if (result.kind === "content_script_unreachable") {
+      return new FetchproxyBridgeDownError({
+        originalError: result.error,
+        retryAttempted,
+        op,
+        url: url2,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+    return new FetchproxyProtocolError(result.error);
   }
   /**
    * Convenience wrapper around `fetch()`. Builds the URL from a path
@@ -35474,8 +35655,18 @@ var FetchproxyServer = class {
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
-    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
-    const url2 = path.startsWith("http://") || path.startsWith("https://") ? path : `https://${host}${path}`;
+    const isAbsolute = path.startsWith("http://") || path.startsWith("https://");
+    let host;
+    if (isAbsolute) {
+      try {
+        host = new URL(path).host;
+      } catch {
+        throw new Error(`FetchproxyServer.request: absolute path is not a valid URL: ${JSON.stringify(path)}`);
+      }
+    } else {
+      host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    }
+    const url2 = isAbsolute ? path : `https://${host}${path}`;
     assertUrlInDomains("request url", url2, this.opts.domains);
     const init = {
       url: url2,
@@ -35486,7 +35677,7 @@ var FetchproxyServer = class {
     };
     const result = await this.fetch(init);
     if (!result.ok) {
-      throw new FetchproxyProtocolError(result.error);
+      throw this._typedErrorFor(result, init.url, "fetch", result.retryAttempted ?? false);
     }
     const response = {
       status: result.status,
@@ -35696,10 +35887,73 @@ var FetchproxyServer = class {
     }
     await this.ensureConnected();
     this.throwIfPendingPair();
-    const declared = this.opts.captureHeaders.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
-    if (!declared) {
-      throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+    const decls = this.opts.captureHeaders;
+    let resolved;
+    if (opts?.urlPattern !== void 0 && opts?.headerName !== void 0) {
+      const found = decls.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
+      if (!found) {
+        throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+      }
+      resolved = found;
+    } else if (opts?.urlPattern === void 0 && opts?.headerName === void 0) {
+      if (decls.length === 0) {
+        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {urlPattern, headerName} explicitly");
+      }
+      if (decls.length > 1) {
+        const list = decls.map((d) => `${JSON.stringify(d.urlPattern)}/${JSON.stringify(d.headerName)}`).join(", ");
+        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {urlPattern, headerName} to disambiguate`);
+      }
+      resolved = decls[0];
+    } else {
+      throw new Error("FetchproxyServer.captureRequestHeader: pass both urlPattern AND headerName, or neither (which defaults to the single declared entry)");
+    }
+    const callOpts = { ...resolved, ...opts?.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} };
+    try {
+      const result = await this._captureRequestHeaderOnce(callOpts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`capture_request_header: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._captureRequestHeaderOnce(callOpts);
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`capture_request_header: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`capture_request_header bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "capture_request_header",
+            url: resolved.urlPattern,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`capture_request_header bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "capture_request_header",
+        url: resolved.urlPattern,
+        role: this.role,
+        port: this.opts.port
+      });
     }
+  }
+  async _captureRequestHeaderOnce(opts) {
     const id = this.nextRequestId++;
     const inner = {
       type: "request",
@@ -35808,18 +36062,35 @@ var FetchproxyServer = class {
   onInner(inner) {
     if (inner.type !== "response")
       return;
+    this.lastExtensionMessageAt = Date.now();
     const fetchCb = this.pending.get(inner.id);
     if (fetchCb) {
       this.pending.delete(inner.id);
       if (inner.ok) {
         if (inner.op === void 0 || inner.op === "fetch") {
-          fetchCb({ ok: true, status: inner.status, url: inner.url, body: inner.body });
+          fetchCb({
+            ok: true,
+            status: inner.status,
+            url: inner.url,
+            body: inner.body,
+            retryAttempted: false
+          });
         } else {
           const error48 = `unexpected ${inner.op} response on fetch awaiter`;
-          fetchCb({ ok: false, error: error48, kind: classifyFetchError(error48) });
+          fetchCb({
+            ok: false,
+            error: error48,
+            kind: classifyFetchError(error48),
+            retryAttempted: false
+          });
         }
       } else {
-        fetchCb({ ok: false, error: inner.error, kind: classifyFetchError(inner.error) });
+        fetchCb({
+          ok: false,
+          error: inner.error,
+          kind: classifyFetchError(inner.error),
+          retryAttempted: false
+        });
       }
       return;
     }
@@ -35889,7 +36160,12 @@ var FetchproxyServer = class {
   rejectAllPending(reason = "extension disconnected") {
     const err = new FetchproxyProtocolError(reason);
     for (const cb of this.pending.values()) {
-      cb({ ok: false, error: err.message, kind: classifyFetchError(err.message) });
+      cb({
+        ok: false,
+        error: err.message,
+        kind: classifyFetchError(err.message),
+        retryAttempted: false
+      });
     }
     this.pending.clear();
     for (const cb of this.pendingReadCookies.values()) {
@@ -35954,6 +36230,19 @@ var FetchproxyServer = class {
   }
 };
 
+// node_modules/@fetchproxy/server/dist/classify-bridge-error.js
+function classifyBridgeError(err) {
+  if (err instanceof FetchproxyTimeoutError)
+    return "timeout";
+  if (err instanceof FetchproxyBridgeDownError)
+    return "bridge_down";
+  if (err instanceof FetchproxyHttpError)
+    return "http";
+  if (err instanceof FetchproxyProtocolError)
+    return "protocol";
+  return "other";
+}
+
 // node_modules/@fetchproxy/bootstrap/dist/index.js
 var defaultFactory = (opts) => new FetchproxyServer(opts);
 async function bootstrap(opts) {
@@ -36008,7 +36297,11 @@ async function bootstrap(opts) {
       key: p.storageKey,
       jsonPointer: p.jsonPointer
     })),
-    onPairCode: opts.onPairCode
+    onPairCode: opts.onPairCode,
+    // 0.8.0+ pass-through. Only forwarded when the caller set them;
+    // unset → server defaults apply (30000 / 2000 in 0.8.0).
+    ...opts.fetchTimeoutMs !== void 0 ? { fetchTimeoutMs: opts.fetchTimeoutMs } : {},
+    ...opts.bridgeReviveDelayMs !== void 0 ? { bridgeReviveDelayMs: opts.bridgeReviveDelayMs } : {}
   });
   const storageDomainOpts = {};
   if (opts.storageDomain !== void 0)
@@ -36111,7 +36404,7 @@ var BootstrapDisabledError = class extends Error {
 // package.json
 var package_default = {
   name: "zola-mcp",
-  version: "1.2.3",
+  version: "1.3.1",
   mcpName: "io.github.chrischall/zola-mcp",
   description: "Zola wedding MCP server for Claude",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -36157,7 +36450,8 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.6.0",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2"
   },
@@ -36217,6 +36511,12 @@ async function resolveRefreshToken() {
       }
       return { token, source: "fetchproxy" };
     } catch (e) {
+      if (classifyBridgeError(e) === "bridge_down") {
+        const downErr = e;
+        throw new Error(
+          `Zola auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+        );
+      }
       const msg = e instanceof Error ? e.message : String(e);
       throw new Error(
         `Zola auth: no ZOLA_REFRESH_TOKEN set, and fetchproxy fallback failed: ${msg}`
@@ -36280,6 +36580,19 @@ var ZolaClient = class {
     await this.ensureSession();
     return this.doRequest(method, path, body);
   }
+  /**
+   * Like `requestMobile` but for endpoints that return a non-JSON body
+   * (e.g. the QR-code preview which returns image bytes).
+   * Sends `Accept: *\/*` (the JSON default would 406), and returns both the
+   * raw bytes and the server's content-type so callers can pass it through.
+   */
+  async requestMobileBinary(method, path, body) {
+    await this.ensureSession();
+    const response = await this.sendWithRetry(method, path, body, false, false, "*/*");
+    const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    return { bytes, contentType };
+  }
   /**
    * Get user context (wedding account ID, registry ID, etc.).
    * Uses env vars as overrides; falls back to GET /v3/users/me/context.
@@ -36312,10 +36625,15 @@ var ZolaClient = class {
     };
     return this.cachedContext;
   }
-  async doRequest(method, path, body, isAuthRetry = false, isRateRetry = false) {
+  async doRequest(method, path, body) {
+    const response = await this.sendWithRetry(method, path, body);
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+  }
+  async sendWithRetry(method, path, body, isAuthRetry = false, isRateRetry = false, accept = "application/json") {
     const sessionId = decodeJwtSessionId(this.sessionToken);
     const headers = {
-      accept: "application/json",
+      accept,
       authorization: `Bearer ${this.sessionToken}`,
       "x-zola-platform-type": "iphone_app",
       "x-zola-session-id": this.deviceSessionId,
@@ -36332,21 +36650,20 @@ var ZolaClient = class {
       this.sessionToken = null;
       this.sessionExpiry = null;
       await this.refresh();
-      return this.doRequest(method, path, body, true, isRateRetry);
+      return this.sendWithRetry(method, path, body, true, isRateRetry, accept);
     }
     if (response.status === 429) {
       if (!isRateRetry) {
         await new Promise((r) => setTimeout(r, 2e3));
-        return this.doRequest(method, path, body, isAuthRetry, true);
+        return this.sendWithRetry(method, path, body, isAuthRetry, true, accept);
       }
       throw new Error("Rate limited by Zola API");
     }
     if (!response.ok) {
-      const text2 = await response.text();
-      throw new Error(`Zola API error: ${response.status} ${response.statusText} for ${method} ${path}: ${text2}`);
+      const text = await response.text();
+      throw new Error(`Zola API error: ${response.status} ${response.statusText} for ${method} ${path}: ${text}`);
     }
-    const text = await response.text();
-    return text ? JSON.parse(text) : null;
+    return response;
   }
   async ensureSession() {
     if (this.sessionToken && this.sessionExpiry) {
@@ -36410,6 +36727,9 @@ var client = new ZolaClient();
 function jsonResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+function imageResult(bytes, mimeType) {
+  return { content: [{ type: "image", data: Buffer.from(bytes).toString("base64"), mimeType }] };
+}
 function pickDefined(base, args, keys) {
   const body = { ...base };
   for (const key of keys) {
@@ -37905,10 +38225,303 @@ function registerRegistryItemTools(server2) {
   }, removeRegistryItem);
 }
 
+// src/tools/invitations.ts
+async function listCardProjects(args) {
+  const response = await client.requestMobile(
+    "POST",
+    "/v3/card-projects/search_request",
+    {
+      completed: args.include_completed ?? false,
+      limit: args.limit ?? 30,
+      card_suite_uuids: [],
+      card_suite_ids: [],
+      offset: 0,
+      fetch_customizations: true,
+      include_deleted: false,
+      medium: ["PAPER", "MAGNET", "DIGITAL"],
+      single_sample: false
+    }
+  );
+  return jsonResult(response.data);
+}
+async function getCardProject(args) {
+  const response = await client.requestMobile(
+    "GET",
+    `/v3/card-projects/${args.project_uuid}`
+  );
+  return jsonResult(response.data);
+}
+async function validateCardProject(args) {
+  const response = await client.requestMobile(
+    "GET",
+    `/v3/card-projects/${args.project_uuid}/validate`
+  );
+  return jsonResult(response.data);
+}
+async function getCardProjectGuests(args) {
+  const response = await client.requestMobile(
+    "GET",
+    `/v3/card-projects/${args.project_uuid}/project-guest-groups`
+  );
+  return jsonResult(response.data);
+}
+async function getCardSuite(args) {
+  const response = await client.requestMobile(
+    "POST",
+    `/v4/card-catalog/suites/details/${args.suite_uuid}`
+  );
+  return jsonResult(response.data);
+}
+async function searchCardCatalog(args) {
+  const response = await client.requestMobile(
+    "POST",
+    "/v3/card-catalog/search/faceted",
+    {
+      lead_card_types: [],
+      include_updated_proof_module: true,
+      limit: args.limit ?? 50,
+      offset: 0,
+      digital_suite: false,
+      include_lead_card_type_metadata: true,
+      lead_card_type: args.card_type ?? "INVITATION",
+      include_module: true
+    }
+  );
+  return jsonResult(response.data);
+}
+async function listFavoriteCardSuites() {
+  const response = await client.requestMobile(
+    "GET",
+    "/v3/favorites/card-suites/"
+  );
+  return jsonResult(response.data);
+}
+async function getRsvpPage() {
+  const { weddingAccountId } = await client.getContext();
+  const response = await client.requestMobile(
+    "GET",
+    `/v3/websites/rsvps/wedding-accounts/${weddingAccountId}`
+  );
+  return jsonResult(response.data);
+}
+async function createCardProject(args) {
+  const { weddingAccountId } = await client.getContext();
+  const response = await client.requestMobile(
+    "POST",
+    "/v3/card-projects",
+    {
+      quantity: args.quantity ?? 150,
+      lead_variation_uuid: args.lead_variation_uuid,
+      extra_customizable: false,
+      account_id: weddingAccountId,
+      suite_uuid: args.suite_uuid
+    }
+  );
+  return jsonResult(response.data);
+}
+async function swapCardProjectVariation(args) {
+  const customizations = {};
+  for (const [customizationUuid, variationUuid] of Object.entries(args.customizations)) {
+    customizations[customizationUuid] = { variation_uuid: variationUuid };
+  }
+  const response = await client.requestMobile(
+    "PUT",
+    `/v3/card-projects/${args.project_uuid}`,
+    { customizations }
+  );
+  return jsonResult(response.data);
+}
+async function setCardProjectGuests(args) {
+  const response = await client.requestMobile(
+    "PUT",
+    `/v3/card-projects/${args.project_uuid}/project-guest-groups`,
+    { guest_group_requests: args.guest_groups }
+  );
+  return jsonResult(response.data);
+}
+async function previewCardTemplate(args) {
+  const substitutions = {};
+  if (args.first_name !== void 0) substitutions.first_name = args.first_name;
+  if (args.last_name !== void 0) substitutions.last_name = args.last_name;
+  if (args.partner_first_name !== void 0) substitutions.partner_first_name = args.partner_first_name;
+  if (args.partner_last_name !== void 0) substitutions.partner_last_name = args.partner_last_name;
+  if (args.wedding_date !== void 0) {
+    substitutions.wedding_date = args.wedding_date;
+  } else {
+    const { weddingDate } = await client.getContext();
+    if (weddingDate) substitutions.wedding_date = weddingDate;
+  }
+  const response = await client.requestMobile(
+    "POST",
+    "/v3/card-templates/preview",
+    {
+      variation_uuids: args.variation_uuids,
+      customizable: true,
+      substitutions
+    }
+  );
+  return jsonResult(response.data);
+}
+async function previewQrcode(args) {
+  const { bytes, contentType } = await client.requestMobileBinary(
+    "PUT",
+    "/v3/card-projects/qrcode/preview",
+    {
+      dimension: args.dimension ?? "MEDIUM",
+      url_type: args.url_type ?? "CUSTOM",
+      enabled: args.enabled ?? true,
+      url: args.url
+    }
+  );
+  return imageResult(bytes, sniffImageType(bytes) ?? contentType);
+}
+function sniffImageType(bytes) {
+  if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) {
+    return "image/png";
+  }
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) {
+    return "image/jpeg";
+  }
+  return null;
+}
+async function setCardProjectQrcode(args) {
+  const response = await client.requestMobile(
+    "PUT",
+    `/v3/card-projects/${args.project_uuid}/customization/page/${args.page_uuid}/qrcode`,
+    {
+      dimension: args.dimension ?? "MEDIUM",
+      url_type: args.url_type ?? "CUSTOM",
+      color: args.color ?? "000000",
+      enabled: args.enabled ?? true,
+      url: args.url
+    }
+  );
+  return jsonResult(response.data);
+}
+function registerInvitationTools(server2) {
+  server2.registerTool("list_card_projects", {
+    description: 'List your invitation / save-the-date / shower-invite "card" projects (paper or digital). Returns project UUID, name, customizations, suite, and quantity.',
+    inputSchema: {
+      include_completed: external_exports3.boolean().optional().describe("Include orders that have already been placed. Default: false (drafts only)."),
+      limit: external_exports3.number().optional().describe("Max projects to return. Default: 30.")
+    },
+    annotations: { readOnlyHint: true }
+  }, listCardProjects);
+  server2.registerTool("get_card_project", {
+    description: "Get full details for one invitation project including all customizations (invitation, envelope, RSVP card, details card), paper/color options, and per-customization pages.",
+    inputSchema: {
+      project_uuid: external_exports3.string().describe("Project UUID from list_card_projects")
+    },
+    annotations: { readOnlyHint: true }
+  }, getCardProject);
+  server2.registerTool("validate_card_project", {
+    description: "Validate an invitation project \u2014 reports any text-fit, image, or guest-addressing errors per customization. Use before placing an order.",
+    inputSchema: {
+      project_uuid: external_exports3.string().describe("Project UUID from list_card_projects")
+    },
+    annotations: { readOnlyHint: true }
+  }, validateCardProject);
+  server2.registerTool("get_card_project_guests", {
+    description: "List the guest groups assigned to an invitation project, including per-group font-size overrides for printed addressing.",
+    inputSchema: {
+      project_uuid: external_exports3.string().describe("Project UUID from list_card_projects")
+    },
+    annotations: { readOnlyHint: true }
+  }, getCardProjectGuests);
+  server2.registerTool("get_card_suite", {
+    description: 'Get details for an invitation design "suite" (the family of matching invitation + RSVP + details cards), including paper types, sizes, and price range.',
+    inputSchema: {
+      suite_uuid: external_exports3.string().describe("Suite UUID (e.g. from search_card_catalog or list_favorite_card_suites)")
+    },
+    annotations: { readOnlyHint: true }
+  }, getCardSuite);
+  server2.registerTool("search_card_catalog", {
+    description: "Search the invitation design catalog. Faceted search returning suites matching the requested card type.",
+    inputSchema: {
+      card_type: external_exports3.string().optional().describe("Lead card type: INVITATION (default), SAVE_THE_DATE, WEDDING_SHOWER_INVITATION, REHEARSAL_DINNER_INVITATION, THANK_YOU_CARD, etc."),
+      limit: external_exports3.number().optional().describe("Max suites to return. Default: 50.")
+    },
+    annotations: { readOnlyHint: true }
+  }, searchCardCatalog);
+  server2.registerTool("list_favorite_card_suites", {
+    description: "List invitation design suites you have favorited (hearted).",
+    annotations: { readOnlyHint: true }
+  }, listFavoriteCardSuites);
+  server2.registerTool("get_rsvp_page", {
+    description: "Get the RSVP page settings on the wedding website (title, intro copy, visibility, customization).",
+    annotations: { readOnlyHint: true }
+  }, getRsvpPage);
+  server2.registerTool("create_card_project", {
+    description: "Create a new invitation project from a design suite and a lead variation (specific size/paper).",
+    inputSchema: {
+      suite_uuid: external_exports3.string().describe("Suite UUID from search_card_catalog or get_card_suite"),
+      lead_variation_uuid: external_exports3.string().describe("Lead variation UUID (specific size/paper/color from the suite)"),
+      quantity: external_exports3.number().optional().describe("Quantity to order. Default: 150.")
+    },
+    annotations: { destructiveHint: false }
+  }, createCardProject);
+  server2.registerTool("swap_card_project_variation", {
+    description: "Swap one or more customizations on a project to different variations (e.g. switch paper type, color, or size). Pass a map of customization UUID \u2192 new variation UUID.",
+    inputSchema: {
+      project_uuid: external_exports3.string().describe("Project UUID from list_card_projects"),
+      customizations: external_exports3.record(external_exports3.string(), external_exports3.string()).describe("{ customization_uuid: new_variation_uuid }")
+    },
+    annotations: { destructiveHint: false }
+  }, swapCardProjectVariation);
+  server2.registerTool("set_card_project_guests", {
+    description: "Enable / disable guest groups for an invitation project and optionally override font sizes for printed names and addresses. Pass the full list of guest groups you want recorded.",
+    inputSchema: {
+      project_uuid: external_exports3.string().describe("Project UUID from list_card_projects"),
+      guest_groups: external_exports3.array(external_exports3.object({
+        guest_group_id: external_exports3.number().describe("Guest group ID from list_guests / get_card_project_guests"),
+        enabled: external_exports3.boolean().describe("Whether to include this group in printed addressing"),
+        guest_name_font_size_override: external_exports3.number().optional().describe("Override font size for the guest name (pt)"),
+        address_font_size_override: external_exports3.number().optional().describe("Override font size for the address (pt)")
+      })).describe("Full list of guest groups to record. Omitted groups are not affected by this call.")
+    },
+    annotations: { destructiveHint: false }
+  }, setCardProjectGuests);
+  server2.registerTool("preview_card_template", {
+    description: "Render an invitation template preview with text substituted in. Use to see how a design would look with your couple's names and wedding date. Returns the template structure including page layouts.",
+    inputSchema: {
+      variation_uuids: external_exports3.array(external_exports3.string()).describe("One or more variation UUIDs to preview (e.g. a specific size+paper of an invitation)"),
+      first_name: external_exports3.string().optional().describe("Substitute for {{first_name}} placeholders"),
+      last_name: external_exports3.string().optional().describe("Substitute for {{last_name}}"),
+      partner_first_name: external_exports3.string().optional().describe("Substitute for {{partner_first_name}}"),
+      partner_last_name: external_exports3.string().optional().describe("Substitute for {{partner_last_name}}"),
+      wedding_date: external_exports3.string().optional().describe("Substitute for {{wedding_date}}, YYYY-MM-DD. Defaults to the wedding date on file.")
+    },
+    annotations: { readOnlyHint: true }
+  }, previewCardTemplate);
+  server2.registerTool("preview_qrcode", {
+    description: "Generate a QR-code PNG for an invitation. Returns the image so it can be inspected. Use set_card_project_qrcode to actually place it on a card.",
+    inputSchema: {
+      url: external_exports3.string().describe("URL the QR code will resolve to"),
+      dimension: external_exports3.string().optional().describe("SMALL | MEDIUM (default) | LARGE"),
+      url_type: external_exports3.string().optional().describe("CUSTOM (default) | WEDDING_WEBSITE | WEDDING_WEBSITE_RSVP"),
+      enabled: external_exports3.boolean().optional().describe("Whether the QR code is enabled. Default: true.")
+    },
+    annotations: { readOnlyHint: true }
+  }, previewQrcode);
+  server2.registerTool("set_card_project_qrcode", {
+    description: "Place (or update) a QR code on a specific page of an invitation project. The page UUID comes from get_card_project (look under the customization's pages array).",
+    inputSchema: {
+      project_uuid: external_exports3.string().describe("Project UUID from list_card_projects"),
+      page_uuid: external_exports3.string().describe("Page UUID of the customization to put the QR on"),
+      url: external_exports3.string().describe("URL the QR code will resolve to"),
+      dimension: external_exports3.string().optional().describe("SMALL | MEDIUM (default) | LARGE"),
+      url_type: external_exports3.string().optional().describe("CUSTOM (default) | WEDDING_WEBSITE | WEDDING_WEBSITE_RSVP"),
+      color: external_exports3.string().optional().describe("Hex color (no #). Default: 000000"),
+      enabled: external_exports3.boolean().optional().describe("Whether to enable the QR code. Default: true.")
+    },
+    annotations: { destructiveHint: false }
+  }, setCardProjectQrcode);
+}
+
 // src/index.ts
 var server = new McpServer({
   name: "zola-mcp",
-  version: "1.2.3"
+  version: "1.3.1"
   // x-release-please-version
 });
 registerVendorTools(server);
@@ -37922,5 +38535,6 @@ registerWebsiteTools(server);
 registerWebsiteContentTools(server);
 registerWebsiteThemeTools(server);
 registerRegistryItemTools(server);
+registerInvitationTools(server);
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/client.js

@@ -65,6 +65,19 @@ export class ZolaClient {
         await this.ensureSession();
         return this.doRequest(method, path, body);
     }
+    /**
+     * Like `requestMobile` but for endpoints that return a non-JSON body
+     * (e.g. the QR-code preview which returns image bytes).
+     * Sends `Accept: *\/*` (the JSON default would 406), and returns both the
+     * raw bytes and the server's content-type so callers can pass it through.
+     */
+    async requestMobileBinary(method, path, body) {
+        await this.ensureSession();
+        const response = await this.sendWithRetry(method, path, body, false, false, '*/*');
+        const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return { bytes, contentType };
+    }
     /**
      * Get user context (wedding account ID, registry ID, etc.).
      * Uses env vars as overrides; falls back to GET /v3/users/me/context.
@@ -99,10 +112,15 @@ export class ZolaClient {
         };
         return this.cachedContext;
     }
-    async doRequest(method, path, body, isAuthRetry = false, isRateRetry = false) {
+    async doRequest(method, path, body) {
+        const response = await this.sendWithRetry(method, path, body);
+        const text = await response.text();
+        return (text ? JSON.parse(text) : null);
+    }
+    async sendWithRetry(method, path, body, isAuthRetry = false, isRateRetry = false, accept = 'application/json') {
         const sessionId = decodeJwtSessionId(this.sessionToken);
         const headers = {
-            accept: 'application/json',
+            accept,
             authorization: `Bearer ${this.sessionToken}`,
             'x-zola-platform-type': 'iphone_app',
             'x-zola-session-id': this.deviceSessionId,
@@ -120,12 +138,12 @@ export class ZolaClient {
             this.sessionToken = null;
             this.sessionExpiry = null;
             await this.refresh();
-            return this.doRequest(method, path, body, true, isRateRetry);
+            return this.sendWithRetry(method, path, body, true, isRateRetry, accept);
         }
         if (response.status === 429) {
             if (!isRateRetry) {
                 await new Promise((r) => setTimeout(r, 2000));
-                return this.doRequest(method, path, body, isAuthRetry, true);
+                return this.sendWithRetry(method, path, body, isAuthRetry, true, accept);
             }
             throw new Error('Rate limited by Zola API');
         }
@@ -133,8 +151,7 @@ export class ZolaClient {
             const text = await response.text();
             throw new Error(`Zola API error: ${response.status} ${response.statusText} for ${method} ${path}: ${text}`);
         }
-        const text = await response.text();
-        return (text ? JSON.parse(text) : null);
+        return response;
     }
     async ensureSession() {
         // Session still valid with comfortable margin

package/dist/index.js

@@ -11,9 +11,10 @@ import { registerWebsiteTools } from './tools/website.js';
 import { registerWebsiteContentTools } from './tools/website-content.js';
 import { registerWebsiteThemeTools } from './tools/website-theme.js';
 import { registerRegistryItemTools } from './tools/registry-items.js';
+import { registerInvitationTools } from './tools/invitations.js';
 const server = new McpServer({
     name: 'zola-mcp',
-    version: '1.2.3', // x-release-please-version
+    version: '1.3.1', // x-release-please-version
 });
 registerVendorTools(server);
 registerBudgetTools(server);
@@ -26,5 +27,6 @@ registerWebsiteTools(server);
 registerWebsiteContentTools(server);
 registerWebsiteThemeTools(server);
 registerRegistryItemTools(server);
+registerInvitationTools(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/invitations.js

@@ -0,0 +1,256 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+import { jsonResult, imageResult } from '../types.js';
+// ─── Tier 1: read-only ───────────────────────────────────────────────────────
+export async function listCardProjects(args) {
+    const response = await client.requestMobile('POST', '/v3/card-projects/search_request', {
+        completed: args.include_completed ?? false,
+        limit: args.limit ?? 30,
+        card_suite_uuids: [],
+        card_suite_ids: [],
+        offset: 0,
+        fetch_customizations: true,
+        include_deleted: false,
+        medium: ['PAPER', 'MAGNET', 'DIGITAL'],
+        single_sample: false,
+    });
+    return jsonResult(response.data);
+}
+export async function getCardProject(args) {
+    const response = await client.requestMobile('GET', `/v3/card-projects/${args.project_uuid}`);
+    return jsonResult(response.data);
+}
+export async function validateCardProject(args) {
+    const response = await client.requestMobile('GET', `/v3/card-projects/${args.project_uuid}/validate`);
+    return jsonResult(response.data);
+}
+export async function getCardProjectGuests(args) {
+    const response = await client.requestMobile('GET', `/v3/card-projects/${args.project_uuid}/project-guest-groups`);
+    return jsonResult(response.data);
+}
+export async function getCardSuite(args) {
+    const response = await client.requestMobile('POST', `/v4/card-catalog/suites/details/${args.suite_uuid}`);
+    return jsonResult(response.data);
+}
+export async function searchCardCatalog(args) {
+    const response = await client.requestMobile('POST', '/v3/card-catalog/search/faceted', {
+        lead_card_types: [],
+        include_updated_proof_module: true,
+        limit: args.limit ?? 50,
+        offset: 0,
+        digital_suite: false,
+        include_lead_card_type_metadata: true,
+        lead_card_type: args.card_type ?? 'INVITATION',
+        include_module: true,
+    });
+    return jsonResult(response.data);
+}
+export async function listFavoriteCardSuites() {
+    const response = await client.requestMobile('GET', '/v3/favorites/card-suites/');
+    return jsonResult(response.data);
+}
+export async function getRsvpPage() {
+    const { weddingAccountId } = await client.getContext();
+    const response = await client.requestMobile('GET', `/v3/websites/rsvps/wedding-accounts/${weddingAccountId}`);
+    return jsonResult(response.data);
+}
+// ─── Tier 2: writes ──────────────────────────────────────────────────────────
+export async function createCardProject(args) {
+    const { weddingAccountId } = await client.getContext();
+    const response = await client.requestMobile('POST', '/v3/card-projects', {
+        quantity: args.quantity ?? 150,
+        lead_variation_uuid: args.lead_variation_uuid,
+        extra_customizable: false,
+        account_id: weddingAccountId,
+        suite_uuid: args.suite_uuid,
+    });
+    return jsonResult(response.data);
+}
+export async function swapCardProjectVariation(args) {
+    const customizations = {};
+    for (const [customizationUuid, variationUuid] of Object.entries(args.customizations)) {
+        customizations[customizationUuid] = { variation_uuid: variationUuid };
+    }
+    const response = await client.requestMobile('PUT', `/v3/card-projects/${args.project_uuid}`, { customizations });
+    return jsonResult(response.data);
+}
+export async function setCardProjectGuests(args) {
+    const response = await client.requestMobile('PUT', `/v3/card-projects/${args.project_uuid}/project-guest-groups`, { guest_group_requests: args.guest_groups });
+    return jsonResult(response.data);
+}
+export async function previewCardTemplate(args) {
+    const substitutions = {};
+    if (args.first_name !== undefined)
+        substitutions.first_name = args.first_name;
+    if (args.last_name !== undefined)
+        substitutions.last_name = args.last_name;
+    if (args.partner_first_name !== undefined)
+        substitutions.partner_first_name = args.partner_first_name;
+    if (args.partner_last_name !== undefined)
+        substitutions.partner_last_name = args.partner_last_name;
+    if (args.wedding_date !== undefined) {
+        substitutions.wedding_date = args.wedding_date;
+    }
+    else {
+        const { weddingDate } = await client.getContext();
+        if (weddingDate)
+            substitutions.wedding_date = weddingDate;
+    }
+    const response = await client.requestMobile('POST', '/v3/card-templates/preview', {
+        variation_uuids: args.variation_uuids,
+        customizable: true,
+        substitutions,
+    });
+    return jsonResult(response.data);
+}
+// ─── QR code ─────────────────────────────────────────────────────────────────
+export async function previewQrcode(args) {
+    const { bytes, contentType } = await client.requestMobileBinary('PUT', '/v3/card-projects/qrcode/preview', {
+        dimension: args.dimension ?? 'MEDIUM',
+        url_type: args.url_type ?? 'CUSTOM',
+        enabled: args.enabled ?? true,
+        url: args.url,
+    });
+    // Zola's qrcode/preview returns PNG bytes with `Content-Type: image/jpeg`. Sniff magic bytes.
+    return imageResult(bytes, sniffImageType(bytes) ?? contentType);
+}
+function sniffImageType(bytes) {
+    if (bytes.length >= 8 &&
+        bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return 'image/png';
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    return null;
+}
+export async function setCardProjectQrcode(args) {
+    const response = await client.requestMobile('PUT', `/v3/card-projects/${args.project_uuid}/customization/page/${args.page_uuid}/qrcode`, {
+        dimension: args.dimension ?? 'MEDIUM',
+        url_type: args.url_type ?? 'CUSTOM',
+        color: args.color ?? '000000',
+        enabled: args.enabled ?? true,
+        url: args.url,
+    });
+    return jsonResult(response.data);
+}
+// ─── MCP registration ────────────────────────────────────────────────────────
+export function registerInvitationTools(server) {
+    server.registerTool('list_card_projects', {
+        description: 'List your invitation / save-the-date / shower-invite "card" projects (paper or digital). Returns project UUID, name, customizations, suite, and quantity.',
+        inputSchema: {
+            include_completed: z.boolean().optional().describe('Include orders that have already been placed. Default: false (drafts only).'),
+            limit: z.number().optional().describe('Max projects to return. Default: 30.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, listCardProjects);
+    server.registerTool('get_card_project', {
+        description: 'Get full details for one invitation project including all customizations (invitation, envelope, RSVP card, details card), paper/color options, and per-customization pages.',
+        inputSchema: {
+            project_uuid: z.string().describe('Project UUID from list_card_projects'),
+        },
+        annotations: { readOnlyHint: true },
+    }, getCardProject);
+    server.registerTool('validate_card_project', {
+        description: 'Validate an invitation project — reports any text-fit, image, or guest-addressing errors per customization. Use before placing an order.',
+        inputSchema: {
+            project_uuid: z.string().describe('Project UUID from list_card_projects'),
+        },
+        annotations: { readOnlyHint: true },
+    }, validateCardProject);
+    server.registerTool('get_card_project_guests', {
+        description: 'List the guest groups assigned to an invitation project, including per-group font-size overrides for printed addressing.',
+        inputSchema: {
+            project_uuid: z.string().describe('Project UUID from list_card_projects'),
+        },
+        annotations: { readOnlyHint: true },
+    }, getCardProjectGuests);
+    server.registerTool('get_card_suite', {
+        description: 'Get details for an invitation design "suite" (the family of matching invitation + RSVP + details cards), including paper types, sizes, and price range.',
+        inputSchema: {
+            suite_uuid: z.string().describe('Suite UUID (e.g. from search_card_catalog or list_favorite_card_suites)'),
+        },
+        annotations: { readOnlyHint: true },
+    }, getCardSuite);
+    server.registerTool('search_card_catalog', {
+        description: 'Search the invitation design catalog. Faceted search returning suites matching the requested card type.',
+        inputSchema: {
+            card_type: z.string().optional().describe('Lead card type: INVITATION (default), SAVE_THE_DATE, WEDDING_SHOWER_INVITATION, REHEARSAL_DINNER_INVITATION, THANK_YOU_CARD, etc.'),
+            limit: z.number().optional().describe('Max suites to return. Default: 50.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, searchCardCatalog);
+    server.registerTool('list_favorite_card_suites', {
+        description: 'List invitation design suites you have favorited (hearted).',
+        annotations: { readOnlyHint: true },
+    }, listFavoriteCardSuites);
+    server.registerTool('get_rsvp_page', {
+        description: 'Get the RSVP page settings on the wedding website (title, intro copy, visibility, customization).',
+        annotations: { readOnlyHint: true },
+    }, getRsvpPage);
+    server.registerTool('create_card_project', {
+        description: 'Create a new invitation project from a design suite and a lead variation (specific size/paper).',
+        inputSchema: {
+            suite_uuid: z.string().describe('Suite UUID from search_card_catalog or get_card_suite'),
+            lead_variation_uuid: z.string().describe('Lead variation UUID (specific size/paper/color from the suite)'),
+            quantity: z.number().optional().describe('Quantity to order. Default: 150.'),
+        },
+        annotations: { destructiveHint: false },
+    }, createCardProject);
+    server.registerTool('swap_card_project_variation', {
+        description: 'Swap one or more customizations on a project to different variations (e.g. switch paper type, color, or size). Pass a map of customization UUID → new variation UUID.',
+        inputSchema: {
+            project_uuid: z.string().describe('Project UUID from list_card_projects'),
+            customizations: z.record(z.string(), z.string()).describe('{ customization_uuid: new_variation_uuid }'),
+        },
+        annotations: { destructiveHint: false },
+    }, swapCardProjectVariation);
+    server.registerTool('set_card_project_guests', {
+        description: 'Enable / disable guest groups for an invitation project and optionally override font sizes for printed names and addresses. Pass the full list of guest groups you want recorded.',
+        inputSchema: {
+            project_uuid: z.string().describe('Project UUID from list_card_projects'),
+            guest_groups: z.array(z.object({
+                guest_group_id: z.number().describe('Guest group ID from list_guests / get_card_project_guests'),
+                enabled: z.boolean().describe('Whether to include this group in printed addressing'),
+                guest_name_font_size_override: z.number().optional().describe('Override font size for the guest name (pt)'),
+                address_font_size_override: z.number().optional().describe('Override font size for the address (pt)'),
+            })).describe('Full list of guest groups to record. Omitted groups are not affected by this call.'),
+        },
+        annotations: { destructiveHint: false },
+    }, setCardProjectGuests);
+    server.registerTool('preview_card_template', {
+        description: 'Render an invitation template preview with text substituted in. Use to see how a design would look with your couple\'s names and wedding date. Returns the template structure including page layouts.',
+        inputSchema: {
+            variation_uuids: z.array(z.string()).describe('One or more variation UUIDs to preview (e.g. a specific size+paper of an invitation)'),
+            first_name: z.string().optional().describe('Substitute for {{first_name}} placeholders'),
+            last_name: z.string().optional().describe('Substitute for {{last_name}}'),
+            partner_first_name: z.string().optional().describe('Substitute for {{partner_first_name}}'),
+            partner_last_name: z.string().optional().describe('Substitute for {{partner_last_name}}'),
+            wedding_date: z.string().optional().describe('Substitute for {{wedding_date}}, YYYY-MM-DD. Defaults to the wedding date on file.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, previewCardTemplate);
+    server.registerTool('preview_qrcode', {
+        description: 'Generate a QR-code PNG for an invitation. Returns the image so it can be inspected. Use set_card_project_qrcode to actually place it on a card.',
+        inputSchema: {
+            url: z.string().describe('URL the QR code will resolve to'),
+            dimension: z.string().optional().describe('SMALL | MEDIUM (default) | LARGE'),
+            url_type: z.string().optional().describe('CUSTOM (default) | WEDDING_WEBSITE | WEDDING_WEBSITE_RSVP'),
+            enabled: z.boolean().optional().describe('Whether the QR code is enabled. Default: true.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, previewQrcode);
+    server.registerTool('set_card_project_qrcode', {
+        description: 'Place (or update) a QR code on a specific page of an invitation project. The page UUID comes from get_card_project (look under the customization\'s pages array).',
+        inputSchema: {
+            project_uuid: z.string().describe('Project UUID from list_card_projects'),
+            page_uuid: z.string().describe('Page UUID of the customization to put the QR on'),
+            url: z.string().describe('URL the QR code will resolve to'),
+            dimension: z.string().optional().describe('SMALL | MEDIUM (default) | LARGE'),
+            url_type: z.string().optional().describe('CUSTOM (default) | WEDDING_WEBSITE | WEDDING_WEBSITE_RSVP'),
+            color: z.string().optional().describe('Hex color (no #). Default: 000000'),
+            enabled: z.boolean().optional().describe('Whether to enable the QR code. Default: true.'),
+        },
+        annotations: { destructiveHint: false },
+    }, setCardProjectQrcode);
+}

package/dist/types.js

@@ -2,6 +2,10 @@
 export function jsonResult(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
+/** Wrap raw image bytes as an MCP image-content tool result. */
+export function imageResult(bytes, mimeType) {
+    return { content: [{ type: 'image', data: Buffer.from(bytes).toString('base64'), mimeType }] };
+}
 /**
  * Build a partial-update body containing only keys from `args` that are not undefined.
  * Used by tools that send PATCH-style updates where omitting a key means "leave unchanged".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zola-mcp",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "mcpName": "io.github.chrischall/zola-mcp",
   "description": "Zola wedding MCP server for Claude",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -46,7 +46,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.6.0",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2"
   },

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/zola-mcp",
     "source": "github"
   },
-  "version": "1.2.3",
+  "version": "1.3.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "zola-mcp",
-      "version": "1.2.3",
+      "version": "1.3.1",
       "transport": {
         "type": "stdio"
       },