# QuickCasa MCP Server - Setup Instructions

## What is this?
QuickCasa exposes an MCP (Model Context Protocol) server that lets AI coding tools like Claude Code, Cursor, Windsurf, and others create, edit, and publish websites on the QuickCasa platform.

## Prerequisites
1. A QuickCasa account with an active company
2. An API key (get one from the QuickCasa admin portal under Settings > API Keys)

## Connect via Claude Code

### Option A: CLI command
```bash
claude mcp add --transport http quickcasa https://api.quickcasa.ai/v1/mcp \
  --header "x-api-key: YOUR_API_KEY"
```

### Option B: .mcp.json file (put in your project root)
```json
{
  "mcpServers": {
    "quickcasa": {
      "type": "http",
      "url": "https://api.quickcasa.ai/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

### Option C: With environment variables
```json
{
  "mcpServers": {
    "quickcasa": {
      "type": "http",
      "url": "${QC_API_URL:-https://api.quickcasa.ai}/v1/mcp",
      "headers": {
        "x-api-key": "${QC_API_KEY}"
      }
    }
  }
}
```

## Connect via Cursor
Add to your `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "quickcasa": {
      "url": "https://api.quickcasa.ai/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

## Getting Started After Connecting

Once connected, start by telling the AI who you are:

> "My name is pat, password is 123456"

This calls the **authenticate** tool, which loads (or creates) your personal session. Your active website, preferences, and memories are restored from your last session.

If this is your first time, pick a website:

> "Show me my websites" → list_websites
> "Switch to the developer portal" → switch_website

Your website choice is saved -  next time you authenticate, it is already loaded.

## Sessions & Memory

The MCP server remembers you across conversations:

- **authenticate** -  Log in with your username and passkey. Loads your session and memories.
- **switch_website** -  Change your active website. Persists across sessions.
- **save_memory** -  Save a preference or note about yourself. The AI will also do this proactively.
- **get_memories** -  Retrieve all your saved memories.
- **delete_memory** -  Remove a specific memory.

Multiple developers can share the same API key -  each one authenticates with their own username and gets their own session, website selection, and memories.

## Legacy: Hardcoded Website ID

You can still pass a website ID directly if you prefer:
- Query parameter: `?websiteId=YOUR_WEBSITE_ID` on the URL
- Header: `x-website-id: YOUR_WEBSITE_ID`

These take priority over session-based resolution. This is useful for scripts and CI/CD pipelines.

## Available Tools (46 total)

### Session & Memory
- **authenticate** - Log in with username/passkey, load session and memories
- **switch_website** - Change active website (persists)
- **get_session** - View current session info
- **save_memory** - Save something for future sessions
- **get_memories** - Retrieve all memories
- **delete_memory** - Remove a memory

### File Operations
- **read_file** - Read a code file by path
- **write_file** - Create or update a file
- **delete_file** - Delete a file
- **list_files** - List all project files
- **search_files** - Search across all files

### Page Operations
- **create_page** - Create a new page with scaffold files
- **list_pages** - List all pages
- **delete_page** - Delete a page and its files
- **duplicate_page** - Copy a page to a new slug

### Website & Data
- **list_websites** - List all websites for your company
- **create_website** - Create a new website
- **get_website_info** - Brand colours, fonts, AI context
- **update_website_settings** - Update brand, fonts, AI context
- **get_code_config** - CDN libraries, global settings
- **get_inventory** - Property listings
- **get_property_details** - Detailed data for a specific entity
- **get_property_hierarchy** - Full property tree
- **get_cms_collections** - CMS collection definitions
- **get_forms** - Custom forms + flow forms with embedUrls (forms MUST be embedded as iframes, never hand-built)
- **get_media_library** - Uploaded images and media

### Fonts & Libraries
- **add_google_font** - Add a Google Font
- **remove_font** - Remove a font
- **list_fonts** - List configured fonts
- **add_library** - Add a CDN library
- **remove_library** - Remove a CDN library

### Local Development Sync
- **sync_push** - Upload local files (with stack validation)
- **sync_pull** - Download all files from QuickCasa
- **sync_status** - Compare local vs remote files
- **validate_project** - Check files against stack requirements

### Publishing & Revisions
- **publish_website** - Publish to production
- **get_preview_url** - Get the preview URL
- **get_domain_info** - Domain and DNS details
- **create_revision** - Snapshot a page
- **list_revisions** - List revisions for a page
- **restore_revision** - Restore a previous version

### Utilities
- **send_bug_report** - Report a bug to the QuickCasa team

## Stack Requirements
QuickCasa websites use a specific stack. The validate_project tool checks for compliance:
- **HTML, CSS, JS only** - no TypeScript, JSX, SCSS, or LESS
- **No npm packages** - use CDN-loaded libraries via <script> tags
- **No ES module imports** - vanilla JavaScript only
- **Web Components** - use customElements.define() for reusable components. Folder names in components/ MUST contain a hyphen (e.g. site-navbar, not navbar) because the folder name is used verbatim as the custom element tag and the HTML spec requires a hyphen.
- **Directory structure**: pages/, components/, shared/

## Example Workflow
1. "My name is pat, password is 123456" → authenticate
2. "Show me my websites" → list_websites
3. "Switch to the developer portal" → switch_website
4. "Pull the project" → sync_pull
5. "Show me the home page" → read_file pages/home/index.html
6. "Add a testimonials section" → write_file
7. "What properties do we have?" → get_inventory
8. "Push everything and publish" → sync_push + publish_website