@hcu-lab.me/mcp-device 1.0.3 → 1.0.5

package/README.md

@@ -21,6 +21,12 @@ mcp-device install
 mcp-device status
 ```
 
+`mcp-device login` stays terminal-only: it prints the pairing URL, user code, and QR code, and never opens a browser automatically.
+
+## Limited hosted access
+
+The public source package remains MIT licensed, but access to the hosted `device.hcu-lab.me` gateway is intentionally limited. New hosted accounts are admitted through a small, controlled supply of invite codes rather than open registration. Invite availability may be capped, paused, expired, or revoked as the service capacity and security policy change. Installing the package does not by itself grant a hosted-service account or guarantee that an invite code will be available.
+
 The hosted Pair/Help pages render their gateway URL and navigation from the deployment that served the page, so staging or custom deployments do not need a production-host rewrite. For the canonical package, `https://device.hcu-lab.me` is the default gateway; `MCP_GATEWAY_URL` is only needed when intentionally using another gateway.
 
 ## Commands
@@ -41,6 +47,12 @@ mcp-device --help       show command help
 
 On Windows, `install` uses current-user background registration. On Linux, every `install` asks whether to use `systemd --user` or an already configured PM2 installation. MCP Device does not install PM2, run `pm2 startup`, or use `sudo` automatically.
 
+## Dashboard updates
+
+Starting with MCP Device 1.0.5, an installed background device reports its package version to the authenticated gateway and can accept a per-device update requested by its owning account from the dashboard. The control is intentionally narrow: the gateway supplies only an exact stable version, and the device installs only `@hcu-lab.me/mcp-device@<version>`, verifies the installed version, then restarts through its existing Windows, systemd-user, or PM2 lifecycle.
+
+Installations older than 1.0.5 do not understand this update control. Upgrade those devices to 1.0.5 once with npm; subsequent releases can be applied from the dashboard. Offline devices remain unchanged until they are online and explicitly updated.
+
 ## First run and trust
 
 The official gateway base URL is `https://device.hcu-lab.me`. The official package pins the independently distributed application CA and requires protocol v2 before the first network connection. If that CA is absent or invalid, MCP Device fails closed instead of learning trust from the gateway it is about to contact or falling back to protocol v1.
