@hcu-lab.me/mcp-device 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Eduard Ruzga and Desktop Commander Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# MCP Device
+
+`@hcu-lab.me/mcp-device` securely connects a user-owned computer to an authenticated Model Context Protocol gateway. The device makes the outbound connection; no inbound device port is required.
+
+The gateway owns accounts, OAuth, device ownership, MCP tool contracts, routing, and usage aggregation. MCP Device owns local device identity, pairing, reconnect lifecycle, bounded execution, background registration, and local status.
+
+## Commands
+
+```text
+mcp-device              start in the foreground
+mcp-device start        start in the foreground
+mcp-device login        explicitly link or switch the gateway account
+mcp-device logout       unlink the gateway account from this device
+mcp-device status       show runtime, manager, connection, security, proxy, usage, and schema state
+mcp-device install      pair if needed, then install and start a background runtime
+mcp-device stop         stop the current runtime without deleting identity/account state
+mcp-device uninstall    remove background registration while preserving identity/account state
+mcp-device --help       show command help
+```
+
+`md` is an alias of `mcp-device` on POSIX shells. On Windows, use `mcp-device`; bare `md` has a shell collision with built-in directory-creation commands/aliases and is not the supported invocation.
+
+On Windows, `install` uses the 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.
+
+## First run and trust
+
+The official gateway is `https://mcp-v2.hcu-lab.me/mcp`. The official package is designed to pin an independently distributed application CA and require protocol v2 before the first network connection. If that CA is absent, MCP Device fails closed rather than learning trust from the gateway it is about to contact or falling back to protocol v1.
+
+For a custom gateway, configure the gateway URL and provision its application CA through an independent trusted channel before enabling protocol v2. Proxy selection is captured during interactive provisioning and reused by the background runtime; proxy credentials are protected with Windows DPAPI on Windows.
+
+## Local state and migration
+
+Canonical state is stored under `~/.mcp-device/`. Existing `~/.hcu-device/` identity/config/status state is migrated non-destructively under serialized runtime ownership. A conflicting canonical and legacy identity fails closed rather than creating a second device identity.
+
+The device identity is Ed25519. On Windows, the private key is protected with DPAPI for the current user. The gateway stores the public identity and account ownership.
+
+## Development
+
+```powershell
+git clone https://github.com/Hiroshimeow/agent-mcp-device.git
+cd agent-mcp-device
+npm ci
+npm run build
+node dist/mcp-device.js --help
+```
+
+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
+
+The local execution engine is derived from [Desktop Commander MCP](https://github.com/wonderwhy-er/DesktopCommanderMCP). Desktop Commander is MIT licensed; its copyright and MIT license are preserved in this repository's `LICENSE`. The MCP Device product identity, gateway protocol, account/device lifecycle, security layer, and packaging are maintained separately in this repository.

package/dist/bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap.js

@@ -0,0 +1,22 @@
+/**
+ * Threadpool bootstrap. MUST be the first import in index.ts.
+ *
+ * Every fs operation (read_file, write_file, edit_block, config/history/log
+ * persistence) runs on libuv's threadpool, which defaults to only 4 threads.
+ * Under heavy parallel load — e.g. several agents reading/writing files on a
+ * slow or cloud-synced filesystem — 4 stalled operations exhaust the pool, and
+ * because a stalled syscall keeps its thread until the OS returns (a JS-level
+ * timeout does not cancel it), every subsequent fs op queues for minutes. That
+ * surfaced as multi-minute tool-call hangs under parallel `claude -p` load.
+ *
+ * Raising the pool size gives enough headroom that a burst of slow reads no
+ * longer starves the rest. libuv reads UV_THREADPOOL_SIZE only when the pool is
+ * first initialized (on first submitted work), so this assignment has to happen
+ * before ANY threadpool work — hence "first import". A user-provided value is
+ * always respected.
+ */
+const DEFAULT_THREADPOOL_SIZE = 16;
+if (!process.env.UV_THREADPOOL_SIZE) {
+    process.env.UV_THREADPOOL_SIZE = String(DEFAULT_THREADPOOL_SIZE);
+}
+export {};

package/dist/command-manager.d.ts

@@ -0,0 +1,8 @@
+declare class CommandManager {
+    getBaseCommand(command: string): string;
+    extractCommands(commandString: string): string[];
+    extractBaseCommand(commandStr: string): string | null;
+    validateCommand(command: string): Promise<boolean>;
+}
+export declare const commandManager: CommandManager;
+export {};

package/dist/command-manager.js

@@ -0,0 +1,241 @@
+import path from 'path';
+import { configManager } from './config-manager.js';
+import { capture } from "./utils/capture.js";
+class CommandManager {
+    getBaseCommand(command) {
+        return command.split(' ')[0].toLowerCase().trim();
+    }
+    extractCommands(commandString) {
+        try {
+            // Trim any leading/trailing whitespace
+            commandString = commandString.trim();
+            // Define command separators - these are the operators that can chain commands
+            const separators = [';', '&&', '||', '|', '&'];
+            // This will store our extracted commands
+            const commands = [];
+            // Split by common separators while preserving quotes
+            let inQuote = false;
+            let quoteChar = '';
+            let currentCmd = '';
+            let escaped = false;
+            for (let i = 0; i < commandString.length; i++) {
+                const char = commandString[i];
+                // Handle escape characters
+                if (char === '\\' && !escaped) {
+                    escaped = true;
+                    currentCmd += char;
+                    continue;
+                }
+                // If this character is escaped, just add it
+                if (escaped) {
+                    escaped = false;
+                    currentCmd += char;
+                    continue;
+                }
+                // Handle quotes (both single and double)
+                if ((char === '"' || char === "'") && !inQuote) {
+                    inQuote = true;
+                    quoteChar = char;
+                    currentCmd += char;
+                    continue;
+                }
+                else if (char === quoteChar && inQuote) {
+                    inQuote = false;
+                    quoteChar = '';
+                    currentCmd += char;
+                    continue;
+                }
+                // Handle $() command substitution even inside quotes (fixes blocklist bypass)
+                if (char === '$' && i + 1 < commandString.length && commandString[i + 1] === '(') {
+                    const startIndex = i;
+                    let openParens = 1;
+                    let j = i + 2; // skip past $(
+                    while (j < commandString.length && openParens > 0) {
+                        if (commandString[j] === '(')
+                            openParens++;
+                        if (commandString[j] === ')')
+                            openParens--;
+                        j++;
+                    }
+                    if (j <= commandString.length && openParens === 0) {
+                        const subContent = commandString.substring(i + 2, j - 1);
+                        const subCommands = this.extractCommands(subContent);
+                        commands.push(...subCommands);
+                        i = j - 1;
+                        if (!inQuote) {
+                            continue;
+                        }
+                        else {
+                            currentCmd += commandString.substring(startIndex, j);
+                            continue;
+                        }
+                    }
+                }
+                // Handle backtick command substitution even inside quotes
+                if (char === '`') {
+                    const startIndex = i;
+                    let j = i + 1;
+                    while (j < commandString.length && commandString[j] !== '`') {
+                        j++;
+                    }
+                    if (j < commandString.length) {
+                        const subContent = commandString.substring(i + 1, j);
+                        const subCommands = this.extractCommands(subContent);
+                        commands.push(...subCommands);
+                        i = j;
+                        if (!inQuote) {
+                            continue;
+                        }
+                        else {
+                            currentCmd += commandString.substring(startIndex, j + 1);
+                            continue;
+                        }
+                    }
+                }
+                // If we're inside quotes, just add the character
+                if (inQuote) {
+                    currentCmd += char;
+                    continue;
+                }
+                // Handle subshells - if we see an opening parenthesis, we need to find its matching closing parenthesis
+                if (char === '(') {
+                    // Find the matching closing parenthesis
+                    let openParens = 1;
+                    let j = i + 1;
+                    while (j < commandString.length && openParens > 0) {
+                        if (commandString[j] === '(')
+                            openParens++;
+                        if (commandString[j] === ')')
+                            openParens--;
+                        j++;
+                    }
+                    // Skip to after the closing parenthesis only if properly balanced
+                    if (j <= commandString.length && openParens === 0) {
+                        const subshellContent = commandString.substring(i + 1, j - 1);
+                        // Recursively extract commands from the subshell
+                        const subCommands = this.extractCommands(subshellContent);
+                        commands.push(...subCommands);
+                        // Move position past the subshell
+                        i = j - 1;
+                        continue;
+                    }
+                }
+                // Check for separators
+                let isSeparator = false;
+                for (const separator of separators) {
+                    if (commandString.startsWith(separator, i)) {
+                        // We found a separator - extract the command before it
+                        if (currentCmd.trim()) {
+                            const baseCommand = this.extractBaseCommand(currentCmd.trim());
+                            if (baseCommand)
+                                commands.push(baseCommand);
+                        }
+                        // Move past the separator
+                        i += separator.length - 1;
+                        currentCmd = '';
+                        isSeparator = true;
+                        break;
+                    }
+                }
+                if (!isSeparator) {
+                    currentCmd += char;
+                }
+            }
+            // Don't forget to add the last command
+            if (currentCmd.trim()) {
+                const baseCommand = this.extractBaseCommand(currentCmd.trim());
+                if (baseCommand)
+                    commands.push(baseCommand);
+            }
+            // Remove duplicates and return
+            return [...new Set(commands)];
+        }
+        catch (error) {
+            // If anything goes wrong, log the error but return the basic command to not break execution
+            capture('server_request_error', {
+                error: 'Error extracting commands'
+            });
+            const baseCmd = this.extractBaseCommand(commandString);
+            return baseCmd ? [baseCmd] : [];
+        }
+    }
+    // This extracts the actual command name from a command string
+    extractBaseCommand(commandStr) {
+        try {
+            // Remove environment variables (patterns like KEY=value)
+            const withoutEnvVars = commandStr.replace(/\w+=\S+\s*/g, '').trim();
+            // If nothing remains after removing env vars, return null
+            if (!withoutEnvVars)
+                return null;
+            // Get the first token (the command)
+            const tokens = withoutEnvVars.split(/\s+/);
+            let firstToken = null;
+            // Find the first valid token (skip variables)
+            for (let i = 0; i < tokens.length; i++) {
+                const token = tokens[i];
+                // Skip dollar-prefixed tokens (variables) but not $() command substitutions
+                if (token.startsWith('$') && !token.startsWith('$(')) {
+                    continue;
+                }
+                // Check if it starts with special characters like ( that might indicate it's not a regular command
+                if (token[0] === '(') {
+                    continue;
+                }
+                firstToken = token;
+                break;
+            }
+            // No valid command token found
+            if (!firstToken) {
+                return null;
+            }
+            // handle $() command substitution - extract the inner command
+            if (firstToken.startsWith('$(') && firstToken.endsWith(')')) {
+                const inner = firstToken.slice(2, -1).trim();
+                if (inner) {
+                    const innerTokens = inner.split(/\s+/);
+                    return path.basename(innerTokens[0]).toLowerCase();
+                }
+                return null;
+            }
+            // strip path prefix so /usr/bin/sudo gets caught as "sudo"
+            const baseName = path.basename(firstToken);
+            return baseName.toLowerCase();
+        }
+        catch (error) {
+            capture('Error extracting base command');
+            return null;
+        }
+    }
+    async validateCommand(command) {
+        try {
+            // Get blocked commands from config
+            const config = await configManager.getConfig();
+            const blockedCommands = config.blockedCommands || [];
+            // Extract all commands from the command string
+            const allCommands = this.extractCommands(command);
+            // If there are no commands extracted, fall back to base command
+            if (allCommands.length === 0) {
+                const baseCommand = this.getBaseCommand(command);
+                return !blockedCommands.includes(baseCommand);
+            }
+            // Check if any of the extracted commands are in the blocked list
+            for (const cmd of allCommands) {
+                if (blockedCommands.includes(cmd)) {
+                    return false; // Command is blocked
+                }
+            }
+            // No commands were blocked
+            return true;
+        }
+        catch (error) {
+            console.error('Error validating command:', error);
+            capture('server_validate_command_error', {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            // Fail closed: deny the command if validation encounters an error.
+            // This prevents a config read failure from bypassing all command filtering.
+            return false;
+        }
+    }
+}
+export const commandManager = new CommandManager();

package/dist/config-field-definitions.d.ts

@@ -0,0 +1,41 @@
+export type ConfigFieldValueType = 'string' | 'number' | 'boolean' | 'array' | 'null';
+export type ConfigFieldDefinition = {
+    label: string;
+    description: string;
+    valueType: ConfigFieldValueType;
+};
+export declare const CONFIG_FIELD_DEFINITIONS: {
+    readonly blockedCommands: {
+        readonly label: "Blocked Commands";
+        readonly description: "This is your personal safety blocklist. If a command appears here, MCP Device will refuse to run it even if a prompt asks for it. Add risky commands you never want executed by mistake.";
+        readonly valueType: "array";
+    };
+    readonly allowedDirectories: {
+        readonly label: "Allowed Folders";
+        readonly description: "These are the folders MCP Device is allowed to read and edit. Think of this as a permission list. Keeping it small is safer. If this list is empty, MCP Device can access your entire filesystem.";
+        readonly valueType: "array";
+    };
+    readonly defaultShell: {
+        readonly label: "Default Shell";
+        readonly description: "This is the shell used for new command sessions (for example /bin/bash or /bin/zsh). Only change this if you know your environment requires a specific shell.";
+        readonly valueType: "string";
+    };
+    readonly telemetryEnabled: {
+        readonly label: "Anonymous Telemetry";
+        readonly description: "When on, MCP Device sends anonymous usage information that helps improve product quality. When off, no telemetry data is sent.";
+        readonly valueType: "boolean";
+    };
+    readonly fileReadLineLimit: {
+        readonly label: "File Read Limit";
+        readonly description: "Maximum number of lines returned from a file in one read action. Lower numbers keep responses short and safer; higher numbers return more text at once.";
+        readonly valueType: "number";
+    };
+    readonly fileWriteLineLimit: {
+        readonly label: "File Write Limit";
+        readonly description: "Maximum number of lines that can be written in one edit operation. This helps prevent accidental oversized writes and keeps file changes predictable.";
+        readonly valueType: "number";
+    };
+};
+export type ConfigFieldKey = keyof typeof CONFIG_FIELD_DEFINITIONS;
+export declare const CONFIG_FIELD_KEYS: ConfigFieldKey[];
+export declare function isConfigFieldKey(value: string): value is ConfigFieldKey;

package/dist/config-field-definitions.js

@@ -0,0 +1,37 @@
+// Single source of truth for user-editable configuration fields.
+export const CONFIG_FIELD_DEFINITIONS = {
+    blockedCommands: {
+        label: 'Blocked Commands',
+        description: 'This is your personal safety blocklist. If a command appears here, MCP Device will refuse to run it even if a prompt asks for it. Add risky commands you never want executed by mistake.',
+        valueType: 'array',
+    },
+    allowedDirectories: {
+        label: 'Allowed Folders',
+        description: 'These are the folders MCP Device is allowed to read and edit. Think of this as a permission list. Keeping it small is safer. If this list is empty, MCP Device can access your entire filesystem.',
+        valueType: 'array',
+    },
+    defaultShell: {
+        label: 'Default Shell',
+        description: 'This is the shell used for new command sessions (for example /bin/bash or /bin/zsh). Only change this if you know your environment requires a specific shell.',
+        valueType: 'string',
+    },
+    telemetryEnabled: {
+        label: 'Anonymous Telemetry',
+        description: 'When on, MCP Device sends anonymous usage information that helps improve product quality. When off, no telemetry data is sent.',
+        valueType: 'boolean',
+    },
+    fileReadLineLimit: {
+        label: 'File Read Limit',
+        description: 'Maximum number of lines returned from a file in one read action. Lower numbers keep responses short and safer; higher numbers return more text at once.',
+        valueType: 'number',
+    },
+    fileWriteLineLimit: {
+        label: 'File Write Limit',
+        description: 'Maximum number of lines that can be written in one edit operation. This helps prevent accidental oversized writes and keeps file changes predictable.',
+        valueType: 'number',
+    },
+};
+export const CONFIG_FIELD_KEYS = Object.keys(CONFIG_FIELD_DEFINITIONS);
+export function isConfigFieldKey(value) {
+    return Object.prototype.hasOwnProperty.call(CONFIG_FIELD_DEFINITIONS, value);
+}

package/dist/config-manager.d.ts

@@ -0,0 +1,102 @@
+export interface ServerConfig {
+    blockedCommands?: string[];
+    defaultShell?: string;
+    allowedDirectories?: string[];
+    telemetryEnabled?: boolean;
+    fileWriteLineLimit?: number;
+    fileReadLineLimit?: number;
+    clientId?: string;
+    currentClient?: ClientInfo;
+    [key: string]: any;
+}
+export interface ClientInfo {
+    name: string;
+    version: string;
+}
+export declare function normalizeTelemetryEnabledValue(value: unknown): unknown;
+export declare function isTelemetryDisabledValue(value: unknown): boolean;
+/**
+ * Singleton config manager for the server
+ */
+declare class ConfigManager {
+    private configPath;
+    private config;
+    private initialized;
+    private _isFirstRun;
+    private writeChain;
+    private saveScheduled;
+    constructor();
+    /**
+     * Initialize configuration - load from disk or create default
+     */
+    init(): Promise<void>;
+    /**
+     * Alias for init() to maintain backward compatibility
+     */
+    loadConfig(): Promise<void>;
+    /**
+     * Create default configuration
+     */
+    private getDefaultConfig;
+    /**
+     * Write the current in-memory config to disk. All writes funnel through
+     * writeChain (see saveConfig / scheduleSave) so overlapping saves can never
+     * interleave and corrupt the file. Previously every tool call could fire its
+     * own independent fs.writeFile of the same path.
+     */
+    private writeConfigToDisk;
+    /**
+     * Awaitable save, serialized on writeChain. Use for explicit, user-driven
+     * config changes where the caller wants on-disk confirmation.
+     */
+    private saveConfig;
+    /**
+     * Non-blocking, coalesced save. Returns immediately; the write runs in the
+     * background. A burst of calls collapses to at most one queued write behind
+     * the in-flight one, so a storm of tool calls can't storm the disk — and,
+     * critically, can't pile up behind a saturated libuv threadpool and gate the
+     * tool-call response path. Used for high-frequency, non-critical persistence
+     * such as usage stats.
+     */
+    scheduleSave(): void;
+    /**
+     * Get the entire config
+     */
+    getConfig(): Promise<ServerConfig>;
+    /**
+     * Get a specific configuration value
+     */
+    getValue(key: string): Promise<any>;
+    /**
+     * Set a specific configuration value
+     */
+    setValue(key: string, value: any): Promise<void>;
+    /**
+     * Update a value in memory and persist it WITHOUT blocking the caller.
+     * The tool-call response path must never wait on a disk write: when the libuv
+     * threadpool is saturated (e.g. many parallel reads stalled on a slow/cloud
+     * filesystem) an awaited write can't get a thread and would hang the response
+     * of even pure-memory tools. The in-memory value is updated synchronously so
+     * subsequent reads see it immediately; the write is coalesced in the
+     * background. Callers needing on-disk confirmation should use setValue.
+     */
+    setValueNonBlocking(key: string, value: any): Promise<void>;
+    /**
+     * Update multiple configuration values at once
+     */
+    updateConfig(updates: Partial<ServerConfig>): Promise<ServerConfig>;
+    /**
+     * Reset configuration to defaults
+     */
+    resetConfig(): Promise<ServerConfig>;
+    /**
+     * Check if this is the first run (config file was just created)
+     */
+    isFirstRun(): boolean;
+    /**
+     * Get or create a persistent client ID for analytics and A/B tests
+     */
+    getOrCreateClientId(): Promise<string>;
+}
+export declare const configManager: ConfigManager;
+export {};