@iobroker/mcp-server 1.7.0 → 1.8.0

package/build/index.js

@@ -40,6 +40,57 @@ const AGG_MAP = {
     integral: 'integral',
 };
 const WEB_EXTENSION_PREFIX = 'mcp/';
+/** Arguments of tool calls whose values are not written to the log, besides file contents (may hold secrets). */
+const LOG_HIDDEN_ARGS = {
+    send_to: ['message'],
+    set_script: ['source'],
+    run_script: ['source'],
+};
+/** Values of tool arguments are cut after this many characters in the log. */
+const LOG_ARG_LENGTH = 200;
+const objectWrite = (rights) => !!rights.object?.write;
+const fileWrite = (rights) => !!rights.file?.write;
+const execute = (rights) => !!rights.other?.execute;
+const sendTo = (rights) => !!rights.other?.sendto;
+/**
+ * The general rights (of the groups of the ioBroker user) without which a tool cannot succeed: such tools are not
+ * offered to the sessions of the user. Tools not listed here are offered to everyone.
+ */
+const TOOL_RIGHTS = {
+    set_state: rights => !!rights.state?.write,
+    set_states: rights => !!rights.state?.write,
+    set_object: objectWrite,
+    create_state: objectWrite,
+    create_scene: objectWrite,
+    create_alias: objectWrite,
+    delete_object: rights => !!rights.object?.delete,
+    write_file: fileWrite,
+    rename_file: fileWrite,
+    mkdir: fileWrite,
+    delete_file: rights => !!rights.file?.delete,
+    start_instance: objectWrite,
+    stop_instance: objectWrite,
+    restart_instance: objectWrite,
+    // persistently in the instance object, or temporarily in its logLevel state
+    set_log_level: rights => objectWrite(rights) || !!rights.state?.write,
+    add_instance: execute,
+    delete_instance: execute,
+    upgrade_adapter: execute,
+    install_package: execute,
+    // for write_file or install_package
+    prepare_upload: rights => fileWrite(rights) || execute(rights),
+    set_script: objectWrite,
+    enable_script: objectWrite,
+    delete_script: rights => !!rights.object?.delete,
+    run_script: sendTo,
+    send_to: sendTo,
+};
+/** Default time `wait_for_state` waits (seconds). */
+const DEFAULT_WAIT_TIMEOUT = 30;
+/** Longest wait of `wait_for_state` and `set_state` (seconds): many MCP clients give up on a call after 60 s. */
+const MAX_WAIT_TIMEOUT = 50;
+/** How often a state is read while waiting for it (ms). */
+const STATE_POLL_INTERVAL = 250;
 const LOOPBACK = new node_net_1.default.BlockList();
 LOOPBACK.addSubnet('127.0.0.0', 8, 'ipv4');
 LOOPBACK.addAddress('::1', 'ipv6');
