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

> Desktop Commander MCP's fuzzy search logger captures match attempts with scores and diffs. Export structured TSV data for debugging using CLI tools. Analyze patterns and debug effectively.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: deep-dive
- Published: 2026-07-29

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/../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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/edit.ts) when `performSearchReplace` falls back to `runFuzzySearchInWorker` after exact-match failures.
- Use [`scripts/view-fuzzy-logs.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/view-fuzzy-logs.js) for quick console inspection or [`scripts/export-fuzzy-logs.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.