Start_search Content vs Files Search Types: Which DesktopCommander MCP Search Mode to Use

In DesktopCommander MCP, start_search offers two search types: files searches only filenames and paths, while content searches the text inside files with line numbers and optional Office document support.

The searchType parameter in DesktopCommander MCP's search system determines whether you're looking for files by name or hunting for specific text within them. Both modes share the same session infrastructure in src/search-manager.ts but produce fundamentally different result structures and invoke different code paths through the ripgrep integration.

What the files Search Type Does

The files search type performs a lightweight filename-only lookup. In src/search-manager.ts at lines 59-66, startSearch routes this mode through ripgrep's --files flag, which returns matching file paths without reading file contents.

Result objects contain only type: 'file' and a file field with the absolute path. No line numbers, no text snippets—just the locations. This makes files searches faster for large codebases since the engine walks the directory tree and applies glob patterns without opening files.

await searchManager.startSearch({
  rootPath: '/home/user/project',
  pattern: '*.md',
  searchType: 'files',
  ignoreCase: true,
  maxResults: 100,
});

Expected result format:

{
  "type": "file",
  "file": "/home/user/project/README.md"
}

What the content Search Type Does

The content search type performs full-text search inside files. According to the SearchSessionOptions interface at lines 34-36, this mode activates additional processing pipelines that files mode skips.

Results include type: 'content' with file, line, and match fields. The implementation in src/search-manager.ts around lines 150-188 shows that content searches also trigger Office document parsing—specifically searchExcelFiles and searchDocxFiles from src/tools/filesystem.ts—when matching .xlsx or .docx files are encountered.

await searchManager.startSearch({
  rootPath: '/home/user/project',
  pattern: 'TODO',
  searchType: 'content',
  ignoreCase: false,
  contextLines: 2,
  literalSearch: true,
});

Expected result format:

{
  "type": "content",
  "file": "/home/user/project/src/app.ts",
  "line": 42,
  "match": " // TODO: refactor this function"
}

Key Differences Between files and content Search Types

Aspect	files	content
Target	Filename/path patterns	Text inside files
Ripgrep flags	--files	-n (line numbers), -i, -F as configured
Result fields	file only	file, line, match
Office documents	Not searched	Parsed via searchExcelFiles / searchDocxFiles
Performance	Faster—no file reads	Slower—reads contents, parses binaries

When to Use Each Search Type

Use files when you need to:

• Locate configuration files by extension (*.json, *.yaml)
• Find all test files matching a naming convention (*.test.ts)
• Enumerate files in a directory tree without reading contents

Use content when you need to:

• Find all occurrences of a function name across source code
• Search for TODO comments or deprecated API usage
• Extract text from Excel spreadsheets or Word documents alongside regular files

Office Document Support in Content Searches

The content search type uniquely handles binary Office formats. When filePattern matches .xlsx or .docx files, the search manager invokes helper functions from src/tools/filesystem.ts to extract searchable text from workbook cells and document paragraphs, merging these results with standard ripgrep output in the same session.

await searchManager.startSearch({
  rootPath: '/home/user/project',
  pattern: 'Invoice #1234',
  searchType: 'content',
  filePattern: '*.xlsx',
});

Summary

• files search type: Fast filename-only lookup via ripgrep's --files flag; returns path strings without file content inspection.
• content search type: Full-text search with line numbers; supports contextLines, case sensitivity toggles, literal matching, and automatic parsing of Excel and DOCX files via src/tools/filesystem.ts.
• Both modes share session tracking and timeout handling in src/search-manager.ts but diverge in ripgrep argument building and post-processing pipelines.

Frequently Asked Questions

What happens if I use content search without specifying filePattern?

The search scans all files under rootPath that ripgrep can read as text, plus any .xlsx or .docx files found. Binary files are typically ignored unless explicitly matched or handled by the Office document parsers.

Can I search both filenames and content in one call?

No—searchType is mutually exclusive. To achieve both, initiate two separate startSearch calls: one with searchType: 'files' and another with searchType: 'content'. The session IDs will differ, so you'll track them separately.

Does files search work with ripgrep's .gitignore handling?

Yes. Both search types respect ripgrep's default behavior for ignore files, and DesktopCommander MCP's buildRipgrepArgs function in src/tools/filesystem.ts passes through relevant flags to control ignore handling per search session.

Is there a performance penalty for content searches on large repositories?

Yes. content searches read file contents and may parse Office binaries, consuming more I/O and CPU. Use maxResults and narrow filePattern globs to limit scope when performance matters.

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