multisite-cms-mcp 1.5.5 → 1.5.7

package/dist/index.js

@@ -118,6 +118,7 @@ const TOOLS = [
                         'parent_context',
                         'equality_comparison',
                         'youtube_embed',
+                        'nested_collection_loop',
                     ],
                     description: 'The type of example to retrieve',
                 },
@@ -133,8 +134,8 @@ const TOOLS = [
             properties: {
                 section: {
                     type: 'string',
-                    enum: ['full', 'analysis', 'structure', 'manifest', 'templates', 'tokens', 'forms', 'assets', 'checklist'],
-                    description: 'Specific section to retrieve, or "full" for everything',
+                    enum: ['full', 'first_steps', 'analysis', 'structure', 'seo', 'manifest', 'templates', 'tokens', 'forms', 'assets', 'checklist'],
+                    description: 'Specific section to retrieve, or "full" for everything. Use "first_steps" to get the required initial steps for establishing the target project.',
                 },
             },
             required: [],

package/dist/tools/get-conversion-guide.d.ts

@@ -1,4 +1,4 @@
-type Section = 'full' | 'analysis' | 'structure' | 'seo' | 'manifest' | 'templates' | 'tokens' | 'forms' | 'assets' | 'checklist';
+type Section = 'full' | 'first_steps' | 'analysis' | 'structure' | 'seo' | 'manifest' | 'templates' | 'tokens' | 'forms' | 'assets' | 'checklist';
 /**
  * Returns the conversion guide, either full or a specific section
  */

package/dist/tools/get-conversion-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-conversion-guide.d.ts","sourceRoot":"","sources":["../../src/tools/get-conversion-guide.ts"],"names":[],"mappings":"AAAA,KAAK,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AAyuBlI;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAuD1E"}
+{"version":3,"file":"get-conversion-guide.d.ts","sourceRoot":"","sources":["../../src/tools/get-conversion-guide.ts"],"names":[],"mappings":"AAAA,KAAK,OAAO,GAAG,MAAM,GAAG,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AA+2BlJ;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CA0D1E"}

package/dist/tools/get-conversion-guide.js

@@ -2,6 +2,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getConversionGuide = getConversionGuide;
 const SECTIONS = {
+    first_steps: `# REQUIRED FIRST STEPS (Do These Before Building the Package)
+
+**IMPORTANT:** Before converting any website, you MUST establish the target project first. This determines the schema and ensures you're deploying to the correct location.
+
+## Step 1: Check for Existing Projects
+
+Call \`list_projects\` to see the user's existing Fast Mode projects.
+
+## Step 2: Ask the User
+
+Based on what \`list_projects\` returns:
+
+**If NO projects exist:**
+- This is a new user - ask: "What would you like to name your new project?"
+- Proceed to Step 3b (New Project)
+
+**If projects exist:**
+- Present the list and ask: "Is this website for one of your existing projects, or should I create a new one?"
+- Let the user choose which project, or confirm they want a new one
+
+## Step 3a: For EXISTING Projects
+
+1. User selects the project from the list
+2. Call \`get_tenant_schema(projectId)\` to get the current collections and fields
+3. **Use this schema to build templates with the correct field names**
+4. When deploying, this will UPDATE the existing project
+5. Proceed to Phase 1 (Website Analysis)
+
+## Step 3b: For NEW Projects
+
+1. Ask for the project name if you don't have it
+2. Call \`create_site(name)\` to create the project
+3. You'll receive a projectId to use for deployment
+4. After building the package, call \`sync_schema\` to create collections/fields
+5. Proceed to Phase 1 (Website Analysis)
+
+---
+
+**WHY THIS MATTERS:**
+- For existing projects: The schema determines which fields to use in templates
+- For new projects: You need the projectId before you can deploy
+- Always: The user must confirm which project to use - never assume
+
+---
+
+`,
     analysis: `# Phase 1: Website Analysis (MANDATORY)
 
 Before writing ANY code, complete this analysis:
@@ -415,6 +461,93 @@ Use for rich text content:
 - \`featured=true\` - Only featured (if collection has boolean "featured" field)
 - \`sort="field"\` - Sort by field
 - \`order="asc|desc"\` - Sort direction
+- \`where="field:value"\` - Filter by field value
+
+## Nested Loops (Hierarchical Content)
+
+For content hierarchies like categories with items, docs sections with pages, or any parent-child relationships.
+
+**Works on ALL page types:** static pages, index pages, AND detail pages.
+
+\`\`\`html
+{{#each doc_categories}}
+  <div class="category-section">
+    <h3>{{name}}</h3>
+    <ul>
+      {{#each doc_pages where="category.slug:{{slug}}"}}
+        <li><a href="{{url}}">{{name}}</a></li>
+      {{/each}}
+    </ul>
+  </div>
+{{/each}}
+\`\`\`
+
+**How it works:**
+- The outer loop iterates through categories
+- \`{{slug}}\` in the where clause references the current category's slug
+- The inner loop filters doc_pages to only those matching that category
+
+---
+
+### Using @root. Prefix
+
+Use \`@root.\` to access collections from the root context when you need to be explicit:
+
+\`\`\`html
+{{#each doc_categories}}
+  <div class="category-section">
+    <h3>{{name}}</h3>
+    <ul>
+      {{#each @root.doc_pages where="category.slug:{{slug}}"}}
+        <li><a href="{{url}}">{{name}}</a></li>
+      {{/each}}
+    </ul>
+  </div>
+{{/each}}
+\`\`\`
+
+**When to use @root.:**
+- When the inner collection name might be ambiguous
+- When you want to be explicit about accessing root-level data
+- Both \`{{#each collection}}\` and \`{{#each @root.collection}}\` work the same
+
+---
+
+### Common Patterns
+
+\`\`\`html
+<!-- Categories with posts -->
+{{#each categories}}
+  <section>
+    <h2>{{name}}</h2>
+    {{#each posts where="category.slug:{{slug}}"}}
+      <article>{{name}}</article>
+    {{/each}}
+  </section>
+{{/each}}
+
+<!-- Authors with their articles -->
+{{#each authors}}
+  <div class="author-section">
+    <h3>{{name}}</h3>
+    {{#each posts where="author.id:{{id}}"}}
+      <a href="{{url}}">{{name}}</a>
+    {{/each}}
+  </div>
+{{/each}}
+
+<!-- Documentation sidebar (on any page type) -->
+{{#each doc_categories sort="order" order="asc"}}
+  <div class="sidebar-section">
+    <h4>{{name}}</h4>
+    {{#each @root.doc_pages where="category.slug:{{slug}}" sort="order" order="asc"}}
+      <a href="{{url}}">{{name}}</a>
+    {{/each}}
+  </div>
+{{/each}}
+\`\`\`
+
+**Important:** The \`{{field}}\` in the where clause is resolved from the outer loop's current item.
 
 ## Conditionals
 \`\`\`html
@@ -741,6 +874,9 @@ async function getConversionGuide(section) {
     if (section === 'full') {
         return `# Complete Website Conversion Guide
 
+${SECTIONS.first_steps}
+---
+
 ${SECTIONS.analysis}
 
 ---
@@ -781,7 +917,7 @@ ${SECTIONS.checklist}
 
 Use these MCP tools during conversion:
 
-- \`get_schema\` - Get collection field reference and token syntax
+- \`get_field_types\` - Get available field types for sync_schema
 - \`get_tenant_schema\` - Get exact collections and fields for a specific project
 - \`get_example\` - Get code examples for specific patterns
 - \`validate_manifest\` - Check your manifest.json

package/dist/tools/get-example.d.ts

@@ -1,4 +1,4 @@
-type ExampleType = 'manifest_basic' | 'manifest_custom_paths' | 'manifest_minimal_with_ui' | 'blog_index_template' | 'blog_post_template' | 'team_template' | 'downloads_template' | 'authors_template' | 'author_detail_template' | 'custom_collection_template' | 'form_handling' | 'asset_paths' | 'image_handling' | 'relation_fields' | 'data_edit_keys' | 'each_loop' | 'conditional_if' | 'nested_fields' | 'featured_posts' | 'parent_context' | 'equality_comparison' | 'youtube_embed';
+type ExampleType = 'manifest_basic' | 'manifest_custom_paths' | 'manifest_minimal_with_ui' | 'blog_index_template' | 'blog_post_template' | 'team_template' | 'downloads_template' | 'authors_template' | 'author_detail_template' | 'custom_collection_template' | 'form_handling' | 'asset_paths' | 'image_handling' | 'relation_fields' | 'data_edit_keys' | 'each_loop' | 'conditional_if' | 'nested_fields' | 'featured_posts' | 'parent_context' | 'equality_comparison' | 'youtube_embed' | 'nested_collection_loop';
 /**
  * Returns example code for a specific pattern
  */

package/dist/tools/get-example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-example.d.ts","sourceRoot":"","sources":["../../src/tools/get-example.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GACZ,gBAAgB,GAChB,uBAAuB,GACvB,0BAA0B,GAC1B,qBAAqB,GACrB,oBAAoB,GACpB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,wBAAwB,GACxB,4BAA4B,GAC5B,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,qBAAqB,GACrB,eAAe,CAAC;AAiiCpB;;GAEG;AACH,wBAAsB,UAAU,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}
+{"version":3,"file":"get-example.d.ts","sourceRoot":"","sources":["../../src/tools/get-example.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GACZ,gBAAgB,GAChB,uBAAuB,GACvB,0BAA0B,GAC1B,qBAAqB,GACrB,oBAAoB,GACpB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,wBAAwB,GACxB,4BAA4B,GAC5B,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,qBAAqB,GACrB,eAAe,GACf,wBAAwB,CAAC;AAmqC7B;;GAEG;AACH,wBAAsB,UAAU,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}

package/dist/tools/get-example.js

@@ -1033,6 +1033,135 @@ https://www.youtube.com/watch?v=VIDEO_ID
   {{/if}}
 </div>
 \`\`\``,
+    nested_collection_loop: `# Nested Collection Loops
+
+For hierarchical content like documentation categories with pages, product categories with products, or authors with their posts.
+
+**Works on ALL page types:** static pages, index pages, AND detail pages.
+
+## The Pattern
+
+\`\`\`html
+{{#each outer_collection}}
+  <div class="category-section">
+    <h3>{{name}}</h3>
+    <ul>
+      {{#each inner_collection where="relation_field.slug:{{slug}}"}}
+        <li><a href="{{url}}">{{name}}</a></li>
+      {{/each}}
+    </ul>
+  </div>
+{{/each}}
+\`\`\`
+
+**How it works:**
+- The outer loop iterates through parent items (e.g., categories)
+- \`{{slug}}\` in the \`where\` clause references the current outer item's slug
+- The inner loop filters to only items matching that parent
+
+---
+
+## Using @root. Prefix
+
+Use \`@root.\` to explicitly access collections from the root context:
+
+\`\`\`html
+{{#each doc_categories}}
+  <h3>{{name}}</h3>
+  {{#each @root.doc_pages where="category.slug:{{slug}}"}}
+    <a href="{{url}}">{{name}}</a>
+  {{/each}}
+{{/each}}
+\`\`\`
+
+Both syntaxes work identically:
+- \`{{#each doc_pages}}\` - Standard syntax
+- \`{{#each @root.doc_pages}}\` - Explicit root reference
+
+---
+
+## Documentation Sidebar Example
+
+**Collections needed:**
+- \`doc_categories\` (name, slug, order)
+- \`doc_pages\` (name, slug, content, category → relation to doc_categories)
+
+\`\`\`html
+<nav class="docs-sidebar">
+  {{#each doc_categories sort="order" order="asc"}}
+    <div class="sidebar-section">
+      <h4 class="section-title">{{name}}</h4>
+      <ul class="section-links">
+        {{#each @root.doc_pages where="category.slug:{{slug}}" sort="order" order="asc"}}
+          <li>
+            <a href="{{url}}" class="doc-link">{{name}}</a>
+          </li>
+        {{/each}}
+      </ul>
+    </div>
+  {{/each}}
+</nav>
+\`\`\`
+
+This sidebar pattern can be included on:
+- **Static pages** (about, contact, etc.)
+- **Index pages** (docs listing page)
+- **Detail pages** (individual doc pages)
+
+---
+
+## Blog Categories with Posts Example
+
+\`\`\`html
+<section class="categorized-posts">
+  {{#each categories}}
+    <div class="category-group">
+      <h2><a href="{{url}}">{{name}}</a></h2>
+      <div class="posts-grid">
+        {{#each posts where="category.id:{{id}}" limit=3 sort="publishedAt" order="desc"}}
+          <article class="post-card">
+            {{#if image}}
+              <img src="{{image}}" alt="{{name}}">
+            {{/if}}
+            <h3><a href="{{url}}">{{name}}</a></h3>
+            <p>{{summary}}</p>
+          </article>
+        {{/each}}
+      </div>
+      <a href="{{url}}" class="view-all">View all {{name}}</a>
+    </div>
+  {{/each}}
+</section>
+\`\`\`
+
+---
+
+## Important Notes
+
+1. **Works on ALL page types** - Static pages, index pages, AND detail pages
+2. **The \`where\` clause uses parent context** - \`{{slug}}\` or \`{{id}}\` comes from the outer loop's current item
+3. **@root. is optional** - Use it when you want to be explicit about root context
+4. **Supports all modifiers** - \`limit\`, \`sort\`, \`order\` work on inner loops
+5. **Relation field format** - Use \`relation_field.slug:{{slug}}\` or \`relation_field.id:{{id}}\`
+
+---
+
+## Manifest Configuration
+
+\`\`\`json
+{
+  "cmsTemplates": {
+    "doc_categoriesIndex": "templates/docs_index.html",
+    "doc_categoriesIndexPath": "/docs",
+    "doc_pagesDetail": "templates/doc_page.html",
+    "doc_pagesDetailPath": "/docs"
+  }
+}
+\`\`\`
+
+This gives you URLs like:
+- \`/docs\` - Documentation index showing all categories with their pages
+- \`/docs/quick-start-guide\` - Individual doc page`,
 };
 /**
  * Returns example code for a specific pattern

package/dist/tools/get-field-types.d.ts

@@ -3,7 +3,7 @@
  *
  * Returns the list of field types that can be used when CREATING new fields
  * in collections. This is NOT the list of fields in your schema - use
- * get_schema or get_tenant_schema for that.
+ * get_tenant_schema for that.
  *
  * No authentication required.
  */

package/dist/tools/get-field-types.js

@@ -4,7 +4,7 @@
  *
  * Returns the list of field types that can be used when CREATING new fields
  * in collections. This is NOT the list of fields in your schema - use
- * get_schema or get_tenant_schema for that.
+ * get_tenant_schema for that.
  *
  * No authentication required.
  */
@@ -104,7 +104,7 @@ async function getFieldTypes() {
 
 These are the field types you can use when CREATING new fields with the \`sync_schema\` tool.
 
-**Note:** This is NOT the list of fields in your schema. Use \`get_schema\` for the generic schema or \`get_tenant_schema\` for a specific project's schema.
+**Note:** This is NOT the list of fields in your schema. Use \`get_tenant_schema\` to see a specific project's schema.
 
 ## Field Types
 

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,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;AAgRrE;;;;;;;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,CAobjB"}
+{"version":3,"file":"validate-template.d.ts","sourceRoot":"","sources":["../../src/tools/validate-template.ts"],"names":[],"mappings":"AAMA,KAAK,YAAY,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;AAmRrE;;;;;;;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,CA4djB"}

package/dist/tools/validate-template.js

@@ -190,12 +190,15 @@ function validateForms(html) {
 }
 /**
  * Extract collection slugs referenced in {{#each}} loops on static pages
+ * Supports both {{#each collection}} and {{#each @root.collection}} syntax
  */
 function extractCollectionReferences(html) {
     const collections = [];
-    const eachLoops = html.match(/\{\{#each\s+(\w+)[^}]*\}\}/g) || [];
+    // Match both {{#each collection}} and {{#each @root.collection}}
+    const eachLoops = html.match(/\{\{#each\s+(?:@root\.)?([\w]+)[^}]*\}\}/g) || [];
     for (const loop of eachLoops) {
-        const match = loop.match(/\{\{#each\s+(\w+)/);
+        // Extract collection name, handling @root. prefix
+        const match = loop.match(/\{\{#each\s+(?:@root\.)?([\w]+)/);
         if (match) {
             collections.push(match[1]);
         }
@@ -218,7 +221,8 @@ async function validateTemplate(html, templateType, collectionSlug, projectId) {
     // Extract all tokens from the HTML
     const doubleTokens = html.match(/\{\{([^{}#/]+)\}\}/g) || [];
     const tripleTokens = html.match(/\{\{\{([^{}]+)\}\}\}/g) || [];
-    const eachLoops = html.match(/\{\{#each\s+(\w+)[^}]*\}\}/g) || [];
+    // Match both {{#each collection}} and {{#each @root.collection}}
+    const eachLoops = html.match(/\{\{#each\s+(?:@root\.)?([\w]+)[^}]*\}\}/g) || [];
     const conditionals = html.match(/\{\{#if\s+([^}]+)\}\}/g) || [];
     // Check for tokens with spaces (like {{ name }} instead of {{name}})
     const tokensWithSpaces = html.match(/\{\{\s+[^{}]+\s*\}\}/g) || [];
@@ -245,9 +249,9 @@ async function validateTemplate(html, templateType, collectionSlug, projectId) {
             warnings.push(`- No {{#each}} loop found - index templates usually need a loop to display items`);
         }
         else {
-            // Check if loop uses correct collection name
+            // Check if loop uses correct collection name (handles @root. prefix)
             for (const loop of eachLoops) {
-                const match = loop.match(/\{\{#each\s+(\w+)/);
+                const match = loop.match(/\{\{#each\s+(?:@root\.)?([\w]+)/);
                 if (match) {
                     const usedCollection = match[1];
                     if (collectionSlug && usedCollection !== collectionSlug) {
@@ -339,6 +343,37 @@ async function validateTemplate(html, templateType, collectionSlug, projectId) {
             suggestions.push(`- Found ${parentRefs.length} parent context reference(s) ({{../fieldName}}) - accesses parent scope in loops`);
         }
     }
+    // Validate nested loops with parent context in where clause
+    // Supports both {{#each collection}} and {{#each @root.collection}}
+    const nestedLoopPattern = /\{\{#each\s+(?:@root\.)?(\w+)\s+[^}]*where="[^:]+:\{\{(\w+)\}\}"[^}]*\}\}/g;
+    const nestedLoops = html.match(nestedLoopPattern) || [];
+    if (nestedLoops.length > 0) {
+        suggestions.push(`- Found ${nestedLoops.length} nested loop(s) with parent context filtering (e.g., where="field:{{parentField}}")`);
+        // Check if there's an outer loop to provide context
+        // Match both {{#each collection}} and {{#each @root.collection}}
+        const allLoopMatches = html.match(/\{\{#each\s+(?:@root\.)?\w+/g) || [];
+        if (allLoopMatches.length < 2 && nestedLoops.length > 0) {
+            warnings.push(`- Nested loop with where="...{{field}}" found but no outer loop detected. The {{field}} needs to come from an outer loop's item.`);
+        }
+    }
+    // Detect common nested loop patterns
+    const hierarchicalPatterns = [
+        { outer: 'categories', inner: 'posts', relation: 'category' },
+        { outer: 'doc_categories', inner: 'doc_pages', relation: 'category' },
+        { outer: 'authors', inner: 'posts', relation: 'author' },
+        { outer: 'tags', inner: 'posts', relation: 'tags' },
+    ];
+    for (const pattern of hierarchicalPatterns) {
+        const outerMatch = new RegExp(`\\{\\{#each\\s+${pattern.outer}`, 'g').test(html);
+        const innerMatch = new RegExp(`\\{\\{#each\\s+${pattern.inner}`, 'g').test(html);
+        if (outerMatch && innerMatch) {
+            // Check if inner loop has proper where clause
+            const innerWithWhere = new RegExp(`\\{\\{#each\\s+${pattern.inner}\\s+[^}]*where=`, 'g').test(html);
+            if (!innerWithWhere) {
+                warnings.push(`- Nested loops: ${pattern.outer} → ${pattern.inner} detected. Consider adding where="${pattern.relation}.slug:{{slug}}" to filter ${pattern.inner} by parent ${pattern.outer}.`);
+            }
+        }
+    }
     // Validate equality helper syntax
     const eqHelpers = html.match(/\{\{#if\s+\(eq\s+[^)]+\)\s*\}\}/g) || [];
     if (eqHelpers.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multisite-cms-mcp",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "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": {