@hcu-lab.me/mcp-device 1.0.0

package/dist/utils/toolHistory.d.ts

@@ -0,0 +1,86 @@
+import { ServerResult } from '../types.js';
+export interface ToolCallRecord {
+    timestamp: string;
+    toolName: string;
+    arguments: any;
+    output: ServerResult;
+    duration?: number;
+}
+interface FormattedToolCallRecord extends Omit<ToolCallRecord, 'timestamp'> {
+    timestamp: string;
+}
+declare class ToolHistory {
+    private history;
+    private readonly MAX_ENTRIES;
+    private readonly MAX_HISTORY_FILE_SIZE_BYTES;
+    private readonly HISTORY_FILE_TRIM_TARGET_BYTES;
+    private readonly historyFile;
+    private writeQueue;
+    private isWriting;
+    private writeInterval?;
+    constructor();
+    /**
+     * Load history from disk (all instances share the same file)
+     */
+    private loadFromDisk;
+    /**
+     * Trim the on-disk history file to stay under the size cap by dropping the
+     * oldest entries (lines) until the kept tail fits within the trim target.
+     * Returns true only when the file was actually rewritten with a smaller
+     * tail, so callers can fall through to their normal path on failure or
+     * no-op rather than mutating in-memory state.
+     *
+     * Always keeps at least the most recent entry, even if a single record
+     * exceeds the trim target — there is no useful state below that.
+     */
+    private trimHistoryFileIfTooLarge;
+    /**
+     * Trim history file to prevent it from growing indefinitely
+     */
+    private trimHistoryFile;
+    /**
+     * Async write processor - batches writes to avoid blocking
+     */
+    private startWriteProcessor;
+    /**
+     * Flush queued writes to disk
+     */
+    private flushToDisk;
+    /**
+     * Add a tool call to history
+     */
+    addCall(toolName: string, args: any, output: ServerResult, duration?: number): void;
+    /**
+     * Get recent tool calls with filters
+     */
+    getRecentCalls(options: {
+        maxResults?: number;
+        toolName?: string;
+        since?: string;
+    }): ToolCallRecord[];
+    /**
+     * Get recent calls formatted with local timezone
+     */
+    getRecentCallsFormatted(options: {
+        maxResults?: number;
+        toolName?: string;
+        since?: string;
+    }): FormattedToolCallRecord[];
+    /**
+     * Get current stats
+     */
+    getStats(): {
+        totalEntries: number;
+        oldestEntry: string;
+        newestEntry: string;
+        historyFile: string;
+        queuedWrites: number;
+    };
+    /**
+     * Cleanup method - clears interval and flushes pending writes
+     * Call this during shutdown or in tests
+     */
+    cleanup(): Promise<void>;
+}
+export declare const toolHistory: ToolHistory;
+export {};

package/dist/utils/toolHistory.js

