@wonderwhy-er/desktop-commander 0.1.39 → 0.2.1

package/README.md

@@ -58,6 +58,10 @@ Execute long-running terminal commands on your computer and manage processes thr
   - Multiple file support
   - Pattern-based replacements
   - vscode-ripgrep based recursive code or text search in folders
+- Comprehensive audit logging:
+  - All tool calls are automatically logged
+  - Log rotation with 10MB size limit
+  - Detailed timestamps and arguments
 
 ## Installation
 First, ensure you've downloaded and installed the [Claude Desktop app](https://claude.ai/download) and you have [npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
@@ -140,24 +144,24 @@ The server provides a comprehensive set of tools organized into several categori
 
 | Category | Tool | Description |
 |----------|------|-------------|
-| **Configuration** | `get_config` | Get the complete server configuration as JSON (includes blockedCommands, defaultShell, allowedDirectories) |
-| | `set_config_value` | Set a specific configuration value by key. Available settings: <br>• `blockedCommands`: Array of shell commands that cannot be executed<br>• `defaultShell`: Shell to use for commands (e.g., bash, zsh, powershell)<br>• `allowedDirectories`: Array of filesystem paths the server can access for file operations (⚠️ terminal commands can still access files outside these directories) |
+| **Configuration** | `get_config` | Get the complete server configuration as JSON (includes blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled) |
+| | `set_config_value` | Set a specific configuration value by key. Available settings: <br>• `blockedCommands`: Array of shell commands that cannot be executed<br>• `defaultShell`: Shell to use for commands (e.g., bash, zsh, powershell)<br>• `allowedDirectories`: Array of filesystem paths the server can access for file operations (⚠️ terminal commands can still access files outside these directories)<br>• `fileReadLineLimit`: Maximum lines to read at once (default: 1000)<br>• `fileWriteLineLimit`: Maximum lines to write at once (default: 50)<br>• `telemetryEnabled`: Enable/disable telemetry (boolean) |
 | **Terminal** | `execute_command` | Execute a terminal command with configurable timeout and shell selection |
 | | `read_output` | Read new output from a running terminal session |
 | | `force_terminate` | Force terminate a running terminal session |
 | | `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 (supports text and images) |
+| **Filesystem** | `read_file` | Read contents from local filesystem or URLs with line-based pagination (supports offset and length parameters) |
 | | `read_multiple_files` | Read multiple files simultaneously |
-| | `write_file` | Completely replace file contents (best for large changes) |
+| | `write_file` | Write file contents with options for rewrite or append mode (uses configurable line limits) |
 | | `create_directory` | Create a new directory or ensure it exists |
 | | `list_directory` | Get detailed listing of files and directories |
 | | `move_file` | Move or rename files and directories |
 | | `search_files` | Find files by name using case-insensitive substring matching |
 | | `search_code` | Search for text/code patterns within file contents using ripgrep |
 | | `get_file_info` | Retrieve detailed metadata about a file or directory |
-| **Text Editing** | `edit_block` | Apply surgical text replacements (best for changes <20% of file size) |
+| **Text Editing** | `edit_block` | Apply targeted text replacements with enhanced prompting for smaller edits (includes character-level diff feedback) |
 
 ### Tool Usage Examples
 
@@ -181,6 +185,18 @@ console.log("new message");
 >>>>>>> REPLACE
 ```
 
+### Enhanced Edit Block Features
+
+The `edit_block` tool includes several enhancements for better reliability:
+
+1. **Improved Prompting**: Tool descriptions now emphasize making multiple small, focused edits rather than one large change
+2. **Fuzzy Search Fallback**: When exact matches fail, it performs fuzzy search and provides detailed feedback
+3. **Character-level Diffs**: Shows exactly what's different using `{-removed-}{+added+}` format
+4. **Multiple Occurrence Support**: Can replace multiple instances with `expected_replacements` parameter
+5. **Comprehensive Logging**: All fuzzy searches are logged for analysis and debugging
+
+When a search fails, you'll see detailed information about the closest match found, including similarity percentage, execution time, and character differences. All these details are automatically logged for later analysis using the fuzzy search log tools.
+
 ### URL Support
 - `read_file` can now fetch content from both local files and URLs
 - Example: `read_file` with `isUrl: true` parameter to read from web resources
