# 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
