# file-search-mcp

A blazingly fast MCP server for searching files in large codebases and monorepos.

## Why This Exists

Standard tools like `grep` and `find` are painfully slow on large codebases. They don't respect `.gitignore`, they follow symlink loops, and they flood your terminal with irrelevant results from `node_modules`.

**file-search-mcp** fixes all that:

| Problem | Solution |
|---------|----------|
| `grep` is slow on big repos | Uses ripgrep (100x faster) |
| `find` follows symlink loops | Built-in loop detection |
| Results flood the terminal | Smart token-based truncation |
| Binary files pollute results | Auto-detected and skipped |
| Need to remember complex flags | Simple, intuitive parameters |
| No context for matches | Configurable context lines |
| Case sensitivity confusion | Smart case by default |

## Installation

### Prerequisites

- Node.js 18+
- ripgrep (for content search)

```bash
# Install ripgrep
brew install ripgrep    # macOS
apt install ripgrep     # Ubuntu
choco install ripgrep   # Windows
```

### Quick Start (npx)

No installation required! Just add to your MCP client config:

```json
{
  "mcpServers": {
    "file-search": {
      "command": "npx",
      "args": ["-y", "file-search-mcp"]
    }
  }
}
```

### Global Install

```bash
npm install -g file-search-mcp
```

Then use in your config:

```json
{
  "mcpServers": {
    "file-search": {
      "command": "file-search-mcp"
    }
  }
}
```

## Usage with Claude Desktop

Add to your Claude Desktop config:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "file-search": {
      "command": "npx",
      "args": ["-y", "file-search-mcp"]
    }
  }
}
```

## Usage with OpenCode

Add to your OpenCode config (`~/.config/opencode/config.json`):

```json
{
  "mcp": {
    "file-search": {
      "type": "local",
      "command": ["npx", "-y", "file-search-mcp"]
    }
  }
}
```

## Tools

### `search_files`

Find files by name or glob pattern.

```
"Find all TypeScript files"
→ search_files(pattern: "*.ts")

"Find config files modified today"
→ search_files(pattern: "*.config.*", modified_within: "24h")

"Find large log files"
→ search_files(pattern: "*.log", min_size: "10MB")
```

**Parameters:**
- `reasoning` (required) - Why you're searching
- `pattern` (required) - Glob pattern like `*.ts`, `src/**/*.js`
- `path` - Directory to search (default: current dir)
- `include_hidden` - Include dotfiles (default: true)
- `ignore_gitignore` - Respect .gitignore (default: true)
- `exclude` - Extra patterns to skip
- `detail_level` - `minimal` | `standard` | `full`
- `modified_within` - Only recent files, e.g., `24h`, `7d`
- `min_size` - Only large files, e.g., `1MB`

### `search_content`

Find text or regex patterns inside files.

```
"Find all TODO comments"
→ search_content(query: "TODO")

"Find API endpoints"
→ search_content(query: "app\.(get|post|put|delete)", file_pattern: "*.ts")

"Find hardcoded secrets"
→ search_content(query: "apiKey|secret|password")
```

**Parameters:**
- `reasoning` (required) - Why you're searching
- `query` (required) - Text or regex to find
- `path` - Directory to search (default: current dir)
- `file_pattern` - Only search matching files
- `include_hidden` - Include dotfiles (default: true)
- `ignore_gitignore` - Respect .gitignore (default: true)
- `exclude` - Extra patterns to skip
- `detail_level` - `minimal` | `standard` | `full`
- `context_lines` - Lines around matches (default: 2)

### `fuzzy_find`

Fuzzy search when you don't remember exact names.

```
"Find the user controller"
→ fuzzy_find(query: "usrctrl")

"Find that API routes file"
→ fuzzy_find(query: "apirts")
```

**Parameters:**
- `reasoning` (required) - Why you're searching
- `query` (required) - Fuzzy search terms
- `path` - Directory to search (default: current dir)
- `include_hidden` - Include dotfiles (default: true)
- `detail_level` - `minimal` | `standard` | `full`

### `tree`

Visualize directory structure.

```
"Show me the project structure"
→ tree(depth: 3)

"What's in the src folder?"
→ tree(path: "src", depth: 2)
```

**Parameters:**
- `reasoning` (required) - Why you need this view
- `path` - Directory to show (default: current dir)
- `depth` - How deep to traverse (default: 3)
- `include_hidden` - Show dotfiles (default: false)
- `dirs_only` - Only show directories (default: false)

## Detail Levels

| Level | What You Get |
|-------|--------------|
| `minimal` | Just paths - fast, low tokens |
| `standard` | Paths + size + modified date |
| `full` | Everything + content preview/matches |

## Smart Features

### Smart Case

Searches are case-insensitive by default, but become case-sensitive if your query contains uppercase letters. This matches how VS Code, ripgrep, and most modern tools work.

### Token Limiting

Results are automatically truncated to ~100k tokens to prevent overwhelming responses. You'll see a warning if truncation occurred.

### Binary Detection

Binary files (images, executables, archives, etc.) are automatically skipped to keep results clean and relevant.

### Symlink Safety

Symlinks are followed, but loops are detected and prevented. No more infinite traversal!

### Default Excludes

These directories are always skipped unless you override:
- `node_modules`
- `.git`
- `dist`, `build`
- `coverage`
- `.next`, `.nuxt`
- `__pycache__`, `.pytest_cache`
- `venv`, `.venv`
- `target` (Rust)
- `vendor` (Go)

## Development

```bash
# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch    # Watch mode
```

### Metrics

All tool calls are tracked locally for development analysis. Metrics include:
- Tool usage counts
- Search patterns and queries
- Response times
- Error and truncation rates
- Reasoning text for understanding use cases

```bash
# View metrics summary
npm run metrics

# View last 50 raw calls
npm run metrics:raw

# Clear all metrics
npm run metrics:clear
```

Metrics are stored at `~/.file-search-mcp/metrics.json`

## License

MIT