How Desktop Commander MCP's Fuzzy Search Logger Analyzes Patterns and Exports Debug Data

Desktop Commander MCP's fuzzy search logger captures every fuzzy-match attempt as structured TSV entries containing similarity scores, execution times, and character-level diffs, then exposes CLI tools to export this data for offline debugging.

The wonderwhy-er/DesktopCommanderMCP repository includes a dedicated fuzzy search logger that helps developers diagnose why specific text edits succeeded or failed. Located in src/utils/fuzzySearchLogger.ts, this utility records granular telemetry whenever the edit engine falls back to fuzzy matching. Understanding how this logger analyzes patterns and exports debug data is essential for troubleshooting complex search-and-replace operations.

What Gets Logged in the Fuzzy Search Logger

Each time the performSearchReplace function in src/tools/edit.ts falls back to fuzzy matching, it constructs a FuzzySearchLogEntry object containing 16 distinct fields. The logger writes these as tab-separated values (TSV) to ~/.claude-server-commander-logs/fuzzy-search.log, creating a header row automatically if the file does not exist.

Core Search Metadata

The entry records the search context that triggered the fuzzy fallback:

• searchText – The original string the user requested to replace
• foundText – The actual string the fuzzy algorithm located
• timestamp – Precise time when the search executed
• fileExtension – Extension of the edited file (used for telemetry correlation)

Similarity and Performance Metrics

The logger captures quantitative data about the match quality:

• similarity – The similarity ratio (0.0 to 1.0) returned by getSimilarityRatio
• fuzzyThreshold – The hard-coded cutoff value (0.7) that determines match validity
• belowThreshold – Boolean flag set to true when similarity < fuzzyThreshold
• executionTime – Milliseconds consumed by the fuzzy worker thread
• exactMatchCount – Number of exact occurrences found (normally 0 when fuzzy fallback activates)
• expectedReplacements – Number of replacements the user requested

Diff Analysis and Character Statistics

To diagnose why a match succeeded or failed, the logger stores detailed delta information:

• diff – Human-readable diff produced by highlightDifferences
• searchLength and foundLength – Character counts for comparison
• diffLength – Total characters that differ between search and found strings
• characterCodes – Histogram of Unicode code points that differ, formatted as code:count[char]
• uniqueCharacterCount – Number of distinct differing characters

How the Fuzzy Search Logger Collects Pattern Data

The data collection follows a strict pipeline inside src/tools/edit.ts that isolates heavy computation in worker threads while keeping logging side-effect-free.

1. Exact-match attempt – The engine first calls content.indexOf(normalizedSearch) to find precise matches
2. Fuzzy fallback activation – When exact matches are insufficient, the code invokes runFuzzySearchInWorker (the worker-thread wrapper around src/tools/fuzzySearchCore.ts)
3. Similarity calculation – After the worker returns a candidate string, getSimilarityRatio computes the final similarity score
4. Character-code analysis – The getCharacterCodeData function extracts differing prefixes and suffixes, builds a map of Unicode code points, and generates printable statistics
5. Log entry creation – All values populate a FuzzySearchLogEntry object passed to fuzzySearchLogger.log(entry)

This architecture ensures the main event loop remains responsive while capturing complete diagnostic information.

Exporting Debug Data from the Fuzzy Search Logger

Two helper scripts in the scripts/ directory provide programmatic access to the TSV log file. Both import the singleton logger instance from ../dist/utils/fuzzySearchLogger.js and expose two public APIs: await fuzzySearchLogger.getRecentLogs(limit) for the last N entries, and await fuzzySearchLogger.getLogPath() for the absolute file path.

Viewing Logs with view-fuzzy-logs.js

The scripts/view-fuzzy-logs.js utility formats recent entries into labeled sections (timestamp, similarity, diff, etc.) and prints them to the console. This is useful for quick inspections during active development.

Exporting to CSV or JSON with export-fuzzy-logs.js

The scripts/export-fuzzy-logs.js script converts the TSV data into portable formats. It parses each line into JavaScript objects, restores escaped newlines and tabs, then:

• CSV mode – Generates a header row from object keys and escapes commas, newlines, and quotes for each value
• JSON mode – Serializes the array using JSON.stringify(array, null, 2) for pretty-printed output

If you omit the --output flag, the script generates a timestamped filename such as fuzzy-search-logs-2024-03-18T12-34-56-789Z.csv.

Practical Example: Triggering and Exporting Logs

The following workflow demonstrates how to trigger a fuzzy match and export the resulting diagnostics:

import { performSearchReplace } from './src/tools/edit.js';
import { fuzzySearchLogger } from './src/utils/fuzzySearchLogger.js';

// Trigger a fuzzy edit by using a typo that forces fallback
await performSearchReplace(
  '/path/to/file.txt',
  { search: 'Commader', replace: 'Commander' }, // typo forces fuzzy path
  1,
  'ui'
);

// View the most recent entry in the console
const recent = await fuzzySearchLogger.getRecentLogs(1);
console.log('Latest fuzzy search log entry:', recent[0]);

// Export the last 50 entries as JSON via CLI:
// $ node scripts/export-fuzzy-logs.js --format json --limit 50

Summary

• Desktop Commander MCP writes every fuzzy search attempt to ~/.claude-server-commander-logs/fuzzy-search.log as TSV data via the FuzzySearchLogger class in src/utils/fuzzySearchLogger.ts.
• Each log entry contains 16 fields including similarity ratios, execution times, Unicode character histograms, and human-readable diffs.
• The logging pipeline activates in src/tools/edit.ts when performSearchReplace falls back to runFuzzySearchInWorker after exact-match failures.
• Use scripts/view-fuzzy-logs.js for quick console inspection or scripts/export-fuzzy-logs.js to generate CSV/JSON files for bug reports.

Frequently Asked Questions

Where does Desktop Commander MCP store fuzzy search logs?

The fuzzy search logger writes all entries to ~/.claude-server-commander-logs/fuzzy-search.log as a Tab-Separated-Values (TSV) file. This path is managed internally by the FuzzySearchLogger class and can be retrieved programmatically via the getLogPath() method.

What similarity threshold triggers logging in the fuzzy search logger?

The logger records all fuzzy fallback attempts regardless of success, but each entry includes a fuzzyThreshold field set to 0.7 and a belowThreshold boolean indicating whether the match fell below this cutoff. Matches with similarity below 0.7 are rejected by the edit engine.

How can I export fuzzy search logs to JSON for analysis?

Run node scripts/export-fuzzy-logs.js --format json --limit 50 from the repository root. This script parses the TSV log file, restores escaped characters, and outputs a pretty-printed JSON array containing the requested number of recent entries. Omit --limit to export the entire history.

What character statistics does the fuzzy search logger capture?

For every fuzzy match, the logger records a characterCodes histogram mapping Unicode code points to their occurrence counts in the diff, along with uniqueCharacterCount (distinct differing characters) and diffLength (total differing characters). These values help identify encoding issues or subtle whitespace differences.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}