mcp-magento-cms 1.0.3 → 1.2.0

package/src/index.js

@@ -5,8 +5,8 @@
  * (standard MCP stdio transport, used by Cursor); auto-switches to
  * Content-Length framing if the client sends framed messages.
  *
- * Tools: magento_health, get/create/update cms page & block
- * Page Builder: Row → Text
+ * Tools: magento_health, compose/validate/repair Page Builder, CMS CRUD
+ * Page Builder: all Magento_PageBuilder native content types via compose_pagebuilder
  *
  * Env: MAGENTO_BASE_URL, MAGENTO_ACCESS_TOKEN (or tools/mcp-magento-cms/.env)
  */
@@ -16,17 +16,33 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   composeFromFields,
+  composeDocument,
   generateIdentifier,
   validatePageBuilderHtml,
+  PAGEBUILDER_ELEMENT_TYPES,
+  describeElements,
 } from './pageBuilder.js';
+import { validatePageBuilderContent } from './pageBuilderValidate.js';
+import { repairPageBuilderContent } from './pageBuilderRepair.js';
+import {
+  PAGEBUILDER_RULES_SUMMARY,
+  CMS_THEME_CONVENTIONS_SUMMARY,
+  SHARED_RULES_SUMMARY,
+  SHARED_RULES_DETAIL,
+} from './pageBuilderRules.js';
+import { loadProjectRules } from './projectRules.js';
 import { MagentoClient, loadDotEnv } from './magentoClient.js';
+import {
+  assignCmsStores,
+  resolveStoreIds,
+} from './assignStores.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 loadDotEnv();
 
 const SERVER_INFO = {
   name: 'magento-cms',
-  version: '1.0.0',
+  version: '1.2.0',
 };
 
 // ---------------------------------------------------------------------------
@@ -86,21 +102,73 @@ function client() {
   return MagentoClient.fromEnv();
 }
 
