@thinremote/thinr-cli 1.0.2 → 1.1.0-alpha.2

package/lib/device-api.js

@@ -0,0 +1,257 @@
+import api from './api.js';
+import { requireConfig } from './config.js';
+import WebSocket from 'ws';
+import { randomUUID } from 'crypto';
+
+/**
+ * Create a device API client for filesystem and command operations
+ * @param {string} deviceId - The device ID
+ * @param {Object} [options] - Options
+ * @param {string} [options.user] - Override API user (admin impersonation)
+ * @returns {Object} API client with fs and exec methods
+ */
+export function createDeviceAPI(deviceId, options = {}) {
+    const config = requireConfig();
+    const apiUser = options.user || config.username;
+    const resourcePath = `/v3/users/${apiUser}/devices/${deviceId}/resources`;
+    const filesPath = `/v3/users/${apiUser}/devices/${deviceId}/files`;
+
+    /**
+     * Call a device resource (for cmd, etc.)
+     */
+    async function callResource(resource, payload = null, opts = {}) {
+        const url = `${resourcePath}/${resource}`;
+        const response = await api.post(url, payload, {
+            responseType: opts.responseType || 'json',
+            params: opts.params || {},
+            headers: opts.headers || {},
+            timeout: opts.timeout || 30000,
+        });
+        return response;
+    }
+
+    return {
+        /**
+         * List directory contents
+         * GET /v3/users/{user}/devices/{device}/files/{path}/
+         */
+        async listDir(dirPath, includeHidden = false) {
+            const normalized = dirPath.endsWith('/') ? dirPath : dirPath + '/';
+            const params = {};
+            if (includeHidden) params.hidden = true;
+            const response = await api.get(`${filesPath}${normalized}`, { params });
+            return response.data;
+        },
+
+        /**
+         * Read file contents
+         * GET /v3/users/{user}/devices/{device}/files/{path}
+         */
+        async readFile(filePath) {
+            const response = await api.get(`${filesPath}${filePath}`, {
+                responseType: 'arraybuffer',
+            });
+            return Buffer.from(response.data);
+        },
+
+        /**
+         * Write file contents
+         * PUT /v3/users/{user}/devices/{device}/files/{path}
+         */
+        async writeFile(filePath, content, overwrite = true) {
+            const params = {};
+            if (!overwrite) params.overwrite = false;
+            const response = await api.put(`${filesPath}${filePath}`, content, {
+                headers: { 'Content-Type': 'application/octet-stream' },
+                params,
+            });
+            return response.data;
+        },
+
+        /**
+         * Get file/directory info
+         * GET /v3/users/{user}/devices/{device}/files/{path}?info=true
+         */
+        async info(filePath) {
+            const response = await api.get(`${filesPath}${filePath}`, {
+                params: { info: true },
+            });
+            return response.data;
+        },
+
+        /**
+         * Delete file or directory
+         * DELETE /v3/users/{user}/devices/{device}/files/{path}
+         */
+        async delete(filePath, recursive = true) {
+            const params = {};
+            if (recursive) params.recursive = true;
+            const response = await api.delete(`${filesPath}${filePath}`, { params });
+            return response.data;
+        },
+
+        /**
+         * Move/rename file or directory
+         * PATCH /v3/users/{user}/devices/{device}/files/{sourcePath}
+         */
+        async move(source, destination, overwrite = false) {
+            const response = await api.patch(`${filesPath}${source}`, {
+                path: destination,
+                overwrite,
+            });
+            return response.data;
+        },
+
+        /**
+         * Create directory
+         * PUT /v3/users/{user}/devices/{device}/files/{path}/
+         */
+        async mkdir(dirPath) {
+            const normalized = dirPath.endsWith('/') ? dirPath : dirPath + '/';
+            const response = await api.put(`${filesPath}${normalized}`, null, {
+                headers: { 'Content-Length': '0' },
+            });
+            return response.data;
+        },
+
+        /**
+         * Read a device resource property (GET)
+         * GET /v3/users/{user}/devices/{device}/resources/{resource}
+         */
+        async getResource(resource) {
+            const url = `${resourcePath}/${resource}`;
+            const response = await api.get(url, { timeout: 15000 });
+            return response.data;
+        },
+
+        /**
+         * Call a device resource action (POST)
+         * POST /v3/users/{user}/devices/{device}/resources/{resource}
+         */
+        async callResource(resource, payload = null, { timeout = 30000 } = {}) {
+            const url = `${resourcePath}/${resource}`;
+            const response = await api.post(url, payload, { timeout });
+            return response.data;
+        },
+
+        /**
+         * Execute a command on the device
+         * POST /v3/users/{user}/devices/{device}/resources/cmd
+         */
+        async exec(cmd, timeout = 30) {
+            const response = await callResource(
+                'cmd',
+                {
+                    cmd,
+                    timeout,
+                    mode: 'api',
+                },
+                { timeout: (timeout + 5) * 1000 },
+            );
+            return response.data;
+        },
+
+        /**
+         * Execute a command on the device using the WebSocket stream. Incoming
+         * frames are dispatched to onStdout/onStderr as they arrive. Resolves
+         * with { exitCode, timedOut } when the remote command completes or the
+         * connection closes. Returns a `cancel()` function via the optional
+         * onCancel hook so callers (e.g. SIGINT handlers) can tear it down.
+         *
+         * Preferred path for the CLI: the server detects WS close and stops
+         * the device-side stream automatically.
+         */
+        execStream(cmd, { timeout = 0, onStdout, onStderr, onCancel, stdin } = {}) {
+            const sessionId = randomUUID();
+            const resource = `$cmd/${sessionId}`;
+            const params = new URLSearchParams({ cmd });
+            if (timeout > 0) params.set('timeout', String(timeout));
+            const isLocal = config.server === 'localhost' || config.server === '127.0.0.1';
+            const insecure = isLocal || process.env.THINR_INSECURE === '1';
+            const wsUrl = `wss://${config.server}/v3/users/${apiUser}/devices/${deviceId}/resources/${resource}?${params}`;
+            const ws = new WebSocket(wsUrl, {
+                headers: { Authorization: `Bearer ${config.token}` },
+                rejectUnauthorized: !insecure,
+            });
+
+            let exitCode = null;
+            let timedOut = false;
+            let cancelled = false;
+
+            const cancel = () => {
+                cancelled = true;
+                if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                    ws.close();
+                }
+            };
+            onCancel?.(cancel);
+
+            const decodeBytes = (field) => {
+                if (typeof field === 'string') return field;
+                if (field && Array.isArray(field.bytes)) {
+                    return Buffer.from(field.bytes).toString('utf8');
+                }
+                return '';
+            };
+
+            return new Promise((resolve, reject) => {
+                let resolved = false;
+                const done = () => {
+                    if (resolved) return;
+                    resolved = true;
+                    resolve({ exitCode, timedOut, cancelled });
+                    // Tear down the socket without blocking on the server's
+                    // close handshake.
+                    if (
+                        ws.readyState === WebSocket.OPEN ||
+                        ws.readyState === WebSocket.CONNECTING
+                    ) {
+                        ws.terminate();
+                    }
+                };
+
+                ws.on('open', () => {
+                    // If the caller supplied a stdin stream, forward each
+                    // chunk to the device as a stream frame. Payload is sent
+                    // as a UTF-8 string under the standard {resource, payload}
+                    // envelope that the server's stream handler expects.
+                    if (stdin && typeof stdin.on === 'function') {
+                        stdin.on('data', (chunk) => {
+                            if (ws.readyState !== WebSocket.OPEN) return;
+                            const text = Buffer.isBuffer(chunk)
+                                ? chunk.toString('utf8')
+                                : String(chunk);
+                            ws.send(JSON.stringify({ resource, payload: text }));
+                        });
+                    }
+                });
+                ws.on('error', (err) => {
+                    if (cancelled) return;
+                    reject(err);
+                });
+                ws.on('message', (raw) => {
+                    let evt;
+                    try {
+                        evt = JSON.parse(raw.toString('utf8'));
+                    } catch {
+                        return;
+                    }
+                    if (evt.signal && evt.signal !== 'data') return;
+                    const p = evt.payload;
+                    if (!p || typeof p !== 'object') return;
+                    if (p.out !== undefined) onStdout?.(decodeBytes(p.out));
+                    else if (p.err !== undefined) onStderr?.(decodeBytes(p.err));
+                    else if (typeof p.exit === 'number') {
+                        exitCode = p.exit;
+                        if (p.timeout === true) timedOut = true;
+                        // We have the full result — resolve immediately and
+                        // tear down the WS without waiting for the server's
+                        // stop cascade, which can add several seconds.
+                        done();
+                    }
+                });
+                ws.on('close', () => done());
+            });
+        },
+    };
+}

