@hcu-lab.me/mcp-device 1.0.0

package/dist/custom-stdio.js

@@ -0,0 +1,358 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import process from "node:process";
+/**
+ * Enhanced StdioServerTransport that wraps console output in valid JSON-RPC structures
+ * instead of filtering them out. This prevents crashes while maintaining debug visibility.
+ */
+export class FilteredStdioServerTransport extends StdioServerTransport {
+    constructor() {
+        super();
+        this.isInitialized = false;
+        this.messageBuffer = [];
+        this.clientName = 'unknown';
+        this.disableNotifications = false;
+        // Store original methods
+        this.originalConsole = {
+            log: console.log,
+            warn: console.warn,
+            error: console.error,
+            debug: console.debug,
+            info: console.info,
+        };
+        this.originalStdoutWrite = process.stdout.write;
+        // Setup console redirection
+        this.setupConsoleRedirection();
+        // Setup stdout filtering for any other output
+        this.setupStdoutFiltering();
+        // Note: We defer the initialization notification until enableNotifications() is called
+        // to ensure MCP protocol compliance - notifications must not be sent before initialization
+    }
+    /**
+     * Call this method after MCP initialization is complete to enable JSON-RPC notifications
+     */
+    enableNotifications() {
+        this.isInitialized = true;
+        // Check if notifications should be disabled based on client
+        if (this.disableNotifications) {
+            // Clear buffer without sending - just log to stderr instead
+            if (this.messageBuffer.length > 0) {
+                process.stderr.write(`[INFO] ${this.messageBuffer.length} buffered messages suppressed for ${this.clientName}\n`);
+            }
+            this.messageBuffer = [];
+            return;
+        }
+        // Send the deferred initialization notification first
+        this.sendLogNotification('info', ['Enhanced FilteredStdioServerTransport initialized']);
+        // Replay all buffered messages in chronological order
+        if (this.messageBuffer.length > 0) {
+            this.sendLogNotification('info', [`Replaying ${this.messageBuffer.length} buffered initialization messages`]);
+            this.messageBuffer
+                .sort((a, b) => a.timestamp - b.timestamp)
+                .forEach(msg => {
+                this.sendLogNotification(msg.level, msg.args);
+            });
+            // Clear the buffer
+            this.messageBuffer = [];
+        }
+        this.sendLogNotification('info', ['JSON-RPC notifications enabled']);
+    }
+    /**
+     * Configure client-specific behavior
+     * Call this BEFORE enableNotifications()
+     */
+    configureForClient(clientName) {
+        this.clientName = clientName.toLowerCase();
+        // Detect Cline and disable notifications
+        if (this.clientName.includes('cline') ||
+            this.clientName.includes('vscode') ||
+            this.clientName === 'claude-dev') {
+            this.disableNotifications = true;
+            process.stderr.write(`[INFO] MCP Device: Notifications disabled for ${clientName}\n`);
+        }
+    }
+    /**
+     * Check if notifications are enabled
+     */
+    get isNotificationsEnabled() {
+        return this.isInitialized;
+    }
+    /**
+     * Get the current count of buffered messages
+     */
+    get bufferedMessageCount() {
+        return this.messageBuffer.length;
+    }
+    setupConsoleRedirection() {
+        console.log = (...args) => {
+            if (this.isInitialized) {
+                this.sendLogNotification("info", args);
+            }
+            else {
+                // Buffer for later replay to client
+                this.messageBuffer.push({
+                    level: "info",
+                    args,
+                    timestamp: Date.now()
+                });
+            }
+        };
+        console.info = (...args) => {
+            if (this.isInitialized) {
+                this.sendLogNotification("info", args);
+            }
+            else {
+                this.messageBuffer.push({
+                    level: "info",
+                    args,
+                    timestamp: Date.now()
+                });
+            }
+        };
+        console.warn = (...args) => {
+            if (this.isInitialized) {
+                this.sendLogNotification("warning", args);
+            }
+            else {
+                this.messageBuffer.push({
+                    level: "warning",
+                    args,
+                    timestamp: Date.now()
+                });
+            }
+        };
+        console.error = (...args) => {
+            if (this.isInitialized) {
+                this.sendLogNotification("error", args);
+            }
+            else {
+                this.messageBuffer.push({
+                    level: "error",
+                    args,
+                    timestamp: Date.now()
+                });
+            }
+        };
+        console.debug = (...args) => {
+            if (this.isInitialized) {
+                this.sendLogNotification("debug", args);
+            }
+            else {
+                this.messageBuffer.push({
+                    level: "debug",
+                    args,
+                    timestamp: Date.now()
+                });
+            }
+        };
+    }
+    setupStdoutFiltering() {
+        process.stdout.write = (buffer, encoding, callback) => {
+            // Handle different call signatures
+            if (typeof buffer === 'string') {
+                const trimmed = buffer.trim();
+                // Check if this looks like a valid JSON-RPC message
+                if (trimmed.startsWith('{') && (trimmed.includes('"jsonrpc"') ||
+                    trimmed.includes('"method"') ||
+                    trimmed.includes('"id"'))) {
+                    // This looks like a valid JSON-RPC message, allow it
+                    return this.originalStdoutWrite.call(process.stdout, buffer, encoding, callback);
+                }
+                else if (trimmed.length > 0) {
+                    // Non-JSON-RPC output, wrap it in a log notification
+                    if (this.isInitialized) {
+                        this.sendLogNotification("info", [buffer.replace(/\n$/, '')]);
+                    }
+                    else {
+                        // Buffer for later replay to client
+                        this.messageBuffer.push({
+                            level: "info",
+                            args: [buffer.replace(/\n$/, '')],
+                            timestamp: Date.now()
+                        });
+                    }
+                    if (callback)
+                        callback();
+                    return true;
+                }
+            }
+            // For non-string buffers or empty strings, let them through
+            return this.originalStdoutWrite.call(process.stdout, buffer, encoding, callback);
+        };
+    }
+    sendLogNotification(level, args) {
+        // Skip if notifications are disabled (e.g., for Cline)
+        if (this.disableNotifications) {
+            return;
+        }
+        try {
+            // For data, we can send structured data or string according to MCP spec
+            let data;
+            if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null) {
+                // Single object - send as structured data
+                data = args[0];
+            }
+            else {
+                // Multiple args or primitives - convert to string
+                data = args.map(arg => {
+                    if (typeof arg === 'object') {
+                        try {
+                            return JSON.stringify(arg, null, 2);
+                        }
+                        catch {
+                            return String(arg);
+                        }
+                    }
+                    return String(arg);
+                }).join(' ');
+            }
+            const notification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: level,
+                    logger: "mcp-device",
+                    data: data
+                }
+            };
+            // Send as valid JSON-RPC notification
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(notification) + '\n');
+        }
+        catch (error) {
+            // Fallback to a simple JSON-RPC error notification if JSON serialization fails
+            const fallbackNotification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: "error",
+                    logger: "mcp-device",
+                    data: `Log serialization failed: ${args.join(' ')}`
+                }
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(fallbackNotification) + '\n');
+        }
+    }
+    /**
+     * Public method to send log notifications from anywhere in the application
+     * Now properly buffers messages before MCP initialization to avoid breaking stdio protocol
+     */
+    sendLog(level, message, data) {
+        // Skip if notifications are disabled (e.g., for Cline)
+        if (this.disableNotifications) {
+            return;
+        }
+        // Buffer messages before initialization to avoid breaking MCP protocol
+        // MCP requires client to send first message - server cannot write to stdout before that
+        if (!this.isInitialized) {
+            this.messageBuffer.push({
+                level,
+                args: [data ? { message, ...data } : message],
+                timestamp: Date.now()
+            });
+            return;
+        }
+        try {
+            const notification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: level,
+                    logger: "mcp-device",
+                    data: data ? { message, ...data } : message
+                }
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(notification) + '\n');
+        }
+        catch (error) {
+            // Fallback to basic JSON-RPC notification
+            const fallbackNotification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: "error",
+                    logger: "mcp-device",
+                    data: `sendLog failed: ${message}`
+                }
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(fallbackNotification) + '\n');
+        }
+    }
+    /**
+     * Send a progress notification (useful for long-running operations)
+     */
+    sendProgress(token, value, total) {
+        // Don't send progress before initialization - would break MCP protocol
+        if (!this.isInitialized) {
+            return;
+        }
+        try {
+            const notification = {
+                jsonrpc: "2.0",
+                method: "notifications/progress",
+                params: {
+                    progressToken: token,
+                    value: value,
+                    ...(total && { total })
+                }
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(notification) + '\n');
+        }
+        catch (error) {
+            // Fallback to basic JSON-RPC notification for progress
+            const fallbackNotification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: "info",
+                    logger: "mcp-device",
+                    data: `Progress ${token}: ${value}${total ? `/${total}` : ''}`
+                }
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(fallbackNotification) + '\n');
+        }
+    }
+    /**
+     * Send a custom notification with any method name
+     */
+    sendCustomNotification(method, params) {
+        // Don't send custom notifications before initialization - would break MCP protocol
+        if (!this.isInitialized) {
+            return;
+        }
+        try {
+            const notification = {
+                jsonrpc: "2.0",
+                method: method,
+                params: params
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(notification) + '\n');
+        }
+        catch (error) {
+            // Fallback to basic JSON-RPC notification for custom notifications
+            const fallbackNotification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: "error",
+                    logger: "mcp-device",
+                    data: `Custom notification failed: ${method}: ${JSON.stringify(params)}`
+                }
+            };
+            this.originalStdoutWrite.call(process.stdout, JSON.stringify(fallbackNotification) + '\n');
+        }
+    }
+    /**
+     * Cleanup method to restore original console methods if needed
+     */
+    cleanup() {
+        if (this.originalConsole) {
+            console.log = this.originalConsole.log;
+            console.warn = this.originalConsole.warn;
+            console.error = this.originalConsole.error;
+            console.debug = this.originalConsole.debug;
+            console.info = this.originalConsole.info;
+        }
+        if (this.originalStdoutWrite) {
+            process.stdout.write = this.originalStdoutWrite;
+        }
+    }
+}