@@ -181,6 +232,8 @@ class McpServer {
     subscriptionCounts = {};
     /** Recent log lines kept for `ioblog://` resource reads (filled while there are log subscribers). */
     logBuffer = [];
+    /** The tools of every server created by {@link createServer}, for {@link hideToolsWithoutRights}. */
+    registeredTools = new WeakMap();
     config;
     extension;
     routerPrefix;
@@ -320,11 +373,50 @@ class McpServer {
      * Build a fresh MCP SDK server with all ioBroker tools registered, ready to be connected to an
      * arbitrary transport. Used for in-process embedding (e.g. by ioBroker.admin) over an
      * InMemoryTransport, where there is no HTTP server/session layer. The caller owns the lifecycle
-     * of the returned server (connect it to a transport, and `close()` it when done).
+     * of the returned server (connect it to a transport, and `close()` it when done). Call
+     * {@link hideToolsWithoutRights} before connecting it to offer only the tools the user may use.
      */
     createInProcessServer() {
         return this.createServer(new Set());
     }
+    /**
+     * Do not offer the tools the user cannot use, because its groups lack a general right the tool needs (e.g.
+     * `install_package` without "execute"), so the client does not try them in vain. Administrators get all
+     * tools. The rights are read once, before the server is connected: changed rights apply to new sessions,
+     * and every call is checked anyway.
+     *
+     * @param server a server returned by {@link createInProcessServer}
+     * @param user the ioBroker user of the session (default: the configured default user)
+     * @returns the names of the hidden tools
+     */
+    async hideToolsWithoutRights(server, user = this.defaultUser) {
+        const tools = this.registeredTools.get(server);
+        if (!tools || user === 'system.user.admin') {
+            return [];
+        }
+        let rights;
+        try {
+            rights = await this.adapter.calculatePermissionsAsync(user, []);
+        }
+        catch (e) {
+            this.adapter.log.warn(`Cannot read the rights of ${user}, all tools are offered: ${e instanceof Error ? e.message : e}`);
+            return [];
+        }
+        if (rights.groups?.includes('system.group.administrator')) {
+            return [];
+        }
+        const hidden = [];
+        for (const [name, tool] of tools) {
+            if (TOOL_RIGHTS[name] && !TOOL_RIGHTS[name](rights)) {
+                tool.disable();
+                hidden.push(name);
+            }
+        }
+        if (hidden.length) {
+            this.adapter.log.debug(`MCP tools not offered to ${user} for lack of rights: ${hidden.join(', ')}`);
+        }
+        return hidden;
+    }
     /**
      * Convenience factory for embedding the MCP server inside another adapter's process (no HTTP).
      * The returned instance is not wired to any Express app; obtain a tool server via
@@ -733,6 +825,7 @@ class McpServer {
                     this.adapter.log.debug(`MCP session closed: ${sid}`);
                 }
             };
+            await this.hideToolsWithoutRights(server, user);
             await server.connect(transport);
         }
         const sessionTransport = transport;
@@ -894,6 +987,76 @@ class McpServer {
         }
         session.subscriptions.clear();
     }
+    /**
+     * Remember every tool registered on `server` afterwards (for {@link hideToolsWithoutRights}) and log its
+     * calls: a failed call as a warning with the tool and its arguments, a successful call of a writing tool
+     * (not `readOnlyHint`) at info level, so the log shows who changed what.
+     *
+     * @param server the server whose `registerTool` is wrapped
+     */
+    trackTools(server) {
+        const register = server.registerTool.bind(server);
+        const tools = new Map();
+        this.registeredTools.set(server, tools);
+        server.registerTool = (name, config, handler) => {
+            const tool = register(name, config, async (...params) => {
+                // Tools with an input schema get (args, extra), the others only (extra)
+                const call = `${name}(${McpServer.describeArgs(name, params.length > 1 ? params[0] : undefined)})`;
+                let result;
+                try {
+                    result = await handler(...params);
+                }
+                catch (e) {
+                    this.adapter.log.warn(`MCP tool error in ${call} by ${this.user}: ${e instanceof Error ? e.message : e}`);
+                    throw e;
+                }
+                if (result?.isError) {
+                    let error = result.content?.[0]?.text;
+                    try {
+                        error = JSON.parse(error).error ?? error;
+                    }
+                    catch {
+                        // not JSON: log the text as it is
+                    }
+                    this.adapter.log.warn(`MCP tool error in ${call} by ${this.user}: ${error}`);
+                }
+                else if (config?.annotations?.readOnlyHint === false) {
+                    this.adapter.log.info(`MCP ${this.user}: ${call}`);
+                }
+                return result;
+            });
+            tools.set(name, tool);
+            return tool;
+        };
+    }
+    /**
+     * The arguments of a tool call for the log: long values are shortened, and contents that may hold secrets
+     * or large data (file contents, script code, message payloads) are replaced by their size.
+     *
+     * @param tool name of the tool
+     * @param args arguments of the call
+     */
+    static describeArgs(tool, args) {
+        if (!args || typeof args !== 'object') {
+            return '';
+        }
+        const hidden = ['content', 'file_content', ...(LOG_HIDDEN_ARGS[tool] || [])];
+        const parts = [];
+        for (const [key, value] of Object.entries(args)) {
+            if (value === undefined) {
+                continue;
+            }
+            let text = JSON.stringify(value) ?? String(value);
+            if (hidden.includes(key)) {
+                text = `<${text.length} chars>`;
+            }
+            else if (text.length > LOG_ARG_LENGTH) {
+                text = `${text.slice(0, LOG_ARG_LENGTH)}...`;
+            }
+            parts.push(`${key}=${text}`);
+        }
+        return parts.join(', ');
+    }
     /**
      * Create a new MCP SDK server with all ioBroker tools registered.
      *
@@ -902,9 +1065,10 @@ class McpServer {
      */
     createServer(subscriptions, baseUrl) {
         const server = new mcp_js_1.McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {}, resources: { subscribe: true } } });
