@thinger-io/cli-core 0.4.2 → 0.5.1

package/lib/mcp/types/bucket-data.js

@@ -0,0 +1,151 @@
+// @ts-check
+import api from '../../api.js';
+import { TIMEOUTS } from '../../constants.js';
+import { getBucketData } from '../../bucket.js';
+import { apiError, inputError } from '../../errors.js';
+import { v1 } from '../../paths.js';
+
+/**
+ * The time series of a bucket, as a type of the resource tools: `list`
+ * reads it with the server's own query (not paged by the tool), `create`
+ * writes samples.
+ *
+ * @type {import('../tools-resource.js').LocalType}
+ */
+export const bucketData = {
+    description: 'The time series of a bucket: list reads it, create writes samples.',
+    parent: 'bucket',
+    paged: false,
+    ops: { list: ['Bucket_ReadData', 'Device_ReadBucketData'], create: 'Bucket_WriteData' },
+    filter: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            device: {
+                type: 'string',
+                description:
+                    'Device id, to read only its records: the bucket needs the `device` tag (product buckets have it).',
+            },
+            items: {
+                type: 'number',
+                description: 'Samples to return (default 10, at most 1000; `count` sets it too).',
+            },
+            minutes: { type: 'number', description: 'Last N minutes (instead of min_ts/max_ts).' },
+            min_ts: { type: 'number', description: 'From (unix ms).' },
+            max_ts: { type: 'number', description: 'To (unix ms, 0 = now).' },
+            sort: { type: 'string', enum: ['desc', 'asc'], description: 'By time (default desc).' },
+            agg: { type: 'string', description: 'Aggregation window: "5m", "1h", "1d"…' },
+            agg_type: {
+                type: 'string',
+                enum: [
+                    'mean',
+                    'max',
+                    'min',
+                    'sum',
+                    'count',
+                    'first',
+                    'last',
+                    'mode',
+                    'median',
+                    'spread',
+                    'stddev',
+                ],
+                description: 'Reducer of each aggregation window.',
+            },
+            tz: {
+                type: 'string',
+                description:
+                    'IANA time zone for the aggregation windows, e.g. "Europe/Madrid": "1d" then cuts at local midnight (default UTC).',
+            },
+            fields: {
+                type: ['string', 'array'],
+                items: { type: 'string' },
+                description:
+                    'Fields to return: comma-separated or an array. Without fields, an aggregation covers numeric fields only (those of the latest record in the range); name string fields explicitly to read them with last, first, mode or count.',
+            },
+            group_by: { type: 'string', description: 'Group key, e.g. "device".' },
+        },
+    },
+    schema: {
+        type: ['object', 'array'],
+        description:
+            'One sample ({"temperature": 21.5}), stored now or at its `ts` (unix ms), or an array of samples each with its numeric `ts` (MongoDB and InfluxDB buckets).',
+    },
+    notes: 'Without filter.device a list reads the whole bucket: a bucket declared in a product profile holds every device of the product interleaved, and filter {"group_by": "device"} gives one row per device when samples carry that tag. With filter.device, the series the bucket keeps for that device. Writes need a bucket whose data source accepts API writes; servers limit how often a bucket can be written (429 when exceeded): for long histories, import a CSV ({op:bucket.import}).',
+    examples: [
+        {
+            tool: 'resource_list',
+            arguments: {
+                type: 'bucket_data',
+                ids: { bucket: 'temps' },
+                filter: {
+                    min_ts: 1793314800000,
+                    max_ts: 1793401199999,
+                    agg: '1h',
+                    agg_type: 'mean',
+                    tz: 'Europe/Madrid',
+                    fields: ['temperature'],
+                    items: 1000,
+                    sort: 'asc',
+                },
+            },
+            does: "Hourly mean of temperature over one local day: min_ts and max_ts are that day's start and end in Europe/Madrid, as unix ms.",
+        },
+        {
+            tool: 'resource_list',
+            arguments: {
+                type: 'bucket_data',
+                ids: { bucket: 'temps' },
+                filter: { device: 'boiler', items: 10 },
+            },
+            does: 'The last 10 samples of one device in a product bucket.',
+        },
+        {
+            tool: 'resource_create',
+            arguments: {
+                type: 'bucket_data',
+                ids: { bucket: 'temps' },
+                body: [
+                    { ts: 1793314800000, temperature: 21.5 },
+                    { ts: 1793318400000, temperature: 22 },
+                ],
+            },
+            does: 'Write two samples, each at its own time.',
+        },
+    ],
+    list(ctx) {
+        const filter = ctx.filter || {};
+        return getBucketData({
+            bucket: String(ctx.parent),
+            ...filter,
+            items: filter.items ?? ctx.count ?? 10,
+            sort: filter.sort ?? 'desc',
+            fields: Array.isArray(filter.fields) ? filter.fields.join(',') : filter.fields,
+            user: ctx.user,
+        });
+    },
+    async create(body, ctx) {
+        if (!body || typeof body !== 'object') {
+            throw inputError('body must be a JSON object (one sample) or an array of them');
+        }
+        // One sample's ts goes in the query, where the server reads it.
+        let data = body;
+        let params;
+        if (!Array.isArray(body) && body.ts !== undefined) {
+            const { ts, ...rest } = body;
+            data = rest;
+            params = { ts };
+        }
+        const samples = Array.isArray(body) ? body.length : 1;
+        try {
+            await api.post(
+                `${v1(ctx.user)}/buckets/${encodeURIComponent(String(ctx.parent))}/data`,
+                data,
+                { params, timeout: TIMEOUTS.API_LONG_MS },
+            );
+        } catch (e) {
+            throw apiError(e, { notFound: `Bucket not found: ${ctx.parent}` });
+        }
+        return { bucket: ctx.parent, samples };
+    },
+};