package/dist/data/official-app-ca.pem

@@ -0,0 +1,12 @@
+-----BEGIN CERTIFICATE-----
+MIIBrzCCAVagAwIBAgIUJT4N8vTRvyxp9rlhfHuY8OOJvB4wCgYIKoZIzj0EAwIw
+JDEiMCAGA1UEAwwZTUNQIERldmljZSBBcHBsaWNhdGlvbiBDQTAeFw0yNjA5MTYx
+NDMyNDVaFw0zNjA5MTMxNDMyNDVaMCQxIjAgBgNVBAMMGU1DUCBEZXZpY2UgQXBw
+bGljYXRpb24gQ0EwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAARFvReUGN6fAVYg
+FF4UTn6F7KQ78b9yhkBU9qBy1XEMnCJqpn07rxKQszaB/ABb0awH0kIQuOUt+NA/
+7iUVeyA4o2YwZDASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjAd
+BgNVHQ4EFgQUMtlUKf+st0jgEdxhESpzROwRDW0wHwYDVR0jBBgwFoAUMtlUKf+s
+t0jgEdxhESpzROwRDW0wCgYIKoZIzj0EAwIDRwAwRAIgbjQRULWIJp+zuwOEQgVo
+9Y+3UygTogcwDkylzlR21lwCIDwbk3Vp07JVK7qBCLL9JplP8j4UWTTXVe5Oi+xJ
+japd
+-----END CERTIFICATE-----

