@iobroker/mcp-server 1.3.0 → 1.5.0

package/README.md

@@ -109,16 +109,44 @@ permissions regardless of which user authenticated. Give the Default User an ioB
 the ACLs the MCP client should have.
 
 ### Permissions
-- **Allow setting states**: Allow MCP clients to write state values (the `set_state` and `set_states` tools).
-  Default: **on**. Which states can be written is decided by the ACLs of the Default User. `set_states` checks the
-  write permission of all states first and writes nothing if one of them is not writable.
+All options that change the system are **off** by default; turn on only what the MCP client really needs.
+
+**States and objects**
+- **Allow setting states**: Allow MCP clients to write state values and to acknowledge system notifications (the
+  `set_state`, `set_states` and `clear_notifications` tools). Default: **on**. Which states can be written is
+  decided by the ACLs of the Default User. `set_states` checks the write permission of all states first and writes
+  nothing if one of them is not writable.
 - **Mark setting states as destructive** (`setStateDestructive`): Declare `set_state` and `set_states` with
   `destructiveHint: true`, so MCP clients can warn before a state is written. Default: **on**. When off, both tools
   are declared as non-destructive writes (`readOnlyHint` stays `false`); whether a client still asks for
   confirmation then depends on the client.
-- **Allow object/file changes**: Allow MCP clients to create/modify/delete objects and files (the `set_object`,
-  `delete_object`, `create_state`, `create_scene`, `write_file`, `delete_file`, `rename_file` and `mkdir`
-  tools). Default: **off**. When off, these tools are not exposed at all.
+- **Allow object/file changes** (`allowObjectChange`): Allow MCP clients to create/modify/delete objects, aliases
+  and files (the `set_object`, `delete_object`, `create_state`, `create_scene`, `create_alias`, `write_file`,
+  `delete_file`, `rename_file` and `mkdir` tools). Default: **off**.
+
+**System**
+- **Allow controlling instances** (`allowInstanceControl`): Start, stop and restart adapter instances and change
+  their log level (`start_instance`, `stop_instance`, `restart_instance`, `set_log_level`). Default: **off**.
+- **Allow managing adapters** (`allowAdapterManagement`): Add and delete instances and upgrade adapters from the
+  repository (`add_instance`, `delete_instance`, `upgrade_adapter`). Default: **off**.
+- **Allow changing scripts** (`allowScriptChange`): Create, change, start/stop and delete scripts of the
+  javascript adapter and run code once (`set_script`, `enable_script`, `delete_script`, `run_script`). Reading
+  scripts (`list_scripts`, `get_script`) is always possible. Scripts run with full access to ioBroker. Default:
+  **off**.
+- **Allow messages to adapters** (`sendToAllowlist`): Adapters (`telegram`) or instances (`backitup.0`) the
+  `send_to` tool may send messages to, separated by commas; `*` allows all. Default: empty, then there is no
+  `send_to` tool.
+
+**Safety**
+- **Ask for confirmation before dangerous actions** (`confirmDangerous`): MCP clients that support
+  [elicitation](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation) ask the user before an
+  object or instance is deleted, an instance stopped, an adapter upgraded or installed, a script saved or run, or a
+  message sent. Clients without elicitation rely on the `destructiveHint` of the tools and their own confirmation.
+  Default: **on**.
+- **Allow download/upload links** (`transferLinks`): Tools may hand out short-lived links for data that is too large
+  for an MCP message, see [Large results and files](#large-results-and-files). Default: **on**.
+
+**Developers**
 - **Allow installing packages (developers only)** (`allowPackageInstall`): Offer the `install_package` tool, which
   installs an adapter package on an ioBroker host - from npm, GitHub, a URL or a `.tgz` file - exactly like
   *Install from custom URL / file* in ioBroker.admin (`iobroker url ...`). Default: **off**. This option is only
@@ -157,24 +185,43 @@ Point your MCP client at:
 | `list_rooms`                | List rooms (`enum.rooms.*`) with localized names and member details; optional `language` and `withIcons`                                                                                                                                             |
 | `list_functions`            | List functions (`enum.functions.*`) with localized names and member details; optional `language` and `withIcons`                                                                                                                                     |
 | `history_query`             | Query historical values (requires a history adapter); aggregations: `raw`, `min`, `max`, `avg`, `sum`, `count`, `minmax`, `percentile`, `quantile`, `integral`                                                                                       |
-| `read_file`                 | Read a file from an adapter file storage (optional base64); large files are read in chunks via `offset`/`length` (default 512 KiB per call) — the result carries `size`, `truncated` and `nextOffset`                                                 |
+| `read_file`                 | Read a file from an adapter file storage (optional base64); large files are read in chunks via `offset`/`length` (default 512 KiB per call) — the result carries `size`, `truncated` and `nextOffset`; `download: true` returns a download link instead |
 | `list_files`                | List a directory in an adapter file storage                                                                                                                                                                                                          |
 | `file_exists`               | Check whether a file exists in an adapter file storage                                                                                                                                                                                               |
 | `get_logs`                  | Retrieve recent ioBroker log lines; optional filters by `level` (error/warn/info/debug), source `adapter` and start time (`from_ts`)                                                                                                                 |
 | `write_log`                 | Write a message to the ioBroker log                                                                                                                                                                                                                  |
 | `system_info`               | Get system and js-controller information                                                                                                                                                                                                             |
+| `list_adapter_updates`      | List installed adapters that have a newer version in the active repository                                                                                                                                                                           |
+| `list_notifications`        | List the system notifications of the hosts (the bell in admin): disk space, crashed adapters, ...                                                                                                                                                    |
+| `list_scripts`              | List the scripts of the javascript adapter (without source)                                                                                                                                                                                          |
+| `get_script`                | Read a script including its source                                                                                                                                                                                                                   |
 | `ping_host`                 | Diagnose connectivity to a network device: ICMP ping to `host` plus an optional TCP connect to `port` — useful to investigate adapter `ETIMEDOUT`/connection errors                                                                                  |
 | `set_state`                 | Set the value of a state (value coerced to the state type) — requires *Allow setting states*                                                                                                                                                         |
 | `set_states`                | Set multiple states in one call (for scenes/group actions like "all lights off") — requires *Allow setting states*                                                                                                                                   |
+| `clear_notifications`       | Acknowledge system notifications, optionally of one scope/category/instance — requires *Allow setting states*                                                                                                                                        |
 | `set_object`                | Create/update an object (merges common/native) — requires *Allow object/file changes*                                                                                                                                                                |
 | `delete_object`             | Delete an object, optionally with all children — requires *Allow object/file changes*                                                                                                                                                                |
 | `create_state`              | Create a new state object with type/role/unit/min/max and optional initial value — requires *Allow object/file changes*                                                                                                                              |
 | `create_scene`              | Create or update a scene for the ioBroker `scenes` adapter (state/value pairs applied together) — requires *Allow object/file changes*                                                                                                               |
-| `write_file`                | Write a file to an adapter file storage — requires *Allow object/file changes*                                                                                                                                                                       |
+| `create_alias`              | Create an alias (`alias.0.*`) pointing to a state, optionally with a separate write state — requires *Allow object/file changes*                                                                                                                     |
+| `write_file`                | Write a file to an adapter file storage, from `content` or from a file uploaded via `prepare_upload` (`upload_id`) — requires *Allow object/file changes*                                                                                              |
 | `delete_file`               | Delete a file from an adapter file storage — requires *Allow object/file changes*                                                                                                                                                                    |
 | `rename_file`               | Rename/move a file within the same adapter file storage — requires *Allow object/file changes*                                                                                                                                                       |
 | `mkdir`                     | Create a directory in an adapter file storage — requires *Allow object/file changes*                                                                                                                                                                 |
-| `install_package`           | Install an adapter package (npm, GitHub, URL, `.tgz` from the file storage or as base64) on a host and restart its enabled instances — requires *Allow installing packages*, developers only                                                         |
+| `prepare_upload`            | Get a one-time upload link for a file that is too large for a tool argument (e.g. a `.tgz`), for clients that can run shell commands — requires *Allow download/upload links* and *Allow object/file changes* or *Allow installing packages*           |
+| `install_package`           | Install an adapter package (npm, GitHub, URL, `.tgz` from the file storage, as base64 or uploaded via `prepare_upload`) on a host and restart its enabled instances — requires *Allow installing packages*, developers only                            |
+| `start_instance`            | Start (enable) an instance — requires *Allow controlling instances*                                                                                                                                                                                  |
+| `stop_instance`             | Stop (disable) an instance — requires *Allow controlling instances*                                                                                                                                                                                  |
+| `restart_instance`          | Restart a running instance — requires *Allow controlling instances*                                                                                                                                                                                  |
+| `set_log_level`             | Change the log level of an instance, temporarily or persistently — requires *Allow controlling instances*                                                                                                                                            |
+| `add_instance`              | Create an instance of an adapter from the repository (`iobroker add`) — requires *Allow managing adapters*                                                                                                                                           |
+| `delete_instance`           | Delete an instance with its objects and states (`iobroker del`) — requires *Allow managing adapters*                                                                                                                                                 |
+| `upgrade_adapter`           | Upgrade an adapter to the repository or a given version (`iobroker upgrade`) — requires *Allow managing adapters*                                                                                                                                    |
+| `set_script`                | Create a JavaScript/TypeScript script or change its source — requires *Allow changing scripts*                                                                                                                                                       |
+| `enable_script`             | Start or stop a script — requires *Allow changing scripts*                                                                                                                                                                                           |
+| `delete_script`             | Delete a script — requires *Allow changing scripts*                                                                                                                                                                                                  |
+| `run_script`                | Run code once in the javascript adapter and return its log output (javascript ≥ 10.1.0) — requires *Allow changing scripts*                                                                                                                          |
+| `send_to`                   | Send a message to an adapter instance (`sendTo`) and return the answer — only instances in *Allow messages to adapters*                                                                                                                              |
 
 All object/state access runs with the permissions of the configured **Default User**. The write tools are only
 registered when their respective permission option is enabled.
@@ -184,6 +231,33 @@ Every tool declares a JSON input schema and all four MCP behaviour hints (`readO
 for confirmation before a writing tool runs. All reading tools are `readOnlyHint: true`; `ping_host` is the only
 tool with `openWorldHint: true`, because it talks to hosts outside of ioBroker.
 
+### Large results and files
+MCP clients reject tool results above 1 MiB, and a model cannot pass megabytes of base64 as a tool argument. So:
+
+- **Every result stays below the limit.** Lists (`get_states`, `search_objects`, `list_files`, `list_scripts`,
+  `history_query`) return as many entries as fit and add `truncated`, `total`, `nextOffset` and a `hint`; call
+  again with `offset` set to `nextOffset` for the next part. `get_logs` keeps the newest lines. Any other result
+  that is too large is replaced by a download link, or by an error asking to narrow the request down.
+- **Download links** (`download_url`): a cut list carries a link to all of its entries as JSON, and `read_file`
+  with `download: true` returns a link to the whole file. Clients that can run shell commands (e.g. Claude Code)
+  fetch it with `curl -o <file> "<download_url>"`.
+- **Upload links**: `prepare_upload` returns a link and an `upload_id`. The client uploads the file with
+  `curl -T <file> "<url>"` (`PUT` or `POST`, raw body, up to 100 MB) and passes the `upload_id` to `write_file` or
+  `install_package`. A link can be used once.
+
+The links are `<mcp endpoint>/transfer/<token>`: the random token is the credential, so they work without the
+login of the MCP endpoint, and they expire after 15 minutes. They are built from the address the client used, or
+from *Public URL*. They are not available in-process (ioBroker.admin) and as a web extension with authentication
+enabled in the web adapter, because the web adapter asks for a login first; the tools then say so.
+
+### Prompts
+MCP clients offer these as ready-made commands (e.g. as slash commands):
+
+- `diagnose_adapter` (`instance`) - find out why an instance does not work: status, log, notifications,
+  connectivity and available updates.
+- `room_overview` (`room`) - summary of the devices of a room and anything unusual.
+- `create_automation` (`description`) - turn a description into a script for the javascript adapter.
+
 ### Resources & live updates (SSE)
 
 States and objects are also exposed as MCP **resources** using the canonical ioBroker URI scheme, so clients
@@ -233,6 +307,15 @@ client calls it and its result is verified:
     Placeholder for the next version (at the beginning of the line):
     ### **WORK IN PROGRESS**
 -->
+### 1.5.0 (2026-10-24)
+* (@GermanBluefox) Tool results are kept below the 1 MiB limit of MCP clients: lists are paged with `offset`, other results are replaced by a download link
+* (@GermanBluefox) Added download links (`read_file` with `download: true`, complete lists) and upload links (`prepare_upload`, used by `write_file` and `install_package`) for large data (option `transferLinks`)
+
+### 1.4.0 (2026-10-23)
+* (@GermanBluefox) Added tools to control instances, manage adapters, read/change/run scripts, read and acknowledge notifications, create aliases and send messages to adapters, each behind its own option (off by default)
+* (@GermanBluefox) Added the prompts `diagnose_adapter`, `room_overview` and `create_automation`
+* (@GermanBluefox) Dangerous actions ask the user for a confirmation if the client supports elicitation (option `confirmDangerous`)
+
 ### 1.3.0 (2026-10-23)
 * (@GermanBluefox) Added the `install_package` tool (opt-in `allowPackageInstall`, only for developers): installs an adapter package from npm, GitHub, a URL or a `.tgz` file on a host
 

package/build/inProcessClient.d.ts

@@ -57,11 +57,21 @@ export interface InProcessMcpOptions {
     setStateDestructive?: boolean;
     /** Allow the object/file-changing tools (`create_state`, `set_object`, ...) (default: false). */
     allowObjectChange?: boolean;
+    /** Allow starting/stopping/restarting instances and changing their log level (default: false). */
+    allowInstanceControl?: boolean;
+    /** Allow adding/deleting instances and upgrading adapters from the repository (default: false). */
+    allowAdapterManagement?: boolean;
     /**
      * Allow the `install_package` tool, which installs adapter packages on a host (default: false).
      * Only relevant for adapter developers.
      */
     allowPackageInstall?: boolean;
+    /** Allow creating/changing/deleting/running scripts of the javascript adapter (default: false). */
+    allowScriptChange?: boolean;
+    /** Adapters or instances `send_to` may address, comma separated, `*` for all (default: none, no tool). */
+    sendToAllowlist?: string;
+    /** Ask the user before dangerous actions if the client supports elicitation (default: true). */
+    confirmDangerous?: boolean;
     /** Name reported to the server by the embedded client. */
     clientName?: string;
     /** Version reported to the server by the embedded client. */

package/build/inProcessClient.js

@@ -23,21 +23,14 @@ const index_1 = __importDefault(require("./index"));
  * @returns a facade to list/call tools and to tear the connection down again
  */
 async function createInProcessMcp(options) {
-    const mcp = index_1.default.createEmbedded({
-        adapter: options.adapter,
-        defaultUser: options.defaultUser,
-        language: options.language,
-        allowSetState: options.allowSetState,
-        allowObjectChange: options.allowObjectChange,
-        setStateDestructive: options.setStateDestructive,
-        allowPackageInstall: options.allowPackageInstall,
-    });
+    const { clientName, clientVersion, ...embedOptions } = options;
+    const mcp = index_1.default.createEmbedded(embedOptions);
     const server = mcp.createInProcessServer();
     const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
     await server.connect(serverTransport);
     const client = new index_js_1.Client({
-        name: options.clientName || 'iobroker-inprocess-client',
-        version: options.clientVersion || '1.0.0',
+        name: clientName || 'iobroker-inprocess-client',
+        version: clientVersion || '1.0.0',
     }, { capabilities: {} });
     await client.connect(clientTransport);
     return {

package/build/inProcessClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"inProcessClient.js","sourceRoot":"","sources":["../src/inProcessClient.ts"],"names":[],"mappings":";;;;;AA4GA,gDA0DC;AAtKD;;;;;;;;GAQG;AACH,wEAAmE;AACnE,uEAA0E;AAC1E,oDAAgC;AA2FhC;;;;;GAKG;AACI,KAAK,UAAU,kBAAkB,CAAC,OAA4B;IACjE,MAAM,GAAG,GAAG,eAAS,CAAC,cAAc,CAAC;QACjC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;KACnD,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,GAAG,CAAC,qBAAqB,EAAE,CAAC;IAC3C,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,+BAAiB,CAAC,gBAAgB,EAAE,CAAC;IAChF,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAEtC,MAAM,MAAM,GAAG,IAAI,iBAAM,CACrB;QACI,IAAI,EAAE,OAAO,CAAC,UAAU,IAAI,2BAA2B;QACvD,OAAO,EAAE,OAAO,CAAC,aAAa,IAAI,OAAO;KAC5C,EACD,EAAE,YAAY,EAAE,EAAE,EAAE,CACvB,CAAC;IACF,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAEtC,OAAO;QACH,KAAK,CAAC,SAAS;YACX,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;YACrC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAClC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAG,IAAI,CAAC,WAAuC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;gBAChG,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;aAChC,CAAC,CAAC,CAAC;QACR,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,IAA8B;YACvD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;YACnE,MAAM,MAAM,GAAI,GAAG,CAAC,OAA0C,IAAI,EAAE,CAAC;YACrE,MAAM,IAAI,GAAG,MAAM;iBACd,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;iBACxE,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAc,CAAC;iBAClC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,KAAK;YACP,IAAI,CAAC;gBACD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACL,SAAS;YACb,CAAC;YACD,IAAI,CAAC;gBACD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACL,SAAS;YACb,CAAC;YACD,GAAG,CAAC,MAAM,EAAE,CAAC;QACjB,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"inProcessClient.js","sourceRoot":"","sources":["../src/inProcessClient.ts"],"names":[],"mappings":";;;;;AAsHA,gDAmDC;AAzKD;;;;;;;;GAQG;AACH,wEAAmE;AACnE,uEAA0E;AAC1E,oDAAgC;AAqGhC;;;;;GAKG;AACI,KAAK,UAAU,kBAAkB,CAAC,OAA4B;IACjE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC;IAC/D,MAAM,GAAG,GAAG,eAAS,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAEnD,MAAM,MAAM,GAAG,GAAG,CAAC,qBAAqB,EAAE,CAAC;IAC3C,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,+BAAiB,CAAC,gBAAgB,EAAE,CAAC;IAChF,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAEtC,MAAM,MAAM,GAAG,IAAI,iBAAM,CACrB;QACI,IAAI,EAAE,UAAU,IAAI,2BAA2B;QAC/C,OAAO,EAAE,aAAa,IAAI,OAAO;KACpC,EACD,EAAE,YAAY,EAAE,EAAE,EAAE,CACvB,CAAC;IACF,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAEtC,OAAO;QACH,KAAK,CAAC,SAAS;YACX,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;YACrC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAClC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAG,IAAI,CAAC,WAAuC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;gBAChG,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;aAChC,CAAC,CAAC,CAAC;QACR,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,IAA8B;YACvD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;YACnE,MAAM,MAAM,GAAI,GAAG,CAAC,OAA0C,IAAI,EAAE,CAAC;YACrE,MAAM,IAAI,GAAG,MAAM;iBACd,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;iBACxE,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAc,CAAC;iBAClC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,KAAK;YACP,IAAI,CAAC;gBACD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACL,SAAS;YACb,CAAC;YACD,IAAI,CAAC;gBACD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACL,SAAS;YACb,CAAC;YACD,GAAG,CAAC,MAAM,EAAE,CAAC;QACjB,CAAC;KACJ,CAAC;AACN,CAAC"}

package/build/index.d.ts

@@ -2,6 +2,7 @@ import type { Server as HttpServer } from 'node:http';
 import type { Server as HttpsServer } from 'node:https';
 import { type Express } from 'express';
 import { McpServer as McpSdkServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpPermissions } from './types';
 import { createInProcessMcp } from './inProcessClient';
 export default class McpServer {
     private readonly adapter;
@@ -40,21 +41,27 @@ export default class McpServer {
     private oauth2?;
     /** Installations started by `install_package`, keyed by the `cmdExec` session id. */
     private readonly cmdSessions;
+    /** Path of the MCP endpoint, e.g. `/mcp`. */
+    private readonly 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.
+     */
+    private readonly linksAvailable;
+    /** Why links are not available, for the answer of the tools. */
+    private readonly linksUnavailableReason;
+    /** Active download and upload links, keyed by their token. */
+    private readonly transfers;
+    /** Temporary folder for the files of the links, created on first use. */
+    private transferDir?;
+    private transferTimer?;
     constructor(server: HttpServer | HttpsServer | null, webSettings: {
         secure?: boolean;
         port?: number | string;
         defaultUser?: string;
         auth?: boolean;
         language?: ioBroker.Languages;
-        /** Explicit override for the `set_state`/`set_states` permission (embedded mode). */
-        allowSetState?: boolean;
-        /** Explicit override for the destructive hint of `set_state`/`set_states` (embedded mode). */
-        setStateDestructive?: boolean;
-        /** Explicit override for the object/file-changing tool permission (embedded mode). */
-        allowObjectChange?: boolean;
-        /** Explicit override for the package installation permission (embedded mode). */
-        allowPackageInstall?: boolean;
-    }, adapter: ioBroker.Adapter, instanceSettings: ioBroker.InstanceObject | null, app?: Express);
+    } & Partial<McpPermissions>, adapter: ioBroker.Adapter, instanceSettings: ioBroker.InstanceObject | null, app?: Express);
     /**
      * 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
@@ -71,20 +78,12 @@ export default 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: {
         adapter: ioBroker.Adapter;
         defaultUser?: `system.user.${string}`;
         language?: ioBroker.Languages;
-        allowSetState?: boolean;
-        allowObjectChange?: boolean;
-        setStateDestructive?: boolean;
-        allowPackageInstall?: boolean;
-    }): McpServer;
+    } & Partial<McpPermissions>): McpServer;
     private initRoutes;
     /**
      * Guard for the MCP endpoint when authentication is enabled (standalone mode). By the time this
@@ -190,6 +189,7 @@ export default 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)
      */
     private createServer;
     /** Build the result entry for one state. */
@@ -309,6 +309,106 @@ export default class McpServer {
      * ioBroker.admin installs from a custom URL or a .tgz file, and wait for the result.
      */
     private installPackage;
+    /** Normalize a host name (with or without `system.host.`) and check that the host exists. */
+    private resolveHost;
+    /**
+     * 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)
+     */
+    private runHostCommand;
+    /** Request something from a host (`getNotifications`, ...) and wait for the answer. */
+    private hostRequest;
+    /** Like admin after an installation: touching the instance objects makes the controller restart them. */
+    private restartAdapterInstances;
+    /** Read an instance object by its short id (`hue.0`) or full id (`system.adapter.hue.0`). */
+    private getInstance;
+    /** Start (enable) or stop (disable) an instance. */
+    private setInstanceEnabled;
+    /** Restart a running instance. */
+    private restartInstance;
+    /**
+     * 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).
+     */
+    private setLogLevel;
+    /** Check an adapter name, as the CLI receives it as an argument. */
+    private static checkAdapterName;
+    /** Create an instance of an adapter (installs the adapter from the repository if necessary). */
+    private addInstance;
+    /** Delete an instance with its objects and states (on the host it runs on). */
+    private deleteInstance;
+    /** Upgrade an installed adapter to the repository version (or the given one). */
+    private upgradeAdapter;
+    /** List the installed adapters that have a newer version in the active repository. */
+    private listAdapterUpdates;
+    /**
+     * 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.
+     */
+    private getRepositoryJson;
+    /** Read the current notifications of one or all hosts, one entry per category and instance. */
+    private listNotifications;
+    /** Acknowledge (delete) notifications on a host, optionally only of one scope/category/instance. */
+    private clearNotifications;
+    /**
+     * 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.
+     */
+    private static scriptId;
+    /** Summary of a script object, optionally with its source. */
+    private scriptInfo;
+    /** Read a script object, failing if it is missing or not a script. */
+    private getScriptObject;
+    /** List the scripts of the javascript adapter (without their source). */
+    private listScripts;
+    /**
+     * 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.
+     */
+    private setScript;
+    /** Enable (start) or disable (stop) a script. */
+    private enableScript;
+    /** Delete a script. */
+    private deleteScript;
+    /**
+     * 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`.
+     */
+    private runScript;
+    /** Whether `send_to` may address this instance (by adapter name, instance or `*`). */
+    private isSendToAllowed;
+    /** Send a message to an adapter instance (`sendTo`) and return its answer. */
+    private sendToInstance;
+    /**
+     * Create an alias (`alias.0.*`) that points to another state. Type, role, unit and limits are copied
+     * from the target unless given.
+     */
+    private createAlias;
+    /**
+     * 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).
+     */
+    private createTransfer;
+    /** The public URL of a download or upload link. */
+    private transferUrl;
+    /** Remove a link and its file. */
+    private removeTransfer;
+    /** Remove the expired links. */
+    private cleanupTransfers;
+    /** `GET <mcp>/transfer/<token>`: send the file of a download link. */
+    private handleDownload;
+    /** `PUT`/`POST <mcp>/transfer/<token>`: receive the file of an upload link (raw body, e.g. `curl -T`). */
+    private handleUpload;
+    /** Write the raw body of a request to a file and return its size. */
+    private static receiveBody;
+    /** Get a received upload by its id, failing if it is unknown, expired or still empty. */
+    private getUpload;
     /** Resolve the member ids of a room/function enum matched by id or (localized) name. */
     private getEnumMembers;
     /** Normalize an ioBroker name (string or {en, de, ...}) to a plain string. */