iobroker.mcp 0.1.4 → 0.2.2

package/README.md

@@ -47,9 +47,11 @@ The adapter can be configured through the ioBroker admin interface using JSONCon
   When running as a web extension and no user is set here, the host `web` instance's default user is used.
 
 ### Permissions
-- **Allow setting states**: Allow MCP clients to write state values (the `set_state` tool). Default: **on**.
-- **Allow object/file changes**: Allow MCP clients to create/modify objects and write files (the `set_object`
-  and `write_file` tools). Default: **off**. When off, these tools are not exposed at all.
+- **Allow setting states**: Allow MCP clients to write state values (the `set_state` and `set_states` tools).
+  Default: **on**.
+- **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.
 
 ### SSL/TLS Configuration
 - **Enable HTTPS**: Enable HTTPS/SSL for secure connections
@@ -67,27 +69,37 @@ state (tracked via the `Mcp-Session-Id` header). Point your MCP client at:
 
 ### Available tools
 
-| Tool             | Description                                                                                                                                                     |
-|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `get_states`     | Retrieve the current value of one or multiple states                                                                                                            |
-| `get_object`     | Read a single object by its ID                                                                                                                                  |
-| `search_objects` | Search objects/states by keyword, role or room                                                                                                                  |
-| `list_devices`   | List detected devices grouped by room (uses the ioBroker type-detector to expose functional devices with named controls); optional `language` and `room` filter |
-| `list_instances` | List adapter instances with their status                                                                                                                        |
-| `list_hosts`     | List ioBroker hosts with their status                                                                                                                           |
-| `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)                                                                                                            |
-| `read_file`      | Read a file from an adapter file storage (optional base64)                                                                                                      |
-| `get_logs`       | Retrieve system logs                                                                                                                                            |
-| `write_log`      | Write a message to the ioBroker log                                                                                                                             |
-| `system_info`    | Get system and js-controller information                                                                                                                        |
-| `set_state`      | Set the value of a state (value coerced to the state type) — requires *Allow setting states*                                                                    |
-| `set_object`     | Create/update an object (merges common/native) — requires *Allow object/file changes*                                                                           |
-| `write_file`     | Write a file to an adapter file storage — requires *Allow object/file changes*                                                                                  |
-
-All object/state access runs with the permissions of the configured **Default User**. The write tools
-(`set_state`, `set_object`, `write_file`) are only registered when their respective permission option is enabled.
+| Tool             | Description                                                                                                                                                      |
+|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `get_states`     | Retrieve the current value of one or multiple states; IDs may contain wildcards (e.g. `hue.0.*.brightness`)                                                      |
+| `get_object`     | Read a single object by its ID                                                                                                                                   |
+| `search_objects` | Search objects/states by keyword (matched against ID and name); optional filters for object `type`, `role`, `room` and source `adapter` instance                 |
+| `list_devices`   | List detected devices grouped by room (uses the ioBroker type-detector to expose functional devices with named controls); optional `language` and `room` filter  |
+| `list_instances` | List adapter instances with their status                                                                                                                         |
+| `list_adapters`  | List installed adapters with metadata (version, title, description, keywords)                                                                                    |
+| `list_hosts`     | List ioBroker hosts with their status                                                                                                                            |
+| `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)                                                                                                       |
+| `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 system logs                                                                                                                                             |
+| `write_log`      | Write a message to the ioBroker log                                                                                                                              |
+| `system_info`    | Get system and js-controller information                                                                                                                         |
+| `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*                                               |
+| `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*                                                                                   |
+| `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*                                                                             |
+
+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.
 
 ### Resources & live updates (SSE)
 
@@ -121,6 +133,22 @@ tools rather than as subscribable resources.)
     Placeholder for the next version (at the beginning of the line):
     ### **WORK IN PROGRESS**
 -->