package/lib/devices.js

@@ -0,0 +1,69 @@
+import { requireConfig } from './config.js';
+import api from './api.js';
+import { apiError } from './errors.js';
+
+/**
+ * Get devices belonging to a product
+ * @param {Object} filter - Filters to query devices
+ * @return {Promise<Array>} List of devices
+ */
+export async function getDevices(filter, user = null) {
+    const config = requireConfig();
+    const apiUser = user || config.username;
+    let devices = [];
+
+    let queryParametersString = '';
+    for (const [key, value] of Object.entries(filter)) {
+        if (value) queryParametersString += key + '=' + value + '&';
+    }
+
+    try {
+        const count = 50;
+        const url = `/v1/users/${apiUser}/devices?count=${count}&${queryParametersString}`;
+        let index = 0;
+        let res_length = 0;
+
+        do {
+            const response = await api.get(`${url}index=${index}`);
+            res_length = response.data.length;
+            index += res_length;
+            devices = devices.concat(response.data);
+        } while (res_length === count);
+
+        return devices;
+    } catch (error) {
+        const product = filter && filter.productId;
+        const notFound = product ? `Product not found: ${product}` : 'Devices not found';
+        throw apiError(error, { notFound });
+    }
+}
+
+/**
+ * Fetch a single device record (metadata only — assigned product,
+ * description, asset group, connection state, …). Use this when you
+ * need the side-channel info that doesn't come from the device's own
+ * agent (system_info, monitoring, …) but from the server's record.
+ *
+ * @param {string} deviceId
+ * @param {string} [user]  Admin impersonation; defaults to the active profile.
+ * @returns {Promise<Object>} Raw API record.
+ */
+export async function getDevice(deviceId, user = null) {
+    const config = requireConfig();
+    const apiUser = user || config.username;
+    try {
+        const response = await api.get(`/v1/users/${apiUser}/devices/${deviceId}`);
+        return response.data || {};
+    } catch (error) {
+        throw apiError(error, { notFound: `Device not found: ${deviceId}` });
+    }
+}
+
+/**
+ * Filter active devices from a list of devices
+ * @param {Array} devices - List of devices to filter
+ * @return {Array} List of active devices
+ */
+export function filterActiveDevices(devices) {
+    return devices.filter((device) => device.connection && device.connection.active === true);
+}