@@ -63,6 +75,14 @@ npm run build
 node dist/mcp-device.js --help
 ```
 
+Normal development pushes do not publish npm. After reviewed development work is committed on a clean `main`, a release is intentionally created with:
+
+```powershell
+npm run release
+```
+
+That command runs the test suite, bumps the patch version, synchronizes project version files, creates the release commit and `vX.Y.Z` tag, then atomically pushes `main` and the tag. The tag-triggered GitHub Actions workflow performs the npm publish through trusted OIDC publishing. Use `npm run release:minor` or `npm run release:major` only when that version change is intentional.
+
 For a custom development gateway, set `MCP_GATEWAY_URL`. Supply `MCP_GATEWAY_APP_CA_PATH` from an independent trusted source when using protocol v2. Non-loopback plaintext gateway URLs are rejected.
 
 ## Upstream execution engine

package/dist/device/device.js

@@ -11,6 +11,7 @@ import { bootstrapOfficialGatewayTrust } from './official-trust.js';
 import { GatewayDeviceStatusStore } from './device-status.js';
 import { GatewayToolAdapter } from './gateway-tool-adapter.js';
 import { RuntimeOwner, acquireRuntimeOwner } from './runtime-owner.js';
+import { installDevicePackageUpdate, scheduleDeviceRuntimeRestart } from './self-update.js';
 import { captureRemote } from '../utils/capture.js';
 export class MCPDevice {
     constructor() {
@@ -112,6 +113,11 @@ export class MCPDevice {
                 appCaPem: gatewayConfig.appCaPem || undefined,
                 adapter: new GatewayToolAdapter(this.desktop, { allowedRoots: gatewayConfig.allowedRoots }),
                 agentVersion: process.env.npm_package_version,
+                onUpdateRequest: async (targetVersion) => {
+                    const record = await identity.loadOrCreate();
+                    await installDevicePackageUpdate(targetVersion);
+                    scheduleDeviceRuntimeRestart({ deviceId: record.deviceId });
+                },
                 onStatus: async (payload) => {
                     const record = await identity.loadOrCreate();
                     await gatewayStatus.update({

package/dist/device/gateway-channel.d.ts

@@ -12,6 +12,7 @@ export interface GatewayChannelOptions {
     adapter: GatewayToolAdapter;
     agentVersion?: string;
     onStatus?: (payload: any) => void | Promise<void>;
+    onUpdateRequest?: (targetVersion: string) => void | Promise<void>;
 }
 export declare class GatewayDeviceChannel {
     private options;
@@ -39,6 +40,7 @@ export declare class GatewayDeviceChannel {
     private sendHelloV2;
     private handleMessage;
     logoutAccount(timeoutMs?: number): Promise<any>;
+    private handleUpdateRequest;
     private handleToolCall;
     private scheduleReconnect;
     private startHeartbeat;

package/dist/device/gateway-channel.js

@@ -4,6 +4,7 @@ import { GatewayDeviceIdentity } from './gateway-identity.js';
 import { DEVICE_INNER_TLS_SUBPROTOCOL, createClientInnerTls, createJsonFrameParser, encodeJsonFrame, exportDeviceAuthKeyingMaterial } from './gateway-secure-transport.js';
 import { GATEWAY_CAPABILITIES } from './gateway-tool-adapter.js';
 import { gatewaySocketUrl } from './gateway-url-policy.js';
+import { VERSION } from '../version.js';
 const PROTOCOL_VERSION = 1;
 const PROTOCOL_VERSION_V2 = 2;
 const HEARTBEAT_MS = 20000;
@@ -138,6 +139,7 @@ export class GatewayDeviceChannel {
             timestamp: Date.now(),
             payload: {
                 agent_version: this.options.agentVersion || 'mcp-device-1',
+                package_version: VERSION,
                 hostname: os.hostname(),
                 platform: process.platform,
                 arch: process.arch,
@@ -160,6 +162,7 @@ export class GatewayDeviceChannel {
             timestamp: Date.now(),
             payload: {
                 agent_version: this.options.agentVersion || 'mcp-device-1',
+                package_version: VERSION,
                 hostname: os.hostname(),
                 platform: process.platform,
                 arch: process.arch,
@@ -173,7 +176,7 @@ export class GatewayDeviceChannel {
         const message = typeof raw === 'string' ? JSON.parse(raw) : raw;
         if (message?.protocol_version !== this.protocolVersion)
             throw new Error('Unsupported gateway protocol version');
-        if (['auth_challenge', 'auth_ok', 'tool_call'].includes(String(message?.type || ''))) {
+        if (['auth_challenge', 'auth_ok', 'tool_call', 'device_update'].includes(String(message?.type || ''))) {
             const record = await this.identity.loadOrCreate();
             if (String(message?.device_id || '') !== record.deviceId)
                 throw new Error('Gateway message device_id mismatch');
@@ -245,6 +248,14 @@ export class GatewayDeviceChannel {
             }
             return;
         }
+        if (message.type === 'device_update') {
+            if (this.connectionEpoch === undefined || this.authenticatedDeviceId === undefined)
+                throw new Error('Gateway device_update arrived before authentication');
+            if (String(message.connection_epoch) !== String(this.connectionEpoch))
+                throw new Error('Gateway device_update connection_epoch mismatch');
+            void this.handleUpdateRequest(message);
+            return;
+        }
         if (message.type !== 'tool_call')
             return;
         if (this.connectionEpoch === undefined || this.authenticatedDeviceId === undefined)
@@ -286,6 +297,41 @@ export class GatewayDeviceChannel {
             clearTimeout(timer);
         }
     }
+    async handleUpdateRequest(message) {
+        if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
+            return;
+        const requestId = String(message.request_id || '').trim();
+        const targetVersion = String(message.payload?.target_version || '').trim();
+        const sendStatus = (state, extra = {}) => {
+            try {
+                this.send({
+                    protocol_version: this.protocolVersion,
+                    type: 'device_update_status',
+                    request_id: requestId,
+                    device_id: this.authenticatedDeviceId,
+                    connection_epoch: this.connectionEpoch,
+                    timestamp: Date.now(),
+                    payload: { state, target_version: targetVersion, package_version: VERSION, ...extra }
+                });
+            }
+            catch { /* reconnect state will make the final version authoritative */ }
+        };
+        if (!requestId || !/^\d+\.\d+\.\d+$/.test(targetVersion) || typeof this.options.onUpdateRequest !== 'function') {
+            sendStatus('failed', { code: 'DEVICE_UPDATE_UNSUPPORTED', message: 'Device update request is unsupported or invalid.' });
+            return;
+        }
+        sendStatus('accepted');
+        try {
+            await this.options.onUpdateRequest(targetVersion);
+            sendStatus('installed');
+        }
+        catch (error) {
+            sendStatus('failed', {
+                code: String(error?.code || 'DEVICE_UPDATE_FAILED').slice(0, 64),
+                message: String(error?.message || error).slice(0, 240)
+            });
+        }
+    }
     async handleToolCall(message) {
         if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
             throw new Error('Gateway tool_call arrived before authentication');

package/dist/device/gateway-pairing.d.ts

@@ -16,6 +16,7 @@ export interface GatewayPairingOptions {
     deviceName?: string;
     fetchFn?: typeof fetch;
     proxyAgent?: Agent;
+    /** @deprecated Pairing is intentionally terminal-only; this hook is ignored. */
     openBrowser?: (url: string) => Promise<unknown>;
     renderQr?: (value: string) => void;
     sleep?: (ms: number) => Promise<void>;

package/dist/device/gateway-pairing.js

@@ -1,7 +1,6 @@
 import { createHash, randomBytes } from 'crypto';
 import { createRequire } from 'module';
 import os from 'os';
-import open from 'open';
 import fetch from 'cross-fetch';
 import { gatewayHttpBase } from './gateway-url-policy.js';
 const CLIENT_ID = 'mcp-device';
@@ -34,7 +33,6 @@ async function jsonResponse(response) {
 export async function pairGatewayDevice(options) {
     const baseUrl = gatewayHttpBase(options.gatewayUrl);
     const fetchFn = options.fetchFn || fetch;
-    const openBrowser = options.openBrowser || (url => open(url));
     const renderQr = options.renderQr || defaultQrRenderer;
     const sleep = options.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
     const log = options.log || (value => console.log(value));
@@ -62,10 +60,6 @@ export async function pairGatewayDevice(options) {
     log(`Pair this device: ${verificationUrl}`);
     log(`Code: ${start.user_code}`);
     renderQr(verificationUrl);
-    try {
-        await openBrowser(verificationUrl);
-    }
-    catch { /* URL + QR remain usable */ }
     const intervalMs = Math.max(1000, Math.min(30000, Number(start.interval || 2) * 1000));
     const deadline = Date.now() + Math.max(1, Number(start.expires_in || 600)) * 1000;
     while (Date.now() < deadline) {

package/dist/device/self-update.d.ts

@@ -0,0 +1,20 @@
+import { spawn as spawnCallback } from 'child_process';
+export declare const MCP_DEVICE_PACKAGE = "@hcu-lab.me/mcp-device";
+export declare function normalizeUpdateVersion(value: string): string;
+export declare function installDevicePackageUpdate(targetVersion: string, options?: {
+    platform?: NodeJS.Platform | string;
+    execFile?: (file: string, args: string[]) => Promise<{
+        stdout?: string;
+        stderr?: string;
+    }>;
+    npmPath?: string;
+}): Promise<string>;
+export declare function buildWindowsRestartHelper(deviceId: string, currentPid?: number): string;
+export declare function scheduleDeviceRuntimeRestart(options: {
+    deviceId: string;
+    platform?: NodeJS.Platform | string;
+    argv?: string[];
+    delayMs?: number;
+    spawn?: typeof spawnCallback;
+    exit?: (code?: number) => never | void;
+}): void;

package/dist/device/self-update.js

@@ -0,0 +1,87 @@
+import { execFile as execFileCallback, spawn as spawnCallback } from 'child_process';
+import path from 'path';
+import { promisify } from 'util';
+import { deviceStatePaths } from './device-state.js';
+import { buildWindowsTaskName } from './windows-service.js';
+const execFileAsync = promisify(execFileCallback);
+export const MCP_DEVICE_PACKAGE = '@hcu-lab.me/mcp-device';
+export function normalizeUpdateVersion(value) {
+    const version = String(value || '').trim();
+    if (!/^\d+\.\d+\.\d+$/.test(version))
+        throw new Error('Update target must be an exact stable semantic version.');
+    return version;
+}
+export async function installDevicePackageUpdate(targetVersion, options = {}) {
+    const version = normalizeUpdateVersion(targetVersion);
+    const platform = options.platform || process.platform;
+    const execFile = options.execFile || (async (file, args) => {
+        const result = await execFileAsync(file, args, { windowsHide: true, encoding: 'utf8' });
+        return { stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
+    });
+    const npmPath = options.npmPath || (platform === 'win32' ? 'npm.cmd' : 'npm');
+    await execFile(npmPath, ['install', '-g', `${MCP_DEVICE_PACKAGE}@${version}`, '--no-audit', '--no-fund']);
+    const listed = await execFile(npmPath, ['list', '-g', MCP_DEVICE_PACKAGE, '--depth=0', '--json']);
+    let actual = '';
+    try {
+        actual = String(JSON.parse(String(listed.stdout || '{}'))?.dependencies?.[MCP_DEVICE_PACKAGE]?.version || '');
+    }
+    catch {
+        throw new Error('Updated package version could not be verified.');
+    }
+    if (actual !== version)
+        throw new Error(`Updated package verification failed: expected ${version}, got ${actual || 'unknown'}.`);
+    return actual;
+}
+function serviceManager(argv) {
+    const value = argv.find(item => String(item).startsWith('--manager='));
+    return value ? String(value).slice('--manager='.length).trim().toLowerCase() : '';
+}
+export function buildWindowsRestartHelper(deviceId, currentPid = process.pid) {
+    const runnerPath = path.join(deviceStatePaths().root, 'run-device.ps1');
+    const taskName = buildWindowsTaskName(deviceId);
+    const psQuote = (value) => `'${String(value).replace(/'/g, "''")}'`;
+    return [
+        `$oldPid = ${Number(currentPid)}`,
+        'for ($i = 0; $i -lt 80; $i++) {',
+        "  if (-not (Get-Process -Id $oldPid -ErrorAction SilentlyContinue)) { break }",
+        '  Start-Sleep -Milliseconds 250',
+        '}',
+        `$taskName = ${psQuote(taskName)}`,
+        `$runner = ${psQuote(runnerPath)}`,
+        'if (Get-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue) {',
+        '  Start-ScheduledTask -TaskName $taskName',
+        '} else {',
+        "  Start-Process -FilePath 'powershell.exe' -ArgumentList @('-NoProfile','-ExecutionPolicy','Bypass','-WindowStyle','Hidden','-File',$runner) -WindowStyle Hidden",
+        '}'
+    ].join('; ');
+}
+export function scheduleDeviceRuntimeRestart(options) {
+    const platform = options.platform || process.platform;
+    const argv = options.argv || process.argv;
+    const delayMs = Math.max(100, Number(options.delayMs ?? 700));
+    const exit = options.exit || process.exit;
+    if (!argv.includes('--service'))
+        throw new Error('Dashboard updates require an installed background MCP Device service.');
+    if (platform === 'linux') {
+        const manager = serviceManager(argv);
+        if (!['systemd', 'pm2'].includes(manager))
+            throw new Error('Linux dashboard update requires systemd or PM2 service ownership.');
+        const timer = setTimeout(() => exit(75), delayMs);
+        timer.unref?.();
+        return;
+    }
+    if (platform === 'win32') {
+        const spawn = options.spawn || spawnCallback;
+        const helper = buildWindowsRestartHelper(options.deviceId);
+        const child = spawn('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden', '-Command', helper], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true
+        });
+        child.unref();
+        const timer = setTimeout(() => exit(0), delayMs);
+        timer.unref?.();
+        return;
+    }
+    throw new Error('Dashboard self-update is supported only on installed Windows and Linux devices.');
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.0.3";
+export declare const VERSION = "1.0.5";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '1.0.3';
+export const VERSION = '1.0.5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcu-lab.me/mcp-device",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP Device securely connects a user-owned computer to an authenticated Model Context Protocol gateway.",
   "license": "MIT",
   "author": "Hirohimeow",
@@ -26,6 +26,10 @@
     "device:start": "tsx src/device/device.ts",
     "device:start:dev": "nodemon --watch src/device --exec tsx src/device/device.ts",
     "sync-version": "node scripts/sync-version.js",
+    "version": "node scripts/sync-version.js && git add server.json src/version.ts package-lock.json",
+    "release": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major",
     "bump": "node scripts/sync-version.js --bump",
     "bump:minor": "node scripts/sync-version.js --bump --minor",
     "bump:major": "node scripts/sync-version.js --bump --major",