@upassist/neos-mcp 2.2.0 → 2.3.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,18 @@
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.3.0](https://github.com/UpAssist/neos-mcp-client/compare/2.2.0...2.3.0) (2026-10-13)
6
+
7
+
8
+ ### Features
9
+
10
+ * add multi-site support to the tools ([#5](https://github.com/UpAssist/neos-mcp-client/issues/5)) ([dbffad3](https://github.com/UpAssist/neos-mcp-client/commit/dbffad3106b39f1f4ba21603e7adc078ca99892e))
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * refuse site-scoped publish when the bridge has no multi-site support ([0076e8d](https://github.com/UpAssist/neos-mcp-client/commit/0076e8deed841fe912c7aa22c97869378b8de8cb))
16
+
5
17
  ## [2.2.0](https://github.com/UpAssist/neos-mcp-client/compare/2.1.0...2.2.0) (2026-10-12)
6
18
 
7
19
 
package/README.md CHANGED
@@ -13,6 +13,8 @@ This is the client-side component. It runs locally on your machine and translate
13
13
 
14
14
  > **v2 auto-detects** the bridge API version. A single MCP server v2 works with both Neos 8 and Neos 9 bridges.
15
15
 
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
+
16
18
  > **`neos_upload_asset`** (client 2.1+) needs a bridge with the `uploadAsset` endpoint: upassist/neos-mcp **2.1+** (Neos 9) or **1.1+** (Neos 8). Against an older bridge the other tools keep working and the upload call fails with a 404.
17
19
 
18
20
  ## Requirements
@@ -127,6 +129,7 @@ Once connected, your AI assistant can use these tools:
127
129
 
128
130
  | Tool | Description |
129
131
  | --- | --- |
132
+ | `neos_list_sites` | List all sites of the Neos instance and which one is the default |
130
133
  | `neos_get_site_context` | Get site structure, node types, and page tree. **Call this first.** |
131
134
  | `neos_list_pages` | List all pages in a workspace |
132
135
  | `neos_get_page_content` | Get all content nodes on a specific page |
@@ -183,6 +186,16 @@ Optional: `filename` (overrides the name taken from the path or URL), `title`, `
183
186
  | `neos_list_pending_changes` | See what has been changed |
184
187
  | `neos_publish_changes` | Publish all changes to live |
185
188
 
189
+ ### Multi-site
190
+
191
+ A Neos instance can host several sites. Without further input the tools work on the instance's default site. `neos_list_sites` shows all sites; pass a site node name as `site` to:
192
+
193
+ - `neos_get_site_context` and `neos_list_pages`: context and page tree of that site,
194
+ - `neos_list_pending_changes`: only the changes of that site (without `site`, each change shows its site),
195
+ - `neos_publish_changes`: publish only that site's changes. **Without `site`, the changes of all sites go live.**
196
+
197
+ 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
+
186
199
  ### Entity management
187
200
 
188
201
  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,10 +21066,12 @@ 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.",
21070
- {},
21071
- async () => {
21072
- const data = await callBridge("getSiteContext", "GET");
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.',
21070
+ {
21071
+ site: external_exports.string().optional().describe("Site node name (see neos_list_sites). Defaults to the default site of the instance.")
21072
+ },
21073
+ async ({ site }) => {
21074
+ const data = await callBridge("getSiteContext", "GET", { site });
21073
21075
  if (data && typeof data === "object" && "apiVersion" in data && data.apiVersion === 2) {
21074
21076
  setApiVersion(2);
21075
21077
  } else {
@@ -21080,6 +21082,19 @@ function registerGetSiteContext(server) {
21080
21082
  );
21081
21083
  }
21082
21084
 
21085
+ // src/tools/listSites.ts
21086
+ function registerListSites(server) {
21087
+ server.tool(
21088
+ "neos_list_sites",
21089
+ 'List all sites of the Neos instance: name, node name, online state, domains and which one is the default site. Pass a site node name as "site" to neos_get_site_context, neos_list_pages, neos_list_pending_changes and neos_publish_changes to work on a site other than the default one.',
21090
+ {},
21091
+ async () => {
21092
+ const data = await callBridge("listSites", "GET");
21093
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21094
+ }
21095
+ );
21096
+ }
21097
+
21083
21098
  // src/tools/setupWorkspace.ts
21084
21099
  function registerSetupWorkspace(server) {
21085
21100
  server.tool(
@@ -21099,10 +21114,11 @@ function registerListPages(server) {
21099
21114
  "neos_list_pages",
21100
21115
  "List all document nodes (pages) in the Neos CMS site as a flat tree with paths and titles.",
21101
21116
  {
21102
- workspace: external_exports.string().default("mcp").describe('Workspace name. Use "live" for published content, "mcp" for staged changes.')
21117
+ 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.")
21103
21119
  },
21104
- async ({ workspace }) => {
21105
- const data = await callBridge("listPages", "GET", { workspace });
21120
+ async ({ workspace, site }) => {
21121
+ const data = await callBridge("listPages", "GET", { workspace, site });
21106
21122
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21107
21123
  }
21108
21124
  );
@@ -21163,10 +21179,11 @@ function registerListPendingChanges(server) {
21163
21179
  "neos_list_pending_changes",
21164
21180
  "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.",
21165
21181
  {
21166
- workspace: external_exports.string().default("mcp").describe("Workspace name to check for pending changes")
21182
+ 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".')
21167
21184
  },
21168
- async ({ workspace }) => {
21169
- const data = await callBridge("listPendingChanges", "GET", { workspace });
21185
+ async ({ workspace, site }) => {
21186
+ const data = await callBridge("listPendingChanges", "GET", { workspace, site });
21170
21187
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21171
21188
  }
21172
21189
  );
@@ -21267,12 +21284,23 @@ function registerDeleteNode(server) {
21267
21284
  function registerPublishChanges(server) {
21268
21285
  server.tool(
21269
21286
  "neos_publish_changes",
21270
- "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.",
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.',
21271
21288
  {
21272
- workspace: external_exports.string().default("mcp").describe("Workspace to publish from")
21289
+ 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.")
21273
21291
  },
21274
- async ({ workspace }) => {
21275
- const data = await callBridge("publishChanges", "POST", { workspace });
21292
+ async ({ workspace, site }) => {
21293
+ if (site) {
21294
+ try {
21295
+ await callBridge("listSites", "GET");
21296
+ } catch (error2) {
21297
+ const reason = error2 instanceof Error ? error2.message : String(error2);
21298
+ throw new Error(
21299
+ `Not published: could not confirm that the bridge supports multi-site (${reason}). A bridge without multi-site support would publish the changes of all sites. Update the bridge (upassist/neos-mcp 2.3+ for Neos 9, 1.2+ for Neos 8) or publish without "site" if that is what you want.`
21300
+ );
21301
+ }
21302
+ }
21303
+ const data = await callBridge("publishChanges", "POST", { workspace, site });
21276
21304
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21277
21305
  }
21278
21306
  );
@@ -21563,6 +21591,7 @@ function createServer() {
21563
21591
  version: "0.1.0"
21564
21592
  });
21565
21593
  registerGetSiteContext(server);
21594
+ registerListSites(server);
21566
21595
  registerSetupWorkspace(server);
21567
21596
  registerListPages(server);
21568
21597
  registerGetPageContent(server);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@upassist/neos-mcp",
3
- "version": "2.2.0",
3
+ "version": "2.3.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": {
package/src/server.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import { registerGetSiteContext } from './tools/getSiteContext.js';
3
+ import { registerListSites } from './tools/listSites.js';
3
4
  import { registerSetupWorkspace } from './tools/setupWorkspace.js';
4
5
  import { registerListPages } from './tools/listPages.js';
5
6
  import { registerGetPageContent } from './tools/getPageContent.js';
@@ -26,6 +27,7 @@ export function createServer(): McpServer {
26
27
  });
27
28
 
28
29
  registerGetSiteContext(server);
30
+ registerListSites(server);
29
31
  registerSetupWorkspace(server);
30
32
  registerListPages(server);
31
33
  registerGetPageContent(server);
@@ -1,13 +1,17 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import { z } from 'zod';
2
3
  import { callBridge, setApiVersion } from '../bridge.js';
3
4
 
4
5
  export function registerGetSiteContext(server: McpServer): void {
5
6
  server.tool(
6
7
  'neos_get_site_context',
7
- 'Get the site context: site name, available content NodeTypes with their properties, current page tree, and editorial workflow instructions. Always call this first at the start of any Neos content editing session.',
8
- {},
9
- async () => {
10
- const data = await callBridge('getSiteContext', 'GET') as Record<string, unknown>;
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.',
10
+ {
11
+ site: z.string().optional().describe('Site node name (see neos_list_sites). Defaults to the default site of the instance.'),
12
+ },
13
+ async ({ site }) => {
14
+ const data = await callBridge('getSiteContext', 'GET', { site }) as Record<string, unknown>;
11
15
 
12
16
  // Auto-detect bridge API version
13
17
  if (data && typeof data === 'object' && 'apiVersion' in data && data.apiVersion === 2) {
@@ -8,9 +8,10 @@ export function registerListPages(server: McpServer): void {
8
8
  'List all document nodes (pages) in the Neos CMS site as a flat tree with paths and titles.',
9
9
  {
10
10
  workspace: z.string().default('mcp').describe('Workspace name. Use "live" for published content, "mcp" for staged changes.'),
11
+ site: z.string().optional().describe('Site node name (see neos_list_sites). Defaults to the default site of the instance.'),
11
12
  },
12
- async ({ workspace }) => {
13
- const data = await callBridge('listPages', 'GET', { workspace });
13
+ async ({ workspace, site }) => {
14
+ const data = await callBridge('listPages', 'GET', { workspace, site });
14
15
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
15
16
  }
16
17
  );
@@ -8,9 +8,10 @@ export function registerListPendingChanges(server: McpServer): void {
8
8
  '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.',
9
9
  {
10
10
  workspace: z.string().default('mcp').describe('Workspace name to check for pending changes'),
11
+ 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".'),
11
12
  },
12
- async ({ workspace }) => {
13
- const data = await callBridge('listPendingChanges', 'GET', { workspace });
13
+ async ({ workspace, site }) => {
14
+ const data = await callBridge('listPendingChanges', 'GET', { workspace, site });
14
15
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
15
16
  }
16
17
  );
@@ -0,0 +1,15 @@
1
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import { callBridge } from '../bridge.js';
3
+
4
+ export function registerListSites(server: McpServer): void {
5
+ server.tool(
6
+ 'neos_list_sites',
7
+ 'List all sites of the Neos instance: name, node name, online state, domains and which one is the default site. ' +
8
+ 'Pass a site node name as "site" to neos_get_site_context, neos_list_pages, neos_list_pending_changes and neos_publish_changes to work on a site other than the default one.',
9
+ {},
10
+ async () => {
11
+ const data = await callBridge('listSites', 'GET');
12
+ return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
13
+ }
14
+ );
15
+ }
@@ -5,12 +5,28 @@ import { callBridge } from '../bridge.js';
5
5
  export function registerPublishChanges(server: McpServer): void {
6
6
  server.tool(
7
7
  'neos_publish_changes',
8
- '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.',
8
+ '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.',
9
10
  {
10
11
  workspace: z.string().default('mcp').describe('Workspace to publish from'),
12
+ 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.'),
11
13
  },
12
- async ({ workspace }) => {
13
- const data = await callBridge('publishChanges', 'POST', { workspace });
14
+ async ({ workspace, site }) => {
15
+ if (site) {
16
+ // A bridge without multi-site support ignores "site" and would publish the changes of
17
+ // all sites. Publishing cannot be undone, so only go ahead when the bridge knows sites.
18
+ try {
19
+ await callBridge('listSites', 'GET');
20
+ } catch (error) {
21
+ const reason = error instanceof Error ? error.message : String(error);
22
+ throw new Error(
23
+ `Not published: could not confirm that the bridge supports multi-site (${reason}). ` +
24
+ 'A bridge without multi-site support would publish the changes of all sites. ' +
25
+ 'Update the bridge (upassist/neos-mcp 2.3+ for Neos 9, 1.2+ for Neos 8) or publish without "site" if that is what you want.'
26
+ );
27
+ }
28
+ }
29
+ const data = await callBridge('publishChanges', 'POST', { workspace, site });
14
30
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
15
31
  }
16
32
  );
@@ -0,0 +1,116 @@
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: URL; method: string; body: any };
11
+
12
+ const realFetch = globalThis.fetch;
13
+ let calls: Call[] = [];
14
+ let client: Client;
15
+
16
+ /** Records bridge calls and answers with a minimal v2 payload. */
17
+ function mockFetch() {
18
+ globalThis.fetch = (async (input: any, init: any = {}) => {
19
+ calls.push({
20
+ url: new URL(String(input)),
21
+ method: init.method ?? 'GET',
22
+ body: init.body ? JSON.parse(init.body) : undefined,
23
+ });
24
+ return new Response(JSON.stringify({ apiVersion: 2, success: true }), {
25
+ status: 200,
26
+ headers: { 'content-type': 'application/json' },
27
+ });
28
+ }) as typeof fetch;
29
+ }
30
+
31
+ before(async () => {
32
+ setApiVersion(2);
33
+ const server = createServer();
34
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
35
+ client = new Client({ name: 'test', version: '0.0.0' });
36
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
37
+ });
38
+
39
+ after(() => {
40
+ globalThis.fetch = realFetch;
41
+ });
42
+
43
+ beforeEach(() => {
44
+ calls = [];
45
+ mockFetch();
46
+ });
47
+
48
+ async function call(name: string, args: Record<string, unknown> = {}) {
49
+ const result = await client.callTool({ name, arguments: args });
50
+ assert.notEqual(result.isError, true, JSON.stringify(result.content));
51
+ assert.equal(calls.length, 1);
52
+ return calls[0];
53
+ }
54
+
55
+ test('neos_list_sites is registered and calls listSites', async () => {
56
+ const { tools } = await client.listTools();
57
+ assert.ok(tools.some((t) => t.name === 'neos_list_sites'));
58
+
59
+ const request = await call('neos_list_sites');
60
+ assert.equal(request.url.pathname, '/neos/mcp/listSites');
61
+ assert.equal(request.method, 'GET');
62
+ });
63
+
64
+ test('neos_get_site_context passes "site" only when given', async () => {
65
+ const withSite = await call('neos_get_site_context', { site: 'azubi' });
66
+ assert.equal(withSite.url.pathname, '/neos/mcp/getSiteContext');
67
+ assert.equal(withSite.url.searchParams.get('site'), 'azubi');
68
+
69
+ calls = [];
70
+ const withoutSite = await call('neos_get_site_context');
71
+ assert.equal(withoutSite.url.searchParams.has('site'), false);
72
+ });
73
+
74
+ test('neos_list_pages and neos_list_pending_changes pass "site" as query parameter', async () => {
75
+ const pages = await call('neos_list_pages', { site: 'azubi' });
76
+ assert.equal(pages.url.pathname, '/neos/mcp/listPages');
77
+ assert.equal(pages.url.searchParams.get('site'), 'azubi');
78
+ assert.equal(pages.url.searchParams.get('workspace'), 'mcp');
79
+
80
+ calls = [];
81
+ const changes = await call('neos_list_pending_changes', { site: 'site' });
82
+ assert.equal(changes.url.pathname, '/neos/mcp/listPendingChanges');
83
+ assert.equal(changes.url.searchParams.get('site'), 'site');
84
+ });
85
+
86
+ test('neos_publish_changes checks multi-site support, then sends "site" in the body, and no site without it', async () => {
87
+ const result = await client.callTool({ name: 'neos_publish_changes', arguments: { site: 'azubi' } });
88
+ assert.notEqual(result.isError, true);
89
+ assert.equal(calls.length, 2);
90
+ assert.equal(calls[0].url.pathname, '/neos/mcp/listSites');
91
+ const perSite = calls[1];
92
+ assert.equal(perSite.url.pathname, '/neos/mcp/publishChanges');
93
+ assert.equal(perSite.method, 'POST');
94
+ assert.deepEqual(perSite.body, { workspace: 'mcp', site: 'azubi' });
95
+
96
+ calls = [];
97
+ const all = await call('neos_publish_changes');
98
+ assert.deepEqual(all.body, { workspace: 'mcp' });
99
+ });
100
+
101
+ test('the publish tool warns that without "site" all sites go live', async () => {
102
+ const { tools } = await client.listTools();
103
+ const tool = tools.find((t) => t.name === 'neos_publish_changes');
104
+ assert.match(tool?.description ?? '', /all sites/);
105
+ });
106
+
107
+ test('neos_publish_changes with "site" does not publish when the bridge has no multi-site support', async () => {
108
+ globalThis.fetch = (async (input: any, init: any = {}) => {
109
+ calls.push({ url: new URL(String(input)), method: init.method ?? 'GET', body: init.body ? JSON.parse(init.body) : undefined });
110
+ return new Response(JSON.stringify({ error: 'Not found' }), { status: 404, headers: { 'content-type': 'application/json' } });
111
+ }) as typeof fetch;
112
+
113
+ const result = await client.callTool({ name: 'neos_publish_changes', arguments: { site: 'azubi' } });
114
+ assert.equal(result.isError, true);
115
+ assert.deepEqual(calls.map((c) => c.url.pathname), ['/neos/mcp/listSites']);
116
+ });