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

2. Patch-Based Editing

3. Browser Automation Strategy

4. Safety First

Code Style Guidelines

TypeScript Standards

Error 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

Module Organization

Maintain loose coupling between modules:

File Structure

Build Commands

Development 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

Safety Requirements

Performance Considerations

Change Management

When making changes to this codebase:

Code Review Checklist

Before submitting changes, verify:

Testing Strategy

Key Technologies

Resources

Notes

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.