-function summarizeEntity(entity, type, editUrl) {
+/** Magento 2.4.8 cmsPage REST returns `active`; older docs use `is_active`. */
+function entityIsActive(entity) {
+  if (entity?.active !== undefined && entity?.active !== null) {
+    return entity.active;
+  }
+  if (entity?.is_active !== undefined && entity?.is_active !== null) {
+    return entity.is_active;
+  }
+  return null;
+}
+
+function summarizeEntity(entity, type, editUrl, extras = {}) {
+  const content = String(entity?.content || '');
   return {
     type,
     id: entity?.id ?? entity?.page_id ?? entity?.block_id ?? null,
     title: entity?.title ?? null,
     identifier: entity?.identifier ?? null,
-    is_active: entity?.is_active ?? null,
-    content_preview: String(entity?.content || '').slice(0, 280),
-    has_pagebuilder:
-      typeof entity?.content === 'string' &&
-      entity.content.includes('data-content-type="row"'),
+    is_active: entityIsActive(entity),
+    content_preview: content.slice(0, 280),
+    content_length: content.length,
+    has_pagebuilder: content.includes('data-content-type="row"'),
     admin_edit_url: editUrl,
+    ...extras,
   };
 }
 
+
+/**
+ * Resolve CMS content from args:
+ * 1) sections[] → composeDocument (full Page Builder tree)
+ * 2) html → raw master-format HTML
+ * 3) content (+headline) → simple Row→Text
+ */
+function resolvePageBuilderContent(args = {}) {
+  if (Array.isArray(args.sections) && args.sections.length) {
+    const doc = composeDocument(args.sections);
+    return {
+      html: doc.html,
+      mode: 'sections',
+      used_types: doc.used_types,
+      allow_full_bleed: doc.allow_full_bleed,
+    };
+  }
+  if (args.html != null && String(args.html).trim()) {
+    return {
+      html: String(args.html),
+      mode: 'html',
+      used_types: [],
+      allow_full_bleed: args.allow_full_bleed === true,
+    };
+  }
+  if (args.content != null && String(args.content).length) {
+    return {
+      html: composeFromFields({
+        content: args.content,
+        headline: args.headline,
+        subheadline: args.subheadline,
+      }),
+      mode: 'simple_text',
+      used_types: ['row', 'text'],
+      allow_full_bleed: false,
+    };
+  }
+  return null;
+}
+
 const TOOLS = [
   {
     name: 'magento_health',
@@ -108,152 +176,776 @@ const TOOLS = [
       'Check Magento REST connectivity and Integration token (reads CMS pages list).',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   },
+  {
+    name: 'pagebuilder_rules',
+    description:
+      'Return Page Builder hard rules plus optional store project rules (media paths, theme tokens) from MAGENTO_CMS_PROJECT_RULES. Read before editing CMS HTML or media.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'list_section_types',
+    description:
+      'List supported Page Builder composers and raw-HTML tools for CMS pages/blocks.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'search_cms',
+    description:
+      'Search CMS pages and/or blocks by identifier (exact or like).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: { type: 'string', description: 'URL key / identifier' },
+        type: {
+          type: 'string',
+          description: 'page | block | both (default both)',
+        },
+        condition_type: {
+          type: 'string',
+          description: 'eq (default) or like',
+        },
+      },
+      required: ['identifier'],
+    },
+  },
   {
     name: 'get_cms_page',
-    description: 'Get a Magento CMS page by page_id (numeric id).',
+    description:
+      'Get a Magento CMS page by page_id. Optionally include full content and Page Builder validation.',
     inputSchema: {
       type: 'object',
       properties: {
-        page_id: { type: 'number', description: 'CMS page ID, e.g. 8' },
+        page_id: { type: 'number', description: 'CMS page ID, e.g. 124' },
+        include_content: {
+          type: 'boolean',
+          description: 'If true, include full Page Builder HTML',
+        },
+        validate: {
+          type: 'boolean',
+          description: 'If true, run Page Builder stage-safety validation',
+        },
       },
       required: ['page_id'],
     },
   },
   {
+    name: 'get_cms_block',
+    description:
+      'Get a Magento CMS block by block_id. Optionally include full content and validation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        block_id: { type: 'number' },
+        include_content: { type: 'boolean' },
+        validate: { type: 'boolean' },
+      },
+      required: ['block_id'],
+    },
+  },
+  {
+    name: 'validate_pagebuilder',
+    description:
+      'Validate Page Builder HTML for admin stage safety (orphan styles, full-bleed, missing inners/widths). Pass html, or page_id / block_id to load from Magento. Use allow_full_bleed=true for intentional edge-to-edge heroes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        html: { type: 'string', description: 'Raw Page Builder HTML' },
+        page_id: { type: 'number' },
+        block_id: { type: 'number' },
+        allow_full_bleed: {
+          type: 'boolean',
+          description: 'Treat full-bleed as warning instead of error (default false)',
+        },
+      },
+    },
+  },
+  {
+    name: 'repair_pagebuilder',
+    description:
+      'Repair Page Builder HTML so admin stage can open: remove orphan styles, fix full-bleed→full-width with inner, add column widths, strip SVG. Pass html to preview, or page_id/block_id with apply=true to save.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        html: { type: 'string' },
+        page_id: { type: 'number' },
+        block_id: { type: 'number' },
+        apply: {
+          type: 'boolean',
+          description: 'If true and page_id/block_id set, save repaired HTML to Magento',
+        },
+        strip_svg: { type: 'boolean', description: 'Default true' },
+        fix_full_bleed: { type: 'boolean', description: 'Default true' },
+      },
+    },
+  },
+  {
+    name: 'set_pagebuilder_html',
+    description:
+      'Save RAW Page Builder HTML to a CMS page or block WITHOUT rebuilding as simple_text. Use for complex layouts (Banner+button, columns, full-bleed hero). Validates before save unless force=true. For intentional full-bleed heroes set allow_full_bleed=true (and repair_first keeps bleed).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_id: { type: 'number' },
+        block_id: { type: 'number' },
+        html: { type: 'string', description: 'Full Page Builder master-format HTML' },
+        force: {
+          type: 'boolean',
+          description: 'Save even if validation reports errors (default false)',
+        },
+        repair_first: {
+          type: 'boolean',
+          description: 'Run repair_pagebuilder before save (default true)',
+        },
+        allow_full_bleed: {
+          type: 'boolean',
+          description:
+            'When true, full-bleed rows are warnings not errors, and repair will NOT convert them to full-width (default false)',
+        },
+      },
+      required: ['html'],
+    },
+  },
+    {
+    name: 'compose_pagebuilder',
+    description:
+      'Compose Magento Page Builder master-format HTML from a structured sections[] tree covering ALL native content types (row, columns, text, heading, image, buttons, banner, html, divider, video, map, tabs, slider, products, block). Does not save unless page_id/block_id provided. Prefer this over project PHP composers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sections: {
+          type: 'array',
+          description:
+            'Tree of {type, ...props, children?}. Root items are usually row. See list_section_types.',
+        },
+        page_id: {
+          type: 'number',
+          description: 'Optional: save composed HTML to this CMS page',
+        },
+        block_id: {
+          type: 'number',
+          description: 'Optional: save composed HTML to this CMS block',
+        },
+        validate: {
+          type: 'boolean',
+          description: 'Validate stage-safety (default true)',
+        },
+        repair_first: {
+          type: 'boolean',
+          description: 'When saving, run repair first (default true)',
+        },
+        allow_full_bleed: {
+          type: 'boolean',
+          description:
+            'Allow full-bleed rows on validate/save. Auto-true if sections include full-bleed row unless set false.',
+        },
+        force: {
+          type: 'boolean',
+          description: 'Save even if validation fails (default false)',
+        },
+      },
+      required: ['sections'],
+    },
+  },
+{
     name: 'create_cms_page',
     description:
-      'Create a Magento CMS page with Page Builder content (Row → Text) from simple text.',
+      'Create a Magento CMS page. Pass sections[] for full Page Builder trees, html for raw master HTML, or content for simple Row→Text. Defaults: page_layout cms-full-width (Page — Full Width), All Store Views (store_id 0). Pass page_layout / store_ids only when the user asks for something different.',
     inputSchema: {
       type: 'object',
       properties: {
         title: { type: 'string', description: 'Page title' },
+        sections: {
+          type: 'array',
+          description: 'Page Builder element tree (preferred for complex pages)',
+        },
+        html: {
+          type: 'string',
+          description: 'Raw Page Builder master-format HTML',
+        },
         content: {
           type: 'string',
-          description: 'Plain text or simple HTML body',
+          description: 'Plain text or simple HTML → Row→Text (legacy)',
         },
         identifier: {
           type: 'string',
           description: 'URL key; auto from title if omitted',
         },
-        headline: { type: 'string', description: 'Optional H2 above body' },
+        headline: { type: 'string', description: 'Optional H2 when using content' },
         is_active: { type: 'boolean', description: 'Default true' },
-        page_layout: { type: 'string', description: 'Default 1column' },
+        page_layout: { type: 'string', description: 'Default cms-full-width (Page — Full Width); pass page_layout only when the user specifies a different layout' },
+        allow_full_bleed: { type: 'boolean' },
+        store_ids: {
+          type: 'array',
+          description:
+            'Store view IDs to assign. Default [0] = All Store Views. Pass specific IDs only when the user asks for particular store(s).',
+          items: { type: 'number' },
+        },
       },
-      required: ['title', 'content'],
+      required: ['title'],
     },
   },
   {
     name: 'update_cms_page',
     description:
-      'Update an existing Magento CMS page by page_id. Rebuilds Page Builder Row → Text when content is provided.',
+      'Update CMS page metadata and/or content. Prefer sections[] or html for complex layouts (same as compose_pagebuilder / set_pagebuilder_html). content alone still rebuilds as Row→Text.',
     inputSchema: {
       type: 'object',
       properties: {
         page_id: { type: 'number', description: 'CMS page ID to update' },
         title: { type: 'string' },
+        sections: { type: 'array' },
+        html: { type: 'string' },
         content: { type: 'string' },
         headline: { type: 'string' },
         identifier: { type: 'string' },
         is_active: { type: 'boolean' },
-        page_layout: { type: 'string' },
+        page_layout: { type: 'string', description: 'Omit to keep existing; on create default is cms-full-width — only set when the user asks for a different layout' },
+        allow_full_bleed: { type: 'boolean' },
+        store_ids: {
+          type: 'array',
+          description:
+            'Optional store view IDs. Omit to leave assignment unchanged; pass [0] for All Store Views or specific IDs when the user asks.',
+          items: { type: 'number' },
+        },
       },
       required: ['page_id'],
     },
   },
