@hcu-lab.me/mcp-device 1.0.0

package/dist/utils/logger.js

@@ -0,0 +1,72 @@
+/**
+ * Centralized logging utility for MCP Device
+ * Ensures all logging goes through proper channels based on initialization state
+ */
+/**
+ * Log a message using the appropriate method based on MCP initialization state
+ */
+export function log(level, message, data) {
+    try {
+        // Check if MCP transport is available
+        if (global.mcpTransport) {
+            // Always use MCP logging (will buffer if not initialized yet)
+            global.mcpTransport.sendLog(level, message, data);
+        }
+        else {
+            // This should rarely happen, but fallback to create a JSON-RPC notification manually
+            const notification = {
+                jsonrpc: "2.0",
+                method: "notifications/message",
+                params: {
+                    level: level,
+                    logger: "mcp-device",
+                    data: data ? { message, ...data } : message
+                }
+            };
+            process.stdout.write(JSON.stringify(notification) + '\n');
+        }
+    }
+    catch (error) {
+        // Ultimate fallback - but this should be JSON-RPC too
+        const notification = {
+            jsonrpc: "2.0",
+            method: "notifications/message",
+            params: {
+                level: "error",
+                logger: "mcp-device",
+                data: `[LOG-ERROR] Failed to log message: ${message}`
+            }
+        };
+        process.stdout.write(JSON.stringify(notification) + '\n');
+    }
+}
+/**
+ * Convenience functions for different log levels
+ */
+export const logger = {
+    emergency: (message, data) => log('emergency', message, data),
+    alert: (message, data) => log('alert', message, data),
+    critical: (message, data) => log('critical', message, data),
+    error: (message, data) => log('error', message, data),
+    warning: (message, data) => log('warning', message, data),
+    notice: (message, data) => log('notice', message, data),
+    info: (message, data) => log('info', message, data),
+    debug: (message, data) => log('debug', message, data),
+};
+/**
+ * Log to stderr during early initialization (before MCP is ready)
+ * Use this for critical startup messages that must be visible
+ * NOTE: This should also be JSON-RPC format
+ */
+export function logToStderr(level, message) {
+    const notification = {
+        jsonrpc: "2.0",
+        method: "notifications/message",
+        params: {
+            level: level,
+            logger: "mcp-device",
+            data: message
+        }
+    };
+    process.stdout.write(JSON.stringify(notification) + '\n');
+}

package/dist/utils/mcp-ui-ab-test.d.ts

