Squarespace MCP Editor
A Model Context Protocol (MCP) server that provides live editing capabilities for Squarespace websites through browser automation and intelligent site knowledge management.
Project Overview
This codebase implements a patch-based editing system for Squarespace sites using Playwright browser automation, site crawling for knowledge management, and strict schema validation for safe content updates.
Architecture Principles
When working with this codebase, adhere to these core architectural principles:
1. Site Brain Knowledge Base
Maintain complete site understanding through crawling and snapshotsStore structured data in `./site-brain/` directoryEnable search across all contentBuild reusable component models from crawled data2. Patch-Based Editing
Represent ALL changes as patch files in JSON formatValidate every patch using Zod schemas before applicationSupport operations: `updateTextBlock`, `updateButton`, `updateImage`, and othersAlways support dry-run and safe-publish modes3. Browser Automation Strategy
Use Playwright to interact with Squarespace editor UIUtilize BlockHint system to locate elements (nearText, heading, buttonLabel, selector)Persist browser sessions to avoid repeated loginsCapture screenshots for debugging and verification4. Safety First
NEVER auto-publish unless explicitly enabled by userValidate all patches before applicationLog all operations with structured logging (Pino)Store before/after artifacts for potential rollbackCode Style Guidelines
TypeScript Standards
Use strict mode at all timesPrefer interfaces over types for public APIsUse Zod schemas for runtime validationAlways handle errors explicitly (no silent failures)Use async/await over raw PromisesError Handling Pattern
```typescript
try {
// operation
} catch (error: any) {
logger.error({ context, error }, 'Operation failed');
return { success: false, error: error.message };
}
```
Logging Pattern
```typescript
import { createModuleLogger } from '../utils/logger.js';
const logger = createModuleLogger('module-name');
logger.info({ data }, 'Operation started');
logger.debug({ details }, 'Debug info');
logger.error({ error }, 'Operation failed');
```
File Operations Pattern
```typescript
import { readJson, writeJson, ensureDir } from '../utils/helpers.js';
// Always ensure directory exists before writing
await ensureDir('./path');
await writeJson('./path/file.json', data);
```
Common Implementation Tasks
Adding a New MCP Tool
1. Define the tool in the `TOOLS` array in `src/index.ts`
2. Add handler case in `handleToolCall()` function
3. Implement the logic (may require creating new modules)
4. Update README documentation with tool details
Adding a New Patch Operation
1. Add operation to `PatchOperationSchema` in `src/types/schemas.ts`
2. Implement handler in `src/browser/editor.ts`
3. Add case handler in `src/patch/manager.ts` `applyPatch()` function
4. Test thoroughly with dry-run mode first
Debugging Browser Automation
Set `PLAYWRIGHT_HEADLESS=false` environment variable to watch browser in actionCheck screenshots in `./site-brain/cache/screenshots/` directoryIncrease `PLAYWRIGHT_SLOW_MO` for slower execution to observe behaviorReview logs for selector matching issues and element location problemsModule Organization
Maintain loose coupling between modules:
`crawler` → depends on utils only`browser` → depends on config and utils only`patch` → depends on browser and utils`search` → depends on utils only`index.ts` → orchestrates all modulesFile Structure
`/src` - TypeScript source code`/dist` - Compiled JavaScript output`/site-brain` - Runtime knowledge base and artifacts`/.vscode` - Editor configurationBuild Commands
`npm run build` - Compile TypeScript to JavaScript`npm run watch` - Watch mode compilation for development`npm run lint` - Check code style compliance`npm run format` - Auto-format code using PrettierDevelopment Workflow
1. Make changes in `/src` directory
2. Build with `npm run build`
3. Test using appropriate CLI command with `DRY_RUN=true`
4. Check logs and screenshots for verification
5. Verify on live site only if not in dry-run mode
Important Constraints
Squarespace Limitations
No official API for content editing existsEditor UI may change without notice (brittle selectors)Must rely on browser automation exclusivelySession management is critical for performanceSafety Requirements
Never publish without explicit user confirmationAlways validate patches against schemasLog ALL operations with structured loggingStore artifacts (before/after states) for potential rollbackPerformance Considerations
Crawler must respect delays to avoid rate limitingLimit concurrent requests to SquarespaceCache browser sessions to minimize login overheadMinimize unnecessary re-crawling of unchanged pagesChange Management
When making changes to this codebase:
Maintain backward compatibility with existing patch filesUpdate Zod schemas carefully (breaking changes require migration strategy)Add comprehensive logging for all new operationsUpdate documentation in README and inline commentsTest thoroughly with real Squarespace site in dry-run mode firstCode Review Checklist
Before submitting changes, verify:
[ ] Type safety maintained throughout (no `any` types without justification)[ ] Error handling present for all fallible operations[ ] Structured logging added for operations[ ] Schema validation included for all external inputs[ ] Documentation updated (README, JSDoc comments)[ ] Tested in dry-run mode with real site[ ] Screenshots reviewed for visual verificationTesting Strategy
Manual testing required (Squarespace is a live system)ALWAYS test with `DRY_RUN=true` environment variable firstUse example patches for regression testingVerify changes on published site only after thorough dry-run testingCheck browser screenshots for visual confirmationKey Technologies
**TypeScript + Node.js 20+** - Core runtime**@modelcontextprotocol/sdk** - MCP server implementation**Playwright** - Browser automation for Squarespace interaction**Cheerio** - HTML parsing for site crawling**Zod** - Runtime schema validation**Pino** - Structured loggingResources
MCP SDK Documentation: https://modelcontextprotocol.ioPlaywright Documentation: https://playwright.devSquarespace Platform: https://www.squarespace.comNotes
This is an MVP with core functionality working. Future enhancements should maintain the same architectural principles (safety-first, patch-based, knowledge-driven) while extending capabilities. All new features must respect the constraint that Squarespace provides no official editing API.