multisite-cms-mcp 1.2.1 → 1.2.2

package/README.md

@@ -100,9 +100,23 @@ Ask your AI assistant:
 
 The AI will use validation tools to create a proper package structure.
 
-### 2. Deploy to Fast Mode
+### 2. Validate & Create Schema (Important!)
 
-Once your package is ready:
+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"
 
@@ -111,36 +125,55 @@ The AI will:
 2. Show your existing projects or create a new one
 3. Upload and deploy your site
 
-### 3. Your Site is Live!
+### 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 (New in v1.2.0)
+## Schema Sync (Critical for Custom Fields)
+
+When your templates use custom fields (fields beyond the built-in ones), you **must** create them in the CMS before deploying. The MCP server handles this automatically.
 
-The MCP server can automatically create collections and fields in your Fast Mode project. This is useful when your templates use custom fields that don't exist yet.
+### 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
 
-### Workflow
+### What Happens During Validation
 
-1. **Validate template with project context:**
-   ```
-   "Validate my blog_post.html template against my Fast Mode project"
-   ```
-   If fields are missing, the tool provides instructions.
+When you validate a template with a project ID, the tool will:
 
-2. **Get available field types:**
-   ```
-   "What field types can I create in Fast Mode?"
-   ```
-   Returns: text, richText, number, boolean, date, datetime, image, url, email, select, multiSelect, relation
+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
 
-3. **Create missing fields:**
-   ```
-   "Add a heroImage (image) and category (select) field to my blogs collection"
-   ```
+### Available Field Types
 
-### Example: Adding Custom Fields
+| 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) |
+| `email` | Email addresses |
+| `select` | Single dropdown choice (category, status) |
+| `multiSelect` | Multiple dropdown choices (tags) |
+| `relation` | Link to another collection (author → authors) |
+
+### Example: Adding Custom Fields to Built-in Collection
 
 ```json
 {
@@ -180,32 +213,47 @@ The MCP server can automatically create collections and fields in your Fast Mode
 
 **Features:**
 - ✅ Validates all field types before creating
-- ✅ Skips duplicates automatically
+- ✅ Skips duplicates automatically (safe to re-run)
 - ✅ Works with both builtin and custom collections
 - ✅ Reports detailed results (created/skipped)
 
 ---
 
-## Example Usage
+## Example Prompts
+
+### Complete Workflow (Recommended)
+
+```
+"Convert this website to Fast Mode, validate against my project, create any missing fields, and deploy"
+```
+
+### Step by Step
 
 ```
-# Convert a website (no auth needed)
-"Use get_conversion_guide to help me convert my website to Fast Mode"
+# 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"
 
-# Validate a package
-"Validate my manifest.json using validate_manifest"
+# 3. Deploy
+"Deploy to my Fast Mode project"
+```
 
-# Validate template against actual project schema
-"Validate my blog_post.html template against my 'My Portfolio' project"
+### Individual Operations
+
+```
+# Check what fields you can create
+"What field types are available in Fast Mode?"
 
-# Create missing fields
-"Add a heroImage field (image type) to the blogs collection in my project"
+# Add a specific field
+"Add a heroImage field (image type) to the blogs collection"
 
-# Deploy to existing project
-"Deploy ./my-site.zip to my Fast Mode project"
+# Create a new custom collection
+"Create a 'testimonials' collection with name (text), quote (richText), and photo (image) fields"
 
-# Create new project and deploy
-"Create a new Fast Mode site called 'My Portfolio' and deploy ./portfolio.zip to it"
+# Validate a single template
+"Validate my blog_post.html template against my project"
 ```
 
 ---

package/dist/index.js

@@ -51,7 +51,7 @@ const TOOLS = [
     },
     {
         name: 'validate_template',
-        description: 'Validate an HTML template for correct CMS token usage. Checks for proper {{token}} syntax, correct field names, and proper use of triple braces for rich text. When authenticated with a projectId, also validates tokens against the actual project schema and reports missing fields.',
+        description: 'Validate an HTML template for correct CMS token usage. Checks {{token}} syntax, field names, and triple braces for rich text. IMPORTANT: When projectId is provided, validates tokens against the project schema and reports missing fields/collections that MUST be created with sync_schema before deploying.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -223,7 +223,7 @@ const TOOLS = [
     },
     {
         name: 'sync_schema',
-        description: 'Create collections and/or add fields to existing collections. Requires authentication. Skips duplicates automatically. All fields must have a type specified - use get_field_types to see available types. Use this after validate_template reports missing fields.',
+        description: 'IMPORTANT: Create new collections and/or add custom fields to collections. Call this BEFORE deploying when validate_template reports missing fields or collections. Requires authentication. All fields must have a type specified - call get_field_types first to see available types. Skips duplicates automatically. Without calling this tool, templates with custom fields will not render correctly.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/tools/validate-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-template.d.ts","sourceRoot":"","sources":["../../src/tools/validate-template.ts"],"names":[],"mappings":"AAMA,KAAK,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;AA6O7J;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,YAAY,EAC1B,cAAc,CAAC,EAAE,MAAM,EACvB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAwVjB"}
+{"version":3,"file":"validate-template.d.ts","sourceRoot":"","sources":["../../src/tools/validate-template.ts"],"names":[],"mappings":"AAMA,KAAK,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;AA6O7J;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,YAAY,EAC1B,cAAc,CAAC,EAAE,MAAM,EACvB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CA4ZjB"}

package/dist/tools/validate-template.js

@@ -383,18 +383,76 @@ async function validateTemplate(html, templateType, collectionSlug, projectId) {
                 if (targetCollection && templateType !== 'static_page') {
                     // Extract fields used in template
                     const usedFields = extractTokenFieldNames(html);
-                    // Find missing fields
-                    const missingFields = findMissingFields(usedFields, targetCollection, isBuiltin, schema);
-                    if (missingFields.length > 0) {
+                    // Check if custom collection exists
+                    const collectionExists = isBuiltin || schema.collections.some(c => c.slug === targetCollection);
+                    if (!isBuiltin && !collectionExists) {
+                        // Collection doesn't exist - need to create it
                         schemaValidation = `
 
