@thinger-io/cli-core 0.1.0 → 0.2.0

package/lib/mcp/helpers.js

@@ -11,7 +11,7 @@ export async function withProfile(profile, fn) {
     if (!profile) return fn();
     if (!getProfile(profile)) {
         throw inputError(
-            `Unknown profile: ${profile}. Use ${toolName('profiles')} to list available ones.`,
+            `Unknown profile: ${profile}. Use ${toolName('profile_list')} to list available ones.`,
         );
     }
     return withActiveProfile(profile, fn);

package/lib/mcp/registry.js

@@ -1,30 +1,44 @@
 // @ts-check
-import { tools as devicesTools } from './tools-devices.js';
-import { tools as resourcesTools } from './tools-resources.js';
-import { tools as propertiesTools } from './tools-properties.js';
-import { tools as productsTools } from './tools-products.js';
-import { tools as profilesTools } from './tools-profiles.js';
-import { tools as bucketsTools } from './tools-buckets.js';
-import { tools as productProfileTools } from './tools-profile.js';
-import { tools as tokensTools } from './tools-tokens.js';
-import { tools as alarmsTools } from './tools-alarms.js';
+import { tools as bucketTools } from './tools-buckets.js';
+import { tools as dashboardTools } from './tools-dashboards.js';
+import { tools as deviceTools } from './tools-devices.js';
+import { tools as miscTools } from './tools-misc.js';
+import { tools as pluginTools } from './tools-plugins.js';
+import { tools as productTools } from './tools-products.js';
+import { resourceTools } from './tools-resource.js';
+import { tools as storageTools } from './tools-storage.js';
+import { FALLBACK_DOCS, docMimeType, listDocs, readDoc } from '../docs.js';
+import { identity } from '../identity.js';
 import { expandToolRefs, toolName } from './naming.js';
 
-/** Tools available to every CLI, declared with their bare names. */
-export const genericTools = [
-    ...devicesTools,
-    ...resourcesTools,
-    ...propertiesTools,
-    ...productsTools,
-    ...profilesTools,
-    ...bucketsTools,
-    ...productProfileTools,
-    ...tokensTools,
-    ...alarmsTools,
-];
+/**
+ * @typedef {object} ToolOptions
+ * @property {Record<string, import('./resource-hooks.js').ResourceHooks>} [hooks]
+ *   The CLI's own hooks on catalog types (see resource-hooks.js).
+ */
+
+/**
+ * Tools available to every CLI, declared with their bare names: the
+ * generic `resource_*` ones over the catalog, and the few operations that
+ * are not CRUD.
+ *
+ * @param {ToolOptions} [opts]
+ */
+export function genericTools(opts = {}) {
+    return [
+        ...resourceTools(opts),
+        ...deviceTools,
+        ...productTools,
+        ...bucketTools,
+        ...storageTools,
+        ...dashboardTools,
+        ...pluginTools,
+        ...miscTools,
+    ];
+}
 
-// `profiles` is the lookup of the profiles themselves, so it takes none.
-const PROFILE_EXEMPT = new Set(['profiles']);
+// `profile_list` is the lookup of the profiles themselves, so it takes none.
+const PROFILE_EXEMPT = new Set(['profile_list']);
 
 /**
  * Build the tool list a CLI serves: its own tools on top of the generic
@@ -38,8 +52,10 @@ const PROFILE_EXEMPT = new Set(['profiles']);
  *
  * @param {Array<object>} [extraTools] CLI-specific tools, same shape as the
  *   generic ones; `replaces: true` swaps out the generic tool of that name.
+ * @param {ToolOptions} [opts]
  */
-export function buildTools(extraTools = []) {
+export function buildTools(extraTools = [], opts = {}) {
+    const generic = genericTools(opts);
     // A CLI may replace a generic tool with its own (same name, flagged
     // `replaces: true`): its platform knows more about that operation.
     // Without the flag a clash is a mistake and fails loudly.
@@ -48,14 +64,14 @@ export function buildTools(extraTools = []) {
     for (const t of extraTools) {
         if (extraNames.has(t.name)) throw new Error(`Duplicate MCP tool name: ${t.name}`);
         extraNames.add(t.name);
-        const generic = genericTools.some((g) => g.name === t.name);
-        if (t.replaces && !generic) {
+        const isGeneric = generic.some((g) => g.name === t.name);
+        if (t.replaces && !isGeneric) {
             throw new Error(`MCP tool "${t.name}" replaces no generic tool`);
         }
-        if (generic && !t.replaces) throw new Error(`Duplicate MCP tool name: ${t.name}`);
-        if (generic) replaced.add(t.name);
+        if (isGeneric && !t.replaces) throw new Error(`Duplicate MCP tool name: ${t.name}`);
+        if (isGeneric) replaced.add(t.name);
     }
-    const declared = [...genericTools.filter((t) => !replaced.has(t.name)), ...extraTools];
+    const declared = [...generic.filter((t) => !replaced.has(t.name)), ...extraTools];
     const known = new Set(declared.map((t) => t.name));
 
     return declared.map((t) => {
@@ -64,7 +80,7 @@ export function buildTools(extraTools = []) {
             inputSchema.properties = inputSchema.properties || {};
             inputSchema.properties.profile = {
                 type: 'string',
-                description: `CLI profile to use for this call (see ${toolName('profiles')}). Omit for the default.`,
+                description: `CLI profile (server) for this call, see ${toolName('profile_list')}. Omit for the default.`,
             };
         }
         const { replaces: _replaces, ...rest } = t;
@@ -89,3 +105,29 @@ function expandSchema(node, known, where) {
     }
     return node;
 }
+
+/**
+ * MCP resources: the documents the server of the default profile lists in
+ * its documentation index (see docs.js), each as `<prefix>://<id>`. Listed
+ * on every request, so a guide the server adds shows up without a CLI
+ * release; the known ones when the server cannot be reached.
+ */
+export async function listResources() {
+    const prefix = identity().mcp.toolPrefix;
+    const docs = await listDocs().catch(() => FALLBACK_DOCS);
+    return docs.map((d) => ({
+        uri: `${prefix}://${d.id}`,
+        name: d.id,
+        title: d.title,
+        description: `${d.description || d.title} Also through ${toolName('doc_read')}.`,
+        mimeType: docMimeType(d.format),
+    }));
+}
+
+/** Text of the resource `<prefix>://<id>`. */
+export async function readResource(uri) {
+    const prefix = `${identity().mcp.toolPrefix}://`;
+    if (!uri.startsWith(prefix)) throw new Error(`Unknown resource: ${uri}`);
+    const { doc, text } = await readDoc(uri.slice(prefix.length));
+    return { mimeType: docMimeType(doc.format), text };
+}

package/lib/mcp/resource-hooks.js

@@ -0,0 +1,145 @@
+// @ts-check
+import { CREDENTIAL_DEVICE_TYPES, generateDeviceCredentials } from '../devices.js';
+import { identity } from '../identity.js';
+import { resolveExpiry, validatePermissionTree } from '../tokens.js';
+import { toolName } from './naming.js';
+
+/**
+ * What the generic `resource_*` tools do beyond the plain request, for the
+ * few types where the CLI knows better than a bare call: generated device
+ * credentials, the identity's product template, token expiries written as
+ * "30d". Everything else goes to the server as the caller wrote it.
+ *
+ * A CLI adds its own hooks (its platform's extra cleanup on delete, say)
+ * through `runCli({ resourceHooks })`; they run after these.
+ *
+ * @typedef {object} HookContext
+ * @property {string} type
+ * @property {string} [parent]
+ * @property {string} [id]
+ * @property {string | null} [user]
+ * @property {boolean} [full]  resource_get asked for the whole record.
+ * @property {Record<string, any>} state  Scratch space shared by the hooks of one call.
+ *
+ * @typedef {object} ResourceHooks
+ * @property {(body: any, ctx: HookContext) => any} [beforeCreate]  Returns the body to send.
+ * @property {(body: any, ctx: HookContext) => any} [beforeUpdate]  Returns the body to send.
+ * @property {(result: any, ctx: HookContext) => string | void | Promise<string | void>} [afterCreate]
+ *   Returns a note added to the tool's answer.
+ * @property {(record: any, ctx: HookContext) => any} [afterGet]  Returns the record to show.
+ * @property {(ctx: HookContext) => string | void | Promise<string | void>} [afterDelete]
+ *   Returns a note added to the tool's answer.
+ */
+
+/** Token bodies: expiry as a duration, permission trees checked before sending. */
+function tokenBody(body) {
+    validatePermissionTree(body.allow, 'allow');
+    validatePermissionTree(body.deny, 'deny');
+    if (body.expire === undefined) return body;
+    const expire = resolveExpiry(body.expire);
+    const { expire: _expire, ...rest } = body;
+    return expire === null ? rest : { ...rest, expire };
+}
+
+/** @type {Record<string, ResourceHooks>} */
+export const coreHooks = {
+    device: {
+        // Credentials are stored hashed: generated ones must be shown now
+        // or never.
+        // The server requires a type; Generic (IOTMP) is the usual one.
+        beforeCreate(body, ctx) {
+            const type = body.type || 'Generic';
+            if (!CREDENTIAL_DEVICE_TYPES.has(type) || body.credentials) return { ...body, type };
+            ctx.state.credentials = generateDeviceCredentials();
+            return { ...body, type, credentials: ctx.state.credentials };
+        },
+        afterCreate(_result, ctx) {
+            if (!ctx.state.credentials) return;
+            return `Generated credentials: ${ctx.state.credentials}\nThe server stores them hashed: this is the only time they can be read. Hand them to whoever flashes the device now.`;
+        },
+    },
+    product: {
+        beforeCreate(body) {
+            const template = identity().productTemplate || {};
+            const config = { ...structuredClone(template.config || {}), ...(body.config || {}) };
+            const profile = body.profile || (template.profile && structuredClone(template.profile));
+            return {
+                ...body,
+                name: body.name || body.product,
+                description: body.description ?? template.description ?? '',
+                enabled: body.enabled ?? true,
+                ...(Object.keys(config).length ? { config } : {}),
+                ...(profile ? { profile } : {}),
+            };
+        },
+    },
+    token: {
+        beforeCreate: (body) => tokenBody({ enabled: true, ...body }),
+        beforeUpdate: (body) => tokenBody(body),
+        afterCreate: () =>
+            `Keep the access_token now: lists never show it (${toolName('resource_get')} on the token does).`,
+    },
+    plugin: {
+        // A catalog manifest (no `state`: not installed) carries each
+        // product's code and console dashboard, thousands of tokens of
+        // little use until asked for.
+        afterGet(record, ctx) {
+            const products = record?.resources?.products;
+            if (ctx.full || record?.state !== undefined || !Array.isArray(products)) return record;
+            let left = false;
+            const trimmed = products.map((product) => {
+                const { _resources, ...rest } = product || {};
+                const code = rest.profile?.code;
+                if (_resources !== undefined) left = true;
+                if (!code || typeof code !== 'object' || code.code === undefined) return rest;
+                left = true;
+                const { code: _source, ...meta } = code;
+                return { ...rest, profile: { ...rest.profile, code: meta } };
+            });
+            if (!left) return record;
+            return {
+                ...record,
+                resources: { ...record.resources, products: trimmed },
+                omitted: `profile.code.code and _resources (console dashboard) of each product: ${toolName('resource_get')} with full: true includes them`,
+            };
+        },
+    },
+    device_token: {
+        beforeCreate(body) {
+            if (body.token_expiration === undefined) return body;
+            const expiration = resolveExpiry(body.token_expiration);
+            const { token_expiration: _e, ...rest } = body;
+            return expiration === null ? rest : { ...rest, token_expiration: expiration };
+        },
+    },
+};
+
+/**
+ * Chain the core hooks with a CLI's: for each type and stage the CLI's
+ * runs on what the core's produced.
+ *
+ * @param {Record<string, ResourceHooks>} [extra]
+ * @returns {Record<string, ResourceHooks>}
+ */
+export function mergeHooks(extra = {}) {
+    const merged = { ...coreHooks };
+    for (const [type, hooks] of Object.entries(extra)) {
+        const base = merged[type] || {};
+        /** @type {any} */
+        const out = { ...base };
+        for (const [stage, fn] of Object.entries(hooks)) {
+            const first = base[stage];
+            if (!first) {
+                out[stage] = fn;
+            } else if (stage === 'afterCreate' || stage === 'afterDelete') {
+                // Both notes are kept.
+                out[stage] = async (a, b) =>
+                    [await first(a, b), await fn(a, b)].filter(Boolean).join('\n') || undefined;
+            } else {
+                out[stage] = async (value, ctx) => fn(await first(value, ctx), ctx);
+            }
+        }
+        merged[type] = out;
+    }
+    return merged;
+}

package/lib/mcp/server.js

@@ -1,11 +1,17 @@
 // @ts-check
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+    CallToolRequestSchema,
+    ListResourcesRequestSchema,
+    ListToolsRequestSchema,
+    ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
 import { classifyError } from '../output.js';
 import { identity } from '../identity.js';
-import { buildTools } from './registry.js';
+import { buildTools, listResources, readResource } from './registry.js';
 import { withProfile } from './helpers.js';
+import { defineCliDocs } from '../docs.js';
 
 /**
  * Start the MCP server over stdio. Serves the generic tools plus the ones
@@ -14,19 +20,30 @@ import { withProfile } from './helpers.js';
  *
  * stdout is the protocol channel from here on: diagnostics go to stderr.
  *
- * @param {{ version?: string, tools?: Array<object>, instructions?: string }} [opts]
+ * @param {{
+ *   version?: string,
+ *   tools?: Array<object>,
+ *   instructions?: string,
+ *   resourceHooks?: Record<string, import('./resource-hooks.js').ResourceHooks>,
+ *   docs?: Parameters<typeof import('../docs.js').defineCliDocs>[0],
+ * }} [opts]
  *   `version` is echoed in the `initialize` response's `serverInfo.version`;
  *   callers pass their `package.json#version` so the two never drift.
  *   `tools` are CLI-specific tools added to the generic set.
  *   `instructions` is the server-level guidance sent to the client.
+ *   `resourceHooks` are the CLI's hooks on catalog types.
+ *   `docs` are the guides the CLI ships (see docs.js).
  */
 export async function startMCPServer({
     version = 'unknown',
     tools: extra = [],
     instructions,
+    resourceHooks,
+    docs,
 } = {}) {
     const { mcp } = identity();
-    const tools = buildTools(extra);
+    defineCliDocs(docs);
+    const tools = buildTools(extra, { hooks: resourceHooks });
 
     const server = new Server(
         {
@@ -34,7 +51,7 @@ export async function startMCPServer({
             version,
         },
         {
-            capabilities: { tools: {} },
+            capabilities: { tools: {}, resources: {} },
             ...(instructions ? { instructions } : {}),
         },
     );
@@ -43,6 +60,18 @@ export async function startMCPServer({
         tools: tools.map(({ handler: _handler, ...t }) => t),
     }));
 
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: await listResources(),
+    }));
+
+    // Resources are read with the default profile: the protocol gives them
+    // no arguments to pick another.
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        const { mimeType, text } = await readResource(uri);
+        return { contents: [{ uri, mimeType, text }] };
+    });
+
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const name = request.params.name;
         const args = request.params.arguments || {};
@@ -53,6 +82,18 @@ export async function startMCPServer({
                 isError: true,
             };
         }
+        // An argument the tool does not declare is a misspelled one
+        // ("aggregation" for "agg"): say so instead of silently ignoring it.
+        const known = tool.inputSchema?.properties;
+        const unknown = known ? Object.keys(args).filter((k) => !(k in known)) : [];
+        if (unknown.length) {
+            const message = `Unknown argument${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}. ${name} takes: ${Object.keys(known).join(', ')}.`;
+            return {
+                content: [{ type: 'text', text: `Error [input_error]: ${message}` }],
+                isError: true,
+                _meta: { code: 'input_error', message },
+            };
+        }
         try {
             return await withProfile(args.profile, () => tool.handler(args));
         } catch (error) {

package/lib/mcp/tools-buckets.js

@@ -1,33 +1,15 @@
 // @ts-check
-import { getBucketData, getBuckets } from '../bucket.js';
-import { inputError } from '../errors.js';
-import { toolName } from './naming.js';
+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';
 
-async function toolBuckets(args) {
-    const buckets = await getBuckets(args.user);
-    if (!buckets.length) {
-        return { content: [{ type: 'text', text: 'No buckets configured' }], isError: false };
-    }
-    const lines = buckets.map((b) => {
-        const enabled = b.enabled === false ? '✗' : '✓';
-        const name = b.name && b.name !== b.bucket ? ` (${b.name})` : '';
-        const source = b.config?.source ? `  source: ${b.config.source}` : '';
-        const product = b.product ? `  [product ${b.product}]` : '';
-        const description = b.description ? `  — ${b.description}` : '';
-        return `${enabled}  ${b.bucket}${name}${product}${source}${description}`;
-    });
-    return {
-        content: [{ type: 'text', text: `${buckets.length} bucket(s):\n${lines.join('\n')}` }],
-        isError: false,
-    };
-}
-
-async function toolBucketRead(args) {
-    if (!args.bucket)
-        throw inputError(`bucket is required. Use ${toolName('buckets')} to list them.`);
+async function toolBucketDataRead(args) {
+    if (!args.bucket) throw inputError('bucket is required');
     const data = await getBucketData({
         bucket: args.bucket,
-        device: args.device_id,
+        device: args.device,
         user: args.user,
         items: args.items || 10,
         sort: args.sort || 'desc',
@@ -36,96 +18,113 @@ async function toolBucketRead(args) {
         max_ts: args.max_ts,
         agg: args.agg,
         agg_type: args.agg_type,
-        fields: args.fields,
+        tz: args.tz,
+        fields: Array.isArray(args.fields) ? args.fields.join(',') : args.fields,
         group_by: args.group_by,
     });
     const text =
         Array.isArray(data) && data.length === 0 ? 'No data' : JSON.stringify(data, null, 2);
+    return { content: [{ type: 'text', text }], isError: false };
+}
+
+async function toolBucketDataWrite(args) {
+    if (!args.bucket) throw inputError('bucket is required');
+    if (!args.data || typeof args.data !== 'object') {
+        throw inputError('data must be a JSON object (one sample) or an array of them');
+    }
+    const count = Array.isArray(args.data) ? args.data.length : 1;
+    const params = args.ts !== undefined ? { ts: args.ts } : undefined;
+    try {
+        await api.post(
+            `${v1(args.user)}/buckets/${encodeURIComponent(args.bucket)}/data`,
+            args.data,
+            { params, timeout: TIMEOUTS.API_LONG_MS },
+        );
+    } catch (e) {
+        throw apiError(e, { notFound: `Bucket not found: ${args.bucket}` });
+    }
     return {
-        content: [{ type: 'text', text }],
+        content: [
+            {
+                type: 'text',
+                text: `Wrote ${count} sample${count === 1 ? '' : 's'} to bucket ${args.bucket}.`,
+            },
+        ],
         isError: false,
     };
 }
 
+const userParam = { type: 'string', description: 'Account to act on (admin only).' };
+
 export const tools = [
     {
-        name: 'buckets',
-        description:
-            'List the data buckets of the account with their enabled flag, name, owning product (for buckets declared in a product profile), data source and description. Use it to find bucket ids for {tool:bucket_read}.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                user: { type: 'string', description: 'API user' },
-            },
-            required: [],
-        },
-        handler: toolBuckets,
-    },
-    {
-        name: 'bucket_read',
-        description: `Query a time-series bucket.
+        name: 'bucket_data_read',
+        description: `Query the time series of a bucket (find them with {tool:resource_list}: type "bucket", or "device_bucket" for one device).
 
-Modes:
-- no device: the account bucket (see {tool:buckets}). For a bucket declared in a product profile this holds the samples of every device of the product, interleaved; pass \`group_by=device\` (when samples are tagged with \`device\`) to get one row per device.
-- device set: the series a product bucket records for that one device.
-
-Don't assume a \`device\` tag exists unless the bucket or product profile defines it.`,
+- Without \`device\`: the whole bucket. A bucket declared in a product profile holds every device of the product interleaved; \`group_by: "device"\` gives one row per device, when samples carry that tag.
+- With \`device\`: the series the bucket keeps for that device.`,
         inputSchema: {
             type: 'object',
             properties: {
-                bucket: {
+                bucket: { type: 'string', description: 'Bucket id.' },
+                device: {
                     type: 'string',
                     description:
-                        'Bucket ID, as listed by {tool:buckets} or declared in a product profile.',
-                },
-                device_id: {
-                    type: 'string',
-                    description:
-                        'Device ID, to read the series a product bucket keeps for that device. Omit to read the account bucket.',
+                        'Device id, to read only its records: the bucket needs the `device` tag (product buckets have it).',
                 },
                 items: {
                     type: 'number',
-                    description:
-                        'Number of data points to return (default: 10). In multi-device mode set ≥ number of devices.',
+                    description: 'Samples to return (default 10, at most 1000).',
                 },
                 minutes: {
                     type: 'number',
-                    description: 'Get data from the last N minutes. Alternative to min_ts/max_ts.',
+                    description: 'Last N minutes (instead of min_ts/max_ts).',
                 },
-                min_ts: { type: 'number', description: 'Minimum timestamp in milliseconds' },
-                max_ts: {
-                    type: 'number',
-                    description: 'Maximum timestamp in milliseconds (0 = now)',
-                },
-                sort: {
-                    type: 'string',
-                    description:
-                        'Sort order by timestamp: "asc" or "desc" (default: "desc"). Does NOT sort by metric — do that client-side.',
-                },
-                agg: {
+                min_ts: { type: 'number', description: 'From (unix ms).' },
+                max_ts: { type: 'number', description: 'To (unix ms, 0 = now).' },
+                sort: { type: 'string', description: '"desc" (default) or "asc", by time.' },
+                agg: { type: 'string', description: 'Aggregation window: "5m", "1h"…' },
+                agg_type: {
                     type: 'string',
                     description:
-                        'Time-window size for windowed aggregation: "5m", "10m", "1h", "6h". Only meaningful with a specific device. For a per-device single value across the whole range, omit `agg` and pass `agg_type` alone.',
+                        'Reducer: mean, max, min, sum, count, first, last, mode, median, spread, stddev.',
                 },
-                agg_type: {
+                tz: {
                     type: 'string',
                     description:
-                        'Reducer applied to each group/window. Supported: "mean", "max", "min", "sum", "count", "first", "last", "median", "spread", "stddev".',
+                        'IANA time zone for the aggregation windows, e.g. "Europe/Madrid": "1d" then cuts at local midnight (default UTC).',
                 },
                 fields: {
-                    type: 'string',
+                    type: ['string', 'array'],
+                    items: { type: 'string' },
                     description:
-                        'Comma-separated fields to return (e.g., "temperature,humidity"). Narrower queries are cheaper.',
+                        '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',
+                group_by: { type: 'string', description: 'Group key, e.g. "device".' },
+                user: userParam,
+            },
+            required: ['bucket'],
+        },
+        handler: toolBucketDataRead,
+    },
+    {
+        name: 'bucket_data_write',
+        description:
+            'Write samples to a bucket whose data source accepts API writes: one object, stored with the current time or `ts`, or an array of objects, each with its own numeric `ts` (unix ms; MongoDB and InfluxDB buckets). Servers limit how often a bucket can be written (429 when exceeded): for long histories, import a CSV ({tool:resource_call} action "import" on the bucket).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: 'Bucket id.' },
+                data: {
+                    type: ['object', 'array'],
                     description:
-                        'Optional group key (e.g. "device" for a one-row-per-device fleet view). Omit for raw samples — custom buckets may not carry a "device" tag.',
+                        'Sample fields, e.g. {"temperature": 21.5}, or an array of samples with `ts`.',
                 },
-                user: { type: 'string', description: 'API user' },
+                ts: { type: 'number', description: 'Timestamp of the sample (unix ms).' },
+                user: userParam,
             },
-            required: ['bucket'],
+            required: ['bucket', 'data'],
         },
-        handler: toolBucketRead,
+        handler: toolBucketDataWrite,
     },
 ];