How to Use VS Code-Ripgrep Based Code and Text Search in Desktop Commander MCP

Desktop Commander MCP provides a high-performance search engine powered by @vscode/ripgrep that enables fast file and content searches across folders through the start_search tool, with results streamed as JSON and paginated via get_more_search_results.

Desktop Commander MCP ships with a built-in search infrastructure that leverages the @vscode/ripgrep package for blazing-fast codebase exploration. The system wraps the ripgrep binary in an ESM-compatible shim and exposes search functionality through MCP tools like start_search and get_more_search_results. This guide explains how to invoke searches, manage sessions, and configure advanced matching options using the actual source implementation from the wonderwhy-er/DesktopCommanderMCP repository.

Search Architecture and Binary Resolution

The search system relies on a robust binary resolution chain to ensure ripgrep executes correctly across platforms.

Ripgrep Wrapper and Resolver

The entry point for binary resolution is getRipgrepPath() in [src/utils/ripgrep-resolver.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ripgrep-resolver.ts). This function attempts three strategies in order:

1. Import @vscode/ripgrep and use the bundled binary (rg-<target>)
2. Use which or where to locate a system rg installation
3. Scan common install locations (Homebrew, Chocolatey, Cargo)

If all strategies fail, the function throws an informative error (lines 75-82). The [scripts/ripgrep-wrapper.js](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/ripgrep-wrapper.js) provides an alternative ESM-compatible shim that selects the correct binary for the current platform and guarantees executable permissions.

Session Lifecycle Management

When a client invokes the start_search tool, [src/search-manager.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) creates a search session. The SearchManager.startSearch method validates the root path, generates a unique session ID, builds command-line arguments via buildRipgrepArgs, and spawns the ripgrep process. Results are streamed back as JSON lines for content searches or plain lines for file searches, with pagination handled by readSearchResults.

Starting a Search Session

Basic Search Parameters

The start_search tool accepts a payload matching the StartSearchArgsSchema defined in [src/tools/schemas.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts). At minimum, you must specify:

{
  rootPath: '/home/user/projects',  // Absolute path to search folder
  pattern: 'TODO',                  // Search string or glob pattern
  searchType: 'content'             // 'files' or 'content'
}

The tool handler in [src/handlers/search-handlers.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/search-handlers.ts) processes these requests and delegates to the SearchManager.

File Search vs. Content Search

The searchType parameter determines the ripgrep invocation strategy implemented in SearchManager.buildRipgrepArgs (lines 333-389):

• File search (searchType: "files"): Adds the --files flag and uses --iglob or --glob for filtering. Exact filenames pass through unchanged; substrings wrap with *…* wildcards.
• Content search (searchType: "content"): Adds --json --line-number for structured output, plus optional flags for case sensitivity, context lines, and literal matching.

Retrieving and Managing Results

Pagination with get_more_search_results

After starting a search, retrieve results using the get_more_search_results tool, implemented by readSearchResults in the search manager:

{
  sessionId: 'search_3_1690567890123',  // Returned by start_search
  offset: 0,                            // Start index (use negative for tail)
  length: 100                           // Number of results to return
}

The API returns results, totalResults, totalMatches, and a hasMoreResults flag. Use a negative offset to implement a "tail" view that returns the last N results, mirroring file-reading semantics.

Session Control Tools

• stop_search: Immediately terminates a running search process by session ID.
• list_searches: Returns an array of active sessions with metadata including id, searchType, pattern, and isComplete.

A global cleanup interval (started by startCleanupIfNeeded) runs every five minutes to delete completed sessions older than the default five-minute window.

Advanced Search Configuration

Literal String Matching

Set literalSearch: true to force fixed-string matching instead of regular expressions. This adds the -F flag to ripgrep (lines 41-44 in buildRipgrepArgs) and prevents regex-based ReDoS attacks when searching user input.

Context Lines and Case Sensitivity

• contextLines: N: Adds -C N to show N lines of surrounding context for each match (lines 45-47).
• ignoreCase: true: Adds the -i flag for case-insensitive matching (default true for content searches).

File Filtering and Result Limits

• filePattern: Pipe-separated glob patterns (e.g., "*.ts|*.md") that translate to -g filters for content searches or --iglob/--glob for file searches (lines 66-84).
• maxResults: N: Hard limit on total matches, translated to the -m N ripgrep flag (lines 62-64).
• includeHidden: true: Adds the --hidden flag to search dotfiles and hidden directories (lines 58-60).

Early Termination Optimization

By default, earlyTermination: true enables an optimization that stops the search immediately when an exact filename match is found (lines 31-49 in processBufferedOutput). Disable this when you need comprehensive results.

Summary

• Desktop Commander MCP uses @vscode/ripgrep through platform-aware wrappers in scripts/ripgrep-wrapper.js and src/utils/ripgrep-resolver.ts.
• Invoke searches via the start_search tool with parameters like rootPath, pattern, and searchType.
• Retrieve paginated results using get_more_search_results with offset-based or tail-based semantics.
• Control matching behavior through literalSearch, ignoreCase, contextLines, and filePattern options that map directly to ripgrep flags.
• Manage long-running searches with stop_search and monitor active sessions via list_searches.

Frequently Asked Questions

What is the difference between file search and content search in Desktop Commander MCP?

File search (searchType: "files") uses the --files flag to return matching filenames only, while content search (searchType: "content") uses --json --line-number to return structured data including line numbers, match text, and context lines. File search applies glob patterns via --iglob, whereas content search uses -g filters.

How does Desktop Commander MCP handle ripgrep binary resolution across different platforms?

The getRipgrepPath() function in src/utils/ripgrep-resolver.ts attempts three resolution strategies: importing the bundled @vscode/ripgrep binary, locating a system rg via which/where, and scanning common installation directories. The scripts/ripgrep-wrapper.js shim ensures the correct platform-specific binary (e.g., rg-x86_64-unknown-linux-musl on Linux) is selected and executable permissions are set.

Can I search using literal strings instead of regular expressions?

Yes. Set literalSearch: true in your start_search payload. This adds the -F flag to the ripgrep invocation, treating the pattern as a fixed string rather than a regex. This is implemented in SearchManager.buildRipgrepArgs and is recommended when searching for special characters or user-provided input.

How do I paginate through large search results?

Use the get_more_search_results tool with the sessionId returned by start_search. Specify an offset (0-based index) and length (number of results). For viewing the most recent results first, use a negative offset value. The response includes hasMoreResults to indicate if additional pages exist and isComplete to show whether the underlying ripgrep process has finished executing.

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