@hcu-lab.me/mcp-device 1.0.0

package/dist/tools/fuzzySearch.d.ts

@@ -0,0 +1,12 @@
+import type { FuzzyMatch } from './fuzzySearchCore.js';
+export { recursiveFuzzyIndexOf, getSimilarityRatio } from './fuzzySearchCore.js';
+/** Abort fuzzy search in the worker after this many ms to avoid unbounded CPU burn. */
+export declare const FUZZY_SEARCH_TIMEOUT_MS = 30000;
+/**
+ * Runs the fuzzy search in a Worker thread so the main MCP event loop stays
+ * responsive to pings and other tool calls during heavy scans. Rejects if the
+ * scan exceeds timeoutMs, terminating the worker so it doesn't linger in the
+ * background. Search metrics come back with the result and are captured here,
+ * on the main thread, where the client identity is initialized.
+ */
+export declare function runFuzzySearchInWorker(text: string, query: string, timeoutMs?: number): Promise<FuzzyMatch>;

package/dist/tools/fuzzySearch.js

@@ -0,0 +1,74 @@
+import { capture } from '../utils/capture.js';
+import { Worker } from 'worker_threads';
+// Re-export so existing callers keep importing from this module.
+export { recursiveFuzzyIndexOf, getSimilarityRatio } from './fuzzySearchCore.js';
+/** Abort fuzzy search in the worker after this many ms to avoid unbounded CPU burn. */
+export const FUZZY_SEARCH_TIMEOUT_MS = 30000;
+/**
+ * Inline worker entry: imports the dependency-free core module (passed as
+ * moduleUrl) and runs the search off the main thread. The core module is
+ * deliberately a leaf — importing this module (or anything app-level) from the
+ * worker would boot the whole server per search. Kept as an eval'd snippet so
+ * the worker needs no separate file to ship alongside the compiled output.
+ */
+const WORKER_CODE = `
+const { workerData, parentPort } = require('worker_threads');
+import(workerData.moduleUrl)
+    .then((m) => {
+        parentPort.postMessage({ ok: true, ...m.runFuzzySearch(workerData.text, workerData.query) });
+    })
+    .catch((err) => {
+        parentPort.postMessage({ ok: false, error: String(err && err.stack || err) });
+    });
+`;
+const CORE_MODULE_URL = new URL('./fuzzySearchCore.js', import.meta.url).href;
+/**
+ * Runs the fuzzy search in a Worker thread so the main MCP event loop stays
+ * responsive to pings and other tool calls during heavy scans. Rejects if the
+ * scan exceeds timeoutMs, terminating the worker so it doesn't linger in the
+ * background. Search metrics come back with the result and are captured here,
+ * on the main thread, where the client identity is initialized.
+ */
+export function runFuzzySearchInWorker(text, query, timeoutMs = FUZZY_SEARCH_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(WORKER_CODE, { eval: true, workerData: { moduleUrl: CORE_MODULE_URL, text, query } });
+        // Never let a scan keep the server process alive during shutdown.
+        worker.unref();
+        const timer = setTimeout(() => {
+            worker.terminate();
+            reject(new Error(`Fuzzy search timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref();
+        worker.on('message', (msg) => {
+            clearTimeout(timer);
+            if (msg.ok) {
+                captureFuzzySearchMetrics(msg.metrics);
+                resolve(msg.result);
+            }
+            else {
+                reject(new Error(`Fuzzy search worker failed: ${msg.error}`));
+            }
+            // Don't let the worker wind down on its own; the answer is already
+            // here, and a lingering worker holds its copy of the file text.
+            // The promise is settled, so the exit-code rejection below is a no-op.
+            worker.terminate();
+        });
+        worker.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        worker.on('exit', (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(`Fuzzy search worker exited with code ${code}`));
+            }
+        });
+    });
+}
+/** Same telemetry events the search used to emit inline, now sent from the main thread. */
+function captureFuzzySearchMetrics(metrics) {
+    capture('fuzzy_search_recursive_metrics', metrics.recursive);
+    if (metrics.iterative) {
+        capture('fuzzy_search_iterative_metrics', metrics.iterative);
+    }
+}

package/dist/tools/fuzzySearchCore.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure fuzzy-search core, kept free of app imports on purpose: it runs inside
+ * the worker thread spawned by runFuzzySearchInWorker (fuzzySearch.ts), and
+ * anything imported here is loaded per worker. Telemetry is returned as data
+ * and captured on the main thread, which has the real client identity.
+ */
+export interface FuzzyMatch {
+    start: number;
+    end: number;
+    value: string;
+    distance: number;
+}
+export interface FuzzySearchMetrics {
+    recursive: {
+        execution_time_ms: number;
+        text_length: number;
+        query_length: number;
+        result_distance: number;
+    };
+    iterative: {
+        execution_time_ms: number;
+        iterations: number;
+        segment_length: number;
+        query_length: number;
+        final_distance: number;
+    } | null;
+}
+/**
+ * Runs a full fuzzy search and returns the match together with the timing
+ * metrics that used to be captured inline.
+ */
+export declare function runFuzzySearch(text: string, query: string): {
+    result: FuzzyMatch;
+    metrics: FuzzySearchMetrics;
+};
+/**
+ * Recursively finds the closest match to a query string within text using fuzzy matching
+ * @param text The text to search within
+ * @param query The query string to find
+ * @param start Start index in the text (default: 0)
+ * @param end End index in the text (default: text.length)
+ * @param parentDistance Best distance found so far (default: Infinity)
+ * @returns Object with start and end indices, matched value, and Levenshtein distance
+ */
+export declare function recursiveFuzzyIndexOf(text: string, query: string, start?: number, end?: number | null, parentDistance?: number): FuzzyMatch;
+/**
+ * Calculates the similarity ratio between two strings
+ * @param a First string
+ * @param b Second string
+ * @returns Similarity ratio (0-1)
+ */
+export declare function getSimilarityRatio(a: string, b: string): number;

package/dist/tools/fuzzySearchCore.js

@@ -0,0 +1,125 @@
+import { distance } from 'fastest-levenshtein';
+// Set by iterativeReduction during a search (exactly one terminal call per
+// search) and collected by runFuzzySearch. Single-threaded per context, so a
+// module-level slot is safe.
+let lastIterativeMetrics = null;
+/**
+ * Runs a full fuzzy search and returns the match together with the timing
+ * metrics that used to be captured inline.
+ */
+export function runFuzzySearch(text, query) {
+    const startTime = performance.now();
+    lastIterativeMetrics = null;
+    const result = recursiveFuzzyIndexOf(text, query);
+    return {
+        result,
+        metrics: {
+            recursive: {
+                execution_time_ms: performance.now() - startTime,
+                text_length: text.length,
+                query_length: query.length,
+                result_distance: result.distance
+            },
+            iterative: lastIterativeMetrics
+        }
+    };
+}
+/**
+ * Recursively finds the closest match to a query string within text using fuzzy matching
+ * @param text The text to search within
+ * @param query The query string to find
+ * @param start Start index in the text (default: 0)
+ * @param end End index in the text (default: text.length)
+ * @param parentDistance Best distance found so far (default: Infinity)
+ * @returns Object with start and end indices, matched value, and Levenshtein distance
+ */
+export function recursiveFuzzyIndexOf(text, query, start = 0, end = null, parentDistance = Infinity) {
+    if (end === null)
+        end = text.length;
+    // For small text segments, use iterative approach
+    if (end - start <= 2 * query.length) {
+        return iterativeReduction(text, query, start, end, parentDistance);
+    }
+    let midPoint = start + Math.floor((end - start) / 2);
+    let leftEnd = Math.min(end, midPoint + query.length); // Include query length to cover overlaps
+    let rightStart = Math.max(start, midPoint - query.length); // Include query length to cover overlaps
+    // Calculate distance for current segments
+    let leftDistance = distance(text.substring(start, leftEnd), query);
+    let rightDistance = distance(text.substring(rightStart, end), query);
+    let bestDistance = Math.min(leftDistance, parentDistance, rightDistance);
+    // If parent distance is already the best, use iterative approach
+    if (parentDistance === bestDistance) {
+        return iterativeReduction(text, query, start, end, parentDistance);
+    }
+    // Recursively search the better half
+    if (leftDistance < rightDistance) {
+        return recursiveFuzzyIndexOf(text, query, start, leftEnd, bestDistance);
+    }
+    else {
+        return recursiveFuzzyIndexOf(text, query, rightStart, end, bestDistance);
+    }
+}
+/**
+ * Iteratively refines the best match by reducing the search area
+ * @param text The text to search within
+ * @param query The query string to find
+ * @param start Start index in the text
+ * @param end End index in the text
+ * @param parentDistance Best distance found so far
+ * @returns Object with start and end indices, matched value, and Levenshtein distance
+ */
+function iterativeReduction(text, query, start, end, parentDistance) {
+    const startTime = performance.now();
+    let iterations = 0;
+    // Seed with the measured distance of this slice. For recursive callers
+    // this equals parentDistance (the parent measured exactly this slice), but
+    // a top-level call on text <= 2x query length arrives with Infinity, which
+    // made the first shrink unconditional and a position-0 match unreachable.
+    let bestDistance = distance(text.substring(start, end), query);
+    let bestStart = start;
+    let bestEnd = end;
+    // Improve start position
+    let nextDistance = distance(text.substring(bestStart + 1, bestEnd), query);
+    while (nextDistance < bestDistance) {
+        bestDistance = nextDistance;
+        bestStart++;
+        const smallerString = text.substring(bestStart + 1, bestEnd);
+        nextDistance = distance(smallerString, query);
+        iterations++;
+    }
+    // Improve end position
+    nextDistance = distance(text.substring(bestStart, bestEnd - 1), query);
+    while (nextDistance < bestDistance) {
+        bestDistance = nextDistance;
+        bestEnd--;
+        const smallerString = text.substring(bestStart, bestEnd - 1);
+        nextDistance = distance(smallerString, query);
+        iterations++;
+    }
+    lastIterativeMetrics = {
+        execution_time_ms: performance.now() - startTime,
+        iterations: iterations,
+        segment_length: end - start,
+        query_length: query.length,
+        final_distance: bestDistance
+    };
+    return {
+        start: bestStart,
+        end: bestEnd,
+        value: text.substring(bestStart, bestEnd),
+        distance: bestDistance
+    };
+}
+/**
+ * Calculates the similarity ratio between two strings
+ * @param a First string
+ * @param b Second string
+ * @returns Similarity ratio (0-1)
+ */
+export function getSimilarityRatio(a, b) {
+    const maxLength = Math.max(a.length, b.length);
+    if (maxLength === 0)
+        return 1; // Both strings are empty
+    const levenshteinDistance = distance(a, b);
+    return 1 - (levenshteinDistance / maxLength);
+}

package/dist/tools/improved-process-tools.d.ts

@@ -0,0 +1,24 @@
+import { ServerResult } from '../types.js';
+/**
+ * Start a new process (renamed from execute_command)
+ * Includes early detection of process waiting for input
+ */
+export declare function startProcess(args: unknown): Promise<ServerResult>;
+/**
+ * Read output from a running process with file-like pagination
+ * Supports offset/length parameters for controlled reading
+ */
+export declare function readProcessOutput(args: unknown): Promise<ServerResult>;
+/**
+ * Interact with a running process (renamed from send_input)
+ * Automatically detects when process is ready and returns output
+ */
+export declare function interactWithProcess(args: unknown): Promise<ServerResult>;
+/**
+ * Force terminate a process
+ */
+export declare function forceTerminate(args: unknown): Promise<ServerResult>;
+/**
+ * List active sessions
+ */
+export declare function listSessions(): Promise<ServerResult>;