@upassist/neos-mcp 2.3.0 → 2.4.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 CHANGED
@@ -2,6 +2,14 @@
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.4.0](https://github.com/UpAssist/neos-mcp-client/compare/2.3.0...2.4.0) (2026-11-02)
6
+
7
+
8
+ ### Features
9
+
10
+ * content dimensions for the node tools and neos_create_node_variant ([#10](https://github.com/UpAssist/neos-mcp-client/issues/10)) ([46f0553](https://github.com/UpAssist/neos-mcp-client/commit/46f0553142faa9579e041517905277901eff617a))
11
+ * dimensions for preview, pending changes and publishing; fix typecheck ([#10](https://github.com/UpAssist/neos-mcp-client/issues/10)) ([d591f17](https://github.com/UpAssist/neos-mcp-client/commit/d591f17ac8d4859661ca70b97159e931b3100009))
12
+
5
13
  ## [2.3.0](https://github.com/UpAssist/neos-mcp-client/compare/2.2.0...2.3.0) (2026-10-13)
6
14
 
7
15
 
package/README.md CHANGED
@@ -15,6 +15,8 @@ This is the client-side component. It runs locally on your machine and translate
15
15
 
16
16
  > **Multi-site** (`neos_list_sites` and the `site` parameter) needs a bridge with multi-site support (see the [bridge README](https://github.com/UpAssist/neos-mcp#multi-site): upassist/neos-mcp **2.3+** for Neos 9, **1.2+** for Neos 8). Older bridges ignore `site` and always work on the default site; `neos_list_sites` fails with a 404 there. To avoid publishing every site by accident, `neos_publish_changes` with `site` first checks that the bridge supports multi-site and refuses to publish otherwise.
17
17
 
18
+ > **Content dimensions** (the `dimensions` parameter and `neos_create_node_variant`) need a bridge with dimension support: upassist/neos-mcp **2.4+** for Neos 9, **1.3+** for Neos 8. With `dimensions` the client first checks that the bridge reports its dimensions and refuses otherwise, because an older bridge would silently use the default dimensions (and write there).
19
+
18
20
  > **`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.
19
21
 
20
22
  ## Requirements
@@ -146,6 +148,7 @@ Once connected, your AI assistant can use these tools:
146
148
  | `neos_create_document_node` | Create a new page |
147
149
  | `neos_move_node` | Move or reorder a node |
148
150
  | `neos_delete_node` | Remove a node |
151
+ | `neos_create_node_variant` | Create a variant of a node in another content dimension (e.g. a translation, when the dimension is a language), as a copy or empty |
149
152
 
150
153
  Property values are passed to the bridge unchanged and resolved there against the NodeType's property type:
151
154
 
@@ -196,6 +199,16 @@ A Neos instance can host several sites. Without further input the tools work on
196
199
 
197
200
  Tools that work by node id (page content, create, update, move, delete) reach nodes of every site; preview links use the domain of the page's own site. One token covers all sites of an instance.
198
201
 
202
+ ### Content dimensions
203
+
204
+ A site can have content dimensions, such as a language or a country; several dimensions can be combined. `neos_get_site_context` lists them under `dimensions`, with the default value and the fallback chain of each value (for example `en_UK` shows `en_US`). Without further input the tools work in the default dimensions. Pass `dimensions`, for example `{"language": "nl"}`, to `neos_list_pages`, `neos_get_page_content`, `neos_get_document_properties` and to all writing tools to work in another dimension. Dimensions you leave out keep their default.
205
+
206
+ - Nodes in the results show the `dimensions` they are stored in and `fallback: true` when they are only visible here through a dimension fallback.
207
+ - A node that only exists in another dimension (shown through a fallback) cannot be changed or moved in the requested dimension: the bridge answers with a 409. Create a variant first with `neos_create_node_variant` (`mode: "copy"` starts from the source content, `mode: "empty"` without properties and content). The parent has to exist in the target dimension, so create variants top-down.
208
+ - `neos_delete_node` with `dimensions` removes only the variant in those dimensions. On Neos 8 a node that is only shown through a fallback is refused; on Neos 9 it is removed from the requested dimension (and its specializations) and stays in the dimension it is stored in.
209
+ - `neos_get_preview_url` with `dimensions` returns a link to the page in those dimensions, including the URL prefix the site uses for them.
210
+ - `neos_list_pending_changes` shows the `dimensions` of each change and can be limited to some. `neos_publish_changes` without `dimensions` publishes the changes of all dimensions; with `dimensions` only the changes made in those. Neos 9 publishes whole nodes, so a node that also changed in another dimension is skipped and reported under `skippedNodes`; Neos 8 publishes the variants of the requested dimensions separately, so a new variant can go live before its counterpart in another dimension.
211
+
199
212
  ### Entity management
200
213
 
201
214
  If the Neos installation exposes custom Doctrine entities (see [bridge documentation](https://github.com/UpAssist/neos-mcp#entity-crud-advanced)), these tools are also available:
package/dist/index.js CHANGED
@@ -21066,7 +21066,7 @@ async function callBridge(action, method, params = {}) {
21066
21066
  function registerGetSiteContext(server) {
21067
21067
  server.tool(
21068
21068
  "neos_get_site_context",
21069
- '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. On a multi-site instance "sites" lists all sites; pass "site" to get the context of another site than the default one.',
21069
+ '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. On a multi-site instance "sites" lists all sites; pass "site" to get the context of another site than the default one. The "dimensions" in the result list the content dimensions (for example language or country) with their default and fallback chains; pass "dimensions" to the other tools to work in one of them.',
21070
21070
  {
21071
21071
  site: external_exports.string().optional().describe("Site node name (see neos_list_sites). Defaults to the default site of the instance.")
21072
21072
  },
@@ -21108,6 +21108,36 @@ function registerSetupWorkspace(server) {
21108
21108
  );
21109
21109
  }
21110
21110
 
21111
+ // src/dimensions.ts
21112
+ var DIMENSIONS_HINT = 'Content dimensions as an object, e.g. {"language":"nl"} or {"language":"nl","country":"be"} (see "dimensions" in neos_get_site_context for the available values). Dimensions you leave out keep their default value; without this argument the default dimensions are used.';
21113
+ function dimensionsSchema(extra = "") {
21114
+ return external_exports.record(external_exports.string()).optional().describe(DIMENSIONS_HINT + (extra ? " " + extra : ""));
21115
+ }
21116
+ var dimensionSupportConfirmed = false;
21117
+ async function assertDimensionSupport() {
21118
+ if (dimensionSupportConfirmed) return;
21119
+ let context;
21120
+ try {
21121
+ context = await callBridge("getSiteContext", "GET");
21122
+ } catch (error2) {
21123
+ const reason = error2 instanceof Error ? error2.message : String(error2);
21124
+ throw new Error(
21125
+ `Not executed: could not confirm that the bridge supports content dimensions (${reason}).`
21126
+ );
21127
+ }
21128
+ if (!context || typeof context !== "object" || !Array.isArray(context.dimensions)) {
21129
+ throw new Error(
21130
+ 'Not executed: this bridge does not support content dimensions and would use the default dimensions instead. Update the bridge (upassist/neos-mcp 2.4+ for Neos 9, 1.3+ for Neos 8) or leave out "dimensions".'
21131
+ );
21132
+ }
21133
+ dimensionSupportConfirmed = true;
21134
+ }
21135
+ async function dimensionsParam(dimensions, key = "dimensions") {
21136
+ if (!dimensions || Object.keys(dimensions).length === 0) return {};
21137
+ await assertDimensionSupport();
21138
+ return { [key]: JSON.stringify(dimensions) };
21139
+ }
21140
+
21111
21141
  // src/tools/listPages.ts
21112
21142
  function registerListPages(server) {
21113
21143
  server.tool(
@@ -21115,10 +21145,11 @@ function registerListPages(server) {
21115
21145
  "List all document nodes (pages) in the Neos CMS site as a flat tree with paths and titles.",
21116
21146
  {
21117
21147
  workspace: external_exports.string().default("mcp").describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
21118
- site: external_exports.string().optional().describe("Site node name (see neos_list_sites). Defaults to the default site of the instance.")
21148
+ site: external_exports.string().optional().describe("Site node name (see neos_list_sites). Defaults to the default site of the instance."),
21149
+ dimensions: dimensionsSchema('Pages that only exist in another dimension and are shown through a fallback have "fallback": true.')
21119
21150
  },
21120
- async ({ workspace, site }) => {
21121
- const data = await callBridge("listPages", "GET", { workspace, site });
21151
+ async ({ workspace, site, dimensions }) => {
21152
+ const data = await callBridge("listPages", "GET", { workspace, site, ...await dimensionsParam(dimensions) });
21122
21153
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21123
21154
  }
21124
21155
  );
@@ -21131,10 +21162,11 @@ function registerGetPageContent(server) {
21131
21162
  "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.",
21132
21163
  {
21133
21164
  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"),
21134
- workspace: external_exports.string().default("mcp").describe("Workspace name")
21165
+ workspace: external_exports.string().default("mcp").describe("Workspace name"),
21166
+ dimensions: dimensionsSchema()
21135
21167
  },
21136
- async ({ node_id, workspace }) => {
21137
- const data = await callBridge("getPageContent", "GET", { ...await nodeIdParam("nodePath", node_id), workspace });
21168
+ async ({ node_id, workspace, dimensions }) => {
21169
+ const data = await callBridge("getPageContent", "GET", { ...await nodeIdParam("nodePath", node_id), workspace, ...await dimensionsParam(dimensions) });
21138
21170
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21139
21171
  }
21140
21172
  );
@@ -21147,10 +21179,11 @@ function registerGetDocumentProperties(server) {
21147
21179
  "Get all properties of a document node (page) without its content nodes. Use this for SEO fields, meta data, and other document-level properties.",
21148
21180
  {
21149
21181
  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"),
21150
- workspace: external_exports.string().default("mcp").describe('Workspace name. Use "live" for published content, "mcp" for staged changes.')
21182
+ workspace: external_exports.string().default("mcp").describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
21183
+ dimensions: dimensionsSchema()
21151
21184
  },
21152
- async ({ node_id, workspace }) => {
21153
- const data = await callBridge("getDocumentProperties", "GET", { ...await nodeIdParam("nodePath", node_id), workspace });
21185
+ async ({ node_id, workspace, dimensions }) => {
21186
+ const data = await callBridge("getDocumentProperties", "GET", { ...await nodeIdParam("nodePath", node_id), workspace, ...await dimensionsParam(dimensions) });
21154
21187
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21155
21188
  }
21156
21189
  );
@@ -21180,10 +21213,11 @@ function registerListPendingChanges(server) {
21180
21213
  "List all content changes staged in the MCP workspace that have not yet been published to live. Call this before neos_publish_changes to review what will go live.",
21181
21214
  {
21182
21215
  workspace: external_exports.string().default("mcp").describe("Workspace name to check for pending changes"),
21183
- site: external_exports.string().optional().describe('Only list changes of this site (site node name, see neos_list_sites). Without it, changes of all sites are listed, each with its "site".')
21216
+ site: external_exports.string().optional().describe('Only list changes of this site (site node name, see neos_list_sites). Without it, changes of all sites are listed, each with its "site".'),
21217
+ dimensions: dimensionsSchema('Only list the changes made in these dimensions. Without it, the changes of all dimensions are listed, each with its "dimensions".')
21184
21218
  },
21185
- async ({ workspace, site }) => {
21186
- const data = await callBridge("listPendingChanges", "GET", { workspace, site });
21219
+ async ({ workspace, site, dimensions }) => {
21220
+ const data = await callBridge("listPendingChanges", "GET", { workspace, site, ...await dimensionsParam(dimensions) });
21187
21221
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21188
21222
  }
21189
21223
  );
@@ -21196,10 +21230,11 @@ function registerGetPreviewUrl(server) {
21196
21230
  "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.",
21197
21231
  {
21198
21232
  node_id: external_exports.string().describe("Node identifier \u2014 use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_list_pages"),
21199
- workspace: external_exports.string().default("mcp").describe("Workspace to preview")
21233
+ workspace: external_exports.string().default("mcp").describe("Workspace to preview"),
21234
+ dimensions: dimensionsSchema("The preview URL shows the page in these dimensions, including the URL prefix the site uses for them (e.g. /nl).")
21200
21235
  },
21201
- async ({ node_id, workspace }) => {
21202
- const data = await callBridge("getPreviewUrl", "GET", { ...await nodeIdParam("nodePath", node_id), workspace });
21236
+ async ({ node_id, workspace, dimensions }) => {
21237
+ const data = await callBridge("getPreviewUrl", "GET", { ...await nodeIdParam("nodePath", node_id), workspace, ...await dimensionsParam(dimensions) });
21203
21238
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21204
21239
  }
21205
21240
  );
@@ -21220,14 +21255,16 @@ function registerCreateContentNode(server) {
21220
21255
  properties: external_exports.record(external_exports.unknown()).default({}).describe(
21221
21256
  "Property key-value pairs to set on the new node. Use neos_list_node_types to see available properties. Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, \u2026 } objects)."
21222
21257
  ),
21223
- workspace: external_exports.string().default("mcp").describe("Draft workspace name")
21258
+ workspace: external_exports.string().default("mcp").describe("Draft workspace name"),
21259
+ dimensions: dimensionsSchema("The content is created in these dimensions; the parent has to exist there.")
21224
21260
  },
21225
- async ({ parent_id, node_type, properties, workspace }) => {
21261
+ async ({ parent_id, node_type, properties, workspace, dimensions }) => {
21226
21262
  const data = await callBridge("createContentNode", "POST", {
21227
21263
  ...await nodeIdParam("parentPath", parent_id),
21228
21264
  nodeType: node_type,
21229
21265
  properties,
21230
- workspace
21266
+ workspace,
21267
+ ...await dimensionsParam(dimensions)
21231
21268
  });
21232
21269
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21233
21270
  }
@@ -21247,14 +21284,16 @@ function registerUpdateNodeProperty(server) {
21247
21284
  value: external_exports.unknown().describe(
21248
21285
  'New property value (string, number, boolean, or object). Image/asset properties: the asset identifier. Link properties (type Neos\\Neos\\Domain\\Link\\Link): a URI string such as "node://<nodeAggregateId>", "asset://<id>" or "https://\u2026", or an object { href, title?, target?, rel?, download? }; an empty string clears the link. A node:// target must exist in the workspace (check with neos_list_pages), otherwise the write is rejected.'
21249
21286
  ),
21250
- workspace: external_exports.string().default("mcp").describe("Workspace to write to")
21287
+ workspace: external_exports.string().default("mcp").describe("Workspace to write to"),
21288
+ dimensions: dimensionsSchema("The property is changed in exactly these dimensions; a node that only exists in another dimension is refused, create a variant first with neos_create_node_variant.")
21251
21289
  },
21252
- async ({ node_id, property, value, workspace }) => {
21290
+ async ({ node_id, property, value, workspace, dimensions }) => {
21253
21291
  const data = await callBridge("updateNodeProperty", "POST", {
21254
21292
  ...await nodeIdParam("contextPath", node_id),
21255
21293
  property,
21256
21294
  value,
21257
- workspace
21295
+ workspace,
21296
+ ...await dimensionsParam(dimensions)
21258
21297
  });
21259
21298
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21260
21299
  }
@@ -21265,15 +21304,17 @@ function registerUpdateNodeProperty(server) {
21265
21304
  function registerDeleteNode(server) {
21266
21305
  server.tool(
21267
21306
  "neos_delete_node",
21268
- "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.",
21307
+ '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. With "dimensions" only the variant in those dimensions is removed, the variants in other dimensions stay. Neos 8 refuses a node that is only shown through a fallback; Neos 9 then removes the page from the requested dimension (and its specializations) only, the page stays in the dimension it is stored in.',
21269
21308
  {
21270
21309
  node_id: external_exports.string().describe("Node identifier \u2014 use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)"),
21271
- workspace: external_exports.string().default("mcp").describe("Workspace to operate in")
21310
+ workspace: external_exports.string().default("mcp").describe("Workspace to operate in"),
21311
+ dimensions: dimensionsSchema()
21272
21312
  },
21273
- async ({ node_id, workspace }) => {
21313
+ async ({ node_id, workspace, dimensions }) => {
21274
21314
  const data = await callBridge("deleteNode", "POST", {
21275
21315
  ...await nodeIdParam("contextPath", node_id),
21276
- workspace
21316
+ workspace,
21317
+ ...await dimensionsParam(dimensions)
21277
21318
  });
21278
21319
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21279
21320
  }
@@ -21284,12 +21325,13 @@ function registerDeleteNode(server) {
21284
21325
  function registerPublishChanges(server) {
21285
21326
  server.tool(
21286
21327
  "neos_publish_changes",
21287
- 'Publish all pending changes from the mcp workspace to live. This is irreversible. Always call neos_list_pending_changes first and confirm with the user before publishing. On a multi-site instance, pass "site" to publish only the changes of that site; without it, the changes of all sites go live.',
21328
+ 'Publish all pending changes from the mcp workspace to live. This is irreversible. Always call neos_list_pending_changes first and confirm with the user before publishing. On a multi-site instance, pass "site" to publish only the changes of that site; without it, the changes of all sites go live. Without "dimensions" the changes of all content dimensions go live; with "dimensions" only the changes made in those dimensions (on Neos 9 a node that also changed in another dimension is skipped and listed in skippedNodes, because Neos publishes whole nodes).',
21288
21329
  {
21289
21330
  workspace: external_exports.string().default("mcp").describe("Workspace to publish from"),
21290
- site: external_exports.string().optional().describe("Only publish changes of this site (site node name, see neos_list_sites). Without it, all pending changes of all sites are published.")
21331
+ site: external_exports.string().optional().describe("Only publish changes of this site (site node name, see neos_list_sites). Without it, all pending changes of all sites are published."),
21332
+ dimensions: dimensionsSchema("Only publish the changes made in these dimensions. Without it, the changes of all dimensions go live.")
21291
21333
  },
21292
- async ({ workspace, site }) => {
21334
+ async ({ workspace, site, dimensions }) => {
21293
21335
  if (site) {
21294
21336
  try {
21295
21337
  await callBridge("listSites", "GET");
@@ -21300,7 +21342,7 @@ function registerPublishChanges(server) {
21300
21342
  );
21301
21343
  }
21302
21344
  }
21303
- const data = await callBridge("publishChanges", "POST", { workspace, site });
21345
+ const data = await callBridge("publishChanges", "POST", { workspace, site, ...await dimensionsParam(dimensions) });
21304
21346
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21305
21347
  }
21306
21348
  );
@@ -21330,9 +21372,10 @@ function registerCreateDocumentNode(server) {
21330
21372
  ),
21331
21373
  insert_after: external_exports.string().optional().describe(
21332
21374
  "Sibling node identifier \u2014 insert the new page after this sibling"
21333
- )
21375
+ ),
21376
+ dimensions: dimensionsSchema("The page is created in these dimensions; the parent has to exist there.")
21334
21377
  },
21335
- async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
21378
+ async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after, dimensions }) => {
21336
21379
  const data = await callBridge("createDocumentNode", "POST", {
21337
21380
  ...await nodeIdParam("parentPath", parent_id),
21338
21381
  nodeType: node_type,
@@ -21340,7 +21383,8 @@ function registerCreateDocumentNode(server) {
21340
21383
  workspace,
21341
21384
  nodeName: node_name ?? "",
21342
21385
  insertBefore: insert_before ?? "",
21343
- insertAfter: insert_after ?? ""
21386
+ insertAfter: insert_after ?? "",
21387
+ ...await dimensionsParam(dimensions)
21344
21388
  });
21345
21389
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21346
21390
  }
@@ -21365,14 +21409,49 @@ function registerMoveNode(server) {
21365
21409
  new_parent_id: external_exports.string().optional().describe(
21366
21410
  "New parent node identifier \u2014 move into this parent (as last child)"
21367
21411
  ),
21368
- workspace: external_exports.string().default("mcp").describe("Draft workspace name")
21412
+ workspace: external_exports.string().default("mcp").describe("Draft workspace name"),
21413
+ dimensions: dimensionsSchema()
21369
21414
  },
21370
- async ({ node_id, insert_before, insert_after, new_parent_id, workspace }) => {
21415
+ async ({ node_id, insert_before, insert_after, new_parent_id, workspace, dimensions }) => {
21371
21416
  const data = await callBridge("moveNode", "POST", {
21372
21417
  ...await nodeIdParam("contextPath", node_id),
21373
21418
  ...await nodeIdParam("newParentPath", new_parent_id ?? ""),
21374
21419
  insertBefore: insert_before ?? "",
21375
21420
  insertAfter: insert_after ?? "",
21421
+ workspace,
21422
+ ...await dimensionsParam(dimensions)
21423
+ });
21424
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21425
+ }
21426
+ );
21427
+ }
21428
+
21429
+ // src/tools/createNodeVariant.ts
21430
+ function registerCreateNodeVariant(server) {
21431
+ server.tool(
21432
+ "neos_create_node_variant",
21433
+ 'Create a variant of a page or content node in another content dimension (for example a translation when the dimension is a language), starting from the node as it exists in the source dimensions. Use mode "copy" to start from the source content, or "empty" for a variant without properties and content. The parent has to exist in the target dimensions first: create variants top-down. Writes to the mcp workspace. Needed before you can change a node that is only shown in the target dimensions through a fallback.',
21434
+ {
21435
+ node_id: external_exports.string().describe(
21436
+ "Node identifier \u2014 use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)"
21437
+ ),
21438
+ dimensions: external_exports.record(external_exports.string()).describe(
21439
+ 'Target dimensions the variant is created in, e.g. {"language":"nl"}, several dimensions can be combined (see "dimensions" in neos_get_site_context)'
21440
+ ),
21441
+ source_dimensions: external_exports.record(external_exports.string()).optional().describe(
21442
+ "Dimensions of the node to start from. Defaults to the default dimensions."
21443
+ ),
21444
+ mode: external_exports.enum(["copy", "empty"]).default("copy").describe(
21445
+ '"copy": copy properties and content from the source. "empty": no properties (except the URL segment) and no content.'
21446
+ ),
21447
+ workspace: external_exports.string().default("mcp").describe("Draft workspace name")
21448
+ },
21449
+ async ({ node_id, dimensions, source_dimensions, mode, workspace }) => {
21450
+ const data = await callBridge("createNodeVariant", "POST", {
21451
+ ...await nodeIdParam("contextPath", node_id),
21452
+ ...await dimensionsParam(dimensions),
21453
+ ...await dimensionsParam(source_dimensions, "sourceDimensions"),
21454
+ mode,
21376
21455
  workspace
21377
21456
  });
21378
21457
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -21605,6 +21684,7 @@ function createServer() {
21605
21684
  registerPublishChanges(server);
21606
21685
  registerCreateDocumentNode(server);
21607
21686
  registerMoveNode(server);
21687
+ registerCreateNodeVariant(server);
21608
21688
  registerRestart(server);
21609
21689
  registerListAssets(server);
21610
21690
  registerListAssetTags(server);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@upassist/neos-mcp",
3
- "version": "2.3.0",
3
+ "version": "2.4.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": {
@@ -24,7 +24,7 @@
24
24
  },
25
25
  "dependencies": {
26
26
  "@modelcontextprotocol/sdk": "^1.0.0",
27
- "zod": "^3.22.0"
27
+ "zod": "^3.25.0"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/node": "^20.0.0",
@@ -0,0 +1,60 @@
1
+ import { z } from 'zod/v3';
2
+ import { callBridge } from './bridge.js';
3
+
4
+ const DIMENSIONS_HINT =
5
+ 'Content dimensions as an object, e.g. {"language":"nl"} or {"language":"nl","country":"be"} (see "dimensions" in neos_get_site_context for the available values). ' +
6
+ 'Dimensions you leave out keep their default value; without this argument the default dimensions are used.';
7
+
8
+ /**
9
+ * Optional "dimensions" tool argument, shared by all tools that work on node content.
10
+ * `extra` is appended to the description for tool specific behaviour.
11
+ */
12
+ export function dimensionsSchema(extra = '') {
13
+ return z.record(z.string()).optional().describe(DIMENSIONS_HINT + (extra ? ' ' + extra : ''));
14
+ }
15
+
16
+ let dimensionSupportConfirmed = false;
17
+
18
+ /**
19
+ * A bridge without content dimension support ignores the "dimensions" argument and would read or
20
+ * write the default dimensions instead. That is wrong for every call, and for writes it changes
21
+ * the wrong content, so only go ahead when the bridge reports the dimensions it knows.
22
+ */
23
+ export async function assertDimensionSupport(): Promise<void> {
24
+ if (dimensionSupportConfirmed) return;
25
+ let context: unknown;
26
+ try {
27
+ context = await callBridge('getSiteContext', 'GET');
28
+ } catch (error) {
29
+ const reason = error instanceof Error ? error.message : String(error);
30
+ throw new Error(
31
+ `Not executed: could not confirm that the bridge supports content dimensions (${reason}).`
32
+ );
33
+ }
34
+ if (!context || typeof context !== 'object' || !Array.isArray((context as { dimensions?: unknown }).dimensions)) {
35
+ throw new Error(
36
+ 'Not executed: this bridge does not support content dimensions and would use the default dimensions instead. ' +
37
+ 'Update the bridge (upassist/neos-mcp 2.4+ for Neos 9, 1.3+ for Neos 8) or leave out "dimensions".'
38
+ );
39
+ }
40
+ dimensionSupportConfirmed = true;
41
+ }
42
+
43
+ /**
44
+ * Bridge parameters for the "dimensions" argument: nothing when not given, otherwise the
45
+ * dimensions as a JSON string (the bridge accepts it in GET queries and POST bodies alike).
46
+ * Refuses when the bridge has no dimension support.
47
+ */
48
+ export async function dimensionsParam(
49
+ dimensions: Record<string, string> | undefined,
50
+ key = 'dimensions'
51
+ ): Promise<Record<string, string>> {
52
+ if (!dimensions || Object.keys(dimensions).length === 0) return {};
53
+ await assertDimensionSupport();
54
+ return { [key]: JSON.stringify(dimensions) };
55
+ }
56
+
57
+ /** Test helper: forget a confirmed bridge so the next call checks again. */
58
+ export function resetDimensionSupport(): void {
59
+ dimensionSupportConfirmed = false;
60
+ }
package/src/server.ts CHANGED
@@ -14,6 +14,7 @@ import { registerDeleteNode } from './tools/deleteNode.js';
14
14
  import { registerPublishChanges } from './tools/publishChanges.js';
15
15
  import { registerCreateDocumentNode } from './tools/createDocumentNode.js';
16
16
  import { registerMoveNode } from './tools/moveNode.js';
17
+ import { registerCreateNodeVariant } from './tools/createNodeVariant.js';
17
18
  import { registerRestart } from './tools/restart.js';
18
19
  import { registerListAssets } from './tools/listAssets.js';
19
20
  import { registerListAssetTags } from './tools/listAssetTags.js';
@@ -41,6 +42,7 @@ export function createServer(): McpServer {
41
42
  registerPublishChanges(server);
42
43
  registerCreateDocumentNode(server);
43
44
  registerMoveNode(server);
45
+ registerCreateNodeVariant(server);
44
46
  registerRestart(server);
45
47
  registerListAssets(server);
46
48
  registerListAssetTags(server);
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerCreateContentNode(server: McpServer): void {
6
7
  server.tool(
@@ -18,13 +19,15 @@ export function registerCreateContentNode(server: McpServer): void {
18
19
  'Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, … } objects).'
19
20
  ),
20
21
  workspace: z.string().default('mcp').describe('Draft workspace name'),
22
+ dimensions: dimensionsSchema('The content is created in these dimensions; the parent has to exist there.'),
21
23
  },
22
- async ({ parent_id, node_type, properties, workspace }) => {
24
+ async ({ parent_id, node_type, properties, workspace, dimensions }) => {
23
25
  const data = await callBridge('createContentNode', 'POST', {
24
26
  ...await nodeIdParam('parentPath', parent_id),
25
27
  nodeType: node_type,
26
28
  properties,
27
29
  workspace,
30
+ ...await dimensionsParam(dimensions),
28
31
  });
29
32
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
30
33
  }
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerCreateDocumentNode(server: McpServer): void {
6
7
  server.tool(
@@ -29,8 +30,9 @@ export function registerCreateDocumentNode(server: McpServer): void {
29
30
  insert_after: z.string().optional().describe(
30
31
  'Sibling node identifier — insert the new page after this sibling'
31
32
  ),
33
+ dimensions: dimensionsSchema('The page is created in these dimensions; the parent has to exist there.'),
32
34
  },
33
- async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after }) => {
35
+ async ({ parent_id, node_type, properties, workspace, node_name, insert_before, insert_after, dimensions }) => {
34
36
  const data = await callBridge('createDocumentNode', 'POST', {
35
37
  ...await nodeIdParam('parentPath', parent_id),
36
38
  nodeType: node_type,
@@ -39,6 +41,7 @@ export function registerCreateDocumentNode(server: McpServer): void {
39
41
  nodeName: node_name ?? '',
40
42
  insertBefore: insert_before ?? '',
41
43
  insertAfter: insert_after ?? '',
44
+ ...await dimensionsParam(dimensions),
42
45
  });
43
46
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
44
47
  }
@@ -0,0 +1,39 @@
1
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import { z } from 'zod/v3';
3
+ import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsParam } from '../dimensions.js';
5
+
6
+ export function registerCreateNodeVariant(server: McpServer): void {
7
+ server.tool(
8
+ 'neos_create_node_variant',
9
+ 'Create a variant of a page or content node in another content dimension (for example a translation when the dimension is a language), starting from the node as it exists in the source dimensions. ' +
10
+ 'Use mode "copy" to start from the source content, or "empty" for a variant without properties and content. ' +
11
+ 'The parent has to exist in the target dimensions first: create variants top-down. ' +
12
+ 'Writes to the mcp workspace. Needed before you can change a node that is only shown in the target dimensions through a fallback.',
13
+ {
14
+ node_id: z.string().describe(
15
+ 'Node identifier — use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)'
16
+ ),
17
+ dimensions: z.record(z.string()).describe(
18
+ 'Target dimensions the variant is created in, e.g. {"language":"nl"}, several dimensions can be combined (see "dimensions" in neos_get_site_context)'
19
+ ),
20
+ source_dimensions: z.record(z.string()).optional().describe(
21
+ 'Dimensions of the node to start from. Defaults to the default dimensions.'
22
+ ),
23
+ mode: z.enum(['copy', 'empty']).default('copy').describe(
24
+ '"copy": copy properties and content from the source. "empty": no properties (except the URL segment) and no content.'
25
+ ),
26
+ workspace: z.string().default('mcp').describe('Draft workspace name'),
27
+ },
28
+ async ({ node_id, dimensions, source_dimensions, mode, workspace }) => {
29
+ const data = await callBridge('createNodeVariant', 'POST', {
30
+ ...await nodeIdParam('contextPath', node_id),
31
+ ...await dimensionsParam(dimensions),
32
+ ...await dimensionsParam(source_dimensions, 'sourceDimensions'),
33
+ mode,
34
+ workspace,
35
+ });
36
+ return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
37
+ }
38
+ );
39
+ }
@@ -1,19 +1,24 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerDeleteNode(server: McpServer): void {
6
7
  server.tool(
7
8
  'neos_delete_node',
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
+ '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. ' +
10
+ 'With "dimensions" only the variant in those dimensions is removed, the variants in other dimensions stay. ' +
11
+ 'Neos 8 refuses a node that is only shown through a fallback; Neos 9 then removes the page from the requested dimension (and its specializations) only, the page stays in the dimension it is stored in.',
9
12
  {
10
13
  node_id: z.string().describe('Node identifier — use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)'),
11
14
  workspace: z.string().default('mcp').describe('Workspace to operate in'),
15
+ dimensions: dimensionsSchema(),
12
16
  },
13
- async ({ node_id, workspace }) => {
17
+ async ({ node_id, workspace, dimensions }) => {
14
18
  const data = await callBridge('deleteNode', 'POST', {
15
19
  ...await nodeIdParam('contextPath', node_id),
16
20
  workspace,
21
+ ...await dimensionsParam(dimensions),
17
22
  });
18
23
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
19
24
  }
@@ -1,5 +1,5 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge } from '../bridge.js';
4
4
 
5
5
  export function registerEntityCrudTools(server: McpServer): void {
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerGetDocumentProperties(server: McpServer): void {
6
7
  server.tool(
@@ -9,9 +10,10 @@ export function registerGetDocumentProperties(server: McpServer): void {
9
10
  {
10
11
  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
12
  workspace: z.string().default('mcp').describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
13
+ dimensions: dimensionsSchema(),
12
14
  },
13
- async ({ node_id, workspace }) => {
14
- const data = await callBridge('getDocumentProperties', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace });
15
+ async ({ node_id, workspace, dimensions }) => {
16
+ const data = await callBridge('getDocumentProperties', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace, ...await dimensionsParam(dimensions) });
15
17
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
16
18
  }
17
19
  );
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerGetPageContent(server: McpServer): void {
6
7
  server.tool(
@@ -9,9 +10,10 @@ export function registerGetPageContent(server: McpServer): void {
9
10
  {
10
11
  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
12
  workspace: z.string().default('mcp').describe('Workspace name'),
13
+ dimensions: dimensionsSchema(),
12
14
  },
13
- async ({ node_id, workspace }) => {
14
- const data = await callBridge('getPageContent', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace });
15
+ async ({ node_id, workspace, dimensions }) => {
16
+ const data = await callBridge('getPageContent', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace, ...await dimensionsParam(dimensions) });
15
17
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
16
18
  }
17
19
  );
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerGetPreviewUrl(server: McpServer): void {
6
7
  server.tool(
@@ -9,9 +10,10 @@ export function registerGetPreviewUrl(server: McpServer): void {
9
10
  {
10
11
  node_id: z.string().describe('Node identifier — use the nodeAggregateId (Neos 9) or path (Neos 8) from neos_list_pages'),
11
12
  workspace: z.string().default('mcp').describe('Workspace to preview'),
13
+ dimensions: dimensionsSchema('The preview URL shows the page in these dimensions, including the URL prefix the site uses for them (e.g. /nl).'),
12
14
  },
13
- async ({ node_id, workspace }) => {
14
- const data = await callBridge('getPreviewUrl', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace });
15
+ async ({ node_id, workspace, dimensions }) => {
16
+ const data = await callBridge('getPreviewUrl', 'GET', { ...await nodeIdParam('nodePath', node_id), workspace, ...await dimensionsParam(dimensions) });
15
17
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
16
18
  }
17
19
  );
@@ -1,12 +1,13 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, setApiVersion } from '../bridge.js';
4
4
 
5
5
  export function registerGetSiteContext(server: McpServer): void {
6
6
  server.tool(
7
7
  'neos_get_site_context',
8
8
  '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. ' +
9
- 'On a multi-site instance "sites" lists all sites; pass "site" to get the context of another site than the default one.',
9
+ 'On a multi-site instance "sites" lists all sites; pass "site" to get the context of another site than the default one. ' +
10
+ 'The "dimensions" in the result list the content dimensions (for example language or country) with their default and fallback chains; pass "dimensions" to the other tools to work in one of them.',
10
11
  {
11
12
  site: z.string().optional().describe('Site node name (see neos_list_sites). Defaults to the default site of the instance.'),
12
13
  },
@@ -1,5 +1,5 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge } from '../bridge.js';
4
4
 
5
5
  export function registerListAssets(server: McpServer): void {
@@ -1,5 +1,5 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge } from '../bridge.js';
4
4
 
5
5
  export function registerListNodeTypes(server: McpServer): void {
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerListPages(server: McpServer): void {
6
7
  server.tool(
@@ -9,9 +10,10 @@ export function registerListPages(server: McpServer): void {
9
10
  {
10
11
  workspace: z.string().default('mcp').describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
11
12
  site: z.string().optional().describe('Site node name (see neos_list_sites). Defaults to the default site of the instance.'),
13
+ dimensions: dimensionsSchema('Pages that only exist in another dimension and are shown through a fallback have "fallback": true.'),
12
14
  },
13
- async ({ workspace, site }) => {
14
- const data = await callBridge('listPages', 'GET', { workspace, site });
15
+ async ({ workspace, site, dimensions }) => {
16
+ const data = await callBridge('listPages', 'GET', { workspace, site, ...await dimensionsParam(dimensions) });
15
17
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
16
18
  }
17
19
  );
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerListPendingChanges(server: McpServer): void {
6
7
  server.tool(
@@ -9,9 +10,10 @@ export function registerListPendingChanges(server: McpServer): void {
9
10
  {
10
11
  workspace: z.string().default('mcp').describe('Workspace name to check for pending changes'),
11
12
  site: z.string().optional().describe('Only list changes of this site (site node name, see neos_list_sites). Without it, changes of all sites are listed, each with its "site".'),
13
+ dimensions: dimensionsSchema('Only list the changes made in these dimensions. Without it, the changes of all dimensions are listed, each with its "dimensions".'),
12
14
  },
13
- async ({ workspace, site }) => {
14
- const data = await callBridge('listPendingChanges', 'GET', { workspace, site });
15
+ async ({ workspace, site, dimensions }) => {
16
+ const data = await callBridge('listPendingChanges', 'GET', { workspace, site, ...await dimensionsParam(dimensions) });
15
17
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
16
18
  }
17
19
  );
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerMoveNode(server: McpServer): void {
6
7
  server.tool(
@@ -22,14 +23,16 @@ export function registerMoveNode(server: McpServer): void {
22
23
  'New parent node identifier — move into this parent (as last child)'
23
24
  ),
24
25
  workspace: z.string().default('mcp').describe('Draft workspace name'),
26
+ dimensions: dimensionsSchema(),
25
27
  },
26
- async ({ node_id, insert_before, insert_after, new_parent_id, workspace }) => {
28
+ async ({ node_id, insert_before, insert_after, new_parent_id, workspace, dimensions }) => {
27
29
  const data = await callBridge('moveNode', 'POST', {
28
30
  ...await nodeIdParam('contextPath', node_id),
29
31
  ...await nodeIdParam('newParentPath', new_parent_id ?? ''),
30
32
  insertBefore: insert_before ?? '',
31
33
  insertAfter: insert_after ?? '',
32
34
  workspace,
35
+ ...await dimensionsParam(dimensions),
33
36
  });
34
37
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
35
38
  }
@@ -1,17 +1,20 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerPublishChanges(server: McpServer): void {
6
7
  server.tool(
7
8
  'neos_publish_changes',
8
9
  'Publish all pending changes from the mcp workspace to live. This is irreversible. Always call neos_list_pending_changes first and confirm with the user before publishing. ' +
9
- 'On a multi-site instance, pass "site" to publish only the changes of that site; without it, the changes of all sites go live.',
10
+ 'On a multi-site instance, pass "site" to publish only the changes of that site; without it, the changes of all sites go live. ' +
11
+ 'Without "dimensions" the changes of all content dimensions go live; with "dimensions" only the changes made in those dimensions (on Neos 9 a node that also changed in another dimension is skipped and listed in skippedNodes, because Neos publishes whole nodes).',
10
12
  {
11
13
  workspace: z.string().default('mcp').describe('Workspace to publish from'),
12
14
  site: z.string().optional().describe('Only publish changes of this site (site node name, see neos_list_sites). Without it, all pending changes of all sites are published.'),
15
+ dimensions: dimensionsSchema('Only publish the changes made in these dimensions. Without it, the changes of all dimensions go live.'),
13
16
  },
14
- async ({ workspace, site }) => {
17
+ async ({ workspace, site, dimensions }) => {
15
18
  if (site) {
16
19
  // A bridge without multi-site support ignores "site" and would publish the changes of
17
20
  // all sites. Publishing cannot be undone, so only go ahead when the bridge knows sites.
@@ -26,7 +29,7 @@ export function registerPublishChanges(server: McpServer): void {
26
29
  );
27
30
  }
28
31
  }
29
- const data = await callBridge('publishChanges', 'POST', { workspace, site });
32
+ const data = await callBridge('publishChanges', 'POST', { workspace, site, ...await dimensionsParam(dimensions) });
30
33
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
31
34
  }
32
35
  );
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { z } from 'zod';
2
+ import { z } from 'zod/v3';
3
3
  import { callBridge, nodeIdParam } from '../bridge.js';
4
+ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
4
5
 
5
6
  export function registerUpdateNodeProperty(server: McpServer): void {
6
7
  server.tool(
@@ -18,13 +19,15 @@ export function registerUpdateNodeProperty(server: McpServer): void {
18
19
  'A node:// target must exist in the workspace (check with neos_list_pages), otherwise the write is rejected.'
19
20
  ),
20
21
  workspace: z.string().default('mcp').describe('Workspace to write to'),
22
+ dimensions: dimensionsSchema('The property is changed in exactly these dimensions; a node that only exists in another dimension is refused, create a variant first with neos_create_node_variant.'),
21
23
  },
22
- async ({ node_id, property, value, workspace }) => {
24
+ async ({ node_id, property, value, workspace, dimensions }) => {
23
25
  const data = await callBridge('updateNodeProperty', 'POST', {
24
26
  ...await nodeIdParam('contextPath', node_id),
25
27
  property,
26
28
  value,
27
29
  workspace,
30
+ ...await dimensionsParam(dimensions),
28
31
  });
29
32
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
30
33
  }
@@ -1,7 +1,7 @@
1
1
  import { readFile } from 'node:fs/promises';
2
2
  import { basename } from 'node:path';
3
3
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
4
- import { z } from 'zod';
4
+ import { z } from 'zod/v3';
5
5
  import { callBridge } from '../bridge.js';
6
6
 
7
7
  async function loadSource(
@@ -0,0 +1,210 @@
1
+ import { test, before, after, beforeEach } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+
4
+ import './support/env.js';
5
+ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
6
+ import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
7
+ import { createServer } from '../src/server.js';
8
+ import { setApiVersion } from '../src/bridge.js';
9
+ import { resetDimensionSupport } from '../src/dimensions.js';
10
+
11
+ type Call = { url: URL; method: string; body: any };
12
+
13
+ const realFetch = globalThis.fetch;
14
+ let calls: Call[] = [];
15
+ let client: Client;
16
+ let bridgeHasDimensions = true;
17
+
18
+ /** Records bridge calls. getSiteContext reports dimensions unless the test simulates an older bridge. */
19
+ function mockFetch() {
20
+ globalThis.fetch = (async (input: any, init: any = {}) => {
21
+ const url = new URL(String(input));
22
+ calls.push({ url, method: init.method ?? 'GET', body: init.body ? JSON.parse(init.body) : undefined });
23
+ const payload = url.pathname.endsWith('/getSiteContext')
24
+ ? { apiVersion: 2, ...(bridgeHasDimensions ? { dimensions: [{ name: 'language', default: 'en_US', values: [] }] } : {}) }
25
+ : { apiVersion: 2, success: true };
26
+ return new Response(JSON.stringify(payload), { status: 200, headers: { 'content-type': 'application/json' } });
27
+ }) as typeof fetch;
28
+ }
29
+
30
+ before(async () => {
31
+ setApiVersion(2);
32
+ const server = createServer();
33
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
34
+ client = new Client({ name: 'test', version: '0.0.0' });
35
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
36
+ });
37
+
38
+ after(() => {
39
+ globalThis.fetch = realFetch;
40
+ });
41
+
42
+ beforeEach(() => {
43
+ calls = [];
44
+ bridgeHasDimensions = true;
45
+ resetDimensionSupport();
46
+ mockFetch();
47
+ });
48
+
49
+ const paths = () => calls.map((c) => c.url.pathname);
50
+
51
+ test('without "dimensions" no support check is made and nothing dimension related is sent', async () => {
52
+ const result = await client.callTool({ name: 'neos_list_pages', arguments: {} });
53
+ assert.notEqual(result.isError, true);
54
+ assert.deepEqual(paths(), ['/neos/mcp/listPages']);
55
+ assert.equal(calls[0].url.searchParams.has('dimensions'), false);
56
+ });
57
+
58
+ test('neos_list_pages sends "dimensions" as a JSON string in the query, after checking bridge support', async () => {
59
+ const result = await client.callTool({ name: 'neos_list_pages', arguments: { workspace: 'live', dimensions: { language: 'nl' } } });
60
+ assert.notEqual(result.isError, true, JSON.stringify(result.content));
61
+ assert.deepEqual(paths(), ['/neos/mcp/getSiteContext', '/neos/mcp/listPages']);
62
+ const list = calls[1];
63
+ assert.equal(list.url.searchParams.get('workspace'), 'live');
64
+ assert.deepEqual(JSON.parse(list.url.searchParams.get('dimensions') ?? ''), { language: 'nl' });
65
+ });
66
+
67
+ test('the bridge support check is made once', async () => {
68
+ await client.callTool({ name: 'neos_list_pages', arguments: { dimensions: { language: 'nl' } } });
69
+ await client.callTool({ name: 'neos_list_pages', arguments: { dimensions: { language: 'de' } } });
70
+ assert.deepEqual(paths(), ['/neos/mcp/getSiteContext', '/neos/mcp/listPages', '/neos/mcp/listPages']);
71
+ });
72
+
73
+ test('read tools pass "dimensions" with the node id', async () => {
74
+ await client.callTool({ name: 'neos_get_page_content', arguments: { node_id: 'abc', dimensions: { language: 'de' } } });
75
+ const read = calls.find((c) => c.url.pathname.endsWith('/getPageContent'))!;
76
+ assert.equal(read.url.searchParams.get('nodeAggregateId'), 'abc');
77
+ assert.deepEqual(JSON.parse(read.url.searchParams.get('dimensions') ?? ''), { language: 'de' });
78
+
79
+ calls = [];
80
+ await client.callTool({ name: 'neos_get_document_properties', arguments: { node_id: 'abc', dimensions: { language: 'de' } } });
81
+ const props = calls.find((c) => c.url.pathname.endsWith('/getDocumentProperties'))!;
82
+ assert.deepEqual(JSON.parse(props.url.searchParams.get('dimensions') ?? ''), { language: 'de' });
83
+ });
84
+
85
+ test('write tools send "dimensions" in the body', async () => {
86
+ const cases: Array<[string, Record<string, unknown>, string]> = [
87
+ ['neos_update_node_property', { node_id: 'abc', property: 'title', value: 'x' }, 'updateNodeProperty'],
88
+ ['neos_delete_node', { node_id: 'abc' }, 'deleteNode'],
89
+ ['neos_move_node', { node_id: 'abc', insert_before: 'def' }, 'moveNode'],
90
+ ['neos_create_content_node', { parent_id: 'abc', node_type: 'X:Y' }, 'createContentNode'],
91
+ ['neos_create_document_node', { parent_id: 'abc', node_type: 'X:Y' }, 'createDocumentNode'],
92
+ ];
93
+ for (const [tool, args, action] of cases) {
94
+ calls = [];
95
+ const result = await client.callTool({ name: tool, arguments: { ...args, dimensions: { language: 'nl' } } });
96
+ assert.notEqual(result.isError, true, tool + ': ' + JSON.stringify(result.content));
97
+ const write = calls.find((c) => c.url.pathname.endsWith('/' + action))!;
98
+ assert.equal(write.method, 'POST', tool);
99
+ assert.deepEqual(JSON.parse(write.body.dimensions), { language: 'nl' }, tool);
100
+ }
101
+ });
102
+
103
+ test('write tools without "dimensions" send no dimensions key', async () => {
104
+ await client.callTool({ name: 'neos_update_node_property', arguments: { node_id: 'abc', property: 'title', value: 'x' } });
105
+ assert.equal('dimensions' in calls[0].body, false);
106
+ });
107
+
108
+ test('neos_create_node_variant sends target and source dimensions and the mode', async () => {
109
+ const result = await client.callTool({
110
+ name: 'neos_create_node_variant',
111
+ arguments: { node_id: 'abc', dimensions: { language: 'nl' }, source_dimensions: { language: 'en_US' }, mode: 'empty' },
112
+ });
113
+ assert.notEqual(result.isError, true, JSON.stringify(result.content));
114
+ const variant = calls.find((c) => c.url.pathname.endsWith('/createNodeVariant'))!;
115
+ assert.equal(variant.method, 'POST');
116
+ assert.equal(variant.body.nodeAggregateId, 'abc');
117
+ assert.deepEqual(JSON.parse(variant.body.dimensions), { language: 'nl' });
118
+ assert.deepEqual(JSON.parse(variant.body.sourceDimensions), { language: 'en_US' });
119
+ assert.equal(variant.body.mode, 'empty');
120
+ assert.equal(variant.body.workspace, 'mcp');
121
+ });
122
+
123
+ test('neos_create_node_variant defaults to copy mode and leaves out the source dimensions', async () => {
124
+ await client.callTool({ name: 'neos_create_node_variant', arguments: { node_id: 'abc', dimensions: { language: 'nl' } } });
125
+ const variant = calls.find((c) => c.url.pathname.endsWith('/createNodeVariant'))!;
126
+ assert.equal(variant.body.mode, 'copy');
127
+ assert.equal('sourceDimensions' in variant.body, false);
128
+ });
129
+
130
+ test('neos_create_node_variant needs target dimensions', async () => {
131
+ const result = await client.callTool({ name: 'neos_create_node_variant', arguments: { node_id: 'abc' } });
132
+ assert.equal(result.isError, true);
133
+ assert.equal(calls.length, 0);
134
+ });
135
+
136
+ test('with "dimensions", nothing is read or written when the bridge has no dimension support', async () => {
137
+ bridgeHasDimensions = false;
138
+ for (const [tool, args] of [
139
+ ['neos_list_pages', {}],
140
+ ['neos_update_node_property', { node_id: 'abc', property: 'title', value: 'x' }],
141
+ ['neos_delete_node', { node_id: 'abc' }],
142
+ ] as Array<[string, Record<string, unknown>]>) {
143
+ calls = [];
144
+ const result = await client.callTool({ name: tool, arguments: { ...args, dimensions: { language: 'nl' } } });
145
+ assert.equal(result.isError, true, tool);
146
+ assert.deepEqual(paths(), ['/neos/mcp/getSiteContext'], tool);
147
+ assert.match(JSON.stringify(result.content), /does not support content dimensions/, tool);
148
+ }
149
+ });
150
+
151
+ test('the dimension tools describe how to work with variants', async () => {
152
+ const { tools } = await client.listTools();
153
+ const variant = tools.find((t) => t.name === 'neos_create_node_variant');
154
+ assert.ok(variant);
155
+ assert.match(variant.description ?? '', /parent/);
156
+ const del = tools.find((t) => t.name === 'neos_delete_node');
157
+ assert.match(del?.description ?? '', /fallback/);
158
+ });
159
+
160
+ test('preview, pending changes and publishing pass "dimensions" and check bridge support first', async () => {
161
+ await client.callTool({ name: 'neos_get_preview_url', arguments: { node_id: 'abc', dimensions: { language: 'nl' } } });
162
+ const preview = calls.find((c) => c.url.pathname.endsWith('/getPreviewUrl'))!;
163
+ assert.deepEqual(JSON.parse(preview.url.searchParams.get('dimensions') ?? ''), { language: 'nl' });
164
+
165
+ calls = [];
166
+ await client.callTool({ name: 'neos_list_pending_changes', arguments: { dimensions: { language: 'nl' } } });
167
+ const pending = calls.find((c) => c.url.pathname.endsWith('/listPendingChanges'))!;
168
+ assert.deepEqual(JSON.parse(pending.url.searchParams.get('dimensions') ?? ''), { language: 'nl' });
169
+
170
+ calls = [];
171
+ await client.callTool({ name: 'neos_publish_changes', arguments: { dimensions: { language: 'nl' } } });
172
+ const publish = calls.find((c) => c.url.pathname.endsWith('/publishChanges'))!;
173
+ assert.equal(publish.method, 'POST');
174
+ assert.deepEqual(JSON.parse(publish.body.dimensions), { language: 'nl' });
175
+ });
176
+
177
+ test('publishing with "dimensions" is refused when the bridge has no dimension support', async () => {
178
+ bridgeHasDimensions = false;
179
+ const result = await client.callTool({ name: 'neos_publish_changes', arguments: { dimensions: { language: 'nl' } } });
180
+ assert.equal(result.isError, true);
181
+ assert.deepEqual(paths(), ['/neos/mcp/getSiteContext']);
182
+ });
183
+
184
+ test('publishing without "dimensions" sends none', async () => {
185
+ await client.callTool({ name: 'neos_publish_changes', arguments: {} });
186
+ assert.equal('dimensions' in calls[0].body, false);
187
+ });
188
+
189
+ test('several dimensions are sent together, for reading and writing', async () => {
190
+ const dimensions = { language: 'nl', country: 'be' };
191
+
192
+ await client.callTool({ name: 'neos_list_pages', arguments: { dimensions } });
193
+ const list = calls.find((c) => c.url.pathname.endsWith('/listPages'))!;
194
+ assert.deepEqual(JSON.parse(list.url.searchParams.get('dimensions') ?? ''), dimensions);
195
+
196
+ calls = [];
197
+ await client.callTool({
198
+ name: 'neos_create_node_variant',
199
+ arguments: { node_id: 'abc', dimensions, source_dimensions: { language: 'en_US', country: 'nl' } },
200
+ });
201
+ const variant = calls.find((c) => c.url.pathname.endsWith('/createNodeVariant'))!;
202
+ assert.deepEqual(JSON.parse(variant.body.dimensions), dimensions);
203
+ assert.deepEqual(JSON.parse(variant.body.sourceDimensions), { language: 'en_US', country: 'nl' });
204
+ });
205
+
206
+ test('an empty "dimensions" object is treated as not given', async () => {
207
+ await client.callTool({ name: 'neos_list_pages', arguments: { dimensions: {} } });
208
+ assert.deepEqual(paths(), ['/neos/mcp/listPages']);
209
+ assert.equal(calls[0].url.searchParams.has('dimensions'), false);
210
+ });