package/lib/errors.js

@@ -0,0 +1,53 @@
+/**
+ * Normalize an axios / fetch-style error into a single Error with a stable
+ * `.code` and `.status`. Replaces the repeated if-response/if-request
+ * blocks in status.js / property.js / resource.js / device.js.
+ *
+ * Pass `messages.notFound` to override the 404 message with something
+ * that names the missing entity (e.g. "Device not found: abc").
+ */
+export function apiError(error, messages = {}) {
+    if (error && error.response) {
+        const status = error.response.status;
+        if (status === 404) {
+            const err = new Error(messages.notFound || 'Not found');
+            err.code = 'not_found';
+            err.status = 404;
+            return err;
+        }
+        if (status === 401 || status === 403) {
+            const err = new Error(
+                messages.unauthorized ||
+                    'Unauthorized. Your token may have expired. Please reconfigure.',
+            );
+            err.code = 'unauthorized';
+            err.status = status;
+            return err;
+        }
+        const err = new Error(`Server error: ${status} ${error.response.statusText || ''}`.trim());
+        err.code = 'server_error';
+        err.status = status;
+        return err;
+    }
+    if (error && error.request) {
+        const err = new Error('No response from server. Please check your connection.');
+        err.code = 'network_error';
+        return err;
+    }
+    const err = new Error(error?.message || String(error));
+    err.code = 'error';
+    return err;
+}
+
+/**
+ * Pre-tagged error for invalid / missing user input (CLI option,
+ * MCP tool argument, …). Picked up by `classifyError` so it surfaces
+ * as `code: 'input_error'` in both the CLI JSON envelope and the
+ * MCP error metadata, matching the same code the CLI's `printErr`
+ * uses for argument validation failures.
+ */
+export function inputError(message) {
+    const err = new Error(message);
+    err.code = 'input_error';
+    return err;
+}

package/lib/mcp/helpers.js

