mcp-magento-cms 1.0.1 → 1.0.2

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 +66 -79
  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,42 @@ 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
-
23
- ### 1. Magento Integration token
22
+ | `list_section_types` | Supported layouts (MVP: `simple_text`) |
24
23
 
25
- Automated (recommended, ddev):
24
+ ## Setup (any machine)
26
25
 
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
- ```
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`.
31
27
 
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.
34
-
35
- Magento 2.4.4+ blocks integration tokens as bearer by default. Enable once:
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
- ```
28
+ ### 1. Magento Integration Access Token
41
29
 
42
- ### 2. Base URL (ddev)
30
+ In Magento Admin:
43
31
 
44
- ```bash
45
- ddev describe
46
- # e.g. https://mage248p3.ddev.site
47
- ```
32
+ 1. **System → Extensions → Integrations → Add New Integration**
33
+ 2. Name it (e.g. `MCP CMS`)
34
+ 3. **API** tab: allow **CMS → Pages**, **CMS → Blocks**, and **Content → Design** (`save_design`) as needed
35
+ 4. **Save → Activate** → copy the **Access Token**
48
36
 
49
- ### 3. Configure `.env`
37
+ Magento **2.4.4+** blocks integration tokens as Bearer by default. Enable once on the Magento server:
50
38
 
51
39
  ```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
40
+ bin/magento config:set oauth/consumer/enable_integration_as_bearer 1
41
+ bin/magento cache:flush config
57
42
  ```
58
43
 
59
- Test without Cursor (optional):
44
+ (With ddev: prefix with `ddev exec`.)
60
45
 
61
- ```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"
46
+ ### 2. Magento base URL
64
47
 
65
- # only works when Magento is up and token is set
66
- node scripts/health-check.js
48
+ Use your storefront base URL **without** a trailing slash, for example:
67
49
 
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
73
- ```
50
+ - Production: `https://www.example.com`
51
+ - Local ddev: `https://your-project.ddev.site` (`ddev describe` shows the URL)
74
52
 
75
- ### 4. Publish to npm (once)
76
-
77
- ```bash
78
- npm login
79
- npm publish --access public
80
- ```
53
+ ### 3. Add the MCP in Cursor
81
54
 
82
- Bump `version` in `package.json` before each later publish.
83
-
84
- ### 5. Cursor MCP config
85
-
86
- **Cursor → Settings → MCP**, or project file `.cursor/mcp.json`:
55
+ **Cursor → Settings → MCP → Edit Config**, or create `.cursor/mcp.json` in your project:
87
56
 
88
57
  ```json
89
58
  {
@@ -92,27 +61,46 @@ Bump `version` in `package.json` before each later publish.
92
61
  "command": "npx",
93
62
  "args": ["-y", "mcp-magento-cms"],
94
63
  "env": {
95
- "MAGENTO_BASE_URL": "https://mage248p3.ddev.site",
96
- "MAGENTO_ACCESS_TOKEN": "YOUR_TOKEN"
64
+ "MAGENTO_BASE_URL": "https://www.example.com",
65
+ "MAGENTO_ACCESS_TOKEN": "YOUR_INTEGRATION_ACCESS_TOKEN"
97
66
  }
98
67
  }
99
68
  }
100
69
  }
101
70
  ```
102
71
 
103
- For ddev + mkcert, also set `NODE_EXTRA_CA_CERTS` to your mkcert root CA path.
72
+ **Local ddev / mkcert only** — Node may not trust the local TLS cert. Add:
73
+
74
+ ```json
75
+ "NODE_EXTRA_CA_CERTS": "/absolute/path/to/mkcert/rootCA.pem"
76
+ ```
77
+
78
+ Typical Linux path: `$HOME/.local/share/mkcert/rootCA.pem`
79
+
80
+ Optional env vars:
81
+
82
+ | Variable | Default | Purpose |
83
+ |----------|---------|---------|
84
+ | `MAGENTO_STORE_CODE` | (empty) | REST store code |
85
+ | `MAGENTO_ADMIN_PATH` | `admin` | Admin path used in edit links |
86
+
87
+ ### 4. Restart MCP
104
88
 
105
- See also `cursor-mcp.example.json`. Restart MCP / Cursor after changes.
89
+ In Cursor MCP settings, refresh/restart the `magento-cms` server until it shows connected.
106
90
 
107
- ## Prompts to try
91
+ ### 5. Verify
92
+
93
+ In Cursor chat:
108
94
 
109
95
  ```text
110
96
  Use magento_health to verify Magento.
111
97
  ```
112
98
 
99
+ Then try:
100
+
113
101
  ```text
114
102
  Create a CMS page titled "MCP Demo" with this content:
115
- First paragraph from Google Docs.
103
+ First paragraph.
116
104
  Second paragraph.
117
105
  ```
118
106
 
@@ -122,20 +110,19 @@ Update CMS page_id 8 with content: Updated body for page 8.
122
110
 
123
111
  ## Security
124
112
 
125
- - Do not commit `.env` or tokens
126
- - Integration token should only have CMS permissions
113
+ - Put tokens only in `mcp.json` / Cursor env (do not commit them)
114
+ - Give the Magento integration **CMS-only** permissions
127
115
 
128
- ## Layout
116
+ ## Requirements
129
117
 
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)
118
+ - Node.js **18+** on the machine running Cursor
119
+ - Magento 2 with REST and an Integration token
120
+ - Network access from that machine to `MAGENTO_BASE_URL`
121
+
122
+ ## For package maintainers
123
+
124
+ Clone this repo to develop or republish. Bump `version` in `package.json`, then:
125
+
126
+ ```bash
127
+ npm publish --access public
141
128
  ```
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.2",
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",