@wonderwhy-er/desktop-commander 0.2.23 → 0.2.24

package/README.md

@@ -39,7 +39,9 @@ Execute long-running terminal commands on your computer and manage processes thr
 
 - **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 files**
+- **Instant data analysis - just ask to analyze CSV/JSON/Excel files**
+- **Native Excel file support** - Read, write, edit, and search Excel files (.xlsx, .xls, .xlsm) without external tools
+- **PDF support** - Read PDFs with text extraction, create new PDFs from markdown, modify existing PDFs
 - **Interact with running processes (SSH, databases, development servers)**
 - Execute terminal commands with output streaming
 - Command timeout and background execution support
@@ -50,10 +52,10 @@ Execute long-running terminal commands on your computer and manage processes thr
   - Update multiple settings at once
   - Dynamic configuration changes without server restart
 - Full filesystem operations:
-  - Read/write files
+  - Read/write files (text, Excel, PDF)
   - Create/list directories
   - Move files/directories
-  - Search files
+  - Search files and content (including Excel content)
   - Get file metadata
   - **Negative offset file reading**: Read from end of files using negative offset values (like Unix tail)
 - Code editing capabilities:
@@ -420,18 +422,19 @@ The server provides a comprehensive set of tools organized into several categori
 | | `list_sessions` | List all active terminal sessions |
 | | `list_processes` | List all running processes with detailed information |
 | | `kill_process` | Terminate a running process by PID |
-| **Filesystem** | `read_file` | Read contents from local filesystem or URLs with line-based pagination (supports positive/negative offset and length parameters) |
+| **Filesystem** | `read_file` | Read contents from local filesystem, URLs, Excel files (.xlsx, .xls, .xlsm), and PDFs with line/page-based pagination |
 | | `read_multiple_files` | Read multiple files simultaneously |
-| | `write_file` | Write file contents with options for rewrite or append mode (uses configurable line limits) |
+| | `write_file` | Write file contents with options for rewrite or append mode. Supports Excel files (JSON 2D array format). For PDFs, use `write_pdf` |
+| | `write_pdf` | Create new PDF files from markdown or modify existing PDFs (insert/delete pages). Supports HTML/CSS styling and SVG graphics |
 | | `create_directory` | Create a new directory or ensure it exists |
 | | `list_directory` | Get detailed recursive listing of files and directories (supports depth parameter, default depth=2) |
 | | `move_file` | Move or rename files and directories |
-| | `start_search` | Start streaming search for files by name or content patterns (unified ripgrep-based search) |
+| | `start_search` | Start streaming search for files by name or content patterns (searches text files and Excel content) |
 | | `get_more_search_results` | Get paginated results from active search with offset support |
 | | `stop_search` | Stop an active search gracefully |
 | | `list_searches` | List all active search sessions |
-| | `get_file_info` | Retrieve detailed metadata about a file or directory |
-| **Text Editing** | `edit_block` | Apply targeted text replacements with enhanced prompting for smaller edits (includes character-level diff feedback) |
+| | `get_file_info` | Retrieve detailed metadata about a file or directory (includes sheet info for Excel files) |
+| **Text Editing** | `edit_block` | Apply targeted text replacements for text files, or range-based cell updates for Excel files |
 | **Analytics** | `get_usage_stats` | Get usage statistics for your own insight |
 | | `get_recent_tool_calls` | Get recent tool call history with arguments and outputs for debugging and context recovery |
 | | `give_feedback_to_desktop_commander` | Open feedback form in browser to provide feedback to Desktop Commander Team |
@@ -760,33 +763,6 @@ This project extends the MCP Filesystem Server to enable:
 
 Created as part of exploring Claude MCPs: https://youtube.com/live/TlbjFDbl5Us
 
