@upassist/neos-mcp 2.4.0 → 2.5.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@upassist/neos-mcp",
3
- "version": "2.4.0",
3
+ "version": "2.5.1",
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,18 +17,18 @@
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.25.0"
27
+ "zod": "^4.6.7"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/node": "^20.0.0",
31
- "esbuild": "^0.27.4",
31
+ "esbuild": "^0.28.2",
32
32
  "ts-node": "^10.9.0",
33
33
  "typescript": "^5.3.0"
34
34
  }
@@ -16,7 +16,7 @@ export function registerCreateContentNode(server: McpServer): void {
16
16
  ),
17
17
  properties: z.record(z.unknown()).default({}).describe(
18
18
  'Property key-value pairs to set on the new node. Use neos_list_node_types to see available properties. ' +
19
- '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).'
20
20
  ),
21
21
  workspace: z.string().default('mcp').describe('Draft workspace name'),
22
22
  dimensions: dimensionsSchema('The content is created in these dimensions; the parent has to exist there.'),
@@ -18,7 +18,7 @@ export function registerCreateDocumentNode(server: McpServer): void {
18
18
  ),
19
19
  properties: z.record(z.unknown()).default({}).describe(
20
20
  'Property key-value pairs, e.g. { title: "About us", uriPathSegment: "about-us" }. ' +
21
- '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).'
22
22
  ),
23
23
  workspace: z.string().default('mcp').describe('Draft workspace name'),
