@estation/create-cms-site 1.0.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@estation/create-cms-site",
+  "version": "1.0.0",
+  "description": "MCP server to scaffold Next.js sites powered by eSTATION CMS",
+  "type": "module",
+  "bin": {
+    "create-cms-site": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "cms",
+    "nextjs",
+    "scaffold",
+    "ctrla",
+    "estation"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/template/.env.example

@@ -0,0 +1,9 @@
+# CMS API
+CMS_API_URL=https://cms-gateway.estation.io/api/v1
+CMS_API_TOKEN=your-tenant-api-token
+
+# On-demand ISR revalidation
+REVALIDATE_SECRET=your-revalidation-secret
+
+# Public site URL (used for sitemap generation)
+NEXT_PUBLIC_SITE_URL=https://your-site.com

package/template/LIVE-PREVIEW.md

@@ -0,0 +1,267 @@
+# CMS Live Preview — Developer Guide
+
+Real-time preview lets content editors see field changes instantly in the website template while editing in the CMS admin. This guide explains how the system works and how to implement it in your own components.
+
+## How It Works
+
+```
+CMS Admin                                    Website Template (iframe)
++--------------------------+                 +----------------------------+
+| AdminPageCompositionEditor|                | CMSPreviewListener         |
+|                          |                 |                            |
+| User types in a field    |  postMessage    | Listens for "message"      |
+| ───────────────────────> | ─────────────>  | events on window           |
+|                          |                 |                            |
+| Resolves:                |                 | Finds element by:          |
+|  - blockTag (first tag)  |                 |  [data-cms-block="{tag}"]  |
+|  - fieldName             |                 |    └─ [data-cms-field="…"] |
+|  - fieldType             |                 |                            |
+|  - value (string)        |                 | Updates DOM directly:      |
+|                          |                 |  text → .textContent       |
+|                          |                 |  richtext → .innerHTML     |
+|                          |                 |  image → .src              |
+|                          |                 |  list → <li> elements      |
++--------------------------+                 +----------------------------+
+```
+
+The admin embeds your website in an `<iframe>`. When a content editor changes any field, the admin sends a `postMessage` to the iframe. The `CMSPreviewListener` component (already installed in the root layout) receives the message, finds the matching DOM element via data attributes, and updates it in place — no page reload required.
+
+## Message Protocol
+
+### `cms-preview-update`
+
+Sent when a field value changes.
+
+```typescript
+interface PreviewUpdateMessage {
+  type: "cms-preview-update";
+  blockTag: string;    // First tag of the content block (e.g., "hero", "text", "faq")
+  fieldName: string;   // Field key (e.g., "title", "description", "body")
+  fieldType: string;   // "text" | "richtext" | "image" | "list"
+  value: string;       // New value (string or JSON-stringified for lists)
+}
+```
+
+### `cms-preview-highlight`
+
+Sent when the editor hovers over or focuses a field in the admin UI.
+
+```typescript
+interface PreviewHighlightMessage {
+  type: "cms-preview-highlight";
+  blockTag: string;    // First tag of the content block
+  fieldName: string;   // Field key
+  active: boolean;     // true = show highlight, false = remove highlight
+}
+```
+
+When active, the target element gets a blue outline and is scrolled into view.
+
+## Data Attributes
+
+The preview system relies on two HTML data attributes to locate elements:
+
+| Attribute | Purpose | Applied to |
+|-----------|---------|------------|
+| `data-cms-block="{tag}"` | Identifies the content block | The wrapping `<section>` element |
+| `data-cms-field="{fieldName}"` | Identifies the field within the block | The element rendering the field value |
+
+The listener finds elements using this selector chain:
+
+```
+document.querySelector(`[data-cms-block="${blockTag}"]`)
+  .querySelector(`[data-cms-field="${fieldName}"]`)
+```
+
+### `data-cms-block`
+
+Applied automatically by `SectionRenderer.tsx` — you don't need to add this yourself:
+
+```tsx
+// SectionRenderer.tsx — already handled
+<section key={block.uuid} data-cms-block={tag}>
+  <Component block={block} />
+</section>
+```
+
+The `tag` value is `block.tags[0]` (the first tag on the content block).
+
+### `data-cms-field`
+
+You must add this to every element in your component whose content comes from a CMS field. The attribute value must match the field key exactly.
+
+## How to Build a Live-Preview-Ready Component
+
+### Step 1: Create the component
+
+```tsx
+// src/components/sections/MySection.tsx
+import type { SectionProps } from "@/lib/types";
+import { str } from "@/lib/types";
+
+export function MySection({ block }: SectionProps) {
+  const c = block.content;
+
+  return (
+    <div className="py-16 px-6 max-w-3xl mx-auto">
+      {/* data-cms-field must match the field key in the CMS */}
+      <h2 data-cms-field="title" className="text-3xl font-bold mb-4">
+        {str(c.title, "Default Title")}
+      </h2>
+
+      <p data-cms-field="subtitle" className="text-gray-600 mb-6">
+        {str(c.subtitle)}
+      </p>
+
+      {/* Richtext: use dangerouslySetInnerHTML */}
+      <div
+        data-cms-field="body"
+        className="prose prose-gray max-w-none"
+        dangerouslySetInnerHTML={{ __html: str(c.body) }}
+      />
+
+      {/* Image: must be on an <img> element */}
+      <img
+        data-cms-field="heroImage"
+        src={str(c.heroImage)}
+        alt={str(c.title)}
+        className="w-full rounded-lg mt-8"
+      />
+    </div>
+  );
+}
+```
+
+### Step 2: Register in SectionRenderer
+
+```tsx
+// src/components/SectionRenderer.tsx
+import { MySection } from "./sections/MySection";
+
+const SECTION_MAP: Record<string, React.FC<SectionProps>> = {
+  // ... existing entries
+  "my-section": MySection,
+};
+```
+
+The key in `SECTION_MAP` must match the first tag you'll assign to this block type in the CMS.
+
+### Step 3: Create content in the CMS
+
+1. Create a content block with tag `my-section`
+2. Add fields: `title` (text), `subtitle` (text), `body` (richtext), `heroImage` (image)
+3. Add the block to a page composition
+4. Open the page editor — the preview iframe shows your component with live updates
+
+## Field Type Handling
+
+The preview listener updates DOM elements differently based on `fieldType`:
+
+| `fieldType` | Update method | Element requirement |
+|-------------|--------------|---------------------|
+| `text` | `el.textContent = value` | Any element (`<h1>`, `<p>`, `<span>`, etc.) |
+| `richtext` | `el.innerHTML = value` | Any element (typically a `<div>`) |
+| `image` | `el.src = value` | Must be an `<img>` element |
+| `list` | Parses JSON, renders `<li>` elements | Typically a `<ul>` or `<div>` |
+| *(default)* | `el.textContent = value` | Any element |
+
+### Text fields
+
+```tsx
+<h2 data-cms-field="title">{str(c.title)}</h2>
+<p data-cms-field="description">{str(c.description)}</p>
+```
+
+### Richtext fields
+
+Use `dangerouslySetInnerHTML` so the preview listener can update via `innerHTML`:
+
+```tsx
+<div
+  data-cms-field="body"
+  className="prose max-w-none"
+  dangerouslySetInnerHTML={{ __html: str(c.body) }}
+/>
+```
+
+### Image fields
+
+Must use an `<img>` tag — the listener checks `el instanceof HTMLImageElement` before setting `.src`:
+
+```tsx
+<img data-cms-field="featuredImage" src={str(c.featuredImage)} alt="..." />
+```
+
+### List fields
+
+The listener receives a JSON string, parses it, and renders `<li>` elements. For basic lists, wrap in a `<ul>`:
+
+```tsx
+<ul data-cms-field="items" className="list-disc pl-6">
+  {items.map((item, i) => (
+    <li key={i}>{item.title}</li>
+  ))}
+</ul>
+```
+
+> **Note:** List preview updates replace the entire inner HTML with simple `<li>` elements. For complex list rendering (cards, grids), the live preview will show a simplified version — the full rendering appears after save + page reload.
+
+## Existing Components Reference
+
+These built-in components are already wired for live preview:
+
+| Component | Tag | Fields with `data-cms-field` |
+|-----------|-----|------------------------------|
+| HeroSection | `hero` | `header`, `description`, `buttonText` |
+| TextSection | `text` | `title`, `subtitle`, `body` |
+| FeaturesSection | `features` | `title`, `description`, `items` |
+| FAQSection | `faq` | `title`, `items` |
+| TestimonialsSection | `testimonials` | `title`, `items` |
+| CTASection | `cta` | `title`, `description`, `buttonText` |
+| SliderSection | `slider` | `items` |
+| GallerySection | `gallery` | `title`, `items` |
+| ContactSection | `contact` | `title`, `description`, `email`, `phone`, `address` |
+
+## Highlight Behavior
+
+When the content editor hovers over a field in the admin panel, the preview listener:
+
+1. Injects a CSS style (once) for `.cms-preview-highlight` — a 2px blue outline with 2px offset
+2. Finds the matching element via `data-cms-block` + `data-cms-field`
+3. Adds the `cms-preview-highlight` class and scrolls the element into view
+4. Removes the class when the editor moves away
+
+No extra markup is needed in your components — this works automatically if you add `data-cms-field` attributes.
+
+## Checklist
+
+When building a new section component, verify:
+
+- [ ] Every visible CMS field has `data-cms-field="{fieldKey}"` on the element that displays it
+- [ ] The `fieldKey` in the attribute exactly matches the field name in the CMS content block
+- [ ] Richtext fields use `dangerouslySetInnerHTML`
+- [ ] Image fields are on `<img>` elements
+- [ ] The component is registered in `SectionRenderer.tsx` with the block tag as key
+- [ ] The block tag in the CMS matches the key in `SECTION_MAP`
+
+## Debugging Preview
+
+If live preview isn't working:
+
+1. **Check the iframe loads** — open your site URL directly, it should render
+2. **Inspect data attributes** — in DevTools, verify `data-cms-block` and `data-cms-field` exist on the right elements
+3. **Monitor messages** — add to your browser console in the iframe:
+   ```js
+   window.addEventListener("message", (e) => console.log("CMS message:", e.data));
+   ```
+4. **Verify the tag** — the `blockTag` in the message must match the `data-cms-block` value. The admin uses `block.tags[0]` as the tag
+5. **Check the field name** — the `fieldName` must exactly match the `data-cms-field` value
+
+## Architecture Notes
+
+- **No backend required** — preview is purely client-side via `window.postMessage`
+- **No WebSocket/SSE** — the iframe and parent communicate directly
+- **Changes are not persisted** — preview updates are DOM-only. The actual save happens when the editor clicks Save in the admin
+- **`CMSPreviewListener` is already in the root layout** — you don't need to add it to individual pages
+- **Server components work fine** — the preview listener is a client component that runs alongside server-rendered content. It patches the DOM after hydration
+- **Sandbox restrictions** — the iframe uses `sandbox="allow-same-origin allow-scripts"` which is sufficient for postMessage communication

package/template/README.md

@@ -0,0 +1,210 @@
+# CMS Website Template
+
+A full-featured Next.js 15 website template that renders content from the eSTATION CMS. Includes SSR + ISR, real-time live preview, blog, news, events, search, collections, dynamic navigation/footer, SEO metadata, and sitemap generation.
+
+## Quick Start
+
+```bash
+cp .env.example .env.local
+# Edit .env.local with your CMS credentials
+
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CMS_API_URL` | CMS API base URL (e.g., `https://cms-gateway.estation.io/api/v1`) |
+| `CMS_API_TOKEN` | Your tenant's API token |
+| `REVALIDATE_SECRET` | Secret for on-demand ISR revalidation webhook |
+| `NEXT_PUBLIC_SITE_URL` | Public site URL for sitemap generation (e.g., `https://your-site.com`) |
+
+## Architecture
+
+```
+src/
+├── app/
+│   ├── page.tsx                    # Homepage (slug: "index")
+│   ├── [slug]/page.tsx             # Dynamic CMS pages
+│   ├── blog/
+│   │   ├── page.tsx                # Blog listing
+│   │   └── [slug]/page.tsx         # Blog detail
+│   ├── news/
+│   │   ├── page.tsx                # News listing
+│   │   └── [slug]/page.tsx         # News detail
+│   ├── events/
+│   │   ├── page.tsx                # Events listing
+│   │   └── [slug]/page.tsx         # Event detail
+│   ├── search/page.tsx             # Search page
+│   ├── collections/[uuid]/page.tsx # Collection results
+│   ├── sitemap.ts                  # Dynamic sitemap
+│   ├── layout.tsx                  # Root layout (nav + footer)
+│   └── api/revalidate/route.ts     # ISR revalidation endpoint
+├── components/
+│   ├── Navigation.tsx              # Dynamic navigation
+│   ├── Footer.tsx                  # Dynamic footer
+│   ├── SectionRenderer.tsx         # Block → component mapper
+│   ├── cms-preview-listener.tsx    # Live preview handler
+│   └── sections/                   # Section components
+│       ├── HeroSection.tsx
+│       ├── TextSection.tsx
+│       ├── FeaturesSection.tsx
+│       ├── FAQSection.tsx
+│       ├── TestimonialsSection.tsx
+│       ├── CTASection.tsx
+│       ├── SliderSection.tsx
+│       ├── GallerySection.tsx
+│       ├── ContactSection.tsx
+│       └── GenericSection.tsx
+└── lib/
+    ├── types.ts                    # TypeScript interfaces
+    ├── cms-api.ts                  # CMS API client
+    └── content-helpers.ts          # Utility functions
+```
+
+## Section Components
+
+| Component | Block Tag(s) | Fields |
+|-----------|-------------|--------|
+| HeroSection | `hero` | `header`, `description`, `buttonText`, `buttonLink` |
+| TextSection | `text` | `title`, `subtitle`, `body` (richtext) |
+| FeaturesSection | `features`, `feature` | `title`, `description`, `items` (list) |
+| FAQSection | `faq` | `title`, `items` (list: `question`, `answer`) |
+| TestimonialsSection | `testimonials`, `testimonial` | `title`, `items` (list: `name`, `quote`, `role`) |
+| CTASection | `cta` | `title`, `description`, `buttonText`, `buttonLink` |
+| SliderSection | `slider`, `sliders` | `items` (list: `title`, `subtitle`, `image`, `linkUrl`, `linkText`) |
+| GallerySection | `gallery` | `title`, `items` (list: `image`, `caption`) |
+| ContactSection | `contact`, `form` | `title`, `description`, `email`, `phone`, `address` |
+| GenericSection | (fallback) | Renders all fields dynamically |
+
+## Content Types
+
+### Blog Posts
+
+- **CMS tag:** `blogs`
+- **Fields:** `slug`, `title`, `author`, `publishDate`, `featuredImage`, `excerpt`, `content` (richtext)
+- **Routes:** `/blog` (listing), `/blog/[slug]` (detail)
+
+### News Articles
+
+- **CMS tag:** `news`
+- **Fields:** `slug`, `title`, `author`, `category`, `publishDate`, `featuredImage`, `excerpt`, `content` (richtext)
+- **Routes:** `/news` (listing), `/news/[slug]` (detail)
+
+### Events
+
+- **CMS tag:** `events`
+- **Fields:** `slug`, `title`, `description`, `location`, `startDate`, `endDate`, `organizer`, `content` (richtext)
+- **Routes:** `/events` (listing), `/events/[slug]` (detail)
+
+## Routing
+
+| Route | Source |
+|-------|--------|
+| `/` | Homepage — CMS page with slug `index` |
+| `/[slug]` | Dynamic CMS pages |
+| `/blog` | Blog listing |
+| `/blog/[slug]` | Blog post detail |
+| `/news` | News listing |
+| `/news/[slug]` | News article detail |
+| `/events` | Events listing |
+| `/events/[slug]` | Event detail |
+| `/search?q=...` | Search results |
+| `/collections/[uuid]` | Collection execution results |
+| `/sitemap.xml` | Auto-generated sitemap |
+
+## Navigation
+
+The `Navigation` component fetches blocks tagged `navigation` from the CMS. Expected field structure:
+
+- `items` (list): each item has `label` and `href`
+
+If no `navigation` block exists, it auto-generates links from all published CMS pages.
+
+## Footer
+
+The `Footer` component fetches blocks tagged `footer`. Expected field structure:
+
+- `copyright` (text)
+- `links` (list): each item has `label` and `href`
+
+Falls back to a default copyright notice if no footer block exists.
+
+## SEO
+
+Every page generates `<title>` and `<meta name="description">` from CMS content:
+
+- Homepage and dynamic pages use the page composition's `title` and `description`
+- Blog, news, and event detail pages use the block's `title` and `excerpt`/`description`
+
+## Sitemap
+
+`/sitemap.xml` is dynamically generated from:
+
+- All published CMS pages
+- All blog posts, news articles, and events with slugs
+
+Set `NEXT_PUBLIC_SITE_URL` to your production URL for correct sitemap URLs.
+
+## Search
+
+`/search` provides server-side search. Query parameters:
+
+- `q` — search query (required)
+- `type` — filter by `block` or `page` (optional)
+- `page` — pagination (optional)
+
+Results link to the appropriate content type page.
+
+## Collections
+
+`/collections/[uuid]` executes a CMS collection query and renders the resulting blocks through `SectionRenderer`.
+
+## On-Demand Revalidation
+
+`POST /api/revalidate` with JSON body:
+
+```json
+{ "secret": "your-secret", "slug": "about" }
+{ "secret": "your-secret", "tag": "tag-hero" }
+{ "secret": "your-secret", "type": "blogs" }
+{ "secret": "your-secret" }
+```
+
+- `slug` — revalidate a specific page
+- `tag` — revalidate a specific cache tag
+- `type` — revalidate a content type (`blogs`, `news`, `events`)
+- No target — revalidates the entire site
+
+## CMS Preview Protocol
+
+When embedded in the CMS admin iframe, the template supports real-time preview via `postMessage`:
+
+- **`cms-preview-update`** — updates field content in-place (text, richtext, image, list)
+- **`cms-preview-highlight`** — highlights the targeted field with a blue outline
+
+Elements are targeted via `data-cms-block="{tag}"` and `data-cms-field="{fieldName}"` attributes.
+
+## Customization
+
+1. Add new section components in `src/components/sections/`
+2. Register them in `SectionRenderer.tsx`'s `SECTION_MAP` with the block tag as key
+3. Each component receives `block: ContentBlock` with `block.content` containing field data
+4. Use `str(block.content.fieldName)` to safely extract string field values
+
+## API Reference (`src/lib/cms-api.ts`)
+
+| Function | Description |
+|----------|-------------|
+| `getPageBySlug(slug)` | Get page composition with resolved blocks |
+| `getBlocksByTags(tags)` | Get all blocks matching any of the given tags |
+| `getBlocksByTagPaginated(tag, page, size)` | Paginated blocks by tag |
+| `getBlockByUUID(uuid)` | Get a single block by UUID |
+| `getAllPages()` | Get all published page compositions |
+| `executeCollection(uuid)` | Execute a collection query and get results |
+| `getCollections()` | List all collections |
+| `searchContent(query, type, page, size)` | Search across content |

package/template/next.config.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "**.amazonaws.com",
+      },
+    ],
+  },
+};
+
+export default nextConfig;

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "cms-website-template",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "^15.3.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.1.0",
+    "typescript": "^5.7.0"
+  }
+}

