@upassist/neos-mcp 1.0.0 → 2.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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,21 @@
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.0.2](https://github.com/UpAssist/neos-mcp-client/compare/2.0.1...2.0.2) (2026-09-23)
6
+
7
+
8
+ ### Bug Fixes
9
+
10
+ * send X-MCP-Token and explicit Content-Length headers to bridge ([94db801](https://github.com/UpAssist/neos-mcp-client/commit/94db8017e0e8d3943dcddcf331af629ea25ff8cf))
11
+
12
+ ### [2.0.1](https://github.com/UpAssist/neos-mcp-client/compare/2.0.0...2.0.1) (2026-04-16)
13
+
14
+
15
+ ### Bug Fixes
16
+
17
+ * lazily auto-detect API version to survive server restarts ([c3e4a4a](https://github.com/UpAssist/neos-mcp-client/commit/c3e4a4a2ae598ed700a5eae84ecc5473729b9b2d))
18
+ * remove pretty-printing from getSiteContext to reduce token usage ([96d57db](https://github.com/UpAssist/neos-mcp-client/commit/96d57db5abd14112d4178eb7690720981493f5aa))
19
+
5
20
  ## 0.2.0 (2026-03-25)
6
21
 
7
22
 
package/README.md CHANGED
@@ -4,6 +4,15 @@
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
+
7
16
  ## Requirements
8
17
 
9
18
  - Node.js 18+
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
- function getHeaders() {
20993
- return {
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
- return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
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
- node_path: external_exports.string().describe("Absolute node path of the document, e.g. /sites/ewijksolartechniek/over-ons"),
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 ({ node_path, workspace }) => {
21078
- const data = await callBridge("getPageContent", "GET", { nodePath: node_path, workspace });
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
- node_path: external_exports.string().describe("Absolute node path of the document, e.g. /sites/ewijksolartechniek/over-ons"),
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 ({ node_path, workspace }) => {
21094
- const data = await callBridge("getDocumentProperties", "GET", { nodePath: node_path, workspace });
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
- node_path: external_exports.string().describe("Absolute node path of the document to preview, e.g. /sites/ewijksolartechniek/over-ons"),
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 ({ node_path, workspace }) => {
21142
- const data = await callBridge("getPreviewUrl", "GET", { nodePath: node_path, workspace });
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
- parent_path: external_exports.string().describe(
21155
- "Absolute path to the content collection node, e.g. /sites/ewijksolartechniek/over-ons/main"
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.EwijkSolarTechniek:Content.Headline"
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 ({ parent_path, node_type, properties, workspace }) => {
21208
+ async ({ parent_id, node_type, properties, workspace }) => {
21166
21209
  const data = await callBridge("createContentNode", "POST", {
21167
- parentPath: parent_path,
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
- context_path: external_exports.string().describe(
21184
- "Context path of the node, e.g. /sites/ewijksolartechniek/page/main/headline@mcp or just the node path without workspace"
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 ({ context_path, property, value, workspace }) => {
21233
+ async ({ node_id, property, value, workspace }) => {
21191
21234
  const data = await callBridge("updateNodeProperty", "POST", {
21192
- contextPath: context_path,
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
- context_path: external_exports.string().describe("Context path or node path of the node to delete"),
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 ({ context_path, workspace }) => {
21254
+ async ({ node_id, workspace }) => {
21212
21255
  const data = await callBridge("deleteNode", "POST", {
21213
- contextPath: context_path,
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
- parent_path: external_exports.string().describe(
21243
- "Absolute path to the parent document node, e.g. /sites/ewijksolartechniek"
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.EwijkSolarTechniek:Document.Page"
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
- "contextPath of a sibling node to insert the new page before"
21299
+ "Sibling node identifier \u2014 insert the new page before this sibling"
21257
21300
  ),
21258
21301
  insert_after: external_exports.string().optional().describe(
21259
- "contextPath of a sibling node to insert the new page after"
21302
+ "Sibling node identifier \u2014 insert the new page after this sibling"
21260
21303
  )
21261
21304
  },
21262
- async ({ parent_path, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
21305
+ async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
21263
21306
  const data = await callBridge("createDocumentNode", "POST", {
21264
- parentPath: parent_path,
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 new_parent_path. Always writes to the mcp workspace.",
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
- context_path: external_exports.string().describe(
21284
- "contextPath of the node to move, e.g. /sites/ewijksolartechniek/about@mcp"
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
- "contextPath of a sibling node \u2014 move the node to appear before this sibling"
21330
+ "Sibling node identifier \u2014 move to appear before this sibling"
21288
21331
  ),
21289
21332
  insert_after: external_exports.string().optional().describe(
21290
- "contextPath of a sibling node \u2014 move the node to appear after this sibling"
21333
+ "Sibling node identifier \u2014 move to appear after this sibling"
21291
21334
  ),
21292
- new_parent_path: external_exports.string().optional().describe(
21293
- "Absolute path of a new parent node \u2014 move the node into this parent (as last child)"
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 ({ context_path, insert_before, insert_after, new_parent_path, workspace }) => {
21340
+ async ({ node_id, insert_before, insert_after, new_parent_id, workspace }) => {
21298
21341
  const data = await callBridge("moveNode", "POST", {
21299
- contextPath: context_path,
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) }] };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@upassist/neos-mcp",
3
- "version": "1.0.0",
3
+ "version": "2.0.2",
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,10 +11,11 @@
11
11
  "typecheck": "tsc --noEmit",
12
12
  "start": "node dist/index.js",
13
13
  "dev": "node --import=tsx src/index.ts",
14
- "release:prerelease": "npx standard-version -t '' -r patch --prerelease && git push --follow-tags",
15
- "release:patch": "npx standard-version -t '' -r patch && git push --follow-tags",
16
- "release:minor": "npx standard-version -t '' -r minor && git push --follow-tags",
17
- "release:major": "npx standard-version -t '' -r major && git push --follow-tags",
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",
18
19
  "release": "yarn release:patch"
19
20
  },
20
21
  "engines": {
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
- function getHeaders(): Record<string, string> {
13
- return {
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
 
@@ -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
- parent_path: z.string().describe(
11
- 'Absolute path to the content collection node, e.g. /sites/ewijksolartechniek/over-ons/main'
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.EwijkSolarTechniek:Content.Headline'
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 ({ parent_path, node_type, properties, workspace }) => {
21
+ async ({ parent_id, node_type, properties, workspace }) => {
22
22
  const data = await callBridge('createContentNode', 'POST', {
23
- parentPath: parent_path,
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
- parent_path: z.string().describe(
13
- 'Absolute path to the parent document node, e.g. /sites/ewijksolartechniek'
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.EwijkSolarTechniek:Document.Page'
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
- 'contextPath of a sibling node to insert the new page before'
26
+ 'Sibling node identifier — insert the new page before this sibling'
27
27
  ),
28
28
  insert_after: z.string().optional().describe(
29
- 'contextPath of a sibling node to insert the new page after'
29
+ 'Sibling node identifier — insert the new page after this sibling'
30
30
  ),
31
31
  },
32
- async ({ parent_path, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
32
+ async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
33
33
  const data = await callBridge('createDocumentNode', 'POST', {
34
- parentPath: parent_path,
34
+ ...await nodeIdParam('parentPath', parent_id),
35
35
  nodeType: node_type,
36
36
  properties,
37
37
  workspace,
@@ -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
- context_path: z.string().describe('Context path or node path of the node to delete'),
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 ({ context_path, workspace }) => {
13
+ async ({ node_id, workspace }) => {
14
14
  const data = await callBridge('deleteNode', 'POST', {
15
- contextPath: context_path,
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
- node_path: z.string().describe('Absolute node path of the document, e.g. /sites/ewijksolartechniek/over-ons'),
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 ({ node_path, workspace }) => {
14
- const data = await callBridge('getDocumentProperties', 'GET', { nodePath: node_path, workspace });
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
- node_path: z.string().describe('Absolute node path of the document, e.g. /sites/ewijksolartechniek/over-ons'),
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 ({ node_path, workspace }) => {
14
- const data = await callBridge('getPageContent', 'GET', { nodePath: node_path, workspace });
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
- node_path: z.string().describe('Absolute node path of the document to preview, e.g. /sites/ewijksolartechniek/over-ons'),
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 ({ node_path, workspace }) => {
14
- const data = await callBridge('getPreviewUrl', 'GET', { nodePath: node_path, workspace });
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
- return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
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
  }
@@ -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 new_parent_path. ' +
9
+ 'Provide exactly one of insert_before, insert_after, or new_parent_id. ' +
10
10
  'Always writes to the mcp workspace.',
11
11
  {
12
- context_path: z.string().describe(
13
- 'contextPath of the node to move, e.g. /sites/ewijksolartechniek/about@mcp'
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
- 'contextPath of a sibling node — move the node to appear before this sibling'
16
+ 'Sibling node identifier — move to appear before this sibling'
17
17
  ),
18
18
  insert_after: z.string().optional().describe(
19
- 'contextPath of a sibling node — move the node to appear after this sibling'
19
+ 'Sibling node identifier — move to appear after this sibling'
20
20
  ),
21
- new_parent_path: z.string().optional().describe(
22
- 'Absolute path of a new parent node — move the node into this parent (as last child)'
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 ({ context_path, insert_before, insert_after, new_parent_path, workspace }) => {
26
+ async ({ node_id, insert_before, insert_after, new_parent_id, workspace }) => {
27
27
  const data = await callBridge('moveNode', 'POST', {
28
- contextPath: context_path,
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
- context_path: z.string().describe(
11
- 'Context path of the node, e.g. /sites/ewijksolartechniek/page/main/headline@mcp or just the node path without workspace'
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 ({ context_path, property, value, workspace }) => {
17
+ async ({ node_id, property, value, workspace }) => {
18
18
  const data = await callBridge('updateNodeProperty', 'POST', {
19
- contextPath: context_path,
19
+ ...await nodeIdParam('contextPath', node_id),
20
20
  property,
21
21
  value,
22
22
  workspace,
package/src/types.ts CHANGED
@@ -1,18 +1,24 @@
1
1
  export interface PageNode {
2
- identifier: string;
3
- contextPath: string;
4
- path: string;
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
- identifier: string;
14
- contextPath: string;
15
- path: string;
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
- identifier: string;
36
- contextPath: string;
37
- path: string;
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 {