@@ -189,6 +205,69 @@ console.log("new message");
 - Claude can see and analyze the actual image content
 - Default 30-second timeout for URL requests
 
+## Fuzzy Search Log Analysis (npm scripts)
+
+The fuzzy search logging system includes convenient npm scripts for analyzing logs outside of the MCP environment:
+
+```bash
+# View recent fuzzy search logs
+npm run logs:view -- --count 20
+
+# Analyze patterns and performance
+npm run logs:analyze -- --threshold 0.8
+
+# Export logs to CSV or JSON
+npm run logs:export -- --format json --output analysis.json
+
+# Clear all logs (with confirmation)
+npm run logs:clear
+```
+
+For detailed documentation on these scripts, see [scripts/README.md](scripts/README.md).
+
+## Fuzzy Search Logs
+
+Desktop Commander includes comprehensive logging for fuzzy search operations in the `edit_block` tool. When an exact match isn't found, the system performs a fuzzy search and logs detailed information for analysis.
+
+### What Gets Logged
+
+Every fuzzy search operation logs:
+- **Search and found text**: The text you're looking for vs. what was found
+- **Similarity score**: How close the match is (0-100%)
+- **Execution time**: How long the search took
+- **Character differences**: Detailed diff showing exactly what's different
+- **File metadata**: Extension, search/found text lengths
+- **Character codes**: Specific character codes causing differences
+
+### Log Location
+
+Logs are automatically saved to:
+- **macOS/Linux**: `~/.claude-server-commander-logs/fuzzy-search.log`
+- **Windows**: `%USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log`
+
+### What You'll Learn
+
+The fuzzy search logs help you understand:
+1. **Why exact matches fail**: Common issues like whitespace differences, line endings, or character encoding
+2. **Performance patterns**: How search complexity affects execution time
+3. **File type issues**: Which file extensions commonly have matching problems
+4. **Character encoding problems**: Specific character codes that cause diffs
+
+## Audit Logging
+
+Desktop Commander now includes comprehensive logging for all tool calls:
+
+### What Gets Logged
+- Every tool call is logged with timestamp, tool name, and arguments (sanitized for privacy)
+- Logs are rotated automatically when they reach 10MB in size
+
+### Log Location
+Logs are saved to:
+- **macOS/Linux**: `~/.claude-server-commander/claude_tool_call.log`
+- **Windows**: `%USERPROFILE%\.claude-server-commander\claude_tool_call.log`
+
+This audit trail helps with debugging, security monitoring, and understanding how Claude is interacting with your system.
+
 ## Handling Long-Running Commands
 
 For commands that may take a while:
@@ -297,6 +376,8 @@ 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
@@ -333,11 +414,13 @@ The following features are currently being explored:
     <ul style="list-style-type: none; padding: 0;">
       <li>🌟 <a href="https://github.com/sponsors/wonderwhy-er"><strong>GitHub Sponsors</strong></a> - Recurring support</li>
       <li>☕ <a href="https://www.buymeacoffee.com/wonderwhyer"><strong>Buy Me A Coffee</strong></a> - One-time contributions</li>
+      <li>💖 <a href="https://www.patreon.com/c/EduardsRuzga"><strong>Patreon</strong></a> - Become a patron and support us monthly</li>
       <li>⭐ <a href="https://github.com/wonderwhy-er/DesktopCommanderMCP"><strong>Star on GitHub</strong></a> - Help others discover the project</li>
     </ul>
   </div>
 </div>
 
+
 ### Supporters Hall of Fame
 
 Generous supporters are featured here. Thank you for helping make this project possible!

package/dist/config-manager.d.ts

