@iobroker/mcp-server 1.4.0 → 1.5.0

package/build/index.js

@@ -9,6 +9,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_net_1 = __importDefault(require("node:net"));
 const node_dns_1 = __importDefault(require("node:dns"));
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const zod_1 = require("zod");
 const express_1 = __importDefault(require("express"));
@@ -79,6 +80,43 @@ const DEFAULT_MAX_READ_BYTES = 512 * 1024;
 const DEFAULT_INSTALL_TIMEOUT = 300;
 /** How many output lines of an installation are returned to the client. */
 const INSTALL_OUTPUT_LINES = 100;
+/**
+ * Maximum size of a tool result. MCP clients (Claude.ai / Claude Desktop / Claude Code) reject results above
+ * 1 MiB, measured on the JSON-RPC message, in which the result text is escaped once more.
+ */
+const MAX_RESULT_BYTES = 900 * 1024;
+/** How long a download or upload link stays valid (ms). */
+const TRANSFER_TTL = 15 * 60_000;
+/** Largest file that can be uploaded through a link (it travels base64-encoded in a message to the host). */
+const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+/** Size of a text inside the JSON-RPC message, where it is escaped once more. */
+function wireSize(text) {
+    return Buffer.byteLength(JSON.stringify(text));
+}
+/**
+ * Take the items from `offset` on, as many as fit into a tool result next to the rest of the answer.
+ * With `fromEnd`, the last items are kept instead (the newest log lines).
+ */
+function fitItems(all, offset = 0, fromEnd = false) {
+    const budget = MAX_RESULT_BYTES - 16 * 1024;
+    const items = all.slice(offset);
+    let size = 0;
+    let count = 0;
+    while (count < items.length) {
+        const item = items[fromEnd ? items.length - 1 - count : count];
+        size += wireSize(JSON.stringify(item)) + 1;
+        if (size > budget) {
+            break;
+        }
+        count++;
+    }
+    if (count === items.length) {
+        return { items, total: all.length, offset, truncated: false };
+    }
+    return fromEnd
+        ? { items: items.slice(items.length - count), total: all.length, offset, truncated: true }
+        : { items: items.slice(0, count), total: all.length, offset, nextOffset: offset + count, truncated: true };
+}
 /**
  * Extract the adapter name from an install source, like `iobroker.admin-7.8.6.tgz`,
  * `ioBroker/ioBroker.admin#main`, `iobroker.admin@7.8.6` or `admin`. Same rules as in ioBroker.admin.
@@ -159,6 +197,20 @@ class McpServer {
     oauth2;
     /** Installations started by `install_package`, keyed by the `cmdExec` session id. */
     cmdSessions = new Map();
