# Fast Mode MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to convert, validate, and deploy websites to [Fast Mode](https://fastmode.ai).

## What is Fast Mode?

Fast Mode is a modern CMS platform that turns static HTML websites into fully editable, content-managed sites. Unlike traditional CMSs that force you into their templates, Fast Mode works with **your existing design** — just add simple template tokens and your site becomes editable.

### Key Features

- **Keep Your Design** — Use any HTML/CSS. No themes, no page builders, no compromises.
- **Custom Collections** — Create any content type you need (blog posts, team members, products, etc.)
- **Visual Editor** — Edit content directly on your live site.
- **Instant Deploy** — Push from GitHub or upload directly. Sites go live in seconds.
- **Forms & Submissions** — Collect form data without any backend code.
- **Custom Domains** — Use your own domain with automatic SSL.

### Links

- **Website:** [fastmode.ai](https://fastmode.ai)
- **Dashboard:** [app.fastmode.ai](https://app.fastmode.ai)
- **Documentation:** [docs.fastmode.ai](https://docs.fastmode.ai)

---

## MCP Server Tools

This MCP server provides tools for AI assistants (Claude, Cursor, etc.) to help you convert websites to Fast Mode format and deploy them.

### IMPORTANT: Start with get_started

The `get_started` tool is your entry point for any task. It automatically:
- Checks authentication status
- Lists your projects with status
- Shows collection/field details
- Returns the exact workflow for your task

```
get_started(intent: "add_content", projectId: "my-project")
```

**Available intents:**
| Intent | Use Case |
|--------|----------|
| `explore` | See what projects and content exist |
| `add_content` | Create/edit CMS items (blog posts, team, etc.) |
| `update_schema` | Add collections or fields |
| `convert` | Build a new website from scratch |
| `deploy` | Push changes live |

### Validation Tools (No Auth Required)

These tools work without authentication — perfect for converting and validating websites before deploying:

| Tool | Description |
|------|-------------|
| `get_started` | **CALL FIRST** - Checks state and returns exact workflow |
| `get_field_types` | Get available field types for creating custom fields |
| `validate_manifest` | Validate your manifest.json file |
| `validate_template` | Check HTML templates for correct token usage, form handling, and schema validation |
| `validate_package` | Validate complete package structure |
| `get_example` | Get example code for common patterns |
| `get_conversion_guide` | Step-by-step website conversion guide |

### MCP Resources (Alternative to Tools)

The server also exposes static content as **MCP Resources** that can be browsed and fetched:

| Resource URI | Description |
|--------------|-------------|
| `fastmode://help` | Quick start guide |
| `fastmode://reference/field-types` | Available field types for creating collections |
| `fastmode://guide/{section}` | Conversion guide sections (full, first_steps, analysis, structure, seo, manifest, templates, tokens, forms, assets, checklist, common_mistakes) |
| `fastmode://examples/{type}` | Code examples (manifest_basic, blog_post_template, form_handling, etc.) |

Resources provide the same content as `get_field_types`, `get_conversion_guide`, and `get_example` tools but in a browsable format.

### What validate_template Checks

The `validate_template` tool performs comprehensive validation:

**Token Validation:**
- Balanced `{{#each}}`, `{{#if}}`, `{{#unless}}` blocks
- Proper triple braces for richText fields (`{{{body}}}`)
- Asset paths with `/public/` prefix
- YouTube iframe required attributes

**Form Validation (v1.5.0+):**
- `data-form` attribute on forms (error if missing)
- Input `name` attributes (error if missing - data won't be captured)
- Submit button presence (warning)
- Deprecation warning for legacy `data-form-name` attribute
- Suggestion to create a thank-you page

**Static Page Validation:**
- Detects `{{#each collection}}` loops (e.g., featured posts on homepage)
- Validates referenced collections exist in schema
- Error if collections don't exist with `sync_schema` instructions

**Schema Validation (when authenticated):**
- Checks all tokens against actual project schema
- Reports missing fields with exact `sync_schema` call to create them

### Authenticated Tools

These tools require a Fast Mode account. The MCP server will automatically open your browser for login when needed:

| Tool | Description |
|------|-------------|
| `list_projects` | List all your Fast Mode projects |
| `get_tenant_schema` | Get schema for a specific project (including custom fields) |
| `create_site` | Create a new Fast Mode project |
| `deploy_package` | Deploy a website package to Fast Mode |
| `sync_schema` | Create collections and fields in your project |
| `generate_sample_items` | Generate placeholder content for collections |

### CMS Item Management Tools

Manage content directly from your AI assistant:

| Tool | Description |
|------|-------------|
| `create_cms_item` | Create a new item in a collection (blog post, team member, etc.) |
| `list_cms_items` | List items in a collection with optional sorting/filtering |
| `get_cms_item` | Get a single item by its slug |
| `update_cms_item` | Update an existing item's name, data, or publish status |
| `delete_cms_item` | Delete an item (requires explicit user confirmation) |

**⚠️ Delete Safety:** The `delete_cms_item` tool requires `confirmDelete: true` and will prompt you to ask the user for permission before deleting anything.

---

## Installation

The MCP server automatically downloads prebuilt binaries for your platform during installation. This eliminates Node.js PATH issues that can occur in some IDE environments.

### For Claude Code (CLI & VS Code Extension)

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "fastmode": {
      "command": "npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}
```

### For Cursor

Add to your Cursor MCP settings (`~/.cursor/mcp.json` or project-level `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "fastmode": {
      "command": "npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}
```

### For Claude Desktop

Add to your Claude config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "fastmode": {
      "command": "npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}
```

### For Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "fastmode": {
      "command": "npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}
```

### Troubleshooting

If the MCP server doesn't start (especially with custom Node.js installations like nvm, volta, or homebrew):

**Option 1: Use shell wrapper (macOS/Linux)**

```json
{
  "mcpServers": {
    "fastmode": {
      "command": "/bin/zsh",
      "args": ["-l", "-c", "npx -y fastmode-mcp"]
    }
  }
}
```

**Option 2: Use absolute path to npx**

Find your npx path with `which npx`, then:

```json
{
  "mcpServers": {
    "fastmode": {
      "command": "/path/to/your/npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}
```

**After any config change:** Fully quit and reopen your IDE (Cmd+Q on macOS, not just close window).

---

## Quick Start

### 1. Start with get_started

Ask your AI assistant what you want to do:

> "I want to add some blog posts to my Fast Mode site"

The AI will call `get_started(intent: "add_content")` to see your projects and schema.

### 2. Convert a Website

> "Convert this website to Fast Mode format"

The AI will use validation tools to create a proper package structure.

### 2. Validate & Create Schema (Important!)

Before deploying, validate your templates against the project schema:

> "Validate my templates against my Fast Mode project and create any missing fields or collections"

**The AI will automatically:**
1. Check each template for fields that don't exist
2. Call `get_field_types` to see available types
3. Call `sync_schema` to create missing collections and fields
4. Confirm everything is ready for deployment

⚠️ **This step is critical!** Templates won't render correctly if the fields don't exist.

### 3. Deploy to Fast Mode

Once your schema is synced:

> "Deploy this to Fast Mode"

The AI will:
1. Open your browser for login (if needed)
2. Show your existing projects or create a new one
3. Upload and deploy your site

### 4. Your Site is Live!

Your site will be available at `https://your-site.fastmode.ai` and you can manage content at [app.fastmode.ai](https://app.fastmode.ai).

---

## Schema Sync (Critical for Custom Fields)

When your templates use custom fields, you **must** create them in the CMS before deploying. The MCP server handles this automatically.

### Recommended Workflow

```
1. "Convert my website to Fast Mode format"
2. "Validate all templates against my project and create any missing fields"
3. "Deploy to Fast Mode"
```

The AI will:
- Use `validate_template` with your project ID to find missing fields
- Use `get_field_types` to determine the correct field type for each
- Use `sync_schema` to create fields/collections before deploying

### What Happens During Validation

When you validate a template with a project ID, the tool will:

1. **✅ All fields exist** → Schema validation passed, ready to deploy
2. **🚨 Missing fields** → Provides exact `sync_schema` call to create them
3. **🚨 Missing collection** → Provides exact `sync_schema` call to create collection with fields

### Available Field Types

| Type | Use For |
|------|---------|
| `text` | Short text (titles, names, single lines) |
| `richText` | Long formatted content with HTML (blog bodies, bios) |
| `number` | Numeric values (prices, counts, order) |
| `boolean` | True/false toggles (featured, published) |
| `date` | Date picker (publishedAt, eventDate) |
| `datetime` | Date + time picker |
| `image` | Image uploads (heroImage, thumbnail, photo) |
| `url` | Links (website, social profiles) |
| `videoEmbed` | **Use for video content** - YouTube, Vimeo, Wistia, Loom. Template: `{{#videoEmbed field}}{{/videoEmbed}}` |
| `email` | Email addresses |
| `select` | Single dropdown choice (category, status) |
| `multiSelect` | Multiple dropdown choices (tags) |
| `relation` | **Use for linked content** (author → authors). Template: `{{author.name}}`, `{{author.url}}` |

### Field Type Tips

The MCP server now provides intelligent field type suggestions when you use sync_schema:

**For Video Content:**
- Use `videoEmbed` type (NOT `url` or `text`)
- Outputs responsive iframes with correct YouTube settings
- Template: `{{#videoEmbed videoFieldName}}{{/videoEmbed}}`

**For Linked Content:**
- Use `relation` type (NOT `text`)
- Links to items in another collection
- Access with dot notation: `{{author.name}}`, `{{category.url}}`
- Requires `referenceCollection` parameter

### Example: Adding Fields to Existing Collection

```json
{
  "projectId": "my-project",
  "fieldsToAdd": [
    {
      "collectionSlug": "posts",
      "fields": [
        { "slug": "heroImage", "name": "Hero Image", "type": "image" },
        { "slug": "category", "name": "Category", "type": "select", "options": "Tech,Business,Lifestyle" }
      ]
    }
  ]
}
```

### Example: Creating a Custom Collection

```json
{
  "projectId": "my-project",
  "collections": [
    {
      "slug": "products",
      "name": "Products",
      "nameSingular": "Product",
      "fields": [
        { "slug": "price", "name": "Price", "type": "number" },
        { "slug": "description", "name": "Description", "type": "richText" },
        { "slug": "image", "name": "Product Image", "type": "image" }
      ]
    }
  ]
}
```

**Features:**
- ✅ Two-phase creation: collections first, then fields (relation fields always work)
- ✅ Automatic retry for transient failures
- ✅ Validates all field types before creating
- ✅ Skips duplicates automatically (safe to re-run)
- ✅ Reports detailed summary table with status

---

## Example Prompts

### Complete Workflow (Recommended)

```
"Convert this website to Fast Mode, validate against my project, create any missing fields, and deploy"
```

### Step by Step

```
# 1. Convert website
"Convert this website to Fast Mode format"

# 2. Validate and sync schema (IMPORTANT - don't skip!)
"Validate my templates against my Fast Mode project and create any missing fields or collections"

# 3. Deploy
"Deploy to my Fast Mode project"
```

### Individual Operations

```
# Check what fields you can create
"What field types are available in Fast Mode?"

# Add a specific field
"Add a heroImage field (image type) to the blogs collection"

# Create a new custom collection
"Create a 'testimonials' collection with name (text), quote (richText), and photo (image) fields"

# Validate a single template
"Validate my blog_post.html template against my project"
```

### Content Management

```
# List all blog posts
"Show me all items in my blog collection"

# Get details of a specific post
"Get the blog post with slug 'my-first-post'"

# Create a new blog post
"Create a new blog post titled 'AI in 2025' with content about artificial intelligence trends"

# Update an existing post
"Update the blog post 'my-first-post' to set featured to true"

# Delete a post (AI will ask for confirmation first)
"Delete the blog post 'old-draft-post'"
```

---

## Authentication

The MCP server uses browser-based authentication (OAuth device flow). When you run a tool that requires auth:

1. Your browser opens automatically
2. Log in or create a Fast Mode account
3. The MCP server receives your credentials
4. Credentials are stored locally at `~/.fastmode/credentials.json`

You can also set the `FASTMODE_AUTH_TOKEN` environment variable if you prefer.

---

## Static Pages with CMS Content

Static pages (like homepages) can display content from CMS collections using `{{#each}}` loops:

```html
<!-- Homepage showing 3 featured blog posts -->
<section class="featured-posts">
  <h2>Latest Articles</h2>
  {{#each posts featured=true limit=3}}
    <article>
      <h3><a href="{{url}}">{{name}}</a></h3>
      <p>{{summary}}</p>
    </article>
  {{/each}}
</section>
```

**The MCP validation tool will:**
- Detect collection references (e.g., `posts`, `team`, `products`)
- Validate that referenced collections exist in your schema
- Error if collections are missing, with `sync_schema` instructions to create them

This ensures your homepage's featured content section will work correctly after deployment.

---

## Form Handling

Fast Mode automatically captures form submissions. Use the `data-form` attribute to identify forms:

```html
<form data-form="contact">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>
```

**Requirements:**
- `data-form="formname"` attribute identifies the form
- All inputs must have `name` attributes to be captured
- Include a submit button

**The MCP validation tool will check:**
- ✅ Form has `data-form` attribute
- ✅ All inputs have `name` attributes
- ⚠️ Warning if no submit button
- 💡 Suggestion to create a `/thank-you` page

**Note:** The legacy `data-form-name` attribute is deprecated. Use `data-form` instead.

Use `get_example("form_handling")` to see the full form handler script.

---

## Package Structure

Fast Mode websites follow this structure:

```
my-site/
├── manifest.json      # Site configuration
├── pages/             # HTML pages
│   ├── index.html
│   ├── about.html
│   └── contact.html
├── public/            # Static assets
│   ├── css/
│   ├── js/
│   └── images/
└── templates/         # CMS templates (optional)
    ├── blog_index.html
    ├── blog_post.html
    └── team.html
```

Use the `get_conversion_guide` tool for detailed instructions.

---

## Support

- **Issues:** [GitHub Issues](https://github.com/arihgoldstein/multisite-cms/issues)
- **Email:** support@fastmode.ai

---

## Changelog

### v1.0.0
- **New Package Name** — Renamed from `multisite-cms-mcp` to `fastmode-mcp` for clarity
- **Prebuilt Binaries** — Automatic binary downloads for macOS, Linux, and Windows (Intel & ARM)
- **No PATH Issues** — Works regardless of how Node.js is installed (nvm, volta, homebrew, etc.)
- **get_started Tool** — Intelligent entry point that detects project state and returns exact workflows
- **CMS Item Management** — Full CRUD tools: `create_cms_item`, `list_cms_items`, `get_cms_item`, `update_cms_item`, `delete_cms_item`
- **Schema Sync** — Create collections and fields with `sync_schema`
- **Deploy Gate** — `deploy_package` validates internally and BLOCKS deployment if there are errors
- **Form Validation** — Validates `data-form` attribute, input names, submit buttons
- **Static Page Validation** — Validates `{{#each}}` collection references against schema

---

## License

MIT