mcp-magento-cms 1.0.0

package/scripts/smoke-e2e.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * End-to-end smoke test: creates a Page Builder CMS page via REST,
+ * reads it back, and prints the admin edit URL.
+ *
+ *   NODE_EXTRA_CA_CERTS=~/.local/share/mkcert/rootCA.pem node scripts/smoke-e2e.js
+ */
+import { MagentoClient, loadDotEnv } from '../src/magentoClient.js';
+import { composeFromFields, generateIdentifier, validatePageBuilderHtml } from '../src/pageBuilder.js';
+
+loadDotEnv();
+const client = MagentoClient.fromEnv();
+
+const title = `MCP Smoke Test ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`;
+const content = composeFromFields({
+  headline: 'MCP Smoke Test',
+  subheadline: 'Created via mcp-magento-cms end-to-end test',
+  content: 'If you can see this page in Admin with Page Builder sections, the pipeline works.\nRow (contained) with a Text element.',
+});
+
+if (!validatePageBuilderHtml(content)) {
+  console.error('Composer output failed Page Builder validation');
+  process.exit(1);
+}
+
+const page = {
+  identifier: generateIdentifier(title),
+  title,
+  page_layout: '1column',
+  content_heading: '',
+  content,
+  active: true,
+};
+
+const created = await client.createPage(page);
+console.log(`Created page id=${created.id} identifier=${created.identifier}`);
+
+const readBack = await client.getPage(created.id);
+const ok = validatePageBuilderHtml(readBack.content);
+console.log(`Read-back content valid Page Builder HTML: ${ok}`);
+console.log(`Admin edit URL: ${client.pageEditUrl(created.id)}`);
+console.log(`Frontend URL: ${client.baseUrl}/${created.identifier}`);

package/scripts/test-compose.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { composeFromFields, validatePageBuilderHtml } from '../src/pageBuilder.js';
+
+const html = composeFromFields({
+  content: 'Hello from MCP\nSecond line',
+  headline: 'Welcome',
+});
+
+if (!validatePageBuilderHtml(html)) {
+  console.error('FAIL: invalid PB HTML');
+  process.exit(1);
+}
+if (!html.includes('Welcome') || !html.includes('Hello from MCP')) {
+  console.error('FAIL: content missing');
+  process.exit(1);
+}
+console.log('OK: Page Builder Row → Text composition');
+console.log(html.slice(0, 200) + '...');

package/src/index.js