package/dist/data/onboarding-prompts.json

@@ -0,0 +1,70 @@
+{
+  "version": "2.0.0",
+  "description": "Desktop Commander onboarding prompts - V2 simplified (5 prompts only)",
+  "prompts": [
+    {
+      "id": "onb2_01",
+      "title": "Organize my Downloads folder",
+      "description": "Clean up and organize your messy Downloads folder into relevant subfolders automatically.",
+      "prompt": "Let's organize your Downloads folder! \n\nFirst, let me check what we're working with. I'll look at your Downloads folder to see how many files are there and what types.\n\nShould I start by analyzing your Downloads folder?",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "FolderOpen",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_02",
+      "title": "Explain codebase or repository to me",
+      "description": "Analyze and explain any codebase - local project or GitHub repository - including architecture, dependencies, and how it works.",
+      "prompt": "I'll analyze and explain any codebase for you! 🔍\n\n**What should I analyze?**\n\n*Local project:* `~/work/my-project` (replace with your path)\n*GitHub repo:* `https://github.com/user/repo`\n\nI'll break down the architecture, dependencies, and how everything works together!",
+      "categories": ["onboarding"],      "secondaryTag": "Code Analysis",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "Code",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_03",
+      "title": "Create organized knowledge/documents folder",
+      "description": "Set up a well-structured knowledge base or document organization system with templates and suggested categories.",
+      "prompt": "Let's create an organized knowledge base! 📚\n\n**Where should I set it up?**\n\n*I suggest: `~/Documents/Knowledge-Base` (replace with your path) or give me a different location.*\n\nI'll create a clean folder structure with templates and organize any existing documents you have!",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "BookOpen",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_04",
+      "title": "Analyze my data file",
+      "description": "Upload or point to any data file (CSV, JSON, Excel, etc.) and get comprehensive analysis including patterns, insights, and summary reports.",
+      "prompt": "I'll help you analyze your data file! \n\nWhat's the path to your data file? (e.g., `/Users/yourname/data.csv`)\n\nOnce you give me the path, I'll start by checking what type of file it is and show you a quick preview, then we can dive deeper step by step.",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "BarChart3",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_05",
+      "title": "Check system health and resources",
+      "description": "Analyze your system's health, resource usage, running processes, and generate a comprehensive system status report.",
+      "prompt": "Let me check your system health and resources!\n\nI'll start by looking at your CPU, memory, and disk usage, then check for any performance issues.\n\nShould I begin the system analysis?",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "Activity",
+      "author": "DC team",
+      "verified": true
+    }
+  ]
+}

