squarespace-mcp: Instructions file for Claude Code

Squarespace MCP — CLAUDE.md

What This Project Is

MCP server that edits Squarespace websites via the Content Save API. Exposes 134 tools for text, images, sections, blocks, pages, menus, forms, commerce, navigation, design, code injection, blog posts, gallery management, PDF menu parsing, section snapshots, Wayback Machine recovery, and more. Used from Claude Desktop and Claude Code (usually parked — revive via /mcp-revive squarespace).

Commands

npm run mcp     # Start MCP server (tsx src/mcp-server/index.ts)
npm run build   # TypeScript compile — the parked MCP config runs dist/, so rebuild after src changes
npm test        # vitest run (~1508 tests, 69 files; 15 known auth/login failures in 3 files pre-date 2026-10-08)
node scripts/relogin.mjs [subdomain...] [--headless]   # re-auth the Squarespace session
node scripts/smoke.mjs [subdomain]                     # endpoint-drift check (read tools vs live API)

Auth & Sessions (read this before debugging 401s)

Auth is cookie-based (storage/auth/sqsp-session.json, a Playwright storageState). The Content API needs a per-site member-session + crumb pair for every site; sessions go stale in ~hours and any browser use of the cookies rotates them, invalidating the stored copy.

• 401 anywhere → call the sq_relogin tool (headless, no user action) or run node scripts/relogin.mjs <subdomain>. Credentials come from SQSP_EMAIL/SQSP_PASSWORD in .env; no CAPTCHA has ever appeared.
• Never "fix" a 401 with sq_restore_session right after a fresh login — the .bak is the older, expired session.
• Endpoint drift is real. Squarespace changes internal APIs under this server. 2026-07-08: injection values moved out of /api/settings (read from /api/config/GetInjectionSettings), and SaveInjectionSettings requires form-encoded header/footer (old injectHeader names were accepted-but-ignored — a silent no-op). 2026-07-19: GET /api/settings started serializing set-type fields as {key: true} maps while PUT /api/settings only accepts the array form the editor UI sends — so read-modify-write PUTs 400 (empty body) until sanitized; see sanitizeSettingsForPut() in content-save/site.ts. 2026-08-07: rendered page HTML dropped the data-page-sections attribute, breaking resolvePageIds on every uncached page ("Could not resolve page"); the editor's GET /api/page-sections/by-collection-ids?collectionIds={id} is now the authoritative pageSectionsId source — see getPageSectionsIdByCollectionId() in content-save/pages.ts. When a tool errors or silently no-ops, run scripts/smoke.mjs first, then capture ground truth with scripts/capture-config-api.mjs <subdomain> </config/...> — headless for read traffic, --headful to drive the panel by hand (e.g. click SAVE) while it records every request with full write payloads. Diff the UI's payload against the MCP client's. Note most config panels stage changes and only write on an explicit SAVE click; nothing fires on toggle/typing. Use the trial/sandbox site (sphere-green-b2j7) for write experiments, never a live client site.