@upassist/neos-mcp 2.0.2 → 2.1.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,13 @@
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.1.0](https://github.com/UpAssist/neos-mcp-client/compare/2.0.2...2.1.0) (2026-10-08)
6
+
7
+
8
+ ### Features
9
+
10
+ * add neos_upload_asset tool ([0870e67](https://github.com/UpAssist/neos-mcp-client/commit/0870e6756da461b051fa51c50a6dea41faddead6))
11
+
5
12
  ### [2.0.2](https://github.com/UpAssist/neos-mcp-client/compare/2.0.1...2.0.2) (2026-09-23)
6
13
 
7
14
 
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
+ > **`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
+
16
18
  ## Requirements
17
19
 
18
20
  - Node.js 18+
@@ -148,6 +150,25 @@ Once connected, your AI assistant can use these tools:
148
150
  | --- | --- |
149
151
  | `neos_list_assets` | Browse images and files from the Media Manager |
150
152
  | `neos_list_asset_tags` | List available asset tags |
153
+ | `neos_upload_asset` | Upload a file (local path, URL or base64) to the Media Manager, incl. title, caption, tags and collections. Identical files are deduplicated. |
154
+
155
+ #### Uploading files
156
+
157
+ `neos_upload_asset` takes exactly one source:
158
+
159
+ | Parameter | Description |
160
+ | --- | --- |
161
+ | `file_path` | Absolute path of a local file, read by this MCP server |
162
+ | `url` | HTTP(S) URL, downloaded by this MCP server (the Neos bridge never fetches remote URLs) |
163
+ | `base64_content` | Raw base64 content (a `data:` URI prefix is allowed); requires `filename` |
164
+
165
+ Optional: `filename` (overrides the name taken from the path or URL), `title`, `caption`, `copyright_notice`, `tags`, `asset_collections` (missing tags and collections are created) and `allow_duplicate`.
166
+
167
+ - The result contains the asset `identifier`, which you can pass to `neos_update_node_property` (or the create tools) for image/asset properties.
168
+ - If a file with identical content already exists, that asset is returned with `duplicate: true` and the title, caption, tags and collections you passed are **not** applied to it. Set `allow_duplicate` to force a new asset.
169
+ - The file travels as base64 in one request, so it is about 33% larger on the wire. The size limit is set by the bridge's PHP (`post_max_size`) and web server configuration. Large files are better added through the Media Manager.
170
+ - Requires a bridge that has the `uploadAsset` endpoint (see the [bridge README](https://github.com/UpAssist/neos-mcp#post-neosmcpuploadasset)). It works with both the Neos 8 and the Neos 9 bridge.
171
+ - A rejected token comes back as a bridge error `401` or `403`.
151
172
 
152
173
  ### Review and publish
153
174
 
@@ -204,6 +225,9 @@ npm run dev
204
225
  # Type check
205
226
  npm run typecheck
206
227
 
228
+ # Run the unit tests
229
+ npm test
230
+
207
231
  # Build for production
208
232
  npm run build
209
233
 
@@ -211,6 +235,10 @@ npm run build
211
235
  npm start
212
236
  ```
213
237
 
238
+ ### Tests
239
+
240
+ `npm test` bundles `test/*.test.ts` with esbuild and runs them with Node's built-in test runner. The tests start the real MCP server in-process (via the SDK's in-memory transport) and replace `fetch`, so they check the exact HTTP requests sent to the bridge without needing a Neos instance. For a true end-to-end check, point `NEOS_MCP_URL` at a Neos instance with the bridge installed and call the tool through any MCP client.
241
+
214
242
  ### Adding a new tool
215
243
 
216
244
  1. Create a file in `src/tools/` (e.g. `myNewTool.ts`)
package/dist/index.js CHANGED
@@ -21491,6 +21491,69 @@ function registerEntityCrudTools(server) {
21491
21491
  );
21492
21492
  }
21493
21493
 
21494
+ // src/tools/uploadAsset.ts
21495
+ var import_promises = require("node:fs/promises");
21496
+ var import_node_path = require("node:path");
21497
+ async function loadSource(filePath, url, base64Content, filename) {
21498
+ const sources = [filePath, url, base64Content].filter((s) => s !== void 0 && s !== "");
21499
+ if (sources.length !== 1) {
21500
+ throw new Error("Provide exactly one of file_path, url or base64_content.");
21501
+ }
21502
+ if (filePath) {
21503
+ const buffer = await (0, import_promises.readFile)(filePath);
21504
+ return { filename: filename || (0, import_node_path.basename)(filePath), content: buffer.toString("base64") };
21505
+ }
21506
+ if (url) {
21507
+ const response = await fetch(url);
21508
+ if (!response.ok) {
21509
+ throw new Error(`Download failed (${response.status}): ${url}`);
21510
+ }
21511
+ const buffer = Buffer.from(await response.arrayBuffer());
21512
+ const urlFilename = decodeURIComponent((0, import_node_path.basename)(new URL(url).pathname));
21513
+ const resolvedFilename = filename || urlFilename;
21514
+ if (!resolvedFilename) {
21515
+ throw new Error("Could not derive a filename from the URL, please pass filename.");
21516
+ }
21517
+ return { filename: resolvedFilename, content: buffer.toString("base64") };
21518
+ }
21519
+ if (!filename) {
21520
+ throw new Error("filename is required when using base64_content.");
21521
+ }
21522
+ return { filename, content: base64Content.replace(/^data:[^;]+;base64,/, "") };
21523
+ }
21524
+ function registerUploadAsset(server) {
21525
+ server.tool(
21526
+ "neos_upload_asset",
21527
+ "Upload a file (image, PDF, video, \u2026) into the Neos Media Manager. Provide exactly one source: a local file_path, a url to download, or base64_content. If a file with identical content already exists, the existing asset is returned (duplicate: true). The returned identifier can be used as value for image/asset properties via neos_update_node_property.",
21528
+ {
21529
+ file_path: external_exports.string().optional().describe("Absolute path to a local file to upload"),
21530
+ url: external_exports.string().optional().describe("HTTP(S) URL of a file to download and upload"),
21531
+ base64_content: external_exports.string().optional().describe("Base64 encoded file content (data URI prefix allowed); requires filename"),
21532
+ filename: external_exports.string().optional().describe("Target filename incl. extension. Defaults to the name from file_path or url."),
21533
+ title: external_exports.string().default("").describe("Asset title"),
21534
+ caption: external_exports.string().default("").describe("Asset caption"),
21535
+ copyright_notice: external_exports.string().default("").describe("Copyright notice"),
21536
+ tags: external_exports.array(external_exports.string()).default([]).describe("Tag labels to assign; missing tags are created"),
21537
+ asset_collections: external_exports.array(external_exports.string()).default([]).describe("Asset collection titles to add the asset to; missing collections are created"),
21538
+ allow_duplicate: external_exports.boolean().default(false).describe("Create a new asset even if identical content already exists")
21539
+ },
21540
+ async ({ file_path, url, base64_content, filename, title, caption, copyright_notice, tags, asset_collections, allow_duplicate }) => {
21541
+ const source = await loadSource(file_path, url, base64_content, filename);
21542
+ const data = await callBridge("uploadAsset", "POST", {
21543
+ filename: source.filename,
21544
+ content: source.content,
21545
+ title,
21546
+ caption,
21547
+ copyrightNotice: copyright_notice,
21548
+ tags,
21549
+ assetCollections: asset_collections,
21550
+ allowDuplicate: allow_duplicate
21551
+ });
21552
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
21553
+ }
21554
+ );
21555
+ }
21556
+
21494
21557
  // src/server.ts
21495
21558
  function createServer() {
21496
21559
  const server = new McpServer({
@@ -21514,6 +21577,7 @@ function createServer() {
21514
21577
  registerRestart(server);
21515
21578
  registerListAssets(server);
21516
21579
  registerListAssetTags(server);
21580
+ registerUploadAsset(server);
21517
21581
  registerEntityCrudTools(server);
21518
21582
  return server;
21519
21583
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@upassist/neos-mcp",
3
- "version": "2.0.2",
3
+ "version": "2.1.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": {
@@ -16,7 +16,8 @@
16
16
  "release:patch": "npx standard-version -t '' -r patch && npm publish --access public && git push --follow-tags",
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
- "release": "yarn release:patch"
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
21
  },
21
22
  "engines": {
22
23
  "node": ">=18.0.0"
package/src/server.ts CHANGED
@@ -17,6 +17,7 @@ import { registerRestart } from './tools/restart.js';
17
17
  import { registerListAssets } from './tools/listAssets.js';
18
18
  import { registerListAssetTags } from './tools/listAssetTags.js';
19
19
  import { registerEntityCrudTools } from './tools/entityCrud.js';
20
+ import { registerUploadAsset } from './tools/uploadAsset.js';
20
21
 
21
22
  export function createServer(): McpServer {
22
23
  const server = new McpServer({
@@ -41,6 +42,7 @@ export function createServer(): McpServer {
41
42
  registerRestart(server);
42
43
  registerListAssets(server);
43
44
  registerListAssetTags(server);
45
+ registerUploadAsset(server);
44
46
  registerEntityCrudTools(server);
45
47
 
46
48
  return server;
@@ -0,0 +1,74 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { basename } from 'node:path';
3
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
4
+ import { z } from 'zod';
5
+ import { callBridge } from '../bridge.js';
6
+
7
+ async function loadSource(
8
+ filePath?: string,
9
+ url?: string,
10
+ base64Content?: string,
11
+ filename?: string
12
+ ): Promise<{ filename: string; content: string }> {
13
+ const sources = [filePath, url, base64Content].filter((s) => s !== undefined && s !== '');
14
+ if (sources.length !== 1) {
15
+ throw new Error('Provide exactly one of file_path, url or base64_content.');
16
+ }
17
+
18
+ if (filePath) {
19
+ const buffer = await readFile(filePath);
20
+ return { filename: filename || basename(filePath), content: buffer.toString('base64') };
21
+ }
22
+
23
+ if (url) {
24
+ const response = await fetch(url);
25
+ if (!response.ok) {
26
+ throw new Error(`Download failed (${response.status}): ${url}`);
27
+ }
28
+ const buffer = Buffer.from(await response.arrayBuffer());
29
+ const urlFilename = decodeURIComponent(basename(new URL(url).pathname));
30
+ const resolvedFilename = filename || urlFilename;
31
+ if (!resolvedFilename) {
32
+ throw new Error('Could not derive a filename from the URL, please pass filename.');
33
+ }
34
+ return { filename: resolvedFilename, content: buffer.toString('base64') };
35
+ }
36
+
37
+ if (!filename) {
38
+ throw new Error('filename is required when using base64_content.');
39
+ }
40
+ return { filename, content: (base64Content as string).replace(/^data:[^;]+;base64,/, '') };
41
+ }
42
+
43
+ export function registerUploadAsset(server: McpServer): void {
44
+ server.tool(
45
+ 'neos_upload_asset',
46
+ 'Upload a file (image, PDF, video, …) into the Neos Media Manager. Provide exactly one source: a local file_path, a url to download, or base64_content. If a file with identical content already exists, the existing asset is returned (duplicate: true). The returned identifier can be used as value for image/asset properties via neos_update_node_property.',
47
+ {
48
+ file_path: z.string().optional().describe('Absolute path to a local file to upload'),
49
+ url: z.string().optional().describe('HTTP(S) URL of a file to download and upload'),
50
+ base64_content: z.string().optional().describe('Base64 encoded file content (data URI prefix allowed); requires filename'),
51
+ filename: z.string().optional().describe('Target filename incl. extension. Defaults to the name from file_path or url.'),
52
+ title: z.string().default('').describe('Asset title'),
53
+ caption: z.string().default('').describe('Asset caption'),
54
+ copyright_notice: z.string().default('').describe('Copyright notice'),
55
+ tags: z.array(z.string()).default([]).describe('Tag labels to assign; missing tags are created'),
56
+ asset_collections: z.array(z.string()).default([]).describe('Asset collection titles to add the asset to; missing collections are created'),
57
+ allow_duplicate: z.boolean().default(false).describe('Create a new asset even if identical content already exists'),
58
+ },
59
+ async ({ file_path, url, base64_content, filename, title, caption, copyright_notice, tags, asset_collections, allow_duplicate }) => {
60
+ const source = await loadSource(file_path, url, base64_content, filename);
61
+ const data = await callBridge('uploadAsset', 'POST', {
62
+ filename: source.filename,
63
+ content: source.content,
64
+ title,
65
+ caption,
66
+ copyrightNotice: copyright_notice,
67
+ tags,
68
+ assetCollections: asset_collections,
69
+ allowDuplicate: allow_duplicate,
70
+ });
71
+ return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
72
+ }
73
+ );
74
+ }
@@ -0,0 +1,3 @@
1
+ // Imported first: src/bridge.ts reads these at module load time, and ES imports are hoisted.
2
+ process.env.NEOS_MCP_URL = 'http://bridge.test';
3
+ process.env.NEOS_MCP_TOKEN = 'unit-test-token';
@@ -0,0 +1,144 @@
1
+ import { test, before, after, beforeEach } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
4
+ import { tmpdir } from 'node:os';
5
+ import { join } from 'node:path';
6
+
7
+ import './support/env.js';
8
+ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
9
+ import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
10
+ import { createServer } from '../src/server.js';
11
+
12
+ type Call = { url: string; method: string; headers: Record<string, string>; body: any };
13
+
14
+ const realFetch = globalThis.fetch;
15
+ let calls: Call[] = [];
16
+ let tmp: string;
17
+ let client: Client;
18
+
19
+ const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==', 'base64');
20
+
21
+ /** Replaces fetch: remote downloads get `remote`, bridge calls are recorded and answered with a canned asset. */
22
+ function mockFetch(remote: { status?: number; body?: Buffer } = {}) {
23
+ globalThis.fetch = (async (input: any, init: any = {}) => {
24
+ const url = String(input);
25
+ if (url.startsWith('http://bridge.test/')) {
26
+ calls.push({
27
+ url,
28
+ method: init.method ?? 'GET',
29
+ headers: init.headers ?? {},
30
+ body: init.body ? JSON.parse(init.body) : undefined,
31
+ });
32
+ return new Response(JSON.stringify({ success: true, duplicate: false, asset: { identifier: 'abc', filename: 'x' } }), {
33
+ status: 200,
34
+ headers: { 'content-type': 'application/json' },
35
+ });
36
+ }
37
+ return new Response(remote.body ?? Buffer.alloc(0), { status: remote.status ?? 200 });
38
+ }) as typeof fetch;
39
+ }
40
+
41
+ async function callUpload(args: Record<string, unknown>) {
42
+ return client.callTool({ name: 'neos_upload_asset', arguments: args });
43
+ }
44
+
45
+ before(async () => {
46
+ tmp = mkdtempSync(join(tmpdir(), 'neos-mcp-upload-'));
47
+ writeFileSync(join(tmp, 'photo.png'), PNG);
48
+ const server = createServer();
49
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
50
+ client = new Client({ name: 'test', version: '0.0.0' });
51
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
52
+ });
53
+
54
+ after(() => {
55
+ globalThis.fetch = realFetch;
56
+ rmSync(tmp, { recursive: true, force: true });
57
+ });
58
+
59
+ beforeEach(() => {
60
+ calls = [];
61
+ mockFetch();
62
+ });
63
+
64
+ test('the tool is registered', async () => {
65
+ const { tools } = await client.listTools();
66
+ assert.ok(tools.some((t) => t.name === 'neos_upload_asset'));
67
+ });
68
+
69
+ test('file_path: reads the file, defaults the filename, base64-encodes it and posts to uploadAsset', async () => {
70
+ const result = await callUpload({ file_path: join(tmp, 'photo.png'), title: 'T', tags: ['a'], asset_collections: ['C'] });
71
+ assert.notEqual(result.isError, true);
72
+
73
+ assert.equal(calls.length, 1);
74
+ const [call] = calls;
75
+ assert.equal(call.url, 'http://bridge.test/neos/mcp/uploadAsset');
76
+ assert.equal(call.method, 'POST');
77
+ assert.equal(call.body.filename, 'photo.png');
78
+ assert.equal(call.body.content, PNG.toString('base64'));
79
+ assert.equal(call.body.title, 'T');
80
+ assert.deepEqual(call.body.tags, ['a']);
81
+ assert.deepEqual(call.body.assetCollections, ['C']);
82
+ assert.equal(call.body.allowDuplicate, false);
83
+ assert.equal(call.headers['Authorization'], 'Bearer unit-test-token');
84
+ });
85
+
86
+ test('file_path: an explicit filename wins over the path', async () => {
87
+ await callUpload({ file_path: join(tmp, 'photo.png'), filename: 'renamed.png' });
88
+ assert.equal(calls[0].body.filename, 'renamed.png');
89
+ });
90
+
91
+ test('url: downloads client-side and uploads the bytes, filename derived from the URL', async () => {
92
+ mockFetch({ body: PNG });
93
+ await callUpload({ url: 'https://example.com/some%20dir/Logo%20Final.png?x=1' });
94
+ assert.equal(calls[0].body.filename, 'Logo Final.png');
95
+ assert.equal(calls[0].body.content, PNG.toString('base64'));
96
+ });
97
+
98
+ test('url: a failed download is reported as a tool error and nothing reaches the bridge', async () => {
99
+ mockFetch({ status: 404 });
100
+ const result = await callUpload({ url: 'https://example.com/missing.png' });
101
+ assert.equal(result.isError, true);
102
+ assert.match(JSON.stringify(result.content), /Download failed \(404\)/);
103
+ assert.equal(calls.length, 0);
104
+ });
105
+
106
+ test('base64_content: strips a data: URI prefix and requires a filename', async () => {
107
+ await callUpload({ base64_content: `data:image/png;base64,${PNG.toString('base64')}`, filename: 'inline.png' });
108
+ assert.equal(calls[0].body.content, PNG.toString('base64'));
109
+ assert.equal(calls[0].body.filename, 'inline.png');
110
+
111
+ calls = [];
112
+ const result = await callUpload({ base64_content: PNG.toString('base64') });
113
+ assert.equal(result.isError, true);
114
+ assert.match(JSON.stringify(result.content), /filename is required/);
115
+ assert.equal(calls.length, 0);
116
+ });
117
+
118
+ test('exactly one source must be given', async () => {
119
+ for (const args of [{}, { file_path: join(tmp, 'photo.png'), url: 'https://example.com/a.png' }]) {
120
+ const result = await callUpload(args);
121
+ assert.equal(result.isError, true);
122
+ assert.match(JSON.stringify(result.content), /exactly one of file_path, url or base64_content/);
123
+ }
124
+ assert.equal(calls.length, 0);
125
+ });
126
+
127
+ test('a missing local file is a tool error', async () => {
128
+ const result = await callUpload({ file_path: join(tmp, 'does-not-exist.png') });
129
+ assert.equal(result.isError, true);
130
+ assert.equal(calls.length, 0);
131
+ });
132
+
133
+ test('allow_duplicate and copyright_notice are passed to the bridge under the bridge parameter names', async () => {
134
+ await callUpload({ file_path: join(tmp, 'photo.png'), allow_duplicate: true, copyright_notice: '(c) me', caption: 'cap' });
135
+ assert.equal(calls[0].body.allowDuplicate, true);
136
+ assert.equal(calls[0].body.copyrightNotice, '(c) me');
137
+ assert.equal(calls[0].body.caption, 'cap');
138
+ });
139
+
140
+ test('the bridge response is returned to the caller', async () => {
141
+ const result = await callUpload({ file_path: join(tmp, 'photo.png') });
142
+ const text = (result.content as Array<{ text: string }>)[0].text;
143
+ assert.equal(JSON.parse(text).asset.identifier, 'abc');
144
+ });