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.

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

Related MCP server: GitBridge

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

# 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:

{
  "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:

node /path/to/searchfox-mcp/dist/index.js

Query Syntax Examples

Basic Searches

// 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

// 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

# 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 - Command-line tool for Searchfox (Rust)

• Searchfox - Mozilla's code search website

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

• MIT license (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.