iobroker.mcp 0.1.4 → 0.2.2

package/{dist → build}/lib/mcp-server.js

@@ -21,6 +21,11 @@ const AGG_MAP = {
     max: 'max',
     avg: 'average',
     sum: 'total',
+    count: 'count',
+    minmax: 'minmax',
+    percentile: 'percentile',
+    quantile: 'quantile',
+    integral: 'integral',
 };
 const WEB_EXTENSION_PREFIX = 'mcp/';
 /** Languages offered for localized names. */
@@ -59,7 +64,9 @@ class McpServer {
     constructor(server, webSettings, adapter, instanceSettings, app) {
         this.app = app;
         this.adapter = adapter;
-        this.config = instanceSettings ? instanceSettings.native : adapter.config;
+        this.config = instanceSettings
+            ? instanceSettings.native
+            : adapter.config;
         this.namespace = instanceSettings
             ? instanceSettings._id.substring('system.adapter.'.length)
             : this.adapter.namespace;
@@ -328,8 +335,9 @@ class McpServer {
             return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: message }) }], isError: true };
         };
         server.registerTool('get_states', {
-            description: 'Retrieve the current value of one or multiple states',
-            inputSchema: { ids: zod_1.z.array(zod_1.z.string()).describe('Array of state IDs') },
+            description: 'Retrieve the current value of one or multiple states. IDs may contain wildcards, ' +
+                'e.g. "hue.0.*.brightness" expands to all matching states.',
+            inputSchema: { ids: zod_1.z.array(zod_1.z.string()).describe('Array of state IDs (wildcards "*" allowed)') },
         }, async ({ ids }) => {
             try {
                 return ok({ ok: true, data: { states: await this.getStates(ids) } });
@@ -357,6 +365,26 @@ class McpServer {
                     return fail(e);
                 }
             });
+            server.registerTool('set_states', {
+                description: 'Set multiple states in one call (e.g. for scenes or group actions like "all lights off"). ' +
+                    'Each value is coerced to its state type. Failures of single states do not abort the rest.',
+                inputSchema: {
+                    states: zod_1.z
+                        .array(zod_1.z.object({
+                        id: zod_1.z.string().describe('State ID'),
+                        value: zod_1.z.any().describe('New value (type depends on the state)'),
+                        ack: zod_1.z.boolean().optional().describe('Acknowledge flag (default false)'),
+                    }))
+                        .describe('Array of state/value pairs to write'),
+                },
+            }, async ({ states }) => {
+                try {
+                    return ok({ ok: true, data: { results: await this.setStates(states) } });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
         }
         server.registerTool('get_logs', {
             description: 'Retrieve system logs',
@@ -383,11 +411,17 @@ class McpServer {
             }
         });
         server.registerTool('search_objects', {
-            description: 'Search objects and states by keywords',
+            description: 'Search objects and states by keyword (matched against ID and name) with optional ' +
+                'filters for object type, role, room and source adapter instance',
             inputSchema: {
-                query: zod_1.z.string().describe('Keyword to search for'),
+                query: zod_1.z.string().describe('Keyword to search for in object IDs and names'),
+                type: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Filter by object type, e.g. state, channel, device, enum, script, instance'),
                 role: zod_1.z.string().optional(),
                 room: zod_1.z.string().optional(),
+                adapter: zod_1.z.string().optional().describe('Filter by source adapter instance, e.g. "hue.0"'),
                 limit: zod_1.z.number().int().default(50),
             },
         }, async (args) => {
@@ -422,7 +456,32 @@ class McpServer {
                 id: zod_1.z.string(),
                 from: zod_1.z.string().optional().describe('Start time (ISO8601)'),
                 to: zod_1.z.string().optional().describe('End time (ISO8601)'),
-                agg: zod_1.z.enum(['raw', 'min', 'max', 'avg', 'sum']).default('raw'),
+                agg: zod_1.z
+                    .enum([
+                    'raw',
+                    'min',
+                    'max',
+                    'avg',
+                    'sum',
+                    'count',
+                    'minmax',
+                    'percentile',
+                    'quantile',
+                    'integral',
+                ])
+                    .default('raw'),
+                percentile: zod_1.z
+                    .number()
+                    .min(0)
+                    .max(100)
+                    .optional()
+                    .describe('Percentile (0-100), only used with agg=percentile'),
+                quantile: zod_1.z
+                    .number()
+                    .min(0)
+                    .max(1)
+                    .optional()
+                    .describe('Quantile (0-1), only used with agg=quantile'),
                 interval: zod_1.z.string().optional().describe('Aggregation interval, e.g. 15m, 1h'),
                 limit: zod_1.z.number().int().default(1000),
             },
@@ -450,6 +509,23 @@ class McpServer {
                 return fail(e);
             }
         });
+        server.registerTool('list_adapters', {
+            description: 'List all installed adapters with metadata (version, title, description, keywords). ' +
+                'Unlike list_instances this lists what is installed, not what is running.',
+            inputSchema: {
+                language: zod_1.z
+                    .enum(LANGUAGES)
+                    .optional()
+                    .describe('Language for title/description (defaults to the adapter language)'),
+            },
+        }, async ({ language }) => {
+            try {
+                return ok({ ok: true, data: { adapters: await this.listAdapters(language) } });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
         const enumInput = {
             language: zod_1.z.enum(LANGUAGES).optional().describe('Language for names (defaults to the adapter language)'),
             withIcons: zod_1.z.boolean().optional().describe('Include the icons of the enum and its members'),
@@ -502,6 +578,32 @@ class McpServer {
                 return fail(e);
             }
         });
+        server.registerTool('list_files', {
+            description: 'List a directory in an adapter file storage, e.g. "vis-2.0/main" or "0_userdata.0"',
+            inputSchema: { path: zod_1.z.string().describe('Path as "<adapter>[/<dir>]"') },
+        }, async ({ path }) => {
+            try {
+                return ok({ ok: true, data: { path, files: await this.listFiles(path) } });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
+        server.registerTool('file_exists', {
+            description: 'Check whether a file exists in an adapter file storage',
+            inputSchema: { path: zod_1.z.string().describe('Path as "<adapter>/<dir>/<file>"') },
+        }, async ({ path }) => {
+            try {
+                const { adapterName, fileName } = McpServer.parseFilePath(path);
+                const exists = await this.adapter.fileExistsAsync(adapterName, fileName, {
+                    user: this.defaultUser,
+                });
+                return ok({ ok: true, data: { path, exists: !!exists } });
+            }
+            catch (e) {
+                return fail(e);
+            }
+        });
         // Always-on log writing (does not change states or objects).
         server.registerTool('write_log', {
             description: 'Write a message to the ioBroker log',
@@ -538,6 +640,73 @@ class McpServer {
                     return fail(e);
                 }
             });
+            server.registerTool('delete_object', {
+                description: 'Delete an ioBroker object (and optionally all its children). ' +
+                    'Be careful: deleting objects that were not created by the user can break adapters.',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Object ID'),
+                    recursive: zod_1.z.boolean().optional().describe('Also delete all child objects'),
+                },
+            }, async ({ id, recursive }) => {
+                try {
+                    await this.deleteObject(id, recursive);
+                    return ok({ ok: true, data: { id, deleted: true } });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('create_state', {
+                description: 'Create a new state object (e.g. under "0_userdata.0."). Fails if the object already ' +
+                    'exists - use set_object to modify existing objects.',
+                inputSchema: {
+                    id: zod_1.z.string().describe('Full state ID, e.g. "0_userdata.0.myState"'),
+                    name: zod_1.z.string().optional().describe('Display name (defaults to the last ID segment)'),
+                    type: zod_1.z
+                        .enum(['boolean', 'number', 'string', 'array', 'object', 'mixed'])
+                        .default('mixed')
+                        .describe('Value type of the state'),
+                    role: zod_1.z.string().default('state').describe('Role, e.g. switch.light, value.temperature'),
+                    read: zod_1.z.boolean().default(true),
+                    write: zod_1.z.boolean().default(true),
+                    unit: zod_1.z.string().optional(),
+                    min: zod_1.z.number().optional(),
+                    max: zod_1.z.number().optional(),
+                    step: zod_1.z.number().optional(),
+                    def: zod_1.z.any().optional().describe('Initial value (written with ack=true)'),
+                    desc: zod_1.z.string().optional().describe('Description'),
+                },
+            }, async (args) => {
+                try {
+                    return ok({ ok: true, data: await this.createState(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('create_scene', {
+                description: 'Create or update a scene for the ioBroker "scenes" adapter: a named collection of ' +
+                    'state/value pairs applied together (e.g. "movie night" dims lights and closes blinds). ' +
+                    'Activate the scene by setting its state to true. Requires an installed scene instance.',
+                inputSchema: {
+                    name: zod_1.z.string().describe('Scene name, becomes part of the ID (e.g. "movie_night")'),
+                    members: zod_1.z
+                        .array(zod_1.z.object({
+                        id: zod_1.z.string().describe('State ID to set'),
+                        value: zod_1.z.any().describe('Value applied when the scene is activated'),
+                    }))
+                        .describe('State/value pairs that define the scene'),
+                    instance: zod_1.z.string().optional().describe('Scene adapter instance (default "scene.0")'),
+                    description: zod_1.z.string().optional(),
+                },
+            }, async (args) => {
+                try {
+                    return ok({ ok: true, data: await this.createScene(args) });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
             server.registerTool('write_file', {
                 description: 'Write a file to an adapter file storage, e.g. "vis-2.0/main/vis-views.json"',
                 inputSchema: {
@@ -554,6 +723,51 @@ class McpServer {
                     return fail(e);
                 }
             });
+            server.registerTool('delete_file', {
+                description: 'Delete a file from an adapter file storage',
+                inputSchema: { path: zod_1.z.string().describe('Path as "<adapter>/<dir>/<file>"') },
+            }, async ({ path }) => {
+                try {
+                    const { adapterName, fileName } = McpServer.parseFilePath(path);
+                    await this.adapter.delFileAsync(adapterName, fileName, { user: this.defaultUser });
+                    return ok({ ok: true, data: { path, deleted: true } });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('rename_file', {
+                description: 'Rename or move a file/directory within the same adapter file storage, ' +
+                    'e.g. "vis-2.0/main/a.json" -> "vis-2.0/backup/a.json"',
+                inputSchema: {
+                    path: zod_1.z.string().describe('Current path as "<adapter>/<dir>/<file>"'),
+                    new_path: zod_1.z.string().describe('New path as "<adapter>/<dir>/<file>" (same adapter)'),
+                },
+            }, async ({ path, new_path }) => {
+                try {
+                    await this.renameFile(path, new_path);
+                    return ok({ ok: true, data: { path: new_path } });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
+            server.registerTool('mkdir', {
+                description: 'Create a directory in an adapter file storage, e.g. "0_userdata.0/my-folder"',
+                inputSchema: { path: zod_1.z.string().describe('Path as "<adapter>/<dir>"') },
+            }, async ({ path }) => {
+                try {
+                    const { adapterName, dirName } = McpServer.parseDirPath(path);
+                    if (!dirName) {
+                        throw new Error('Path must contain a directory after the adapter, e.g. "0_userdata.0/my-folder"');
+                    }
+                    await this.adapter.mkdirAsync(adapterName, dirName, { user: this.defaultUser });
+                    return ok({ ok: true, data: { path } });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            });
         }
         // --- Resources: expose states and objects via the canonical ioBroker URI scheme ---
         // States as `iobstate://<id>`, objects as `iobobject://<id>`. On change the server pushes a
@@ -619,20 +833,31 @@ class McpServer {
     // ---------------------------------------------------------------------
     // Tool implementations (return plain data; the wrappers serialize them)
     // ---------------------------------------------------------------------
+    /** Build the result entry for one state. */
+    static stateEntry(id, state) {
+        if (!state) {
+            return { id, value: null, ack: false, ts: Date.now() };
+        }
+        const entry = { id, value: state.val, ack: state.ack, ts: state.ts };
+        if (state.lc !== state.ts) {
+            entry.lc = state.lc;
+        }
+        return entry;
+    }
     async getStates(ids) {
         const states = [];
         for (const id of ids) {
             try {
-                const state = await this.adapter.getForeignStateAsync(id, { user: this.defaultUser });
-                if (state) {
-                    const entry = { id, value: state.val, ack: state.ack, ts: state.ts };
-                    if (state.lc !== state.ts) {
-                        entry.lc = state.lc;
+                if (id.includes('*')) {
+                    // Wildcard pattern: expand to all matching states.
+                    const matches = await this.adapter.getForeignStatesAsync(id, { user: this.defaultUser });
+                    for (const matchId of Object.keys(matches || {})) {
+                        states.push(McpServer.stateEntry(matchId, matches[matchId]));
                     }
-                    states.push(entry);
                 }
                 else {
-                    states.push({ id, value: null, ack: false, ts: Date.now() });
+                    const state = await this.adapter.getForeignStateAsync(id, { user: this.defaultUser });
+                    states.push(McpServer.stateEntry(id, state));
                 }
             }
             catch (e) {
@@ -647,6 +872,20 @@ class McpServer {
         }
         return states;
     }
+    /** Write multiple states; failures of single states are reported per item and do not abort the rest. */
+    async setStates(items) {
+        const results = [];
+        for (const item of items) {
+            try {
+                const written = await this.setState(item.id, item.value, item.ack ?? false);
+                results.push({ id: item.id, value: written });
+            }
+            catch (e) {
+                results.push({ id: item.id, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return results;
+    }
     getLogs(params) {
         return new Promise((resolve, reject) => {
             const message = { data: { size: params.limit || 200 } };
@@ -697,17 +936,22 @@ class McpServer {
         };
     }
     async searchObjects(params) {
-        const { query = '', role, room, limit = 100 } = params;
+        const { query = '', type, role, room, adapter, limit = 100 } = params;
         const result = await this.adapter.getObjectListAsync({
             startkey: '',
             endkey: '\u9999',
         }, { sorted: true, user: this.defaultUser });
         const allObjects = result.rows;
         const roomMembers = room ? await this.getEnumMembers('enum.rooms.', room) : null;
+        const needle = query.toLowerCase();
         const results = [];
         for (const obj of allObjects) {
             const o = obj.value;
-            if (query && !obj.value._id.toLowerCase().includes(query.toLowerCase())) {
+            const name = this.getName(o?.common?.name);
+            if (needle && !obj.value._id.toLowerCase().includes(needle) && !name.toLowerCase().includes(needle)) {
+                continue;
+            }
+            if (type && o?.type !== type) {
                 continue;
             }
             if (role && o?.common?.role !== role) {
@@ -716,12 +960,16 @@ class McpServer {
             if (roomMembers && !roomMembers.includes(obj.value._id)) {
                 continue;
             }
+            const sourceAdapter = obj.value._id.match(/^([^.]+\.\d+)/)?.[1] || '';
+            if (adapter && sourceAdapter !== adapter) {
+                continue;
+            }
             results.push({
                 id: obj.value._id,
                 type: o?.type || 'state',
                 role: o?.common?.role || '',
-                name: this.getName(o?.common?.name),
-                adapter: obj.value._id.match(/^([^.]+\.\d+)/)?.[1] || '',
+                name,
+                adapter: sourceAdapter,
             });
             if (results.length >= limit) {
                 break;
@@ -750,6 +998,12 @@ class McpServer {
         if (params.to) {
             options.end = new Date(params.to).getTime();
         }
+        if (params.percentile !== undefined) {
+            options.percentile = params.percentile;
+        }
+        if (params.quantile !== undefined) {
+            options.quantile = params.quantile;
+        }
         const step = params.interval ? this.parseInterval(params.interval) : undefined;
         if (step) {
             options.step = step;
@@ -781,6 +1035,22 @@ class McpServer {
         }
         return result;
     }
+    /** List installed adapters (system.adapter.<name> objects, no instances). */
+    async listAdapters(language) {
+        const lang = language || this.language;
+        const view = await this.adapter.getObjectViewAsync('system', 'adapter', { startkey: 'system.adapter.', endkey: 'system.adapter.香' }, { user: this.defaultUser });
+        return view.rows.map(row => {
+            const common = (row.value?.common || {});
+            return {
+                name: common.name || row.id.replace('system.adapter.', ''),
+                version: common.version || '',
+                title: getText(common.titleLang || common.title, lang),
+                description: getText(common.desc, lang),
+                keywords: common.keywords || [],
+                mode: common.mode || '',
+            };
+        });
+    }
     async listHosts() {
         const objs = await this.adapter.getForeignObjectsAsync('system.host.*', 'host', { user: this.defaultUser });
         const result = [];
@@ -918,6 +1188,26 @@ class McpServer {
         const data = base64 ? Buffer.from(content, 'base64') : content;
         await this.adapter.writeFileAsync(adapterName, fileName, data, { user: this.defaultUser });
     }
+    /** List a directory in an adapter file storage. */
+    async listFiles(path) {
+        const { adapterName, dirName } = McpServer.parseDirPath(path);
+        const entries = await this.adapter.readDirAsync(adapterName, dirName, { user: this.defaultUser });
+        return (entries || []).map(entry => ({
+            file: entry.file,
+            isDir: !!entry.isDir,
+            size: entry.stats?.size,
+            modified: entry.modifiedAt,
+        }));
+    }
+    /** Rename/move a file within the same adapter file storage. */
+    async renameFile(path, newPath) {
+        const from = McpServer.parseFilePath(path);
+        const to = McpServer.parseFilePath(newPath);
+        if (from.adapterName !== to.adapterName) {
+            throw new Error('Renaming across adapter storages is not supported; both paths must share the adapter');
+        }
+        await this.adapter.renameAsync(from.adapterName, from.fileName, to.fileName, { user: this.defaultUser });
+    }
     /** Create or update an object, merging common/native into an existing object (n8n `setIobObject`). */
     async setObject(id, obj) {
         let existing = await this.adapter.getForeignObjectAsync(id, { user: this.defaultUser });
@@ -946,6 +1236,99 @@ class McpServer {
         }
         return { adapterName, fileName };
     }
+    /** Split a directory path "<adapter>[/<dir>]" into adapter name and (possibly empty) directory. */
+    static parseDirPath(path) {
+        const [adapterName, ...rest] = path.replace(/^\//, '').replace(/\/$/, '').split('/');
+        if (!adapterName) {
+            throw new Error('Path must start with an adapter name, e.g. "vis-2.0/main" or "0_userdata.0"');
+        }
+        return { adapterName, dirName: rest.join('/') };
+    }
+    /** Delete an object, optionally with all its children. */
+    async deleteObject(id, recursive) {
+        const existing = await this.adapter.getForeignObjectAsync(id, { user: this.defaultUser });
+        if (!existing) {
+            throw new Error(`Object "${id}" does not exist`);
+        }
+        await this.adapter.delForeignObjectAsync(id, { user: this.defaultUser, recursive: !!recursive });
+    }
+    /** Create a new state object; refuses to overwrite an existing object. */
+    async createState(params) {
+        const existing = await this.adapter.getForeignObjectAsync(params.id, { user: this.defaultUser });
+        if (existing) {
+            throw new Error(`Object "${params.id}" already exists - use set_object to modify it`);
+        }
+        const common = {
+            name: params.name || params.id.split('.').pop() || params.id,
+            type: params.type || 'mixed',
+            role: params.role || 'state',
+            read: params.read !== false,
+            write: params.write !== false,
+        };
+        if (params.unit !== undefined) {
+            common.unit = params.unit;
+        }
+        if (params.min !== undefined) {
+            common.min = params.min;
+        }
+        if (params.max !== undefined) {
+            common.max = params.max;
+        }
+        if (params.step !== undefined) {
+            common.step = params.step;
+        }
+        if (params.desc !== undefined) {
+            common.desc = params.desc;
+        }
+        await this.adapter.setForeignObjectAsync(params.id, { type: 'state', common, native: {} }, { user: this.defaultUser });
+        if (params.def !== undefined) {
+            const coerced = McpServer.coerceValue(params.def, common.type);
+            await this.adapter.setForeignStateAsync(params.id, coerced, true, { user: this.defaultUser });
+        }
+        return { id: params.id };
+    }
+    /** Create or update a scene object for the ioBroker "scenes" adapter. */
+    async createScene(params) {
+        const instance = params.instance || 'scene.0';
+        const instanceObj = await this.adapter.getForeignObjectAsync(`system.adapter.${instance}`, {
+            user: this.defaultUser,
+        });
+        if (!instanceObj) {
+            throw new Error(`Scene adapter instance "${instance}" is not installed. Install the ioBroker "scenes" adapter first.`);
+        }
+        // Scene IDs may not contain the characters that are forbidden in ioBroker IDs.
+        const sceneName = params.name.replace(/[\s.*?"'[\]]/g, '_');
+        const id = `${instance}.${sceneName}`;
+        const sceneObj = {
+            type: 'state',
+            common: {
+                name: params.name,
+                type: 'boolean',
+                role: 'scene.state',
+                desc: params.description || '',
+                read: true,
+                write: true,
+                def: false,
+                engine: `system.adapter.${instance}`,
+                enabled: true,
+            },
+            native: {
+                onTrue: { trigger: {}, cron: null, astro: null },
+                onFalse: { enabled: false, trigger: {}, cron: null, astro: null },
+                members: params.members.map(member => ({
+                    id: member.id,
+                    setIfTrue: member.value,
+                    setIfFalse: null,
+                    stopAllDelays: true,
+                    delay: 0,
+                    disabled: false,
+                })),
+                burstInterval: 0,
+            },
+        };
+        await this.adapter.setForeignObjectAsync(id, sceneObj, { user: this.defaultUser });
+        return { id, members: params.members.length };
+    }
     // --- helpers ---
     /** Resolve the member ids of a room/function enum matched by id or (localized) name. */
     async getEnumMembers(prefix, nameOrId) {