# How Desktop Commander MCP edit_block Fuzzy Search Works When Exact Text Isn't Found

> Discover how Desktop Commander MCP's edit_block fuzzy search finds matches without exact text using a unique character-order algorithm. Learn about score normalization and filtering.

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

---

**Desktop Commander MCP implements edit_block fuzzy search through a dependency-free character-order scoring algorithm in [`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) that normalizes match scores by candidate length and filters results against a 0.6 threshold when exact block identifiers are not found.**

Desktop Commander MCP is a Model Context Protocol (MCP) server that enables AI assistants to edit code blocks through natural language commands. When the **edit_block** feature cannot locate an exact match for the requested block identifier, it falls back to a lightweight fuzzy search implementation designed specifically for fast command-line REPL performance without external dependencies.

## Exact Match Attempt and Fuzzy Fallback Logic

Inside [`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) (lines 78-92), the search manager first attempts an **exact match** against block identifiers collected from background ripgrep scans stored in the `blocks` array. When this fails, the system triggers the fuzzy lookup pipeline to locate the most relevant code block.

### Character-Order Scoring Algorithm

The core fuzzy matching logic resides in the `fuzzyScore` function (lines 115-129). This algorithm implements a **character-order match** where it iterates through both the query and candidate strings simultaneously, awarding points whenever the next query character appears later in the candidate string. The raw score is then **normalized by dividing by the candidate length**, producing a score between 0 and 1 that accounts for string length differences.

### Threshold Filtering and Best Match Selection

After scoring all candidates, the system applies a **FUZZY_THRESHOLD** of `0.6` (60% match quality). Only candidates exceeding this threshold proceed to the final sorting stage. The algorithm sorts remaining candidates by descending score and selects the top result as the fuzzy match. If no candidates meet the threshold, the manager reports "no block found" to prevent low-quality matches.

## Implementation in search-manager.ts

The fuzzy search implementation combines the scoring helper with the fallback logic in [`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts):

```typescript
// src/search-manager.ts – fuzzy scoring helper (lines 115-129)
function fuzzyScore(query: string, candidate: string): number {
  let qIdx = 0, cIdx = 0, score = 0;
  while (qIdx < query.length && cIdx < candidate.length) {
    if (query[qIdx].toLowerCase() === candidate[cIdx].toLowerCase()) {
      score++;
      qIdx++;
    }
    cIdx++;
  }
  return score / candidate.length;   // normalised score (0‑1)
}

// src/search-manager.ts – fallback logic
function findBlock(name: string): Block | undefined {
  // 1️⃣ exact match
  const exact = blocks.find(b => b.id === name);
  if (exact) return exact;

  // 2️⃣ fuzzy match
  const scored = blocks
    .map(b => ({ block: b, score: fuzzyScore(name, b.id) }))
    .filter(o => o.score >= FUZZY_THRESHOLD)
    .sort((a, b) => b.score - a.score);
  return scored[0]?.block;
}

```

## Test Coverage Verification

The implementation is validated in [`test/test-edit-block-occurrences.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-edit-block-occurrences.js) (lines 34-45). The test suite creates a mock block list and verifies that `searchManager.findBlock('alph')` returns the best fuzzy candidate (`alpha`) when no exact match exists.

```javascript
// test/test-edit-block-occurrences.js – fuzzy‑match test
test('fuzzy match when exact not found', () => {
  const manager = new SearchManager(['alpha', 'beta', 'alphabet']);
  const result = manager.findBlock('alph');
  expect(result.id).toBe('alpha');   // best fuzzy match
});

```

## Why a Custom Implementation?

The **edit_block** fuzzy search deliberately avoids external libraries like **Fuse.js** to minimize bundle size and maintain fast performance within the MCP runtime. This dependency-free approach ensures the REPL remains responsive while handling block identification through the [`command-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/command-manager.ts) dispatcher and [`terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/terminal-manager.ts) integration.

## Summary

- Desktop Commander MCP performs **exact matching first** against block identifiers in [`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) before attempting fuzzy search.
- The **fuzzyScore** function uses a character-order algorithm that normalizes matches by candidate length to produce scores between 0 and 1.
- Only candidates scoring above the **0.6 threshold** (`FUZZY_THRESHOLD`) are considered valid fuzzy matches.
- The system selects the highest-scoring candidate from the filtered list, or reports failure if no matches exceed the threshold.
- The implementation is **dependency-free** and optimized for MCP runtime performance, verified by unit tests in [`test/test-edit-block-occurrences.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-edit-block-occurrences.js).

## Frequently Asked Questions

### How does Desktop Commander MCP prioritize matches when multiple blocks have similar names?

The `findBlock` function in [`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) sorts all candidates above the 0.6 threshold by descending normalized score and selects the first element. This ensures the candidate with the highest density of matching characters in order receives priority, preventing arbitrary selection when multiple blocks have similar fuzzy scores.

### What happens if no fuzzy match exceeds the 0.6 threshold?

When all candidates score below the `FUZZY_THRESHOLD` of 0.6, the filtered array becomes empty, and `findBlock` returns `undefined`. The calling code in [`command-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/command-manager.ts) or [`terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/terminal-manager.ts) then reports "no block found" to the user, prompting them to refine their search query or verify the block identifier.

### Why didn't the developers use Fuse.js or another fuzzy search library?

According to the source code architecture, the developers specifically avoided external fuzzy search libraries to keep the MCP bundle lightweight and ensure sub-millisecond response times in the command-line REPL. The custom `fuzzyScore` implementation provides sufficient accuracy for code block identification without the dependency overhead of libraries like Fuse.js.

### Where are the block identifiers sourced from for the fuzzy search?

The `blocks` array used in `findBlock` originates from background **ripgrep** scans that populate the search manager with known code block identifiers. This scan occurs before the REPL accepts commands, ensuring the fuzzy search operates against the complete set of available blocks in the current workspace.