@@ -0,0 +1,34 @@
+// @ts-check
+import { createDeviceAPI } from '../device-api.js';
+import { getActiveProfile, getProfile, setActiveProfile } from '../config.js';
+import { setBaseURL } from '../api.js';
+import { inputError } from '../errors.js';
+
+/** Build a device-scoped API client. Tools must always pass `device`
+ *  explicitly — the server has no per-session default. */
+export function getAPI(device, user) {
+    if (!device)
+        throw inputError('device is required. Use thinr_devices to list available devices.');
+    return { api: createDeviceAPI(device, { user: user || undefined }), device };
+}
+
+/** Run `fn` with the active profile temporarily switched to `profile`
+ *  (when supplied) so callers can target any configured environment per
+ *  tool call without persisting the change. */
+export async function withProfile(profile, fn) {
+    if (!profile) return fn();
+    const previous = getActiveProfile();
+    const target = getProfile(profile);
+    if (!target) {
+        throw inputError(`Unknown profile: ${profile}. Use thinr_profiles to list available ones.`);
+    }
+    setActiveProfile(profile);
+    if (target.server) setBaseURL(`https://${target.server}`);
+    try {
+        return await fn();
+    } finally {
+        setActiveProfile(previous);
+        const restore = previous ? getProfile(previous) : null;
+        if (restore?.server) setBaseURL(`https://${restore.server}`);
+    }
+}

package/lib/mcp/registry.js

@@ -0,0 +1,32 @@
+// @ts-check
+import { tools as devicesTools } from './tools-devices.js';
+import { tools as filesystemTools } from './tools-filesystem.js';
+import { tools as execTools } from './tools-exec.js';
+import { tools as resourcesTools } from './tools-resources.js';
+import { tools as propertiesTools } from './tools-properties.js';
+import { tools as scriptsTools } from './tools-scripts.js';
+import { tools as productsTools } from './tools-products.js';
+import { tools as profilesTools } from './tools-profiles.js';
+
+export const tools = [
+    ...devicesTools,
+    ...filesystemTools,
+    ...execTools,
+    ...resourcesTools,
+    ...propertiesTools,
+    ...scriptsTools,
+    ...productsTools,
+    ...profilesTools,
+];
+
+// Inject the optional `profile` parameter on every tool so callers can
+// target any configured environment per-call without changing the saved
+// default. `thinr_profiles` is the lookup itself, so it's exempt.
+for (const t of tools) {
+    if (t.name === 'thinr_profiles') continue;
+    t.inputSchema.properties = t.inputSchema.properties || {};
+    t.inputSchema.properties.profile = {
+        type: 'string',
+        description: 'CLI profile to use for this call (see thinr_profiles). Omit for the default.',
+    };
+}

package/lib/mcp/server.js

@@ -0,0 +1,67 @@
+// @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 { readConfig } from '../config.js';
+import { setBaseURL } from '../api.js';
+import { classifyError } from '../output.js';
+import { tools } from './registry.js';
+import { withProfile } from './helpers.js';
+
+/**
+ * Start a generic MCP server for ThinRemote.
+ * All tools accept device (when relevant) plus optional user/profile parameters.
+ *
+ * @param {{ version?: string }} [opts] `version` is echoed back in the
+ *   MCP `initialize` response's `serverInfo.version`. Caller is expected
+ *   to pass the CLI's `package.json#version` so the two never drift.
+ */
+export async function startMCPServer({ version = 'unknown' } = {}) {
+    const config = readConfig();
+    if (config.server) {
+        setBaseURL(`https://${config.server}`);
+    }
+
+    const server = new Server(
+        {
+            name: 'thinr',
+            version,
+        },
+        {
+            capabilities: { tools: {} },
+        },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map(({ handler: _handler, ...t }) => t),
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = request.params.arguments || {};
+        const tool = tools.find((t) => t.name === name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        try {
+            return await withProfile(args.profile, () => tool.handler(args));
+        } catch (error) {
+            // Surface the same {message, code} pair the CLI emits in JSON
+            // mode so MCP clients can pattern-match on `[code]` instead of
+            // doing fuzzy matches on the human message.
+            const { message, code } = classifyError(error);
+            return {
+                content: [{ type: 'text', text: `Error [${code}]: ${message}` }],
+                isError: true,
+                _meta: { code, message },
+            };
+        }
+    });
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[thinr-mcp] Server started');
+}