package/lib/mcp/{tools-dashboards.js → types/dashboard-apps.js}

@@ -5,15 +5,24 @@ import {
     collectFiles,
     destinationContext,
     manifestName,
+    defaultStorage,
+    listFiles,
     publishApp,
     publishSummary,
-} from '../dashboard.js';
-import { devLink } from '../dashboard-dev.js';
-import { DEFAULT_TEMPLATE, initApp } from '../dashboard-init.js';
-import { inputError } from '../errors.js';
-import { toolName } from './naming.js';
+} from '../../dashboard.js';
+import { devLink } from '../../dashboard-dev.js';
+import { DEFAULT_TEMPLATE, initApp } from '../../dashboard-init.js';
+import { inputError } from '../../errors.js';
+import { opRef } from '../naming.js';
+
+/**
+ * Dashboard apps on the dashboard SDK: actions of the catalog type
+ * dashboard that run on this machine (start a project, link its dev
+ * server to the server) or upload its build (publish).
+ */
 
 async function toolInit(args) {
+    args = args ?? {};
     if (args.to) checkDestination(args.to);
     const r = await initApp({
         dir: args.dir,
@@ -30,7 +39,7 @@ async function toolInit(args) {
                 type: 'text',
                 text: [
                     `Created ${r.dir}: ${r.template} app on @thinger-io/dashboard-sdk ${r.dependency}, with ${manifestName()} (publishes ${r.build} to storage ${r.storage}${args.to ? '' : '; add destinations under dashboard.to'}) and AGENTS.md (how to develop it and the rules of the console's frame: read it).`,
-                    `Next: ${r.installed ? '' : 'npm install, then '}${r.devCommand} in the background (it serves ${r.devUrl}), ${toolName('dashboard_dev')} with url ${r.devUrl}${Object.keys(r.context).length ? '' : ' and a context'} and dir ${r.dir}, open the link with browser tools; when it works, npm run build and ${toolName('dashboard_publish')} with dir ${r.dir}/${r.build}.`,
+                    `Next: ${r.installed ? '' : 'npm install, then '}${r.devCommand} in the background (it serves ${r.devUrl}), ${opRef('dashboard', 'dev')} with url ${r.devUrl}${Object.keys(r.context).length ? '' : ' and a context'} and dir ${r.dir}, open the link with browser tools; when it works, npm run build and ${opRef('dashboard', 'publish')} with dir ${r.dir}/${r.build}.`,
                 ].join('\n'),
             },
         ],
@@ -38,7 +47,8 @@ async function toolInit(args) {
     };
 }
 
-async function toolDev(args) {
+async function toolDev(args, ctx) {
+    args = args ?? {};
     if (!args.url) throw inputError("pass url: the app's dev server, e.g. http://localhost:4200/");
     if (args.to && args.context) throw inputError('pass to or context, not both');
     if (args.to) checkDestination(args.to);
@@ -47,11 +57,11 @@ async function toolDev(args) {
         context: args.to ? destinationContext(args.to) : args.context,
         route: args.route ?? args.to?.route,
         hours: args.hours,
-        user: args.user,
+        user: ctx.user,
         dir: args.dir || process.cwd(),
         allowRemote: args.allow_remote === true,
     });
-    const ctx = Object.entries(dev.context).map(([k, v]) => `${k} ${v}`);
+    const shown = Object.entries(dev.context).map(([k, v]) => `${k} ${v}`);
     const until = new Date(dev.expire).toISOString().slice(0, 16).replace('T', ' ');
     return {
         content: [
@@ -59,10 +69,11 @@ async function toolDev(args) {
                 type: 'text',
                 text: [
                     `Open this link in a browser: ${dev.link}`,
-                    `It opens ${dev.app} as a standalone page against ${dev.server} as ${dev.user}${ctx.length ? `, context ${ctx.join(', ')}` : ''}, with a temporary token (${dev.token}, full access, until ${until} UTC; a new link replaces it). Calls reach the real server: writes are real.`,
+                    `It opens ${dev.app} as a standalone page against ${dev.server} as ${dev.user}${shown.length ? `, context ${shown.join(', ')}` : ''}
+, with a temporary token (${dev.token}, full access, until ${until} UTC; a new link replaces it). Calls reach the real server: writes are real.`,
                     ...dev.notes.map((n) => `Check: ${n}`),
                     "The app's dev server reloads it on every change; its errors are in the browser console. Unlike in the console's sandboxed iframe, localStorage, cookies and a <base> tag work here, so do not rely on them.",
-                    `When it works, build it and publish the build once with ${toolName('dashboard_publish')}.`,
+                    `When it works, build it and publish the build once with ${opRef('dashboard', 'publish')}.`,
                 ].join('\n'),
             },
         ],
@@ -70,7 +81,8 @@ async function toolDev(args) {
     };
 }
 
-async function toolPublish(args) {
+async function toolPublish(args, ctx) {
+    args = args ?? {};
     if (args.dir && args.files) throw inputError('pass dir or files, not both');
     if (args.files) {
         if (typeof args.files !== 'object' || Array.isArray(args.files)) {
@@ -80,15 +92,31 @@ async function toolPublish(args) {
             if (typeof content !== 'string') throw inputError(`files["${file}"] must be a string`);
         }
     }
+    const files = args.dir ? collectFiles(args.dir) : args.files;
+    // Pruning deletes files of the storage: say which before doing it.
+    const to = Array.isArray(args.to) ? args.to : [];
+    const storage =
+        args.storage ||
+        (to.length === 1 && (to[0].dashboard || (to[0].type && to[0].id))
+            ? defaultStorage(to[0].dashboard, to[0].dashboard ? undefined : to[0])
+            : undefined);
+    if (args.prune && files && storage && !ctx.confirmed) {
+        const gone = (await listFiles(storage, ctx.user)).filter((f) => !(f in files));
+        const shown =
+            gone.slice(0, 50).join(', ') + (gone.length > 50 ? ` (+${gone.length - 50})` : '');
+        return ctx.plan(
+            `It would upload ${Object.keys(files).length} file(s) to storage ${storage} and delete the ${gone.length} file(s) of it that are not in this upload${gone.length ? `: ${shown}` : ''}.`,
+        );
+    }
     const result = await publishApp({
         storage: args.storage,
-        files: args.dir ? collectFiles(args.dir) : args.files,
+        files,
         prune: args.prune,
         to: args.to,
         preview: args.preview,
         point: args.point,
         bump: args.bump,
-        user: args.user,
+        user: ctx.user,
         dir: args.dir,
     });
     return {
@@ -97,12 +125,15 @@ async function toolPublish(args) {
     };
 }
 
-export const tools = [
-    {
-        name: 'dashboard_init',
-        description: `Create a dashboard app: a TypeScript project on @thinger-io/dashboard-sdk from one of the templates the SDK package ships (react by default, angular…), with its manifest for {tool:dashboard_dev} and {tool:dashboard_publish} and an AGENTS.md with the rules of the console's frame. Start every new dashboard app here instead of writing one from scratch.`,
-        inputSchema: {
+/** @type {Record<string, import('../tools-resource.js').LocalAction>} */
+export const dashboardActions = {
+    init: {
+        on: 'collection',
+        local: true,
+        description: `Create a dashboard app: a TypeScript project on @thinger-io/dashboard-sdk from one of the templates the SDK package ships (react by default, angular…), with its manifest for its dev and publish actions and an AGENTS.md with the rules of the console's frame. Start every new dashboard app here instead of writing one from scratch.`,
+        body: {
             type: 'object',
+            additionalProperties: false,
             properties: {
                 dir: {
                     type: 'string',
@@ -116,7 +147,7 @@ export const tools = [
                 to: {
                     type: 'object',
                     description:
-                        'Where it publishes, as in dashboard_publish: {type, id}, or {dashboard}. Its context is the one dashboard_dev uses.',
+                        'Where it publishes, as in publish: {type, id}, or {dashboard}. Its context is the one dev uses.',
                     properties: {
                         dashboard: { type: 'string' },
                         type: { type: 'string', enum: DASHBOARD_TARGETS },
@@ -140,15 +171,28 @@ export const tools = [
             },
             required: ['dir'],
         },
-        handler: toolInit,
+        examples: [
+            {
+                tool: 'resource_call',
+                arguments: {
+                    type: 'dashboard',
+                    action: 'init',
+                    body: { dir: 'plant-dashboard', to: { type: 'project', id: 'plant_a' } },
+                },
+                does: 'Start a React dashboard app that publishes as the dashboard of project plant_a.',
+            },
+        ],
+        run: (body) => toolInit(body),
     },
-    {
-        name: 'dashboard_dev',
-        description: `Develop a dashboard app on its own dev server (ng serve, npm run dev…) against this server, then publish it once with {tool:dashboard_publish}, instead of publishing to try every change.
+    dev: {
+        on: 'collection',
+        local: true,
+        description: `Develop a dashboard app on its own dev server (ng serve, npm run dev…) against this server, then publish it once with its publish action, instead of publishing to try every change.
 
 Returns a link to the app's local url that opens it as a standalone page: the SDK reads the server, a temporary token and the context from the link and calls the server directly, so the app gets real data, its dev server reloads it on every change and its errors are in the browser console. Start the app's dev server first (the answer says when nothing answers at url). Open the link with the browser tools to see the app and read its console. Each call replaces the previous link's token.`,
-        inputSchema: {
+        body: {
             type: 'object',
+            additionalProperties: false,
             properties: {
                 url: {
                     type: 'string',
@@ -158,7 +202,7 @@ Returns a link to the app's local url that opens it as a standalone page: the SD
                 to: {
                     type: 'object',
                     description:
-                        'Destination whose context the app gets, as in dashboard_publish: {type, id}, or {dashboard} for a collection dashboard (no context).',
+                        'Destination whose context the app gets, as in publish: {type, id}, or {dashboard} for a collection dashboard (no context).',
                     properties: {
                         dashboard: { type: 'string' },
                         type: { type: 'string', enum: DASHBOARD_TARGETS },
@@ -186,21 +230,24 @@ Returns a link to the app's local url that opens it as a standalone page: the SD
                     description:
                         'Allow a url that is not on this machine. The link carries a full-access token: only for a dev server the user named and trusts.',
                 },
-                user: { type: 'string', description: 'Account to act on (admin only).' },
             },
             required: ['url'],
         },
-        handler: toolDev,
+        run: (body, ctx) => toolDev(body, ctx),
     },
-    {
-        name: 'dashboard_publish',
-        description: `Publish an HTML app to a public storage and point dashboards at it. Upload (dir or files) and point (to) are both optional: upload a new build, point more dashboards at an app already uploaded, or both. Read the dashboard SDK reference with {tool:resource_describe} type "dashboard" first.
+    publish: {
+        on: 'collection',
+        local: true,
+        confirm: true,
+        op: ['Storage_UpdateFilesFiles(?<file>.*$)', 'Dashboard_Create', 'Dashboard_Update'],
+        description: `Publish an HTML app to a public storage and point dashboards at it. Upload (dir or files) and point (to) are both optional: upload a new build, point more dashboards at an app already uploaded, or both. Read the dashboard SDK reference first ({op:dashboard.describe}).
 
 Destinations (to): {dashboard} for the dashboards collection (created if missing, empty context), or {type, id} to set the "dashboard" property of a device, product, asset_type, asset_group or project, whose id the page gets in Thinger.context. Each may open its own entry page and an initial hash route.
 
-One app can serve many dashboards: name its storage (e.g. app_<project>) and upload the build output folder with prune: true (hashed file names change between builds). Dashboards point at the storage folder (…/files/, served as the storage's index) or at another entry page by name, without version queries: files are served with no-cache and an ETag, so viewers always get the latest upload. Apps in the iframe: start them with {tool:dashboard_init} (a TypeScript project on @thinger-io/dashboard-sdk with these rules set up and an AGENTS.md); hash routing, relative asset URLs and no <base> tag, render after Thinger.ready(), and no localStorage or cookies (opaque origin: keep state in properties through the SDK). Publish the build output folder; the answer warns when the app's SDK needs a newer server than this one, is not the latest on npm, or a page loads the deprecated script build (thinger-dashboard.js).`,
-        inputSchema: {
+One app can serve many dashboards: name its storage (e.g. app_<project>) and upload the build output folder with prune: true (hashed file names change between builds). Dashboards point at the storage folder (…/files/, served as the storage's index) or at another entry page by name, without version queries: files are served with no-cache and an ETag, so viewers always get the latest upload. Apps in the iframe: start them with the init action (a TypeScript project on @thinger-io/dashboard-sdk with these rules set up and an AGENTS.md); hash routing, relative asset URLs and no <base> tag, render after Thinger.ready(), and no localStorage or cookies (opaque origin: keep state in properties through the SDK). Publish the build output folder; the answer warns when the app's SDK needs a newer server than this one, is not the latest on npm, or a page loads the deprecated script build (thinger-dashboard.js).`,
+        body: {
             type: 'object',
+            additionalProperties: false,
             properties: {
                 storage: {
                     type: 'string',
@@ -218,7 +265,8 @@ One app can serve many dashboards: name its storage (e.g. app_<project>) and upl
                 },
                 prune: {
                     type: 'boolean',
-                    description: 'Delete files of the storage that are not in this upload.',
+                    description:
+                        'Delete files of the storage that are not in this upload (asks first: see confirm).',
                 },
                 to: {
                     type: 'array',
@@ -253,10 +301,24 @@ One app can serve many dashboards: name its storage (e.g. app_<project>) and upl
                     description:
                         'false: only build preview links for `to`, without pointing those dashboards again.',
                 },
-                user: { type: 'string', description: 'Account to act on (admin only).' },
             },
             required: [],
         },
-        handler: toolPublish,
+        examples: [
+            {
+                tool: 'resource_call',
+                arguments: {
+                    type: 'dashboard',
+                    action: 'publish',
+                    body: {
+                        dir: './dist',
+                        storage: 'app_plant',
+                        to: [{ dashboard: 'plant_overview' }],
+                    },
+                },
+                does: 'Upload the build in ./dist to storage app_plant and point dashboard plant_overview at it.',
+            },
+        ],
+        run: (body, ctx) => toolPublish(body, ctx),
     },
-];
+};

package/lib/mcp/types/device-resource.js

@@ -0,0 +1,117 @@
+// @ts-check
+import api from '../../api.js';
+import { apiError } from '../../errors.js';
+import { v1 } from '../../paths.js';
+import { callDeviceResource, listDeviceResourcesWithSchemas } from '../../resource.js';
+import { textResult } from '../helpers.js';
+
+/** What a resource takes and gives, by its `fn`. */
+const KIND = { 1: 'no params', 2: 'input', 3: 'output', 4: 'input/output' };
+
+/**
+ * The resources of a connected device (its firmware's API plus the API
+ * resources its product adds), as a type of the resource tools: list
+ * them, and run one with the `call` action. There is no get: reading a
+ * resource without input runs it.
+ *
+ * @type {import('../tools-resource.js').LocalType}
+ */
+export const deviceResource = {
+    description:
+        "Resources of a connected device: its firmware's API (a sensor to read, an output to switch) plus the API resources its product adds. Not server resources. The device must be online.",
+    parent: 'device',
+    id: 'resource',
+    recordId: 'name',
+
+    ops: { list: 'Device_AccessResources' },
+    notes: 'list gives each resource with its kind and its input and output shapes. Run one with the call action: with a body it runs with that input; without, it reads its output (a resource without input runs anyway).',
+    async list(ctx) {
+        const entries = await listDeviceResourcesWithSchemas(String(ctx.parent), {
+            user: ctx.user,
+        });
+        return entries.map((e) => ({ ...e, kind: KIND[e.fn] ?? 'unknown' }));
+    },
+    actions: {
+        call: {
+            description:
+                "Run a resource of a connected device with `body` as its input, and return its output; without a body it reads the output (a resource without input runs). Its input and output shapes are in the list of the device's resources.",
+            op: ['Device_AccessInputResources', 'Device_AccessOutputResources'],
+            examples: [
+                {
+                    tool: 'resource_call',
+                    arguments: {
+                        type: 'device_resource',
+                        action: 'call',
+                        ids: { device: 'boiler', resource: 'led' },
+                        body: true,
+                    },
+                    does: 'Switch the resource led on (its input is a boolean).',
+                },
+                {
+                    tool: 'resource_call',
+                    arguments: {
+                        type: 'device_resource',
+                        action: 'call',
+                        ids: { device: 'boiler', resource: 'temperature' },
+                    },
+                    does: 'Read the current output of the resource temperature.',
+                },
+            ],
+            async run(body, ctx) {
+                const data = await callDeviceResource(String(ctx.parent), String(ctx.id), body, {
+                    user: ctx.user,
+                });
+                return textResult(
+                    data === undefined || data === null || data === ''
+                        ? '(no output)'
+                        : typeof data === 'string'
+                          ? data
+                          : JSON.stringify(data, null, 2),
+                    data ?? null,
+                );
+            },
+        },
+    },
+};
+
+/**
+ * Usage of every device of the account, and their positions: an action on
+ * the collection of devices.
+ *
+ * @type {import('../tools-resource.js').LocalAction}
+ */
+export const overview = {
+    description:
+        'Usage of all the devices of the account over the last 30 days, per day; with body {locations: true}, also the last known position of each connected device.',
+    on: 'collection',
+    readOnly: true,
+    op: ['Device_ReadDevicesStatistics', 'User_ListDeviceLocations'],
+    body: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            locations: {
+                type: 'boolean',
+                description: 'Also the last known position of each connected device.',
+            },
+        },
+    },
+    examples: [
+        {
+            tool: 'resource_call',
+            arguments: { type: 'device', action: 'overview', body: { locations: true } },
+            does: 'Usage of every device, and where the connected ones are.',
+        },
+    ],
+    async run(body, ctx) {
+        try {
+            const [stats, locations] = await Promise.all([
+                api.get(`${v1(ctx.user)}/info/devices/stats`),
+                body?.locations ? api.get(`${v1(ctx.user)}/info/devices/locations`) : null,
+            ]);
+            return locations ? { stats: stats.data, locations: locations.data } : stats.data;
+        } catch (e) {
+            throw apiError(e);
+        }
+    },
+};

package/lib/mcp/types/doc.js

@@ -0,0 +1,35 @@
+// @ts-check
+import { listDocs, readDoc } from '../../docs.js';
+
+/**
+ * The guides for agents and app developers (docs.js) as a type of the
+ * resource tools: list them, read one whole.
+ *
+ * @type {import('../tools-resource.js').LocalType}
+ */
+export const doc = {
+    description:
+        "Guides for agents and app developers: the platform's concepts, product code, server administration, the dashboard SDK reference and types (the version the project in this folder uses), and this CLI's own.",
+    id: 'doc',
+    user: false,
+    local: true,
+    notes: 'Read the relevant guide before building something new: list gives the ids.',
+    examples: [
+        {
+            tool: 'resource_get',
+            arguments: { type: 'doc', ids: { doc: 'concepts' } },
+            does: "Read the guide to the platform's concepts.",
+        },
+    ],
+    async list() {
+        return (await listDocs()).map((d) => ({
+            doc: d.id,
+            title: d.title,
+            ...(d.description ? { description: d.description } : {}),
+            format: d.format,
+        }));
+    },
+    async get(ctx) {
+        return (await readDoc(String(ctx.id))).text;
+    },
+};

package/lib/mcp/types/plugin-call.js

@@ -0,0 +1,75 @@
+// @ts-check
+import api from '../../api.js';
+import { TIMEOUTS } from '../../constants.js';
+import { apiError, inputError } from '../../errors.js';
+import { pluginApi } from '../../paths.js';
+import { textResult } from '../helpers.js';
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+/**
+ * The API an installed plugin serves, at its own paths (no catalog): an
+ * action of the catalog type plugin. Its body is an envelope (path,
+ * method, body) and `query` goes to the plugin as is.
+ *
+ * @type {import('../tools-resource.js').LocalAction}
+ */
+export const pluginCall = {
+    description:
+        "Call the API an installed plugin serves: body {path, method, body} and the call's `query` go to the plugin as they are (what it offers depends on the plugin; see its documentation or try GET on its root).",
+    query: true,
+    body: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: { type: 'string', description: 'Path inside the plugin, e.g. "/api/status".' },
+            method: { type: 'string', enum: METHODS, description: 'Default get.' },
+            body: { description: 'JSON body for post, put and patch.' },
+        },
+    },
+    examples: [
+        {
+            tool: 'resource_call',
+            arguments: {
+                type: 'plugin',
+                action: 'call',
+                ids: { plugin: 'node-red' },
+                body: { path: '/api/status', method: 'get' },
+            },
+            does: "GET the plugin's /api/status.",
+        },
+    ],
+    async run(body, ctx) {
+        const b = body ?? {};
+        const method = String(b.method || 'get').toLowerCase();
+        if (!METHODS.includes(method))
+            throw inputError(`body.method must be one of ${METHODS.join(', ')}`);
+        const path = b.path ? `/${String(b.path).replace(/^\/+/, '')}` : '';
+        // %2e%2e is resolved like .. by the URL parser.
+        const dots = (seg) => /^(\.|%2e){1,2}$/i.test(seg);
+        if (path.split('/').some(dots))
+            throw inputError('body.path must not contain "." or ".." segments');
+        try {
+            const res = await api.request({
+                method,
+                url: `${pluginApi(ctx.user, String(ctx.id))}${path}`,
+                data: method === 'get' || method === 'delete' ? undefined : (b.body ?? {}),
+                params: ctx.query,
+                paramsSerializer: { indexes: null },
+                transformResponse: [(x) => x],
+                responseType: 'text',
+                timeout: TIMEOUTS.API_LONG_MS,
+            });
+            const raw = String(res.data ?? '');
+            let text = raw;
+            let data = raw;
+            try {
+                data = JSON.parse(raw);
+                text = JSON.stringify(data, null, 2);
+            } catch {}
+            return textResult(text || `${res.status} (no content)`, data === '' ? null : data);
+        } catch (e) {
+            throw apiError(e, { notFound: `Not found: plugin ${ctx.id}${path}` });
+        }
+    },
+};