@@ -3,6 +3,8 @@ export interface ServerConfig {
     defaultShell?: string;
     allowedDirectories?: string[];
     telemetryEnabled?: boolean;
+    fileWriteLineLimit?: number;
+    fileReadLineLimit?: number;
     [key: string]: any;
 }
 /**

package/dist/config-manager.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { existsSync } from 'fs';
 import { mkdir } from 'fs/promises';
 import os from 'os';
+import { VERSION } from './version.js';
 import { CONFIG_FILE } from './config.js';
 /**
  * Singleton config manager for the server
@@ -39,6 +40,7 @@ class ConfigManager {
                 this.config = this.getDefaultConfig();
                 await this.saveConfig();
             }
+            this.config['version'] = VERSION;
             this.initialized = true;
         }
         catch (error) {
@@ -101,7 +103,9 @@ class ConfigManager {
             ],
             defaultShell: os.platform() === 'win32' ? 'powershell.exe' : 'bash',
             allowedDirectories: [],
-            telemetryEnabled: true // Default to opt-out approach (telemetry on by default)
+            telemetryEnabled: true, // Default to opt-out approach (telemetry on by default)
+            fileWriteLineLimit: 50, // Default line limit for file write operations (changed from 100)
+            fileReadLineLimit: 1000 // Default line limit for file read operations (changed from character-based)
         };
     }
     /**

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 export declare const USER_HOME: string;
 export declare const CONFIG_FILE: string;
 export declare const TOOL_CALL_FILE: string;
+export declare const TOOL_CALL_FILE_MAX_SIZE: number;
 export declare const DEFAULT_COMMAND_TIMEOUT = 1000;

package/dist/config.js

@@ -6,4 +6,5 @@ const CONFIG_DIR = path.join(USER_HOME, '.claude-server-commander');
 // Paths relative to the config directory
 export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 export const TOOL_CALL_FILE = path.join(CONFIG_DIR, 'claude_tool_call.log');
+export const TOOL_CALL_FILE_MAX_SIZE = 1024 * 1024 * 10; // 10 MB
 export const DEFAULT_COMMAND_TIMEOUT = 1000; // milliseconds

package/dist/handlers/filesystem-handlers.js

@@ -1,6 +1,7 @@
 import { readFile, readMultipleFiles, writeFile, createDirectory, listDirectory, moveFile, searchFiles, getFileInfo } 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, SearchFilesArgsSchema, GetFileInfoArgsSchema } from '../tools/schemas.js';
 /**
  * Helper function to check if path contains an error
@@ -19,9 +20,22 @@ function getErrorFromPath(path) {
  */
 export async function handleReadFile(args) {
     const HANDLER_TIMEOUT = 60000; // 60 seconds total operation timeout
+    // 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);
-        const fileResult = await readFile(parsed.path, parsed.isUrl);
+        // Get the configuration for file read limits
+        const config = await configManager.getConfig();
+        if (!config) {
+            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) {
             // For image files, return as an image content type
             return {
@@ -103,9 +117,29 @@ export async function handleReadMultipleFiles(args) {
 export async function handleWriteFile(args) {
     try {
         const parsed = WriteFileArgsSchema.parse(args);
-        await writeFile(parsed.path, parsed.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 was written with warning: Line count limit exceeded: ${lineCount} lines (maximum: ${MAX_LINES}).
+            
+SOLUTION: Split your content into smaller chunks:
+1. First chunk: write_file(path, firstChunk, {mode: 'rewrite'})
+2. Additional chunks: write_file(path, nextChunk, {mode: 'append'})`;
+        }
+        // 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';
         return {
-            content: [{ type: "text", text: `Successfully wrote to ${parsed.path}` }],
+            content: [{
+                    type: "text",
+                    text: `Successfully ${modeMessage} ${parsed.path} (${lineCount} lines) ${errorMessage}`
+                }],
         };
     }
     catch (error) {

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

@@ -0,0 +1,13 @@
+import { ServerResult } from '../types.js';
+/**
+ * View recent fuzzy search logs
+ */
+export declare function handleViewFuzzySearchLogs(args: unknown): Promise<ServerResult>;
+/**
+ * Analyze fuzzy search logs to identify patterns and issues
+ */
+export declare function handleAnalyzeFuzzySearchLogs(args: unknown): Promise<ServerResult>;
+/**
+ * Clear fuzzy search logs
+ */
+export declare function handleClearFuzzySearchLogs(args: unknown): Promise<ServerResult>;

package/dist/handlers/fuzzy-search-log-handlers.js

@@ -0,0 +1,179 @@
+import { fuzzySearchLogger } from '../utils/fuzzySearchLogger.js';
+import { createErrorResponse } from '../error-handlers.js';
+import { ViewFuzzySearchLogsArgsSchema, AnalyzeFuzzySearchLogsArgsSchema, ClearFuzzySearchLogsArgsSchema } from '../tools/schemas.js';
+/**
+ * View recent fuzzy search logs
+ */
+export async function handleViewFuzzySearchLogs(args) {
+    try {
+        const parsed = ViewFuzzySearchLogsArgsSchema.parse(args);
+        const logs = await fuzzySearchLogger.getRecentLogs(parsed.count);
+        const logPath = await fuzzySearchLogger.getLogPath();
+        if (logs.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No fuzzy search logs found. Log file location: ${logPath}`
+                    }],
+            };
+        }
+        // Parse and format logs for better readability
+        const formattedLogs = logs.map((log, index) => {
+            const parts = log.split('\t');
+            if (parts.length >= 16) {
+                const [timestamp, searchText, foundText, similarity, executionTime, exactMatchCount, expectedReplacements, fuzzyThreshold, belowThreshold, diff, searchLength, foundLength, fileExtension, characterCodes, uniqueCharacterCount, diffLength] = parts;
+                return `
+--- Log Entry ${index + 1} ---
+Timestamp: ${timestamp}
+File Extension: ${fileExtension}
+Search Text: ${searchText.replace(/\\n/g, '\n').replace(/\\t/g, '\t')}
+Found Text: ${foundText.replace(/\\n/g, '\n').replace(/\\t/g, '\t')}
+Similarity: ${(parseFloat(similarity) * 100).toFixed(2)}%
+Execution Time: ${parseFloat(executionTime).toFixed(2)}ms
+Exact Match Count: ${exactMatchCount}
+Expected Replacements: ${expectedReplacements}
+Below Threshold: ${belowThreshold}
+Diff: ${diff.replace(/\\n/g, '\n').replace(/\\t/g, '\t')}
+Search Length: ${searchLength}
+Found Length: ${foundLength}
+Character Codes: ${characterCodes}
+Unique Characters: ${uniqueCharacterCount}
+Diff Length: ${diffLength}
+`;
+            }
+            return `Malformed log entry: ${log}`;
+        }).join('\n');
+        return {
+            content: [{
+                    type: "text",
+                    text: `Recent Fuzzy Search Logs (${logs.length} entries):\n\n${formattedLogs}\n\nLog file location: ${logPath}`
+                }],
+        };
+    }
+    catch (error) {
+        return createErrorResponse(`Failed to view fuzzy search logs: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Analyze fuzzy search logs to identify patterns and issues
+ */
+export async function handleAnalyzeFuzzySearchLogs(args) {
+    try {
+        const parsed = AnalyzeFuzzySearchLogsArgsSchema.parse(args);
+        const logs = await fuzzySearchLogger.getRecentLogs(100); // Analyze more logs
+        const logPath = await fuzzySearchLogger.getLogPath();
+        if (logs.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No fuzzy search logs found. Log file location: ${logPath}`
+                    }],
+            };
+        }
+        // Parse logs and gather statistics
+        let totalEntries = 0;
+        let exactMatches = 0;
+        let fuzzyMatches = 0;
+        let failures = 0;
+        let belowThresholdCount = 0;
+        const executionTimes = [];
+        const similarities = [];
+        const fileExtensions = new Map();
+        const commonCharacterCodes = new Map();
+        for (const log of logs) {
+            const parts = log.split('\t');
+            if (parts.length >= 16) {
+                totalEntries++;
+                const [timestamp, searchText, foundText, similarity, executionTime, exactMatchCount, expectedReplacements, fuzzyThreshold, belowThreshold, diff, searchLength, foundLength, fileExtension, characterCodes, uniqueCharacterCount, diffLength] = parts;
+                const simValue = parseFloat(similarity);
+                const execTime = parseFloat(executionTime);
+                const exactCount = parseInt(exactMatchCount);
+                const belowThresh = belowThreshold === 'true';
+                if (exactCount > 0) {
+                    exactMatches++;
+                }
+                else if (simValue >= parsed.failureThreshold) {
+                    fuzzyMatches++;
+                }
+                else {
+                    failures++;
+                }
+                if (belowThresh) {
+                    belowThresholdCount++;
+                }
+                executionTimes.push(execTime);
+                similarities.push(simValue);
+                // Track file extensions
+                fileExtensions.set(fileExtension, (fileExtensions.get(fileExtension) || 0) + 1);
+                // Track character codes that appear in diffs
+                if (characterCodes && characterCodes !== '') {
+                    const codes = characterCodes.split(',');
+                    for (const code of codes) {
+                        const key = code.split(':')[0];
+                        commonCharacterCodes.set(key, (commonCharacterCodes.get(key) || 0) + 1);
+                    }
+                }
+            }
+        }
+        // Calculate statistics
+        const avgExecutionTime = executionTimes.reduce((a, b) => a + b, 0) / executionTimes.length;
+        const avgSimilarity = similarities.reduce((a, b) => a + b, 0) / similarities.length;
+        // Sort by frequency
+        const sortedExtensions = Array.from(fileExtensions.entries()).sort((a, b) => b[1] - a[1]);
+        const sortedCharCodes = Array.from(commonCharacterCodes.entries()).sort((a, b) => b[1] - a[1]);
+        const analysis = `
+=== Fuzzy Search Analysis ===
+
+Total Entries: ${totalEntries}
+Exact Matches: ${exactMatches} (${((exactMatches / totalEntries) * 100).toFixed(2)}%)
+Fuzzy Matches: ${fuzzyMatches} (${((fuzzyMatches / totalEntries) * 100).toFixed(2)}%)
+Failures: ${failures} (${((failures / totalEntries) * 100).toFixed(2)}%)
+Below Threshold: ${belowThresholdCount} (${((belowThresholdCount / totalEntries) * 100).toFixed(2)}%)
+
+Performance:
+Average Execution Time: ${avgExecutionTime.toFixed(2)}ms
+Average Similarity: ${(avgSimilarity * 100).toFixed(2)}%
+
+File Extensions (Top 5):
+${sortedExtensions.slice(0, 5).map(([ext, count]) => `${ext || 'none'}: ${count} times`).join('\n')}
+
+Common Character Codes in Diffs (Top 5):
+${sortedCharCodes.slice(0, 5).map(([code, count]) => {
+            const charCode = parseInt(code);
+            const char = String.fromCharCode(charCode);
+            const display = charCode < 32 || charCode > 126 ? `\\x${charCode.toString(16).padStart(2, '0')}` : char;
+            return `${code} [${display}]: ${count} times`;
+        }).join('\n')}
+
+Log file location: ${logPath}
+`;
+        return {
+            content: [{
+                    type: "text",
+                    text: analysis
+                }],
+        };
+    }
+    catch (error) {
+        return createErrorResponse(`Failed to analyze fuzzy search logs: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Clear fuzzy search logs
+ */
+export async function handleClearFuzzySearchLogs(args) {
+    try {
+        ClearFuzzySearchLogsArgsSchema.parse(args);
+        await fuzzySearchLogger.clearLog();
+        const logPath = await fuzzySearchLogger.getLogPath();
+        return {
+            content: [{
+                    type: "text",
+                    text: `Fuzzy search logs cleared. Log file location: ${logPath}`
+                }],
+        };
+    }
+    catch (error) {
+        return createErrorResponse(`Failed to clear fuzzy search logs: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}