@upassist/neos-mcp 1.0.0 → 2.1.0
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.
- package/CHANGELOG.md +22 -0
- package/README.md +37 -0
- package/dist/index.js +149 -42
- package/package.json +8 -6
- package/src/bridge.ts +69 -3
- package/src/server.ts +2 -0
- package/src/tools/createContentNode.ts +6 -6
- package/src/tools/createDocumentNode.ts +8 -8
- package/src/tools/deleteNode.ts +4 -4
- package/src/tools/getDocumentProperties.ts +5 -5
- package/src/tools/getPageContent.ts +4 -4
- package/src/tools/getPreviewUrl.ts +4 -4
- package/src/tools/getSiteContext.ts +11 -3
- package/src/tools/moveNode.ts +11 -11
- package/src/tools/updateNodeProperty.ts +5 -5
- package/src/tools/uploadAsset.ts +74 -0
- package/src/types.ts +19 -10
- package/test/support/env.ts +3 -0
- package/test/uploadAsset.test.ts +144 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,28 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
|
|
4
4
|
|
|
5
|
+
## [2.1.0](https://github.com/UpAssist/neos-mcp-client/compare/2.0.2...2.1.0) (2026-10-08)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
|
|
10
|
+
* add neos_upload_asset tool ([0870e67](https://github.com/UpAssist/neos-mcp-client/commit/0870e6756da461b051fa51c50a6dea41faddead6))
|
|
11
|
+
|
|
12
|
+
### [2.0.2](https://github.com/UpAssist/neos-mcp-client/compare/2.0.1...2.0.2) (2026-09-23)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
### Bug Fixes
|
|
16
|
+
|
|
17
|
+
* send X-MCP-Token and explicit Content-Length headers to bridge ([94db801](https://github.com/UpAssist/neos-mcp-client/commit/94db8017e0e8d3943dcddcf331af629ea25ff8cf))
|
|
18
|
+
|
|
19
|
+
### [2.0.1](https://github.com/UpAssist/neos-mcp-client/compare/2.0.0...2.0.1) (2026-04-16)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### Bug Fixes
|
|
23
|
+
|
|
24
|
+
* lazily auto-detect API version to survive server restarts ([c3e4a4a](https://github.com/UpAssist/neos-mcp-client/commit/c3e4a4a2ae598ed700a5eae84ecc5473729b9b2d))
|
|
25
|
+
* remove pretty-printing from getSiteContext to reduce token usage ([96d57db](https://github.com/UpAssist/neos-mcp-client/commit/96d57db5abd14112d4178eb7690720981493f5aa))
|
|
26
|
+
|
|
5
27
|
## 0.2.0 (2026-03-25)
|
|
6
28
|
|
|
7
29
|
|
package/README.md
CHANGED
|
@@ -4,6 +4,17 @@
|
|
|
4
4
|
|
|
5
5
|
This is the client-side component. It runs locally on your machine and translates MCP tool calls into HTTP requests to the [UpAssist.Neos.Mcp](https://github.com/UpAssist/neos-mcp) bridge running inside your Neos installation.
|
|
6
6
|
|
|
7
|
+
## Compatibility
|
|
8
|
+
|
|
9
|
+
| MCP Server version | Bridge version | Neos CMS | Node.js |
|
|
10
|
+
|-------------------|------------------------|----------|---------|
|
|
11
|
+
| 2.x (`main`) | upassist/neos-mcp 1.x or 2.x | 8.3+ / 9.0+ | 18+ |
|
|
12
|
+
| 1.x (`neos-8`) | upassist/neos-mcp 1.x | 8.3+ | 18+ |
|
|
13
|
+
|
|
14
|
+
> **v2 auto-detects** the bridge API version. A single MCP server v2 works with both Neos 8 and Neos 9 bridges.
|
|
15
|
+
|
|
16
|
+
> **`neos_upload_asset`** (client 2.1+) needs a bridge with the `uploadAsset` endpoint: upassist/neos-mcp **2.1+** (Neos 9) or **1.1+** (Neos 8). Against an older bridge the other tools keep working and the upload call fails with a 404.
|
|
17
|
+
|
|
7
18
|
## Requirements
|
|
8
19
|
|
|
9
20
|
- Node.js 18+
|
|
@@ -139,6 +150,25 @@ Once connected, your AI assistant can use these tools:
|
|
|
139
150
|
| --- | --- |
|
|
140
151
|
| `neos_list_assets` | Browse images and files from the Media Manager |
|
|
141
152
|
| `neos_list_asset_tags` | List available asset tags |
|
|
153
|
+
| `neos_upload_asset` | Upload a file (local path, URL or base64) to the Media Manager, incl. title, caption, tags and collections. Identical files are deduplicated. |
|
|
154
|
+
|
|
155
|
+
#### Uploading files
|
|
156
|
+
|
|
157
|
+
`neos_upload_asset` takes exactly one source:
|
|
158
|
+
|
|
159
|
+
| Parameter | Description |
|
|
160
|
+
| --- | --- |
|
|
161
|
+
| `file_path` | Absolute path of a local file, read by this MCP server |
|
|
162
|
+
| `url` | HTTP(S) URL, downloaded by this MCP server (the Neos bridge never fetches remote URLs) |
|
|
163
|
+
| `base64_content` | Raw base64 content (a `data:` URI prefix is allowed); requires `filename` |
|
|
164
|
+
|
|
165
|
+
Optional: `filename` (overrides the name taken from the path or URL), `title`, `caption`, `copyright_notice`, `tags`, `asset_collections` (missing tags and collections are created) and `allow_duplicate`.
|
|
166
|
+
|
|
167
|
+
- The result contains the asset `identifier`, which you can pass to `neos_update_node_property` (or the create tools) for image/asset properties.
|
|
168
|
+
- If a file with identical content already exists, that asset is returned with `duplicate: true` and the title, caption, tags and collections you passed are **not** applied to it. Set `allow_duplicate` to force a new asset.
|
|
169
|
+
- The file travels as base64 in one request, so it is about 33% larger on the wire. The size limit is set by the bridge's PHP (`post_max_size`) and web server configuration. Large files are better added through the Media Manager.
|
|
170
|
+
- Requires a bridge that has the `uploadAsset` endpoint (see the [bridge README](https://github.com/UpAssist/neos-mcp#post-neosmcpuploadasset)). It works with both the Neos 8 and the Neos 9 bridge.
|
|
171
|
+
- A rejected token comes back as a bridge error `401` or `403`.
|
|
142
172
|
|
|
143
173
|
### Review and publish
|
|
144
174
|
|
|
@@ -195,6 +225,9 @@ npm run dev
|
|
|
195
225
|
# Type check
|
|
196
226
|
npm run typecheck
|
|
197
227
|
|
|
228
|
+
# Run the unit tests
|
|
229
|
+
npm test
|
|
230
|
+
|
|
198
231
|
# Build for production
|
|
199
232
|
npm run build
|
|
200
233
|
|
|
@@ -202,6 +235,10 @@ npm run build
|
|
|
202
235
|
npm start
|
|
203
236
|
```
|
|
204
237
|
|
|
238
|
+
### Tests
|
|
239
|
+
|
|
240
|
+
`npm test` bundles `test/*.test.ts` with esbuild and runs them with Node's built-in test runner. The tests start the real MCP server in-process (via the SDK's in-memory transport) and replace `fetch`, so they check the exact HTTP requests sent to the bridge without needing a Neos instance. For a true end-to-end check, point `NEOS_MCP_URL` at a Neos instance with the bridge installed and call the tool through any MCP client.
|
|
241
|
+
|
|
205
242
|
### Adding a new tool
|
|
206
243
|
|
|
207
244
|
1. Create a file in `src/tools/` (e.g. `myNewTool.ts`)
|
package/dist/index.js
CHANGED
|
@@ -20989,12 +20989,50 @@ var EMPTY_COMPLETION_RESULT = {
|
|
|
20989
20989
|
// src/bridge.ts
|
|
20990
20990
|
var BASE_URL = (process.env.NEOS_MCP_URL ?? "http://localhost:8081").replace(/\/$/, "");
|
|
20991
20991
|
var TOKEN = process.env.NEOS_MCP_TOKEN ?? "";
|
|
20992
|
-
|
|
20993
|
-
|
|
20992
|
+
var detectedApiVersion = null;
|
|
20993
|
+
var versionDetectionPromise = null;
|
|
20994
|
+
function setApiVersion(version2) {
|
|
20995
|
+
detectedApiVersion = version2;
|
|
20996
|
+
}
|
|
20997
|
+
async function ensureApiVersion() {
|
|
20998
|
+
if (detectedApiVersion !== null) return;
|
|
20999
|
+
if (versionDetectionPromise) return versionDetectionPromise;
|
|
21000
|
+
versionDetectionPromise = (async () => {
|
|
21001
|
+
try {
|
|
21002
|
+
const data = await callBridge("getSiteContext", "GET");
|
|
21003
|
+
detectedApiVersion = data && data.apiVersion === 2 ? 2 : 1;
|
|
21004
|
+
} catch {
|
|
21005
|
+
detectedApiVersion = 1;
|
|
21006
|
+
} finally {
|
|
21007
|
+
versionDetectionPromise = null;
|
|
21008
|
+
}
|
|
21009
|
+
})();
|
|
21010
|
+
return versionDetectionPromise;
|
|
21011
|
+
}
|
|
21012
|
+
async function nodeIdParam(key, nodeId) {
|
|
21013
|
+
await ensureApiVersion();
|
|
21014
|
+
if (detectedApiVersion === 2) {
|
|
21015
|
+
const v2Keys = {
|
|
21016
|
+
nodePath: "nodeAggregateId",
|
|
21017
|
+
contextPath: "nodeAggregateId",
|
|
21018
|
+
parentPath: "parentNodeAggregateId",
|
|
21019
|
+
newParentPath: "newParentId"
|
|
21020
|
+
};
|
|
21021
|
+
return { [v2Keys[key]]: nodeId };
|
|
21022
|
+
}
|
|
21023
|
+
return { [key]: nodeId };
|
|
21024
|
+
}
|
|
21025
|
+
function getHeaders(body) {
|
|
21026
|
+
const headers = {
|
|
20994
21027
|
"Authorization": `Bearer ${TOKEN}`,
|
|
21028
|
+
"X-MCP-Token": TOKEN,
|
|
20995
21029
|
"Content-Type": "application/json",
|
|
20996
21030
|
"Accept": "application/json"
|
|
20997
21031
|
};
|
|
21032
|
+
if (body !== void 0) {
|
|
21033
|
+
headers["Content-Length"] = String(Buffer.byteLength(body, "utf8"));
|
|
21034
|
+
}
|
|
21035
|
+
return headers;
|
|
20998
21036
|
}
|
|
20999
21037
|
async function callBridge(action, method, params = {}) {
|
|
21000
21038
|
let url = `${BASE_URL}/neos/mcp/${action}`;
|
|
@@ -21007,7 +21045,7 @@ async function callBridge(action, method, params = {}) {
|
|
|
21007
21045
|
}
|
|
21008
21046
|
const response = await fetch(url, {
|
|
21009
21047
|
method,
|
|
21010
|
-
headers: getHeaders(),
|
|
21048
|
+
headers: getHeaders(body),
|
|
21011
21049
|
body
|
|
21012
21050
|
});
|
|
21013
21051
|
const text = await response.text();
|
|
@@ -21032,7 +21070,12 @@ function registerGetSiteContext(server) {
|
|
|
21032
21070
|
{},
|
|
21033
21071
|
async () => {
|
|
21034
21072
|
const data = await callBridge("getSiteContext", "GET");
|
|
21035
|
-
|
|
21073
|
+
if (data && typeof data === "object" && "apiVersion" in data && data.apiVersion === 2) {
|
|
21074
|
+
setApiVersion(2);
|
|
21075
|
+
} else {
|
|
21076
|
+
setApiVersion(1);
|
|
21077
|
+
}
|
|
21078
|
+
return { content: [{ type: "text", text: JSON.stringify(data) }] };
|
|
21036
21079
|
}
|
|
21037
21080
|
);
|
|
21038
21081
|
}
|
|
@@ -21071,11 +21114,11 @@ function registerGetPageContent(server) {
|
|
|
21071
21114
|
"neos_get_page_content",
|
|
21072
21115
|
"Get all content nodes on a specific page with their properties. Call neos_get_site_context first if you have not already done so this session.",
|
|
21073
21116
|
{
|
|
21074
|
-
|
|
21117
|
+
node_id: external_exports.string().describe("Node identifier \u2014 use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_get_site_context / neos_list_pages"),
|
|
21075
21118
|
workspace: external_exports.string().default("mcp").describe("Workspace name")
|
|
21076
21119
|
},
|
|
21077
|
-
async ({
|
|
21078
|
-
const data = await callBridge("getPageContent", "GET", { nodePath
|
|
21120
|
+
async ({ node_id, workspace }) => {
|
|
21121
|
+
const data = await callBridge("getPageContent", "GET", { ...await nodeIdParam("nodePath", node_id), workspace });
|
|
21079
21122
|
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
21080
21123
|
}
|
|
21081
21124
|
);
|
|
@@ -21087,11 +21130,11 @@ function registerGetDocumentProperties(server) {
|
|
|
21087
21130
|
"neos_get_document_properties",
|
|
21088
21131
|
"Get all properties of a document node (page) without its content nodes. Use this for SEO fields, meta data, and other document-level properties.",
|
|
21089
21132
|
{
|
|
21090
|
-
|
|
21133
|
+
node_id: external_exports.string().describe("Node identifier \u2014 use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_get_site_context / neos_list_pages"),
|
|
21091
21134
|
workspace: external_exports.string().default("mcp").describe('Workspace name. Use "live" for published content, "mcp" for staged changes.')
|
|
21092
21135
|
},
|
|
21093
|
-
async ({
|
|
21094
|
-
const data = await callBridge("getDocumentProperties", "GET", { nodePath
|
|
21136
|
+
async ({ node_id, workspace }) => {
|
|
21137
|
+
const data = await callBridge("getDocumentProperties", "GET", { ...await nodeIdParam("nodePath", node_id), workspace });
|
|
21095
21138
|
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
21096
21139
|
}
|
|
21097
21140
|
);
|
|
@@ -21135,11 +21178,11 @@ function registerGetPreviewUrl(server) {
|
|
|
21135
21178
|
"neos_get_preview_url",
|
|
21136
21179
|
"Generate a time-limited public preview URL for a page in the MCP workspace. The URL can be opened in any browser without logging into Neos \u2014 valid for 24 hours.",
|
|
21137
21180
|
{
|
|
21138
|
-
|
|
21181
|
+
node_id: external_exports.string().describe("Node identifier \u2014 use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_list_pages"),
|
|
21139
21182
|
workspace: external_exports.string().default("mcp").describe("Workspace to preview")
|
|
21140
21183
|
},
|
|
21141
|
-
async ({
|
|
21142
|
-
const data = await callBridge("getPreviewUrl", "GET", { nodePath
|
|
21184
|
+
async ({ node_id, workspace }) => {
|
|
21185
|
+
const data = await callBridge("getPreviewUrl", "GET", { ...await nodeIdParam("nodePath", node_id), workspace });
|
|
21143
21186
|
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
21144
21187
|
}
|
|
21145
21188
|
);
|
|
@@ -21151,20 +21194,20 @@ function registerCreateContentNode(server) {
|
|
|
21151
21194
|
"neos_create_content_node",
|
|
21152
21195
|
"Create a new content element inside a page's content collection. Call neos_get_site_context first if you have not already done so this session. Always writes to the mcp workspace.",
|
|
21153
21196
|
{
|
|
21154
|
-
|
|
21155
|
-
"
|
|
21197
|
+
parent_id: external_exports.string().describe(
|
|
21198
|
+
"Parent node identifier \u2014 the content collection to add to. Use nodeAggregateId (Neos 9) or path (Neos 8)."
|
|
21156
21199
|
),
|
|
21157
21200
|
node_type: external_exports.string().describe(
|
|
21158
|
-
"Node type name, e.g. UpAssist.
|
|
21201
|
+
"Node type name, e.g. UpAssist.Site:Content.Headline"
|
|
21159
21202
|
),
|
|
21160
21203
|
properties: external_exports.record(external_exports.unknown()).default({}).describe(
|
|
21161
21204
|
"Property key-value pairs to set on the new node. Use neos_list_node_types to see available properties."
|
|
21162
21205
|
),
|
|
21163
21206
|
workspace: external_exports.string().default("mcp").describe("Draft workspace name")
|
|
21164
21207
|
},
|
|
21165
|
-
async ({
|
|
21208
|
+
async ({ parent_id, node_type, properties, workspace }) => {
|
|
21166
21209
|
const data = await callBridge("createContentNode", "POST", {
|
|
21167
|
-
parentPath
|
|
21210
|
+
...await nodeIdParam("parentPath", parent_id),
|
|
21168
21211
|
nodeType: node_type,
|
|
21169
21212
|
properties,
|
|
21170
21213
|
workspace
|
|
@@ -21180,16 +21223,16 @@ function registerUpdateNodeProperty(server) {
|
|
|
21180
21223
|
"neos_update_node_property",
|
|
21181
21224
|
"Update a single property on an existing content node. Call neos_get_site_context first if you have not already done so this session. Always writes to the mcp workspace.",
|
|
21182
21225
|
{
|
|
21183
|
-
|
|
21184
|
-
"
|
|
21226
|
+
node_id: external_exports.string().describe(
|
|
21227
|
+
"Node identifier \u2014 use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)"
|
|
21185
21228
|
),
|
|
21186
21229
|
property: external_exports.string().describe("Property name to update"),
|
|
21187
21230
|
value: external_exports.unknown().describe("New property value (string, number, boolean, or object)"),
|
|
21188
21231
|
workspace: external_exports.string().default("mcp").describe("Workspace to write to")
|
|
21189
21232
|
},
|
|
21190
|
-
async ({
|
|
21233
|
+
async ({ node_id, property, value, workspace }) => {
|
|
21191
21234
|
const data = await callBridge("updateNodeProperty", "POST", {
|
|
21192
|
-
contextPath
|
|
21235
|
+
...await nodeIdParam("contextPath", node_id),
|
|
21193
21236
|
property,
|
|
21194
21237
|
value,
|
|
21195
21238
|
workspace
|
|
@@ -21205,12 +21248,12 @@ function registerDeleteNode(server) {
|
|
|
21205
21248
|
"neos_delete_node",
|
|
21206
21249
|
"Mark a content node as removed in the mcp workspace. The deletion is staged and will only go live after neos_publish_changes is called.",
|
|
21207
21250
|
{
|
|
21208
|
-
|
|
21251
|
+
node_id: external_exports.string().describe("Node identifier \u2014 use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)"),
|
|
21209
21252
|
workspace: external_exports.string().default("mcp").describe("Workspace to operate in")
|
|
21210
21253
|
},
|
|
21211
|
-
async ({
|
|
21254
|
+
async ({ node_id, workspace }) => {
|
|
21212
21255
|
const data = await callBridge("deleteNode", "POST", {
|
|
21213
|
-
contextPath
|
|
21256
|
+
...await nodeIdParam("contextPath", node_id),
|
|
21214
21257
|
workspace
|
|
21215
21258
|
});
|
|
21216
21259
|
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
@@ -21239,11 +21282,11 @@ function registerCreateDocumentNode(server) {
|
|
|
21239
21282
|
"neos_create_document_node",
|
|
21240
21283
|
"Create a new page (document node) as a child of a parent page. Call neos_get_site_context first to see available document NodeTypes and the page tree. Always writes to the mcp workspace.",
|
|
21241
21284
|
{
|
|
21242
|
-
|
|
21243
|
-
"
|
|
21285
|
+
parent_id: external_exports.string().describe(
|
|
21286
|
+
"Parent node identifier \u2014 use nodeAggregateId (Neos 9) or path (Neos 8)."
|
|
21244
21287
|
),
|
|
21245
21288
|
node_type: external_exports.string().describe(
|
|
21246
|
-
"Document node type name, e.g. UpAssist.
|
|
21289
|
+
"Document node type name, e.g. UpAssist.Site:Document.Page"
|
|
21247
21290
|
),
|
|
21248
21291
|
properties: external_exports.record(external_exports.unknown()).default({}).describe(
|
|
21249
21292
|
'Property key-value pairs, e.g. { title: "About us", uriPathSegment: "about-us" }'
|
|
@@ -21253,15 +21296,15 @@ function registerCreateDocumentNode(server) {
|
|
|
21253
21296
|
"URL slug used as the node name (auto-generated from nodeType if omitted)"
|
|
21254
21297
|
),
|
|
21255
21298
|
insert_before: external_exports.string().optional().describe(
|
|
21256
|
-
"
|
|
21299
|
+
"Sibling node identifier \u2014 insert the new page before this sibling"
|
|
21257
21300
|
),
|
|
21258
21301
|
insert_after: external_exports.string().optional().describe(
|
|
21259
|
-
"
|
|
21302
|
+
"Sibling node identifier \u2014 insert the new page after this sibling"
|
|
21260
21303
|
)
|
|
21261
21304
|
},
|
|
21262
|
-
async ({
|
|
21305
|
+
async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
|
|
21263
21306
|
const data = await callBridge("createDocumentNode", "POST", {
|
|
21264
|
-
parentPath
|
|
21307
|
+
...await nodeIdParam("parentPath", parent_id),
|
|
21265
21308
|
nodeType: node_type,
|
|
21266
21309
|
properties,
|
|
21267
21310
|
workspace,
|
|
@@ -21278,28 +21321,28 @@ function registerCreateDocumentNode(server) {
|
|
|
21278
21321
|
function registerMoveNode(server) {
|
|
21279
21322
|
server.tool(
|
|
21280
21323
|
"neos_move_node",
|
|
21281
|
-
"Reorder or reparent a page or content node. Provide exactly one of insert_before, insert_after, or
|
|
21324
|
+
"Reorder or reparent a page or content node. Provide exactly one of insert_before, insert_after, or new_parent_id. Always writes to the mcp workspace.",
|
|
21282
21325
|
{
|
|
21283
|
-
|
|
21284
|
-
"
|
|
21326
|
+
node_id: external_exports.string().describe(
|
|
21327
|
+
"Node identifier to move \u2014 use nodeAggregateId (Neos 9) or contextPath (Neos 8)"
|
|
21285
21328
|
),
|
|
21286
21329
|
insert_before: external_exports.string().optional().describe(
|
|
21287
|
-
"
|
|
21330
|
+
"Sibling node identifier \u2014 move to appear before this sibling"
|
|
21288
21331
|
),
|
|
21289
21332
|
insert_after: external_exports.string().optional().describe(
|
|
21290
|
-
"
|
|
21333
|
+
"Sibling node identifier \u2014 move to appear after this sibling"
|
|
21291
21334
|
),
|
|
21292
|
-
|
|
21293
|
-
"
|
|
21335
|
+
new_parent_id: external_exports.string().optional().describe(
|
|
21336
|
+
"New parent node identifier \u2014 move into this parent (as last child)"
|
|
21294
21337
|
),
|
|
21295
21338
|
workspace: external_exports.string().default("mcp").describe("Draft workspace name")
|
|
21296
21339
|
},
|
|
21297
|
-
async ({
|
|
21340
|
+
async ({ node_id, insert_before, insert_after, new_parent_id, workspace }) => {
|
|
21298
21341
|
const data = await callBridge("moveNode", "POST", {
|
|
21299
|
-
contextPath
|
|
21342
|
+
...await nodeIdParam("contextPath", node_id),
|
|
21343
|
+
...await nodeIdParam("newParentPath", new_parent_id ?? ""),
|
|
21300
21344
|
insertBefore: insert_before ?? "",
|
|
21301
21345
|
insertAfter: insert_after ?? "",
|
|
21302
|
-
newParentPath: new_parent_path ?? "",
|
|
21303
21346
|
workspace
|
|
21304
21347
|
});
|
|
21305
21348
|
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
@@ -21448,6 +21491,69 @@ function registerEntityCrudTools(server) {
|
|
|
21448
21491
|
);
|
|
21449
21492
|
}
|
|
21450
21493
|
|
|
21494
|
+
// src/tools/uploadAsset.ts
|
|
21495
|
+
var import_promises = require("node:fs/promises");
|
|
21496
|
+
var import_node_path = require("node:path");
|
|
21497
|
+
async function loadSource(filePath, url, base64Content, filename) {
|
|
21498
|
+
const sources = [filePath, url, base64Content].filter((s) => s !== void 0 && s !== "");
|
|
21499
|
+
if (sources.length !== 1) {
|
|
21500
|
+
throw new Error("Provide exactly one of file_path, url or base64_content.");
|
|
21501
|
+
}
|
|
21502
|
+
if (filePath) {
|
|
21503
|
+
const buffer = await (0, import_promises.readFile)(filePath);
|
|
21504
|
+
return { filename: filename || (0, import_node_path.basename)(filePath), content: buffer.toString("base64") };
|
|
21505
|
+
}
|
|
21506
|
+
if (url) {
|
|
21507
|
+
const response = await fetch(url);
|
|
21508
|
+
if (!response.ok) {
|
|
21509
|
+
throw new Error(`Download failed (${response.status}): ${url}`);
|
|
21510
|
+
}
|
|
21511
|
+
const buffer = Buffer.from(await response.arrayBuffer());
|
|
21512
|
+
const urlFilename = decodeURIComponent((0, import_node_path.basename)(new URL(url).pathname));
|
|
21513
|
+
const resolvedFilename = filename || urlFilename;
|
|
21514
|
+
if (!resolvedFilename) {
|
|
21515
|
+
throw new Error("Could not derive a filename from the URL, please pass filename.");
|
|
21516
|
+
}
|
|
21517
|
+
return { filename: resolvedFilename, content: buffer.toString("base64") };
|
|
21518
|
+
}
|
|
21519
|
+
if (!filename) {
|
|
21520
|
+
throw new Error("filename is required when using base64_content.");
|
|
21521
|
+
}
|
|
21522
|
+
return { filename, content: base64Content.replace(/^data:[^;]+;base64,/, "") };
|
|
21523
|
+
}
|
|
21524
|
+
function registerUploadAsset(server) {
|
|
21525
|
+
server.tool(
|
|
21526
|
+
"neos_upload_asset",
|
|
21527
|
+
"Upload a file (image, PDF, video, \u2026) into the Neos Media Manager. Provide exactly one source: a local file_path, a url to download, or base64_content. If a file with identical content already exists, the existing asset is returned (duplicate: true). The returned identifier can be used as value for image/asset properties via neos_update_node_property.",
|
|
21528
|
+
{
|
|
21529
|
+
file_path: external_exports.string().optional().describe("Absolute path to a local file to upload"),
|
|
21530
|
+
url: external_exports.string().optional().describe("HTTP(S) URL of a file to download and upload"),
|
|
21531
|
+
base64_content: external_exports.string().optional().describe("Base64 encoded file content (data URI prefix allowed); requires filename"),
|
|
21532
|
+
filename: external_exports.string().optional().describe("Target filename incl. extension. Defaults to the name from file_path or url."),
|
|
21533
|
+
title: external_exports.string().default("").describe("Asset title"),
|
|
21534
|
+
caption: external_exports.string().default("").describe("Asset caption"),
|
|
21535
|
+
copyright_notice: external_exports.string().default("").describe("Copyright notice"),
|
|
21536
|
+
tags: external_exports.array(external_exports.string()).default([]).describe("Tag labels to assign; missing tags are created"),
|
|
21537
|
+
asset_collections: external_exports.array(external_exports.string()).default([]).describe("Asset collection titles to add the asset to; missing collections are created"),
|
|
21538
|
+
allow_duplicate: external_exports.boolean().default(false).describe("Create a new asset even if identical content already exists")
|
|
21539
|
+
},
|
|
21540
|
+
async ({ file_path, url, base64_content, filename, title, caption, copyright_notice, tags, asset_collections, allow_duplicate }) => {
|
|
21541
|
+
const source = await loadSource(file_path, url, base64_content, filename);
|
|
21542
|
+
const data = await callBridge("uploadAsset", "POST", {
|
|
21543
|
+
filename: source.filename,
|
|
21544
|
+
content: source.content,
|
|
21545
|
+
title,
|
|
21546
|
+
caption,
|
|
21547
|
+
copyrightNotice: copyright_notice,
|
|
21548
|
+
tags,
|
|
21549
|
+
assetCollections: asset_collections,
|
|
21550
|
+
allowDuplicate: allow_duplicate
|
|
21551
|
+
});
|
|
21552
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
21553
|
+
}
|
|
21554
|
+
);
|
|
21555
|
+
}
|
|
21556
|
+
|
|
21451
21557
|
// src/server.ts
|
|
21452
21558
|
function createServer() {
|
|
21453
21559
|
const server = new McpServer({
|
|
@@ -21471,6 +21577,7 @@ function createServer() {
|
|
|
21471
21577
|
registerRestart(server);
|
|
21472
21578
|
registerListAssets(server);
|
|
21473
21579
|
registerListAssetTags(server);
|
|
21580
|
+
registerUploadAsset(server);
|
|
21474
21581
|
registerEntityCrudTools(server);
|
|
21475
21582
|
return server;
|
|
21476
21583
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@upassist/neos-mcp",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "MCP server for Neos CMS — connects AI assistants to any UpAssist.Neos.Mcp bridge",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
|
@@ -11,11 +11,13 @@
|
|
|
11
11
|
"typecheck": "tsc --noEmit",
|
|
12
12
|
"start": "node dist/index.js",
|
|
13
13
|
"dev": "node --import=tsx src/index.ts",
|
|
14
|
-
"
|
|
15
|
-
"release:
|
|
16
|
-
"release:
|
|
17
|
-
"release:
|
|
18
|
-
"release": "
|
|
14
|
+
"prepublishOnly": "npm run build",
|
|
15
|
+
"release:prerelease": "npx standard-version -t '' -r patch --prerelease && npm publish --access public --tag next && git push --follow-tags",
|
|
16
|
+
"release:patch": "npx standard-version -t '' -r patch && npm publish --access public && git push --follow-tags",
|
|
17
|
+
"release:minor": "npx standard-version -t '' -r minor && npm publish --access public && git push --follow-tags",
|
|
18
|
+
"release:major": "npx standard-version -t '' -r major && npm publish --access public && git push --follow-tags",
|
|
19
|
+
"release": "yarn release:patch",
|
|
20
|
+
"test": "esbuild test/*.test.ts --bundle --platform=node --format=esm --target=node20 --outdir=.test-build --out-extension:.js=.mjs --packages=external && node --test .test-build/"
|
|
19
21
|
},
|
|
20
22
|
"engines": {
|
|
21
23
|
"node": ">=18.0.0"
|
package/src/bridge.ts
CHANGED
|
@@ -4,17 +4,83 @@
|
|
|
4
4
|
* Environment variables:
|
|
5
5
|
* NEOS_MCP_URL — Base URL, e.g. http://localhost:8081 or https://mysite.nl
|
|
6
6
|
* NEOS_MCP_TOKEN — Bearer token matching NEOS_MCP_BRIDGE_TOKEN on the server
|
|
7
|
+
*
|
|
8
|
+
* Supports both v1 (Neos 8) and v2 (Neos 9) bridge API versions.
|
|
9
|
+
* API version is auto-detected on the first getSiteContext call.
|
|
7
10
|
*/
|
|
8
11
|
|
|
9
12
|
const BASE_URL = (process.env.NEOS_MCP_URL ?? 'http://localhost:8081').replace(/\/$/, '');
|
|
10
13
|
const TOKEN = process.env.NEOS_MCP_TOKEN ?? '';
|
|
11
14
|
|
|
12
|
-
|
|
13
|
-
|
|
15
|
+
let detectedApiVersion: 1 | 2 | null = null;
|
|
16
|
+
let versionDetectionPromise: Promise<void> | null = null;
|
|
17
|
+
|
|
18
|
+
export function setApiVersion(version: 1 | 2): void {
|
|
19
|
+
detectedApiVersion = version;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function getApiVersion(): 1 | 2 {
|
|
23
|
+
return detectedApiVersion ?? 1;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Auto-detect API version by calling getSiteContext.
|
|
28
|
+
* Cached after first successful detection; concurrent callers share the same request.
|
|
29
|
+
*/
|
|
30
|
+
async function ensureApiVersion(): Promise<void> {
|
|
31
|
+
if (detectedApiVersion !== null) return;
|
|
32
|
+
if (versionDetectionPromise) return versionDetectionPromise;
|
|
33
|
+
versionDetectionPromise = (async () => {
|
|
34
|
+
try {
|
|
35
|
+
const data = await callBridge('getSiteContext', 'GET') as Record<string, unknown>;
|
|
36
|
+
detectedApiVersion = (data && data.apiVersion === 2) ? 2 : 1;
|
|
37
|
+
} catch {
|
|
38
|
+
detectedApiVersion = 1; // fallback to v1 on error
|
|
39
|
+
} finally {
|
|
40
|
+
versionDetectionPromise = null;
|
|
41
|
+
}
|
|
42
|
+
})();
|
|
43
|
+
return versionDetectionPromise;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Build the correct bridge parameter name for a node identifier.
|
|
48
|
+
* v1 (Neos 8) uses nodePath/contextPath, v2 (Neos 9) uses nodeAggregateId.
|
|
49
|
+
* Auto-detects the API version on first use if not yet known.
|
|
50
|
+
*/
|
|
51
|
+
export async function nodeIdParam(key: 'nodePath' | 'contextPath' | 'parentPath' | 'newParentPath', nodeId: string): Promise<Record<string, string>> {
|
|
52
|
+
await ensureApiVersion();
|
|
53
|
+
if (detectedApiVersion === 2) {
|
|
54
|
+
const v2Keys: Record<string, string> = {
|
|
55
|
+
nodePath: 'nodeAggregateId',
|
|
56
|
+
contextPath: 'nodeAggregateId',
|
|
57
|
+
parentPath: 'parentNodeAggregateId',
|
|
58
|
+
newParentPath: 'newParentId',
|
|
59
|
+
};
|
|
60
|
+
return { [v2Keys[key]]: nodeId };
|
|
61
|
+
}
|
|
62
|
+
return { [key]: nodeId };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Build sibling reference params for move/insert operations.
|
|
67
|
+
*/
|
|
68
|
+
export function siblingParam(key: 'insertBefore' | 'insertAfter', siblingId: string): Record<string, string> {
|
|
69
|
+
// Same parameter names for both v1 and v2
|
|
70
|
+
return { [key]: siblingId };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function getHeaders(body?: string): Record<string, string> {
|
|
74
|
+
const headers: Record<string, string> = {
|
|
14
75
|
'Authorization': `Bearer ${TOKEN}`,
|
|
76
|
+
'X-MCP-Token': TOKEN,
|
|
15
77
|
'Content-Type': 'application/json',
|
|
16
78
|
'Accept': 'application/json',
|
|
17
79
|
};
|
|
80
|
+
if (body !== undefined) {
|
|
81
|
+
headers['Content-Length'] = String(Buffer.byteLength(body, 'utf8'));
|
|
82
|
+
}
|
|
83
|
+
return headers;
|
|
18
84
|
}
|
|
19
85
|
|
|
20
86
|
export async function callBridge(
|
|
@@ -37,7 +103,7 @@ export async function callBridge(
|
|
|
37
103
|
|
|
38
104
|
const response = await fetch(url, {
|
|
39
105
|
method,
|
|
40
|
-
headers: getHeaders(),
|
|
106
|
+
headers: getHeaders(body),
|
|
41
107
|
body,
|
|
42
108
|
});
|
|
43
109
|
|
package/src/server.ts
CHANGED
|
@@ -17,6 +17,7 @@ import { registerRestart } from './tools/restart.js';
|
|
|
17
17
|
import { registerListAssets } from './tools/listAssets.js';
|
|
18
18
|
import { registerListAssetTags } from './tools/listAssetTags.js';
|
|
19
19
|
import { registerEntityCrudTools } from './tools/entityCrud.js';
|
|
20
|
+
import { registerUploadAsset } from './tools/uploadAsset.js';
|
|
20
21
|
|
|
21
22
|
export function createServer(): McpServer {
|
|
22
23
|
const server = new McpServer({
|
|
@@ -41,6 +42,7 @@ export function createServer(): McpServer {
|
|
|
41
42
|
registerRestart(server);
|
|
42
43
|
registerListAssets(server);
|
|
43
44
|
registerListAssetTags(server);
|
|
45
|
+
registerUploadAsset(server);
|
|
44
46
|
registerEntityCrudTools(server);
|
|
45
47
|
|
|
46
48
|
return server;
|
|
@@ -1,26 +1,26 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerCreateContentNode(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_create_content_node',
|
|
8
8
|
'Create a new content element inside a page\'s content collection. Call neos_get_site_context first if you have not already done so this session. Always writes to the mcp workspace.',
|
|
9
9
|
{
|
|
10
|
-
|
|
11
|
-
'
|
|
10
|
+
parent_id: z.string().describe(
|
|
11
|
+
'Parent node identifier — the content collection to add to. Use nodeAggregateId (Neos 9) or path (Neos 8).'
|
|
12
12
|
),
|
|
13
13
|
node_type: z.string().describe(
|
|
14
|
-
'Node type name, e.g. UpAssist.
|
|
14
|
+
'Node type name, e.g. UpAssist.Site:Content.Headline'
|
|
15
15
|
),
|
|
16
16
|
properties: z.record(z.unknown()).default({}).describe(
|
|
17
17
|
'Property key-value pairs to set on the new node. Use neos_list_node_types to see available properties.'
|
|
18
18
|
),
|
|
19
19
|
workspace: z.string().default('mcp').describe('Draft workspace name'),
|
|
20
20
|
},
|
|
21
|
-
async ({
|
|
21
|
+
async ({ parent_id, node_type, properties, workspace }) => {
|
|
22
22
|
const data = await callBridge('createContentNode', 'POST', {
|
|
23
|
-
parentPath
|
|
23
|
+
...await nodeIdParam('parentPath', parent_id),
|
|
24
24
|
nodeType: node_type,
|
|
25
25
|
properties,
|
|
26
26
|
workspace,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerCreateDocumentNode(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
@@ -9,11 +9,11 @@ export function registerCreateDocumentNode(server: McpServer): void {
|
|
|
9
9
|
'Call neos_get_site_context first to see available document NodeTypes and the page tree. ' +
|
|
10
10
|
'Always writes to the mcp workspace.',
|
|
11
11
|
{
|
|
12
|
-
|
|
13
|
-
'
|
|
12
|
+
parent_id: z.string().describe(
|
|
13
|
+
'Parent node identifier — use nodeAggregateId (Neos 9) or path (Neos 8).'
|
|
14
14
|
),
|
|
15
15
|
node_type: z.string().describe(
|
|
16
|
-
'Document node type name, e.g. UpAssist.
|
|
16
|
+
'Document node type name, e.g. UpAssist.Site:Document.Page'
|
|
17
17
|
),
|
|
18
18
|
properties: z.record(z.unknown()).default({}).describe(
|
|
19
19
|
'Property key-value pairs, e.g. { title: "About us", uriPathSegment: "about-us" }'
|
|
@@ -23,15 +23,15 @@ export function registerCreateDocumentNode(server: McpServer): void {
|
|
|
23
23
|
'URL slug used as the node name (auto-generated from nodeType if omitted)'
|
|
24
24
|
),
|
|
25
25
|
insert_before: z.string().optional().describe(
|
|
26
|
-
'
|
|
26
|
+
'Sibling node identifier — insert the new page before this sibling'
|
|
27
27
|
),
|
|
28
28
|
insert_after: z.string().optional().describe(
|
|
29
|
-
'
|
|
29
|
+
'Sibling node identifier — insert the new page after this sibling'
|
|
30
30
|
),
|
|
31
31
|
},
|
|
32
|
-
async ({
|
|
32
|
+
async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
|
|
33
33
|
const data = await callBridge('createDocumentNode', 'POST', {
|
|
34
|
-
parentPath
|
|
34
|
+
...await nodeIdParam('parentPath', parent_id),
|
|
35
35
|
nodeType: node_type,
|
|
36
36
|
properties,
|
|
37
37
|
workspace,
|
package/src/tools/deleteNode.ts
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerDeleteNode(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_delete_node',
|
|
8
8
|
'Mark a content node as removed in the mcp workspace. The deletion is staged and will only go live after neos_publish_changes is called.',
|
|
9
9
|
{
|
|
10
|
-
|
|
10
|
+
node_id: z.string().describe('Node identifier — use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)'),
|
|
11
11
|
workspace: z.string().default('mcp').describe('Workspace to operate in'),
|
|
12
12
|
},
|
|
13
|
-
async ({
|
|
13
|
+
async ({ node_id, workspace }) => {
|
|
14
14
|
const data = await callBridge('deleteNode', 'POST', {
|
|
15
|
-
contextPath
|
|
15
|
+
...await nodeIdParam('contextPath', node_id),
|
|
16
16
|
workspace,
|
|
17
17
|
});
|
|
18
18
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerGetDocumentProperties(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_get_document_properties',
|
|
8
8
|
'Get all properties of a document node (page) without its content nodes. Use this for SEO fields, meta data, and other document-level properties.',
|
|
9
9
|
{
|
|
10
|
-
|
|
10
|
+
node_id: z.string().describe('Node identifier — use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_get_site_context / neos_list_pages'),
|
|
11
11
|
workspace: z.string().default('mcp').describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
|
|
12
12
|
},
|
|
13
|
-
async ({
|
|
14
|
-
const data = await callBridge('getDocumentProperties', 'GET', { nodePath
|
|
13
|
+
async ({ node_id, workspace }) => {
|
|
14
|
+
const data = await callBridge('getDocumentProperties', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace });
|
|
15
15
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
16
16
|
}
|
|
17
17
|
);
|
|
18
|
-
}
|
|
18
|
+
}
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerGetPageContent(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_get_page_content',
|
|
8
8
|
'Get all content nodes on a specific page with their properties. Call neos_get_site_context first if you have not already done so this session.',
|
|
9
9
|
{
|
|
10
|
-
|
|
10
|
+
node_id: z.string().describe('Node identifier — use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_get_site_context / neos_list_pages'),
|
|
11
11
|
workspace: z.string().default('mcp').describe('Workspace name'),
|
|
12
12
|
},
|
|
13
|
-
async ({
|
|
14
|
-
const data = await callBridge('getPageContent', 'GET', { nodePath
|
|
13
|
+
async ({ node_id, workspace }) => {
|
|
14
|
+
const data = await callBridge('getPageContent', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace });
|
|
15
15
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
16
16
|
}
|
|
17
17
|
);
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerGetPreviewUrl(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_get_preview_url',
|
|
8
8
|
'Generate a time-limited public preview URL for a page in the MCP workspace. The URL can be opened in any browser without logging into Neos — valid for 24 hours.',
|
|
9
9
|
{
|
|
10
|
-
|
|
10
|
+
node_id: z.string().describe('Node identifier — use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_list_pages'),
|
|
11
11
|
workspace: z.string().default('mcp').describe('Workspace to preview'),
|
|
12
12
|
},
|
|
13
|
-
async ({
|
|
14
|
-
const data = await callBridge('getPreviewUrl', 'GET', { nodePath
|
|
13
|
+
async ({ node_id, workspace }) => {
|
|
14
|
+
const data = await callBridge('getPreviewUrl', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace });
|
|
15
15
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
16
16
|
}
|
|
17
17
|
);
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
|
-
import { callBridge } from '../bridge.js';
|
|
2
|
+
import { callBridge, setApiVersion } from '../bridge.js';
|
|
3
3
|
|
|
4
4
|
export function registerGetSiteContext(server: McpServer): void {
|
|
5
5
|
server.tool(
|
|
@@ -7,8 +7,16 @@ export function registerGetSiteContext(server: McpServer): void {
|
|
|
7
7
|
'Get the site context: site name, available content NodeTypes with their properties, current page tree, and editorial workflow instructions. Always call this first at the start of any Neos content editing session.',
|
|
8
8
|
{},
|
|
9
9
|
async () => {
|
|
10
|
-
const data = await callBridge('getSiteContext', 'GET')
|
|
11
|
-
|
|
10
|
+
const data = await callBridge('getSiteContext', 'GET') as Record<string, unknown>;
|
|
11
|
+
|
|
12
|
+
// Auto-detect bridge API version
|
|
13
|
+
if (data && typeof data === 'object' && 'apiVersion' in data && data.apiVersion === 2) {
|
|
14
|
+
setApiVersion(2);
|
|
15
|
+
} else {
|
|
16
|
+
setApiVersion(1);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
return { content: [{ type: 'text', text: JSON.stringify(data) }] };
|
|
12
20
|
}
|
|
13
21
|
);
|
|
14
22
|
}
|
package/src/tools/moveNode.ts
CHANGED
|
@@ -1,34 +1,34 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerMoveNode(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_move_node',
|
|
8
8
|
'Reorder or reparent a page or content node. ' +
|
|
9
|
-
'Provide exactly one of insert_before, insert_after, or
|
|
9
|
+
'Provide exactly one of insert_before, insert_after, or new_parent_id. ' +
|
|
10
10
|
'Always writes to the mcp workspace.',
|
|
11
11
|
{
|
|
12
|
-
|
|
13
|
-
'
|
|
12
|
+
node_id: z.string().describe(
|
|
13
|
+
'Node identifier to move — use nodeAggregateId (Neos 9) or contextPath (Neos 8)'
|
|
14
14
|
),
|
|
15
15
|
insert_before: z.string().optional().describe(
|
|
16
|
-
'
|
|
16
|
+
'Sibling node identifier — move to appear before this sibling'
|
|
17
17
|
),
|
|
18
18
|
insert_after: z.string().optional().describe(
|
|
19
|
-
'
|
|
19
|
+
'Sibling node identifier — move to appear after this sibling'
|
|
20
20
|
),
|
|
21
|
-
|
|
22
|
-
'
|
|
21
|
+
new_parent_id: z.string().optional().describe(
|
|
22
|
+
'New parent node identifier — move into this parent (as last child)'
|
|
23
23
|
),
|
|
24
24
|
workspace: z.string().default('mcp').describe('Draft workspace name'),
|
|
25
25
|
},
|
|
26
|
-
async ({
|
|
26
|
+
async ({ node_id, insert_before, insert_after, new_parent_id, workspace }) => {
|
|
27
27
|
const data = await callBridge('moveNode', 'POST', {
|
|
28
|
-
contextPath
|
|
28
|
+
...await nodeIdParam('contextPath', node_id),
|
|
29
|
+
...await nodeIdParam('newParentPath', new_parent_id ?? ''),
|
|
29
30
|
insertBefore: insert_before ?? '',
|
|
30
31
|
insertAfter: insert_after ?? '',
|
|
31
|
-
newParentPath: new_parent_path ?? '',
|
|
32
32
|
workspace,
|
|
33
33
|
});
|
|
34
34
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import { callBridge } from '../bridge.js';
|
|
3
|
+
import { callBridge, nodeIdParam } from '../bridge.js';
|
|
4
4
|
|
|
5
5
|
export function registerUpdateNodeProperty(server: McpServer): void {
|
|
6
6
|
server.tool(
|
|
7
7
|
'neos_update_node_property',
|
|
8
8
|
'Update a single property on an existing content node. Call neos_get_site_context first if you have not already done so this session. Always writes to the mcp workspace.',
|
|
9
9
|
{
|
|
10
|
-
|
|
11
|
-
'
|
|
10
|
+
node_id: z.string().describe(
|
|
11
|
+
'Node identifier — use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)'
|
|
12
12
|
),
|
|
13
13
|
property: z.string().describe('Property name to update'),
|
|
14
14
|
value: z.unknown().describe('New property value (string, number, boolean, or object)'),
|
|
15
15
|
workspace: z.string().default('mcp').describe('Workspace to write to'),
|
|
16
16
|
},
|
|
17
|
-
async ({
|
|
17
|
+
async ({ node_id, property, value, workspace }) => {
|
|
18
18
|
const data = await callBridge('updateNodeProperty', 'POST', {
|
|
19
|
-
contextPath
|
|
19
|
+
...await nodeIdParam('contextPath', node_id),
|
|
20
20
|
property,
|
|
21
21
|
value,
|
|
22
22
|
workspace,
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { basename } from 'node:path';
|
|
3
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
4
|
+
import { z } from 'zod';
|
|
5
|
+
import { callBridge } from '../bridge.js';
|
|
6
|
+
|
|
7
|
+
async function loadSource(
|
|
8
|
+
filePath?: string,
|
|
9
|
+
url?: string,
|
|
10
|
+
base64Content?: string,
|
|
11
|
+
filename?: string
|
|
12
|
+
): Promise<{ filename: string; content: string }> {
|
|
13
|
+
const sources = [filePath, url, base64Content].filter((s) => s !== undefined && s !== '');
|
|
14
|
+
if (sources.length !== 1) {
|
|
15
|
+
throw new Error('Provide exactly one of file_path, url or base64_content.');
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
if (filePath) {
|
|
19
|
+
const buffer = await readFile(filePath);
|
|
20
|
+
return { filename: filename || basename(filePath), content: buffer.toString('base64') };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
if (url) {
|
|
24
|
+
const response = await fetch(url);
|
|
25
|
+
if (!response.ok) {
|
|
26
|
+
throw new Error(`Download failed (${response.status}): ${url}`);
|
|
27
|
+
}
|
|
28
|
+
const buffer = Buffer.from(await response.arrayBuffer());
|
|
29
|
+
const urlFilename = decodeURIComponent(basename(new URL(url).pathname));
|
|
30
|
+
const resolvedFilename = filename || urlFilename;
|
|
31
|
+
if (!resolvedFilename) {
|
|
32
|
+
throw new Error('Could not derive a filename from the URL, please pass filename.');
|
|
33
|
+
}
|
|
34
|
+
return { filename: resolvedFilename, content: buffer.toString('base64') };
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
if (!filename) {
|
|
38
|
+
throw new Error('filename is required when using base64_content.');
|
|
39
|
+
}
|
|
40
|
+
return { filename, content: (base64Content as string).replace(/^data:[^;]+;base64,/, '') };
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function registerUploadAsset(server: McpServer): void {
|
|
44
|
+
server.tool(
|
|
45
|
+
'neos_upload_asset',
|
|
46
|
+
'Upload a file (image, PDF, video, …) into the Neos Media Manager. Provide exactly one source: a local file_path, a url to download, or base64_content. If a file with identical content already exists, the existing asset is returned (duplicate: true). The returned identifier can be used as value for image/asset properties via neos_update_node_property.',
|
|
47
|
+
{
|
|
48
|
+
file_path: z.string().optional().describe('Absolute path to a local file to upload'),
|
|
49
|
+
url: z.string().optional().describe('HTTP(S) URL of a file to download and upload'),
|
|
50
|
+
base64_content: z.string().optional().describe('Base64 encoded file content (data URI prefix allowed); requires filename'),
|
|
51
|
+
filename: z.string().optional().describe('Target filename incl. extension. Defaults to the name from file_path or url.'),
|
|
52
|
+
title: z.string().default('').describe('Asset title'),
|
|
53
|
+
caption: z.string().default('').describe('Asset caption'),
|
|
54
|
+
copyright_notice: z.string().default('').describe('Copyright notice'),
|
|
55
|
+
tags: z.array(z.string()).default([]).describe('Tag labels to assign; missing tags are created'),
|
|
56
|
+
asset_collections: z.array(z.string()).default([]).describe('Asset collection titles to add the asset to; missing collections are created'),
|
|
57
|
+
allow_duplicate: z.boolean().default(false).describe('Create a new asset even if identical content already exists'),
|
|
58
|
+
},
|
|
59
|
+
async ({ file_path, url, base64_content, filename, title, caption, copyright_notice, tags, asset_collections, allow_duplicate }) => {
|
|
60
|
+
const source = await loadSource(file_path, url, base64_content, filename);
|
|
61
|
+
const data = await callBridge('uploadAsset', 'POST', {
|
|
62
|
+
filename: source.filename,
|
|
63
|
+
content: source.content,
|
|
64
|
+
title,
|
|
65
|
+
caption,
|
|
66
|
+
copyrightNotice: copyright_notice,
|
|
67
|
+
tags,
|
|
68
|
+
assetCollections: asset_collections,
|
|
69
|
+
allowDuplicate: allow_duplicate,
|
|
70
|
+
});
|
|
71
|
+
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
72
|
+
}
|
|
73
|
+
);
|
|
74
|
+
}
|
package/src/types.ts
CHANGED
|
@@ -1,18 +1,24 @@
|
|
|
1
1
|
export interface PageNode {
|
|
2
|
-
identifier
|
|
3
|
-
|
|
4
|
-
|
|
2
|
+
// v2 (Neos 9) primary identifier
|
|
3
|
+
nodeAggregateId?: string;
|
|
4
|
+
// v1 (Neos 8) identifiers
|
|
5
|
+
identifier?: string;
|
|
6
|
+
contextPath?: string;
|
|
7
|
+
// Common fields
|
|
8
|
+
path?: string;
|
|
5
9
|
nodeType: string;
|
|
6
10
|
name: string;
|
|
7
11
|
title: string;
|
|
8
12
|
hidden: boolean;
|
|
9
13
|
depth: number;
|
|
14
|
+
properties?: Record<string, unknown>;
|
|
10
15
|
}
|
|
11
16
|
|
|
12
17
|
export interface ContentNode {
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
18
|
+
nodeAggregateId?: string;
|
|
19
|
+
identifier?: string;
|
|
20
|
+
contextPath?: string;
|
|
21
|
+
path?: string;
|
|
16
22
|
nodeType: string;
|
|
17
23
|
name: string;
|
|
18
24
|
properties: Record<string, unknown>;
|
|
@@ -32,11 +38,14 @@ export interface NodeTypeSchema {
|
|
|
32
38
|
}
|
|
33
39
|
|
|
34
40
|
export interface PendingChange {
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
41
|
+
// v2
|
|
42
|
+
nodeAggregateId?: string;
|
|
43
|
+
// v1
|
|
44
|
+
identifier?: string;
|
|
45
|
+
contextPath?: string;
|
|
46
|
+
path?: string;
|
|
38
47
|
nodeType: string;
|
|
39
|
-
changeType: 'added' | 'modified' | 'removed';
|
|
48
|
+
changeType: 'added' | 'modified' | 'removed' | 'moved';
|
|
40
49
|
}
|
|
41
50
|
|
|
42
51
|
export interface BridgeErrorResponse {
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { test, before, after, beforeEach } from 'node:test';
|
|
2
|
+
import assert from 'node:assert/strict';
|
|
3
|
+
import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
|
|
4
|
+
import { tmpdir } from 'node:os';
|
|
5
|
+
import { join } from 'node:path';
|
|
6
|
+
|
|
7
|
+
import './support/env.js';
|
|
8
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
9
|
+
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
|
|
10
|
+
import { createServer } from '../src/server.js';
|
|
11
|
+
|
|
12
|
+
type Call = { url: string; method: string; headers: Record<string, string>; body: any };
|
|
13
|
+
|
|
14
|
+
const realFetch = globalThis.fetch;
|
|
15
|
+
let calls: Call[] = [];
|
|
16
|
+
let tmp: string;
|
|
17
|
+
let client: Client;
|
|
18
|
+
|
|
19
|
+
const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==', 'base64');
|
|
20
|
+
|
|
21
|
+
/** Replaces fetch: remote downloads get `remote`, bridge calls are recorded and answered with a canned asset. */
|
|
22
|
+
function mockFetch(remote: { status?: number; body?: Buffer } = {}) {
|
|
23
|
+
globalThis.fetch = (async (input: any, init: any = {}) => {
|
|
24
|
+
const url = String(input);
|
|
25
|
+
if (url.startsWith('http://bridge.test/')) {
|
|
26
|
+
calls.push({
|
|
27
|
+
url,
|
|
28
|
+
method: init.method ?? 'GET',
|
|
29
|
+
headers: init.headers ?? {},
|
|
30
|
+
body: init.body ? JSON.parse(init.body) : undefined,
|
|
31
|
+
});
|
|
32
|
+
return new Response(JSON.stringify({ success: true, duplicate: false, asset: { identifier: 'abc', filename: 'x' } }), {
|
|
33
|
+
status: 200,
|
|
34
|
+
headers: { 'content-type': 'application/json' },
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
return new Response(remote.body ?? Buffer.alloc(0), { status: remote.status ?? 200 });
|
|
38
|
+
}) as typeof fetch;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function callUpload(args: Record<string, unknown>) {
|
|
42
|
+
return client.callTool({ name: 'neos_upload_asset', arguments: args });
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
before(async () => {
|
|
46
|
+
tmp = mkdtempSync(join(tmpdir(), 'neos-mcp-upload-'));
|
|
47
|
+
writeFileSync(join(tmp, 'photo.png'), PNG);
|
|
48
|
+
const server = createServer();
|
|
49
|
+
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
|
|
50
|
+
client = new Client({ name: 'test', version: '0.0.0' });
|
|
51
|
+
await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
after(() => {
|
|
55
|
+
globalThis.fetch = realFetch;
|
|
56
|
+
rmSync(tmp, { recursive: true, force: true });
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
beforeEach(() => {
|
|
60
|
+
calls = [];
|
|
61
|
+
mockFetch();
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
test('the tool is registered', async () => {
|
|
65
|
+
const { tools } = await client.listTools();
|
|
66
|
+
assert.ok(tools.some((t) => t.name === 'neos_upload_asset'));
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
test('file_path: reads the file, defaults the filename, base64-encodes it and posts to uploadAsset', async () => {
|
|
70
|
+
const result = await callUpload({ file_path: join(tmp, 'photo.png'), title: 'T', tags: ['a'], asset_collections: ['C'] });
|
|
71
|
+
assert.notEqual(result.isError, true);
|
|
72
|
+
|
|
73
|
+
assert.equal(calls.length, 1);
|
|
74
|
+
const [call] = calls;
|
|
75
|
+
assert.equal(call.url, 'http://bridge.test/neos/mcp/uploadAsset');
|
|
76
|
+
assert.equal(call.method, 'POST');
|
|
77
|
+
assert.equal(call.body.filename, 'photo.png');
|
|
78
|
+
assert.equal(call.body.content, PNG.toString('base64'));
|
|
79
|
+
assert.equal(call.body.title, 'T');
|
|
80
|
+
assert.deepEqual(call.body.tags, ['a']);
|
|
81
|
+
assert.deepEqual(call.body.assetCollections, ['C']);
|
|
82
|
+
assert.equal(call.body.allowDuplicate, false);
|
|
83
|
+
assert.equal(call.headers['Authorization'], 'Bearer unit-test-token');
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
test('file_path: an explicit filename wins over the path', async () => {
|
|
87
|
+
await callUpload({ file_path: join(tmp, 'photo.png'), filename: 'renamed.png' });
|
|
88
|
+
assert.equal(calls[0].body.filename, 'renamed.png');
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
test('url: downloads client-side and uploads the bytes, filename derived from the URL', async () => {
|
|
92
|
+
mockFetch({ body: PNG });
|
|
93
|
+
await callUpload({ url: 'https://example.com/some%20dir/Logo%20Final.png?x=1' });
|
|
94
|
+
assert.equal(calls[0].body.filename, 'Logo Final.png');
|
|
95
|
+
assert.equal(calls[0].body.content, PNG.toString('base64'));
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
test('url: a failed download is reported as a tool error and nothing reaches the bridge', async () => {
|
|
99
|
+
mockFetch({ status: 404 });
|
|
100
|
+
const result = await callUpload({ url: 'https://example.com/missing.png' });
|
|
101
|
+
assert.equal(result.isError, true);
|
|
102
|
+
assert.match(JSON.stringify(result.content), /Download failed \(404\)/);
|
|
103
|
+
assert.equal(calls.length, 0);
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
test('base64_content: strips a data: URI prefix and requires a filename', async () => {
|
|
107
|
+
await callUpload({ base64_content: `data:image/png;base64,${PNG.toString('base64')}`, filename: 'inline.png' });
|
|
108
|
+
assert.equal(calls[0].body.content, PNG.toString('base64'));
|
|
109
|
+
assert.equal(calls[0].body.filename, 'inline.png');
|
|
110
|
+
|
|
111
|
+
calls = [];
|
|
112
|
+
const result = await callUpload({ base64_content: PNG.toString('base64') });
|
|
113
|
+
assert.equal(result.isError, true);
|
|
114
|
+
assert.match(JSON.stringify(result.content), /filename is required/);
|
|
115
|
+
assert.equal(calls.length, 0);
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
test('exactly one source must be given', async () => {
|
|
119
|
+
for (const args of [{}, { file_path: join(tmp, 'photo.png'), url: 'https://example.com/a.png' }]) {
|
|
120
|
+
const result = await callUpload(args);
|
|
121
|
+
assert.equal(result.isError, true);
|
|
122
|
+
assert.match(JSON.stringify(result.content), /exactly one of file_path, url or base64_content/);
|
|
123
|
+
}
|
|
124
|
+
assert.equal(calls.length, 0);
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
test('a missing local file is a tool error', async () => {
|
|
128
|
+
const result = await callUpload({ file_path: join(tmp, 'does-not-exist.png') });
|
|
129
|
+
assert.equal(result.isError, true);
|
|
130
|
+
assert.equal(calls.length, 0);
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
test('allow_duplicate and copyright_notice are passed to the bridge under the bridge parameter names', async () => {
|
|
134
|
+
await callUpload({ file_path: join(tmp, 'photo.png'), allow_duplicate: true, copyright_notice: '(c) me', caption: 'cap' });
|
|
135
|
+
assert.equal(calls[0].body.allowDuplicate, true);
|
|
136
|
+
assert.equal(calls[0].body.copyrightNotice, '(c) me');
|
|
137
|
+
assert.equal(calls[0].body.caption, 'cap');
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
test('the bridge response is returned to the caller', async () => {
|
|
141
|
+
const result = await callUpload({ file_path: join(tmp, 'photo.png') });
|
|
142
|
+
const text = (result.content as Array<{ text: string }>)[0].text;
|
|
143
|
+
assert.equal(JSON.parse(text).asset.identifier, 'abc');
|
|
144
|
+
});
|