@@ -0,0 +1,257 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { CONFIG_DIR } from '../config.js';
+// Format timestamp in local timezone for display
+function formatLocalTimestamp(isoTimestamp) {
+    const date = new Date(isoTimestamp);
+    return date.toLocaleString('en-US', {
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false
+    });
+}
+class ToolHistory {
+    constructor() {
+        this.history = [];
+        this.MAX_ENTRIES = 1000;
+        this.MAX_HISTORY_FILE_SIZE_BYTES = 5 * 1024 * 1024;
+        // When the file exceeds the cap we trim it down to this target instead of
+        // all the way to zero, so a single overflow doesn't cause every subsequent
+        // flush to re-trim.
+        this.HISTORY_FILE_TRIM_TARGET_BYTES = 4 * 1024 * 1024;
+        this.writeQueue = [];
+        this.isWriting = false;
+        // Store history under the canonical MCP Device state root.
+        const historyDir = path.join(CONFIG_DIR, 'logs');
+        // Ensure directory exists
+        if (!fs.existsSync(historyDir)) {
+            fs.mkdirSync(historyDir, { recursive: true });
+        }
+        // Use append-only JSONL format (JSON Lines).
+        this.historyFile = path.join(historyDir, 'history.jsonl');
+        // Load existing history on startup
+        this.loadFromDisk();
+        // Start async write processor
+        this.startWriteProcessor();
+    }
+    /**
+     * Load history from disk (all instances share the same file)
+     */
+    loadFromDisk() {
+        try {
+            if (!fs.existsSync(this.historyFile)) {
+                return;
+            }
+            // If the file is over the cap, trim it down before reading so we
+            // load a bounded amount.
+            this.trimHistoryFileIfTooLarge();
+            const content = fs.readFileSync(this.historyFile, 'utf-8');
+            const lines = content.trim().split('\n').filter(line => line.trim());
+            // Parse each line as JSON
+            const records = [];
+            for (const line of lines) {
+                try {
+                    records.push(JSON.parse(line));
+                }
+                catch (e) {
+                    // Silently skip invalid lines
+                }
+            }
+            // Keep only last 1000 entries
+            this.history = records.slice(-this.MAX_ENTRIES);
+            // If file is getting too large, trim it
+            if (lines.length > this.MAX_ENTRIES * 2) {
+                this.trimHistoryFile();
+            }
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    /**
+     * Trim the on-disk history file to stay under the size cap by dropping the
+     * oldest entries (lines) until the kept tail fits within the trim target.
+     * Returns true only when the file was actually rewritten with a smaller
+     * tail, so callers can fall through to their normal path on failure or
+     * no-op rather than mutating in-memory state.
+     *
+     * Always keeps at least the most recent entry, even if a single record
+     * exceeds the trim target — there is no useful state below that.
+     */
+    trimHistoryFileIfTooLarge() {
+        let stats;
+        try {
+            if (!fs.existsSync(this.historyFile)) {
+                return false;
+            }
+            stats = fs.statSync(this.historyFile);
+            if (stats.size <= this.MAX_HISTORY_FILE_SIZE_BYTES) {
+                return false;
+            }
+        }
+        catch (error) {
+            return false;
+        }
+        try {
+            const content = fs.readFileSync(this.historyFile, 'utf-8');
+            const lines = content.split('\n').filter(line => line.length > 0);
+            if (lines.length === 0) {
+                return false;
+            }
+            // Walk lines from newest to oldest, accumulating bytes (line + '\n'),
+            // and keep as many as fit within the trim target. Always keep at
+            // least the last line.
+            const kept = [];
+            let bytes = 0;
+            for (let i = lines.length - 1; i >= 0; i--) {
+                const lineBytes = Buffer.byteLength(lines[i], 'utf-8') + 1; // +1 for '\n'
+                if (kept.length > 0 && bytes + lineBytes > this.HISTORY_FILE_TRIM_TARGET_BYTES) {
+                    break;
+                }
+                kept.push(lines[i]);
+                bytes += lineBytes;
+            }
+            kept.reverse();
+            fs.writeFileSync(this.historyFile, kept.join('\n') + '\n', 'utf-8');
+            return true;
+        }
+        catch (error) {
+            // Trim failed; do not claim the file was changed.
+            return false;
+        }
+    }
+    /**
+     * Trim history file to prevent it from growing indefinitely
+     */
+    trimHistoryFile() {
+        try {
+            // Keep last 1000 entries in memory
+            const keepEntries = this.history.slice(-this.MAX_ENTRIES);
+            // Write them back
+            const lines = keepEntries.map(entry => JSON.stringify(entry)).join('\n') + '\n';
+            fs.writeFileSync(this.historyFile, lines, 'utf-8');
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
+    /**
+     * Async write processor - batches writes to avoid blocking
+     */
+    startWriteProcessor() {
+        this.writeInterval = setInterval(() => {
+            if (this.writeQueue.length > 0 && !this.isWriting) {
+                this.flushToDisk();
+            }
+        }, 1000); // Flush every second
+        // Prevent interval from keeping process alive during shutdown/tests
+        this.writeInterval.unref();
+    }
+    /**
+     * Flush queued writes to disk
+     */
+    async flushToDisk() {
+        if (this.isWriting || this.writeQueue.length === 0)
+            return;
+        this.isWriting = true;
+        const toWrite = [...this.writeQueue];
+        this.writeQueue = [];
+        try {
+            // If the on-disk file has grown past the cap, trim it down to the
+            // target size (keeping the most recent entries) before appending.
+            // The in-memory cache is unaffected — it is already bounded by
+            // MAX_ENTRIES via addCall.
+            this.trimHistoryFileIfTooLarge();
+            // Append to file (atomic append operation)
+            const lines = toWrite.map(entry => JSON.stringify(entry)).join('\n') + '\n';
+            fs.appendFileSync(this.historyFile, lines, 'utf-8');
+        }
+        catch (error) {
+            // Put back in queue on failure
+            this.writeQueue.unshift(...toWrite);
+        }
+        finally {
+            this.isWriting = false;
+        }
+    }
+    /**
+     * Add a tool call to history
+     */
+    addCall(toolName, args, output, duration) {
+        const record = {
+            timestamp: new Date().toISOString(),
+            toolName,
+            arguments: args,
+            output,
+            duration
+        };
+        this.history.push(record);
+        // Keep only last 1000 in memory
+        if (this.history.length > this.MAX_ENTRIES) {
+            this.history.shift();
+        }
+        // Queue for async write
+        this.writeQueue.push(record);
+    }
+    /**
+     * Get recent tool calls with filters
+     */
+    getRecentCalls(options) {
+        let results = [...this.history];
+        // Filter by tool name
+        if (options.toolName) {
+            results = results.filter(r => r.toolName === options.toolName);
+        }
+        // Filter by timestamp
+        if (options.since) {
+            const sinceDate = new Date(options.since);
+            results = results.filter(r => new Date(r.timestamp) >= sinceDate);
+        }
+        // Limit results (default 50, max 1000)
+        const limit = Math.min(options.maxResults || 50, 1000);
+        return results.slice(-limit);
+    }
+    /**
+     * Get recent calls formatted with local timezone
+     */
+    getRecentCallsFormatted(options) {
+        const calls = this.getRecentCalls(options);
+        // Format timestamps to local timezone
+        return calls.map(call => ({
+            ...call,
+            timestamp: formatLocalTimestamp(call.timestamp)
+        }));
+    }
+    /**
+     * Get current stats
+     */
+    getStats() {
+        return {
+            totalEntries: this.history.length,
+            oldestEntry: this.history[0]?.timestamp,
+            newestEntry: this.history[this.history.length - 1]?.timestamp,
+            historyFile: this.historyFile,
+            queuedWrites: this.writeQueue.length
+        };
+    }
+    /**
+     * Cleanup method - clears interval and flushes pending writes
+     * Call this during shutdown or in tests
+     */
+    async cleanup() {
+        // Clear the interval
+        if (this.writeInterval) {
+            clearInterval(this.writeInterval);
+            this.writeInterval = undefined;
+        }
+        // Flush any remaining writes
+        if (this.writeQueue.length > 0) {
+            await this.flushToDisk();
+        }
+    }
+}
+export const toolHistory = new ToolHistory();

package/dist/utils/trackTools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Track tool calls and save them to a log file
+ * @param toolName Name of the tool being called
+ * @param args Arguments passed to the tool (optional)
+ */
+export declare function trackToolCall(toolName: string, args?: unknown): Promise<void>;

package/dist/utils/trackTools.js

@@ -0,0 +1,54 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { TOOL_CALL_FILE, TOOL_CALL_FILE_MAX_SIZE } from '../config.js';
+// Ensure the directory for the log file exists
+const logDir = path.dirname(TOOL_CALL_FILE);
+await fs.promises.mkdir(logDir, { recursive: true });
+/**
+ * Track tool calls and save them to a log file
+ * @param toolName Name of the tool being called
+ * @param args Arguments passed to the tool (optional)
+ */
+export async function trackToolCall(toolName, args) {
+    try {
+        // Get current timestamp
+        const timestamp = new Date().toISOString();
+        // Format the log entry
+        const logEntry = `${timestamp} | ${toolName.padEnd(20, ' ')}${args ? `\t| Arguments: ${JSON.stringify(args)}` : ''}\n`;
+        // Check if file exists and get its size
+        let fileSize = 0;
+        try {
+            const stats = await fs.promises.stat(TOOL_CALL_FILE);
+            fileSize = stats.size;
+        }
+        catch (err) {
+            // File doesn't exist yet, size remains 0
+        }
+        // If file size is 10MB or larger, rotate the log file
+        if (fileSize >= TOOL_CALL_FILE_MAX_SIZE) {
+            const fileExt = path.extname(TOOL_CALL_FILE);
+            const fileBase = path.basename(TOOL_CALL_FILE, fileExt);
+            const dirName = path.dirname(TOOL_CALL_FILE);
+            // Create a timestamp-based filename for the old log
+            const date = new Date();
+            const rotateTimestamp = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}_${String(date.getHours()).padStart(2, '0')}-${String(date.getMinutes()).padStart(2, '0')}-${String(date.getSeconds()).padStart(2, '0')}`;
+            const newFileName = path.join(dirName, `${fileBase}_${rotateTimestamp}${fileExt}`);
+            // Rename the current file
+            await fs.promises.rename(TOOL_CALL_FILE, newFileName);
+        }
+        // Append to log file (if file was renamed, this will create a new file)
+        await fs.promises.appendFile(TOOL_CALL_FILE, logEntry, 'utf8');
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const { capture } = await import('./capture.js');
+        // Send a final telemetry event noting that the user has opted out
+        // This helps us track opt-out rates while respecting the user's choice
+        await capture('server_track_tool_call_error', {
+            error: errorMessage,
+            toolName
+        });
+        // Don't let logging errors affect the main functionality
+        console.error(`Error logging tool call: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/utils/unsupportedParams.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility for detecting parameters a caller sent that a tool's Zod schema does
+ * not accept.
+ *
+ * Zod's default `z.object()` silently strips unknown keys, so a model that
+ * invents a parameter (e.g. `view_range`) gets a normal-looking response with no
+ * signal that its input was ignored. These helpers let the dispatcher surface a
+ * corrective warning instead.
+ *
+ * Detection is top-level only. That is sufficient here because none of the tool
+ * arg schemas use a top-level `.passthrough()`/catchall — free-form fields
+ * (`options`, `params`, `pdfOptions`) are named keys whose contents are
+ * intentionally unvalidated.
+ */
+/** List the parameter names a tool schema accepts (empty array if it takes none). */
+export declare function getSupportedParams(schema: unknown): string[];
+/**
+ * Return the names of top-level keys in `args` that the schema does not accept.
+ * Returns [] when args is not a plain object or the schema's params can't be
+ * determined (so we never warn on something we can't reason about).
+ */
+export declare function detectUnsupportedParams(args: unknown, schema: unknown): string[];
+/** Build the corrective warning string shown to the model. */
+export declare function buildUnsupportedParamsWarning(toolName: string, unsupported: string[], supported: string[]): string;

package/dist/utils/unsupportedParams.js

@@ -0,0 +1,66 @@
+/**
+ * Utility for detecting parameters a caller sent that a tool's Zod schema does
+ * not accept.
+ *
+ * Zod's default `z.object()` silently strips unknown keys, so a model that
+ * invents a parameter (e.g. `view_range`) gets a normal-looking response with no
+ * signal that its input was ignored. These helpers let the dispatcher surface a
+ * corrective warning instead.
+ *
+ * Detection is top-level only. That is sufficient here because none of the tool
+ * arg schemas use a top-level `.passthrough()`/catchall — free-form fields
+ * (`options`, `params`, `pdfOptions`) are named keys whose contents are
+ * intentionally unvalidated.
+ */
+/**
+ * Resolve a Zod schema down to the field map of its underlying object schema,
+ * unwrapping wrappers (effects/optional/default/nullable/branded) defensively.
+ * Returns null when the schema is not (and does not wrap) a plain object schema,
+ * in which case we cannot determine the supported parameters and must not warn.
+ */
+function getObjectShape(schema) {
+    let current = schema;
+    for (let i = 0; current && current._def && i < 10; i++) {
+        const typeName = current._def.typeName;
+        if (typeName === 'ZodObject') {
+            const shape = typeof current.shape === 'function' ? current.shape() : current.shape;
+            return shape ?? null;
+        }
+        if (typeName === 'ZodEffects')
+            current = current._def.schema;
+        else if (typeName === 'ZodOptional' || typeName === 'ZodNullable' || typeName === 'ZodDefault') {
+            current = typeof current._def.innerType === 'function' ? current._def.innerType() : current._def.innerType;
+        }
+        else if (typeName === 'ZodBranded')
+            current = current._def.type;
+        else
+            return null;
+    }
+    return null;
+}
+/** List the parameter names a tool schema accepts (empty array if it takes none). */
+export function getSupportedParams(schema) {
+    const shape = getObjectShape(schema);
+    return shape ? Object.keys(shape) : [];
+}
+/**
+ * Return the names of top-level keys in `args` that the schema does not accept.
+ * Returns [] when args is not a plain object or the schema's params can't be
+ * determined (so we never warn on something we can't reason about).
+ */
+export function detectUnsupportedParams(args, schema) {
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return [];
+    const shape = getObjectShape(schema);
+    if (shape === null)
+        return [];
+    const supported = new Set(Object.keys(shape));
+    return Object.keys(args).filter((k) => !supported.has(k));
+}
+/** Build the corrective warning string shown to the model. */
+export function buildUnsupportedParamsWarning(toolName, unsupported, supported) {
+    const ignored = unsupported.join(', ');
+    const supportedList = supported.length > 0 ? supported.join(', ') : '(none)';
+    return `You sent parameters not supported by this tool, which were ignored: ${ignored}. `
+        + `Supported parameters for ${toolName}: ${supportedList}.`;
+}

package/dist/utils/usageTracker.d.ts

@@ -0,0 +1,133 @@
+export interface ToolUsageStats {
+    filesystemOperations: number;
+    terminalOperations: number;
+    editOperations: number;
+    searchOperations: number;
+    configOperations: number;
+    processOperations: number;
+    totalToolCalls: number;
+    successfulCalls: number;
+    failedCalls: number;
+    toolCounts: Record<string, number>;
+    firstUsed: number;
+    lastUsed: number;
+    totalSessions: number;
+    lastFeedbackPrompt: number;
+    lastFeedbackPromptDate?: string;
+    feedbackAttempts?: number;
+}
+export interface OnboardingState {
+    promptsUsed: boolean;
+    attemptsShown: number;
+    lastShownAt: number;
+}
+export interface UsageSession {
+    sessionStart: number;
+    lastActivity: number;
+    commandsInSession: number;
+    promptedThisSession: boolean;
+}
+declare class UsageTracker {
+    private currentSession;
+    /**
+     * Get default usage stats
+     */
+    private getDefaultStats;
+    /**
+     * Get current usage stats from config
+     */
+    getStats(): Promise<ToolUsageStats>;
+    /**
+     * Save usage stats to config.
+     * Non-blocking: the tool-call return path must not wait on a disk write. The
+     * in-memory stats are already updated by the caller (getStats returns the live
+     * config object), so persistence is coalesced in the background. This is what
+     * keeps a saturated libuv threadpool from gating tool responses on every call.
+     */
+    private saveStats;
+    /**
+     * Determine which category a tool belongs to
+     */
+    private getToolCategory;
+    /**
+     * Check if we're in a new session
+     */
+    private isNewSession;
+    /**
+     * Update session tracking
+     */
+    private updateSession;
+    /**
+     * Track a successful tool call
+     */
+    trackSuccess(toolName: string): Promise<ToolUsageStats>;
+    /**
+     * Track a failed tool call
+     */
+    trackFailure(toolName: string): Promise<ToolUsageStats>;
+    /**
+     * Check if user should be prompted for feedback based on usage patterns
+     */
+    shouldPromptForFeedback(): Promise<boolean>;
+    /**
+     * Get a random feedback prompt message with strong CTAs and clear actions
+     * NEW 2025 Survey - 3 variants for fresh analytics tracking
+     */
+    getFeedbackPromptMessage(): Promise<{
+        variant: string;
+        message: string;
+    }>;
+    /**
+     * Check if user should be prompted for error feedback
+     */
+    shouldPromptForErrorFeedback(): Promise<boolean>;
+    /**
+     * Mark that user was prompted for feedback
+     */
+    markFeedbackPrompted(): Promise<void>;
+    /**
+     * Mark that user has given feedback
+     */
+    markFeedbackGiven(): Promise<void>;
+    /**
+     * Get usage summary for debugging/admin purposes
+     */
+    getUsageSummary(): Promise<string>;
+    /**
+     * Get onboarding state from config
+     */
+    getOnboardingState(): Promise<OnboardingState>;
+    /**
+     * Save onboarding state to config
+     */
+    saveOnboardingState(state: OnboardingState): Promise<void>;
+    /**
+     * Check if user should see onboarding invitation - SIMPLE VERSION
+     */
+    shouldShowOnboarding(): Promise<boolean>;
+    /**
+     * Get onboarding message for new users - DIRECT 5-OPTION LIST (V2)
+     */
+    getOnboardingMessage(): Promise<{
+        variant: string;
+        message: string;
+    }>;
+    /**
+     * Mark that onboarding message was shown - SIMPLE VERSION
+     */
+    markOnboardingShown(variant: string): Promise<void>;
+    /**
+     * Mark that user used prompts after seeing onboarding invitation - SIMPLE VERSION
+     */
+    markOnboardingPromptsUsed(): Promise<void>;
+    /**
+     * Mark that user has used a specific prompt (for analytics)
+     */
+    markPromptUsed(promptId: string, category: string): Promise<void>;
+    /**
+     * Reset onboarding state for testing purposes - SIMPLE VERSION
+     */
+    resetOnboardingState(): Promise<void>;
+}
+export declare const usageTracker: UsageTracker;
+export {};