package/template/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/template/src/app/[slug]/page.tsx

@@ -0,0 +1,38 @@
+import { getPageBySlug } from "@/lib/cms-api";
+import { SectionRenderer } from "@/components/SectionRenderer";
+import type { ContentBlock } from "@/lib/types";
+import type { Metadata } from "next";
+
+interface PageProps {
+  params: Promise<{ slug: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  try {
+    const data = await getPageBySlug(slug);
+    return {
+      title: data.page.title || slug,
+      description: data.page.description || undefined,
+    };
+  } catch {
+    return { title: slug };
+  }
+}
+
+export default async function DynamicPage({ params }: PageProps) {
+  const { slug } = await params;
+  const data = await getPageBySlug(slug);
+  const orderedBlocks = getOrderedBlocks(data.page.blocks, data.blocks);
+
+  return <SectionRenderer blocks={orderedBlocks} />;
+}
+
+function getOrderedBlocks(
+  blockUuids: string[],
+  blocksMap: Record<string, ContentBlock>
+): ContentBlock[] {
+  return blockUuids
+    .map((uuid) => blocksMap[uuid])
+    .filter(Boolean);
+}

package/template/src/app/api/revalidate/route.ts

@@ -0,0 +1,34 @@
+import { revalidateTag, revalidatePath } from "next/cache";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function POST(request: NextRequest) {
+  const body = await request.json().catch(() => null);
+  if (!body) {
+    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  const { secret, slug, tag, type } = body;
+
+  if (secret !== process.env.REVALIDATE_SECRET) {
+    return NextResponse.json({ error: "Invalid secret" }, { status: 401 });
+  }
+
+  if (tag) {
+    revalidateTag(tag);
+    return NextResponse.json({ revalidated: true, tag });
+  }
+
+  if (type) {
+    revalidateTag(`tag-${type}`);
+    return NextResponse.json({ revalidated: true, type });
+  }
+
+  if (slug) {
+    revalidateTag(`page-${slug}`);
+    return NextResponse.json({ revalidated: true, slug });
+  }
+
+  // No specific target — revalidate everything
+  revalidatePath("/", "layout");
+  return NextResponse.json({ revalidated: true, all: true });
+}