@wonderwhy-er/desktop-commander 0.2.38 → 0.2.40

package/README.md

@@ -37,6 +37,7 @@ Work with code and text, run processes, and automate tasks, going far beyond oth
 - [How to install](#how-to-install)
 - [Getting Started](#getting-started)
 - [Usage](#usage)
+- [File Preview UI & Markdown Editor](#file-preview-ui--markdown-editor)
 - [Handling Long-Running Commands](#handling-long-running-commands)
 - [Work in Progress and TODOs](#roadmap)
 - [Sponsors and Supporters](#support-desktop-commander)
@@ -54,7 +55,7 @@ Execute long-running terminal commands on your computer and manage processes thr
 ## Features
 
 - **Remote AI Control** - Use Desktop Commander from ChatGPT, Claude web, and other AI services via [Remote MCP](https://mcp.desktopcommander.app)
-- **File Preview UI** - Visual file previews in Claude Desktop with rendered markdown, inline images, expandable content, and quick "Open in folder" access
+- **File Preview UI** - Visual file previews in Claude Desktop with rendered markdown, inline images, expandable content, built-in markdown editor, and quick "Open in folder" access
 - **Enhanced terminal commands with interactive process control**
 - **Execute code in memory (Python, Node.js, R) without saving files**
 - **Instant data analysis - just ask to analyze CSV/JSON/Excel files**
@@ -336,7 +337,7 @@ Add this to your client's MCP configuration file at the locations below:
 <details>
 <summary><b>Cursor</b></summary>
 
-[![Install MCP Server in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=desktop-commander&config=eyJjb21tYW5kIjoibnB4IC15IEB3b25kZXJ3aHktZXIvZGVza3RvcC1jb21tYW5kZXJAbGF0ZXN0In0%3D)
+[Install MCP Server in Cursor](https://cursor.directory/mcp/desktop-commander-mcp)
 
 Or add manually to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project folder (project-specific).
 
@@ -694,6 +695,56 @@ Desktop Commander can be run in Docker containers for **complete isolation from
 - Claude can see and analyze the actual image content
 - Default 30-second timeout for URL requests
 
+## File Preview UI & Markdown Editor
+
+Desktop Commander includes a rich file preview widget in Claude Desktop that renders files visually as AI works with them.
+
+### Supported file types
+- **Markdown** — rendered preview with a built-in editor
+- **Images** — inline display (PNG, JPEG, GIF, WebP, etc.)
+- **Code files** — syntax-highlighted source view
+- **HTML** — rendered preview with toggle to source view
+- **Directories** — interactive tree with expand/collapse and lazy loading
+- **PDF, Excel, DOCX** — native content extraction and display
+
+### Markdown Editor
+
+When viewing a `.md` file in Claude Desktop, you can edit it directly inside the preview panel — no need to open a separate app.
+
+**How to use:**
+1. Ask Claude to read or create a markdown file
+2. Expand the file preview to fullscreen using the **⤢ Expand** button
+3. The editor activates automatically in fullscreen mode
+4. Edit your content with a live preview toggle, copy, undo, and save controls
+5. Changes are saved back to disk; collapse to return to inline view
+
+**Editor features:**
+- Live **edit / preview toggle** — switch between raw markdown and rendered output
+- **Auto-save** to disk with save status indicator
+- **Undo** support to revert unsaved changes
+- **Copy** button to grab the full markdown source
+- **Open in editor** — launch your default markdown app directly from the panel
+- Partial-file awareness — loads and merges surrounding lines when the file was only partially read
+- Text selection context — select text in preview mode and the AI can reference your selection
+
+### Directory Browser
+
+When Claude runs `list_directory`, the result opens as an interactive file tree inside the preview panel — not just raw text output.
+
+**Features:**
+- **Expandable tree** — folders expand and collapse on click; top-level contents shown immediately
+- **Lazy loading** — subfolders load on demand to keep the initial view fast
+- **Large directory handling** — directories with many items show a `⚠ click to load all` button instead of overwhelming the view
+- **Open in Finder/Explorer** — each folder has a quick-open button to reveal it in your file manager
+- **Click to preview** — clicking any file in the tree opens it in the file preview panel directly
+- **Back navigation** — after opening a file from the tree, a ← Back button returns you to the directory view
+
+### Other preview features
+- **Expand / collapse** — toggle between compact summary row and full panel
+- **Open in folder** — reveal the file in Finder/Explorer with one click
+- **Load more lines** — incrementally load content above or below a partial read window
+- **Text selection** — highlight text in any preview; the AI can see and reference your selection
+
 ## Fuzzy Search Log Analysis (npm scripts)
 
 The fuzzy search logging system includes convenient npm scripts for analyzing logs outside of the MCP environment:

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

@@ -1,4 +1,9 @@
 import { ServerResult } from '../types.js';
+/**
+ * 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 declare function resolveAbsolutePath(filePath: string): string;
 /**
  * Handle read_file command
  */

package/dist/handlers/filesystem-handlers.js

@@ -19,7 +19,7 @@ function expandHome(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.
  */
-function resolveAbsolutePath(filePath) {
+export function resolveAbsolutePath(filePath) {
     const expanded = expandHome(filePath);
     return path.isAbsolute(expanded)
         ? path.resolve(expanded)
@@ -133,7 +133,7 @@ export async function handleReadFile(args) {
             const textContent = typeof fileResult.content === 'string'
                 ? fileResult.content
                 : fileResult.content.toString('utf8');
-            const fileType = resolvePreviewFileType(resolvedFilePath);
+            const fileType = fileResult.metadata?.isDirectory ? 'directory' : resolvePreviewFileType(resolvedFilePath);
             return {
                 content: [{ type: "text", text: textContent }],
                 structuredContent: {
@@ -236,11 +236,17 @@ export async function handleWriteFile(args) {
         await writeFile(parsed.path, parsed.content, parsed.mode);
         // Provide more informative message based on mode
         const modeMessage = parsed.mode === 'append' ? 'appended to' : 'wrote to';
+        const resolvedWritePath = resolveAbsolutePath(parsed.path);
         return {
             content: [{
                     type: "text",
                     text: `Successfully ${modeMessage} ${parsed.path} (${lineCount} lines) ${errorMessage}`
                 }],
+            structuredContent: {
+                fileName: path.basename(resolvedWritePath),
+                filePath: resolvedWritePath,
+                fileType: resolvePreviewFileType(resolvedWritePath),
+            },
         };
     }
     catch (error) {
@@ -274,8 +280,14 @@ export async function handleListDirectory(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 }],
+            structuredContent: {
+                fileName: path.basename(resolvedPath),
+                filePath: resolvedPath,
+                fileType: 'directory',
+            },
         };
     }
     catch (error) {

package/dist/remote-device/desktop-commander-integration.js

@@ -76,7 +76,7 @@ export class DesktopCommanderIntegration {
                 // We can't run it directly as it's an stdio MCP server that waits for input
                 const whichCommand = process.platform === 'win32' ? 'where' : 'which';
                 console.debug('[DEBUG] Using platform command:', whichCommand, 'on platform:', process.platform);
-                const check = spawn(whichCommand, [commandName]);
+                const check = spawn(whichCommand, [commandName], { windowsHide: true }); // Prevent visible console windows on Windows
                 check.on('error', (err) => {
                     console.debug('[DEBUG] Spawn error for', whichCommand, ':', err.message);
                     reject(err);

package/dist/search-manager.js

@@ -33,7 +33,7 @@ import PizZip from 'pizzip';
             throw new Error(`Failed to locate ripgrep binary: ${err instanceof Error ? err.message : String(err)}`);
         }
         // Start ripgrep process
-        const rgProcess = spawn(rgPath, args);
+        const rgProcess = spawn(rgPath, args, { windowsHide: true }); // Prevent visible console windows on Windows
         if (!rgProcess.pid) {
             throw new Error('Failed to start ripgrep process');
         }
@@ -94,7 +94,8 @@ import PizZip from 'pizzip';
         const shouldSearchExcel = options.searchType === 'content' &&
             this.shouldIncludeExcelSearch(options.filePattern, validPath);
         if (shouldSearchExcel) {
-            this.searchExcelFiles(validPath, options.pattern, options.ignoreCase !== false, options.maxResults, options.filePattern // Pass filePattern to filter Excel files too
+            this.searchExcelFiles(validPath, options.pattern, options.ignoreCase !== false, options.maxResults, options.filePattern, // Pass filePattern to filter Excel files too
+            options.literalSearch // Respect literalSearch flag for Office files
             ).then(excelResults => {
                 // Add Excel results to session (merged after initial response)
                 for (const result of excelResults) {
@@ -110,7 +111,8 @@ import PizZip from 'pizzip';
         const shouldSearchDocx = options.searchType === 'content' &&
             this.shouldIncludeDocxSearch(options.filePattern, validPath);
         if (shouldSearchDocx) {
-            this.searchDocxFiles(validPath, options.pattern, options.ignoreCase !== false, options.maxResults, options.filePattern).then(docxResults => {
+            this.searchDocxFiles(validPath, options.pattern, options.ignoreCase !== false, options.maxResults, options.filePattern, options.literalSearch // Respect literalSearch flag for Office files
+            ).then(docxResults => {
                 for (const result of docxResults) {
                     session.results.push(result);
                     session.totalMatches++;
@@ -223,19 +225,11 @@ import PizZip from 'pizzip';
      * and inject into SearchManager, similar to how file handlers are structured in src/utils/files/
      * This would allow adding other file type searches (PDF, etc.) without bloating search-manager.ts
      */
-    async searchExcelFiles(rootPath, pattern, ignoreCase, maxResults, filePattern) {
+    async searchExcelFiles(rootPath, pattern, ignoreCase, maxResults, filePattern, _literalSearch) {
         const results = [];
-        // Build regex for matching content
-        const flags = ignoreCase ? 'i' : '';
-        let regex;
-        try {
-            regex = new RegExp(pattern, flags);
-        }
-        catch {
-            // If pattern is not valid regex, escape it for literal matching
-            const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            regex = new RegExp(escaped, flags);
-        }
+        // Office file search always uses literal matching to prevent ReDoS.
+        // Regex patterns are treated as literal strings — this is intentional.
+        const searchTerm = ignoreCase ? pattern.toLowerCase() : pattern;
         // Find Excel files recursively
         let excelFiles = await this.findExcelFiles(rootPath);
         // Filter by filePattern if provided
@@ -246,7 +240,13 @@ import PizZip from 'pizzip';
                 return patterns.some(pat => {
                     // Support glob-like patterns
                     if (pat.includes('*')) {
-                        const regexPat = pat.replace(/\./g, '\\.').replace(/\*/g, '.*');
+                        // Escape all regex metacharacters first (preserving * for glob expansion),
+                        // then convert the remaining * wildcards to .* for glob matching.
+                        // Without this, patterns like report(2024).xlsx or [draft].xlsx would be
+                        // misinterpreted as regex groups/character-classes.
+                        const regexPat = pat
+                            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape metacharacters except *
+                            .replace(/\*/g, '.*'); // glob * → regex .*
                         return new RegExp(`^${regexPat}$`, 'i').test(fileName);
                     }
                     // Exact match (case-insensitive)
@@ -300,12 +300,10 @@ import PizZip from 'pizzip';
                         });
                         // Join all cell values with space for cross-column matching
                         const rowText = rowValues.join(' ');
-                        if (regex.test(rowText)) {
-                            // Extract the matching portion for display
-                            const match = rowText.match(regex);
-                            const matchContext = match
-                                ? this.getMatchContext(rowText, match.index || 0, match[0].length)
-                                : rowText.substring(0, 150);
+                        const textToSearch = ignoreCase ? rowText.toLowerCase() : rowText;
+                        const matchIndex = textToSearch.indexOf(searchTerm);
+                        if (matchIndex !== -1) {
+                            const matchContext = this.getMatchContext(rowText, matchIndex, searchTerm.length);
                             results.push({
                                 file: `${filePath}:${sheetName}!Row${rowNumber}`,
                                 line: rowNumber,
@@ -386,17 +384,11 @@ import PizZip from 'pizzip';
      * Search DOCX files for content matches
      * Extracts <w:t> text from document.xml and searches it
      */
-    async searchDocxFiles(rootPath, pattern, ignoreCase, maxResults, filePattern) {
+    async searchDocxFiles(rootPath, pattern, ignoreCase, maxResults, filePattern, _literalSearch) {
         const results = [];
-        const flags = ignoreCase ? 'i' : '';
-        let regex;
-        try {
-            regex = new RegExp(pattern, flags);
-        }
-        catch {
-            const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            regex = new RegExp(escaped, flags);
-        }
+        // Office file search always uses literal matching to prevent ReDoS.
+        // Regex patterns are treated as literal strings — this is intentional.
+        const searchTerm = ignoreCase ? pattern.toLowerCase() : pattern;
         let docxFiles = await this.findDocxFiles(rootPath);
         if (filePattern) {
             const patterns = filePattern.split('|').map(p => p.trim()).filter(Boolean);
@@ -404,7 +396,9 @@ import PizZip from 'pizzip';
                 const fileName = path.basename(filePath);
                 return patterns.some(pat => {
                     if (pat.includes('*')) {
-                        const regexPat = pat.replace(/\./g, '\\.').replace(/\*/g, '.*');
+                        const regexPat = pat
+                            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape metacharacters except *
+                            .replace(/\*/g, '.*'); // glob * → regex .*
                         return new RegExp(`^${regexPat}$`, 'i').test(fileName);
                     }
                     return fileName.toLowerCase() === pat.toLowerCase();
@@ -438,11 +432,10 @@ import PizZip from 'pizzip';
                         if (!text || !text.trim())
                             continue;
                         lineNum++;
-                        if (regex.test(text)) {
-                            const match = text.match(regex);
-                            const matchContext = match
-                                ? this.getMatchContext(text, match.index || 0, match[0].length)
-                                : text.substring(0, 150);
+                        const textToSearch = ignoreCase ? text.toLowerCase() : text;
+                        const matchIndex = textToSearch.indexOf(searchTerm);
+                        if (matchIndex !== -1) {
+                            const matchContext = this.getMatchContext(text, matchIndex, searchTerm.length);
                             const partName = xmlPath === 'word/document.xml' ? '' : `:${xmlPath.replace('word/', '')}`;
                             results.push({
                                 file: `${filePath}${partName}`,

package/dist/server.js

@@ -137,9 +137,11 @@ deferLog('info', 'Setting up request handlers...');
  * Check if a tool should be included based on current client
  */
 function shouldIncludeTool(toolName) {
-    // Exclude give_feedback_to_desktop_commander for desktop-commander client
-    if (toolName === 'give_feedback_to_desktop_commander' && currentClient?.name === 'desktop-commander') {
-        return false;
+    // Exclude these tools for desktop-commander client (DC-specific meta-tools not useful when DC itself is the client)
+    if (currentClient?.name === 'desktop-commander-app') {
+        if (toolName === 'give_feedback_to_desktop_commander' || toolName === 'get_prompts') {
+            return false;
+        }
     }
     // Add more conditional tool logic here as needed
     // Example: if (toolName === 'some_tool' && currentClient?.name === 'some_client') return false;
@@ -328,6 +330,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(WriteFileArgsSchema),
+                _meta: buildUiToolMeta(FILE_PREVIEW_RESOURCE_URI, true),
                 annotations: {
                     title: "Write File",
                     readOnlyHint: false,
@@ -447,6 +450,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(ListDirectoryArgsSchema),
+                _meta: buildUiToolMeta(FILE_PREVIEW_RESOURCE_URI, true),
                 annotations: {
                     title: "List Directory Contents",
                     readOnlyHint: true,
@@ -705,6 +709,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(EditBlockArgsSchema),
+                _meta: buildUiToolMeta(FILE_PREVIEW_RESOURCE_URI, true),
                 annotations: {
                     title: "Edit Block",
                     readOnlyHint: false,
@@ -1087,7 +1092,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const startTime = Date.now();
     try {
         // Prepare telemetry data - add config key for set_config_value
-        const telemetryData = { name };
+        const telemetryData = { tool_name: name };
         // Extract metadata from _meta field if present
         const metadata = request.params._meta;
         if (metadata && typeof metadata === 'object') {

package/dist/terminal-manager.js

@@ -119,7 +119,8 @@ export class TerminalManager {
                 env: {
                     ...process.env,
                     TERM: 'xterm-256color' // Better terminal compatibility
-                }
+                },
+                windowsHide: true // Prevent visible console windows on Windows
             };
             // Add shell option if needed (for unknown shells)
             if (spawnConfig.useShellOption) {
@@ -138,7 +139,8 @@ export class TerminalManager {
                 env: {
                     ...process.env,
                     TERM: 'xterm-256color'
-                }
+                },
+                windowsHide: true // Prevent visible console windows on Windows
             };
         }
         // Spawn the process with appropriate arguments

package/dist/tools/edit.js

@@ -23,6 +23,8 @@ import path from 'path';
 import { detectLineEnding, normalizeLineEndings } from '../utils/lineEndingHandler.js';
 import { configManager } from '../config-manager.js';
 import { fuzzySearchLogger } from '../utils/fuzzySearchLogger.js';
+import { resolvePreviewFileType } from '../ui/file-preview/shared/preview-file-types.js';
+import { resolveAbsolutePath } from '../handlers/filesystem-handlers.js';
 /**
  * Threshold for fuzzy matching - similarity must be at least this value to be considered
  * (0-1 scale where 1 is perfect match and 0 is completely different)
@@ -155,11 +157,30 @@ RECOMMENDATION: For large search/replace operations, consider breaking them into
         }
         await writeFile(filePath, newContent);
         capture('server_edit_block_exact_success', { fileExtension: fileExtension, expectedReplacements, hasWarning: warningMessage !== "" });
+        const resolvedEditPath = resolveAbsolutePath(filePath);
+        // Show a partial preview centered on the edited area
+        const newLines = newContent.split('\n');
+        const totalLines = newLines.length;
+        const changePos = content.indexOf(normalizedSearch);
+        const changeStartLine = changePos >= 0 ? newContent.substring(0, changePos).split('\n').length - 1 : 0;
+        const changeLineCount = block.replace.split('\n').length;
+        const contextLines = 10;
+        const previewStart = Math.max(0, changeStartLine - contextLines);
+        const previewEnd = Math.min(totalLines, changeStartLine + changeLineCount + contextLines);
+        const previewContent = newLines.slice(previewStart, previewEnd).join('\n');
+        const previewLineCount = previewEnd - previewStart;
+        const remaining = totalLines - previewEnd;
+        const statusLine = `[Reading ${previewLineCount} lines from ${previewStart === 0 ? 'start' : `line ${previewStart}`} (total: ${totalLines} lines, ${remaining} remaining)]\n\n`;
         return {
             content: [{
                     type: "text",
-                    text: `Successfully applied ${expectedReplacements} edit${expectedReplacements > 1 ? 's' : ''} to ${filePath}${warningMessage}`
+                    text: `${statusLine}${previewContent}`
                 }],
+            structuredContent: {
+                fileName: path.basename(resolvedEditPath),
+                filePath: resolvedEditPath,
+                fileType: resolvePreviewFileType(resolvedEditPath),
+            },
         };
     }
     // If exact match found but count doesn't match expected, inform the user
@@ -337,11 +358,17 @@ export async function handleEditBlock(args) {
             try {
                 // parsed.range is guaranteed non-empty string by hasRange check above
                 await handler.editRange(validatedPath, parsed.range, content, parsed.options);
+                const resolvedRangePath = resolveAbsolutePath(parsed.file_path);
                 return {
                     content: [{
                             type: "text",
                             text: `Successfully updated range ${parsed.range} in ${parsed.file_path}`
                         }],
+                    structuredContent: {
+                        fileName: path.basename(resolvedRangePath),
+                        filePath: resolvedRangePath,
+                        fileType: resolvePreviewFileType(resolvedRangePath),
+                    },
                 };
             }
             catch (error) {
@@ -366,11 +393,17 @@ export async function handleEditBlock(args) {
                 expected_replacements: parsed.expected_replacements,
             });
             if (result.success) {
+                const resolvedEditRangePath = resolveAbsolutePath(parsed.file_path);
                 return {
                     content: [{
                             type: "text",
                             text: `Successfully applied ${result.editsApplied} edit(s) to ${parsed.file_path}`
                         }],
+                    structuredContent: {
+                        fileName: path.basename(resolvedEditRangePath),
+                        filePath: resolvedEditRangePath,
+                        fileType: resolvePreviewFileType(resolvedEditRangePath),
+                    },
                 };
             }
             const errorMsg = result.errors?.map(e => e.error).join('; ') || 'Unknown error';

package/dist/tools/filesystem.js

@@ -46,6 +46,45 @@ async function getDefaultReadLength() {
     const config = await configManager.getConfig();
     return config.fileReadLineLimit ?? 1000; // Default to 1000 lines if not set
 }
+/**
+ * Returns a helpful error message when a file operation fails with a permission
+ * or timeout error.
+ *
+ * Lists all common causes without path-based detection — the AI receiving this
+ * error should inspect the path and inform the user which cause is most likely
+ * (e.g. cloud storage folder, network drive, system file, locked file, etc.)
+ */
+function buildPermissionError(filePath, errCode) {
+    const isMac = process.platform === 'darwin';
+    const isTimeout = errCode === 'ETIMEDOUT';
+    const lines = [
+        `Cannot read file — ${isTimeout ? 'operation timed out' : 'permission denied'} (${errCode}).`,
+        `Path: ${filePath}`,
+        ``,
+        `[AI: based on the path above, determine which cause is most likely and explain it to the user.]`,
+        ``,
+        `Possible causes and fixes:`,
+        `  1. File is in cloud storage (Google Drive / iCloud / Dropbox / OneDrive) but not downloaded locally.`,
+        `       → Right-click the file and choose "Download Now", "Make Available Offline", or "Keep on This Device".`,
+        `  2. Cloud storage app is not running or not signed in.`,
+        `       → Open your cloud storage app and make sure it is syncing.`,
+        `  3. File is on a network drive or virtual filesystem that is currently unavailable.`,
+        `       → Check that the network share or drive is mounted and accessible.`,
+        `  4. File has restricted permissions (e.g. system file, locked by another process, or chmod 000).`,
+        `       → Check file permissions or close any app that may have the file open.`,
+        `  5. The app does not have permission to access this location (macOS Full Disk Access).`,
+    ];
+    if (isMac) {
+        lines.push(`       → Go to System Settings → Privacy & Security → Full Disk Access and enable Claude.`);
+        lines.push(`       → To open that pane directly, run in terminal:`);
+        lines.push(`           open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"`);
+        lines.push(`         Then find "Claude" in the list and enable the toggle next to it.`);
+    }
+    else {
+        lines.push(`       → Check that the app has permission to access this file location.`);
+    }
+    return new Error(lines.join('\n'));
+}
 // Initialize allowed directories from configuration
 async function getAllowedDirs() {
     try {
@@ -307,6 +346,35 @@ export async function readFileFromDisk(filePath, options) {
     const validPath = await validatePath(filePath);
     // Get file extension for telemetry
     const fileExtension = getFileExtension(validPath);
+    // Check if path is a directory — return listing instead of EISDIR error
+    try {
+        const stats = await fs.stat(validPath);
+        if (stats.isDirectory()) {
+            const dirListOp = async () => {
+                const entries = await listDirectory(validPath);
+                const listing = entries.join('\n');
+                return {
+                    content: `This is a directory, not a file. Use the list_directory tool instead of read_file for directories.\n\n${listing}`,
+                    mimeType: 'text/plain',
+                    metadata: { isImage: false, isDirectory: true }
+                };
+            };
+            const dirResult = await withTimeout(dirListOp(), FILE_OPERATION_TIMEOUTS.FILE_READ, 'Directory listing fallback', null);
+            if (dirResult === null) {
+                throw new Error(`Directory listing timed out for: ${filePath}`);
+            }
+            return dirResult;
+        }
+    }
+    catch (error) {
+        // If stat itself failed, fall through to the read path which will produce a proper error.
+        // But if this was a directory-listing error, re-throw — don't let it fall into the file-read path.
+        const err = error;
+        if (err.message?.includes('Directory listing') || err.message?.includes('list_directory')) {
+            throw error;
+        }
+        // stat() failed (e.g. ENOENT) — fall through to the read path below
+    }
     // Check file size before attempting to read
     try {
         const stats = await fs.stat(validPath);
@@ -357,7 +425,20 @@ export async function readFileFromDisk(filePath, options) {
         };
     };
     // Execute with timeout
-    const result = await withTimeout(readOperation(), FILE_OPERATION_TIMEOUTS.FILE_READ, `Read file operation for ${filePath}`, null);
+    let result;
+    try {
+        result = await withTimeout(readOperation(), FILE_OPERATION_TIMEOUTS.FILE_READ, `Read file operation for ${filePath}`, null);
+    }
+    catch (error) {
+        const err = error;
+        // withTimeout rejects with a plain string "__ERROR__: ... timed out after N seconds"
+        // when defaultValue is null — it has no .code property, so check for that too.
+        const isWithTimeoutString = typeof error === 'string' && error.startsWith('__ERROR__:');
+        if (isWithTimeoutString || err.code === 'EPERM' || err.code === 'EACCES' || err.code === 'ETIMEDOUT') {
+            throw buildPermissionError(filePath, isWithTimeoutString ? 'ETIMEDOUT' : err.code);
+        }
+        throw error;
+    }
     if (result == null) {
         // Handles the impossible case where withTimeout resolves to null instead of throwing
         throw new Error('Failed to read the file');
@@ -490,9 +571,16 @@ export async function listDirectory(dirPath, depth = 2) {
             entries = await fs.readdir(currentPath, { withFileTypes: true });
         }
         catch (error) {
-            // If we can't read this directory (permission denied), show as denied
+            const err = error;
             const displayPath = relativePath || path.basename(currentPath);
-            results.push(`[DENIED] ${displayPath}`);
+            // Keep [DENIED] prefix so UI parser regex still matches.
+            // Append a hint for permission/timeout errors so user gets context.
+            if (err.code === 'EPERM' || err.code === 'EACCES' || err.code === 'ETIMEDOUT') {
+                results.push(`[DENIED] ${displayPath} — not accessible (permission denied, cloud-only file, or Full Disk Access not granted)`);
+            }
+            else {
+                results.push(`[DENIED] ${displayPath}`);
+            }
             return;
         }
         // Apply filtering for nested directories (not top level)

package/dist/tools/improved-process-tools.js

@@ -27,7 +27,8 @@ async function executeNodeCode(code, timeout_ms = 30000) {
         const result = await new Promise((resolve) => {
             const proc = spawn(process.execPath, [tempFile], {
                 cwd: mcpRoot,
-                timeout: timeout_ms
+                timeout: timeout_ms,
+                windowsHide: true // Prevent visible console windows on Windows
             });
             let stdout = '';
             let stderr = '';