-## ⚠️ Missing Fields in Schema
+## 🚨 ACTION REQUIRED: Collection Does Not Exist
 
-The following fields are used in the template but don't exist in the "${targetCollection}" collection:
+The collection "${targetCollection}" does **not exist** in this project.
+
+---
+
+### ⚡ YOU MUST CREATE THIS COLLECTION
+
+Use the \`sync_schema\` tool to create the collection and its fields before deploying.
+
+**Step 1:** First, call \`get_field_types\` to see available field types.
+
+**Step 2:** Then call \`sync_schema\` to create the collection with its fields:
+
+\`\`\`json
+{
+  "projectId": "${resolved.tenantId}",
+  "collections": [
+    {
+      "slug": "${targetCollection}",
+      "name": "${targetCollection.charAt(0).toUpperCase() + targetCollection.slice(1)}",
+      "nameSingular": "${targetCollection.endsWith('s') ? targetCollection.slice(0, -1).charAt(0).toUpperCase() + targetCollection.slice(0, -1).slice(1) : targetCollection.charAt(0).toUpperCase() + targetCollection.slice(1)}",
+      "fields": [
+${usedFields.filter(f => !['name', 'slug', 'publishedAt'].includes(f)).map(f => `        { "slug": "${f}", "name": "${f.charAt(0).toUpperCase() + f.slice(1).replace(/([A-Z])/g, ' $1').trim()}", "type": "YOUR_TYPE" }`).join(',\n')}
+      ]
+    }
+  ]
+}
+\`\`\`
+
+**Common field types:**
+- \`text\` - Short text (titles, names)
+- \`richText\` - Long formatted content with HTML
+- \`image\` - Image upload
+- \`url\` - Links
+- \`boolean\` - True/false toggles
+- \`date\` - Date picker
+- \`number\` - Numeric values
+- \`select\` - Dropdown (requires \`options\` parameter)
+
+**DO NOT SKIP THIS STEP** - Templates will not render without the collection.
+`;
+                    }
+                    else {
+                        // Find missing fields
+                        const missingFields = findMissingFields(usedFields, targetCollection, isBuiltin, schema);
+                        if (missingFields.length > 0) {
+                            schemaValidation = `
+
+## 🚨 ACTION REQUIRED: Missing Fields
+
+The following fields are used in the template but **do not exist** in the "${targetCollection}" collection:
 
 ${missingFields.map(f => `- \`${f}\``).join('\n')}
 
-**To create these fields, use the \`sync_schema\` tool:**
+---
+
+### ⚡ YOU MUST CREATE THESE FIELDS
+
+Use the \`sync_schema\` tool to create the missing fields before deploying. This is required for your template to work correctly.
+
+**Step 1:** First, call \`get_field_types\` to see available field types.
+
+**Step 2:** Then call \`sync_schema\` with the following structure (replace YOUR_TYPE with actual field types):
 
 \`\`\`json
 {
@@ -404,24 +462,34 @@ ${missingFields.map(f => `- \`${f}\``).join('\n')}
       "collectionSlug": "${targetCollection}",
       "isBuiltin": ${isBuiltin},
       "fields": [
-${missingFields.map(f => `        { "slug": "${f}", "name": "${f.charAt(0).toUpperCase() + f.slice(1).replace(/([A-Z])/g, ' $1')}", "type": "YOUR_TYPE_HERE" }`).join(',\n')}
+${missingFields.map(f => `        { "slug": "${f}", "name": "${f.charAt(0).toUpperCase() + f.slice(1).replace(/([A-Z])/g, ' $1').trim()}", "type": "YOUR_TYPE" }`).join(',\n')}
       ]
     }
   ]
 }
 \`\`\`
 
-**Important:** Replace \`"type": "YOUR_TYPE_HERE"\` with the appropriate field type.
-Use \`get_field_types\` to see available field types.
+**Common field types:**
+- \`text\` - Short text (titles, names)
+- \`richText\` - Long formatted content with HTML
+- \`image\` - Image upload
+- \`url\` - Links
+- \`boolean\` - True/false toggles
+- \`date\` - Date picker
+- \`number\` - Numeric values
+- \`select\` - Dropdown (requires \`options\` parameter)
+
+**DO NOT SKIP THIS STEP** - Templates will not render correctly without these fields.
 `;
-                    }
-                    else {
-                        schemaValidation = `
+                        }
+                        else {
+                            schemaValidation = `
 
 ## ✅ Schema Validation Passed
 
 All fields used in this template exist in the "${targetCollection}" collection.
 `;
+                        }
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multisite-cms-mcp",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "MCP server for Fast Mode CMS. Convert websites, validate packages, and deploy directly to Fast Mode. Includes authentication, project creation, schema sync, and one-click deployment.",
   "main": "dist/index.js",
   "bin": {