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

> Understand DesktopCommander MCP start_search content vs files search. Learn when to use each mode for efficient filename or text file searching and boost your productivity.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) at [lines 59-66](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts#L59-L66), `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.

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

```

Expected result format:

```json
{
  "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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts#L34-L36), 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) around [lines 150-188](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts#L150-L188) shows that `content` searches also trigger Office document parsing—specifically `searchExcelFiles` and `searchDocxFiles` from [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts)—when matching `.xlsx` or `.docx` files are encountered.

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

```

Expected result format:

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

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts).
- Both modes share session tracking and timeout handling in [`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.