+    /** Path of the MCP endpoint, e.g. `/mcp`. */
+    mcpPath;
+    /**
+     * Whether tools may hand out download/upload links (`<mcp>/transfer/<token>`). Needs our own HTTP
+     * routes; not as a web extension with authentication, where the web adapter asks for a login first.
+     */
+    linksAvailable;
+    /** Why links are not available, for the answer of the tools. */
+    linksUnavailableReason;
+    /** Active download and upload links, keyed by their token. */
+    transfers = new Map();
+    /** Temporary folder for the files of the links, created on first use. */
+    transferDir;
+    transferTimer;
     constructor(server, 
     // The permission toggles are explicit overrides for embedded mode (see `McpPermissions`)
     webSettings, adapter, instanceSettings, app) {
@@ -171,6 +223,10 @@ class McpServer {
         };
         this.extension = !!instanceSettings;
         this.routerPrefix = this.extension ? `/${WEB_EXTENSION_PREFIX}` : '/';
+        // In standalone mode this is `/mcp`; as a web extension we own the `/<adapter>/` namespace
+        // (e.g. `/mcp/`) within the shared web server, and strip the trailing slash so the route
+        // matches both `/mcp` and `/mcp/` (Express, non-strict).
+        this.mcpPath = this.extension ? this.routerPrefix.replace(/\/$/, '') : '/mcp';
         // Determine the ioBroker user whose permissions all MCP requests run with.
         // Prefer this adapter's own setting; when embedded, fall back to the host web server's
         // default user; finally to "admin". Always normalize to the "system.user." prefix.
@@ -195,6 +251,22 @@ class McpServer {
         this.config.sendToAllowlist = (this.config.sendToAllowlist || '').trim();
         // Confirmations via elicitation are on unless turned off explicitly
         this.config.confirmDangerous = this.config.confirmDangerous !== false;
+        this.config.transferLinks = this.config.transferLinks !== false;
+        if (!this.app) {
+            this.linksUnavailableReason = 'Links need the HTTP server of MCP, they are not available in this mode';
+        }
+        else if (!this.config.transferLinks) {
+            this.linksUnavailableReason =
+                'Links are turned off in the MCP adapter settings ("Allow download/upload links")';
+        }
+        else if (this.extension && webSettings.auth) {
+            this.linksUnavailableReason =
+                'Links are not available as a web extension with authentication enabled in the web adapter';
+        }
+        else {
+            this.linksUnavailableReason = '';
+        }
+        this.linksAvailable = !this.linksUnavailableReason;
         // State writes are declared destructive unless turned off explicitly
         this.config.setStateDestructive = this.config.setStateDestructive !== false;
         // Authentication is enforced by us only when we run standalone (we own the Express app) and
@@ -255,10 +327,7 @@ class McpServer {
             // Embedded in-process mode: no HTTP transport, so there is nothing to route.
             return;
         }
-        // The MCP endpoint. In standalone mode this is `/mcp`; as a web extension we own the
-        // `/<adapter>/` namespace (e.g. `/mcp/`) within the shared web server. `.replace` strips
-        // the trailing slash so the route matches both `/mcp` and `/mcp/` (Express, non-strict).
-        const mcpPath = this.extension ? this.routerPrefix.replace(/\/$/, '') : '/mcp';
+        const mcpPath = this.mcpPath;
         // The MCP transport needs a parsed JSON body; apply the parser per-route so we never
         // touch the body handling of the web adapter or other extensions when running embedded.
         const jsonParser = express_1.default.json({ limit: '4mb' });
@@ -275,7 +344,9 @@ class McpServer {
         // As an extension these would collide with the web adapter's own routes.
         if (!this.extension) {
             app.use((req, _res, next) => {
-                this.adapter.log.debug(`${req.method} ${req.url} from ${req.ip}`);
+                // The token of a transfer link is a credential, so it does not go into the log
+                const url = req.url.replace(/\/transfer\/[^/?]+/, '/transfer/***');
+                this.adapter.log.debug(`${req.method} ${url} from ${req.ip}`);
                 next();
             });
             app.get('/', (_req, res) => {
@@ -370,6 +441,18 @@ class McpServer {
         app.delete(mcpPath, ...guards, (req, res) => {
             void this.handleMcpSessionRequest(req, res);
         });
+        // --- Download and upload links (see createTransfer) ---
+        // No guards: the random token in the path is the credential. An authenticated MCP session got
+        // it from a tool and hands it to a program without MCP access, e.g. curl in a shell.
+        if (this.linksAvailable) {
+            app.get(`${mcpPath}/transfer/:token`, (req, res) => this.handleDownload(req, res));
+            app.put(`${mcpPath}/transfer/:token`, (req, res) => {
+                void this.handleUpload(req, res);
+            });
+            app.post(`${mcpPath}/transfer/:token`, (req, res) => {
+                void this.handleUpload(req, res);
+            });
+        }
         // Catch-all 404 + error handlers only in standalone mode; the web adapter provides its own.
         if (!this.extension) {
             app.use((req, res) => {
@@ -540,7 +623,7 @@ class McpServer {
                 return;
             }
             const subscriptions = new Set();
-            const server = this.createServer(subscriptions);
+            const server = this.createServer(subscriptions, this.getBaseUrl(req));
             transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                 sessionIdGenerator: () => (0, node_crypto_1.randomUUID)(),
                 onsessioninitialized: (sid) => {
@@ -722,15 +805,68 @@ class McpServer {
      * Create a new MCP SDK server with all ioBroker tools registered.
      *
      * @param subscriptions the per-session set of subscribed state ids (mutated by subscribe/unsubscribe)
+     * @param baseUrl public address of this server, for download/upload links (none in-process)
      */
-    createServer(subscriptions) {
+    createServer(subscriptions, baseUrl) {
         const server = new mcp_js_1.McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {}, resources: { subscribe: true } } });
-        const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
         const fail = (error) => {
             const message = error instanceof Error ? error.message : String(error);
             this.adapter.log.warn(`MCP tool error: ${message}`);
             return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: message }) }], isError: true };
         };
+        const canLink = this.linksAvailable && !!baseUrl;
+        // A download link for data that is too large for a tool result
+        const download = (name, data, contentType) => ({
+            download_url: this.transferUrl(baseUrl, this.createTransfer('download', name, data, contentType)),
+            expires_in: TRANSFER_TTL / 1000,
+        });
+        const linkHint = 'fetch it with e.g. `curl -o <file> "<download_url>"` if you can run shell commands';
+        // Clients reject results above 1 MiB without telling the server, so never send one
+        const ok = (data) => {
+            const text = JSON.stringify(data);
+            if (wireSize(text) <= MAX_RESULT_BYTES) {
+                return { content: [{ type: 'text', text }] };
+            }
+            const size = `${Math.round(Buffer.byteLength(text) / 1024)} KB`;
+            if (canLink) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: true,
+                                too_large: true,
+                                size,
+                                ...download('result.json', text, 'application/json'),
+                                hint: `The result (${size}) is too large for one answer: narrow the request down, or ${linkHint}`,
+                            }),
+                        },
+                    ],
+                };
+            }
+            return fail(new Error(`The result (${size}) is larger than ${MAX_RESULT_BYTES / 1024} KB, which MCP clients accept. ` +
+                'Narrow the request down (filters, wildcards, time range) or use offset/limit.'));
+        };
+        // Describe a cut list: how to get the rest, and a link to all of it (if it was cut for its size)
+        const pageInfo = (page, all, name, link = true) => {
+            if (!page.truncated) {
+                return {};
+            }
+            const info = { truncated: true, total: page.total };
+            const ways = [];
+            if (page.nextOffset !== undefined) {
+                info.nextOffset = page.nextOffset;
+                ways.push('call again with offset=nextOffset');
+            }
+            ways.push('narrow the request down');
+            if (canLink && link) {
+                Object.assign(info, download(name, JSON.stringify(all), 'application/json'));
+                ways.push(`get all ${all.length} entries from download_url: ${linkHint}`);
+            }
+            info.hint = `${link ? 'Not everything fits into one answer' : 'There are more entries'}: ${ways.join(', or ')}`;
+            return info;
+        };
+        const offsetSchema = zod_1.z.number().int().min(0).optional().describe('Skip this many entries (for paging)');
         // Ask the user before a dangerous action, if the client can (MCP elicitation). Clients without
         // elicitation rely on the destructiveHint of the tool instead.
         const confirm = async (message) => {
@@ -754,10 +890,15 @@ class McpServer {
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
             description: 'Retrieve the current value of one or multiple states. IDs may contain wildcards, ' +
                 'e.g. "hue.0.*.brightness" expands to all matching states.',
-            inputSchema: { ids: zod_1.z.array(zod_1.z.string()).describe('Array of state IDs (wildcards "*" allowed)') },
-        }, async ({ ids }) => {
+            inputSchema: {
+                ids: zod_1.z.array(zod_1.z.string()).describe('Array of state IDs (wildcards "*" allowed)'),
+                offset: offsetSchema,
+            },
+        }, async ({ ids, offset }) => {
             try {
-                return ok({ ok: true, data: { states: await this.getStates(ids) } });
+                const states = await this.getStates(ids);
+                const page = fitItems(states, offset);
+                return ok({ ok: true, data: { states: page.items, ...pageInfo(page, states, 'states.json') } });
             }
             catch (e) {
                 return fail(e);
@@ -839,7 +980,10 @@ class McpServer {
             },
         }, async (args) => {
             try {
-                return ok({ ok: true, data: { logs: await this.getLogs(args) } });
+                // Keep the newest lines if not all of them fit
+                const logs = await this.getLogs(args);
+                const page = fitItems(logs, 0, true);
+                return ok({ ok: true, data: { logs: page.items, ...pageInfo(page, logs, 'logs.json') } });
             }
             catch (e) {
                 return fail(e);
@@ -897,11 +1041,23 @@ class McpServer {
                 role: zod_1.z.string().optional(),
                 room: zod_1.z.string().optional(),
                 adapter: zod_1.z.string().optional().describe('Filter by source adapter instance, e.g. "hue.0"'),
-                limit: zod_1.z.number().int().optional().describe('Maximum number of results (default 50)'),
+                limit: zod_1.z.number().int().min(1).optional().describe('Maximum number of results (default 50)'),
+                offset: offsetSchema,
             },
-        }, async (args) => {
+        }, async ({ limit = 50, offset = 0, ...filters }) => {
             try {
-                return ok({ ok: true, data: { results: await this.searchObjects(args) } });
+                const matches = await this.searchObjects(filters);
+                const page = fitItems(matches.slice(0, offset + limit), offset);
+                const tooLarge = page.truncated;
+                if (!page.truncated && matches.length > offset + limit) {
+                    page.truncated = true;
+                    page.nextOffset = offset + limit;
+                }
+                page.total = matches.length;
+                return ok({
+                    ok: true,
+                    data: { results: page.items, ...pageInfo(page, matches, 'objects.json', tooLarge) },
+                });
             }
             catch (e) {
                 return fail(e);
@@ -964,10 +1120,16 @@ class McpServer {
                     .describe('Quantile (0-1), only used with agg=quantile'),
                 interval: zod_1.z.string().optional().describe('Aggregation interval, e.g. 15m, 1h'),
                 limit: zod_1.z.number().int().optional().describe('Maximum number of values (default 1000)'),
+                offset: offsetSchema,
             },
-        }, async (args) => {
+        }, async ({ offset, ...args }) => {
             try {
-                return ok({ ok: true, data: await this.historyQuery(args) });
+                const result = await this.historyQuery(args);
+                const page = fitItems(result.values, offset);
+                return ok({
+                    ok: true,
+                    data: { ...result, values: page.items, ...pageInfo(page, result.values, 'history.json') },
+                });
             }
             catch (e) {
                 return fail(e);
@@ -1108,7 +1270,8 @@ class McpServer {
                 `At most \`length\` bytes (default ${DEFAULT_MAX_READ_BYTES}) are returned per call; ` +
                 'large files are read in chunks: when the result has `truncated: true`, call again with ' +
                 '`offset` set to the returned `nextOffset` until `truncated` is false. ' +
-                '`size` is the total file size in bytes.',
+                '`size` is the total file size in bytes. If you can run shell commands (e.g. Claude Code), ' +
+                'set `download: true` instead to get a link to the whole file, which you fetch with curl.',
             inputSchema: {
                 path: zod_1.z.string().describe('Path as "<adapter>/<dir>/<file>"'),
                 base64: zod_1.z.boolean().optional().describe('Return binary content base64-encoded'),
@@ -1124,9 +1287,34 @@ class McpServer {
                     .min(1)
                     .optional()
                     .describe(`Maximum number of bytes to return (default ${DEFAULT_MAX_READ_BYTES})`),
+                download: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Return a download link to the whole file instead of its content'),
             },
-        }, async ({ path, base64, offset, length }) => {
+        }, async ({ path, base64, offset, length, download: asLink }) => {
             try {
+                if (asLink) {
+                    if (!canLink) {
+                        throw new Error(this.linksUnavailableReason || 'Links are not available');
+                    }
+                    const { adapterName, fileName } = McpServer.parseFilePath(path);
+                    const file = await this.adapter.readFileAsync(adapterName, fileName, {
+                        user: this.defaultUser,
+                    });
+                    const data = Buffer.isBuffer(file.file) ? file.file : Buffer.from(file.file || '');
+                    const mimeType = file.mimeType || 'application/octet-stream';
+                    return ok({
+                        ok: true,
+                        data: {
+                            path,
+                            size: data.length,
+                            mimeType,
+                            ...download(fileName.split('/').pop() || 'file', data, mimeType),
+                            hint: linkHint,
+                        },
+                    });
+                }
                 return ok({ ok: true, data: await this.readFile(path, base64, offset, length) });
             }
             catch (e) {
@@ -1137,10 +1325,12 @@ class McpServer {
             title: 'List a directory',
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
             description: 'List a directory in an adapter file storage, e.g. "vis-2.0/main" or "0_userdata.0"',
-            inputSchema: { path: zod_1.z.string().describe('Path as "<adapter>[/<dir>]"') },
-        }, async ({ path }) => {
+            inputSchema: { path: zod_1.z.string().describe('Path as "<adapter>[/<dir>]"'), offset: offsetSchema },
+        }, async ({ path, offset }) => {
             try {
-                return ok({ ok: true, data: { path, files: await this.listFiles(path) } });
+                const files = await this.listFiles(path);
+                const page = fitItems(files, offset);
+                return ok({ ok: true, data: { path, files: page.items, ...pageInfo(page, files, 'files.json') } });
             }
             catch (e) {
                 return fail(e);
@@ -1349,14 +1539,29 @@ class McpServer {
                     idempotentHint: true,
                     openWorldHint: false,
                 },
-                description: 'Write a file to an adapter file storage, e.g. "vis-2.0/main/vis-views.json"',
+                description: 'Write a file to an adapter file storage, e.g. "vis-2.0/main/vis-views.json". Give the ' +
+                    'content, or - for a large file, if you can run shell commands - upload it with ' +
+                    'prepare_upload and give its upload_id.',
                 inputSchema: {
                     path: zod_1.z.string().describe('Path as "<adapter>/<dir>/<file>"'),
-                    content: zod_1.z.string().describe('File content (UTF-8, or base64 when base64=true)'),
+                    content: zod_1.z.string().optional().describe('File content (UTF-8, or base64 when base64=true)'),
                     base64: zod_1.z.boolean().optional().describe('Treat content as base64-encoded binary'),
+                    upload_id: zod_1.z.string().optional().describe('Id of a file uploaded via prepare_upload'),
                 },
-            }, async ({ path, content, base64 }) => {
+            }, async ({ path, content, base64, upload_id }) => {
                 try {
+                    if ((content === undefined) === (upload_id === undefined)) {
+                        throw new Error('Give either "content" or "upload_id"');
+                    }
+                    if (upload_id !== undefined) {
+                        const upload = this.getUpload(upload_id);
+                        const { adapterName, fileName } = McpServer.parseFilePath(path);
+                        await this.adapter.writeFileAsync(adapterName, fileName, node_fs_1.default.readFileSync(upload.file), {
+                            user: this.defaultUser,
+                        });
+                        this.removeTransfer(upload_id);
+                        return ok({ ok: true, data: { path, size: upload.size } });
+                    }
                     await this.writeFile(path, content, base64);
                     return ok({ ok: true, data: { path } });
                 }
@@ -1470,10 +1675,16 @@ class McpServer {
                 'id, name, type, whether they run, and the javascript instance - without the source.',
             inputSchema: {
                 folder: zod_1.z.string().optional().describe('Only scripts in this folder, e.g. "common" or "lights"'),
+                offset: offsetSchema,
             },
-        }, async ({ folder }) => {
+        }, async ({ folder, offset }) => {
             try {
-                return ok({ ok: true, data: { scripts: await this.listScripts(folder) } });
+                const scripts = await this.listScripts(folder);
+                const page = fitItems(scripts, offset);
+                return ok({
+                    ok: true,
+                    data: { scripts: page.items, ...pageInfo(page, scripts, 'scripts.json') },
+                });
             }
             catch (e) {
                 return fail(e);
@@ -1685,6 +1896,44 @@ class McpServer {
                 }
             });
         }
+        // Large files cannot pass through the model: the client uploads them with a separate program
+        if (canLink && (this.config.allowObjectChange || this.config.allowPackageInstall)) {
+            server.registerTool('prepare_upload', {
+                title: 'Prepare a file upload',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                description: 'Get a one-time link to upload a file that is too large for a tool argument, e.g. a .tgz ' +
+                    'for install_package or a big file for write_file. Only useful if you can run shell ' +
+                    'commands (e.g. Claude Code): upload the local file with `curl -T <file> "<url>"`, then ' +
+                    `pass the returned upload_id to install_package or write_file. Valid for ${TRANSFER_TTL / 60_000} minutes, ` +
+                    `up to ${MAX_UPLOAD_BYTES / 1024 / 1024} MB.`,
+                inputSchema: {
+                    name: zod_1.z.string().describe('File name, e.g. "iobroker.hue-3.9.1.tgz"'),
+                },
+            }, ({ name }) => {
+                try {
+                    const token = this.createTransfer('upload', name);
+                    const url = this.transferUrl(baseUrl, token);
+                    return Promise.resolve(ok({
+                        ok: true,
+                        data: {
+                            upload_id: token,
+                            url,
+                            method: 'PUT',
+                            expires_in: TRANSFER_TTL / 1000,
+                            command: `curl -T "${name}" "${url}"`,
+                        },
+                    }));
+                }
+                catch (e) {
+                    return Promise.resolve(fail(e));
+                }
+            });
+        }
         // Installing packages runs arbitrary code on the host, so it is a separate opt-in for developers.
         if (this.config.allowPackageInstall) {
             server.registerTool('install_package', {
@@ -1700,7 +1949,8 @@ class McpServer {
                     'package ("iobroker.hue@3.9.0" or just "hue"), a GitHub repository ' +
                     '("ioBroker/ioBroker.hue#main" or https URL), an https URL of a .tgz or a .tgz path on the ' +
                     'target host; `file_path` - a .tgz in the ioBroker file storage ("0_userdata.0/x.tgz"); or ' +
-                    '`file_name` + `file_content` - a small .tgz as base64. Waits until the installation is ' +
+                    '`file_name` + `file_content` - a small .tgz as base64; or `upload_id` - a .tgz uploaded ' +
+                    'via prepare_upload (for large files, if you can run shell commands). Waits until the installation is ' +
                     'finished (or `timeout`), returns the exit code and the last output lines. Enabled instances ' +
                     'of the adapter are restarted afterwards; no new instance is created.',
                 inputSchema: {
@@ -1717,6 +1967,7 @@ class McpServer {
                         .optional()
                         .describe('File name of the .tgz in file_content, e.g. "iobroker.hue-3.9.0.tgz"'),
                     file_content: zod_1.z.string().optional().describe('The .tgz file as base64'),
+                    upload_id: zod_1.z.string().optional().describe('Id of a .tgz uploaded via prepare_upload'),
                     host: zod_1.z.string().optional().describe('Target host (default: the host of this instance)'),
                     debug: zod_1.z.boolean().optional().describe('Install with --debug for more output'),
                     restart_instances: zod_1.z
@@ -1733,7 +1984,7 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
-                    await confirm(`Install the package "${args.source || args.file_path || args.file_name}"? It runs with full rights on the host.`);
+                    await confirm(`Install the package "${args.source || args.file_path || args.file_name || args.upload_id}"? It runs with full rights on the host.`);
                     return ok({ ok: true, data: await this.installPackage(args) });
                 }
                 catch (e) {
@@ -2429,7 +2680,7 @@ class McpServer {
         };
     }
     async searchObjects(params) {
-        const { query = '', type, role, room, adapter, limit = 50 } = params;
+        const { query = '', type, role, room, adapter } = params;
         const result = await this.adapter.getObjectListAsync({
             startkey: '',
             endkey: '\u9999',
@@ -2464,9 +2715,6 @@ class McpServer {
                 name,
                 adapter: sourceAdapter,
             });
-            if (results.length >= limit) {
-                break;
-            }
         }
         return results;
     }
@@ -2914,11 +3162,18 @@ class McpServer {
      * ioBroker.admin installs from a custom URL or a .tgz file, and wait for the result.
      */
     async installPackage(params) {
-        const given = [params.source, params.file_path, params.file_content].filter(one => one !== undefined);
+        const given = [params.source, params.file_path, params.file_content, params.upload_id].filter(one => one !== undefined);
         if (given.length !== 1) {
-            throw new Error('Give exactly one of "source", "file_path" or "file_name" + "file_content"');
+            throw new Error('Give exactly one of "source", "file_path", "file_name" + "file_content" or "upload_id"');
         }
         const host = await this.resolveHost(params.host);
+        let upload;
+        if (params.upload_id !== undefined) {
+            upload = this.getUpload(params.upload_id);
+            if (!upload.name.toLowerCase().endsWith('.tgz')) {
+                throw new Error('Only .tgz files can be installed');
+            }
+        }
         let source;
         let files;
         if (params.source !== undefined) {
@@ -2941,6 +3196,10 @@ class McpServer {
                 data = Buffer.isBuffer(result.file) ? result.file : Buffer.from(result.file || '');
                 fileName = storageName.split('/').pop() || '';
             }
+            else if (upload) {
+                data = node_fs_1.default.readFileSync(upload.file);
+                fileName = upload.name;
+            }
             else {
                 if (!params.file_name) {
                     throw new Error('"file_content" requires "file_name"');
@@ -2962,7 +3221,10 @@ class McpServer {
             files = [{ name: source, file: data.toString('base64') }];
         }
         const result = await this.runHostCommand(host, `url ${source} --host ${host}${params.debug ? ' --debug' : ''}`, params.timeout, files);
-        const adapterName = extractAdapterName(params.file_path || params.file_name || params.source || '');
+        if (upload && result.finished) {
+            this.removeTransfer(params.upload_id);
+        }
+        const adapterName = extractAdapterName(params.file_path || params.file_name || upload?.name || params.source || '');
         const restarted = result.success && adapterName && params.restart_instances !== false
             ? await this.restartAdapterInstances(adapterName)
             : [];
@@ -3408,6 +3670,138 @@ class McpServer {
         await this.adapter.setForeignObjectAsync(id, { type: 'state', common, native: {} }, { user: this.defaultUser });
         return { id, target: params.target, ...(params.write_target ? { write_target: params.write_target } : {}) };
     }
+    /**
+     * Create a download link for `data`, or an upload link when `data` is undefined, and return its
+     * token. The file lives in a temporary folder until the link expires (or the upload is used).
+     */
+    createTransfer(kind, name, data, contentType = 'application/octet-stream') {
+        this.cleanupTransfers();
+        if (!this.transferDir) {
+            this.transferDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'iobroker-mcp-'));
+            this.transferTimer = setInterval(() => this.cleanupTransfers(), 60_000);
+            this.transferTimer.unref?.();
+        }
+        const token = (0, node_crypto_1.randomBytes)(32).toString('hex');
+        // One folder per link, so the file keeps its name (`npm` needs the .tgz extension)
+        const folder = node_path_1.default.join(this.transferDir, token);
+        node_fs_1.default.mkdirSync(folder);
+        const file = node_path_1.default.join(folder, name.replace(/[^a-zA-Z0-9._-]/g, '_') || 'file');
+        if (data !== undefined) {
+            node_fs_1.default.writeFileSync(file, data);
+        }
+        this.transfers.set(token, {
+            kind,
+            name,
+            file,
+            contentType,
+            expires: Date.now() + TRANSFER_TTL,
+            size: data !== undefined ? Buffer.byteLength(data) : undefined,
+        });
+        return token;
+    }
+    /** The public URL of a download or upload link. */
+    transferUrl(baseUrl, token) {
+        return `${baseUrl}${this.mcpPath}/transfer/${token}`;
+    }
+    /** Remove a link and its file. */
+    removeTransfer(token) {
+        const transfer = this.transfers.get(token);
+        if (transfer) {
+            this.transfers.delete(token);
+            try {
+                node_fs_1.default.rmSync(node_path_1.default.dirname(transfer.file), { recursive: true, force: true });
+            }
+            catch (e) {
+                this.adapter.log.warn(`Cannot delete "${transfer.file}": ${e}`);
+            }
+        }
+    }
+    /** Remove the expired links. */
+    cleanupTransfers() {
+        const now = Date.now();
+        for (const [token, transfer] of this.transfers) {
+            if (transfer.expires < now) {
+                this.removeTransfer(token);
+            }
+        }
+    }
+    /** `GET <mcp>/transfer/<token>`: send the file of a download link. */
+    handleDownload(req, res) {
+        const transfer = this.transfers.get(String(req.params.token));
+        if (!transfer || transfer.kind !== 'download' || transfer.expires < Date.now()) {
+            res.status(404).json({ error: 'Unknown or expired link' });
+            return;
+        }
+        res.setHeader('Content-Type', transfer.contentType);
+        res.setHeader('Content-Disposition', `attachment; filename="${node_path_1.default.basename(transfer.file)}"`);
+        if (transfer.size !== undefined) {
+            res.setHeader('Content-Length', transfer.size);
+        }
+        node_fs_1.default.createReadStream(transfer.file).pipe(res);
+    }
+    /** `PUT`/`POST <mcp>/transfer/<token>`: receive the file of an upload link (raw body, e.g. `curl -T`). */
+    async handleUpload(req, res) {
+        const token = String(req.params.token);
+        const transfer = this.transfers.get(token);
+        if (!transfer || transfer.kind !== 'upload' || transfer.expires < Date.now()) {
+            res.status(404).json({ error: 'Unknown or expired link' });
+            return;
+        }
+        if (transfer.size !== undefined) {
+            res.status(409).json({ error: 'This link was already used' });
+            return;
+        }
+        try {
+            transfer.size = await McpServer.receiveBody(req, transfer.file);
+            this.adapter.log.info(`Received upload "${transfer.name}" (${transfer.size} bytes)`);
+            res.json({ ok: true, upload_id: token, name: transfer.name, size: transfer.size });
+        }
+        catch (e) {
+            const error = e;
+            node_fs_1.default.rmSync(transfer.file, { force: true });
+            res.status(error.status || 400).json({ error: error.message });
+        }
+    }
+    /** Write the raw body of a request to a file and return its size. */
+    static receiveBody(req, file) {
+        const tooLarge = () => Object.assign(new Error(`The file is larger than ${MAX_UPLOAD_BYTES / 1024 / 1024} MB`), { status: 413 });
+        // The body parsers of the web adapter may have read the stream already and kept the bytes
+        const read = req.rawBody ?? (Buffer.isBuffer(req.body) ? req.body : null);
+        if (read) {
+            if (read.length > MAX_UPLOAD_BYTES) {
+                return Promise.reject(tooLarge());
+            }
+            node_fs_1.default.writeFileSync(file, read);
+            return Promise.resolve(read.length);
+        }
+        return new Promise((resolve, reject) => {
+            const out = node_fs_1.default.createWriteStream(file);
+            let size = 0;
+            req.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > MAX_UPLOAD_BYTES) {
+                    req.unpipe(out);
+                    out.destroy();
+                    reject(tooLarge());
+                }
+            });
+            req.on('error', reject);
+            out.on('error', reject);
+            out.on('finish', () => resolve(size));
+            req.pipe(out);
+        });
+    }
+    /** Get a received upload by its id, failing if it is unknown, expired or still empty. */
+    getUpload(uploadId) {
+        const transfer = this.transfers.get(uploadId);
+        if (!transfer || transfer.kind !== 'upload' || transfer.expires < Date.now()) {
+            throw new Error(`Unknown or expired upload "${uploadId}" - create a new one with prepare_upload`);
+        }
+        if (transfer.size === undefined) {
+            throw new Error(`Nothing was uploaded to "${uploadId}" yet - upload the file to its url first`);
+        }
+        return transfer;
+    }
     // --- helpers ---
     /** Resolve the member ids of a room/function enum matched by id or (localized) name. */
     async getEnumMembers(prefix, nameOrId) {
@@ -3448,6 +3842,15 @@ class McpServer {
         catch {
             // ignore
         }
+        if (this.transferTimer) {
+            clearInterval(this.transferTimer);
+            this.transferTimer = undefined;
+        }
+        if (this.transferDir) {
+            node_fs_1.default.rmSync(this.transferDir, { recursive: true, force: true });
+            this.transferDir = undefined;
+            this.transfers.clear();
+        }
         for (const session of Object.values(this.sessions)) {
             try {
                 void session.transport.close();