@upassist/neos-mcp 2.3.0 → 2.5.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,27 @@
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.5.0](https://github.com/UpAssist/neos-mcp-client/compare/2.4.0...2.5.0) (2026-11-12)
6
+
7
+
8
+ ### Features
9
+
10
+ * describe references in the tool descriptions ([2a0aedb](https://github.com/UpAssist/neos-mcp-client/commit/2a0aedbd3ad7503f0d62a9da27fbf06fa3f2f544)), closes [UpAssist/neos-mcp#14](https://github.com/UpAssist/neos-mcp/issues/14)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * allow an empty list for references in the types ([af7ed4c](https://github.com/UpAssist/neos-mcp-client/commit/af7ed4c4c29538316ce3a7992a8017e37c901e51))
16
+ * run the tests with a glob so npm test works on Node 22 and newer ([#8](https://github.com/UpAssist/neos-mcp-client/issues/8)) ([6a17c1c](https://github.com/UpAssist/neos-mcp-client/commit/6a17c1c89b7b7835397497e732f46feac3b6c91b)), closes [#7](https://github.com/UpAssist/neos-mcp-client/issues/7)
17
+
18
+ ## [2.4.0](https://github.com/UpAssist/neos-mcp-client/compare/2.3.0...2.4.0) (2026-11-02)
19
+
20
+
21
+ ### Features
22
+
23
+ * 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))
24
+ * 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))
25
+
5
26
  ## [2.3.0](https://github.com/UpAssist/neos-mcp-client/compare/2.2.0...2.3.0) (2026-10-13)
6
27
 
7
28
 
package/README.md CHANGED
@@ -9,12 +9,14 @@ This is the client-side component. It runs locally on your machine and translate
9
9
  | MCP Server version | Bridge version | Neos CMS | Node.js |
10
10
  |-------------------|------------------------|----------|---------|
11
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+ |
12
+ | 1.x (`neos-8`, no longer maintained) | upassist/neos-mcp 1.x | 8.3+ | 18+ |
13
13
 
14
- > **v2 auto-detects** the bridge API version. A single MCP server v2 works with both Neos 8 and Neos 9 bridges.
14
+ > **v2 auto-detects** the bridge API version. A single MCP server v2 works with both Neos 8 and Neos 9 bridges. **Use v2 for Neos 8 as well:** all new client features (`neos_upload_asset`, multi-site, content dimensions) only land in v2 and are not backported to 1.x. What each feature needs from the bridge is listed below.
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,11 +148,13 @@ 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
 
152
155
  - Image/asset properties: the asset `identifier` (e.g. from `neos_list_assets` or `neos_upload_asset`).
153
156
  - Link properties (`Neos\Neos\Domain\Link\Link`, edited with the LinkEditor): a URI string such as `node://<nodeAggregateId>`, `asset://<id>` or `https://…`, or an object `{ "href": "…", "title": "…", "target": "_blank" }`. An empty string clears the link. A `node://` target must exist in the workspace, otherwise the bridge rejects the write. Needs a Neos 9 bridge with Link property support (see the [bridge README](https://github.com/UpAssist/neos-mcp#property-resolution)).
157
+ - References (for example selected brands or a contact person): write a `nodeAggregateId` for a `reference` and an array of them for `references`; the array replaces the previous list, in that order. An empty value clears them. On Neos 9 references are no node properties: `neos_list_node_types` and `neos_get_site_context` list them per node type under `references` with `type`, `label` and `targetNodeTypes`, and `neos_list_pages`, `neos_get_page_content` and `neos_get_document_properties` show the current targets under `references`. This needs bridge 2.5.0 or later, which also rejects unknown targets and targets of another node type; setting references works with every Neos 9 bridge since 2.3.0. On Neos 8 references are regular properties of type `reference`/`references`, and there is no separate `references` block.
154
158
 
155
159
  ### Media
156
160
 
@@ -196,6 +200,16 @@ A Neos instance can host several sites. Without further input the tools work on
196
200
 
197
201
  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
202
 
203
+ ### Content dimensions
204
+
205
+ 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.
206
+
207
+ - Nodes in the results show the `dimensions` they are stored in and `fallback: true` when they are only visible here through a dimension fallback.
208
+ - 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.
209
+ - `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.
210
+ - `neos_get_preview_url` with `dimensions` returns a link to the page in those dimensions, including the URL prefix the site uses for them.
211
+ - `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.
212
+
199
213
  ### Entity management
200
214
 
201
215
  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. Neos 9: each node type also lists its "references" to other nodes, see neos_list_node_types. 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,17 +21108,48 @@ 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(
21114
21144
  "neos_list_pages",
21115
- "List all document nodes (pages) in the Neos CMS site as a flat tree with paths and titles.",
21145
+ 'List all document nodes (pages) in the Neos CMS site as a flat tree with paths and titles. Neos 9: each page also lists its "references" (nodeAggregateIds of the referenced nodes).',
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
  );
@@ -21128,13 +21159,14 @@ function registerListPages(server) {
21128
21159
  function registerGetPageContent(server) {
21129
21160
  server.tool(
21130
21161
  "neos_get_page_content",
21131
- "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.",
21162
+ 'Get all content nodes on a specific page with their properties. Neos 9: each node also lists its "references" (nodeAggregateIds of the referenced nodes, in the format neos_update_node_property accepts). 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
  );
@@ -21144,13 +21176,14 @@ function registerGetPageContent(server) {
21144
21176
  function registerGetDocumentProperties(server) {
21145
21177
  server.tool(
21146
21178
  "neos_get_document_properties",
21147
- "Get all properties of a document node (page) without its content nodes. Use this for SEO fields, meta data, and other document-level properties.",
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. Neos 9: the document's "references" (nodeAggregateIds of the referenced nodes) are listed next to "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
  );
@@ -21160,7 +21193,7 @@ function registerGetDocumentProperties(server) {
21160
21193
  function registerListNodeTypes(server) {
21161
21194
  server.tool(
21162
21195
  "neos_list_node_types",
21163
- "List available content node types with their property schemas. Useful to know which types and properties are available before creating or updating nodes.",
21196
+ 'List available content node types with their property schemas. Useful to know which types and properties are available before creating or updating nodes. Neos 9: references to other nodes (for example selected brands or a contact person) are listed separately under "references", each with "type" ("reference" for one node, "references" for several), "label" and "targetNodeTypes" (the node types that can be referenced, null if any node can). In Neos 8 references are regular properties of type "reference"/"references".',
21164
21197
  {
21165
21198
  filter: external_exports.enum(["content", "document", "all"]).default("content").describe(
21166
21199
  '"content" for content elements, "document" for page types, "all" for everything'
@@ -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
  );
@@ -21218,16 +21253,18 @@ function registerCreateContentNode(server) {
21218
21253
  "Node type name, e.g. UpAssist.Site:Content.Headline"
21219
21254
  ),
21220
21255
  properties: external_exports.record(external_exports.unknown()).default({}).describe(
21221
- "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)."
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, nodeAggregateIds for references)."
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
  }
@@ -21243,18 +21280,20 @@ function registerUpdateNodeProperty(server) {
21243
21280
  node_id: external_exports.string().describe(
21244
21281
  "Node identifier \u2014 use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)"
21245
21282
  ),
21246
- property: external_exports.string().describe("Property name to update"),
21283
+ property: external_exports.string().describe("Property or reference name to update"),
21247
21284
  value: external_exports.unknown().describe(
21248
- '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.'
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. References (Neos 9: listed under "references" of the node type in neos_list_node_types, not under "properties"): a nodeAggregateId for type "reference", an array of nodeAggregateIds for type "references" (the complete new list in the desired order, it replaces the old one); an empty string or empty array clears them. Every target must exist in the workspace and be of one of the reference's "targetNodeTypes" (if set), otherwise the write is rejected. The current targets are shown under "references" in neos_get_page_content / neos_get_document_properties.`
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
  );
@@ -21319,7 +21361,7 @@ function registerCreateDocumentNode(server) {
21319
21361
  "Document node type name, e.g. UpAssist.Site:Document.Page"
21320
21362
  ),
21321
21363
  properties: external_exports.record(external_exports.unknown()).default({}).describe(
21322
- 'Property key-value pairs, e.g. { title: "About us", uriPathSegment: "about-us" }. Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, \u2026 } objects).'
21364
+ 'Property key-value pairs, e.g. { title: "About us", uriPathSegment: "about-us" }. Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, \u2026 } objects, nodeAggregateIds for references).'
21323
21365
  ),
21324
21366
  workspace: external_exports.string().default("mcp").describe("Draft workspace name"),
21325
21367
  node_name: external_exports.string().optional().describe(
@@ -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.5.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": {
@@ -17,14 +17,14 @@
17
17
  "release:minor": "npx standard-version -t '' -r minor && npm publish --access public && git push --follow-tags",
18
18
  "release:major": "npx standard-version -t '' -r major && npm publish --access public && git push --follow-tags",
19
19
  "release": "yarn release:patch",
20
- "test": "esbuild test/*.test.ts --bundle --platform=node --format=esm --target=node20 --outdir=.test-build --out-extension:.js=.mjs --packages=external && node --test .test-build/"
20
+ "test": "esbuild test/*.test.ts --bundle --platform=node --format=esm --target=node20 --outdir=.test-build --out-extension:.js=.mjs --packages=external && node --test .test-build/*.mjs"
21
21
  },
22
22
  "engines": {
23
23
  "node": ">=18.0.0"
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(
@@ -15,16 +16,18 @@ export function registerCreateContentNode(server: McpServer): void {
15
16
  ),
16
17
  properties: z.record(z.unknown()).default({}).describe(
17
18
  'Property key-value pairs to set on the new node. Use neos_list_node_types to see available properties. ' +
18
- 'Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, … } objects).'
19
+ 'Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, … } objects, nodeAggregateIds for references).'
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(
@@ -17,7 +18,7 @@ export function registerCreateDocumentNode(server: McpServer): void {
17
18
  ),
18
19
  properties: z.record(z.unknown()).default({}).describe(
19
20
  'Property key-value pairs, e.g. { title: "About us", uriPathSegment: "about-us" }. ' +
20
- 'Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, … } objects).'
21
+ 'Values are resolved like in neos_update_node_property (asset identifiers, link URIs or { href, … } objects, nodeAggregateIds for references).'
21
22
  ),
22
23
  workspace: z.string().default('mcp').describe('Draft workspace name'),
23
24
  node_name: z.string().optional().describe(
@@ -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
+ }