-  {
-    name: 'get_cms_block',
-    description: 'Get a Magento CMS block by block_id.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        block_id: { type: 'number' },
-      },
-      required: ['block_id'],
-    },
-  },
   {
     name: 'create_cms_block',
     description:
-      'Create a Magento CMS block with Page Builder Row → Text from simple text.',
+      'Create a Magento CMS block. Pass sections[] (full PB tree), html, or content (Row→Text).',
     inputSchema: {
       type: 'object',
       properties: {
         title: { type: 'string' },
+        sections: { type: 'array' },
+        html: { type: 'string' },
         content: { type: 'string' },
         identifier: { type: 'string' },
         headline: { type: 'string' },
         is_active: { type: 'boolean' },
+        allow_full_bleed: { type: 'boolean' },
+        store_ids: {
+          type: 'array',
+          description:
+            'Store view IDs to assign. Default [0] = All Store Views. Pass specific IDs only when the user asks for particular store(s).',
+          items: { type: 'number' },
+        },
       },
-      required: ['title', 'content'],
+      required: ['title'],
     },
   },
   {
     name: 'update_cms_block',
     description:
-      'Update Magento CMS block by block_id. Rebuilds Page Builder when content is set.',
+      'Update CMS block metadata and/or content via sections[], html, or content (Row→Text).',
     inputSchema: {
       type: 'object',
       properties: {
         block_id: { type: 'number' },
         title: { type: 'string' },
+        sections: { type: 'array' },
+        html: { type: 'string' },
         content: { type: 'string' },
         headline: { type: 'string' },
         identifier: { type: 'string' },
         is_active: { type: 'boolean' },
+        allow_full_bleed: { type: 'boolean' },
+        store_ids: {
+          type: 'array',
+          description:
+            'Optional store view IDs. Omit to leave assignment unchanged; pass [0] for All Store Views or specific IDs when the user asks.',
+          items: { type: 'number' },
+        },
       },
       required: ['block_id'],
     },
   },