+        this.trackTools(server);
+        // Logged by trackTools, together with the tool and its arguments
         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;
@@ -1014,6 +1178,93 @@ class McpServer {
                 return fail(e);
             }
         });
+        server.registerTool('wait_for_state', {
+            title: 'Wait for a state value',
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            description: 'Wait until a state has the given `value` - or, without `value`, until it is updated - and ' +
+                'return the state, e.g. to check that a device really switched or a process finished. ' +
+                `Gives up after \`timeout\` seconds (default ${DEFAULT_WAIT_TIMEOUT}) with reached=false. ` +
+                `The state is read every ${STATE_POLL_INTERVAL} ms, so a value that lasts shorter can be missed.`,
+            inputSchema: {
+                id: zod_1.z.string().describe('State ID'),
+                value: zod_1.z
+                    .any()
+                    .optional()
+                    .describe('Expected value (coerced to the state type); omit it to wait for the next update'),
+                ack: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Only accept a state with this flag: true = confirmed by the device, false = command'),
+                timeout: zod_1.z
+                    .number()
+                    .min(0)
+                    .max(MAX_WAIT_TIMEOUT)
+                    .optional()
+                    .describe(`Seconds to wait at most (default ${DEFAULT_WAIT_TIMEOUT})`),
+            },
+        }, async ({ id, value, ack, timeout }, extra) => {
+            try {
+                const seconds = timeout ?? DEFAULT_WAIT_TIMEOUT;
+                const obj = await this.adapter.getForeignObjectAsync(id, { user: this.user });
+                const expected = McpServer.coerceValue(value, obj?.common?.type);
+                const initial = await this.adapter.getForeignStateAsync(id, { user: this.user });
+                const result = await this.waitForState(id, state => !!state &&
+                    (ack === undefined || state.ack === ack) &&
+                    (value === undefined
+                        ? !initial || state.ts !== initial.ts
+                        : McpServer.sameValue(state.val, expected)), seconds, extra.signal);
+                return ok({
+                    ok: true,
+                    data: {
+                        id,
+                        reached: result.reached,
+                        state: result.state ?? null,
+                        waited_ms: result.waited,
+                        ...(result.reached
+                            ? {}
+                            : {
+                                hint: `${value === undefined ? 'Not updated' : 'The value was not reached'} within ${seconds} s`,
+                            }),
+                    },
+                });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
+        server.registerTool('find_orphan_states', {
+            title: 'Find states without object',
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            description: 'Find states that have no object, e.g. "system.adapter.vis.0.alive" left over from a deleted ' +
+                'instance. The other tools and admin do not show them, but scripts and visualizations may still ' +
+                'read their old values. `pattern` selects the states to check, e.g. "system.adapter.*" or ' +
+                '"hue.0.*"; "*" checks all states and objects, which takes a while on large installations. ' +
+                'Found states can be deleted on the host with `iobroker state del <id>`.',
+            inputSchema: {
+                pattern: zod_1.z
+                    .string()
+                    .min(1)
+                    .describe('IDs of the states to check, wildcards "*" allowed, e.g. "system.adapter.*"'),
+                offset: offsetSchema,
+            },
+        }, async ({ pattern, offset }) => {
+            try {
+                const { checked, orphans } = await this.findOrphanStates(pattern);
+                const page = fitItems(orphans, offset);
+                return ok({
+                    ok: true,
+                    data: {
+                        pattern,
+                        checked,
+                        orphans: page.items,
+                        ...pageInfo(page, orphans, 'orphans.json'),
+                    },
+                });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
         if (this.config.allowSetState) {
             server.registerTool('set_state', {
                 title: 'Set a state value',
@@ -1023,7 +1274,10 @@ class McpServer {
                     idempotentHint: true,
                     openWorldHint: false,
                 },
-                description: 'Set the value of a state. The value is coerced to the state type (boolean/number/string).',
+                description: 'Set the value of a state. The value is coerced to the state type (boolean/number/string). ' +
+                    'With `wait_ack`, wait until the adapter of the device confirms the command (ack=true) and ' +
+                    'return the confirmed state - its value may differ from the written one, e.g. when the ' +
+                    'device limits it.',
                 inputSchema: {
                     id: zod_1.z.string().describe('State ID'),
                     value: zod_1.z.any().describe('New value (type depends on the state)'),
@@ -1035,11 +1289,41 @@ class McpServer {
                         // fields of the other tools, which pass their defaults in code instead.
                         .object({ ack: zod_1.z.boolean().default(false), expire: zod_1.z.number().int().nullable().optional() })
                         .optional(),
+                    wait_ack: zod_1.z
+                        .number()
+                        .min(0)
+                        .max(MAX_WAIT_TIMEOUT)
+                        .optional()
+                        .describe('Wait up to this many seconds for the confirmation (ack=true) by the adapter of the ' +
+                        'device (only for a command, i.e. ack=false)'),
                 },
-            }, async ({ id, value, options }) => {
+            }, async ({ id, value, options, wait_ack }, extra) => {
                 try {
-                    const written = await this.setState(id, value, options?.ack ?? false);
-                    return ok({ ok: true, data: { id, value: written } });
+                    const ack = options?.ack ?? false;
+                    const written = await this.setState(id, value, ack);
+                    const data = { id, value: written };
+                    if (wait_ack && !ack) {
+                        try {
+                            // Our command is stored with ack=false, so a state with ack=true is the answer
+                            const result = await this.waitForState(id, state => !!state?.ack, wait_ack, extra.signal);
+                            Object.assign(data, {
+                                acked: result.reached,
+                                state: result.state,
+                                waited_ms: result.waited,
+                                ...(result.reached
+                                    ? {}
+                                    : {
+                                        hint: `The value was written, but not confirmed within ${wait_ack} s: the ` +
+                                            'device may be unreachable, or no adapter processes this state',
+                                    }),
+                            });
+                        }
+                        catch (e) {
+                            data.acked = false;
+                            data.ackError = `The value was written, but the confirmation cannot be read: ${e instanceof Error ? e.message : e}`;
+                        }
+                    }
+                    return ok({ ok: true, data });
                 }
                 catch (e) {
                     return fail(e);
@@ -1080,8 +1364,9 @@ class McpServer {
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
             description: 'Retrieve recent ioBroker log lines from the host log file. Each entry has {ts, level, ' +
                 'source, message}. Optionally filter by `level` (error/warn/info/debug), by `adapter` ' +
-                '(source, e.g. "hm-rpc.0" or "hm-rpc"), or from `from_ts` (ms). When a level filter is set, ' +
-                'a larger window of the log is scanned so errors/warnings are not hidden behind debug spam. ' +
+                '(source, e.g. "hm-rpc.0" or "hm-rpc"), from `from_ts` (ms), or by `search` in the message. ' +
+                'When a filter is set, a larger window of the log is scanned so the matching lines are not ' +
+                'hidden behind debug spam. ' +
                 '`logFile` tells the time of the newest line in the file and its size: if they do not change ' +
                 'between calls, the host does not see new log lines.',
             inputSchema: {
@@ -1089,6 +1374,11 @@ class McpServer {
                 from_ts: zod_1.z.number().int().optional(),
                 limit: zod_1.z.number().int().optional().describe('Maximum number of lines to return (default 200)'),
                 adapter: zod_1.z.string().optional(),
+                search: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Only lines whose message contains this text (case-insensitive), or matches it as a ' +
+                    'regular expression when written as /pattern/flags, e.g. "/timeout|ECONNREFUSED/i"'),
             },
         }, async (args) => {
             try {
@@ -2003,6 +2293,8 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
+                    // Before asking: the user should not confirm what is denied anyway
+                    await this.assertOtherPermission('execute', 'run commands on a host');
                     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) });
                 }
@@ -2028,6 +2320,7 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
+                    await this.assertOtherPermission('execute', 'run commands on a host');
                     await confirm(`Upgrade the adapter "${args.adapter}"${args.version ? ` to ${args.version}` : ''}?`);
                     return ok({ ok: true, data: await this.upgradeAdapter(args) });
                 }
@@ -2133,6 +2426,7 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
+                    await this.assertOtherPermission('execute', 'run commands on a host');
                     await confirm(`Install the package "${args.source || args.file_path || args.file_name || args.upload_id}"? It runs with full rights on the host.`);
                     return ok({ ok: true, data: await this.installPackage(args) });
                 }
@@ -2241,6 +2535,7 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
+                    await this.assertOtherPermission('sendto', 'send messages to adapters');
                     await confirm('Run the code in the javascript adapter?');
                     return ok({ ok: true, data: await this.runScript(args) });
                 }
@@ -2276,6 +2571,7 @@ class McpServer {
                 },
             }, async (args) => {
                 try {
+                    await this.assertOtherPermission('sendto', 'send messages to adapters');
                     await confirm(`Send "${args.command}" to "${args.instance}"?`);
                     return ok({ ok: true, data: await this.sendToInstance(args) });
                 }
@@ -2473,6 +2769,26 @@ class McpServer {
         }
         return results;
     }
+    /**
+     * Verify a right of the "other" category of the user, like admin does for `cmdExec` (`execute`) and
+     * `sendTo` (`sendto`). js-controller does not check them for messages, so without this an MCP user
+     * could run what the ioBroker user may not.
+     *
+     * @param operation `execute` for CLI commands on a host, `sendto` for messages to adapters
+     * @param action what was denied, for the error message (e.g. `run "iobroker url ..." on host "x"`)
+     * @throws {Error} a permissionError before anything was done
+     */
+    async assertOtherPermission(operation, action) {
+        if (this.user === 'system.user.admin') {
+            return;
+        }
+        const permissions = await this.adapter.calculatePermissionsAsync(this.user, []);
+        if (permissions.groups?.includes('system.group.administrator') || permissions.other?.[operation]) {
+            return;
+        }
+        throw new Error(`permissionError: user "${this.user}" may not ${action} (missing "${operation}" in the ` +
+            '"other" permissions of its groups) - nothing was done');
+    }
     /**
      * Verify that the user of the request may write every given state, mirroring the checks js-controller runs in
      * `setForeignState`: the user must be able to read the object (needed for the type coercion in
@@ -2648,7 +2964,30 @@ class McpServer {
      */
     getLogs(params) {
         const limit = Math.max(1, params.limit || 200);
-        const filtering = !!((params.level && params.level.length) || params.adapter || params.from_ts !== undefined);
+        // `search` is a text (case-insensitive) or a regular expression written as /pattern/flags
+        let matches;
+        if (params.search) {
+            const regExp = params.search.match(/^\/(.+)\/([a-z]*)$/);
+            if (regExp) {
+                let pattern;
+                try {
+                    // without g/y: test() would continue from the last match
+                    pattern = new RegExp(regExp[1], regExp[2].replace(/[gy]/g, ''));
+                }
+                catch (e) {
+                    return Promise.reject(new Error(`Invalid regular expression ${params.search}: ${e instanceof Error ? e.message : e}`));
+                }
+                matches = message => pattern.test(message);
+            }
+            else {
+                const text = params.search.toLowerCase();
+                matches = message => message.toLowerCase().includes(text);
+            }
+        }
+        const filtering = !!((params.level && params.level.length) ||
+            params.adapter ||
+            params.from_ts !== undefined ||
+            matches);
         // The host `getLogs` returns the tail of the log file (≈150 bytes per requested line). When a
         // filter is active, scan a much larger window so error/warn lines are not pushed out by a flood
         // of debug lines from a chatty adapter.
@@ -2669,9 +3008,14 @@ class McpServer {
                 }
                 let logs = this.parseLogLines(rawList);
                 const newestTs = logs.length ? logs[logs.length - 1].ts : undefined;
-                // The host appends the size of the log file as the last element
+                // The host appends the size of the log file as the last element: as a string after reading
+                // the file, as a number only if reading failed
                 const last = rawList[rawList.length - 1];
-                const fileSize = typeof last === 'number' ? last : undefined;
+                const fileSize = typeof last === 'number'
+                    ? last
+                    : typeof last === 'string' && /^\d+$/.test(last)
+                        ? Number(last)
+                        : undefined;
                 if (params.level && params.level.length) {
                     logs = logs.filter(log => params.level.includes(log.level));
                 }
@@ -2682,6 +3026,9 @@ class McpServer {
                     const adapter = params.adapter;
                     logs = logs.filter(log => log.source === adapter || log.source.startsWith(`${adapter}.`));
                 }
+                if (matches) {
+                    logs = logs.filter(log => matches(log.message));
+                }
                 // Return the most recent `limit` matching lines.
                 if (logs.length > limit) {
                     logs = logs.slice(logs.length - limit);
@@ -3152,6 +3499,69 @@ class McpServer {
         await this.adapter.setForeignStateAsync(id, coerced, ack, { user: this.user });
         return coerced;
     }
+    /**
+     * Read a state until `reached` accepts it, the time is up or the client cancels the call.
+     *
+     * @param id state ID
+     * @param reached the condition
+     * @param timeoutSeconds how long to wait at most
+     * @param signal aborted when the client cancels the call
+     * @returns whether the condition was met, the last read state and how long it took (ms)
+     */
+    async waitForState(id, reached, timeoutSeconds, signal) {
+        const start = Date.now();
+        const deadline = start + timeoutSeconds * 1000;
+        for (;;) {
+            const state = await this.adapter.getForeignStateAsync(id, { user: this.user });
+            const done = reached(state);
+            if (done || Date.now() >= deadline || signal?.aborted) {
+                return { reached: done, state, waited: Date.now() - start };
+            }
+            await new Promise(resolve => setTimeout(resolve, Math.min(STATE_POLL_INTERVAL, deadline - Date.now())));
+        }
+    }
+    /**
+     * Whether a state value is the expected one, also if one of them is stored as a string ("21.5" and 21.5,
+     * '{"a":1}' and {a: 1}).
+     */
+    static sameValue(actual, expected) {
+        if (actual === null || actual === undefined || expected === null || expected === undefined) {
+            return actual === expected;
+        }
+        const text = (value) => (typeof value === 'string' ? value : JSON.stringify(value));
+        return text(actual) === text(expected);
+    }
+    /**
+     * The states without object. For a pattern, js-controller returns only the states of existing state objects,
+     * except in its maintenance mode (only for the admin user), which reads the keys of the states database. The
+     * objects are read with the rights of the adapter, as an object the user may not see is still an object. A
+     * state without object has no ACL, so js-controller lets every user read it anyway.
+     *
+     * @param pattern IDs of the states to check, wildcards allowed
+     * @returns how many states were checked, and the states without object
+     */
+    async findOrphanStates(pattern) {
+        // not a literal argument: the types of the adapter do not know `maintenance`
+        const maintenance = { user: 'system.user.admin', maintenance: true };
+        const states = await this.adapter.getForeignStatesAsync(pattern, maintenance);
+        // The state objects of all IDs the pattern may match
+        const prefix = pattern.split('*')[0];
+        const view = await this.adapter.getObjectViewAsync('system', 'state', {
+            startkey: prefix,
+            endkey: `${prefix}香`,
+        });
+        const objects = new Set(view.rows.map(row => row.id));
+        const orphans = [];
+        for (const id of Object.keys(states).sort()) {
+            // the rare state of an object of another type is no orphan either
+            if (objects.has(id) || (await this.adapter.getForeignObjectAsync(id))) {
+                continue;
+            }
+            const state = states[id];
+            orphans.push({ id, val: state?.val, ack: state?.ack, ts: state?.ts, from: state?.from });
+        }
+        return { checked: Object.keys(states).length, orphans };
+    }
     /** Coerce an arbitrary value to the given ioBroker state type. */
     static coerceValue(value, type) {
         if (value === null || value === undefined) {
@@ -3460,18 +3870,35 @@ class McpServer {
             this.removeTransfer(params.upload_id);
         }
         const adapterName = extractAdapterName(params.file_path || params.file_name || upload?.name || params.source || '');
+        // The package is installed at this point: errors from here on are reported, not thrown, so the
+        // caller still learns that the installation happened
         const restartTs = Date.now();
-        const restarted = result.success && adapterName && params.restart_instances !== false
-            ? await this.restartAdapterInstances(adapterName)
-            : [];
+        const restarted = [];
+        let restartError;
+        if (result.success && adapterName && params.restart_instances !== false) {
+            try {
+                await this.restartAdapterInstances(adapterName, restarted);
+            }
+            catch (e) {
+                restartError = `Installed, but the instances could not be restarted: ${e instanceof Error ? e.message : e}`;
+            }
+        }
         const startTimeout = params.start_timeout ?? DEFAULT_START_TIMEOUT;
+        let instances;
+        if (restarted.length && startTimeout) {
+            try {
+                instances = await this.waitForStart(restarted, restartTs, startTimeout);
+            }
+            catch (e) {
+                restartError ??= `Installed, but the start of the instances could not be checked: ${e instanceof Error ? e.message : e}`;
+            }
+        }
         return {
             ...result,
             adapter: adapterName,
             restartedInstances: restarted,
-            ...(restarted.length && startTimeout
-                ? { instances: await this.waitForStart(restarted, restartTs, startTimeout) }
-                : {}),
+            ...(restartError ? { restartError } : {}),
+            ...(instances ? { instances } : {}),
         };
     }
     /**
@@ -3547,6 +3974,7 @@ class McpServer {
      * @param files files sent along with the command (the command refers to them by name)
      */
     async runHostCommand(host, command, timeoutSeconds, files) {
+        await this.assertOtherPermission('execute', `run "iobroker ${command}" on host "${host}"`);
         const id = `mcp-${(0, node_crypto_1.randomUUID)()}`;
         const timeout = (timeoutSeconds ?? DEFAULT_INSTALL_TIMEOUT) * 1000;
         const output = [];
@@ -3592,19 +4020,22 @@ class McpServer {
             });
         });
     }
-    /** Like admin after an installation: touching the instance objects makes the controller restart them. */
-    async restartAdapterInstances(adapterName) {
+    /**
+     * Like admin after an installation: touching the instance objects makes the controller restart them.
+     *
+     * @param adapterName adapter whose enabled instances are restarted
+     * @param restarted receives the ids of the restarted instances, also those before an error
+     */
+    async restartAdapterInstances(adapterName, restarted) {
         const instances = await this.adapter.getForeignObjectsAsync(`system.adapter.${adapterName}.*`, 'instance', {
             user: this.user,
         });
-        const restarted = [];
         for (const [instanceId, instance] of Object.entries(instances || {})) {
             if (instance?.common?.enabled) {
                 await this.adapter.extendForeignObjectAsync(instanceId, {}, { user: this.user });
                 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) {
@@ -3895,6 +4326,7 @@ class McpServer {
      */
     async runScript(params) {
         const instance = await this.getInstance(params.instance || 'javascript.0');
+        await this.assertOtherPermission('sendto', `run code in "${instance.id}"`);
         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.user });
         if (!result || typeof result !== 'object') {
@@ -3916,6 +4348,7 @@ class McpServer {
         if (!this.isSendToAllowed(instance.id)) {
             throw new Error(`"${instance.id}" is not in the allowlist of send_to`);
         }
+        await this.assertOtherPermission('sendto', `send messages to "${instance.id}"`);
         const response = await this.adapter.sendToAsync(instance.id, params.command, (params.message ?? {}), { timeout: params.timeout ?? 10_000, user: this.user });
         return { instance: instance.id, command: params.command, response: response ?? null };
     }