fastmode-mcp 1.0.0

package/README.md

@@ -0,0 +1,561 @@
+# 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
+

package/bin/run.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Entry point that tries to run the native binary first, then falls back to Node.js.
+ * This allows the MCP server to work regardless of how Node.js is installed.
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const BINARY_NAME = 'fastmode-mcp';
+
+function getNativeBinaryPath() {
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  const binaryPath = path.join(__dirname, `${BINARY_NAME}${ext}`);
+
+  if (fs.existsSync(binaryPath)) {
+    return binaryPath;
+  }
+
+  return null;
+}
+
+function runNativeBinary(binaryPath) {
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  child.on('error', (error) => {
+    console.error(`Failed to run native binary: ${error.message}`);
+    runNodeFallback();
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}
+
+function runNodeFallback() {
+  // Fall back to the Node.js version
+  require('../dist/index.js');
+}
+
+const nativeBinary = getNativeBinaryPath();
+
+if (nativeBinary) {
+  runNativeBinary(nativeBinary);
+} else {
+  runNodeFallback();
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}