# Searchfox MCP Server
A comprehensive Model Context Protocol (MCP) server that provides full access to Mozilla's Searchfox code search and analysis service. This server enables AI assistants to search through Mozilla codebases, analyze code structure, retrieve file contents, and understand call relationships.
> [!WARNING]
> Prefer using [searchfox-cli](https://github.com/padenot/searchfox-cli) for agentic workflows (like Claude Code) instead of this MCP.
## Features
- **Advanced Code Search**: Unified search with advanced query syntax (symbol:, id:, path:, etc.)
- **Symbol Analysis**: Search for symbols and extract complete definitions
- **Call Graph Analysis**: Analyze function call relationships with three query modes
- **Memory Layout**: View C++ class/struct memory layout with field offsets
- **Git Blame**: Get commit history for specific lines or files
- **File Operations**: Retrieve file contents with line range support
- **Path Search**: Find files matching specific patterns
- **Multiple Repositories**: Support for mozilla-central, autoland, mozilla-beta, ESR branches, and more
## Available Tools (8 Total)
### 1. `search`
Unified code search with advanced query syntax and filtering capabilities.
**Parameters:**
- `query` (string): Search query with optional advanced syntax
- `symbol:Name` - Symbol search (definitions/declarations)
- `id:Name` - Exact identifier matching
- `path:dir/file` - Path filter
- `pathre:regex` - Path regex filter
- `text:exact` - Exact text search
- `re:pattern` - Regular expression pattern
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
- `case_sensitive` (boolean, optional): Enable case sensitive search
- `limit` (number, optional): Maximum number of results (default: 50)
- `context_lines` (number, optional): Number of context lines before/after matches
- `filters` (object, optional): Additional filters
- `language`: Filter by language (cpp, c, js, webidl, rust)
- `exclude_tests`: Exclude test files
- `exclude_generated`: Exclude generated files
- `exclude_thirdparty`: Exclude third-party files
- `only_tests`: Include only test files
**Example:**
```json
{
"query": "symbol:AudioContext path:dom/media",
"filters": {
"language": "cpp",
"exclude_tests": true
}
}
```
### 2. `get_file`
Retrieve file contents with optional line range support.
**Parameters:**
- `path` (string): File path within the repository
- `repo` (string, optional): Repository name (default: "mozilla-central")
- `lines` (object, optional): Line range to retrieve
- `start` (number): Starting line number (1-based)
- `end` (number): Ending line number (inclusive)
- `context` (number): Additional context lines before/after range
**Example:**
```json
{
"path": "dom/media/AudioContext.cpp",
"lines": {
"start": 100,
"end": 200,
"context": 5
}
}
```
### 3. `search_paths`
Find files by path pattern.
**Parameters:**
- `pattern` (string): File path pattern to search for
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
- `limit` (number, optional): Maximum number of results (default: 100)
**Example:**
```json
{
"pattern": "AudioContext",
"repo": "mozilla-central"
}
```
### 4. `search_symbols`
Dedicated symbol/identifier search with language and path filtering.
**Parameters:**
- `symbol` (string): Symbol or identifier name to search for
- `type` (string, optional): Search type - "symbol" (default) or "identifier"
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
- `path_filter` (string, optional): Path filter to narrow results
- `limit` (number, optional): Maximum number of results (default: 50)
- `language` (string, optional): Filter by language (cpp, c, js, webidl, rust)
**Example:**
```json
{
"symbol": "MediaStream",
"type": "symbol",
"path_filter": "dom/media",
"language": "cpp"
}
```
### 5. `get_definition`
Extract complete function/class definitions using intelligent brace-matching.
**Parameters:**
- `symbol` (string): Symbol name to get definition for
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
- `path_filter` (string, optional): Path filter to find the right definition
- `language` (string, optional): Language hint - cpp, c, js, webidl, rust, or "auto" (default: "auto")
- `max_lines` (number, optional): Maximum number of lines to extract (default: 500)
**Features:**
- Intelligent brace-matching state machine
- Handles nested braces, strings, comments, escape sequences
- Supports C++, C, Rust, JavaScript, and WebIDL
- Scans backward to find function/class start
- Includes initializer lists in C++
**Example:**
```json
{
"symbol": "AudioContext",
"path_filter": "dom/media",
"language": "cpp"
}
```
### 6. `get_call_graph`
Analyze function call relationships with three query modes.
**Parameters:**
- `mode` (string): Query mode
- `calls-from` - What does this function call?
- `calls-to` - What calls this function?
- `calls-between` - Find call paths between two functions
- `source_symbol` (string): Source symbol/function name
- `target_symbol` (string, optional): Target symbol (required for calls-between mode)
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
- `depth` (number, optional): Maximum traversal depth 1-3 (default: 1)
**Features:**
- Results grouped by class/namespace
- Overloaded functions collapsed together
- Formatted markdown output
- Depth control for breadth-first traversal
**Language Support:**
- ✅ C++ (full support)
- ✅ Java, Kotlin, Python (via SCIP indexing)
- ❌ JavaScript/TypeScript (not supported)
**Example:**
```json
{
"mode": "calls-from",
"source_symbol": "mozilla::dom::AudioContext::Create",
"depth": 2
}
```
### 7. `get_field_layout`
Get C++ class/struct memory layout information.
**Parameters:**
- `class_name` (string): C++ class or struct name
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
**Features:**
- Shows size and alignment in bytes
- Lists base classes with offsets
- Shows field offsets, sizes, and types
- Handles template class variants
- C++ only
**Example:**
```json
{
"class_name": "mozilla::dom::AudioContext",
"repo": "mozilla-central"
}
```
### 8. `get_blame`
Get git blame information for files.
**Parameters:**
- `path` (string): File path within the repository
- `repo` (string, optional): Repository to search in (default: "mozilla-central")
- `start_line` (number, optional): Starting line number (default: 1)
- `end_line` (number, optional): Ending line number (inclusive)
**Features:**
- Shows commit hash, author, date, and message
- Supports line range filtering
- Batches commit info requests for efficiency
- Formatted markdown output
**Example:**
```json
{
"path": "dom/media/AudioContext.cpp",
"start_line": 100,
"end_line": 200
}
```
## Supported Repositories
- `mozilla-central` (default) - Main development branch
- `autoland` - Integration branch
- `mozilla-beta` - Beta release branch
- `mozilla-release` - Release branch
- `mozilla-esr115`, `mozilla-esr128`, `mozilla-esr140` - ESR branches
- `comm-central` - Thunderbird codebase
## Installation
```bash
# Clone the repository
git clone https://github.com/canova/searchfox-mcp.git
cd searchfox-mcp
# Install dependencies
npm install
# Build the project
npm run build
```
## Usage
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"searchfox": {
"command": "node",
"args": ["/absolute/path/to/searchfox-mcp/dist/index.js"]
}
}
}
```
**Configuration file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
### Other MCP Clients
This server uses stdio transport and follows the MCP protocol specification. Configure your MCP client to run:
```bash
node /path/to/searchfox-mcp/dist/index.js
```
## Query Syntax Examples
### Basic Searches
```json
// Simple text search
{"query": "AudioContext"}
// Symbol search
{"query": "symbol:MediaStream"}
// Exact identifier
{"query": "id:nsISupports"}
// Path filtered search
{"query": "AudioNode path:dom/media/webaudio"}
// Regular expression
{"query": "re:Create.*Context"}
```
### Advanced Filtering
```json
// C++ code only, exclude tests
{
"query": "symbol:AudioContext",
"filters": {
"language": "cpp",
"exclude_tests": true,
"exclude_generated": true
}
}
// JavaScript in tests only
{
"query": "AudioContext",
"filters": {
"language": "js",
"only_tests": true
}
}
```
### Workflow Examples
**Understanding a New API:**
1. Search for symbol: `{"query": "symbol:AudioContext"}`
2. Get definition: `{"symbol": "AudioContext", "language": "cpp"}`
3. See what it calls: `{"mode": "calls-from", "source_symbol": "mozilla::dom::AudioContext::Create"}`
4. Find usage: `{"mode": "calls-to", "source_symbol": "mozilla::dom::AudioContext::Create"}`
**Debugging a Crash:**
1. Get implementation: `{"symbol": "MediaStream::AddTrack"}`
2. See what it calls: `{"mode": "calls-from", "source_symbol": "mozilla::dom::MediaStream::AddTrack"}`
3. Check blame: `{"path": "dom/media/MediaStream.cpp", "start_line": 100, "end_line": 150}`
**Memory Layout Analysis:**
1. Get layout: `{"class_name": "mozilla::dom::AudioContext"}`
2. Check field sizes and offsets for padding analysis
3. Understand inheritance hierarchy
## Development
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode with hot reload
npm run dev
# Linting
npm run lint
npm run lint:fix
# Formatting
npm run format
npm run format:check
```
## Architecture
This MCP server is built with a modular architecture:
```
src/
├── index.ts # Main server, tool registration
├── types.ts # TypeScript interfaces
├── constants.ts # Constants and mappings
├── tools/ # Tool implementations
│ ├── search.ts # Unified search
│ ├── files.ts # File operations
│ ├── symbols.ts # Symbol tools
│ ├── callgraph.ts # Call graph analysis
│ ├── analysis.ts # Field layout
│ └── blame.ts # Git blame
├── parsers/ # Code parsing utilities
│ ├── definition-extractor.ts # Brace-matching parser
│ └── callgraph-parser.ts # Call graph parsing
└── utils/ # Shared utilities
├── searchfox-client.ts # Searchfox API client
├── github-client.ts # GitHub API client
├── repo-mapping.ts # Repository mappings
├── query-builder.ts # Query syntax parsing
└── filters.ts # Filtering utilities
```
## Related Projects
- [searchfox-cli](https://github.com/padenot/searchfox-cli) - Command-line tool for Searchfox (Rust)
- [Searchfox](https://searchfox.org/) - Mozilla's code search website
## License
Licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
