@thinremote/thinr-cli 1.2.0-alpha.1 → 1.2.0

package/lib/mcp/tools-buckets.js

@@ -0,0 +1,103 @@
+// @ts-check
+import { getBucketData } from '../bucket.js';
+import { inputError } from '../errors.js';
+
+async function toolBucketRead(args) {
+    if (!args.bucket)
+        throw inputError(
+            'bucket is required. Buckets are declared in the product profile (default: "monitoring").',
+        );
+    const data = await getBucketData({
+        bucket: args.bucket,
+        device: args.device,
+        user: args.user,
+        items: args.items || 10,
+        sort: args.sort || 'desc',
+        minutes: args.minutes,
+        min_ts: args.min_ts,
+        max_ts: args.max_ts,
+        agg: args.agg,
+        agg_type: args.agg_type,
+        fields: 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,
+    };
+}
+
+export const tools = [
+    {
+        name: 'thinr_bucket_read',
+        description: `Query any time-series bucket declared in the product profile. Use this for custom metrics (domain data, business events, custom sensors) beyond the default \`monitoring\` bucket — for \`monitoring\` itself prefer \`thinr_monitoring\`, which formats the output.
+
+Modes:
+- device set: historical time series scoped to that device.
+- no device: user-level query across the fleet. By default returns raw interleaved samples; pass \`group_by=device\` (assuming the bucket tags samples with \`device\`) to get one row per device.
+
+Custom buckets may not share the \`monitoring\` schema — don't assume a \`device\` tag exists unless the product profile defines it.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: {
+                    type: 'string',
+                    description:
+                        'Bucket ID as declared in the product profile (e.g. "monitoring", or a custom one like "sensors", "events").',
+                },
+                device: {
+                    type: 'string',
+                    description:
+                        'Device ID. Omit for a one-row-per-device fleet view.',
+                },
+                items: {
+                    type: 'number',
+                    description:
+                        'Number of data points to return (default: 10). In multi-device mode set ≥ number of devices.',
+                },
+                minutes: {
+                    type: 'number',
+                    description:
+                        'Get data from the last N minutes. Alternative to 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: {
+                    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.',
+                },
+                agg_type: {
+                    type: 'string',
+                    description:
+                        'Reducer applied to each group/window. Supported: "mean", "max", "min", "sum", "count", "first", "last", "median", "spread", "stddev".',
+                },
+                fields: {
+                    type: 'string',
+                    description:
+                        'Comma-separated fields to return (e.g., "temperature,humidity"). Narrower queries are cheaper.',
+                },
+                group_by: {
+                    type: 'string',
+                    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.',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['bucket'],
+        },
+        handler: toolBucketRead,
+    },
+];

package/lib/mcp/tools-devices.js

@@ -1,7 +1,8 @@
 // @ts-check
-import { getDevices, getDevice } from '../devices.js';
+import { getDevices, getDevice, deleteDevice } from '../devices.js';
 import { setDeviceProduct } from '../product.js';
 import { inputError } from '../errors.js';
+import { BYTES } from '../constants.js';
 import { getAPI } from './helpers.js';
 
 async function toolDevices(args) {
@@ -87,11 +88,11 @@ async function toolDeviceInfo(args) {
             );
         if (mon.memory)
             parts.push(
-                `Memory: ${mon.memory.usage?.toFixed(1)}% (${(mon.memory.total / 1073741824).toFixed(1)}GB total)`,
+                `Memory: ${mon.memory.usage?.toFixed(1)}% (${(mon.memory.total / BYTES.GB).toFixed(1)}GB total)`,
             );
         if (mon.disk?.root)
             parts.push(
-                `Disk: ${mon.disk.root.usage?.toFixed(1)}% (${(mon.disk.root.total / 1073741824).toFixed(0)}GB total)`,
+                `Disk: ${mon.disk.root.usage?.toFixed(1)}% (${(mon.disk.root.total / BYTES.GB).toFixed(0)}GB total)`,
             );
         if (mon.network)
             parts.push(
@@ -131,6 +132,21 @@ async function toolDeviceSetProduct(args) {
     return { content: [{ type: 'text', text: label }], isError: false };
 }
 
+async function toolDeviceDelete(args) {
+    const device = args.device;
+    if (!device) throw inputError('device is required');
+    const removed = await deleteDevice(device, args.user);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: removed ? `Deleted ${device}` : `Device ${device} did not exist`,
+            },
+        ],
+        isError: false,
+    };
+}
+
 export const tools = [
     {
         name: 'thinr_devices',
@@ -191,4 +207,18 @@ export const tools = [
         },
         handler: toolDeviceSetProduct,
     },
+    {
+        name: 'thinr_device_delete',
+        description:
+            'Delete a device record from the platform. Destructive and irreversible — drops the device, its server-side metadata, and stored properties. The agent on the host (if still running) will be left orphaned and will not auto-recreate the record. Idempotent: returns success when the device was already absent.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                device: { type: 'string', description: 'Device ID to delete.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['device'],
+        },
+        handler: toolDeviceDelete,
+    },
 ];

package/lib/mcp/tools-exec.js

@@ -1,14 +1,17 @@
 // @ts-check
 import { getMonitoringData } from '../monitoring.js';
 import { inputError } from '../errors.js';
+import { BYTES, TIMEOUTS } from '../constants.js';
 import { getAPI } from './helpers.js';
 
 async function toolExec(args) {
     const { api } = getAPI(args.device, args.user);
-    // Default to 30s so a hung command doesn't lock the session
-    // indefinitely. Callers can pass a larger value for known-long
-    // operations (compiles, backups, …).
-    const timeout = Number.isFinite(args.timeout) && args.timeout > 0 ? args.timeout : 30;
+    // Default guards against hung commands locking the session; callers
+    // override for known-long operations. Knob lives in lib/constants.js.
+    const timeout =
+        Number.isFinite(args.timeout) && args.timeout > 0
+            ? args.timeout
+            : TIMEOUTS.DEFAULT_EXEC_SECONDS;
     let output = '';
     const { exitCode, timedOut } = await api.execStream(args.command, {
         timeout,
@@ -58,15 +61,15 @@ async function toolMonitoring(args) {
             );
         if (mon.memory)
             parts.push(
-                `Memory: ${mon.memory.usage?.toFixed(1)}% (available: ${(mon.memory.available / 1073741824).toFixed(1)}GB / total: ${(mon.memory.total / 1073741824).toFixed(1)}GB)`,
+                `Memory: ${mon.memory.usage?.toFixed(1)}% (available: ${(mon.memory.available / BYTES.GB).toFixed(1)}GB / total: ${(mon.memory.total / BYTES.GB).toFixed(1)}GB)`,
             );
         if (mon.disk?.root)
             parts.push(
-                `Disk: ${mon.disk.root.usage?.toFixed(1)}% (available: ${(mon.disk.root.available / 1073741824).toFixed(1)}GB / total: ${(mon.disk.root.total / 1073741824).toFixed(0)}GB)`,
+                `Disk: ${mon.disk.root.usage?.toFixed(1)}% (available: ${(mon.disk.root.available / BYTES.GB).toFixed(1)}GB / total: ${(mon.disk.root.total / BYTES.GB).toFixed(0)}GB)`,
             );
         if (mon.network)
             parts.push(
-                `Network: rx=${(mon.network.rx_rate / 1024).toFixed(1)}KB/s tx=${(mon.network.tx_rate / 1024).toFixed(1)}KB/s`,
+                `Network: rx=${(mon.network.rx_rate / BYTES.KB).toFixed(1)}KB/s tx=${(mon.network.tx_rate / BYTES.KB).toFixed(1)}KB/s`,
             );
         if (mon.load)
             parts.push(
@@ -99,8 +102,10 @@ async function toolMonitoring(args) {
     if (Array.isArray(data) && data.length > 0) {
         output = data
             .map((d) => {
-                const ts = new Date(d.ts).toISOString();
-                const parts = [ts];
+                // Single-window aggregated rows (group_by without `agg`) come
+                // back without `ts`; skip it rather than emitting "Invalid Date".
+                const parts = [];
+                if (d.ts) parts.push(new Date(d.ts).toISOString());
                 if (d.device) parts.push(`device=${d.device}`);
                 if (d.cpu) {
                     const cpuParts = [];
@@ -113,7 +118,7 @@ async function toolMonitoring(args) {
                 if (d.disk?.root) parts.push(`disk=${d.disk.root.usage?.toFixed(1)}%`);
                 if (d.network)
                     parts.push(
-                        `net_rx=${(d.network.rx_rate / 1024)?.toFixed(1)}KB/s tx=${(d.network.tx_rate / 1024)?.toFixed(1)}KB/s`,
+                        `net_rx=${(d.network.rx_rate / BYTES.KB)?.toFixed(1)}KB/s tx=${(d.network.tx_rate / BYTES.KB)?.toFixed(1)}KB/s`,
                     );
                 if (d.load) parts.push(`load=${d.load['1m']?.toFixed(2)}`);
                 if (d.processes) parts.push(`procs=${d.processes.total}`);
@@ -166,7 +171,12 @@ export const tools = [
     },
     {
         name: 'thinr_monitoring',
-        description: `Get monitoring data (CPU, memory, disk, network, temperature, load) from a device or all devices. Use realtime=true for live data from the device, or omit for historical data from the monitoring bucket.`,
+        description: `Get monitoring data (CPU, memory, disk, network, temperature, load).
+
+Modes:
+- realtime=true + device: live sample read straight from the agent.
+- device only: historical time series for that device. Use \`agg\`+\`agg_type\` for time-windowed aggregates (e.g. avg CPU every 5m over the last hour).
+- no device: historical fleet view — returns ONE ROW PER DEVICE. Without \`agg_type\` each row is the latest sample for that device ("current fleet state"). With \`agg_type\` each row is the reducer applied over the time window per device (e.g. \`agg_type=max\`+\`minutes=60\` ⇒ peak per device in the last hour, ideal for ranking "which device had the most X"). Sort the returned array client-side on the metric to get the top N.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -178,11 +188,11 @@ export const tools = [
                 device: {
                     type: 'string',
                     description:
-                        'Device ID. Required for realtime. Omit for historical data from ALL devices.',
+                        'Device ID. Required for realtime. Omit for a one-row-per-device fleet view.',
                 },
                 items: {
                     type: 'number',
-                    description: 'Number of data points to return (default: 10)',
+                    description: 'Number of data points to return (default: 10). In multi-device mode set ≥ number of devices (e.g. 200) since each device contributes one row.',
                 },
                 minutes: {
                     type: 'number',
@@ -195,14 +205,17 @@ export const tools = [
                 },
                 sort: {
                     type: 'string',
-                    description: 'Sort order: "asc" or "desc" (default: "desc")',
+                    description: 'Sort order by timestamp: "asc" or "desc" (default: "desc"). Does NOT sort by metric — do that client-side on the result.',
+                },
+                agg: { 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.' },
+                agg_type: {
+                    type: 'string',
+                    description: 'Reducer applied to each group/window. Supported: "mean", "max", "min", "sum", "count", "first", "last", "median", "spread" (max-min), "stddev". Most common for monitoring: max, mean, min.',
                 },
-                agg: { type: 'string', description: 'Aggregation period: "5m", "10m", "1h", "6h"' },
-                agg_type: { type: 'string', description: 'Aggregation type: "mean", "min", "max"' },
                 fields: {
                     type: 'string',
                     description:
-                        'Comma-separated fields to return (e.g., "cpu.usage,memory.usage,disk.root.usage")',
+                        'Comma-separated fields to return (e.g., "cpu.usage,memory.usage,disk.root.usage"). Narrower queries are cheaper and produce tidier output.',
                 },
                 user: { type: 'string', description: 'API user' },
             },

package/lib/mcp/tools-filesystem.js

@@ -1,5 +1,8 @@
 // @ts-check
+import { readFile as readLocalFile, writeFile as writeLocalFile } from 'fs/promises';
+import { resolve as resolvePath, basename } from 'path';
 import { getAPI } from './helpers.js';
+import { inputError } from '../errors.js';
 
 async function toolRead(args) {
     const { api } = getAPI(args.device, args.user);
@@ -43,7 +46,7 @@ async function toolMkdir(args) {
     };
 }
 
-async function toolDelete(args) {
+async function toolRm(args) {
     const { api } = getAPI(args.device, args.user);
     await api.delete(args.path, args.recursive !== false);
     return {
@@ -52,7 +55,7 @@ async function toolDelete(args) {
     };
 }
 
-async function toolMove(args) {
+async function toolMv(args) {
     const { api } = getAPI(args.device, args.user);
     await api.move(args.source, args.destination, args.overwrite || false);
     return {
@@ -61,6 +64,55 @@ async function toolMove(args) {
     };
 }
 
+async function toolPush(args) {
+    if (typeof args.source !== 'string' || !args.source) {
+        throw inputError('`source` (local file path) is required');
+    }
+    if (typeof args.destination !== 'string' || !args.destination) {
+        throw inputError('`destination` (remote path on the device) is required');
+    }
+    const localPath = resolvePath(args.source);
+    const remotePath = args.destination.endsWith('/')
+        ? args.destination + basename(localPath)
+        : args.destination;
+    const { api } = getAPI(args.device, args.user);
+    const content = await readLocalFile(localPath);
+    await api.writeFile(remotePath, content);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Pushed ${content.byteLength} bytes: ${localPath} → ${remotePath}`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolPull(args) {
+    if (typeof args.source !== 'string' || !args.source) {
+        throw inputError('`source` (remote path on the device) is required');
+    }
+    if (typeof args.destination !== 'string' || !args.destination) {
+        throw inputError('`destination` (local file path) is required');
+    }
+    const localPath = args.destination.endsWith('/')
+        ? resolvePath(args.destination, basename(args.source))
+        : resolvePath(args.destination);
+    const { api } = getAPI(args.device, args.user);
+    const buf = await api.readFile(args.source);
+    await writeLocalFile(localPath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Pulled ${buf.byteLength} bytes: ${args.source} → ${localPath}`,
+            },
+        ],
+        isError: false,
+    };
+}
+
 export const tools = [
     {
         name: 'thinr_read',
@@ -124,7 +176,7 @@ export const tools = [
         handler: toolMkdir,
     },
     {
-        name: 'thinr_delete',
+        name: 'thinr_rm',
         description: `Delete a file or directory on a remote device. Paths are absolute on the device filesystem (e.g., "/etc/hosts", "/var/log/syslog"). Subject to the OS user the agent runs as; check whoami (or thinr_device_info) before assuming write access to system paths like /etc.`,
         inputSchema: {
             type: 'object',
@@ -139,10 +191,10 @@ export const tools = [
             },
             required: ['path', 'device'],
         },
-        handler: toolDelete,
+        handler: toolRm,
     },
     {
-        name: 'thinr_move',
+        name: 'thinr_mv',
         description: `Move or rename a file or directory on a remote device. Paths are absolute on the device filesystem (e.g., "/etc/hosts", "/var/log/syslog"). Subject to the OS user the agent runs as; check whoami (or thinr_device_info) before assuming write access to system paths like /etc.`,
         inputSchema: {
             type: 'object',
@@ -158,6 +210,50 @@ export const tools = [
             },
             required: ['source', 'destination', 'device'],
         },
-        handler: toolMove,
+        handler: toolMv,
+    },
+    {
+        name: 'thinr_push',
+        description: `Upload a local file to a remote device. \`source\` is a path on the machine running the MCP server; \`destination\` is an absolute path on the device (trailing "/" keeps the source basename). Use this for binary or large payloads that don't fit as inline strings in thinr_write.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: {
+                    type: 'string',
+                    description: 'Local file path (absolute or relative to the MCP server CWD).',
+                },
+                destination: {
+                    type: 'string',
+                    description:
+                        'Absolute path on the device. Trailing "/" keeps the source basename.',
+                },
+                device: { type: 'string', description: 'Device ID' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['source', 'destination', 'device'],
+        },
+        handler: toolPush,
+    },
+    {
+        name: 'thinr_pull',
+        description: `Download a remote file from a device to the local disk of the machine running the MCP server. \`source\` is an absolute path on the device; \`destination\` is a local file path (trailing "/" keeps the source basename).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: {
+                    type: 'string',
+                    description: 'Absolute file path on the device.',
+                },
+                destination: {
+                    type: 'string',
+                    description:
+                        'Local file path (absolute or relative to the MCP server CWD). Trailing "/" keeps the source basename.',
+                },
+                device: { type: 'string', description: 'Device ID' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['source', 'destination', 'device'],
+        },
+        handler: toolPull,
     },
 ];

package/lib/mcp/tools-install.js

@@ -0,0 +1,153 @@
+// @ts-check
+import { requireConfig } from '../config.js';
+import { inputError } from '../errors.js';
+
+const CHANNEL_SCRIPT = {
+    latest: 'install.sh',
+    main: 'install-main.sh',
+    develop: 'install-develop.sh',
+};
+
+function shQuote(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function decodeJwtClaims(token) {
+    const parts = String(token).split('.');
+    if (parts.length !== 3) return null;
+    try {
+        const pad = parts[1].length % 4 === 0 ? '' : '='.repeat(4 - (parts[1].length % 4));
+        const normalized = parts[1].replace(/-/g, '+').replace(/_/g, '/') + pad;
+        return JSON.parse(Buffer.from(normalized, 'base64').toString('utf8'));
+    } catch {
+        return null;
+    }
+}
+
+async function toolAgentInstallCommand(args) {
+    // requireConfig throws `not_configured` if there's no active profile
+    // with a token — classifyError in server.js surfaces that cleanly.
+    const config = requireConfig();
+
+    const channel = args.channel || 'latest';
+    const script = CHANNEL_SCRIPT[channel];
+    if (!script) {
+        throw inputError(
+            `Unknown channel "${channel}". Valid channels: ${Object.keys(CHANNEL_SCRIPT).join(', ')}.`,
+        );
+    }
+
+    const scheme = args.http ? 'http' : 'https';
+    const url = `${scheme}://get.thinremote.io/${script}`;
+
+    const agentArgs = ['install', '--token', shQuote(config.token)];
+    if (args.device) agentArgs.push('--device', shQuote(args.device));
+    if (args.product) agentArgs.push('--product', shQuote(args.product));
+    if (args.overwrite) agentArgs.push('--overwrite');
+    if (args.no_start) agentArgs.push('--no-start');
+    if (args.no_verify_ssl) agentArgs.push('--no-verify-ssl');
+
+    const runner = args.sudo ? 'sudo sh' : 'sh';
+    const command = `curl -fsSL ${url} | ${runner} -s -- ${agentArgs.join(' ')}`;
+
+    // The agent's `install --token` flow decodes the JWT and requires
+    // both `svr` and `usr` claims. Permanent user tokens minted via
+    // /v1/users/{user}/tokens are missing `svr` on some server versions,
+    // which makes auto-provisioning fail with "Invalid token". Warn up
+    // front so the caller can switch to an OAuth-issued token or ask
+    // the platform for a proper provisioning token.
+    const claims = decodeJwtClaims(config.token);
+    const warnings = [];
+    if (!claims) {
+        warnings.push(
+            'The active profile token is not a decodable JWT. Auto-provisioning expects a JWT with `svr` and `usr` claims.',
+        );
+    } else {
+        if (!claims.svr) {
+            warnings.push(
+                `The profile token is missing the \`svr\` claim. The agent will reject it with "Invalid token: missing 'svr' or 'usr' claim". Re-authenticate this profile via OAuth (\`thinr\`) or generate a provisioning token from the ${config.server} console.`,
+            );
+        }
+        if (!claims.usr) {
+            warnings.push('The profile token is missing the `usr` claim.');
+        }
+    }
+
+    const sections = [
+        `Server:  ${config.server}`,
+        `User:    ${config.username}`,
+        `Channel: ${channel}`,
+        '',
+        'Run on the target host (directly or via `ssh host "<command>"`):',
+        '',
+        command,
+        '',
+        'Notes:',
+        '- The command embeds the active profile\'s API token — treat it as a credential.',
+        '- Installing the system service needs root. Pass `sudo: true` if the target host is not already root.',
+        '- The agent reads the target server from the JWT, so `--host` is not needed.',
+    ];
+
+    if (warnings.length) {
+        sections.push('', 'Warnings:', ...warnings.map((w) => `- ${w}`));
+    }
+
+    return {
+        content: [{ type: 'text', text: sections.join('\n') }],
+        isError: false,
+    };
+}
+
+export const tools = [
+    {
+        name: 'thinr_agent_install_command',
+        description:
+            "Generate a one-liner shell command that installs thinr-agent on a remote host using the active profile's token for auto-provisioning. Meant to be run on the target machine (directly or piped through `ssh`). The token is embedded verbatim, so only share the output through trusted channels.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                device: {
+                    type: 'string',
+                    description:
+                        'Custom device identifier. Omit to let the agent default to the target host\'s hostname.',
+                },
+                product: {
+                    type: 'string',
+                    description:
+                        'Product to associate the device with. Omit to auto-detect or create the default product.',
+                },
+                overwrite: {
+                    type: 'boolean',
+                    description:
+                        'Auto-overwrite an existing device with the same id on the server.',
+                },
+                no_start: {
+                    type: 'boolean',
+                    description: 'Install the service but do not start it.',
+                },
+                no_verify_ssl: {
+                    type: 'boolean',
+                    description:
+                        'Disable TLS certificate verification (for self-signed servers).',
+                },
+                channel: {
+                    type: 'string',
+                    enum: ['latest', 'main', 'develop'],
+                    description: 'Release channel. Defaults to `latest` (stable).',
+                },
+                sudo: {
+                    type: 'boolean',
+                    description:
+                        'Pipe into `sudo sh` instead of `sh`. Needed on Linux hosts when running as a non-root user, since installing the systemd service writes under /etc.',
+                },
+                http: {
+                    type: 'boolean',
+                    description:
+                        'Use http://get.thinremote.io instead of https (for devices without working HTTPS).',
+                },
+            },
+            required: [],
+        },
+        handler: toolAgentInstallCommand,
+    },
+];