@hcu-lab.me/mcp-device 1.0.0

package/dist/device/device-status.js

@@ -0,0 +1,156 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { deviceStatePaths } from './device-state.js';
+function defaultStatusPath() {
+    return deviceStatePaths().status;
+}
+function emptyStatus() {
+    return {
+        version: 1,
+        gatewayUrl: null,
+        deviceId: null,
+        deviceName: null,
+        identityPresent: false,
+        account: { connected: false, label: null },
+        connection: { online: false, connectionEpoch: null, lastConnectedAt: null },
+        usage: null,
+        schema: null,
+        usageFreshAt: null
+    };
+}
+function sanitizedStatus(value) {
+    const base = emptyStatus();
+    if (!value || typeof value !== 'object')
+        return base;
+    const usage = value.usage && typeof value.usage === 'object' ? {
+        connections: Number(value.usage.connections || 0),
+        reconnects: Number(value.usage.reconnects || 0),
+        toolCallsStarted: Number(value.usage.toolCallsStarted || 0),
+        toolCallsSucceeded: Number(value.usage.toolCallsSucceeded || 0),
+        toolCallsFailed: Number(value.usage.toolCallsFailed || 0),
+        requestBytes: Number(value.usage.requestBytes || 0),
+        responseBytes: Number(value.usage.responseBytes || 0),
+        lastSeenAt: value.usage.lastSeenAt == null ? null : Number(value.usage.lastSeenAt),
+        lastErrorCode: value.usage.lastErrorCode ? String(value.usage.lastErrorCode).slice(0, 64) : null
+    } : null;
+    const schema = value.schema && typeof value.schema === 'object' ? {
+        toolCount: Number(value.schema.toolCount || 0),
+        toolSchemaBytes: Number(value.schema.toolSchemaBytes || 0),
+        toolSchemaTokenEstimate: Number(value.schema.toolSchemaTokenEstimate || 0),
+        tokenEstimateMethod: String(value.schema.tokenEstimateMethod || 'utf8_bytes_div_4_estimate').slice(0, 64),
+        tokenUsageKind: 'schema_estimate_not_billing'
+    } : null;
+    return {
+        version: 1,
+        gatewayUrl: value.gatewayUrl ? String(value.gatewayUrl) : null,
+        deviceId: value.deviceId ? String(value.deviceId) : null,
+        deviceName: value.deviceName ? String(value.deviceName) : null,
+        identityPresent: value.identityPresent === true,
+        account: {
+            connected: value.account?.connected === true,
+            label: value.account?.label ? String(value.account.label).slice(0, 128) : null
+        },
+        connection: {
+            online: value.connection?.online === true,
+            connectionEpoch: value.connection?.connectionEpoch ?? null,
+            lastConnectedAt: value.connection?.lastConnectedAt == null ? null : Number(value.connection.lastConnectedAt)
+        },
+        usage,
+        schema,
+        usageFreshAt: value.usageFreshAt == null ? null : Number(value.usageFreshAt)
+    };
+}
+export class GatewayDeviceStatusStore {
+    constructor(statusPath = defaultStatusPath()) {
+        this.statusPath = path.resolve(statusPath);
+    }
+    async load() {
+        try {
+            return sanitizedStatus(JSON.parse(await fs.readFile(this.statusPath, 'utf8')));
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return emptyStatus();
+            throw error;
+        }
+    }
+    async update(patch) {
+        const current = await this.load();
+        const merged = sanitizedStatus({
+            ...current,
+            ...patch,
+            account: patch.account ? { ...current.account, ...patch.account } : current.account,
+            connection: patch.connection ? { ...current.connection, ...patch.connection } : current.connection,
+            usage: patch.usage === undefined ? current.usage : patch.usage,
+            schema: patch.schema === undefined ? current.schema : patch.schema
+        });
+        await this.persist(merged);
+        return merged;
+    }
+    async markOffline() {
+        const current = await this.load();
+        return await this.update({ connection: { ...current.connection, online: false } });
+    }
+    async clearAccount() {
+        return await this.update({ account: { connected: false, label: null } });
+    }
+    async persist(status) {
+        await fs.mkdir(path.dirname(this.statusPath), { recursive: true });
+        const temporary = `${this.statusPath}.${process.pid}.${Date.now()}.tmp`;
+        await fs.writeFile(temporary, JSON.stringify(status, null, 2), { mode: 0o600 });
+        await fs.rename(temporary, this.statusPath);
+        try {
+            await fs.chmod(this.statusPath, 0o600);
+        }
+        catch { /* Windows ACL inherits from user profile. */ }
+    }
+}
+function dateText(value) {
+    if (!value)
+        return 'never';
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? 'unknown' : date.toISOString();
+}
+export function effectiveGatewayStatus(status, { runtimeOwned = false, serviceRunning = false } = {}) {
+    if (runtimeOwned || serviceRunning || !status.connection.online)
+        return status;
+    return { ...status, connection: { ...status.connection, online: false } };
+}
+function securityChannelText(status, security) {
+    if (Math.max(1, Number(security.protocolFloor) || 1) < 2)
+        return 'legacy v1';
+    return status.connection.online ? 'v2 required/active' : 'v2 required/offline';
+}
+export function formatGatewayStatus(status, options = {}) {
+    const service = options.service || { installed: false, running: false };
+    const security = options.security || { protocolFloor: 1, appCaProvisioned: false };
+    const proxy = options.proxy || { mode: 'direct' };
+    const runtime = options.runtime || null;
+    const managers = options.managers || [];
+    const securityChannel = securityChannelText(status, security);
+    const payload = { ...status, service, runtime, managers, security: { ...security, channel: securityChannel }, proxy };
+    if (options.json)
+        return JSON.stringify(payload, null, 2);
+    const accountText = status.account.connected
+        ? `connected${status.account.label ? ` (${status.account.label})` : ''}`
+        : 'not connected';
+    const usage = status.usage;
+    const schema = status.schema;
+    return [
+        `Gateway: ${status.gatewayUrl || 'not configured'}`,
+        `Device: ${status.deviceName || status.deviceId || 'unknown'}${status.deviceId ? ` (${status.deviceId})` : ''}`,
+        `Identity: ${status.identityPresent ? 'present' : 'missing'}`,
+        `Account: ${accountText}`,
+        `Connection: ${status.connection.online ? 'online' : 'offline'}; last connected ${dateText(status.connection.lastConnectedAt)}`,
+        `Runtime: ${runtime ? `${runtime.mode} (pid ${runtime.pid})` : 'not running'}`,
+        `Service: ${service.installed ? (service.running ? 'installed/running' : 'installed/stopped') : 'not installed'}`,
+        `Startup: ${service.installed ? (service.autostart ? `autostart${service.registration && service.registration !== 'manual' ? ` (${service.registration})` : ''}` : 'manual') : (service.registration === 'stale' ? 'stale registration' : 'not installed')}`,
+        ...(managers.length ? managers.map(manager => `Manager: ${manager.manager} ${manager.installed ? 'installed' : 'not-installed'}/${manager.running ? 'running' : 'stopped'}/${manager.autostart ? 'autostart' : 'manual'}`) : []),
+        `Security: ${securityChannel}; app CA ${security.appCaProvisioned ? 'provisioned' : 'not provisioned'}`,
+        `Proxy: ${proxy.mode === 'configured' ? 'configured' : 'direct'}`,
+        `Usage: calls ${usage?.toolCallsStarted ?? 0} started / ${usage?.toolCallsSucceeded ?? 0} succeeded / ${usage?.toolCallsFailed ?? 0} failed; bytes ${usage?.requestBytes ?? 0} in / ${usage?.responseBytes ?? 0} out`,
+        `Schema: ${schema?.toolCount ?? 0} tools / ${schema?.toolSchemaBytes ?? 0} bytes`,
+        `Schema token estimate: ${schema?.toolSchemaTokenEstimate ?? 0} (${schema?.tokenEstimateMethod || 'unavailable'}; not ChatGPT billing usage)`,
+        `Usage fresh at: ${dateText(status.usageFreshAt)}`
+    ].join('\n');
+}

