mcp-magento-cms 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,14 @@
-# Magento CMS MCP (Cursor) — zero npm dependencies
+# Magento CMS MCP (Cursor)
 
-Create/update Magento **CMS Pages / Blocks** with Page Builder **Row → Text**.
+Create/update Magento **CMS Pages / Blocks** with Page Builder **Row → Text** from Cursor chat.
 
-- **AI:** your Cursor subscription (chat plans content)
-- **This server:** Magento REST only (Integration Access Token)
+- **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)
 
-Requires **Node 18+** only (`fetch` built-in). No `npm install` required.
+Requires **Node.js 18+** and [Cursor](https://cursor.com).
+
+Package: [npmjs.com/package/mcp-magento-cms](https://www.npmjs.com/package/mcp-magento-cms)
 
 ## Tools
 
@@ -14,113 +17,90 @@ Requires **Node 18+** only (`fetch` built-in). No `npm install` required.
 | `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` (e.g. 8) |
+| `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
-
-### 1. Magento Integration token
+| `list_section_types` | Supported layouts (MVP: `simple_text`) |
 
-Automated (recommended, ddev):
+## Setup (any machine)
 
-```bash
-ddev exec php tools/mcp-magento-cms/scripts/create-integration.php
-# prints ACCESS_TOKEN=... (idempotent; reuses the "MCP CMS Studio" integration)
-```
+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`.
 
-Or manually: Admin → **System → Extensions → Integrations** → Add New Integration →
-API tab: allow **CMS Pages/Blocks** and **Content → Design (save_design)** → Save → Activate → copy Access Token.
-
-Magento 2.4.4+ blocks integration tokens as bearer by default. Enable once:
-
-```bash
-ddev exec bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
-ddev exec bin/magento cache:flush config
-```
+### 1. Magento Integration Access Token
 
-### 2. Base URL (ddev)
+In Magento Admin:
 
-```bash
-ddev describe
-# e.g. https://mage248p3.ddev.site
-```
+1. **System → Extensions → Integrations → Add New Integration**
+2. Name it (e.g. `MCP CMS`)
+3. **API** tab: allow **CMS → Pages**, **CMS → Blocks**, and **Content → Design** (`save_design`) as needed
+4. **Save → Activate** → copy the **Access Token**
 
-### 3. Configure `.env`
+Magento **2.4.4+** blocks integration tokens as Bearer by default. Enable once on the Magento server:
 
 ```bash
-cd tools/mcp-magento-cms
-cp .env.example .env
-# set:
-# MAGENTO_BASE_URL=https://YOUR-PROJECT.ddev.site
-# MAGENTO_ACCESS_TOKEN=your_access_token
+bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
+bin/magento cache:flush config
 ```
 
-Test without Cursor (optional):
+(With ddev: prefix with `ddev exec`.)
 
-```bash
-# ddev uses a mkcert TLS cert that Node does not trust by default:
-export NODE_EXTRA_CA_CERTS="$HOME/.local/share/mkcert/rootCA.pem"
+### 2. Magento base URL
 
-# only works when Magento is up and token is set
-node scripts/health-check.js
+Use your storefront base URL **without** a trailing slash, for example:
 
-# full end-to-end: creates a real Page Builder CMS page and reads it back
-node scripts/smoke-e2e.js
-
-# local compose smoke test (no Magento):
-node scripts/test-compose.js
-```
+- Production: `https://www.example.com`
+- Local ddev: `https://your-project.ddev.site` (`ddev describe` shows the URL)
 
-### 4. Cursor MCP config
+### 3. Add the MCP in Cursor
 
-**Cursor → Settings → MCP**, or project file `.cursor/mcp.json`:
-
-Use **absolute** path to `index.js`:
+**Cursor → Settings → MCP → Edit Config**, or create `.cursor/mcp.json` in your project:
 
 ```json
 {
   "mcpServers": {
     "magento-cms": {
-      "command": "node",
-      "args": [
-        "/home/YOUR_USER/htdocs/mage248p3/tools/mcp-magento-cms/src/index.js"
-      ]
+      "command": "npx",
+      "args": ["-y", "mcp-magento-cms"],
+      "env": {
+        "MAGENTO_BASE_URL": "https://www.example.com",
+        "MAGENTO_ACCESS_TOKEN": "YOUR_INTEGRATION_ACCESS_TOKEN"
+      }
     }
   }
 }
 ```
 
-Secrets can stay in `.env` next to the server (auto-loaded). Or pass env:
+**Local ddev / mkcert only** — Node may not trust the local TLS cert. Add:
 
 ```json
-{
-  "mcpServers": {
-    "magento-cms": {
-      "command": "node",
-      "args": [
-        "/ABSOLUTE/PATH/tools/mcp-magento-cms/src/index.js"
-      ],
-      "env": {
-        "MAGENTO_BASE_URL": "https://mage248p3.ddev.site",
-        "MAGENTO_ACCESS_TOKEN": "YOUR_TOKEN"
-      }
-    }
-  }
-}
+"NODE_EXTRA_CA_CERTS": "/absolute/path/to/mkcert/rootCA.pem"
 ```
 
-See also `cursor-mcp.example.json`. Restart MCP / Cursor after changes.
+Typical Linux path: `$HOME/.local/share/mkcert/rootCA.pem`
+
+Optional env vars:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MAGENTO_STORE_CODE` | (empty) | REST store code |
+| `MAGENTO_ADMIN_PATH` | `admin` | Admin path used in edit links |
 
-## Prompts to try
+### 4. Restart MCP
+
+In Cursor MCP settings, refresh/restart the `magento-cms` server until it shows connected.
+
+### 5. Verify
+
+In Cursor chat:
 
 ```text
 Use magento_health to verify Magento.
 ```
 
+Then try:
+
 ```text
 Create a CMS page titled "MCP Demo" with this content:
-First paragraph from Google Docs.
+First paragraph.
 Second paragraph.
 ```
 
@@ -130,20 +110,19 @@ Update CMS page_id 8 with content: Updated body for page 8.
 
 ## Security
 
-- Do not commit `.env` or tokens
-- Integration token should only have CMS permissions
+- Put tokens only in `mcp.json` / Cursor env (do not commit them)
+- Give the Magento integration **CMS-only** permissions
 
-## Layout
+## Requirements
 
-```
-tools/mcp-magento-cms/
-  src/index.js                    MCP server (stdio)
-  src/magentoClient.js            REST client
-  src/pageBuilder.js              Row → Text HTML
-  .env.example
-  scripts/create-integration.php  Create integration + token (run via ddev exec)
-  scripts/health-check.js
-  scripts/smoke-e2e.js            End-to-end page creation test
-  scripts/test-compose.js
-  samples/                        Exported reference pages (Page Builder HTML)
+- 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`
+
+## For package maintainers
+
+Clone this repo to develop or republish. Bump `version` in `package.json`, then:
+
+```bash
+npm publish --access public
 ```

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "mcp-magento-cms",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Cursor MCP: Magento CMS pages/blocks with Page Builder Row→Text (zero npm deps)",
   "type": "module",
   "main": "src/index.js",
+  "bin": {
+    "mcp-magento-cms": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "start": "node src/index.js",
     "health": "node scripts/health-check.js",

package/.env.example

@@ -1,11 +0,0 @@
-# Magento (ddev or remote) — no trailing slash
-MAGENTO_BASE_URL=https://mage248p3.ddev.site
-
-# Integration Access Token from Admin → System → Integrations
-MAGENTO_ACCESS_TOKEN=
-
-# Optional store code for REST (default: all / empty uses /rest/V1)
-# MAGENTO_STORE_CODE=default
-
-# Optional admin path prefix for edit links (default: admin)
-# MAGENTO_ADMIN_PATH=admin

package/cursor-mcp.example.json

@@ -1,15 +0,0 @@
-{
-  "mcpServers": {
-    "magento-cms": {
-      "command": "node",
-      "args": [
-        "/home/ajaykumar.prajapati@brainvire.com/htdocs/mage248p3/tools/mcp-magento-cms/src/index.js"
-      ],
-      "env": {
-        "MAGENTO_BASE_URL": "https://mage248p3.ddev.site",
-        "MAGENTO_ACCESS_TOKEN": "REPLACE_WITH_INTEGRATION_ACCESS_TOKEN",
-        "NODE_EXTRA_CA_CERTS": "/home/ajaykumar.prajapati@brainvire.com/.local/share/mkcert/rootCA.pem"
-      }
-    }
-  }
-}