24
24
  node_name: z.string().optional().describe(
@@ -6,7 +6,7 @@ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
6
6
  export function registerGetDocumentProperties(server: McpServer): void {
7
7
  server.tool(
8
8
  'neos_get_document_properties',
9
- 'Get all properties of a document node (page) without its content nodes. Use this for SEO fields, meta data, and other document-level properties.',
9
+ '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".',
10
10
  {
11
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'),
12
12
  workspace: z.string().default('mcp').describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
@@ -6,7 +6,7 @@ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
6
6
  export function registerGetPageContent(server: McpServer): void {
7
7
  server.tool(
8
8
  'neos_get_page_content',
9
- 'Get all content nodes on a specific page with their properties. Call neos_get_site_context first if you have not already done so this session.',
9
+ '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.',
10
10
  {
11
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'),
12
12
  workspace: z.string().default('mcp').describe('Workspace name'),
@@ -7,6 +7,7 @@ export function registerGetSiteContext(server: McpServer): void {
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
9
  'On a multi-site instance "sites" lists all sites; pass "site" to get the context of another site than the default one. ' +
10
+ 'Neos 9: each node type also lists its "references" to other nodes, see neos_list_node_types. ' +
10
11
  '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.',
11
12
  {
12
13
  site: z.string().optional().describe('Site node name (see neos_list_sites). Defaults to the default site of the instance.'),
@@ -5,7 +5,9 @@ import { callBridge } from '../bridge.js';
5
5
  export function registerListNodeTypes(server: McpServer): void {
6
6
  server.tool(
7
7
  'neos_list_node_types',
8
- 'List available content node types with their property schemas. Useful to know which types and properties are available before creating or updating nodes.',
8
+ 'List available content node types with their property schemas. Useful to know which types and properties are available before creating or updating nodes. ' +
9
+ '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). ' +
10
+ 'In Neos 8 references are regular properties of type "reference"/"references".',
9
11
  {
10
12
  filter: z.enum(['content', 'document', 'all']).default('content').describe(
11
13
  '"content" for content elements, "document" for page types, "all" for everything'
@@ -6,7 +6,7 @@ import { dimensionsSchema, dimensionsParam } from '../dimensions.js';
6
6
  export function registerListPages(server: McpServer): void {
7
7
  server.tool(
8
8
  'neos_list_pages',
9
- 'List all document nodes (pages) in the Neos CMS site as a flat tree with paths and titles.',
9
+ '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).',
10
10
  {
11
11
  workspace: z.string().default('mcp').describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
12
12
  site: z.string().optional().describe('Site node name (see neos_list_sites). Defaults to the default site of the instance.'),
@@ -11,12 +11,16 @@ export function registerUpdateNodeProperty(server: McpServer): void {
11
11
  node_id: z.string().describe(
12
12
  'Node identifier — use nodeAggregateId (Neos 9) or contextPath/path (Neos 8)'
13
13
  ),
14
- property: z.string().describe('Property name to update'),
14
+ property: z.string().describe('Property or reference name to update'),
15
15
  value: z.unknown().describe(
16
16
  'New property value (string, number, boolean, or object). Image/asset properties: the asset identifier. ' +
17
17
  'Link properties (type Neos\\Neos\\Domain\\Link\\Link): a URI string such as "node://<nodeAggregateId>", "asset://<id>" or "https://…", ' +
18
18
  'or an object { href, title?, target?, rel?, download? }; an empty string clears the link. ' +
19
- 'A node:// target must exist in the workspace (check with neos_list_pages), otherwise the write is rejected.'
19
+ 'A node:// target must exist in the workspace (check with neos_list_pages), otherwise the write is rejected. ' +
20
+ 'References (Neos 9: listed under "references" of the node type in neos_list_node_types, not under "properties"): ' +
21
+ '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); ' +
22
+ '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. ' +
23
+ 'The current targets are shown under "references" in neos_get_page_content / neos_get_document_properties.'
20
24
  ),
21
25
  workspace: z.string().default('mcp').describe('Workspace to write to'),
22
26
  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.'),
package/src/types.ts CHANGED
@@ -1,3 +1,5 @@
1
+ export type NodeReferences = Record<string, string | string[] | null> | [];
2
+
1
3
  export interface PageNode {
2
4
  // v2 (Neos 9) primary identifier
3
5
  nodeAggregateId?: string;
@@ -12,6 +14,8 @@ export interface PageNode {
12
14
  hidden: boolean;
13
15
  depth: number;
14
16
  properties?: Record<string, unknown>;
17
+ /** Keyed by reference name; the bridge sends an empty list ([]) instead of {} when the node type has none. */
18
+ references?: NodeReferences;
15
19
  }
16
20
 
17
21
  export interface ContentNode {
@@ -22,6 +26,8 @@ export interface ContentNode {
22
26
  nodeType: string;
23
27
  name: string;
24
28
  properties: Record<string, unknown>;
29
+ /** Keyed by reference name; the bridge sends an empty list ([]) instead of {} when the node type has none. */
30
+ references?: NodeReferences;
25
31
  }
26
32
 
27
33
  export interface NodeTypeProperty {
@@ -30,11 +36,19 @@ export interface NodeTypeProperty {
30
36
  label: string;
31
37
  }
32
38
 
39
+ export interface NodeTypeReference {
40
+ type: 'reference' | 'references';
41
+ label: string;
42
+ targetNodeTypes: string[] | null;
43
+ }
44
+
33
45
  export interface NodeTypeSchema {
34
46
  name: string;
35
47
  isContent: boolean;
36
48
  isDocument: boolean;
37
49
  properties: Record<string, NodeTypeProperty>;
50
+ /** An empty list ([]) instead of {} when the node type has none. */
51
+ references?: Record<string, NodeTypeReference> | [];
38
52
  }
39
53
 
40
54
  export interface PendingChange {
@@ -0,0 +1,85 @@
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
+
10
+ type Call = { url: string; body: any };
11
+
12
+ const realFetch = globalThis.fetch;
13
+ let calls: Call[] = [];
14
+ let client: Client;
15
+
16
+ /** Records bridge calls; the bridge resolves reference targets, so the client must pass them through untouched. */
17
+ function mockFetch() {
18
+ globalThis.fetch = (async (input: any, init: any = {}) => {
19
+ calls.push({ url: String(input), body: init.body ? JSON.parse(init.body) : undefined });
20
+ return new Response(JSON.stringify({ success: true }), {
21
+ status: 200,
22
+ headers: { 'content-type': 'application/json' },
23
+ });
24
+ }) as typeof fetch;
25
+ }
26
+
27
+ before(async () => {
28
+ setApiVersion(2);
29
+ const server = createServer();
30
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
31
+ client = new Client({ name: 'test', version: '0.0.0' });
32
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
33
+ });
34
+
35
+ after(() => {
36
+ globalThis.fetch = realFetch;
37
+ });
38
+
39
+ beforeEach(() => {
40
+ calls = [];
41
+ mockFetch();
42
+ });
43
+
44
+ test('neos_update_node_property: a list of reference targets is sent as an array', async () => {
45
+ const targets = ['brand-1', 'brand-2', 'brand-3'];
46
+ const result = await client.callTool({
47
+ name: 'neos_update_node_property',
48
+ arguments: { node_id: 'n1', property: 'brandReferences', value: targets },
49
+ });
50
+ assert.notEqual(result.isError, true);
51
+
52
+ assert.equal(calls[0].url, 'http://bridge.test/neos/mcp/updateNodeProperty');
53
+ assert.deepEqual(calls[0].body.value, targets);
54
+ });
55
+
56
+ test('neos_create_content_node: reference targets inside properties are sent unchanged', async () => {
57
+ const properties = { contactPersonReference: 'person-1', brandReferences: ['brand-1', 'brand-2'] };
58
+ const result = await client.callTool({
59
+ name: 'neos_create_content_node',
60
+ arguments: { parent_id: 'p1', node_type: 'Vendor.Site:Content.BrandSelection', properties },
61
+ });
62
+ assert.notEqual(result.isError, true);
63
+
64
+ assert.deepEqual(calls[0].body.properties, properties);
65
+ });
66
+
67
+ test('references are described on the tools that read and write them', async () => {
68
+ const { tools } = await client.listTools();
69
+ const byName = (name: string) => tools.find((t) => t.name === name);
70
+
71
+ const value = (byName('neos_update_node_property')?.inputSchema.properties as any)?.value?.description ?? '';
72
+ assert.match(value, /"references"/);
73
+ assert.match(value, /targetNodeTypes/);
74
+ assert.match(byName('neos_list_node_types')?.description ?? '', /targetNodeTypes/);
75
+ for (const name of ['neos_list_pages', 'neos_get_page_content', 'neos_get_document_properties', 'neos_get_site_context']) {
76
+ assert.match(byName(name)?.description ?? '', /"references"/, name);
77
+ }
78
+ });
79
+
80
+ test('the references block is described as Neos 9 only', async () => {
81
+ const { tools } = await client.listTools();
82
+ const value = (tools.find((t) => t.name === 'neos_update_node_property')?.inputSchema.properties as any)?.value?.description ?? '';
83
+ assert.match(value, /Neos 9/);
84
+ assert.match(tools.find((t) => t.name === 'neos_list_node_types')?.description ?? '', /Neos 8/);
85
+ });