-  {
-    name: 'list_section_types',
-    description:
-      'List supported Page Builder section types (MVP: simple_text).',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
 ];
 
+async function loadHtmlFromArgs(magento, args) {
+  if (args.html !== undefined && String(args.html || '').length) {
+    return { html: String(args.html), source: 'html' };
+  }
+  if (args.page_id) {
+    const page = await magento.getPage(args.page_id);
+    return {
+      html: String(page.content || ''),
+      source: 'page',
+      entity: page,
+    };
+  }
+  if (args.block_id) {
+    const block = await magento.getBlock(args.block_id);
+    return {
+      html: String(block.content || ''),
+      source: 'block',
+      entity: block,
+    };
+  }
+  throw new Error('Provide html, page_id, or block_id');
+}
+
 async function callTool(name, args = {}) {
   switch (name) {
     case 'magento_health': {
       const magento = client();
       const result = await magento.health();
+      const project = loadProjectRules();
       return toolOk({
         ...result,
-        message: 'Magento REST OK. You can create/update CMS pages and blocks.',
+        message:
+          'Magento REST OK. CMS content: use this MCP only (no PHP compose/deploy). Call pagebuilder_rules first, then compose_pagebuilder / create_* / set_pagebuilder_html + validate/repair.',
+        pagebuilder_rules: PAGEBUILDER_RULES_SUMMARY,
+        cms_theme_conventions: CMS_THEME_CONVENTIONS_SUMMARY,
+        project_rules: project.rules,
+        project_rules_source: project.source,
+      });
+    }
+    case 'pagebuilder_rules': {
+      const project = loadProjectRules();
+      return toolOk({
+        rules: [...SHARED_RULES_SUMMARY, ...project.rules],
+        pagebuilder_rules: PAGEBUILDER_RULES_SUMMARY,
+        cms_theme_conventions: CMS_THEME_CONVENTIONS_SUMMARY,
+        project_rules: project.rules,
+        project_rules_source: project.source,
+        detail: {
+          ...SHARED_RULES_DETAIL,
+          ...project.detail,
+        },
       });
     }
+    case 'list_section_types':
+      return toolOk({
+        elements: describeElements(),
+        element_types: PAGEBUILDER_ELEMENT_TYPES,
+        section_types: [
+          {
+            type: 'sections_tree',
+            description:
+              'Preferred: pass sections[] to compose_pagebuilder / create_cms_page / create_cms_block. Nested {type, children} using any Magento_PageBuilder native type.',
+            params: ['sections[]'],
+          },
+          {
+            type: 'simple_text',
+            description:
+              'Legacy: Page Builder Row (contained) → Text via content/headline fields.',
+            params: ['content', 'headline?', 'subheadline?'],
+          },
+          {
+            type: 'raw_pagebuilder_html',
+            description:
+              'Pass full master-format HTML via set_pagebuilder_html or html= on create/update.',
+            params: [
+              'html',
+              'page_id|block_id',
+              'repair_first?',
+              'force?',
+              'allow_full_bleed?',
+            ],
+          },
+          {
+            type: 'banner_poster_cta',
+            description:
+              'sections pattern: row → banner (poster, show_button=always, link_url, background_image, content_html).',
+            params: [
+              'background_image',
+              'content_html',
+              'button_text',
+              'link_url',
+              'show_button=always',
+              'allow_full_bleed?',
+            ],
+          },
+          {
+            type: 'hero_plus_body',
+            description:
+              'sections pattern: row(full-bleed|full-width)+banner hero, then row(contained|full-width) body with heading/text/columns/image/buttons.',
+            params: [
+              'hero_image',
+              'content_html',
+              'button_text?',
+              'link_url?',
+              'body children',
+              'css_classes?',
+            ],
+          },
+          {
+            type: 'column_cards',
+            description:
+              'sections pattern: columns → each column Image+Text(+Buttons). Prefer Image over SVG-in-Text.',
+            params: ['column_count', 'cards[]'],
+          },
+        ],
+        maintenance_tools: [
+          'compose_pagebuilder',
+          'validate_pagebuilder',
+          'repair_pagebuilder',
+          'pagebuilder_rules',
+          'search_cms',
+        ],
+        note: PAGEBUILDER_RULES_SUMMARY.join(' '),
+      });
+    case 'search_cms': {
+      const magento = client();
+      const type = (args.type || 'both').toLowerCase();
+      const condition = (args.condition_type || 'eq').toLowerCase();
+      const out = { identifier: args.identifier, pages: [], blocks: [] };
+      if (type === 'page' || type === 'both') {
+        const res = await magento.searchPagesByIdentifier(
+          args.identifier,
+          condition
+        );
+        out.pages = (res.items || []).map((p) =>
+          summarizeEntity(p, 'page', magento.pageEditUrl(p.id))
+        );
+      }
+      if (type === 'block' || type === 'both') {
+        const res = await magento.searchBlocksByIdentifier(
+          args.identifier,
+          condition
+        );
+        out.blocks = (res.items || []).map((b) =>
+          summarizeEntity(b, 'block', magento.blockEditUrl(b.id))
+        );
+      }
+      return toolOk(out);
+    }
     case 'get_cms_page': {
       const magento = client();
       const page = await magento.getPage(args.page_id);
+      const extras = {};
+      if (args.include_content) extras.content = page.content;
+      if (args.validate) {
+        extras.validation = validatePageBuilderContent(String(page.content || ''));
+      }
       return toolOk(
-        summarizeEntity(page, 'page', magento.pageEditUrl(page.id || args.page_id))
+        summarizeEntity(
+          page,
+          'page',
+          magento.pageEditUrl(page.id || args.page_id),
+          extras
+        )
       );
     }
+    case 'get_cms_block': {
+      const magento = client();
+      const block = await magento.getBlock(args.block_id);
+      const extras = {};
+      if (args.include_content) extras.content = block.content;
+      if (args.validate) {
+        extras.validation = validatePageBuilderContent(
+          String(block.content || '')
+        );
+      }
+      return toolOk(
+        summarizeEntity(
+          block,
+          'block',
+          magento.blockEditUrl(block.id || args.block_id),
+          extras
+        )
+      );
+    }
+    case 'validate_pagebuilder': {
+      const magento = client();
+      const loaded = await loadHtmlFromArgs(magento, args);
+      const validation = validatePageBuilderContent(loaded.html, {
+        allowFullBleed: args.allow_full_bleed === true,
+      });
+      return toolOk({
+        source: loaded.source,
+        page_id: args.page_id || null,
+        block_id: args.block_id || null,
+        identifier: loaded.entity?.identifier || null,
+        allow_full_bleed: args.allow_full_bleed === true,
+        ...validation,
+      });
+    }
+    case 'repair_pagebuilder': {
+      const magento = client();
+      const loaded = await loadHtmlFromArgs(magento, args);
+      const repaired = repairPageBuilderContent(loaded.html, {
+        stripSvg: args.strip_svg,
+        fixFullBleed: args.fix_full_bleed,
+      });
+
+      let saved = null;
+      if (args.apply) {
+        if (args.page_id) {
+          const existing = loaded.entity || (await magento.getPage(args.page_id));
+          await magento.updatePage(args.page_id, {
+            title: existing.title,
+            identifier: existing.identifier,
+            content: repaired.content,
+            content_heading: existing.content_heading ?? '',
+            page_layout: existing.page_layout || 'cms-full-width',
+            is_active: entityIsActive(existing),
+            meta_title: existing.meta_title || existing.title,
+            meta_description: existing.meta_description || '',
+          });
+          saved = { type: 'page', id: args.page_id };
+        } else if (args.block_id) {
+          const existing =
+            loaded.entity || (await magento.getBlock(args.block_id));
+          await magento.updateBlock(args.block_id, {
+            title: existing.title,
+            identifier: existing.identifier,
+            content: repaired.content,
+            is_active: entityIsActive(existing),
+          });
+          saved = { type: 'block', id: args.block_id };
+        } else {
+          throw new Error('apply=true requires page_id or block_id');
+        }
+      }
+
+      return toolOk({
+        changed: repaired.changed,
+        actions: repaired.actions,
+        before_ok: repaired.before.ok,
+        after_ok: repaired.after.ok,
+        before_errors: repaired.before.errors,
+        after_errors: repaired.after.errors,
+        after_warnings: repaired.after.warnings,
+        saved,
+        // Only return repaired HTML when not applied (preview) or explicitly small
+        content_length: repaired.content.length,
+        content_preview: repaired.content.slice(0, 400),
+        content: args.apply ? undefined : repaired.content,
+      });
+    }
+    case 'set_pagebuilder_html': {
+      const magento = client();
+      if (!args.page_id && !args.block_id) {
+        throw new Error('set_pagebuilder_html requires page_id or block_id');
+      }
+      let html = String(args.html || '');
+      const repairFirst = args.repair_first !== false;
+      const allowFullBleed = args.allow_full_bleed === true;
+      let repairMeta = null;
+      if (repairFirst) {
+        const repaired = repairPageBuilderContent(html, {
+          stripSvg: true,
+          // Keep intentional full-bleed heroes (edge-to-edge Banner)
+          fixFullBleed: allowFullBleed ? false : true,
+        });
+        html = repaired.content;
+        repairMeta = {
+          actions: repaired.actions,
+          after_ok: repaired.after.ok,
+          after_errors: repaired.after.errors,
+          fix_full_bleed: allowFullBleed ? false : true,
+        };
+      }
+      const validation = validatePageBuilderContent(html, {
+        allowFullBleed,
+      });
+      if (!validation.ok && !args.force) {
+        throw new Error(
+          `Page Builder validation failed (pass force=true to save anyway): ${validation.errors.join(
+            ' | '
+          )}`
+        );
+      }
+      if (args.page_id) {
+        const existing = await magento.getPage(args.page_id);
+        await magento.updatePage(args.page_id, {
+          title: existing.title,
+          identifier: existing.identifier,
+          content: html,
+          content_heading: existing.content_heading ?? '',
+          page_layout: existing.page_layout || 'cms-full-width',
+          is_active: entityIsActive(existing),
+          meta_title: existing.meta_title || existing.title,
+          meta_description: existing.meta_description || '',
+        });
+        return toolOk({
+          result: 'saved',
+          type: 'page',
+          id: args.page_id,
+          content_length: html.length,
+          allow_full_bleed: allowFullBleed,
+          validation,
+          repair: repairMeta,
+          admin_edit_url: magento.pageEditUrl(args.page_id),
+        });
+      }
+      const existing = await magento.getBlock(args.block_id);
+      await magento.updateBlock(args.block_id, {
+        title: existing.title,
+        identifier: existing.identifier,
+        content: html,
+        is_active: entityIsActive(existing),
+      });
+      return toolOk({
+        result: 'saved',
+        type: 'block',
+        id: args.block_id,
+        content_length: html.length,
+        allow_full_bleed: allowFullBleed,
+        validation,
+        repair: repairMeta,
+        admin_edit_url: magento.blockEditUrl(args.block_id),
+      });
+    }
+    case 'compose_pagebuilder': {
+      const doc = composeDocument(args.sections);
+      let html = doc.html;
+      const allowFullBleed =
+        args.allow_full_bleed === false
+          ? false
+          : args.allow_full_bleed === true || doc.allow_full_bleed;
+      const doValidate = args.validate !== false;
+      let repairMeta = null;
+      if (args.page_id || args.block_id) {
+        const repairFirst = args.repair_first !== false;
+        if (repairFirst) {
+          const repaired = repairPageBuilderContent(html, {
+            stripSvg: true,
+            fixFullBleed: allowFullBleed ? false : true,
+          });
+          html = repaired.content;
+          repairMeta = {
+            actions: repaired.actions,
+            after_ok: repaired.after.ok,
+            after_errors: repaired.after.errors,
+          };
+        }
+      }
+      const validation = doValidate
+        ? validatePageBuilderContent(html, { allowFullBleed })
+        : null;
+      if (doValidate && validation && !validation.ok && !args.force) {
+        if (!args.page_id && !args.block_id) {
+          return toolOk({
+            result: 'composed',
+            saved: false,
+            used_types: doc.used_types,
+            allow_full_bleed: allowFullBleed,
+            validation,
+            content_length: html.length,
+            html,
+            note: 'Validation reported errors — HTML still returned. Pass force=true with page_id/block_id to save anyway.',
+          });
+        }
+        throw new Error(
+          `Page Builder validation failed (pass force=true to save anyway): ${validation.errors.join(
+            ' | '
+          )}`
+        );
+      }
+
+      if (args.page_id || args.block_id) {
+        const magento = client();
+        if (args.page_id) {
+          const existing = await magento.getPage(args.page_id);
+          await magento.updatePage(args.page_id, {
+            title: existing.title,
+            identifier: existing.identifier,
+            content: html,
+            content_heading: existing.content_heading ?? '',
+            page_layout: existing.page_layout || 'cms-full-width',
+            is_active: entityIsActive(existing),
+            meta_title: existing.meta_title || existing.title,
+            meta_description: existing.meta_description || '',
+          });
+          return toolOk({
+            result: 'saved',
+            type: 'page',
+            id: args.page_id,
+            used_types: doc.used_types,
+            allow_full_bleed: allowFullBleed,
+            validation,
+            repair: repairMeta,
+            content_length: html.length,
+            admin_edit_url: magento.pageEditUrl(args.page_id),
+          });
+        }
+        const existing = await magento.getBlock(args.block_id);
+        await magento.updateBlock(args.block_id, {
+          title: existing.title,
+          identifier: existing.identifier,
+          content: html,
+          is_active: entityIsActive(existing),
+        });
+        return toolOk({
+          result: 'saved',
+          type: 'block',
+          id: args.block_id,
+          used_types: doc.used_types,
+          allow_full_bleed: allowFullBleed,
+          validation,
+          repair: repairMeta,
+          content_length: html.length,
+          admin_edit_url: magento.blockEditUrl(args.block_id),
+        });
+      }
+
+      return toolOk({
+        result: 'composed',
+        saved: false,
+        used_types: doc.used_types,
+        allow_full_bleed: allowFullBleed,
+        validation,
+        content_length: html.length,
+        html,
+      });
+    }
     case 'create_cms_page': {
       const magento = client();
       const identifier =
         (args.identifier || '').trim() || generateIdentifier(args.title);
-      const pbHtml = composeFromFields({
-        content: args.content,
-        headline: args.headline,
+      const resolved = resolvePageBuilderContent(args);
+      if (!resolved) {
+        throw new Error(
+          'Provide sections[], html, or content to create a CMS page'
+        );
+      }
+      let pbHtml = resolved.html;
+      const allowFullBleed =
+        args.allow_full_bleed === true || resolved.allow_full_bleed === true;
+      if (resolved.mode === 'sections' || resolved.mode === 'html') {
+        const repaired = repairPageBuilderContent(pbHtml, {
+          stripSvg: true,
+          fixFullBleed: allowFullBleed ? false : true,
+        });
+        pbHtml = repaired.content;
+      }
+      const validation = validatePageBuilderContent(pbHtml, {
+        allowFullBleed,
       });
+      if (!validation.ok) {
+        throw new Error(
+          `Page Builder validation failed: ${validation.errors.join(' | ')}`
+        );
+      }
       if (!validatePageBuilderHtml(pbHtml)) {
-        throw new Error('Generated Page Builder HTML failed validation');
+        throw new Error('Generated Page Builder HTML failed basic check');
       }
       const page = await magento.createPage({
         title: args.title,
         identifier,
         content: pbHtml,
         content_heading: '',
-        page_layout: args.page_layout || '1column',
+        page_layout: args.page_layout || 'cms-full-width',
         is_active: args.is_active !== false,
-        store_id: [0],
         meta_title: args.title,
         meta_description: '',
       });
       const id = page?.id ?? page?.page_id;
+      const storeIds = resolveStoreIds(args);
+      const storeAssign = assignCmsStores('page', Number(id), storeIds);
       return toolOk({
         result: 'created',
+        mode: resolved.mode,
+        used_types: resolved.used_types,
+        allow_full_bleed: allowFullBleed,
+        validation,
+        store_ids: storeIds,
+        store_assign: storeAssign,
         ...summarizeEntity(page, 'page', magento.pageEditUrl(id)),
         full_content_length: pbHtml.length,
       });
@@ -268,13 +960,31 @@ async function callTool(name, args = {}) {
         generateIdentifier(title);
 
       let content = existing.content;
-      if (args.content !== undefined && String(args.content || '').length) {
-        content = composeFromFields({
-          content: args.content,
-          headline: args.headline,
-        });
+      let mode = 'metadata_only';
+      let used_types = [];
+      let validation = null;
+      const resolved = resolvePageBuilderContent(args);
+      if (resolved) {
+        mode = resolved.mode;
+        used_types = resolved.used_types;
+        content = resolved.html;
+        const allowFullBleed =
+          args.allow_full_bleed === true || resolved.allow_full_bleed === true;
+        if (mode === 'sections' || mode === 'html') {
+          const repaired = repairPageBuilderContent(content, {
+            stripSvg: true,
+            fixFullBleed: allowFullBleed ? false : true,
+          });
+          content = repaired.content;
+        }
+        validation = validatePageBuilderContent(content, { allowFullBleed });
+        if (!validation.ok) {
+          throw new Error(
+            `Page Builder validation failed: ${validation.errors.join(' | ')}`
+          );
+        }
         if (!validatePageBuilderHtml(content)) {
-          throw new Error('Generated Page Builder HTML failed validation');
+          throw new Error('Generated Page Builder HTML failed basic check');
         }
       }
 
@@ -283,48 +993,76 @@ async function callTool(name, args = {}) {
         identifier,
         content,
         content_heading: existing.content_heading ?? '',
-        page_layout: args.page_layout || existing.page_layout || '1column',
+        page_layout: args.page_layout || existing.page_layout || 'cms-full-width',
         is_active:
-          args.is_active !== undefined ? args.is_active : existing.is_active,
+          args.is_active !== undefined
+            ? args.is_active
+            : entityIsActive(existing),
         meta_title: existing.meta_title || title,
         meta_description: existing.meta_description || '',
-        store_id: existing.store_id || [0],
       });
       const id = page?.id ?? args.page_id;
+      let storeAssign = null;
+      let storeIds = null;
+      if (args.store_ids !== undefined) {
+        storeIds = resolveStoreIds(args);
+        storeAssign = assignCmsStores('page', Number(id), storeIds);
+      }
       return toolOk({
         result: 'updated',
+        mode,
+        used_types,
+        validation,
+        store_ids: storeIds,
+        store_assign: storeAssign,
         ...summarizeEntity(page, 'page', magento.pageEditUrl(id)),
         full_content_length: String(content || '').length,
       });
     }
-    case 'get_cms_block': {
-      const magento = client();
-      const block = await magento.getBlock(args.block_id);
-      return toolOk(
-        summarizeEntity(block, 'block', magento.blockEditUrl(block.id || args.block_id))
-      );
-    }
     case 'create_cms_block': {
       const magento = client();
       const identifier =
         (args.identifier || '').trim() || generateIdentifier(args.title);
-      const pbHtml = composeFromFields({
-        content: args.content,
-        headline: args.headline,
+      const resolved = resolvePageBuilderContent(args);
+      if (!resolved) {
+        throw new Error(
+          'Provide sections[], html, or content to create a CMS block'
+        );
+      }
+      let pbHtml = resolved.html;
+      const allowFullBleed =
+        args.allow_full_bleed === true || resolved.allow_full_bleed === true;
+      if (resolved.mode === 'sections' || resolved.mode === 'html') {
+        const repaired = repairPageBuilderContent(pbHtml, {
+          stripSvg: true,
+          fixFullBleed: allowFullBleed ? false : true,
+        });
+        pbHtml = repaired.content;
+      }
+      const validation = validatePageBuilderContent(pbHtml, {
+        allowFullBleed,
       });
-      if (!validatePageBuilderHtml(pbHtml)) {
-        throw new Error('Generated Page Builder HTML failed validation');
+      if (!validation.ok) {
+        throw new Error(
+          `Page Builder validation failed: ${validation.errors.join(' | ')}`
+        );
       }
       const block = await magento.createBlock({
         title: args.title,
         identifier,
         content: pbHtml,
         is_active: args.is_active !== false,
-        store_id: [0],
       });
       const id = block?.id ?? block?.block_id;
+      const storeIds = resolveStoreIds(args);
+      const storeAssign = assignCmsStores('block', Number(id), storeIds);
       return toolOk({
         result: 'created',
+        mode: resolved.mode,
+        used_types: resolved.used_types,
+        validation,
+        store_ids: storeIds,
+        store_assign: storeAssign,
         ...summarizeEntity(block, 'block', magento.blockEditUrl(id)),
       });
     }
@@ -338,13 +1076,28 @@ async function callTool(name, args = {}) {
         generateIdentifier(title);
 
       let content = existing.content;
-      if (args.content !== undefined && String(args.content || '').length) {
-        content = composeFromFields({
-          content: args.content,
-          headline: args.headline,
-        });
-        if (!validatePageBuilderHtml(content)) {
-          throw new Error('Generated Page Builder HTML failed validation');
+      let mode = 'metadata_only';
+      let used_types = [];
+      let validation = null;
+      const resolved = resolvePageBuilderContent(args);
+      if (resolved) {
+        mode = resolved.mode;
+        used_types = resolved.used_types;
+        content = resolved.html;
+        const allowFullBleed =
+          args.allow_full_bleed === true || resolved.allow_full_bleed === true;
+        if (mode === 'sections' || mode === 'html') {
+          const repaired = repairPageBuilderContent(content, {
+            stripSvg: true,
+            fixFullBleed: allowFullBleed ? false : true,
+          });
+          content = repaired.content;
+        }
+        validation = validatePageBuilderContent(content, { allowFullBleed });
+        if (!validation.ok) {
+          throw new Error(
+            `Page Builder validation failed: ${validation.errors.join(' | ')}`
+          );
         }
       }
 
@@ -353,27 +1106,25 @@ async function callTool(name, args = {}) {
         identifier,
         content,
         is_active:
-          args.is_active !== undefined ? args.is_active : existing.is_active,
-        store_id: existing.store_id || [0],
+          args.is_active !== undefined ? args.is_active : entityIsActive(existing),
       });
       const id = block?.id ?? args.block_id;
+      let storeAssign = null;
+      let storeIds = null;
+      if (args.store_ids !== undefined) {
+        storeIds = resolveStoreIds(args);
+        storeAssign = assignCmsStores('block', Number(id), storeIds);
+      }
       return toolOk({
         result: 'updated',
+        mode,
+        used_types,
+        validation,
+        store_ids: storeIds,
+        store_assign: storeAssign,
         ...summarizeEntity(block, 'block', magento.blockEditUrl(id)),
       });
     }
-    case 'list_section_types':
-      return toolOk({
-        section_types: [
-          {
-            type: 'simple_text',
-            description:
-              'Page Builder Row (contained) → Text (WYSIWYG). Default for pasted content.',
-            params: ['content', 'headline?', 'subheadline?'],
-          },
-        ],
-        note: 'More types will be added as element templates are documented.',
-      });
     default:
       throw new Error(`Unknown tool: ${name}`);
   }