zola-mcp 0.3.0

package/dist/client.js

@@ -0,0 +1,194 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+try {
+    const { config } = await import('dotenv');
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    config({ path: join(__dirname, '..', '.env'), override: false });
+}
+catch {
+    // bundled mode — rely on process.env
+}
+const BASE_URL = 'https://www.zola.com';
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36';
+// Session refresh: GET this endpoint with usr+guid cookies to obtain a fresh us
+// token plus CSRF tokens in one round-trip. Zola auto-refreshes on this path.
+const REFRESH_PATH = '/website-nav/web-api/v1/user/get';
+function decodeJwtExp(token) {
+    const parts = token.split('.');
+    if (parts.length < 3 || !parts[1]) {
+        throw new Error(`Invalid JWT structure: expected 3 dot-separated parts, got ${parts.length}`);
+    }
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    if (typeof payload.exp !== 'number') {
+        throw new Error('JWT payload missing numeric "exp" claim');
+    }
+    return payload.exp;
+}
+function parseCookies(headers) {
+    const cookies = {};
+    const setCookieValues = typeof headers.getSetCookie === 'function'
+        ? headers.getSetCookie()
+        : // Fallback for environments without getSetCookie(). The comma-split heuristic
+            // can misparse cookies whose values contain commas not preceded by a space,
+            // but this branch is never reached on Node 18.14+ which is our target runtime.
+            (headers.get('set-cookie') ?? '').split(/,(?=[^ ])/).filter(Boolean);
+    for (const raw of setCookieValues) {
+        const match = raw.match(/^([^=]+)=([^;]*)/);
+        if (match)
+            cookies[match[1].trim()] = match[2].trim();
+    }
+    return cookies;
+}
+const SETUP_HINT = 'To fix: open Zola in Chrome → DevTools → Application → Cookies → www.zola.com → ' +
+    'copy "usr" → ZOLA_REFRESH_TOKEN and "guid" → ZOLA_GUID in .env';
+export class ZolaClient {
+    sessionToken = null;
+    sessionExpiry = null;
+    csrfSecret = null;
+    csrfToken = null;
+    async request(method, path, body) {
+        await this.ensureSession();
+        if (method !== 'GET')
+            await this.ensureCsrf();
+        return this.doRequest(method, path, body);
+    }
+    async doRequest(method, path, body, isAuthRetry = false, isRateRetry = false) {
+        const headers = {
+            accept: 'application/json',
+            'user-agent': USER_AGENT,
+            cookie: this.buildCookieHeader(),
+        };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (method !== 'GET' && this.csrfToken) {
+            headers['x-csrf-token'] = this.csrfToken;
+        }
+        const response = await fetch(`${BASE_URL}${path}`, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (response.status === 401 && !isAuthRetry) {
+            this.sessionToken = null;
+            this.sessionExpiry = null;
+            await this.refresh();
+            return this.doRequest(method, path, body, true, isRateRetry);
+        }
+        if (response.status === 429) {
+            if (!isRateRetry) {
+                await new Promise((r) => setTimeout(r, 2000));
+                return this.doRequest(method, path, body, isAuthRetry, true);
+            }
+            throw new Error('Rate limited by Zola API');
+        }
+        if (!response.ok) {
+            throw new Error(`Zola API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+        }
+        const text = await response.text();
+        return (text ? JSON.parse(text) : null);
+    }
+    async ensureSession() {
+        // Session still valid with comfortable margin
+        if (this.sessionToken && this.sessionExpiry) {
+            if (this.sessionExpiry.getTime() - Date.now() > 5 * 60 * 1000)
+                return;
+        }
+        // Note: ZOLA_SESSION_TOKEN is read from env only on first load (sessionToken === null).
+        // If the env value is rotated mid-run, restart the server to pick up the new token.
+        if (this.sessionToken === null) {
+            const envSession = process.env.ZOLA_SESSION_TOKEN;
+            if (envSession) {
+                try {
+                    const exp = decodeJwtExp(envSession);
+                    if (exp * 1000 - Date.now() > 5 * 60 * 1000) {
+                        this.sessionToken = envSession;
+                        this.sessionExpiry = new Date(exp * 1000);
+                        return;
+                    }
+                }
+                catch {
+                    // Invalid JWT in env — fall through to refresh
+                }
+            }
+        }
+        await this.refresh();
+    }
+    async ensureCsrf() {
+        if (this.csrfToken)
+            return;
+        // CSRF tokens are normally obtained during refresh(). This fallback handles
+        // the case where a valid ZOLA_SESSION_TOKEN was used and refresh() was skipped.
+        try {
+            const resp = await fetch(`${BASE_URL}/`, {
+                headers: { 'user-agent': USER_AGENT },
+            });
+            const cookies = parseCookies(resp.headers);
+            if (cookies['_csrf'])
+                this.csrfSecret = cookies['_csrf'];
+            if (cookies['CSRF-TOKEN'])
+                this.csrfToken = cookies['CSRF-TOKEN'];
+        }
+        catch {
+            // non-fatal: proceed without CSRF
+        }
+    }
+    async refresh() {
+        const refreshToken = process.env.ZOLA_REFRESH_TOKEN;
+        if (!refreshToken)
+            throw new Error('ZOLA_REFRESH_TOKEN must be set');
+        const guid = process.env.ZOLA_GUID;
+        if (!guid)
+            throw new Error('ZOLA_GUID must be set');
+        // GET /website-nav/web-api/v1/user/get with usr+guid — Zola auto-issues a
+        // fresh us token and CSRF cookies in the Set-Cookie response headers.
+        const cookieParts = [`usr=${refreshToken}`, `guid=${guid}`];
+        if (this.sessionToken)
+            cookieParts.push(`us=${this.sessionToken}`);
+        let resp;
+        try {
+            resp = await fetch(`${BASE_URL}${REFRESH_PATH}`, {
+                headers: {
+                    accept: 'application/json',
+                    'user-agent': USER_AGENT,
+                    cookie: cookieParts.join('; '),
+                },
+            });
+        }
+        catch (err) {
+            throw new Error(`Zola session refresh network error: ${String(err)}\n${SETUP_HINT}`);
+        }
+        if (!resp.ok) {
+            throw new Error(`Zola session refresh failed: ${resp.status} ${resp.statusText}\n${SETUP_HINT}`);
+        }
+        const cookies = parseCookies(resp.headers);
+        if (!cookies['us']) {
+            throw new Error('Zola session refresh returned no session token — ZOLA_REFRESH_TOKEN or ZOLA_GUID may be expired.\n' +
+                SETUP_HINT);
+        }
+        const exp = decodeJwtExp(cookies['us']);
+        this.sessionToken = cookies['us'];
+        this.sessionExpiry = new Date(exp * 1000);
+        // Capture CSRF tokens from the same response to avoid a separate GET /
+        if (cookies['_csrf'])
+            this.csrfSecret = cookies['_csrf'];
+        if (cookies['CSRF-TOKEN'])
+            this.csrfToken = cookies['CSRF-TOKEN'];
+    }
+    buildCookieHeader() {
+        const parts = [];
+        if (this.sessionToken)
+            parts.push(`us=${this.sessionToken}`);
+        const refreshToken = process.env.ZOLA_REFRESH_TOKEN;
+        if (refreshToken)
+            parts.push(`usr=${refreshToken}`);
+        const guid = process.env.ZOLA_GUID;
+        if (guid)
+            parts.push(`guid=${guid}`);
+        if (this.csrfSecret)
+            parts.push(`_csrf=${this.csrfSecret}`);
+        if (this.csrfToken)
+            parts.push(`CSRF-TOKEN=${this.csrfToken}`);
+        return parts.join('; ');
+    }
+}
+export const client = new ZolaClient();

package/dist/index.js

@@ -0,0 +1,10 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+const server = new McpServer({
+    name: 'zola-mcp',
+    version: '0.3.0',
+});
+// Domain tool registrations are added here as each domain is built.
+// Example (future): registerRegistryTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "zola-mcp",
+  "version": "0.3.0",
+  "description": "Zola wedding MCP server for Claude",
+  "author": "Claude Sonnet 4.6 (AI) <https://www.anthropic.com/claude>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischall/zola-mcp.git"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "skills",
+    ".mcp.json"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "type": "module",
+  "bin": {
+    "zola-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && npm run bundle",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "dev": "node --env-file=.env dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "esbuild": "^0.27.5",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/skills/zola/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: zola
+description: This skill should be used when the user asks about Zola wedding planning data. Triggers on phrases like "check Zola", "Zola vendors", "wedding budget", "Zola guests", "RSVP status", "seating chart", "vendor inquiries", "wedding registry", "gift tracker", or any request involving wedding vendors, guest list, budget, seating, events, registry, or inquiry management on Zola.
+---
+
+# zola-mcp
+
+MCP server for Zola — 27 tools for managing your entire wedding via the Zola mobile API.
+
+## Tools
+
+### Vendors
+- `list_vendors` — List all booked vendors
+- `search_vendors` — Search vendors by name/category
+- `add_vendor` — Book a new vendor
+- `update_vendor` — Update vendor details
+- `remove_vendor` — Unbook a vendor
+
+### Budget
+- `get_budget` — Budget summary with all items
+- `update_budget_item` — Update cost or note
+
+### Guests
+- `list_guests` — List all guest groups with stats
+- `add_guest` — Add a guest group
+- `update_guest_address` — Update mailing address
+- `remove_guest` — Remove a guest group
+
+### Seating
+- `list_seating_charts` — List charts
+- `get_seating_chart` — Chart with tables/seats/occupants
+- `list_unseated_guests` — Guests not yet seated
+- `assign_seat` — Assign guest to seat
+
+### Inquiries
+- `list_inquiries` — All vendor inquiries
+- `get_inquiry_conversation` — Full conversation
+- `mark_inquiry_read` — Mark as read
+
+### Events & RSVPs
+- `list_events` — All events with RSVP counts
+- `track_rsvps` — RSVP tracking per event
+- `update_event` — Update event details
+
+### Registry & Gifts
+- `get_registry` — Registry categories and items
+- `get_gift_tracker` — Gifts received and thank-you status
+
+### Discovery
+- `get_wedding_dashboard` — Planning overview
+- `search_storefronts` — Search marketplace
+- `get_storefront` — Full vendor details
+- `list_favorites` — Saved vendors