package/dist/device/device-state.d.ts

@@ -0,0 +1,13 @@
+export declare const DEVICE_STATE_FILES: readonly string[];
+export interface DeviceStatePaths {
+    root: string;
+    legacyRoot: string;
+    identity: string;
+    config: string;
+    status: string;
+}
+export declare function deviceStatePaths(home?: string): DeviceStatePaths;
+export declare function migrateLegacyDeviceState(paths?: DeviceStatePaths): Promise<{
+    migrated: string[];
+    legacyStateSeen: boolean;
+}>;

package/dist/device/device-state.js

@@ -0,0 +1,100 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+export const DEVICE_STATE_FILES = Object.freeze([
+    'gateway-identity.json',
+    'gateway-config.json',
+    'gateway-status.json'
+]);
+export function deviceStatePaths(home = os.homedir()) {
+    const root = path.resolve(home, '.mcp-device');
+    const legacyRoot = path.resolve(home, '.hcu-device');
+    return {
+        root,
+        legacyRoot,
+        identity: path.join(root, 'gateway-identity.json'),
+        config: path.join(root, 'gateway-config.json'),
+        status: path.join(root, 'gateway-status.json')
+    };
+}
+async function readJsonIfExists(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf8'));
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw new Error(`Invalid MCP Device state file ${filePath}: ${error?.message || error}`);
+    }
+}
+async function copyAtomic(source, target) {
+    const content = await fs.readFile(source);
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(temporary, content, { mode: 0o600, flag: 'wx' });
+    await fs.rename(temporary, target);
+    try {
+        await fs.chmod(target, 0o600);
+    }
+    catch { /* Windows ACLs inherit from the user profile. */ }
+}
+function identityFingerprint(value) {
+    if (!value)
+        return null;
+    const deviceId = String(value.deviceId || '').trim();
+    const publicKeyPem = String(value.publicKeyPem || '').trim();
+    return deviceId && publicKeyPem ? `${deviceId}\n${publicKeyPem}` : null;
+}
+export async function migrateLegacyDeviceState(paths = deviceStatePaths()) {
+    await fs.mkdir(paths.root, { recursive: true, mode: 0o700 });
+    const legacyIdentityPath = path.join(paths.legacyRoot, 'gateway-identity.json');
+    const canonicalIdentity = await readJsonIfExists(paths.identity);
+    const legacyIdentity = await readJsonIfExists(legacyIdentityPath);
+    const legacyPresence = await Promise.all(DEVICE_STATE_FILES.map(async (name) => {
+        try {
+            await fs.access(path.join(paths.legacyRoot, name));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+    const legacyStateSeen = legacyPresence.some(Boolean);
+    if (canonicalIdentity && legacyIdentity) {
+        const canonicalFingerprint = identityFingerprint(canonicalIdentity);
+        const legacyFingerprint = identityFingerprint(legacyIdentity);
+        if (!canonicalFingerprint || !legacyFingerprint || canonicalFingerprint !== legacyFingerprint) {
+            throw new Error('MCP Device migration conflict: canonical and legacy device identities differ.');
+        }
+    }
+    if (legacyStateSeen && !legacyIdentity && !canonicalIdentity) {
+        throw new Error('MCP Device migration failed closed: legacy state exists without a device identity.');
+    }
+    const migrated = [];
+    for (const name of DEVICE_STATE_FILES) {
+        const source = path.join(paths.legacyRoot, name);
+        const target = path.join(paths.root, name);
+        let sourceExists = true;
+        try {
+            await fs.access(source);
+        }
+        catch {
+            sourceExists = false;
+        }
+        if (!sourceExists)
+            continue;
+        await readJsonIfExists(source);
+        let targetExists = true;
+        try {
+            await fs.access(target);
+        }
+        catch {
+            targetExists = false;
+        }
+        if (!targetExists) {
+            await copyAtomic(source, target);
+            migrated.push(name);
+        }
+    }
+    return { migrated, legacyStateSeen };
+}

package/dist/device/device-status.d.ts

@@ -0,0 +1,81 @@
+export interface GatewayAccountStatus {
+    connected: boolean;
+    label: string | null;
+}
+export interface GatewayUsageStatus {
+    connections: number;
+    reconnects: number;
+    toolCallsStarted: number;
+    toolCallsSucceeded: number;
+    toolCallsFailed: number;
+    requestBytes: number;
+    responseBytes: number;
+    lastSeenAt: number | null;
+    lastErrorCode: string | null;
+}
+export interface GatewaySchemaStatus {
+    toolCount: number;
+    toolSchemaBytes: number;
+    toolSchemaTokenEstimate: number;
+    tokenEstimateMethod: string;
+    tokenUsageKind: 'schema_estimate_not_billing';
+}
+export interface GatewayDeviceStatus {
+    version: 1;
+    gatewayUrl: string | null;
+    deviceId: string | null;
+    deviceName: string | null;
+    identityPresent: boolean;
+    account: GatewayAccountStatus;
+    connection: {
+        online: boolean;
+        connectionEpoch: number | string | null;
+        lastConnectedAt: number | null;
+    };
+    usage: GatewayUsageStatus | null;
+    schema: GatewaySchemaStatus | null;
+    usageFreshAt: number | null;
+}
+export interface GatewayServiceStatus {
+    installed: boolean;
+    running: boolean;
+    autostart?: boolean;
+    registration?: 'task' | 'run' | 'manual' | 'stale';
+    taskName?: string | null;
+}
+export interface GatewaySecurityStatus {
+    protocolFloor: number;
+    appCaProvisioned: boolean;
+}
+export interface GatewayProxyStatus {
+    mode: 'direct' | 'configured';
+}
+export declare class GatewayDeviceStatusStore {
+    readonly statusPath: string;
+    constructor(statusPath?: string);
+    load(): Promise<GatewayDeviceStatus>;
+    update(patch: Partial<GatewayDeviceStatus>): Promise<GatewayDeviceStatus>;
+    markOffline(): Promise<GatewayDeviceStatus>;
+    clearAccount(): Promise<GatewayDeviceStatus>;
+    private persist;
+}
+export declare function effectiveGatewayStatus(status: GatewayDeviceStatus, { runtimeOwned, serviceRunning }?: {
+    runtimeOwned?: boolean | undefined;
+    serviceRunning?: boolean | undefined;
+}): GatewayDeviceStatus;
+export declare function formatGatewayStatus(status: GatewayDeviceStatus, options?: {
+    json?: boolean;
+    service?: GatewayServiceStatus;
+    security?: GatewaySecurityStatus;
+    proxy?: GatewayProxyStatus;
+    runtime?: {
+        mode: string;
+        pid: number;
+    } | null;
+    managers?: Array<{
+        manager: string;
+        installed: boolean;
+        running: boolean;
+        autostart: boolean;
+    }>;
+}): string;