package/dist/device/device.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { type RuntimeOwnerStatus } from './runtime-owner.js';
+export declare class MCPDevice {
+    private isShuttingDown;
+    private desktop;
+    private gatewayChannel?;
+    private gatewayProxyAgent?;
+    private runtimeOwner?;
+    constructor();
+    private setupShutdownHandlers;
+    start(options?: {
+        confirmTakeover?: (existing: RuntimeOwnerStatus) => Promise<boolean> | boolean;
+    }): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare function isModuleEntrypoint(moduleUrl: string, argvEntry?: string, pmExecPath?: string): boolean;

package/dist/device/device.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import os from 'os';
+import path from 'path';
+import { DesktopCommanderIntegration } from './execution-engine.js';
+import { GatewayDeviceChannel } from './gateway-channel.js';
+import { GatewayDeviceConfigStore, createGatewayProxyAgent } from './gateway-config.js';
+import { GatewayDeviceIdentity } from './gateway-identity.js';
+import { pairGatewayDevice } from './gateway-pairing.js';
+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 { captureRemote } from '../utils/capture.js';
+export class MCPDevice {
+    constructor() {
+        this.isShuttingDown = false;
+        this.desktop = new DesktopCommanderIntegration();
+        this.setupShutdownHandlers();
+    }
+    setupShutdownHandlers() {
+        const handleShutdown = async (signal) => {
+            if (this.isShuttingDown) {
+                console.log(`\n${signal} received, but already shutting down...`);
+                process.exit(1);
+                return;
+            }
+            console.log(`\n${signal} received, initiating graceful shutdown...`);
+            const forceExit = setTimeout(() => {
+                console.error('\n⚠️ Graceful shutdown timed out, forcing exit...');
+                process.exit(1);
+            }, 5000);
+            try {
+                await this.shutdown();
+                clearTimeout(forceExit);
+                process.exit(0);
+            }
+            catch (error) {
+                console.error('Error during shutdown:', error);
+                await captureRemote('remote_device_shutdown_handler_error', { error });
+                process.exit(1);
+            }
+        };
+        process.on('SIGINT', () => {
+            handleShutdown('SIGINT').catch((error) => {
+                console.error('Fatal error during shutdown:', error);
+                captureRemote('remote_device_shutdown_handler_error', { error, signal: 'SIGINT' }).catch(() => { });
+                process.exit(1);
+            });
+        });
+        process.on('SIGTERM', () => {
+            handleShutdown('SIGTERM').catch((error) => {
+                console.error('Fatal error during shutdown:', error);
+                captureRemote('remote_device_shutdown_handler_error', { error, signal: 'SIGTERM' }).catch(() => { });
+                process.exit(1);
+            });
+        });
+    }
+    async start(options = {}) {
+        try {
+            console.log('🚀 Starting MCP Device...');
+            if (process.env.DEBUG_MODE === 'true')
+                console.log('  - 🐞 DEBUG_MODE');
+            const managerArg = process.argv.find(value => value.startsWith('--manager='));
+            const manager = managerArg?.slice('--manager='.length);
+            const mode = process.argv.includes('--service')
+                ? (process.platform === 'win32' ? 'windows' : manager === 'pm2' ? 'pm2' : 'systemd')
+                : 'foreground';
+            this.runtimeOwner = new RuntimeOwner({ mode, onStop: () => this.shutdown() });
+            await acquireRuntimeOwner(this.runtimeOwner, { confirmTakeover: options.confirmTakeover });
+            await this.runtimeOwner.bootstrap();
+            await bootstrapOfficialGatewayTrust(new GatewayDeviceConfigStore());
+            await this.desktop.initialize();
+            const gatewayStatus = new GatewayDeviceStatusStore();
+            const storedGatewayStatus = await gatewayStatus.load();
+            const gatewayConfig = await new GatewayDeviceConfigStore().load();
+            const gatewayUrl = String(gatewayConfig.gatewayUrl || storedGatewayStatus.gatewayUrl || '').trim();
+            if (!gatewayUrl)
+                throw new Error('Gateway configuration is missing. Run `mcp-device login` or `mcp-device install` first.');
+            if (gatewayConfig.securityProtocolFloor >= 2 && !gatewayConfig.appCaPem) {
+                throw new Error('Gateway security protocol floor requires a provisioned application CA.');
+            }
+            const proxy = createGatewayProxyAgent(gatewayConfig);
+            this.gatewayProxyAgent = proxy.agent;
+            process.env.MCP_DEVICE_REMOTE = 'true';
+            console.log(`⏳ Connecting directly to MCP Gateway ${gatewayUrl}`);
+            const identity = new GatewayDeviceIdentity();
+            const identityRecord = await identity.loadOrCreate();
+            this.runtimeOwner.setDeviceId(identityRecord.deviceId);
+            const enrollmentCredential = String(process.env.MCP_GATEWAY_ENROLLMENT_TOKEN || process.env.MCP_DEVICE_ENROLLMENT_TOKEN || '').trim() || undefined;
+            let pairingGrant;
+            if (!identityRecord.enrolled && !enrollmentCredential) {
+                const pairing = await pairGatewayDevice({ gatewayUrl, identity, proxyAgent: proxy.agent, deviceName: os.hostname() });
+                pairingGrant = pairing.enrollmentGrant;
+                await gatewayStatus.update({
+                    gatewayUrl,
+                    deviceId: identityRecord.deviceId,
+                    deviceName: os.hostname(),
+                    identityPresent: true,
+                    account: { connected: false, label: pairing.account.label },
+                    connection: { ...storedGatewayStatus.connection, online: false }
+                });
+                console.log(`✓ Authorized account: ${pairing.account.label || 'connected'}`);
+            }
+            this.gatewayChannel = new GatewayDeviceChannel({
+                gatewayUrl,
+                enrollmentToken: enrollmentCredential,
+                pairingGrant,
+                identity,
+                proxyAgent: proxy.agent,
+                securityProtocolFloor: gatewayConfig.securityProtocolFloor,
+                appCaPem: gatewayConfig.appCaPem || undefined,
+                adapter: new GatewayToolAdapter(this.desktop, { allowedRoots: gatewayConfig.allowedRoots }),
+                agentVersion: process.env.npm_package_version,
+                onStatus: async (payload) => {
+                    const record = await identity.loadOrCreate();
+                    await gatewayStatus.update({
+                        gatewayUrl,
+                        deviceId: record.deviceId,
+                        deviceName: payload?.device?.name || os.hostname(),
+                        identityPresent: true,
+                        account: payload?.account || storedGatewayStatus.account,
+                        connection: {
+                            online: payload?.device?.online !== false,
+                            connectionEpoch: payload?.device?.connectionEpoch ?? null,
+                            lastConnectedAt: payload?.device?.connectedAt || Date.now()
+                        },
+                        usage: payload?.usage || null,
+                        schema: payload?.schema || null,
+                        usageFreshAt: Date.now()
+                    });
+                }
+            });
+            await this.gatewayChannel.start();
+            console.log('✓ Device ready through direct Gateway channel');
+        }
+        catch (error) {
+            console.error(' - ❌ Device startup failed:', error.message);
+            if (error.stack && process.env.DEBUG_MODE === 'true')
+                console.error('Stack trace:', error.stack);
+            await captureRemote('remote_device_startup_failed', { error });
+            await this.shutdown();
+            process.exit(1);
+        }
+    }
+    async shutdown() {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        console.log('\n🛑 Shutting down device...');
+        try {
+            if (this.gatewayChannel) {
+                console.log('  → Closing direct Gateway channel...');
+                await this.gatewayChannel.stop();
+                this.gatewayChannel = undefined;
+            }
+            if (this.gatewayProxyAgent) {
+                this.gatewayProxyAgent.destroy();
+                this.gatewayProxyAgent = undefined;
+            }
+            await new GatewayDeviceStatusStore().markOffline().catch(() => { });
+            await this.desktop.shutdown();
+            if (this.runtimeOwner) {
+                await this.runtimeOwner.release().catch(() => { });
+                this.runtimeOwner = undefined;
+            }
+            console.log('✓ Device shutdown complete');
+        }
+        catch (error) {
+            console.error('Shutdown error:', error.message);
+            await captureRemote('remote_device_shutdown_error', { error });
+        }
+    }
+}
+// Start only when this module itself is the entrypoint. Package/bin execution goes
+// through src/mcp-device.ts -> src/index.ts, which owns the single device lifecycle.
+export function isModuleEntrypoint(moduleUrl, argvEntry, pmExecPath) {
+    const moduleEntryPath = path.resolve(fileURLToPath(moduleUrl));
+    const candidates = [argvEntry, pmExecPath]
+        .map(value => value ? path.resolve(value) : '')
+        .filter(Boolean);
+    return candidates.some(candidate => process.platform === 'win32'
+        ? moduleEntryPath.toLowerCase() === candidate.toLowerCase()
+        : moduleEntryPath === candidate);
+}
+const isMainModule = isModuleEntrypoint(import.meta.url, process.argv[1], process.env.pm_exec_path);
+if (isMainModule) {
+    const device = new MCPDevice();
+    device.start();
+}

package/dist/device/execution-engine.d.ts

@@ -0,0 +1,144 @@
+interface McpConfig {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export declare class DesktopCommanderIntegration {
+    private mcpClient;
+    private mcpTransport;
+    private isReady;
+    initialize(): Promise<void>;
+    resolveMcpConfig(): Promise<McpConfig | null>;
+    callClientTool(toolName: string, args: any, metadata?: any): Promise<{
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    listClientTools(): Promise<{
+        tools: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "required" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+    }>;
+    shutdown(): Promise<void>;
+}
+export {};