@iobroker/mcp-server 1.3.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"));
@@ -18,6 +19,7 @@ const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamable
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const devices_1 = require("./devices");
 const iob_uri_1 = require("./iob-uri");
+const types_1 = require("./types");
 const inProcessClient_1 = require("./inProcessClient");
 Object.defineProperty(exports, "createInProcessMcp", { enumerable: true, get: function () { return inProcessClient_1.createInProcessMcp; } });
 const package_json_1 = __importDefault(require("../package.json"));
@@ -78,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.
@@ -98,6 +137,29 @@ function extractAdapterName(source) {
     }
     return null;
 }
+/**
+ * Compare two versions like `3.9.0` and `3.10.0-alpha.1`: > 0 if `a` is newer, < 0 if `b` is newer.
+ * A pre-release is older than the release with the same numbers.
+ */
+function compareVersions(a, b) {
+    const [mainA, preA] = (a || '0').split('-', 2);
+    const [mainB, preB] = (b || '0').split('-', 2);
+    const partsA = mainA.split('.').map(part => parseInt(part, 10) || 0);
+    const partsB = mainB.split('.').map(part => parseInt(part, 10) || 0);
+    for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+        const diff = (partsA[i] || 0) - (partsB[i] || 0);
+        if (diff) {
+            return diff;
+        }
+    }
+    if (preA === preB) {
+        return 0;
+    }
+    if (!preA || !preB) {
+        return preA ? -1 : 1;
+    }
+    return preA.localeCompare(preB, undefined, { numeric: true });
+}
 class McpServer {
     adapter;
     /** The Express app we attach routes to. Undefined in embedded in-process mode (no HTTP). */
@@ -135,7 +197,23 @@ class McpServer {
     oauth2;
     /** Installations started by `install_package`, keyed by the `cmdExec` session id. */
     cmdSessions = new Map();
-    constructor(server, webSettings, adapter, instanceSettings, app) {
+    /** 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) {
         this.app = app;
         this.adapter = adapter;
         // Clone the source config so we never mutate the host adapter's config object — important in
@@ -145,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.
@@ -153,23 +235,38 @@ class McpServer {
         this.config.defaultUser = this.defaultUser;
         this.language = webSettings.language || 'en';
         // Embedded callers may set the permission toggles explicitly (they don't read the mcp config).
-        if (webSettings.allowSetState !== undefined) {
-            this.config.allowSetState = webSettings.allowSetState;
-        }
-        if (webSettings.allowObjectChange !== undefined) {
-            this.config.allowObjectChange = webSettings.allowObjectChange;
-        }
-        if (webSettings.setStateDestructive !== undefined) {
-            this.config.setStateDestructive = webSettings.setStateDestructive;
-        }
-        if (webSettings.allowPackageInstall !== undefined) {
-            this.config.allowPackageInstall = webSettings.allowPackageInstall;
+        for (const key of types_1.PERMISSION_KEYS) {
+            if (webSettings[key] !== undefined) {
+                this.config[key] = webSettings[key];
+            }
         }
-        // Permission toggles: state writes are allowed by default, object/file changes and
-        // package installation are not.
+        // Permission toggles: state writes are allowed by default, everything that changes the
+        // system (objects, instances, adapters, packages, scripts, messages) is not.
         this.config.allowSetState = this.config.allowSetState !== false;
         this.config.allowObjectChange = this.config.allowObjectChange === true;
+        this.config.allowInstanceControl = this.config.allowInstanceControl === true;
+        this.config.allowAdapterManagement = this.config.allowAdapterManagement === true;
         this.config.allowPackageInstall = this.config.allowPackageInstall === true;
+        this.config.allowScriptChange = this.config.allowScriptChange === true;
+        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
@@ -193,8 +290,8 @@ class McpServer {
         }
         // Receive ioBroker log messages (only forwarded once a session subscribes via requireLog).
         this.adapter.on('log', this.onLog);
-        if (this.config.allowPackageInstall) {
-            // The host reports the progress of `cmdExec` (install_package) as messages to this instance
+        if (this.config.allowPackageInstall || this.config.allowAdapterManagement) {
+            // The host reports the progress of `cmdExec` (install_package etc.) as messages to this instance
             this.adapter.on('message', this.onMessage);
         }
         // Wire HTTP routes only when we own/share an Express app. In embedded in-process mode (no app)
@@ -219,22 +316,10 @@ class McpServer {
      * @param options.adapter The host adapter into which the MCP server is embedded. Used for receiving state/object changes and logs, and for performing actions with the host adapter's permissions.
      * @param options.defaultUser Default user
      * @param options.language Language
-     * @param options.allowSetState Allow the state-writing tools `set_state`/`set_states` (opt-out, default true)
-     * @param options.allowObjectChange Allow the object/file-changing tools (opt-in, default false)
-     * @param options.setStateDestructive Declare `set_state`/`set_states` as destructive (default true)
-     * @param options.allowPackageInstall Allow the `install_package` tool (opt-in, default false, developers only)
      */
     static createEmbedded(options) {
-        return new McpServer(null, {
-            secure: false,
-            port: 0,
-            defaultUser: options.defaultUser,
-            language: options.language,
-            allowSetState: options.allowSetState,
-            allowObjectChange: options.allowObjectChange,
-            setStateDestructive: options.setStateDestructive,
-            allowPackageInstall: options.allowPackageInstall,
-        }, options.adapter, null);
+        const { adapter, ...settings } = options;
+        return new McpServer(null, { secure: false, port: 0, ...settings }, adapter, null);
     }
     initRoutes() {
         const app = this.app;
@@ -242,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' });
@@ -262,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) => {
@@ -357,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) => {
@@ -527,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) => {
@@ -709,24 +805,100 @@ 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) => {
+            if (!this.config.confirmDangerous || !server.server.getClientCapabilities()?.elicitation) {
+                return;
+            }
+            const answer = await server.server.elicitInput({
+                message,
+                requestedSchema: {
+                    type: 'object',
+                    properties: { confirm: { type: 'boolean', title: 'Yes, do it' } },
+                    required: ['confirm'],
+                },
+            });
+            if (answer.action !== 'accept' || answer.content?.confirm !== true) {
+                throw new Error('Cancelled by the user');
+            }
+        };
         server.registerTool('get_states', {
             title: 'Get state values',
             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);
@@ -808,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);
@@ -866,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);
@@ -933,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);
@@ -1077,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'),
@@ -1093,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) {
@@ -1106,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);
@@ -1206,6 +1427,7 @@ class McpServer {
                 },
             }, async ({ id, recursive }) => {
                 try {
+                    await confirm(`Delete the object "${id}"${recursive ? ' and all its children' : ''}?`);
                     await this.deleteObject(id, recursive);
                     return ok({ ok: true, data: { id, deleted: true } });
                 }
@@ -1281,6 +1503,34 @@ class McpServer {
                     return fail(e);
                 }
             });