@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+/**
+ * Magento CMS MCP server (zero npm dependencies — Node 18+ only).
+ * Protocol: JSON-RPC 2.0 over stdio. Newline-delimited JSON by default
+ * (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
+ *
+ * Env: MAGENTO_BASE_URL, MAGENTO_ACCESS_TOKEN (or tools/mcp-magento-cms/.env)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  composeFromFields,
+  generateIdentifier,
+  validatePageBuilderHtml,
+} from './pageBuilder.js';
+import { MagentoClient, loadDotEnv } from './magentoClient.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+loadDotEnv();
+
+const SERVER_INFO = {
+  name: 'magento-cms',
+  version: '1.0.0',
+};
+
+// ---------------------------------------------------------------------------
+// JSON-RPC / MCP framing
+// ---------------------------------------------------------------------------
+
+let clientUsesContentLength = false;
+
+function sendMessage(msg) {
+  const json = JSON.stringify(msg);
+  if (clientUsesContentLength) {
+    const body = Buffer.from(json, 'utf8');
+    process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+    process.stdout.write(body);
+  } else {
+    process.stdout.write(json + '\n');
+  }
+}
+
+function sendResult(id, result) {
+  sendMessage({ jsonrpc: '2.0', id, result });
+}
+
+function sendError(id, code, message) {
+  sendMessage({
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  });
+}
+
+/** Tool result helpers (MCP content items) */
+function toolOk(data) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: typeof data === 'string' ? data : JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+function toolFail(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: 'text', text: `Error: ${message}` }],
+    isError: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Magento tools
+// ---------------------------------------------------------------------------
+
+function client() {
+  return MagentoClient.fromEnv();
+}
+
+function summarizeEntity(entity, type, editUrl) {
+  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"'),
+    admin_edit_url: editUrl,
+  };
+}
+
+const TOOLS = [
+  {
+    name: 'magento_health',
+    description:
+      'Check Magento REST connectivity and Integration token (reads CMS pages list).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'get_cms_page',
+    description: 'Get a Magento CMS page by page_id (numeric id).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_id: { type: 'number', description: 'CMS page ID, e.g. 8' },
+      },
+      required: ['page_id'],
+    },
+  },
+  {
+    name: 'create_cms_page',
+    description:
+      'Create a Magento CMS page with Page Builder content (Row → Text) from simple text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Page title' },
+        content: {
+          type: 'string',
+          description: 'Plain text or simple HTML body',
+        },
+        identifier: {
+          type: 'string',
+          description: 'URL key; auto from title if omitted',
+        },
+        headline: { type: 'string', description: 'Optional H2 above body' },
+        is_active: { type: 'boolean', description: 'Default true' },
+        page_layout: { type: 'string', description: 'Default 1column' },
+      },
+      required: ['title', 'content'],
+    },
+  },
+  {
+    name: 'update_cms_page',
+    description:
+      'Update an existing Magento CMS page by page_id. Rebuilds Page Builder Row → Text when content is provided.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_id: { type: 'number', description: 'CMS page ID to update' },
+        title: { type: 'string' },
+        content: { type: 'string' },
+        headline: { type: 'string' },
+        identifier: { type: 'string' },
+        is_active: { type: 'boolean' },
+        page_layout: { type: 'string' },
+      },
+      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.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+        content: { type: 'string' },
+        identifier: { type: 'string' },
+        headline: { type: 'string' },
+        is_active: { type: 'boolean' },
+      },
+      required: ['title', 'content'],
+    },
+  },
+  {
+    name: 'update_cms_block',
+    description:
+      'Update Magento CMS block by block_id. Rebuilds Page Builder when content is set.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        block_id: { type: 'number' },
+        title: { type: 'string' },
+        content: { type: 'string' },
+        headline: { type: 'string' },
+        identifier: { type: 'string' },
+        is_active: { type: 'boolean' },
+      },
+      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 callTool(name, args = {}) {
+  switch (name) {
+    case 'magento_health': {
+      const magento = client();
+      const result = await magento.health();
+      return toolOk({
+        ...result,
+        message: 'Magento REST OK. You can create/update CMS pages and blocks.',
+      });
+    }
+    case 'get_cms_page': {
+      const magento = client();
+      const page = await magento.getPage(args.page_id);
+      return toolOk(
+        summarizeEntity(page, 'page', magento.pageEditUrl(page.id || args.page_id))
+      );
+    }
+    case 'create_cms_page': {
+      const magento = client();
+      const identifier =
+        (args.identifier || '').trim() || generateIdentifier(args.title);
+      const pbHtml = composeFromFields({
+        content: args.content,
+        headline: args.headline,
+      });
+      if (!validatePageBuilderHtml(pbHtml)) {
+        throw new Error('Generated Page Builder HTML failed validation');
+      }
+      const page = await magento.createPage({
+        title: args.title,
+        identifier,
+        content: pbHtml,
+        content_heading: '',
+        page_layout: args.page_layout || '1column',
+        is_active: args.is_active !== false,
+        store_id: [0],
+        meta_title: args.title,
+        meta_description: '',
+      });
+      const id = page?.id ?? page?.page_id;
+      return toolOk({
+        result: 'created',
+        ...summarizeEntity(page, 'page', magento.pageEditUrl(id)),
+        full_content_length: pbHtml.length,
+      });
+    }
+    case 'update_cms_page': {
+      const magento = client();
+      const existing = await magento.getPage(args.page_id);
+      const title = (args.title || '').trim() || existing.title;
+      const identifier =
+        (args.identifier || '').trim() ||
+        existing.identifier ||
+        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');
+        }
+      }
+
+      const page = await magento.updatePage(args.page_id, {
+        title,
+        identifier,
+        content,
+        content_heading: existing.content_heading ?? '',
+        page_layout: args.page_layout || existing.page_layout || '1column',
+        is_active:
+          args.is_active !== undefined ? args.is_active : existing.is_active,
+        meta_title: existing.meta_title || title,
+        meta_description: existing.meta_description || '',
+        store_id: existing.store_id || [0],
+      });
+      const id = page?.id ?? args.page_id;
+      return toolOk({
+        result: 'updated',
+        ...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,
+      });
+      if (!validatePageBuilderHtml(pbHtml)) {
+        throw new Error('Generated Page Builder HTML failed validation');
+      }
+      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;
+      return toolOk({
+        result: 'created',
+        ...summarizeEntity(block, 'block', magento.blockEditUrl(id)),
+      });
+    }
+    case 'update_cms_block': {
+      const magento = client();
+      const existing = await magento.getBlock(args.block_id);
+      const title = (args.title || '').trim() || existing.title;
+      const identifier =
+        (args.identifier || '').trim() ||
+        existing.identifier ||
+        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');
+        }
+      }
+
+      const block = await magento.updateBlock(args.block_id, {
+        title,
+        identifier,
+        content,
+        is_active:
+          args.is_active !== undefined ? args.is_active : existing.is_active,
+        store_id: existing.store_id || [0],
+      });
+      const id = block?.id ?? args.block_id;
+      return toolOk({
+        result: 'updated',
+        ...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}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Request handlers
+// ---------------------------------------------------------------------------
+
+async function handleRequest(msg) {
+  const { id, method, params } = msg;
+
+  // Notifications have no id
+  if (id === undefined || id === null) {
+    if (method === 'notifications/initialized' || method === 'notifications/cancelled') {
+      return;
+    }
+    // ignore other notifications
+    return;
+  }
+
+  try {
+    switch (method) {
+      case 'initialize':
+        sendResult(id, {
+          protocolVersion: params?.protocolVersion || '2024-11-05',
+          capabilities: {
+            tools: {},
+          },
+          serverInfo: SERVER_INFO,
+        });
+        break;
+
+      case 'ping':
+        sendResult(id, {});
+        break;
+
+      case 'tools/list':
+        sendResult(id, { tools: TOOLS });
+        break;
+
+      case 'tools/call': {
+        const name = params?.name;
+        const args = params?.arguments || {};
+        try {
+          const result = await callTool(name, args);
+          sendResult(id, result);
+        } catch (e) {
+          sendResult(id, toolFail(e));
+        }
+        break;
+      }
+
+      default:
+        sendError(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (e) {
+    sendError(id, -32603, e instanceof Error ? e.message : String(e));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stdio reader (Content-Length framing)
+// ---------------------------------------------------------------------------
+
+let buffer = Buffer.alloc(0);
+
+process.stdin.on('data', (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  processBuffer();
+});
+
+process.stdin.on('error', (err) => {
+  console.error('stdin error', err);
+});
+
+function processBuffer() {
+  while (true) {
+    // Skip leading whitespace/newlines between messages
+    let start = 0;
+    while (
+      start < buffer.length &&
+      (buffer[start] === 0x0a || buffer[start] === 0x0d || buffer[start] === 0x20 || buffer[start] === 0x09)
+    ) {
+      start++;
+    }
+    if (start > 0) buffer = buffer.slice(start);
+    if (buffer.length === 0) return;
+
+    if (buffer[0] === 0x7b /* '{' */) {
+      // Newline-delimited JSON (standard MCP stdio, used by Cursor)
+      const nl = buffer.indexOf('\n');
+      if (nl === -1) return;
+      const line = buffer.slice(0, nl).toString('utf8').trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        void handleRequest(msg);
+      } catch (e) {
+        console.error('parse error', e);
+      }
+      continue;
+    }
+
+    // Content-Length framed (LSP-style) message
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) return;
+
+    const header = buffer.slice(0, headerEnd).toString('utf8');
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (!match) {
+      // Unrecognized header block; drop it to avoid an infinite loop
+      buffer = buffer.slice(headerEnd + 4);
+      continue;
+    }
+
+    const length = parseInt(match[1], 10);
+    const bodyStart = headerEnd + 4;
+    if (buffer.length < bodyStart + length) return;
+
+    const body = buffer.slice(bodyStart, bodyStart + length).toString('utf8');
+    buffer = buffer.slice(bodyStart + length);
+    clientUsesContentLength = true;
+
+    try {
+      const msg = JSON.parse(body);
+      void handleRequest(msg);
+    } catch (e) {
+      console.error('parse error', e);
+    }
+  }
+}
+
+// Keep process alive
+process.stdin.resume();
+
+// Log to stderr only (stdout is MCP protocol)
+console.error(`[magento-cms MCP] ready (base=${process.env.MAGENTO_BASE_URL || 'unset'})`);