+### 0.2.2 (2026-06-11)
+* (@GermanBluefox) Supported direct import of MCP server
+
+### 0.2.0 (2026-06-11)
+* (@GermanBluefox) Many changes: see the previous changelog entry
+
+### 0.1.5 (2026-06-11)
+* (@GermanBluefox) Added wildcard support to `get_states` (e.g. `hue.0.*.brightness`)
+* (@GermanBluefox) Added `set_states` for writing multiple states in one call (scenes/group actions)
+* (@GermanBluefox) Added `delete_object` and `create_state` tools (gated by *Allow object/file changes*)
+* (@GermanBluefox) Added `create_scene` tool that creates scenes for the ioBroker `scenes` adapter
+* (@GermanBluefox) Added file management tools: `list_files`, `file_exists`, `delete_file`, `rename_file`, `mkdir`
+* (@GermanBluefox) Added `list_adapters` to list installed adapters with metadata
+* (@GermanBluefox) Extended `search_objects` with `type` and `adapter` filters; the keyword now also matches object names
+* (@GermanBluefox) Extended `history_query` with the aggregations `count`, `minmax`, `percentile`, `quantile` and `integral`
+
 ### 0.1.4 (2026-05-28)
 * (@GermanBluefox) Initial development
 

package/build/lib/devices.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Device detection utilities, ported from the ioBroker n8n nodes
+ * (`IoBrokerNodes/DevicesUtils.ts`).
+ *
+ * Uses the ioBroker type detector (https://github.com/ioBroker/ioBroker.type-detector)
+ * to turn raw states/channels/devices into "controls" (functional devices) and groups
+ * them into an AI-friendly structure of rooms -> devices -> named controls.
+ *
+ * All object reads accept an optional `{ user }` so the detection respects the ACLs of
+ * the configured default user (see McpServer).
+ */
+import { type ExternalDetectorState, Types } from '@iobroker/type-detector';
+/** Read options passed through to `getObjectViewAsync` (currently only the ACL user). */
+export interface ReadOptions {
+    user?: `system.user.${string}`;
+}
+export type SmartNameObject = {
+    [lang in ioBroker.Languages]?: string;
+} & {
+    smartType?: string | null;
+    byON?: string | null;
+    toggle?: boolean;
+};
+export type SmartName = null | false | string | SmartNameObject;
+/** Detector state enriched with the concrete object id, smart name and common metadata. */
+export interface IotExternalDetectorState extends ExternalDetectorState {
+    id: string;
+    smartName: SmartName | undefined;
+    common: {
+        min?: number;
+        max?: number;
+        unit?: string;
+        type?: ioBroker.CommonType;
+        states?: {
+            [value: string]: string;
+        };
+        role?: string;
+        name?: ioBroker.StringOrTranslated;
+        icon?: string;
+        color?: string;
+    };
+}
+export interface IotExternalPatternControl {
+    states: IotExternalDetectorState[];
+    type: Types;
+    enumRequired?: boolean;
+    object?: {
+        id: string;
+        type: ioBroker.ObjectType;
+        common: ioBroker.StateCommon | ioBroker.ChannelCommon | ioBroker.DeviceCommon;
+        autoDetected: boolean;
+        toggle?: boolean;
+        smartName?: SmartName;
+    };
+    groupNames: string[];
+    room?: {
+        id: string;
+        common: ioBroker.EnumCommon;
+    };
+    functionality?: {
+        id: string;
+        common: ioBroker.EnumCommon;
+    };
+}
+/**
+ * Checks whether the provided value is a valid smart name.
+ *
+ * @param smartName The value to check
+ * @param lang Configured language
+ * @returns True if a valid smart name, false - otherwise.
+ */
+export declare function isValidSmartName(smartName: SmartName | undefined, lang: ioBroker.Languages): boolean;
+/**
+ * Inspects all objects (states, channels and devices) and tries to identify so-called 'controls'
+ *
+ * To identify the controls, the ioBroker type detector library is used (https://github.com/ioBroker/ioBroker.type-detector).
+ *
+ * @param adapter The adapter instance
+ * @param lang language
+ * @param options read options (ACL user)
+ * @returns An array containing the detected controls
+ */
+export declare function controls(adapter: ioBroker.Adapter, lang: ioBroker.Languages, options?: ReadOptions): Promise<IotExternalPatternControl[]>;
+type RoomName = string;
+type FunctionalityName = string;
+type ControlType = 'power' | 'dimmer' | 'blindPosition' | 'stop' | 'openedClosed' | 'alarm' | 'color' | 'colorRed' | 'colorGreen' | 'colorBlue' | 'colorWhite' | 'colorTemperature' | 'openClose' | 'open' | 'close' | 'fanSpeed' | 'boostMode' | 'swingPosition' | 'saturation' | 'swingOnOff' | 'actualTemperature' | 'humidity' | 'illuminance' | 'level' | 'volume' | 'targetTemperature' | 'lock' | 'valve';
+type ControlInDevice = {
+    stateId: string;
+    controlType: ControlType;
+    ioBrokerValueType: ioBroker.CommonType;
+    writable: boolean;
+    readable: boolean;
+    min?: number;
+    max?: number;
+    unit?: string;
+    states?: {
+        [value: string]: string;
+    };
+    role?: string;
+};
+export interface Device {
+    deviceName: string | ioBroker.StringOrTranslated | undefined;
+    deviceType: Types;
+    friendlyDeviceNames: string[];
+    room?: RoomName;
+    functionality?: FunctionalityName;
+    controls: {
+        [controlType: string]: ControlInDevice;
+    };
+}
+export interface Room {
+    roomName: RoomName;
+    devicesInRoom: Device[];
+}
+export interface Functionality {
+    functionalityName: FunctionalityName;
+    devicesInFunctionality: Device[];
+}
+/**
+ * Build an AI-friendly structure of rooms -> devices -> named controls.
+ *
+ * @param adapter The adapter instance
+ * @param lang language
+ * @param options read options (ACL user)
+ */
+export declare function getAiFriendlyStructure(adapter: ioBroker.Adapter, lang: ioBroker.Languages, options?: ReadOptions): Promise<Room[]>;
+export {};

package/build/lib/iob-uri.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical ioBroker URI helpers, ported from `@iobroker/adapter-react-v5` (`Components/IobUri`).
+ *
+ *   - state:  `iobstate://<id>[/<attr>]`            (attr: val, ts, lc, ack, q, from, ...)
+ *   - object: `iobobject://<id>[/<attr.path>]`      (attr.path: common.enabled, native.x, ...)
+ *   - file:   `iobfile://<adapter>/<dir>/<file>`
+ *   - http:   `http(s)://...`
+ *   - base64: `data:...`
+ */
+export type IobUriType = 'object' | 'state' | 'file' | 'http' | 'base64';
+export interface IobUriParsed {
+    type: IobUriType;
+    address: string;
+    path?: string;
+}
+export declare function iobUriToString(uri: IobUriParsed): string;
+/** Parse an ioBroker URI. */
+export declare function iobUriParse(uri: string): IobUriParsed;
+/** Read a nested attribute from an object by a dotted path (e.g. ["common","enabled"]). */
+export declare function getAttrInObject(obj: Record<string, any> | null | undefined, path: string[] | undefined): any;

package/build/lib/mcp-server.d.ts

@@ -0,0 +1,125 @@
+import { type Express } from 'express';
+import type { Server as HttpServer } from 'node:http';
+import type { Server as HttpsServer } from 'node:https';
+export default class McpServer {
+    private readonly adapter;
+    private readonly app;
+    /** Active sessions keyed by session id. */
+    private readonly sessions;
+    /** Ref-count of adapter-level subscriptions across all sessions, keyed by "<type>:<address>" or "log". */
+    private readonly subscriptionCounts;
+    /** Recent log lines kept for `ioblog://` resource reads (filled while there are log subscribers). */
+    private readonly logBuffer;
+    private config;
+    private readonly namespace;
+    private readonly extension;
+    private readonly routerPrefix;
+    /** The ioBroker user whose permissions every MCP request runs with. */
+    private readonly defaultUser;
+    /** Default language used to localize device/room/function names. */
+    private readonly language;
+    constructor(server: HttpServer | HttpsServer, webSettings: {
+        secure: boolean;
+        port: number | string;
+        defaultUser?: `system.user.${string}`;
+        auth?: boolean;
+        language?: ioBroker.Languages;
+    }, adapter: ioBroker.Adapter, instanceSettings: ioBroker.InstanceObject | null, app: Express);
+    private initRoutes;
+    /**
+     * Called by the ioBroker web adapter to list this extension on its welcome/intro page.
+     * Only relevant when running embedded.
+     */
+    welcomePage(): {
+        link: string;
+        name: string;
+        img: string;
+        color: string;
+        order: number;
+        pro: boolean;
+    };
+    /** Handle client -> server messages (initialize, tools/call, ...). */
+    private handleMcpPost;
+    /** Handle server -> client SSE stream (GET) and session termination (DELETE). */
+    private handleMcpSessionRequest;
+    /**
+     * Forward an ioBroker state change to subscribed sessions.
+     *
+     * Called by our own adapter (standalone) or by the host web adapter (extension mode), which
+     * invokes `stateChange` on every web extension that defines it.
+     */
+    stateChange(id: string, _state: ioBroker.State | null | undefined): void;
+    /**
+     * Forward an ioBroker object change to subscribed sessions. Called by our own adapter
+     * (standalone) or automatically by the host web adapter (extension mode).
+     */
+    objectChange(id: string, _obj: ioBroker.Object | null | undefined): void;
+    /** Push `resources/updated` to every session subscribed to the given state/object id. */
+    private notifySubscribers;
+    /** Receive an ioBroker log line: buffer it and push `resources/updated` to ioblog subscribers. */
+    private onLog;
+    /** Classify a resource URI into its subscription kind, address and ref-count key. */
+    private uriKind;
+    /** Add an adapter-level subscription, subscribing on the adapter only on the first reference. */
+    private refSubscribe;
+    /** Drop an adapter-level subscription, unsubscribing on the adapter when the last reference goes. */
+    private refUnsubscribe;
+    /** Release all subscriptions held by a session (on close). */
+    private cleanupSession;
+    /**
+     * 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)
+     */
+    private createServer;
+    /** Build the result entry for one state. */
+    private static stateEntry;
+    private getStates;
+    /** Write multiple states; failures of single states are reported per item and do not abort the rest. */
+    private setStates;
+    private getLogs;
+    private getSystemInfo;
+    private searchObjects;
+    private listDevices;
+    private historyQuery;
+    private listInstances;
+    /** List installed adapters (system.adapter.<name> objects, no instances). */
+    private listAdapters;
+    private listHosts;
+    /**
+     * Read the rooms/functions enums with localized names and details about each member object
+     * (ported from the ioBroker n8n node's `readIobEnums`).
+     */
+    private readEnums;
+    /** Write a state, coercing the value to the state's declared type (boolean/number/string). */
+    private setState;
+    /** Coerce an arbitrary value to the given ioBroker state type. */
+    private static coerceValue;
+    /** Read a file from an adapter file storage. */
+    private readFile;
+    /** Write a file to an adapter file storage. */
+    private writeFile;
+    /** List a directory in an adapter file storage. */
+    private listFiles;
+    /** Rename/move a file within the same adapter file storage. */
+    private renameFile;
+    /** Create or update an object, merging common/native into an existing object (n8n `setIobObject`). */
+    private setObject;
+    /** Split a file path "<adapter>/<dir>/<file>" into adapter name and file name. */
+    private static parseFilePath;
+    /** Split a directory path "<adapter>[/<dir>]" into adapter name and (possibly empty) directory. */
+    private static parseDirPath;
+    /** Delete an object, optionally with all its children. */
+    private deleteObject;
+    /** Create a new state object; refuses to overwrite an existing object. */
+    private createState;
+    /** Create or update a scene object for the ioBroker "scenes" adapter. */
+    private createScene;
+    /** 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. */
+    private getName;
+    /** Parse an interval like "15m", "1h", "30s" into milliseconds. */
+    private parseInterval;
+    unload(): void;
+}