@@ -0,0 +1,13 @@
+export declare const MCP_UI_EXPERIMENT_NAME = "McpUiPreviews";
+export declare const MCP_UI_SHOW_VARIANT = "showMCPUi";
+export declare const MCP_UI_HIDE_VARIANT = "notShowMCPUi";
+export interface McpUiPreviewDecisionDeps {
+    getExistingAssignment: () => Promise<unknown>;
+    isFirstRun: () => boolean;
+    wasLoadedFromCache: () => boolean;
+    waitForFreshFlags: () => Promise<void>;
+    getABTestVariant: (experimentName: string) => Promise<string | null>;
+    capture: (event: string, properties?: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+export declare function resolveMcpUiPreviewDecision(deps: McpUiPreviewDecisionDeps): Promise<boolean>;
+export declare function shouldShowMcpUiPreviews(): Promise<boolean>;

package/dist/utils/mcp-ui-ab-test.js

@@ -0,0 +1,62 @@
+import { configManager } from '../config-manager.js';
+import { getABTestVariant } from './ab-test.js';
+import { capture } from './capture.js';
+import { featureFlagManager } from './feature-flags.js';
+export const MCP_UI_EXPERIMENT_NAME = 'McpUiPreviews';
+export const MCP_UI_SHOW_VARIANT = 'showMCPUi';
+export const MCP_UI_HIDE_VARIANT = 'notShowMCPUi';
+function variantEnablesMcpUi(variant) {
+    if (variant === MCP_UI_HIDE_VARIANT)
+        return false;
+    if (variant === MCP_UI_SHOW_VARIANT)
+        return true;
+    return null;
+}
+export async function resolveMcpUiPreviewDecision(deps) {
+    try {
+        const existingAssignment = await deps.getExistingAssignment();
+        const existingDecision = variantEnablesMcpUi(existingAssignment);
+        if (existingDecision !== null) {
+            if (!deps.wasLoadedFromCache()) {
+                await deps.waitForFreshFlags();
+            }
+            const currentVariant = await deps.getABTestVariant(MCP_UI_EXPERIMENT_NAME);
+            return variantEnablesMcpUi(currentVariant) ?? existingDecision;
+        }
+        if (!deps.isFirstRun()) {
+            return true;
+        }
+        if (!deps.wasLoadedFromCache()) {
+            await deps.waitForFreshFlags();
+        }
+        const variant = await deps.getABTestVariant(MCP_UI_EXPERIMENT_NAME);
+        const decision = variantEnablesMcpUi(variant);
+        if (decision === null) {
+            return true;
+        }
+        try {
+            await deps.capture('server_mcp_ui_ab_decision', {
+                experiment: MCP_UI_EXPERIMENT_NAME,
+                variant,
+                mcp_ui_enabled: decision,
+            });
+        }
+        catch {
+            // Telemetry must not change the assigned product experience.
+        }
+        return decision;
+    }
+    catch {
+        return true;
+    }
+}
+export async function shouldShowMcpUiPreviews() {
+    return resolveMcpUiPreviewDecision({
+        getExistingAssignment: () => configManager.getValue(`abTest_${MCP_UI_EXPERIMENT_NAME}`),
+        isFirstRun: () => configManager.isFirstRun(),
+        wasLoadedFromCache: () => featureFlagManager.wasLoadedFromCache(),
+        waitForFreshFlags: () => featureFlagManager.waitForFreshFlags(),
+        getABTestVariant,
+        capture,
+    });
+}

package/dist/utils/open-browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Open a URL in the default browser (cross-platform)
+ * Uses execFile/spawn with args array to avoid shell injection
+ */
+export declare function openBrowser(url: string): Promise<void>;
+/**
+ * Open the MCP Device project page.
+ */
+export declare function openWelcomePage(_clientName?: string): Promise<void>;

package/dist/utils/open-browser.js

@@ -0,0 +1,42 @@
+import { execFile, spawn } from 'child_process';
+import os from 'os';
+import { logToStderr } from './logger.js';
+/**
+ * Open a URL in the default browser (cross-platform)
+ * Uses execFile/spawn with args array to avoid shell injection
+ */
+export async function openBrowser(url) {
+    const platform = os.platform();
+    return new Promise((resolve, reject) => {
+        const callback = (error) => {
+            if (error) {
+                logToStderr('error', `Failed to open browser: ${error.message}`);
+                reject(error);
+            }
+            else {
+                logToStderr('info', `Opened browser to: ${url}`);
+                resolve();
+            }
+        };
+        switch (platform) {
+            case 'darwin':
+                execFile('open', [url], callback);
+                break;
+            case 'win32':
+                // Windows 'start' is a shell builtin, use spawn with shell but pass URL as separate arg
+                spawn('cmd', ['/c', 'start', '', url], { shell: false, windowsHide: true }).on('close', (code) => {
+                    code === 0 ? resolve() : reject(new Error(`Exit code ${code}`));
+                });
+                break;
+            default:
+                execFile('xdg-open', [url], callback);
+                break;
+        }
+    });
+}
+/**
+ * Open the MCP Device project page.
+ */
+export async function openWelcomePage(_clientName) {
+    await openBrowser('https://github.com/Hiroshimeow/agent-mcp-device#readme');
+}

package/dist/utils/process-detection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * REPL and Process State Detection Utilities
+ * Detects when processes are waiting for input vs finished vs running
+ */
+export interface ProcessState {
+    isWaitingForInput: boolean;
+    isFinished: boolean;
+    isRunning: boolean;
+    detectedPrompt?: string;
+    lastOutput: string;
+}
+/**
+ * Analyze process output to determine current state
+ */
+export declare function analyzeProcessState(output: string, pid?: number): ProcessState;
+/**
+ * Clean output by removing prompts and input echoes
+ */
+export declare function cleanProcessOutput(output: string, inputSent?: string): string;
+/**
+ * Format process state for user display
+ */
+export declare function formatProcessStateMessage(state: ProcessState, pid: number): string;

package/dist/utils/process-detection.js

@@ -0,0 +1,150 @@
+/**
+ * REPL and Process State Detection Utilities
+ * Detects when processes are waiting for input vs finished vs running
+ */
+// Common REPL prompt patterns
+const REPL_PROMPTS = {
+    python: ['>>> ', '... '],
+    node: ['> ', '... '],
+    r: ['> ', '+ '],
+    julia: ['julia> ', '       '], // julia continuation is spaces
+    shell: ['$ ', '# ', '% ', 'bash-', 'zsh-'],
+    mysql: ['mysql> ', '    -> '],
+    postgres: ['=# ', '-# '],
+    redis: ['redis> '],
+    mongo: ['> ', '... ']
+};
+// Error patterns that indicate completion (even with errors)
+const ERROR_COMPLETION_PATTERNS = [
+    /Error:/i,
+    /Exception:/i,
+    /Traceback/i,
+    /SyntaxError/i,
+    /NameError/i,
+    /TypeError/i,
+    /ValueError/i,
+    /ReferenceError/i,
+    /Uncaught/i,
+    /at Object\./i, // Node.js stack traces
+    /^\s*\^/m // Syntax error indicators
+];
+// Process completion indicators
+const COMPLETION_INDICATORS = [
+    /Process finished/i,
+    /Command completed/i,
+    /\[Process completed\]/i,
+    /Program terminated/i,
+    /Exit code:/i
+];
+/**
+ * Analyze process output to determine current state
+ */
+export function analyzeProcessState(output, pid) {
+    if (!output || output.trim().length === 0) {
+        return {
+            isWaitingForInput: false,
+            isFinished: false,
+            isRunning: true,
+            lastOutput: output
+        };
+    }
+    const lines = output.split('\n');
+    const lastLine = lines[lines.length - 1] || '';
+    const lastFewLines = lines.slice(-3).join('\n');
+    // Check for REPL prompts (waiting for input)
+    const allPrompts = Object.values(REPL_PROMPTS).flat();
+    const detectedPrompt = allPrompts.find(prompt => lastLine.endsWith(prompt) || lastLine.includes(prompt));
+    if (detectedPrompt) {
+        return {
+            isWaitingForInput: true,
+            isFinished: false,
+            isRunning: true,
+            detectedPrompt,
+            lastOutput: output
+        };
+    }
+    // Check for completion indicators
+    const hasCompletionIndicator = COMPLETION_INDICATORS.some(pattern => pattern.test(output));
+    if (hasCompletionIndicator) {
+        return {
+            isWaitingForInput: false,
+            isFinished: true,
+            isRunning: false,
+            lastOutput: output
+        };
+    }
+    // Check for error completion (errors usually end with prompts, but let's be thorough)
+    const hasErrorCompletion = ERROR_COMPLETION_PATTERNS.some(pattern => pattern.test(lastFewLines));
+    if (hasErrorCompletion) {
+        // Errors can indicate completion, but check if followed by prompt
+        if (detectedPrompt) {
+            return {
+                isWaitingForInput: true,
+                isFinished: false,
+                isRunning: true,
+                detectedPrompt,
+                lastOutput: output
+            };
+        }
+        else {
+            return {
+                isWaitingForInput: false,
+                isFinished: true,
+                isRunning: false,
+                lastOutput: output
+            };
+        }
+    }
+    // Default: process is running, not clearly waiting or finished
+    return {
+        isWaitingForInput: false,
+        isFinished: false,
+        isRunning: true,
+        lastOutput: output
+    };
+}
+/**
+ * Clean output by removing prompts and input echoes
+ */
+export function cleanProcessOutput(output, inputSent) {
+    let cleaned = output;
+    // Remove input echo if provided
+    if (inputSent) {
+        const inputLines = inputSent.split('\n');
+        inputLines.forEach(line => {
+            if (line.trim()) {
+                cleaned = cleaned.replace(new RegExp(`^${escapeRegExp(line.trim())}\\s*\n?`, 'm'), '');
+            }
+        });
+    }
+    // Remove common prompt patterns from output
+    cleaned = cleaned.replace(/^>>>\s*/gm, ''); // Python >>>
+    cleaned = cleaned.replace(/^>\s*/gm, ''); // Node.js/Shell >
+    cleaned = cleaned.replace(/^\.{3}\s*/gm, ''); // Python ...
+    cleaned = cleaned.replace(/^\+\s*/gm, ''); // R +
+    // Remove trailing prompts
+    cleaned = cleaned.replace(/\n>>>\s*$/, '');
+    cleaned = cleaned.replace(/\n>\s*$/, '');
+    cleaned = cleaned.replace(/\n\+\s*$/, '');
+    return cleaned.trim();
+}
+/**
+ * Escape special regex characters
+ */
+function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Format process state for user display
+ */
+export function formatProcessStateMessage(state, pid) {
+    if (state.isWaitingForInput) {
+        return `Process ${pid} is waiting for input${state.detectedPrompt ? ` (detected: "${state.detectedPrompt.trim()}")` : ''}`;
+    }
+    else if (state.isFinished) {
+        return `Process ${pid} has finished execution`;
+    }
+    else {
+        return `Process ${pid} is running`;
+    }
+}

package/dist/utils/ripgrep-resolver.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve ripgrep binary path with multiple fallback strategies
+ * This handles cases where @vscode/ripgrep postinstall fails in npx environments
+ */
+export declare function getRipgrepPath(): Promise<string>;
+/**
+ * Clear the cached ripgrep path (useful for testing)
+ */
+export declare function clearRipgrepCache(): void;

package/dist/utils/ripgrep-resolver.js

@@ -0,0 +1,74 @@
+import { execSync } from 'child_process';
+import { existsSync, chmodSync } from 'fs';
+import path from 'path';
+import os from 'os';
+let cachedRgPath = null;
+/**
+ * Resolve ripgrep binary path with multiple fallback strategies
+ * This handles cases where @vscode/ripgrep postinstall fails in npx environments
+ */
+export async function getRipgrepPath() {
+    if (cachedRgPath) {
+        return cachedRgPath;
+    }
+    // Strategy 1: Try @vscode/ripgrep package
+    try {
+        const { rgPath } = await import('@vscode/ripgrep');
+        if (existsSync(rgPath)) {
+            // Ensure executable permissions on Unix systems
+            if (process.platform !== 'win32') {
+                try {
+                    chmodSync(rgPath, 0o755);
+                }
+                catch (e) {
+                    // Ignore chmod errors - might not have write access
+                }
+            }
+            cachedRgPath = rgPath;
+            return rgPath;
+        }
+    }
+    catch (e) {
+        // @vscode/ripgrep import or binary resolution failed, continue to fallbacks
+    }
+    // Strategy 2: Try system ripgrep using 'which' (Unix) or 'where' (Windows)
+    try {
+        const systemRg = process.platform === 'win32' ? 'rg.exe' : 'rg';
+        const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+        const result = execSync(`${whichCmd} ${systemRg}`, { encoding: 'utf-8' }).trim().split(/\r?\n/)[0];
+        if (result && existsSync(result)) {
+            cachedRgPath = result;
+            return result;
+        }
+    }
+    catch (e) {
+        // System rg not found via which
+    }
+    // Strategy 3: Try common installation paths
+    const commonPaths = [];
+    if (process.platform === 'win32') {
+        commonPaths.push('C:\\Program Files\\Ripgrep\\rg.exe', 'C:\\Program Files (x86)\\Ripgrep\\rg.exe', path.join(os.homedir(), 'scoop', 'apps', 'ripgrep', 'current', 'rg.exe'), path.join(os.homedir(), '.cargo', 'bin', 'rg.exe'));
+    }
+    else {
+        commonPaths.push('/usr/local/bin/rg', '/usr/bin/rg', path.join(os.homedir(), '.cargo', 'bin', 'rg'), '/opt/homebrew/bin/rg' // Apple Silicon Homebrew
+        );
+    }
+    for (const possiblePath of commonPaths) {
+        if (existsSync(possiblePath)) {
+            cachedRgPath = possiblePath;
+            return possiblePath;
+        }
+    }
+    // No ripgrep found - provide helpful error message
+    throw new Error('ripgrep binary not found. MCP Device requires ripgrep to perform searches. ' +
+        'Please install ripgrep:\n' +
+        '  macOS: brew install ripgrep\n' +
+        '  Linux: See https://github.com/BurntSushi/ripgrep#installation\n' +
+        '  Windows: choco install ripgrep or download from https://github.com/BurntSushi/ripgrep/releases');
+}
+/**
+ * Clear the cached ripgrep path (useful for testing)
+ */
+export function clearRipgrepCache() {
+    cachedRgPath = null;
+}

package/dist/utils/system-info.d.ts

@@ -0,0 +1,71 @@
+export interface DockerMount {
+    hostPath: string;
+    containerPath: string;
+    type: 'bind' | 'volume';
+    readOnly: boolean;
+    description: string;
+}
+export interface ContainerInfo {
+    isContainer: boolean;
+    containerType: 'docker' | 'podman' | 'kubernetes' | 'lxc' | 'systemd-nspawn' | 'other' | null;
+    orchestrator: 'kubernetes' | 'docker-compose' | 'docker-swarm' | 'podman-compose' | null;
+    isDocker: boolean;
+    mountPoints: DockerMount[];
+    containerEnvironment?: {
+        dockerImage?: string;
+        containerName?: string;
+        hostPlatform?: string;
+        kubernetesNamespace?: string;
+        kubernetesPod?: string;
+        kubernetesNode?: string;
+    };
+}
+export interface SystemInfo {
+    platform: string;
+    platformName: string;
+    defaultShell: string;
+    pathSeparator: string;
+    isWindows: boolean;
+    isMacOS: boolean;
+    isLinux: boolean;
+    docker: ContainerInfo;
+    isDXT: boolean;
+    nodeInfo?: {
+        version: string;
+        path: string;
+        npmVersion?: string;
+    };
+    pythonInfo?: {
+        available: boolean;
+        command: string;
+        version?: string;
+    };
+    processInfo: {
+        pid: number;
+        arch: string;
+        platform: string;
+        versions: NodeJS.ProcessVersions;
+    };
+    examplePaths: {
+        home: string;
+        temp: string;
+        absolute: string;
+        accessible?: string[];
+    };
+}
+/**
+ * Get comprehensive system information for tool prompts
+ */
+export declare function getSystemInfo(): SystemInfo;
+/**
+ * Generate OS-specific guidance for tool prompts
+ */
+export declare function getOSSpecificGuidance(systemInfo: SystemInfo): string;
+/**
+ * Get common development tool guidance based on OS
+ */
+export declare function getDevelopmentToolGuidance(systemInfo: SystemInfo): string;
+/**
+ * Get path guidance (simplified since paths are normalized)
+ */
+export declare function getPathGuidance(systemInfo: SystemInfo): string;