-## DONE
-- **20-05-2025 v0.1.40 Release** - Added audit logging for all tool calls, improved line-based file operations, enhanced edit_block with better prompting for smaller edits, added explicit telemetry opt-out prompting 
-- **05-05-2025 Fuzzy Search Logging** - Added comprehensive logging system for fuzzy search operations with detailed analysis tools, character-level diffs, and performance metrics to help debug edit_block failures
-- **29-04-2025 Telemetry Opt Out through configuration** - There is now setting to disable telemetry in config, ask in chat
-- **23-04-2025 Enhanced edit functionality** - Improved format, added fuzzy search and multi-occurrence replacements, should fail less and use edit block more often
-- **16-04-2025 Better configurations** - Improved settings for allowed paths, commands and shell environments
-- **14-04-2025 Windows environment fixes** - Resolved issues specific to Windows platforms
-- **14-04-2025 Linux improvements** - Enhanced compatibility with various Linux distributions
-- **12-04-2025 Better allowed directories and blocked commands** - Improved security and path validation for file read/write and terminal command restrictions.
-Terminal still can access files ignoring allowed directories.
-- **11-04-2025 Shell configuration** - Added ability to configure preferred shell for command execution
-- **07-04-2025 Added URL support** - `read_file` command can now fetch content from URLs
-- **28-03-2025 Fixed "Watching /" JSON error** - Implemented custom stdio transport to handle non-JSON messages and prevent server crashes
-- **25-03-2025 Better code search** ([merged](https://github.com/wonderwhy-er/ClaudeServerCommander/pull/17)) - Enhanced code exploration with context-aware results
-
-## Roadmap
-
-The following features are currently being explored:
-
-- **Support for WSL** - Windows Subsystem for Linux integration
-- **Support for SSH** - Remote server command execution
-- **Better file support for formats like CSV/PDF**
-- **Terminal sandboxing for Mac/Linux/Windows for better security**
-- **File reading modes** - For example, allow reading HTML as plain text or markdown
-- **Interactive shell support** - ssh, node/python repl
-- **Improve large file reading and writing**
-
 ## Support Desktop Commander
 
 <div align="center">
@@ -931,28 +907,11 @@ Please create a [GitHub Issue](https://github.com/wonderwhy-er/DesktopCommanderM
 
 ## Data Collection & Privacy
 
-Desktop Commander collects limited anonymous telemetry data to help improve the tool. No personal information, file contents, file paths, or command arguments are collected.
-
-### Usage Analytics (Local Only)
-- **Local usage statistics** are always collected and stored locally on your machine for functionality and the `get_usage_stats` tool
-- Use the `get_usage_stats` tool to view your personal usage patterns, success rates, and performance metrics
-- **This data is NOT sent anywhere** - it remains on your computer for your personal insights
-
-### Feedback System
-- Use the `give_feedback_to_desktop_commander` tool to provide feedback about Desktop Commander
-- Opens a browser-based feedback form to send suggestions and feedback to the development team
-- Only basic usage statistics (tool call count, days using, platform) are pre-filled to provide context but you can remove them
-
-### External Telemetry Opt-Out
-External telemetry (sent to analytics services) is enabled by default but can be disabled:
-
-1. Open the chat and simply ask:
-   **"Disable telemetry"**
-2. The chatbot will update your settings automatically.
+Desktop Commander collects limited, pseudonymous telemetry to improve the tool. We do not collect file contents, file paths, or command arguments.
 
-**Note:** This only disables external telemetry. Local usage analytics remain active for tool functionality but is not share externally
+**Opt-out:** Ask Claude to "disable Desktop Commander telemetry" or set `"telemetryEnabled": false` in your config.
 
-For complete details about data collection, please see our [Privacy Policy](https://legal.desktopcommander.app/privacy_desktop_commander_mcp).
+For complete details, see our [Privacy Policy](PRIVACY.md).
 
 ## Verifications
 [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/25ff7a06-58bc-40b8-bd79-ebb715140f1a)

package/dist/custom-stdio.d.ts

@@ -33,6 +33,7 @@ export declare class FilteredStdioServerTransport extends StdioServerTransport {
     private sendLogNotification;
     /**
      * Public method to send log notifications from anywhere in the application
+     * Now properly buffers messages before MCP initialization to avoid breaking stdio protocol
      */
     sendLog(level: "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug", message: string, data?: any): void;
     /**

package/dist/custom-stdio.js

@@ -233,12 +233,23 @@ export class FilteredStdioServerTransport extends StdioServerTransport {
     }
     /**
      * Public method to send log notifications from anywhere in the application
+     * Now properly buffers messages before MCP initialization to avoid breaking stdio protocol
      */
     sendLog(level, message, data) {
         // Skip if notifications are disabled (e.g., for Cline)
         if (this.disableNotifications) {
             return;
         }
+        // Buffer messages before initialization to avoid breaking MCP protocol
+        // MCP requires client to send first message - server cannot write to stdout before that
+        if (!this.isInitialized) {
+            this.messageBuffer.push({
+                level,
+                args: [data ? { message, ...data } : message],
+                timestamp: Date.now()
+            });
+            return;
+        }
         try {
             const notification = {
                 jsonrpc: "2.0",
@@ -269,6 +280,10 @@ export class FilteredStdioServerTransport extends StdioServerTransport {
      * Send a progress notification (useful for long-running operations)
      */
     sendProgress(token, value, total) {
+        // Don't send progress before initialization - would break MCP protocol
+        if (!this.isInitialized) {
+            return;
+        }
         try {
             const notification = {
                 jsonrpc: "2.0",
@@ -299,6 +314,10 @@ export class FilteredStdioServerTransport extends StdioServerTransport {
      * Send a custom notification with any method name
      */
     sendCustomNotification(method, params) {
+        // Don't send custom notifications before initialization - would break MCP protocol
+        if (!this.isInitialized) {
+            return;
+        }
         try {
             const notification = {
                 jsonrpc: "2.0",

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

@@ -27,3 +27,7 @@ export declare function handleMoveFile(args: unknown): Promise<ServerResult>;
  * Handle get_file_info command
  */
 export declare function handleGetFileInfo(args: unknown): Promise<ServerResult>;
+/**
+ * Handle write_pdf command
+ */
+export declare function handleWritePdf(args: unknown): Promise<ServerResult>;

package/dist/handlers/filesystem-handlers.js

@@ -1,8 +1,8 @@
-import { readFile, readMultipleFiles, writeFile, createDirectory, listDirectory, moveFile, getFileInfo } from '../tools/filesystem.js';
+import { readFile, readMultipleFiles, writeFile, createDirectory, listDirectory, moveFile, getFileInfo, writePdf } 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 } from '../tools/schemas.js';
+import { ReadFileArgsSchema, ReadMultipleFilesArgsSchema, WriteFileArgsSchema, CreateDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, GetFileInfoArgsSchema, WritePdfArgsSchema } from '../tools/schemas.js';
 /**
  * Helper function to check if path contains an error
  */
@@ -32,12 +32,52 @@ export async function handleReadFile(args) {
             return createErrorResponse('Configuration not available');
         }
         const defaultLimit = config.fileReadLineLimit ?? 1000;
-        // Use the provided limits or defaults
-        const offset = parsed.offset ?? 0;
-        const length = parsed.length ?? defaultLimit;
-        const fileResult = await readFile(parsed.path, parsed.isUrl, offset, length);
-        if (fileResult.isImage) {
+        // 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
+        };
+        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
+                ]
+            };
+        }
+        // Handle image files
+        if (fileResult.metadata?.isImage) {
             // For image files, return as an image content type
+            // Content should already be base64-encoded string from handler
+            const imageData = typeof fileResult.content === 'string'
+                ? fileResult.content
+                : fileResult.content.toString('base64');
             return {
                 content: [
                     {
@@ -46,7 +86,7 @@ export async function handleReadFile(args) {
                     },
                     {
                         type: "image",
-                        data: fileResult.content,
+                        data: imageData,
                         mimeType: fileResult.mimeType
                     }
                 ],
@@ -54,8 +94,11 @@ export async function handleReadFile(args) {
         }
         else {
             // For all other files, return as text
+            const textContent = typeof fileResult.content === 'string'
+                ? fileResult.content
+                : fileResult.content.toString('utf8');
             return {
-                content: [{ type: "text", text: fileResult.content }],
+                content: [{ type: "text", text: textContent }],
             };
         }
     };
@@ -78,6 +121,9 @@ export async function handleReadMultipleFiles(args) {
         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)'}`;
         }
@@ -92,7 +138,22 @@ export async function handleReadMultipleFiles(args) {
     // Add each file content
     for (const result of fileResults) {
         if (!result.error && result.content !== undefined) {
-            if (result.isImage && result.mimeType) {
+            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",
@@ -196,6 +257,33 @@ export async function handleMoveFile(args) {
         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
  */
@@ -203,12 +291,14 @@ 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: Object.entries(info)
-                        .map(([key, value]) => `${key}: ${value}`)
-                        .join('\n')
+                    text: formattedText
                 }],
         };
     }
@@ -217,5 +307,21 @@ export async function handleGetFileInfo(args) {
         return createErrorResponse(errorMessage);
     }
 }
-// The listAllowedDirectories function has been removed
 // 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/node-handlers.d.ts

@@ -0,0 +1,6 @@
+import { ServerResult } from '../types.js';
+/**
+ * Handle execute_node command
+ * Executes Node.js code using the same Node runtime as the MCP
+ */
+export declare function handleExecuteNode(args: unknown): Promise<ServerResult>;

package/dist/handlers/node-handlers.js

@@ -0,0 +1,73 @@
+import { spawn } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { ExecuteNodeArgsSchema } from '../tools/schemas.js';
+// Get the directory where the MCP is installed (for requiring packages like exceljs)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const mcpRoot = path.resolve(__dirname, '..', '..');
+/**
+ * Handle execute_node command
+ * Executes Node.js code using the same Node runtime as the MCP
+ */
+export async function handleExecuteNode(args) {
+    const parsed = ExecuteNodeArgsSchema.parse(args);
+    const { code, timeout_ms } = parsed;
+    // Create temp file IN THE MCP DIRECTORY so ES module imports resolve correctly
+    // (ES modules resolve packages relative to file location, not NODE_PATH or cwd)
+    const tempFile = path.join(mcpRoot, `.mcp-exec-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`);
+    // User code runs directly - imports will resolve from mcpRoot/node_modules
+    const wrappedCode = code;
+    try {
+        await fs.writeFile(tempFile, wrappedCode, 'utf8');
+        const result = await new Promise((resolve) => {
+            const proc = spawn(process.execPath, [tempFile], {
+                cwd: mcpRoot,
+                timeout: timeout_ms
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', (exitCode) => {
+                resolve({ stdout, stderr, exitCode: exitCode ?? 1 });
+            });
+            proc.on('error', (err) => {
+                resolve({ stdout, stderr: stderr + '\n' + err.message, exitCode: 1 });
+            });
+        });
+        // Clean up temp file
+        await fs.unlink(tempFile).catch(() => { });
+        if (result.exitCode !== 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Execution failed (exit code ${result.exitCode}):\n${result.stderr}\n${result.stdout}`
+                    }],
+                isError: true
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: result.stdout || '(no output)'
+                }]
+        };
+    }
+    catch (error) {
+        // Clean up temp file on error
+        await fs.unlink(tempFile).catch(() => { });
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to execute Node.js code: ${error instanceof Error ? error.message : String(error)}`
+                }],
+            isError: true
+        };
+    }
+}

package/dist/index.js

@@ -31,6 +31,11 @@ async function runServer() {
         }
         // Set global flag for onboarding control
         global.disableOnboarding = DISABLE_ONBOARDING;
+        // Create transport FIRST so all logging gets properly buffered
+        // This must happen before any code that might use logger.*
+        const transport = new FilteredStdioServerTransport();
+        // Export transport for use throughout the application
+        global.mcpTransport = transport;
         try {
             deferLog('info', 'Loading configuration...');
             await configManager.loadConfig();
@@ -47,9 +52,6 @@ async function runServer() {
             deferLog('warning', 'Continuing with in-memory configuration only');
             // Continue anyway - we'll use an in-memory config
         }
-        const transport = new FilteredStdioServerTransport();
-        // Export transport for use throughout the application
-        global.mcpTransport = transport;
         // Handle uncaught exceptions
         process.on('uncaughtException', async (error) => {
             const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/search-manager.d.ts

@@ -83,6 +83,24 @@ export interface SearchSessionOptions {
         runtime: number;
         totalResults: number;
     }>;
+    /**
+     * Search Excel files for content matches
+     * Called during content search to include Excel files alongside text files
+     * Searches ALL sheets in each Excel file (row-wise for cross-column matching)
+     *
+     * TODO: Refactor - Extract Excel search logic to separate module (src/utils/search/excel-search.ts)
+     * 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
+     */
+    private searchExcelFiles;
+    /**
+     * Find all Excel files in a directory recursively
+     */
+    private findExcelFiles;
+    /**
+     * Extract context around a match for display (show surrounding text)
+     */
+    private getMatchContext;
     /**
      * Clean up completed sessions older than specified time
      * Called automatically by cleanup interval
@@ -101,6 +119,13 @@ export interface SearchSessionOptions {
      * Detect if pattern contains glob wildcards
      */
     private isGlobPattern;
+    /**
+     * Determine if Excel search should be included based on context
+     * Only searches Excel files when:
+     * - filePattern explicitly targets Excel files (*.xlsx, *.xls, *.xlsm, *.xlsb)
+     * - or the rootPath itself is an Excel file
+     */
+    private shouldIncludeExcelSearch;
     private buildRipgrepArgs;
     private setupProcessHandlers;
     private processBufferedOutput;