@hcu-lab.me/mcp-device 1.0.0

package/dist/handlers/filesystem-handlers.js

@@ -0,0 +1,440 @@
+import { readFile, readMultipleFiles, writeFile, createDirectory, listDirectory, moveFile, getFileInfo, writePdf, getDefaultEditorMetadata } from '../tools/filesystem.js';
+import { withTimeout } from '../utils/withTimeout.js';
+import { createErrorResponse } from '../error-handlers.js';
+import { configManager } from '../config-manager.js';
+import { ReadFileArgsSchema, ReadMultipleFilesArgsSchema, WriteFileArgsSchema, CreateDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, GetFileInfoArgsSchema, WritePdfArgsSchema } from '../tools/schemas.js';
+import path from 'path';
+import os from 'os';
+import { resolvePreviewFileType } from '../ui/file-preview/shared/preview-file-types.js';
+/**
+ * Expand home directory (~) in a file path
+ */
+function expandHome(filePath) {
+    if (filePath === '~' || filePath.startsWith('~/') || filePath.startsWith(`~${path.sep}`)) {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return filePath;
+}
+/**
+ * Resolve a file path to an absolute path for use in structured content.
+ * This ensures "Open in folder" always has a valid absolute path.
+ */
+export function resolveAbsolutePath(filePath) {
+    const expanded = expandHome(filePath);
+    return path.isAbsolute(expanded)
+        ? path.resolve(expanded)
+        : path.resolve(process.cwd(), expanded);
+}
+/**
+ * Helper function to check if path contains an error
+ */
+function isErrorPath(filePath) {
+    return filePath.startsWith('__ERROR__:');
+}
+/**
+ * Extract error message from error path
+ */
+function getErrorFromPath(path) {
+    return path.substring('__ERROR__:'.length).trim();
+}
+/**
+ * Handle read_file command
+ */
+export async function handleReadFile(args) {
+    // Backstop for the whole handler operation. The real control is the
+    // 3-minute cancellable read timeout inside readFileFromDisk; this sits just
+    // above it (so that one fires first, with cleanup + a useful error) but
+    // still below the MCP client's ~4-minute hard cap, so we never leave the
+    // client hanging on an opaque timeout.
+    const HANDLER_TIMEOUT = 3.5 * 60 * 1000; // 3m30s
+    // Add input validation
+    if (args === null || args === undefined) {
+        return createErrorResponse('No arguments provided for read_file command');
+    }
+    const readFileOperation = async () => {
+        const parsed = ReadFileArgsSchema.parse(args);
+        // Get the configuration for file read limits
+        const config = await configManager.getConfig();
+        if (!config) {
+            return createErrorResponse('Configuration not available');
+        }
+        const defaultLimit = config.fileReadLineLimit ?? 1000;
+        // Convert sheet parameter: numeric strings become numbers for Excel index access
+        let sheetParam = parsed.sheet;
+        if (parsed.sheet !== undefined && /^\d+$/.test(parsed.sheet)) {
+            sheetParam = parseInt(parsed.sheet, 10);
+        }
+        const options = {
+            isUrl: parsed.isUrl,
+            offset: parsed.offset ?? 0,
+            length: parsed.length ?? defaultLimit,
+            sheet: sheetParam,
+            range: parsed.range
+        };
+        // Resolve to absolute path for local files (not URLs) so "Open in folder" works
+        const resolvedFilePath = parsed.isUrl
+            ? parsed.path
+            : resolveAbsolutePath(parsed.path);
+        const fileResult = await readFile(parsed.path, options);
+        // Handle PDF files
+        if (fileResult.metadata?.isPdf) {
+            const meta = fileResult.metadata;
+            const author = meta?.author ? `, Author: ${meta?.author}` : "";
+            const title = meta?.title ? `, Title: ${meta?.title}` : "";
+            const pdfContent = fileResult.metadata?.pages?.flatMap((p) => [
+                ...(p.images?.map((image) => ({
+                    type: "image",
+                    data: image.data,
+                    mimeType: image.mimeType
+                })) ?? []),
+                {
+                    type: "text",
+                    text: `<!-- Page: ${p.pageNumber} -->\n${p.text}`,
+                },
+            ]) ?? [];
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `PDF file: ${parsed.path}${author}${title} (${meta?.totalPages} pages) \n`
+                    },
+                    ...pdfContent
+                ],
+                ...(parsed.origin === 'ui' ? {
+                    structuredContent: {
+                        fileName: path.basename(resolvedFilePath),
+                        filePath: resolvedFilePath,
+                        fileType: 'unsupported',
+                        ...await getDefaultEditorMetadata(resolvedFilePath),
+                    },
+                } : {}),
+            };
+        }
+        // Handle image files
+        if (fileResult.metadata?.isImage) {
+            // Return the image bytes in the MCP content array so the host model can
+            // actually see the image. The preview widget gets its copy from its own
+            // origin:'ui' read — structuredContent stays metadata-only.
+            const imageData = typeof fileResult.content === 'string'
+                ? fileResult.content
+                : fileResult.content.toString('base64');
+            const imageSummary = `Image file: ${parsed.path} (${fileResult.mimeType})\n`;
+            const imageStructuredContent = {
+                fileName: path.basename(resolvedFilePath),
+                filePath: resolvedFilePath,
+                fileType: 'image',
+                ...await getDefaultEditorMetadata(resolvedFilePath),
+                mimeType: fileResult.mimeType,
+            };
+            // Widget pull (origin: 'ui'): return the base64 in a TEXT block, never
+            // an image block. An image content block makes the host inline-vision-
+            // render the result, which preempts delivery of this RPC response to
+            // the widget — leaving the preview stuck on "Preparing preview…" for
+            // exactly the host-rendered types (png/jpeg/gif/webp). Text-only lets
+            // the RPC response through so the widget can draw the <img>.
+            if (parsed.origin === 'ui') {
+                return {
+                    content: [{ type: "text", text: imageData }],
+                    structuredContent: imageStructuredContent,
+                };
+            }
+            // Model-facing read: keep the image block so the host/model sees it.
+            // No structuredContent — the widget renders from its own origin:'ui'
+            // read, and nothing else consumes it.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: imageSummary
+                    },
+                    {
+                        type: "image",
+                        data: imageData,
+                        mimeType: fileResult.mimeType
+                    }
+                ],
+            };
+        }
+        else {
+            // For all other files, return as text.
+            // structuredContent carries only file metadata (no content duplication);
+            // the widget reads text from the MCP content array (over the RPC read).
+            let textContent = typeof fileResult.content === 'string'
+                ? fileResult.content
+                : fileResult.content.toString('utf8');
+            const fileType = fileResult.metadata?.isDirectory ? 'directory' : resolvePreviewFileType(resolvedFilePath);
+            // The directory fallback prefixes a "use list_directory instead" hint
+            // for the LLM. The widget's own read (a list_directory preview pulls
+            // read_file on the dir path) would render that hint as a notice — strip it.
+            if (parsed.origin === 'ui' && fileType === 'directory') {
+                textContent = textContent.replace(/^This is a directory, not a file\.[^\n]*\n+/, '');
+            }
+            return {
+                content: [{ type: "text", text: textContent }],
+                ...(parsed.origin === 'ui' ? {
+                    structuredContent: {
+                        fileName: path.basename(resolvedFilePath),
+                        filePath: resolvedFilePath,
+                        fileType,
+                        ...await getDefaultEditorMetadata(resolvedFilePath),
+                    },
+                } : {}),
+            };
+        }
+    };
+    // Execute with timeout at the handler level
+    const result = await withTimeout(readFileOperation(), HANDLER_TIMEOUT, 'Read file handler operation', null);
+    if (result == null) {
+        // Handles the impossible case where withTimeout resolves to null instead of throwing
+        throw new Error('Failed to read the file');
+    }
+    return result;
+}
+/**
+ * Handle read_multiple_files command
+ */
+export async function handleReadMultipleFiles(args) {
+    const parsed = ReadMultipleFilesArgsSchema.parse(args);
+    const fileResults = await readMultipleFiles(parsed.paths);
+    // Create a text summary of all files
+    const textSummary = fileResults.map(result => {
+        if (result.error) {
+            return `${result.path}: Error - ${result.error}`;
+        }
+        else if (result.isPdf) {
+            return `${result.path}: PDF file with ${result.payload?.pages?.length} pages`;
+        }
+        else if (result.mimeType) {
+            return `${result.path}: ${result.mimeType} ${result.isImage ? '(image)' : '(text)'}`;
+        }
+        else {
+            return `${result.path}: Unknown type`;
+        }
+    }).join("\n");
+    // Create content items for each file
+    const contentItems = [];
+    // Add the text summary
+    contentItems.push({ type: "text", text: textSummary });
+    // Add each file content
+    for (const result of fileResults) {
+        if (!result.error && result.content !== undefined) {
+            if (result.isPdf) {
+                result.payload?.pages.forEach((page, i) => {
+                    page.images.forEach((image, i) => {
+                        contentItems.push({
+                            type: "image",
+                            data: image.data,
+                            mimeType: image.mimeType
+                        });
+                    });
+                    contentItems.push({
+                        type: "text",
+                        text: page.text,
+                    });
+                });
+            }
+            else if (result.isImage && result.mimeType) {
+                // For image files, add an image content item
+                contentItems.push({
+                    type: "image",
+                    data: result.content,
+                    mimeType: result.mimeType
+                });
+            }
+            else {
+                // For text files, add a text summary
+                contentItems.push({
+                    type: "text",
+                    text: `\n--- ${result.path} contents: ---\n${result.content}`
+                });
+            }
+        }
+    }
+    return { content: contentItems };
+}
+/**
+ * Handle write_file command
+ */
+export async function handleWriteFile(args) {
+    try {
+        const modeProvided = !!(args && typeof args === 'object' && 'mode' in args);
+        const parsed = WriteFileArgsSchema.parse(args);
+        // An omitted `mode` falls back to 'rewrite', which silently destroys
+        // the target's existing content. The common failure is an LLM caller
+        // intending to append but dropping the optional param (issue #541), so
+        // require explicit intent when the target already has content;
+        // new/empty files keep the zero-friction default.
+        if (!modeProvided) {
+            let existing = null;
+            try {
+                existing = await getFileInfo(parsed.path);
+            }
+            catch {
+                // Missing file or invalid path — nothing to protect; the write
+                // itself will surface any real path error.
+            }
+            if (existing?.isFile && existing.size > 0) {
+                return createErrorResponse(`Write rejected to prevent accidental data loss: ${parsed.path} already exists ` +
+                    `with content (${existing.size} bytes), and no 'mode' was specified — the default ` +
+                    `mode 'rewrite' would REPLACE the entire file. Retry with an explicit mode: ` +
+                    `'append' to add your content to the end of the existing file, or 'rewrite' ` +
+                    `to replace all existing content.`);
+            }
+        }
+        // Get the line limit from configuration
+        const config = await configManager.getConfig();
+        const MAX_LINES = config.fileWriteLineLimit ?? 50; // Default to 50 if not set
+        // Strictly enforce line count limit
+        const lines = parsed.content.split('\n');
+        const lineCount = lines.length;
+        let errorMessage = "";
+        if (lineCount > MAX_LINES) {
+            errorMessage = `✅ File written successfully! (${lineCount} lines)
+            
+💡 Performance tip: For optimal speed, consider chunking files into ≤30 line pieces in future operations.`;
+        }
+        // Pass the mode parameter to writeFile
+        await writeFile(parsed.path, parsed.content, parsed.mode);
+        // Provide more informative message based on mode
+        const modeMessage = parsed.mode === 'append' ? 'appended to' : 'wrote to';
+        // No structuredContent: nothing in the UI calls write_file (the widget
+        // previews the write via its own read_file pull at tool-result time).
+        return {
+            content: [{
+                    type: "text",
+                    text: `Successfully ${modeMessage} ${parsed.path} (${lineCount} lines) ${errorMessage}`
+                }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}
+/**
+ * Handle create_directory command
+ */
+export async function handleCreateDirectory(args) {
+    try {
+        const parsed = CreateDirectoryArgsSchema.parse(args);
+        await createDirectory(parsed.path);
+        return {
+            content: [{ type: "text", text: `Successfully created directory ${parsed.path}` }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}
+/**
+ * Handle list_directory command
+ */
+export async function handleListDirectory(args) {
+    try {
+        const startTime = Date.now();
+        const parsed = ListDirectoryArgsSchema.parse(args);
+        const entries = await listDirectory(parsed.path, parsed.depth);
+        const duration = Date.now() - startTime;
+        const resultText = entries.join('\n');
+        const resolvedPath = resolveAbsolutePath(parsed.path);
+        return {
+            content: [{ type: "text", text: resultText }],
+            ...(parsed.origin === 'ui' ? {
+                structuredContent: {
+                    fileName: path.basename(resolvedPath),
+                    filePath: resolvedPath,
+                    fileType: 'directory',
+                },
+            } : {}),
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}
+/**
+ * Handle move_file command
+ */
+export async function handleMoveFile(args) {
+    try {
+        const parsed = MoveFileArgsSchema.parse(args);
+        await moveFile(parsed.source, parsed.destination);
+        return {
+            content: [{ type: "text", text: `Successfully moved ${parsed.source} to ${parsed.destination}` }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}
+/**
+ * Format a value for display, handling objects and arrays
+ */
+function formatValue(value, indent = '') {
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        // For arrays of objects (like sheets), format each item
+        const items = value.map((item, i) => {
+            if (typeof item === 'object' && item !== null) {
+                const props = Object.entries(item)
+                    .map(([k, v]) => `${k}: ${v}`)
+                    .join(', ');
+                return `${indent}  [${i}] { ${props} }`;
+            }
+            return `${indent}  [${i}] ${item}`;
+        });
+        return `\n${items.join('\n')}`;
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+/**
+ * Handle get_file_info command
+ */
+export async function handleGetFileInfo(args) {
+    try {
+        const parsed = GetFileInfoArgsSchema.parse(args);
+        const info = await getFileInfo(parsed.path);
+        // Generic formatting for any file type
+        const formattedText = Object.entries(info)
+            .map(([key, value]) => `${key}: ${formatValue(value)}`)
+            .join('\n');
+        return {
+            content: [{
+                    type: "text",
+                    text: formattedText
+                }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}
+// Use get_config to retrieve the allowedDirectories configuration
+/**
+ * Handle write_pdf command
+ */
+export async function handleWritePdf(args) {
+    try {
+        const parsed = WritePdfArgsSchema.parse(args);
+        await writePdf(parsed.path, parsed.content, parsed.outputPath, parsed.options);
+        const targetPath = parsed.outputPath || parsed.path;
+        return {
+            content: [{ type: "text", text: `Successfully wrote PDF to ${targetPath}${parsed.outputPath ? `\nOriginal file: ${parsed.path}` : ''}` }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}

package/dist/handlers/history-handlers.d.ts

@@ -0,0 +1,12 @@
+import { ServerResult } from '../types.js';
+type TrackUiEventParams = Record<string, string | number | boolean | null>;
+export declare function buildTrackUiEventCapturePayload(event: string, component: string, params: TrackUiEventParams): Record<string, string | number | boolean | null>;
+/**
+ * Handle get_recent_tool_calls command
+ */
+export declare function handleGetRecentToolCalls(args: unknown): Promise<ServerResult>;
+/**
+ * Handle track_ui_event command
+ */
+export declare function handleTrackUiEvent(args: unknown): Promise<ServerResult>;
+export {};

package/dist/handlers/history-handlers.js

@@ -0,0 +1,67 @@
+import { toolHistory } from '../utils/toolHistory.js';
+import { GetRecentToolCallsArgsSchema, TrackUiEventArgsSchema } from '../tools/schemas.js';
+import { capture_ui_event } from '../utils/capture.js';
+export function buildTrackUiEventCapturePayload(event, component, params) {
+    return {
+        ...params,
+        component,
+        event
+    };
+}
+/**
+ * Handle get_recent_tool_calls command
+ */
+export async function handleGetRecentToolCalls(args) {
+    try {
+        const parsed = GetRecentToolCallsArgsSchema.parse(args);
+        // Use formatted version with local timezone
+        const calls = toolHistory.getRecentCallsFormatted({
+            maxResults: parsed.maxResults,
+            toolName: parsed.toolName,
+            since: parsed.since
+        });
+        const stats = toolHistory.getStats();
+        // Format the response (excluding file path per user request)
+        const summary = `Tool Call History (${calls.length} results, ${stats.totalEntries} total in memory)`;
+        const historyJson = JSON.stringify(calls, null, 2);
+        return {
+            content: [{
+                    type: "text",
+                    text: `${summary}\n\n${historyJson}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error getting tool history: ${error instanceof Error ? error.message : String(error)}`
+                }],
+            isError: true
+        };
+    }
+}
+/**
+ * Handle track_ui_event command
+ */
+export async function handleTrackUiEvent(args) {
+    try {
+        const parsed = TrackUiEventArgsSchema.parse(args);
+        await capture_ui_event('mcp_ui_event', buildTrackUiEventCapturePayload(parsed.event, parsed.component, parsed.params));
+        return {
+            content: [{
+                    type: "text",
+                    text: `Tracked UI event: ${parsed.event}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error tracking UI event: ${error instanceof Error ? error.message : String(error)}`
+                }],
+            isError: true
+        };
+    }
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,6 @@
+export * from './filesystem-handlers.js';
+export * from './terminal-handlers.js';
+export * from './process-handlers.js';
+export * from './edit-search-handlers.js';
+export * from './search-handlers.js';
+export * from './history-handlers.js';

package/dist/handlers/index.js

@@ -0,0 +1,7 @@
+// Export all handlers from their respective files
+export * from './filesystem-handlers.js';
+export * from './terminal-handlers.js';
+export * from './process-handlers.js';
+export * from './edit-search-handlers.js';
+export * from './search-handlers.js';
+export * from './history-handlers.js';

package/dist/handlers/process-handlers.d.ts

@@ -0,0 +1,9 @@
+import { ServerResult } from '../types.js';
+/**
+ * Handle list_processes command
+ */
+export declare function handleListProcesses(): Promise<ServerResult>;
+/**
+ * Handle kill_process command
+ */
+export declare function handleKillProcess(args: unknown): Promise<ServerResult>;

package/dist/handlers/process-handlers.js

@@ -0,0 +1,15 @@
+import { listProcesses, killProcess } from '../tools/process.js';
+import { KillProcessArgsSchema } from '../tools/schemas.js';
+/**
+ * Handle list_processes command
+ */
+export async function handleListProcesses() {
+    return listProcesses();
+}
+/**
+ * Handle kill_process command
+ */
+export async function handleKillProcess(args) {
+    const parsed = KillProcessArgsSchema.parse(args);
+    return killProcess(parsed);
+}

package/dist/handlers/search-handlers.d.ts

@@ -0,0 +1,17 @@
+import { ServerResult } from '../types.js';
+/**
+ * Handle start_search command
+ */
+export declare function handleStartSearch(args: unknown): Promise<ServerResult>;
+/**
+ * Handle get_more_search_results command
+ */
+export declare function handleGetMoreSearchResults(args: unknown): Promise<ServerResult>;
+/**
+ * Handle stop_search command
+ */
+export declare function handleStopSearch(args: unknown): Promise<ServerResult>;
+/**
+ * Handle list_searches command
+ */
+export declare function handleListSearches(): Promise<ServerResult>;