mcp-magento-cms 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +78 -75
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,11 +1,14 @@
1
- # Magento CMS MCP (Cursor) — zero npm dependencies
1
+ # Magento CMS MCP (Cursor)
2
2
 
3
- Create/update Magento **CMS Pages / Blocks** with Page Builder **Row → Text**.
3
+ Create/update Magento **CMS Pages / Blocks** with Page Builder **Row → Text** from Cursor chat.
4
4
 
5
- - **AI:** your Cursor subscription (chat plans content)
6
- - **This server:** Magento REST only (Integration Access Token)
5
+ - **AI:** Cursor plans the content
6
+ - **This server:** Magento REST via an Integration Access Token
7
+ - **Install:** `npx` (no local clone, no `tools/` folder, no `.env` file required)
7
8
 
8
- Requires **Node 18+** only (`fetch` built-in). No `npm install` required.
9
+ Requires **Node.js 18+** and [Cursor](https://cursor.com).
10
+
11
+ Package: [npmjs.com/package/mcp-magento-cms](https://www.npmjs.com/package/mcp-magento-cms)
9
12
 
10
13
  ## Tools
11
14
 
@@ -14,76 +17,58 @@ Requires **Node 18+** only (`fetch` built-in). No `npm install` required.
14
17
  | `magento_health` | Test base URL + token |
15
18
  | `get_cms_page` | Load by `page_id` |
16
19
  | `create_cms_page` | Create from title + content |
17
- | `update_cms_page` | Update by `page_id` (e.g. 8) |
20
+ | `update_cms_page` | Update by `page_id` |
18
21
  | `get_cms_block` / `create_cms_block` / `update_cms_block` | Blocks |
19
- | `list_section_types` | Supported layouts (MVP: simple_text) |
20
-
21
- ## Setup
22
+ | `list_section_types` | Supported layouts (MVP: `simple_text`) |
22
23
 
23
- ### 1. Magento Integration token
24
+ ## Setup (any machine)
24
25
 
25
- Automated (recommended, ddev):
26
+ 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`.
26
27
 
27
- ```bash
28
- ddev exec php tools/mcp-magento-cms/scripts/create-integration.php
29
- # prints ACCESS_TOKEN=... (idempotent; reuses the "MCP CMS Studio" integration)
30
- ```
28
+ ### 1. Magento Integration Access Token
31
29
 
32
- Or manually: Admin → **System → Extensions → Integrations** → Add New Integration →
33
- API tab: allow **CMS Pages/Blocks** and **Content → Design (save_design)** → Save → Activate → copy Access Token.
30
+ No clone or `tools/` folder is needed. Create the token in Magento Admin:
34
31
 
35
- Magento 2.4.4+ blocks integration tokens as bearer by default. Enable once:
32
+ 1. **System → Extensions → Integrations → Add New Integration**
33
+ 2. Name it (e.g. `MCP CMS`) and set your admin password when prompted
34
+ 3. Open the **API** tab → set **Resource Access** to **Custom**
35
+ 4. Under **Content → Elements**, select:
36
36
 
37
- ```bash
38
- ddev exec bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
39
- ddev exec bin/magento cache:flush config
40
- ```
37
+ | Select | Notes |
38
+ |--------|--------|
39
+ | **Pages** | Required (parent) |
40
+ | → **Save Page** | Create / update pages |
41
+ | → **Edit Page Design** | Page Builder / design fields |
42
+ | → **Delete Page** | Optional (MCP does not delete today) |
43
+ | **Blocks** | Required (create / update blocks) |
41
44
 
42
- ### 2. Base URL (ddev)
45
+ Leave everything else unchecked (Staging, Widgets, Media Gallery, Amasty, Blog, Design Themes, etc.).
43
46
 
44
- ```bash
45
- ddev describe
46
- # e.g. https://mage248p3.ddev.site
47
- ```
47
+ 5. **Save → Activate** → copy the **Access Token** into `mcp.json` (step 3)
48
48
 
49
- ### 3. Configure `.env`
49
+ Magento **2.4.4+** blocks integration tokens as Bearer by default. Enable once (either way):
50
50
 
51
- ```bash
52
- cd tools/mcp-magento-cms
53
- cp .env.example .env
54
- # set:
55
- # MAGENTO_BASE_URL=https://YOUR-PROJECT.ddev.site
56
- # MAGENTO_ACCESS_TOKEN=your_access_token
57
- ```
51
+ **Admin UI:** **Stores → Configuration → Services → OAuth → Consumer Settings** → set **Allow OAuth Access Tokens to be used as standalone Bearer tokens** to **Yes** → Save Config.
58
52
 
59
- Test without Cursor (optional):
53
+ **CLI:**
60
54
 
61
55
  ```bash
62
- # ddev uses a mkcert TLS cert that Node does not trust by default:
63
- export NODE_EXTRA_CA_CERTS="$HOME/.local/share/mkcert/rootCA.pem"
64
-
65
- # only works when Magento is up and token is set
66
- node scripts/health-check.js
67
-
68
- # full end-to-end: creates a real Page Builder CMS page and reads it back
69
- node scripts/smoke-e2e.js
70
-
71
- # local compose smoke test (no Magento):
72
- node scripts/test-compose.js
56
+ bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
57
+ bin/magento cache:flush config
73
58
  ```
74
59
 
75
- ### 4. Publish to npm (once)
60
+ (With ddev: prefix CLI with `ddev exec`.)
76
61
 
77
- ```bash
78
- npm login
79
- npm publish --access public
80
- ```
62
+ ### 2. Magento base URL
81
63
 
82
- Bump `version` in `package.json` before each later publish.
64
+ Use your storefront base URL **without** a trailing slash, for example:
83
65
 
84
- ### 5. Cursor MCP config
66
+ - Production: `https://www.example.com`
67
+ - Local ddev: `https://your-project.ddev.site` (`ddev describe` shows the URL)
85
68
 
86
- **Cursor → Settings → MCP**, or project file `.cursor/mcp.json`:
69
+ ### 3. Add the MCP in Cursor
70
+
71
+ **Cursor → Settings → MCP → Edit Config**, or create `.cursor/mcp.json` in your project:
87
72
 
88
73
  ```json
89
74
  {
@@ -92,27 +77,46 @@ Bump `version` in `package.json` before each later publish.
92
77
  "command": "npx",
93
78
  "args": ["-y", "mcp-magento-cms"],
94
79
  "env": {
95
- "MAGENTO_BASE_URL": "https://mage248p3.ddev.site",
96
- "MAGENTO_ACCESS_TOKEN": "YOUR_TOKEN"
80
+ "MAGENTO_BASE_URL": "https://www.example.com",
81
+ "MAGENTO_ACCESS_TOKEN": "YOUR_INTEGRATION_ACCESS_TOKEN"
97
82
  }
98
83
  }
99
84
  }
100
85
  }
101
86
  ```
102
87
 
103
- For ddev + mkcert, also set `NODE_EXTRA_CA_CERTS` to your mkcert root CA path.
88
+ **Local ddev / mkcert only** — Node may not trust the local TLS cert. Add:
89
+
90
+ ```json
91
+ "NODE_EXTRA_CA_CERTS": "/absolute/path/to/mkcert/rootCA.pem"
92
+ ```
93
+
94
+ Typical Linux path: `$HOME/.local/share/mkcert/rootCA.pem`
95
+
96
+ Optional env vars:
97
+
98
+ | Variable | Default | Purpose |
99
+ |----------|---------|---------|
100
+ | `MAGENTO_STORE_CODE` | (empty) | REST store code |
101
+ | `MAGENTO_ADMIN_PATH` | `admin` | Admin path used in edit links |
102
+
103
+ ### 4. Restart MCP
104
104
 
105
- See also `cursor-mcp.example.json`. Restart MCP / Cursor after changes.
105
+ In Cursor MCP settings, refresh/restart the `magento-cms` server until it shows connected.
106
106
 
107
- ## Prompts to try
107
+ ### 5. Verify
108
+
109
+ In Cursor chat:
108
110
 
109
111
  ```text
110
112
  Use magento_health to verify Magento.
111
113
  ```
112
114
 
115
+ Then try:
116
+
113
117
  ```text
114
118
  Create a CMS page titled "MCP Demo" with this content:
115
- First paragraph from Google Docs.
119
+ First paragraph.
116
120
  Second paragraph.
117
121
  ```
118
122
 
@@ -122,20 +126,19 @@ Update CMS page_id 8 with content: Updated body for page 8.
122
126
 
123
127
  ## Security
124
128
 
125
- - Do not commit `.env` or tokens
126
- - Integration token should only have CMS permissions
129
+ - Put tokens only in `mcp.json` / Cursor env (do not commit them)
130
+ - Give the Magento integration **CMS-only** permissions
127
131
 
128
- ## Layout
132
+ ## Requirements
129
133
 
130
- ```
131
- tools/mcp-magento-cms/
132
- src/index.js MCP server (stdio)
133
- src/magentoClient.js REST client
134
- src/pageBuilder.js Row → Text HTML
135
- .env.example
136
- scripts/create-integration.php Create integration + token (run via ddev exec)
137
- scripts/health-check.js
138
- scripts/smoke-e2e.js End-to-end page creation test
139
- scripts/test-compose.js
140
- samples/ Exported reference pages (Page Builder HTML)
134
+ - Node.js **18+** on the machine running Cursor
135
+ - Magento 2 with REST and an Integration token
136
+ - Network access from that machine to `MAGENTO_BASE_URL`
137
+
138
+ ## For package maintainers
139
+
140
+ Clone this repo to develop or republish. Bump `version` in `package.json`, then:
141
+
142
+ ```bash
143
+ npm publish --access public
141
144
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-magento-cms",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "description": "Cursor MCP: Magento CMS pages/blocks with Page Builder Row→Text (zero npm deps)",
5
5
  "type": "module",
6
6
  "main": "src/index.js",