+            server.registerTool('create_alias', {
+                title: 'Create an alias',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                description: 'Create an alias state (alias.0.*) that points to another state, e.g. to give a device a ' +
+                    'stable, readable id that survives replacing the hardware. Type, role, unit and limits are ' +
+                    'copied from the target. With write_target, reading and writing use different states ' +
+                    '(e.g. a thermostat with separate actual and set values). Fails if the alias exists.',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Alias id, e.g. "livingroom.ceiling_light" (becomes alias.0.…)'),
+                    target: zod_1.z.string().describe('State the alias reads (and writes), e.g. "hue.0.light.state"'),
+                    write_target: zod_1.z.string().optional().describe('Different state for writing'),
+                    name: zod_1.z.string().optional().describe('Display name (default: name of the target)'),
+                    role: zod_1.z.string().optional().describe('Role (default: role of the target)'),
+                    unit: zod_1.z.string().optional().describe('Unit (default: unit of the target)'),
+                },
+            }, async (args) => {
+                try {
+                    return ok({ ok: true, data: await this.createAlias(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
             server.registerTool('write_file', {
                 title: 'Write a file',
                 annotations: {
@@ -1289,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 } });
                 }
@@ -1371,6 +1636,304 @@ class McpServer {
                 }
             });
         }
+        server.registerTool('list_adapter_updates', {
+            title: 'List adapter updates',
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            description: 'List the installed adapters that have a newer version in the active repository ' +
+                '(installed and available version). Reads the already-downloaded repository (no network).',
+            inputSchema: {},
+        }, async () => {
+            try {
+                return ok({ ok: true, data: { updates: await this.listAdapterUpdates() } });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
+        server.registerTool('list_notifications', {
+            title: 'List system notifications',
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            description: 'List the current system notifications of the hosts, as shown by the bell in ioBroker.admin ' +
+                '(e.g. disk space low, adapter crashed repeatedly, adapter updates). Each entry has host, ' +
+                'scope, category, severity, the affected instance and its messages.',
+            inputSchema: {
+                host: zod_1.z.string().optional().describe('Only this host (default: all running hosts)'),
+                language: zod_1.z.enum(LANGUAGES).optional().describe('Language for names and descriptions'),
+            },
+        }, async (args) => {
+            try {
+                return ok({ ok: true, data: { notifications: await this.listNotifications(args) } });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
+        server.registerTool('list_scripts', {
+            title: 'List scripts',
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            description: 'List the scripts of the javascript adapter (JavaScript, TypeScript, Blockly, Rules) with ' +
+                '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, offset }) => {
+            try {
+                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);
+            }
+        });
+        server.registerTool('get_script', {
+            title: 'Read a script',
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            description: 'Read a script of the javascript adapter including its source code',
+            inputSchema: {
+                id: zod_1.z.string().describe('Script id, e.g. "script.js.common.lights" or "common.lights"'),
+            },
+        }, async ({ id }) => {
+            try {
+                const script = await this.getScriptObject(id);
+                return ok({ ok: true, data: this.scriptInfo(script.id, script.obj, true) });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
+        if (this.config.allowSetState) {
+            server.registerTool('clear_notifications', {
+                title: 'Acknowledge notifications',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Acknowledge (delete) system notifications of a host - all, or only those of one scope, ' +
+                    'category and/or instance as returned by list_notifications.',
+                inputSchema: {
+                    host: zod_1.z.string().optional().describe('Host (default: the host of this instance)'),
+                    scope: zod_1.z.string().optional().describe('e.g. "system"'),
+                    category: zod_1.z.string().optional().describe('e.g. "diskSpaceIssues"'),
+                    instance: zod_1.z.string().optional().describe('e.g. "hue.0"'),
+                },
+            }, async (args) => {
+                try {
+                    return ok({ ok: true, data: await this.clearNotifications(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+        }
+        if (this.config.allowInstanceControl) {
+            const instanceSchema = { id: zod_1.z.string().describe('Instance, e.g. "hue.0"') };
+            server.registerTool('start_instance', {
+                title: 'Start an instance',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Start (enable) an adapter instance',
+                inputSchema: instanceSchema,
+            }, async ({ id }) => {
+                try {
+                    return ok({ ok: true, data: await this.setInstanceEnabled(id, true) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('stop_instance', {
+                title: 'Stop an instance',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Stop (disable) an adapter instance. It stays stopped until it is started again, also ' +
+                    'after a restart of ioBroker.',
+                inputSchema: instanceSchema,
+            }, async ({ id }) => {
+                try {
+                    await confirm(`Stop the instance "${id}"?`);
+                    return ok({ ok: true, data: await this.setInstanceEnabled(id, false) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('restart_instance', {
+                title: 'Restart an instance',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                description: 'Restart a running adapter instance, e.g. after changing its configuration',
+                inputSchema: instanceSchema,
+            }, async ({ id }) => {
+                try {
+                    return ok({ ok: true, data: await this.restartInstance(id) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('set_log_level', {
+                title: 'Set the log level of an instance',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Change the log level of an adapter instance, e.g. to "debug" to analyze a problem with ' +
+                    'get_logs. By default only until the next start of the instance and without a restart; ' +
+                    'with persistent=true it is stored in the instance configuration (restarts the instance).',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Instance, e.g. "hue.0"'),
+                    level: zod_1.z.enum(['silly', 'debug', 'info', 'warn', 'error']),
+                    persistent: zod_1.z.boolean().optional().describe('Store it permanently (default false)'),
+                },
+            }, async ({ id, level, persistent }) => {
+                try {
+                    return ok({ ok: true, data: await this.setLogLevel(id, level, persistent) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+        }
+        if (this.config.allowAdapterManagement) {
+            const timeoutSchema = zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(3600)
+                .optional()
+                .describe(`Seconds to wait (default ${DEFAULT_INSTALL_TIMEOUT}); the command keeps running on the host after that`);
+            server.registerTool('add_instance', {
+                title: 'Add an adapter instance',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+                description: 'Create a new instance of an adapter from the repository (`iobroker add`). Installs the ' +
+                    'adapter first if it is not installed yet. Find adapters with search_adapter_repository.',
+                inputSchema: {
+                    adapter: zod_1.z.string().describe('Adapter name, e.g. "hue"'),
+                    instance: zod_1.z.number().int().min(0).optional().describe('Instance number (default: next free)'),
+                    host: zod_1.z.string().optional().describe('Host (default: the host of this instance)'),
+                    timeout: timeoutSchema,
+                },
+            }, async (args) => {
+                try {
+                    return ok({ ok: true, data: await this.addInstance(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('delete_instance', {
+                title: 'Delete an adapter instance',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                description: 'Delete an adapter instance with its configuration, objects and states (`iobroker del`). ' +
+                    'This cannot be undone.',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Instance, e.g. "hue.0"'),
+                    timeout: timeoutSchema,
+                },
+            }, async (args) => {
+                try {
+                    await confirm(`Delete the instance "${args.id}" with its configuration, objects and states? This cannot be undone.`);
+                    return ok({ ok: true, data: await this.deleteInstance(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('upgrade_adapter', {
+                title: 'Upgrade an adapter',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
+                description: 'Upgrade an installed adapter to the version of the active repository or to the given ' +
+                    'version (`iobroker upgrade`). Its instances are restarted. See list_adapter_updates.',
+                inputSchema: {
+                    adapter: zod_1.z.string().describe('Adapter name, e.g. "hue"'),
+                    version: zod_1.z.string().optional().describe('Version (default: the repository version)'),
+                    host: zod_1.z.string().optional().describe('Host (default: the host of this instance)'),
+                    timeout: timeoutSchema,
+                },
+            }, async (args) => {
+                try {
+                    await confirm(`Upgrade the adapter "${args.adapter}"${args.version ? ` to ${args.version}` : ''}?`);
+                    return ok({ ok: true, data: await this.upgradeAdapter(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+        }
+        // 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', {
@@ -1386,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: {
@@ -1403,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
@@ -1419,6 +1984,7 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
+                    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) {
@@ -1426,22 +1992,224 @@ class McpServer {
                 }
             });
         }
-        // --- Resources: expose states and objects via the canonical ioBroker URI scheme ---
-        // States as `iobstate://<id>`, objects as `iobobject://<id>`. On change the server pushes a
-        // `notifications/resources/updated` over the session's SSE stream and the client re-reads.
-        server.registerResource('state', new mcp_js_1.ResourceTemplate('iobstate://{id}', { list: undefined }), {
-            title: 'ioBroker state',
-            description: 'A single ioBroker state value, addressed as iobstate://<id>',
-            mimeType: 'application/json',
-        }, async (uri, variables) => {
-            const id = decodeURIComponent(String(variables.id));
-            const state = await this.adapter.getForeignStateAsync(id, { user: this.defaultUser });
-            const body = state
-                ? { id, val: state.val, ack: state.ack, ts: state.ts, lc: state.lc, q: state.q }
-                : { id, val: null };
-            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(body) }] };
-        });
-        server.registerResource('object', new mcp_js_1.ResourceTemplate('iobobject://{id}', { list: undefined }), {
+        if (this.config.allowScriptChange) {
+            const engineTypeSchema = zod_1.z
+                .enum(['Javascript/js', 'TypeScript/ts'])
+                .optional()
+                .describe('Script language (default "Javascript/js")');
+            server.registerTool('set_script', {
+                title: 'Create or change a script',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Create a JavaScript/TypeScript script of the javascript adapter or replace the source of ' +
+                    'an existing one (a running script restarts with the new source). New scripts are created ' +
+                    'disabled unless enabled=true; missing folders are created. Blockly and Rules scripts ' +
+                    'cannot be changed. Test code first with run_script.',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Script id, e.g. "common.lights" (folder "common") or "lights"'),
+                    source: zod_1.z.string().describe('The complete source code'),
+                    engineType: engineTypeSchema,
+                    name: zod_1.z.string().optional().describe('Display name (default: last part of the id)'),
+                    enabled: zod_1.z.boolean().optional().describe('Start (true) or stop (false) the script'),
+                    instance: zod_1.z.string().optional().describe('javascript instance (default "javascript.0")'),
+                },
+            }, async (args) => {
+                try {
+                    await confirm(`Save the script "${args.id}"${args.enabled ? ' and start it' : ''}?`);
+                    return ok({ ok: true, data: await this.setScript(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('enable_script', {
+                title: 'Start or stop a script',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Start (enabled=true) or stop (enabled=false) a script of the javascript adapter',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Script id, e.g. "script.js.common.lights"'),
+                    enabled: zod_1.z.boolean(),
+                },
+            }, async ({ id, enabled }) => {
+                try {
+                    return ok({ ok: true, data: await this.enableScript(id, enabled) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('delete_script', {
+                title: 'Delete a script',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+                description: 'Delete a script of the javascript adapter',
+                inputSchema: { id: zod_1.z.string().describe('Script id, e.g. "script.js.common.lights"') },
+            }, async ({ id }) => {
+                try {
+                    await confirm(`Delete the script "${id}"?`);
+                    return ok({ ok: true, data: await this.deleteScript(id) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('run_script', {
+                title: 'Run code once',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                description: 'Run JavaScript/TypeScript once in the javascript adapter, with the same API as a script ' +
+                    '(getState, setState, log, ...), and return everything it logged. Nothing is stored; ' +
+                    'timers and subscriptions end after `timeout`. Use it to test code before set_script. ' +
+                    'Requires javascript adapter 10.1.0 or newer.',
+                inputSchema: {
+                    source: zod_1.z.string().describe('The code, e.g. log(getState("hue.0.light.state").val)'),
+                    engineType: engineTypeSchema,
+                    timeout: zod_1.z
+                        .number()
+                        .int()
+                        .min(0)
+                        .max(60000)
+                        .optional()
+                        .describe('Milliseconds to collect asynchronous output (default 5000)'),
+                    instance: zod_1.z.string().optional().describe('javascript instance (default "javascript.0")'),
+                },
+            }, async (args) => {
+                try {
+                    await confirm('Run the code in the javascript adapter?');
+                    return ok({ ok: true, data: await this.runScript(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+        }
+        if (this.config.sendToAllowlist) {
+            server.registerTool('send_to', {
+                title: 'Send a message to an adapter',
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+                description: 'Send a message to an adapter instance (`sendTo`) and return its answer, e.g. a Telegram ' +
+                    'message ({instance:"telegram.0", command:"send", message:{text:"Hi"}}) or a backup ' +
+                    `(backitup.0, "oneClick"). Allowed instances: ${this.config.sendToAllowlist}. The commands ` +
+                    'and the message format are described in the documentation of each adapter.',
+                inputSchema: {
+                    instance: zod_1.z.string().describe('Instance, e.g. "telegram.0"'),
+                    command: zod_1.z.string().describe('Command, e.g. "send"'),
+                    message: zod_1.z.any().optional().describe('Message payload (object or string)'),
+                    timeout: zod_1.z
+                        .number()
+                        .int()
+                        .min(100)
+                        .max(120000)
+                        .optional()
+                        .describe('Milliseconds to wait for the answer (default 10000)'),
+                },
+            }, async (args) => {
+                try {
+                    await confirm(`Send "${args.command}" to "${args.instance}"?`);
+                    return ok({ ok: true, data: await this.sendToInstance(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+        }
+        // --- Prompts: ready-made workflows that MCP clients offer as slash commands ---
+        server.registerPrompt('diagnose_adapter', {
+            title: 'Diagnose an adapter',
+            description: 'Find out why an adapter instance does not work and suggest a fix',
+            argsSchema: { instance: zod_1.z.string().describe('Instance, e.g. "hue.0"') },
+        }, ({ instance }) => ({
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Diagnose the ioBroker instance "${instance}". Check with list_instances whether it ` +
+                            `is enabled, alive and connected, read its errors and warnings with get_logs ` +
+                            `(adapter "${instance}"), look at list_notifications and, if the log names a device ` +
+                            `or service address, test it with ping_host. Compare its version with ` +
+                            `list_adapter_updates. Explain the cause in plain words and suggest the fix; ask ` +
+                            `before you change anything.`,
+                    },
+                },
+            ],
+        }));
+        server.registerPrompt('room_overview', {
+            title: 'Room overview',
+            description: 'Summarize the devices of a room and their current state',
+            argsSchema: { room: zod_1.z.string().describe('Room name, e.g. "Living room"') },
+        }, ({ room }) => ({
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Give me an overview of the room "${room}" in ioBroker: use list_devices for the ` +
+                            `room and get_states for the current values. Group them into lights, climate, ` +
+                            `windows/doors and others and point out anything unusual (open windows, lights on, ` +
+                            `low batteries, unreachable devices).`,
+                    },
+                },
+            ],
+        }));
+        server.registerPrompt('create_automation', {
+            title: 'Create an automation',
+            description: 'Turn a description into an ioBroker script',
+            argsSchema: { description: zod_1.z.string().describe('What should happen, e.g. "lights off at 23:00"') },
+        }, ({ description }) => ({
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Create an ioBroker automation: ${description}\n` +
+                            `Find the state ids with list_devices and search_objects, check the existing scripts ` +
+                            `with list_scripts and write a JavaScript for the javascript adapter (on(), ` +
+                            `schedule(), setState()). Test parts with run_script if available, show me the code ` +
+                            `and save it with set_script only after I agreed. If the script tools are not ` +
+                            `available, show me the code so I can paste it into the script editor.`,
+                    },
+                },
+            ],
+        }));
+        // --- Resources: expose states and objects via the canonical ioBroker URI scheme ---
+        // States as `iobstate://<id>`, objects as `iobobject://<id>`. On change the server pushes a
+        // `notifications/resources/updated` over the session's SSE stream and the client re-reads.
+        server.registerResource('state', new mcp_js_1.ResourceTemplate('iobstate://{id}', { list: undefined }), {
+            title: 'ioBroker state',
+            description: 'A single ioBroker state value, addressed as iobstate://<id>',
+            mimeType: 'application/json',
+        }, async (uri, variables) => {
+            const id = decodeURIComponent(String(variables.id));
+            const state = await this.adapter.getForeignStateAsync(id, { user: this.defaultUser });
+            const body = state
+                ? { id, val: state.val, ack: state.ack, ts: state.ts, lc: state.lc, q: state.q }
+                : { id, val: null };
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(body) }] };
+        });
+        server.registerResource('object', new mcp_js_1.ResourceTemplate('iobobject://{id}', { list: undefined }), {
             title: 'ioBroker object',
             description: 'A single ioBroker object, addressed as iobobject://<id>',
             mimeType: 'application/json',
@@ -1912,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',
@@ -1947,9 +2715,6 @@ class McpServer {
                 name,
                 adapter: sourceAdapter,
             });
-            if (results.length >= limit) {
-                break;
-            }
         }
         return results;
     }
@@ -2036,27 +2801,7 @@ class McpServer {
         const lang = params.language || this.language;
         const needle = (params.query || '').toLowerCase();
         const limit = params.limit ?? 20;
-        const reposObj = await this.adapter.getForeignObjectAsync('system.repositories', { user: this.defaultUser });
-        const repositories = (reposObj?.native?.repositories || {});
-        // Prefer the active repository; fall back to the first repository that has content.
-        const sysCfg = await this.adapter.getForeignObjectAsync('system.config', { user: this.defaultUser });
-        const active = sysCfg?.common?.activeRepo;
-        const activeNames = Array.isArray(active) ? active : active ? [active] : [];
-        // Merge the JSON of ALL active repositories (or all repositories if none is marked active). An
-        // adapter present in several repos is kept once (first/active repo wins). This matters when the
-        // user has custom repos active next to the default one (their adapters are not in stable).
-        const activeWithJson = activeNames.filter(name => repositories[name]?.json);
-        const sources = (activeWithJson.length ? activeWithJson.map(name => repositories[name]) : Object.values(repositories))
-            .map(repo => repo?.json)
-            .filter((j) => !!j);
-        const json = {};
-        for (const src of sources) {
-            for (const key of Object.keys(src)) {
-                if (!(key in json)) {
-                    json[key] = src[key];
-                }
-            }
-        }
+        const json = await this.getRepositoryJson();
         if (!Object.keys(json).length) {
             return [];
         }
@@ -2417,17 +3162,17 @@ 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"');
-        }
-        const host = (params.host || this.adapter.host || '').replace(/^system\.host\./, '');
-        if (!host || /\s/.test(host)) {
-            throw new Error(`Invalid host "${host}"`);
+            throw new Error('Give exactly one of "source", "file_path", "file_name" + "file_content" or "upload_id"');
         }
-        const hostObj = await this.adapter.getForeignObjectAsync(`system.host.${host}`, { user: this.defaultUser });
-        if (hostObj?.type !== 'host') {
-            throw new Error(`Host "${host}" not found`);
+        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;
@@ -2451,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"');
@@ -2471,11 +3220,42 @@ class McpServer {
             source = fileName.replace(/[^a-zA-Z0-9._-]/g, '_');
             files = [{ name: source, file: data.toString('base64') }];
         }
-        const command = `url ${source} --host ${host}${params.debug ? ' --debug' : ''}`;
+        const result = await this.runHostCommand(host, `url ${source} --host ${host}${params.debug ? ' --debug' : ''}`, params.timeout, files);
+        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)
+            : [];
+        return { ...result, adapter: adapterName, restartedInstances: restarted };
+    }
+    /** Normalize a host name (with or without `system.host.`) and check that the host exists. */
+    async resolveHost(host) {
+        const name = (host || this.adapter.host || '').replace(/^system\.host\./, '');
+        if (!name || /\s/.test(name)) {
+            throw new Error(`Invalid host "${name}"`);
+        }
+        const hostObj = await this.adapter.getForeignObjectAsync(`system.host.${name}`, { user: this.defaultUser });
+        if (hostObj?.type !== 'host') {
+            throw new Error(`Host "${name}" not found`);
+        }
+        return name;
+    }
+    /**
+     * Run an ioBroker CLI command on a host via `cmdExec` and wait for its exit code. The host reports
+     * the output and the exit code as messages to this instance, see {@link onMessage}.
+     *
+     * @param host host name without `system.host.`
+     * @param command the CLI arguments, e.g. `upgrade hue@3.9.0`
+     * @param timeoutSeconds how long to wait; the command keeps running on the host after that
+     * @param files files sent along with the command (the command refers to them by name)
+     */
+    async runHostCommand(host, command, timeoutSeconds, files) {
         const id = `mcp-${(0, node_crypto_1.randomUUID)()}`;
-        const timeout = (params.timeout ?? DEFAULT_INSTALL_TIMEOUT) * 1000;
+        const timeout = (timeoutSeconds ?? DEFAULT_INSTALL_TIMEOUT) * 1000;
         const output = [];
-        this.adapter.log.info(`[install_package] ${host}: iobroker ${command}`);
+        this.adapter.log.info(`[cmdExec] ${host}: iobroker ${command}`);
         const exitCode = await new Promise(resolve => {
             const timer = setTimeout(() => {
                 this.cmdSessions.delete(id);
@@ -2490,34 +3270,538 @@ class McpServer {
             });
             this.adapter.sendToHost(`system.host.${host}`, 'cmdExec', { data: command, id, files });
         });
-        const adapterName = extractAdapterName(params.file_path || params.file_name || params.source || '');
-        const restarted = [];
-        if (exitCode === 0 && adapterName && params.restart_instances !== false) {
-            // Like admin: touching the instance object makes the controller restart it with the new code
-            const instances = await this.adapter.getForeignObjectsAsync(`system.adapter.${adapterName}.*`, 'instance', {
-                user: this.defaultUser,
-            });
-            for (const [instanceId, instance] of Object.entries(instances || {})) {
-                if (instance?.common?.enabled) {
-                    await this.adapter.extendForeignObjectAsync(instanceId, {}, { user: this.defaultUser });
-                    restarted.push(instanceId.replace('system.adapter.', ''));
-                }
-            }
-        }
         return {
             host,
             command: `iobroker ${command}`,
-            adapter: adapterName,
             ...(exitCode === null
                 ? {
                     finished: false,
-                    note: `No result after ${timeout / 1000}s - the installation keeps running on the host, check the log`,
+                    note: `No result after ${timeout / 1000}s - the command keeps running on the host, check the log`,
                 }
                 : { finished: true, success: exitCode === 0, exitCode }),
-            restartedInstances: restarted,
             output,
         };
     }
+    /** Request something from a host (`getNotifications`, ...) and wait for the answer. */
+    hostRequest(host, command, message) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`Host "${host}" did not answer "${command}"`)), 10_000);
+            this.adapter.sendToHost(`system.host.${host}`, command, message, (result) => {
+                clearTimeout(timer);
+                if (result?.error) {
+                    reject(new Error(result.error));
+                }
+                else {
+                    resolve(result);
+                }
+            });
+        });
+    }
+    /** Like admin after an installation: touching the instance objects makes the controller restart them. */
+    async restartAdapterInstances(adapterName) {
+        const instances = await this.adapter.getForeignObjectsAsync(`system.adapter.${adapterName}.*`, 'instance', {
+            user: this.defaultUser,
+        });
+        const restarted = [];
+        for (const [instanceId, instance] of Object.entries(instances || {})) {
+            if (instance?.common?.enabled) {
+                await this.adapter.extendForeignObjectAsync(instanceId, {}, { user: this.defaultUser });
+                restarted.push(instanceId.replace('system.adapter.', ''));
+            }
+        }
+        return restarted;
+    }
+    /** Read an instance object by its short id (`hue.0`) or full id (`system.adapter.hue.0`). */
+    async getInstance(id) {
+        const shortId = id.replace(/^system\.adapter\./, '');
+        if (!/^[a-z0-9][a-z0-9_-]*\.\d+$/i.test(shortId)) {
+            throw new Error(`Invalid instance "${id}", expected e.g. "hue.0"`);
+        }
+        const fullId = `system.adapter.${shortId}`;
+        const obj = await this.adapter.getForeignObjectAsync(fullId, { user: this.defaultUser });
+        if (obj?.type !== 'instance') {
+            throw new Error(`Instance "${shortId}" not found`);
+        }
+        return { id: shortId, fullId, obj: obj };
+    }
+    /** Start (enable) or stop (disable) an instance. */
+    async setInstanceEnabled(id, enabled) {
+        const instance = await this.getInstance(id);
+        const changed = !!instance.obj.common.enabled !== enabled;
+        if (changed) {
+            await this.adapter.extendForeignObjectAsync(instance.fullId, { common: { enabled } }, { user: this.defaultUser });
+        }
+        return { id: instance.id, enabled, changed };
+    }
+    /** Restart a running instance. */
+    async restartInstance(id) {
+        const instance = await this.getInstance(id);
+        if (!instance.obj.common.enabled) {
+            throw new Error(`Instance "${instance.id}" is not enabled - start it instead`);
+        }
+        await this.adapter.extendForeignObjectAsync(instance.fullId, {}, { user: this.defaultUser });
+        return { id: instance.id, restarted: true };
+    }
+    /**
+     * Change the log level of an instance: temporarily via its `logLevel` state (no restart, until the
+     * next start), or persistently in the instance object (restarts the instance).
+     */
+    async setLogLevel(id, level, persistent) {
+        const instance = await this.getInstance(id);
+        if (persistent) {
+            await this.adapter.extendForeignObjectAsync(instance.fullId, { common: { loglevel: level } }, { user: this.defaultUser });
+        }
+        else {
+            await this.adapter.setForeignStateAsync(`${instance.fullId}.logLevel`, level, false, {
+                user: this.defaultUser,
+            });
+        }
+        return { id: instance.id, level, persistent: !!persistent };
+    }
+    /** Check an adapter name, as the CLI receives it as an argument. */
+    static checkAdapterName(name) {
+        const adapterName = name
+            .trim()
+            .replace(/^iobroker\./i, '')
+            .toLowerCase();
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(adapterName)) {
+            throw new Error(`Invalid adapter name "${name}"`);
+        }
+        return adapterName;
+    }
+    /** Create an instance of an adapter (installs the adapter from the repository if necessary). */
+    async addInstance(params) {
+        const adapterName = McpServer.checkAdapterName(params.adapter);
+        const host = await this.resolveHost(params.host);
+        if (params.instance !== undefined) {
+            const existing = await this.adapter.getForeignObjectAsync(`system.adapter.${adapterName}.${params.instance}`, { user: this.defaultUser });
+            if (existing) {
+                throw new Error(`Instance "${adapterName}.${params.instance}" already exists`);
+            }
+        }
+        return this.runHostCommand(host, `add ${adapterName}${params.instance !== undefined ? ` ${params.instance}` : ''} --host ${host}`, params.timeout);
+    }
+    /** Delete an instance with its objects and states (on the host it runs on). */
+    async deleteInstance(params) {
+        const instance = await this.getInstance(params.id);
+        const host = await this.resolveHost(instance.obj.common.host);
+        return this.runHostCommand(host, `del ${instance.id}`, params.timeout);
+    }
+    /** Upgrade an installed adapter to the repository version (or the given one). */
+    async upgradeAdapter(params) {
+        const adapterName = McpServer.checkAdapterName(params.adapter);
+        if (params.version !== undefined && !/^\d+\.\d+\.\d+[\w.+-]*$/.test(params.version)) {
+            throw new Error(`Invalid version "${params.version}"`);
+        }
+        const adapterObj = await this.adapter.getForeignObjectAsync(`system.adapter.${adapterName}`, {
+            user: this.defaultUser,
+        });
+        if (adapterObj?.type !== 'adapter') {
+            throw new Error(`Adapter "${adapterName}" is not installed - use add_instance to install it`);
+        }
+        const version = params.version || (await this.getRepositoryJson())[adapterName]?.version;
+        if (!version) {
+            throw new Error(`Adapter "${adapterName}" is not in the active repository, give a version`);
+        }
+        const host = await this.resolveHost(params.host);
+        return this.runHostCommand(host, `upgrade ${adapterName}@${version}`, params.timeout);
+    }
+    /** List the installed adapters that have a newer version in the active repository. */
+    async listAdapterUpdates() {
+        const repo = await this.getRepositoryJson();
+        const result = [];
+        for (const adapter of await this.listAdapters()) {
+            const name = adapter.name;
+            const available = repo[name]?.version;
+            if (available && compareVersions(available, adapter.version) > 0) {
+                result.push({ name, installed: adapter.version, available, title: adapter.title });
+            }
+        }
+        return result;
+    }
+    /**
+     * Read the JSON of the active repositories from `system.repositories` (or of all repositories if none
+     * is marked active). An adapter present in several repos is kept once (first/active repo wins). This
+     * matters when the user has custom repos active next to the default one.
+     */
+    async getRepositoryJson() {
+        const reposObj = await this.adapter.getForeignObjectAsync('system.repositories', { user: this.defaultUser });
+        const repositories = (reposObj?.native?.repositories || {});
+        const sysCfg = await this.adapter.getForeignObjectAsync('system.config', { user: this.defaultUser });
+        const active = sysCfg?.common?.activeRepo;
+        const activeNames = Array.isArray(active) ? active : active ? [active] : [];
+        const activeWithJson = activeNames.filter(name => repositories[name]?.json);
+        const sources = (activeWithJson.length ? activeWithJson.map(name => repositories[name]) : Object.values(repositories))
+            .map(repo => repo?.json)
+            .filter((j) => !!j);
+        const json = {};
+        for (const src of sources) {
+            for (const key of Object.keys(src)) {
+                if (!(key in json)) {
+                    json[key] = src[key];
+                }
+            }
+        }
+        return json;
+    }
+    /** Read the current notifications of one or all hosts, one entry per category and instance. */
+    async listNotifications(params) {
+        const lang = params.language || this.language;
+        const hosts = params.host
+            ? [await this.resolveHost(params.host)]
+            : (await this.listHosts()).filter(host => host.alive).map(host => host.id);
+        const result = [];
+        for (const host of hosts) {
+            const answer = await this.hostRequest(host, 'getNotifications', {});
+            const scopes = (answer?.result || {});
+            for (const [scope, scopeObj] of Object.entries(scopes)) {
+                const categories = (scopeObj?.categories || {});
+                for (const [category, categoryObj] of Object.entries(categories)) {
+                    const instances = (categoryObj?.instances || {});
+                    for (const [instance, instanceObj] of Object.entries(instances)) {
+                        const messages = (instanceObj?.messages || []);
+                        if (!messages.length) {
+                            continue;
+                        }
+                        result.push({
+                            host,
+                            scope,
+                            category,
+                            instance: instance.replace(/^system\.adapter\./, ''),
+                            severity: categoryObj.severity,
+                            name: getText(categoryObj.name, lang),
+                            description: getText(categoryObj.description, lang),
+                            messages: messages.map(one => ({ message: one.message, ts: one.ts })),
+                        });
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    /** Acknowledge (delete) notifications on a host, optionally only of one scope/category/instance. */
+    async clearNotifications(params) {
+        const host = await this.resolveHost(params.host);
+        const instance = params.instance ? `system.adapter.${params.instance.replace(/^system\.adapter\./, '')}` : null;
+        await this.hostRequest(host, 'clearNotifications', {
+            scope: params.scope || null,
+            category: params.category || null,
+            instance,
+        });
+        return { host, cleared: true };
+    }
+    /**
+     * Normalize a script id: `script.js.common.lights`, `common.lights` or `lights` (folder `common`).
+     * Every segment is reduced to the characters the javascript editor uses for ids.
+     */
+    static scriptId(id) {
+        let path = id.trim().replace(/^script\.js\./, '');
+        if (!path.includes('.')) {
+            path = `common.${path}`;
+        }
+        const segments = path.split('.').map(segment => segment.trim().replace(/[^\p{L}\p{N}_-]/gu, '_'));
+        if (segments.some(segment => !segment)) {
+            throw new Error(`Invalid script id "${id}"`);
+        }
+        return `script.js.${segments.join('.')}`;
+    }
+    /** Summary of a script object, optionally with its source. */
+    scriptInfo(id, obj, withSource) {
+        const common = (obj.common || {});
+        return {
+            id,
+            name: this.getName(common.name),
+            engineType: common.engineType || 'Javascript/js',
+            enabled: !!common.enabled,
+            engine: (common.engine || '').replace(/^system\.adapter\./, ''),
+            ...(withSource ? { source: common.source || '' } : {}),
+        };
+    }
+    /** Read a script object, failing if it is missing or not a script. */
+    async getScriptObject(id) {
+        const scriptId = McpServer.scriptId(id);
+        const obj = await this.adapter.getForeignObjectAsync(scriptId, { user: this.defaultUser });
+        if (obj?.type !== 'script') {
+            throw new Error(`Script "${scriptId}" not found`);
+        }
+        return { id: scriptId, obj };
+    }
+    /** List the scripts of the javascript adapter (without their source). */
+    async listScripts(folder) {
+        const prefix = folder ? `script.js.${folder.replace(/^script\.js\./, '').replace(/\.$/, '')}.` : 'script.js.';
+        const objs = await this.adapter.getForeignObjectsAsync(`${prefix}*`, 'script', { user: this.defaultUser });
+        return Object.entries(objs || {}).map(([id, obj]) => this.scriptInfo(id, obj));
+    }
+    /**
+     * Create a script or change the source of an existing one. Blockly and Rules scripts keep their
+     * blocks in the source, so they are not changed. New scripts start disabled unless `enabled` is given.
+     */
+    async setScript(params) {
+        const scriptId = McpServer.scriptId(params.id);
+        const existing = await this.adapter.getForeignObjectAsync(scriptId, { user: this.defaultUser });
+        if (existing && existing.type !== 'script') {
+            throw new Error(`"${scriptId}" exists and is not a script`);
+        }
+        if (existing) {
+            const engineType = existing.common.engineType || 'Javascript/js';
+            if (!/^(javascript|typescript)/i.test(engineType)) {
+                throw new Error(`"${scriptId}" is a ${engineType} script; only JavaScript/TypeScript can be changed`);
+            }
+            const common = { source: params.source };
+            if (params.name !== undefined) {
+                common.name = params.name;
+            }
+            if (params.enabled !== undefined) {
+                common.enabled = params.enabled;
+            }
+            await this.adapter.extendForeignObjectAsync(scriptId, { common }, { user: this.defaultUser });
+            return { id: scriptId, created: false };
+        }
+        const engine = (await this.getInstance(params.instance || 'javascript.0')).id;
+        // The parent folders are channels, like the javascript editor creates them
+        const segments = scriptId.split('.');
+        for (let i = 3; i < segments.length; i++) {
+            const folderId = segments.slice(0, i).join('.');
+            if (!(await this.adapter.getForeignObjectAsync(folderId, { user: this.defaultUser }))) {
+                await this.adapter.setForeignObjectAsync(folderId, { type: 'channel', common: { name: segments[i - 1] }, native: {} }, { user: this.defaultUser });
+            }
+        }
+        await this.adapter.setForeignObjectAsync(scriptId, {
+            type: 'script',
+            common: {
+                name: params.name || segments[segments.length - 1],
+                expert: true,
+                engineType: params.engineType || 'Javascript/js',
+                enabled: !!params.enabled,
+                engine: `system.adapter.${engine}`,
+                source: params.source,
+                debug: false,
+                verbose: false,
+            },
+            native: {},
+        }, { user: this.defaultUser });
+        return { id: scriptId, created: true };
+    }
+    /** Enable (start) or disable (stop) a script. */
+    async enableScript(id, enabled) {
+        const script = await this.getScriptObject(id);
+        await this.adapter.extendForeignObjectAsync(script.id, { common: { enabled } }, { user: this.defaultUser });
+        return { id: script.id, enabled };
+    }
+    /** Delete a script. */
+    async deleteScript(id) {
+        const script = await this.getScriptObject(id);
+        await this.adapter.delForeignObjectAsync(script.id, { user: this.defaultUser });
+        return { id: script.id, deleted: true };
+    }
+    /**
+     * Run code once in the javascript adapter (its `execute` message) and return what it logged. Nothing
+     * is stored; timers and subscriptions are cleaned up after `timeout`.
+     */
+    async runScript(params) {
+        const instance = await this.getInstance(params.instance || 'javascript.0');
+        const timeout = params.timeout ?? 5000;
+        const result = await this.adapter.sendToAsync(instance.id, 'execute', { source: params.source, engineType: params.engineType, timeout, verbose: false, logLevel: 'info' }, { timeout: timeout + 15_000, user: this.defaultUser });
+        if (!result || typeof result !== 'object') {
+            throw new Error(`"${instance.id}" did not answer - javascript adapter 10.1.0 or newer is required`);
+        }
+        return result;
+    }
+    /** Whether `send_to` may address this instance (by adapter name, instance or `*`). */
+    isSendToAllowed(instance) {
+        const allowed = (this.config.sendToAllowlist || '')
+            .split(/[\s,;]+/)
+            .map(one => one.replace(/^system\.adapter\./, ''))
+            .filter(Boolean);
+        return allowed.includes('*') || allowed.includes(instance) || allowed.includes(instance.split('.')[0]);
+    }
+    /** Send a message to an adapter instance (`sendTo`) and return its answer. */
+    async sendToInstance(params) {
+        const instance = await this.getInstance(params.instance);
+        if (!this.isSendToAllowed(instance.id)) {
+            throw new Error(`"${instance.id}" is not in the allowlist of send_to`);
+        }
+        const response = await this.adapter.sendToAsync(instance.id, params.command, (params.message ?? {}), { timeout: params.timeout ?? 10_000, user: this.defaultUser });
+        return { instance: instance.id, command: params.command, response: response ?? null };
+    }
+    /**
+     * Create an alias (`alias.0.*`) that points to another state. Type, role, unit and limits are copied
+     * from the target unless given.
+     */
+    async createAlias(params) {
+        const id = params.id.startsWith('alias.') ? params.id : `alias.0.${params.id}`;
+        if (!/^alias\.\d+\.[^*\s]+$/.test(id)) {
+            throw new Error(`Invalid alias id "${params.id}"`);
+        }
+        if (await this.adapter.getForeignObjectAsync(id, { user: this.defaultUser })) {
+            throw new Error(`Object "${id}" already exists`);
+        }
+        const target = await this.adapter.getForeignObjectAsync(params.target, { user: this.defaultUser });
+        if (target?.type !== 'state') {
+            throw new Error(`Target "${params.target}" is not a state`);
+        }
+        if (params.write_target) {
+            const writeTarget = await this.adapter.getForeignObjectAsync(params.write_target, {
+                user: this.defaultUser,
+            });
+            if (writeTarget?.type !== 'state') {
+                throw new Error(`Write target "${params.write_target}" is not a state`);
+            }
+        }
+        const source = target.common;
+        const common = {
+            name: params.name || source.name || id.split('.').pop(),
+            type: source.type || 'mixed',
+            role: params.role || source.role || 'state',
+            read: source.read !== false,
+            write: params.write_target ? true : source.write !== false,
+            alias: {
+                id: params.write_target ? { read: params.target, write: params.write_target } : params.target,
+            },
+        };
+        for (const key of ['min', 'max', 'step', 'states']) {
+            if (source[key] !== undefined) {
+                common[key] = source[key];
+            }
+        }
+        if (params.unit !== undefined || source.unit !== undefined) {
+            common.unit = params.unit ?? source.unit;
+        }
+        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) {
@@ -2558,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();