mcp-magento-cms 1.0.3 → 1.2.0

package/README.md

@@ -1,74 +1,73 @@
 # Magento CMS MCP (Cursor)
 
-Create/update Magento **CMS Pages / Blocks** with Page Builder **Row → Text** from Cursor chat.
+Create/update Magento **CMS Pages / Blocks** with Page Builder from Cursor chat — including **validate/repair** for stage-safe HTML and **raw Page Builder HTML** saves for complex layouts.
 
-- **AI:** Cursor plans the content
-- **This server:** Magento REST via an Integration Access Token
-- **Install:** `npx` (no local clone, no `tools/` folder, no `.env` file required)
+- **AI:** Cursor plans content and diagnostics
+- **This server:** Magento REST via Integration Access Token
+- **Local:** run from this repo path in `mcp.json` (point `MAGENTO_BASE_URL` at the target store)
+- **Published:** `npx -y mcp-magento-cms` (npm)
 
 Requires **Node.js 18+** and [Cursor](https://cursor.com).
 
-Package: [npmjs.com/package/mcp-magento-cms](https://www.npmjs.com/package/mcp-magento-cms)
+## CMS workflow (mandatory for agents & teams)
 
-## Tools
-
-| Tool | Purpose |
-|------|---------|
-| `magento_health` | Test base URL + token |
-| `get_cms_page` | Load by `page_id` |
-| `create_cms_page` | Create from title + content |
-| `update_cms_page` | Update by `page_id` |
-| `get_cms_block` / `create_cms_block` / `update_cms_block` | Blocks |
-| `list_section_types` | Supported layouts (MVP: `simple_text`) |
-
-## Setup (any machine)
+**Use this MCP as the only way to create or update Magento CMS pages/blocks.**
 
-You do **not** need to clone this repo or create a `.env` file. Cursor runs the package with `npx` and reads credentials from `mcp.json`.
+| Do | Do not |
+|----|--------|
+| `pagebuilder_rules` → `compose_pagebuilder` / `create_cms_page` / `set_pagebuilder_html` | Project PHP `tools/compose-*.php` / `deploy-*.php` |
+| `validate_pagebuilder` / `repair_pagebuilder` before save | Direct DB edits to `cms_page` / `cms_block` content |
+| Improve **this package** when something is missing or wrong | Bypass MCP with one-off scripts |
 
-### 1. Magento Integration Access Token
+Preferred path: `sections[]` → `compose_pagebuilder` (or `create_cms_page` with `sections`) → validate → save. Use `set_pagebuilder_html` only for intentional raw master HTML. After save, verify on the storefront.
 
-No clone or `tools/` folder is needed. Create the token in Magento Admin:
+Reload/restart the MCP server in Cursor after changing this package so teammates pick up new rules and tools.
 
-1. **System → Extensions → Integrations → Add New Integration**
-2. Name it (e.g. `MCP CMS`) and set your admin password when prompted
-3. Open the **API** tab → set **Resource Access** to **Custom**
-4. Under **Content → Elements**, select:
+**REST field note (Magento 2.4.8):** `cmsPage` create/update use `active` (not `is_active`) and reject `store_id` / unknown fields. The client maps `is_active` → `active` so tool args stay familiar.
 
-| Select | Notes |
-|--------|--------|
-| **Pages** | Required (parent) |
-| → **Save Page** | Create / update pages |
-| → **Edit Page Design** | Page Builder / design fields |
-| → **Delete Page** | Optional (MCP does not delete today) |
-| **Blocks** | Required (create / update blocks) |
+**Store views:** Magento REST cannot set `cms_page_store` / `cms_block_store`. On create, this MCP assigns **All Store Views** (`store_id = 0`) by default via Magento PHP (`scripts/assign-stores.php` + `ddev exec` when `.ddev` exists). Pass `store_ids: [1, 2]` (etc.) only when the user asks for specific store view(s). Requires `MAGENTO_ROOT` (or infer from `MAGENTO_CMS_PROJECT_RULES` → project root).
 
-Leave everything else unchecked (Staging, Widgets, Media Gallery, Amasty, Blog, Design Themes, etc.).
+**Page layout:** On create, default `page_layout` is **`cms-full-width`** (admin label: Page — Full Width). Pass `page_layout` only when the user asks for a different layout (e.g. `1column`).
 
-5. **Save → Activate** → copy the **Access Token** into `mcp.json` (step 3)
+## Shared rules (all projects — read first)
 
-Magento **2.4.4+** blocks integration tokens as Bearer by default. Enable once (either way):
+Returned by `pagebuilder_rules` for **every** store. This package stays free of store-specific hex / class catalogs; those go in optional project rules.
 
-**Admin UI:** **Stores → Configuration → Services → OAuth → Consumer Settings** → set **Allow OAuth Access Tokens to be used as standalone Bearer tokens** to **Yes** → Save Config.
+### Page Builder (stage-safe)
 
-**CLI:**
+1. Rows: use **Full Width** or **Contained**. **Never Full Bleed** unless the user explicitly asks.
+2. When edge-to-edge hero is intentional: `allow_full_bleed=true` on validate/set/repair.
+3. `full-width` rows **MUST** include `.row-full-width-inner[data-element=inner]`.
+4. `contained` rows **MUST** include `[data-element=inner]`.
+5. Converting `full-bleed` → `full-width` without adding the inner wrapper breaks admin Page Builder.
+6. Every `[data-pb-style=ID]` in `<style>` must match an element — **orphans crash** the stage.
+7. Every column needs `width:%` in the style block.
+8. Avoid raw `<svg>` inside Text — use **Image** (or theme CSS) for icons.
+9. Hero CTAs: Banner **Show Button=Always** + Link URL.
+10. Links: prefer `{{store url=path}}` with an unquoted path (avoid `&quot;` in href).
+11. Prefer native content types; CMS body = page content only (layout owns chrome).
 
-```bash
-bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
-bin/magento cache:flush config
-```
+### CMS media + theme conventions (all projects)
 
-(With ddev: prefix CLI with `ddev exec`.)
+12. **One flat media folder per CMS page** under `pub/media/wysiwyg/` — no `cards/`, `icons/`, `products/`, `related/` subfolders.
+13. **Folder name = CMS page URL key** (identifier), e.g. `wysiwyg/markets/market-industrial/hero.jpg`.
+14. After renaming media folders, update all `{{media url=…}}` in `cms_page` / `cms_block`, then flush cache.
+15. Sibling pages share **one** Magento_Cms LESS partial + shared classes — do not copy near-identical LESS into theme `_sources.less` per page.
+16. Page-only LESS → theme `Magento_Cms/web/css/source/` + `_module.less` import.
+17. Brand primary/secondary once in `_theme.less` (`@theme__color__primary` / `@theme__color__secondary`); use vars, not hex, in page LESS.
+18. **No module-level re-aliases** of theme vars; **no redundant `font-family`** when body already uses the theme base font.
+19. Scope page CSS with layout body class and/or content markers (`:has(.…)`).
 
-### 2. Magento base URL
+Use tools `pagebuilder_rules`, `validate_pagebuilder`, and `repair_pagebuilder`.
 
-Use your storefront base URL **without** a trailing slash, for example:
+## Per-store project rules (optional)
 
-- Production: `https://www.example.com`
-- Local ddev: `https://your-project.ddev.site` (`ddev describe` shows the URL)
+Keep the published MCP **general**. Put store-specific values (brand hex, Vendor/theme, URL keys, class prefixes) in the **Magento project**, not in this package.
 
-### 3. Add the MCP in Cursor
+**Recommended (project-wise Cursor config):**
 
-**Cursor → Settings → MCP → Edit Config**, or create `.cursor/mcp.json` in your project:
+1. Commit `.cursor/magento-cms-project-rules.json` in the Magento repo.
+2. Add project MCP config at `.cursor/mcp.json` (Customize → MCPs → workspace) with `MAGENTO_ROOT` only — rules auto-load from `${MAGENTO_ROOT}/.cursor/magento-cms-project-rules.json`.
 
 ```json
 {
@@ -77,68 +76,160 @@ Use your storefront base URL **without** a trailing slash, for example:
       "command": "npx",
       "args": ["-y", "mcp-magento-cms"],
       "env": {
-        "MAGENTO_BASE_URL": "https://www.example.com",
-        "MAGENTO_ACCESS_TOKEN": "YOUR_INTEGRATION_ACCESS_TOKEN"
+        "MAGENTO_BASE_URL": "https://your-store.example/",
+        "MAGENTO_ACCESS_TOKEN": "${env:MAGENTO_ACCESS_TOKEN}",
+        "MAGENTO_ROOT": "${workspaceFolder}"
       }
     }
   }
 }
 ```
 
-**Local ddev / mkcert only** — Node may not trust the local TLS cert. Add:
+Optional override: `MAGENTO_CMS_PROJECT_RULES=/path/to/file.json` if the rules file is not under `.cursor/`.
+
+`pagebuilder_rules` appends project rules after shared rules. JSON shape:
 
 ```json
-"NODE_EXTRA_CA_CERTS": "/absolute/path/to/mkcert/rootCA.pem"
+{
+  "rules": ["store-only convention"],
+  "detail": { "brand_tokens": "optional longer notes" }
+}
 ```
 
-Typical Linux path: `$HOME/.local/share/mkcert/rootCA.pem`
+Markdown/text files are also supported (one rule per non-empty, non-`#` line). Projects with no rules file still get all shared conventions.
+
 
-Optional env vars:
+## Compose with sections[]
 
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `MAGENTO_STORE_CODE` | (empty) | REST store code |
-| `MAGENTO_ADMIN_PATH` | `admin` | Admin path used in edit links |
+Prefer structured trees over project-specific PHP. Theme CSS class names go in `css_classes` (project owns naming).
 
-### 4. Restart MCP
+```js
+// Tool: compose_pagebuilder  OR  create_cms_page({ title, sections })
+{
+  "sections": [
+    {
+      "type": "row",
+      "appearance": "full-bleed",
+      "children": [{
+        "type": "banner",
+        "background_image": "{{media url=wysiwyg/hero.jpg}}",
+        "content_html": "<h1>Title</h1>",
+        "show_button": "always",
+        "button_text": "Contact",
+        "link_url": "#contact"
+      }]
+    },
+    {
+      "type": "row",
+      "appearance": "contained",
+      "children": [
+        { "type": "heading", "text": "Section", "heading_type": "h2" },
+        { "type": "text", "html": "<p>Body</p>" },
+        {
+          "type": "columns",
+          "columns": [
+            { "children": [
+              { "type": "image", "src": "{{media url=wysiwyg/a.jpg}}", "alt": "A" },
+              { "type": "text", "html": "<p>Card</p>" }
+            ]}
+          ]
+        },
+        { "type": "buttons", "items": [{ "text": "Shop", "url": "{{store url=shop}}" }] },
+        { "type": "divider" },
+        { "type": "products", "skus": ["SKU1", "SKU2"] },
+        { "type": "block", "identifier": "my-cms-block" }
+      ]
+    }
+  ]
+}
+```
 
-In Cursor MCP settings, refresh/restart the `magento-cms` server until it shows connected.
+Native types: `row`, `columns` / `column-group` / `column`, `text`, `heading`, `image`, `buttons`, `banner`, `html`, `divider`, `video`, `map`, `tabs`, `slider`, `products`, `block`.
 
-### 5. Verify
+Call `list_section_types` for the full parameter catalog. For intentional edge-to-edge heroes use `appearance: "full-bleed"` and `allow_full_bleed: true` on save.
 
-In Cursor chat:
+## Tools
 
-```text
-Use magento_health to verify Magento.
-```
+| Tool | Purpose |
+|------|---------|
+| `magento_health` | Test base URL + token |
+| `pagebuilder_rules` | Return Full Width / inner / orphan-style rules |
+| `list_section_types` | Native element catalog + composition patterns |
+| `compose_pagebuilder` | Build master-format HTML from `sections[]` (all PB types); optional save |
+| `search_cms` | Find pages/blocks by identifier |
+| `get_cms_page` / `get_cms_block` | Load entity (`include_content`, `validate`) |
+| `validate_pagebuilder` | Stage-safety checks (html / page_id / block_id) |
+| `repair_pagebuilder` | Fix orphans, full-bleed, inners, widths, SVG (`apply=true` to save) |
+| `set_pagebuilder_html` | Save **raw** PB HTML without wiping to simple_text |
+| `create_cms_page` / `update_cms_page` | Simple Row→Text composer |
+| `create_cms_block` / `update_cms_block` | Simple Row→Text composer |
 
-Then try:
+**Important:** `update_cms_page` / `update_cms_block` with `content` rebuild as **simple_text** only. For complex pages use `set_pagebuilder_html` or `repair_pagebuilder` with `apply=true`.
 
-```text
-Create a CMS page titled "MCP Demo" with this content:
-First paragraph.
-Second paragraph.
-```
+## Local Cursor config (this machine)
 
-```text
-Update CMS page_id 8 with content: Updated body for page 8.
+```json
+{
+  "mcpServers": {
+    "magento-cms": {
+      "command": "node",
+      "args": [
+        "/home/ajaykumar.prajapati@brainvire.com/htdocs/mcp-magento-cms/src/index.js"
+      ],
+      "env": {
+        "MAGENTO_BASE_URL": "https://your-store.ddev.site",
+        "MAGENTO_ACCESS_TOKEN": "YOUR_TOKEN",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+      }
+    }
+  }
+}
 ```
 
-## Security
+After changing this package, **reload MCP** in Cursor (Settings → MCP → refresh / restart).
+
+## Setup (published npx)
 
-- Put tokens only in `mcp.json` / Cursor env (do not commit them)
-- Give the Magento integration **CMS-only** permissions
+### 1. Magento Integration Access Token
 
-## Requirements
+1. **System → Extensions → Integrations → Add New Integration**
+2. API → Custom → Content → Pages (Save/Edit Design) + Blocks
+3. Activate → copy Access Token
 
-- Node.js **18+** on the machine running Cursor
-- Magento 2 with REST and an Integration token
-- Network access from that machine to `MAGENTO_BASE_URL`
+Enable Bearer tokens (2.4.4+):
 
-## For package maintainers
+```bash
+bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
+bin/magento cache:flush config
+```
 
-Clone this repo to develop or republish. Bump `version` in `package.json`, then:
+### 2. mcp.json with npx
+
+```json
+{
+  "mcpServers": {
+    "magento-cms": {
+      "command": "npx",
+      "args": ["-y", "mcp-magento-cms"],
+      "env": {
+        "MAGENTO_BASE_URL": "https://www.example.com",
+        "MAGENTO_ACCESS_TOKEN": "YOUR_INTEGRATION_ACCESS_TOKEN"
+      }
+    }
+  }
+}
+```
+
+Local ddev TLS: add `"NODE_TLS_REJECT_UNAUTHORIZED": "0"`.
+
+## Scripts
 
 ```bash
-npm publish --access public
+npm run test:compose
+npm run test:validate
+npm run health
 ```
+
+## Version
+
+`1.2.0` — compose all native Page Builder content types via `sections[]` + validate/repair/raw HTML.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-magento-cms",
-  "version": "1.0.3",
-  "description": "Cursor MCP: Magento CMS pages/blocks with Page Builder Row→Text (zero npm deps)",
+  "version": "1.2.0",
+  "description": "Cursor MCP: Magento CMS pages/blocks + Page Builder compose/validate/repair for all native content types (zero npm deps)",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -14,7 +14,8 @@
   "scripts": {
     "start": "node src/index.js",
     "health": "node scripts/health-check.js",
-    "test:compose": "node scripts/test-compose.js"
+    "test:compose": "node scripts/test-compose.js",
+    "test:validate": "node scripts/test-validate-repair.js"
   },
   "engines": {
     "node": ">=18"

package/src/assignStores.js

@@ -0,0 +1,150 @@
+/**
+ * Assign CMS page/block to Magento store view(s).
+ *
+ * Magento 2.4.8 REST cmsPage/cmsBlock reject store_id on create/update, so we
+ * assign via Magento bootstrap PHP when MAGENTO_ROOT is set (or inferred from
+ * MAGENTO_CMS_PROJECT_RULES → project/.cursor/… → project root).
+ *
+ * Default: [0] = All Store Views.
+ * Override: pass store_ids from the tool args when the user names specific stores.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function resolveMagentoRoot() {
+  const fromEnv = String(process.env.MAGENTO_ROOT || '').trim();
+  if (fromEnv && fs.existsSync(path.join(fromEnv, 'app/bootstrap.php'))) {
+    return path.resolve(fromEnv);
+  }
+  const rules = String(process.env.MAGENTO_CMS_PROJECT_RULES || '').trim();
+  if (rules) {
+    const candidate = path.resolve(path.dirname(rules), '..');
+    if (fs.existsSync(path.join(candidate, 'app/bootstrap.php'))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {object} args
+ * @returns {number[]}
+ */
+export function resolveStoreIds(args = {}) {
+  let ids = [];
+  if (Array.isArray(args.store_ids) && args.store_ids.length) {
+    ids = args.store_ids.map((n) => Number(n)).filter((n) => Number.isFinite(n));
+  } else if (typeof args.store_ids === 'string' && args.store_ids.trim()) {
+    ids = args.store_ids
+      .split(',')
+      .map((s) => Number(s.trim()))
+      .filter((n) => Number.isFinite(n));
+  } else if (Array.isArray(args.store_codes) && args.store_codes.length) {
+    const codes = args.store_codes.map((c) => String(c).toLowerCase());
+    if (codes.includes('all') || codes.includes('*')) {
+      return [0];
+    }
+    // Numeric codes still accepted via store_ids; unknown codes → default all
+    return [0];
+  }
+
+  if (!ids.length) {
+    return [0];
+  }
+  if (ids.includes(0)) {
+    return [0];
+  }
+  return [...new Set(ids)];
+}
+
+/**
+ * @param {'page'|'block'} type
+ * @param {number} id
+ * @param {number[]} storeIds
+ */
+export function assignCmsStores(type, id, storeIds = [0]) {
+  const root = resolveMagentoRoot();
+  if (!root) {
+    return {
+      ok: false,
+      skipped: true,
+      error:
+        'Store assignment skipped: set MAGENTO_ROOT in mcp.json (path to Magento) so pages default to All Store Views (store_id 0).',
+    };
+  }
+
+  const srcScript = path.join(__dirname, '..', 'scripts', 'assign-stores.php');
+  if (!fs.existsSync(srcScript)) {
+    return { ok: false, error: `Missing ${srcScript}` };
+  }
+
+  const stores = (storeIds?.length ? storeIds : [0]).join(',');
+  const useDdev =
+    ['1', 'true', 'yes'].includes(
+      String(process.env.MAGENTO_USE_DDEV || '').toLowerCase()
+    ) || fs.existsSync(path.join(root, '.ddev'));
+
+  // Copy script into Magento var/ so ddev exec can run it inside the project mount
+  const destDir = path.join(root, 'var');
+  const destScript = path.join(destDir, 'mcp-assign-stores.php');
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(srcScript, destScript);
+  } catch (e) {
+    return { ok: false, error: `Cannot stage assign script: ${e.message}` };
+  }
+
+  const args = [
+    'var/mcp-assign-stores.php',
+    `--type=${type}`,
+    `--id=${id}`,
+    `--stores=${stores}`,
+  ];
+
+  let result;
+  if (useDdev) {
+    result = spawnSync('ddev', ['exec', 'php', ...args], {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 120000,
+    });
+  } else {
+    const phpBin = String(process.env.MAGENTO_PHP || 'php').trim() || 'php';
+    result = spawnSync(phpBin, [destScript, `--root=${root}`, ...args.slice(1)], {
+      encoding: 'utf8',
+      timeout: 120000,
+      env: process.env,
+    });
+  }
+
+  if (result.error) {
+    return { ok: false, error: result.error.message };
+  }
+  const out = String(result.stdout || '').trim();
+  const err = String(result.stderr || '').trim();
+  if (result.status !== 0) {
+    return { ok: false, error: err || out || `exit ${result.status}` };
+  }
+  try {
+    const jsonLine = out
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .pop();
+    const parsed = JSON.parse(jsonLine);
+    return {
+      ok: !!parsed.ok,
+      assigned_stores: parsed.assigned_stores,
+      requested_stores: parsed.requested_stores,
+      magento_root: root,
+      via: useDdev ? 'ddev' : 'php',
+    };
+  } catch {
+    return { ok: true, assigned_stores: storeIds, raw: out, magento_root: root };
+  }
+}