# 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)
3. A website ID (visible in the URL when editing a website: /website-builder/{websiteId})

## Connect via Claude Code

### Option A: CLI command
```bash
claude mcp add --transport http quickcasa https://api.quickcasa.ai/v1/mcp?websiteId=YOUR_WEBSITE_ID \
  --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?websiteId=YOUR_WEBSITE_ID",
      "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?websiteId=${QC_WEBSITE_ID}",
      "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?websiteId=YOUR_WEBSITE_ID",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

## Available Tools (37 total)

### 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

### Website & Data
- **get_website_info** - Brand colours, fonts, AI context
- **get_code_config** - CDN libraries, global settings
- **get_inventory** - Property listings
- **get_forms** - Custom form definitions
- **get_media_library** - Uploaded images and media

### 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
- **publish_website** - Publish to production

## 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
- **Directory structure**: pages/, components/, shared/

## Example Workflow
1. "Pull the project from QuickCasa" → sync_pull
2. "Show me the home page" → read_file pages/home/index.html
3. "Add a testimonials section" → write_file pages/home/index.html (with new content)
4. "Create an about page" → create_page + write_file
5. "What properties do we have?" → get_inventory
6. "Push everything and publish" → sync_push + publish_website

## Local Development
For the best experience, create a local folder matching QuickCasa's structure:
```
my-website/
  pages/
    home/
      index.html
      styles.css
      script.js
    about/
      ...
  components/
    navbar/
      ...
  shared/
    global.css
    utilities.js
  quickcasa.config.json
```

Use sync_pull to populate it, edit locally, then sync_push to upload.