everything-mcp

Everything MCP Server

A high-performance Model Context Protocol (MCP) server that provides file search capabilities using the Everything Search Engine on Windows.

Features

• ⚡ Lightning-fast file search using Everything's indexed database
• 🔍 6 specialized search tools optimized for AI coding assistants
• 📊 Optional rich metadata (file sizes, timestamps, attributes)
• 🔒 Works across privilege levels (elevated/non-elevated processes)
• 🚀 Dual-mode operation: fast basic search (QUERY1) or detailed metadata search (QUERY2)
• 🧵 Thread-safe queue-based architecture with dedicated message window
• 📚 Comprehensive XML documentation for IntelliSense support

Prerequisites

• Windows operating system
• Everything Search Engine installed and running
• .NET 8.0 Runtime (for pre-built releases) or SDK (for building from source)

Installation

Option 1: Download Release

1. Download the latest release from GitHub Releases
2. Extract to a directory (e.g., C:\Tools\everything-mcp\)
3. Ensure Everything Search Engine is installed and running

Option 2: Build from Source

git clone https://github.com/rweijnen/everything-mcp.git
cd everything-mcp
dotnet build --configuration Release

Configuration

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "everything": {
      "command": "C:\\Tools\\everything-mcp\\everything-mcp.exe"
    }
  }
}

Claude Code

Use the command palette (Ctrl+Shift+P):

• Run: mcp add everything "C:\Tools\everything-mcp\everything-mcp.exe"

Configuration Options

The MCP server can be configured via appsettings.json in the same directory as the executable. By default, logging is disabled for optimal performance.

Enable Logging (Optional)

To enable file logging for debugging, create an appsettings.json file:

{
  "EverythingMcp": {
    "Logging": {
      "Enabled": true,
      "LogFilePath": "logs/everything-mcp.log",
      "LogLevel": "Information",
      "RollingInterval": "Day",
      "RetainedFileCountLimit": 7
    }
  }
}

Configuration Options

• Logging.Enabled: Enable file logging (default: false)
• Logging.LogFilePath: Path for log files (supports environment variables like %TEMP%)
• Logging.LogLevel: Minimum log level (Verbose, Debug, Information, Warning, Error, Fatal)
• Logging.RollingInterval: How often to create new log files (Day, Hour, etc.)
• Logging.RetainedFileCountLimit: Number of old log files to keep

See appsettings.example.json for a complete configuration example with comments.

Available Tools

1. search_files

General file and folder search with intelligent scoping

• query (required): Search query with Everything syntax (wildcards, operators, etc.)
• scope: Search scope (default: "current")
  • "current": Current directory only
  • "recursive": Current directory and subdirectories
  • "system": System-wide search
  • "path:/custom/path": Search in specific path
• include_metadata: Include file sizes and timestamps (default: false)
• max_results: Limit results (default: 100)

2. search_in_project

Search within a specific project directory

• project_path (required): Root directory of the project
• pattern (required): Search pattern (wildcards supported)
• include_metadata: Include file metadata (default: false)
• max_results: Maximum number of results (default: 100)

3. find_executable

Locate executable files (smart detection based on input)

• name (required): Name of the executable
• exact_match: Use exact matching (default: auto-detected)
  • Auto-detection: Uses exact match if extension provided or no wildcards
• max_results: Maximum number of results (default: 20)

4. find_source_files

Find source code files by programming language

• filename (required): Base filename to search for
• extensions: Comma-separated language extensions (e.g., 'cs,js,py')
  • Default extensions by language included automatically
• include_metadata: Include file metadata (default: false)
• max_results: Maximum number of results (default: 100)

5. search_recent_files

Find recently modified files

• hours (required): Number of hours to look back
• pattern: File pattern to filter (default: "*" for all files)
• include_metadata: Include file metadata (default: true)
• max_results: Maximum number of results (default: 100)

6. find_config_files

Find configuration files in a project or globally

• project_path: Project directory (null for global search)
• include_metadata: Include file metadata (default: false)
• max_results: Maximum number of results (default: 50)

Everything Search Syntax

All tools support Everything's powerful search syntax in the query parameter:

Basic Operators

• AND: file1 file2 (space-separated)
• OR: file1|file2 (pipe-separated)
• NOT: !unwanted (exclamation mark)
• Grouping: <group1> <group2>
• Exact filename: exact:"filename.ext" (exact operator)

Wildcards

• * - Zero or more characters (*.txt, test*)
• ? - Single character (file?.txt)

Advanced Features

• Regex: regex:^[A-Z]+\.txt$ (regular expressions)
• File size: size:>1GB, size:<100MB
• Extensions: ext:doc;pdf;txt
• Empty files: empty:
• Name length: len:>50
• Starts/ends with: startwith:test, endwith:.log
• Count limit: count:10

Examples

*.cs !bin !obj                    # C# files excluding build folders
regex:test.*\.log$                 # Log files starting with "test"
size:>100MB ext:mp4;avi           # Large video files
exact:"notepad.exe"                # Exact filename match
file1|file2 !folder               # Either file1 or file2, not in "folder"

Architecture

The Everything MCP Server uses a sophisticated multi-layered architecture:

Core Components

• Everything.Interop: Low-level IPC communication with Everything.exe using Windows messages
• Everything.Client: High-level async client with queue-based threading and automatic protocol selection
• Everything.Mcp: MCP JSON-RPC server with 6 specialized tools

Technical Features

• Dual Protocol Support: Automatically selects QUERY1 (fast, basic) or QUERY2 (metadata-rich) based on requirements
• Cross-Privilege Communication: Uses UIPI filters to enable communication across elevation levels
• Thread Safety: Dedicated message window thread handles all IPC communication
• Performance Optimized: QUERY1 searches complete in ~20-30ms, QUERY2 in ~50-100ms

Development

Building

dotnet build --configuration Release

Testing

# Run all tests
dotnet test --configuration Release

# Run only unit tests
dotnet test tests/Everything.Interop.Tests/ --configuration Release

# Run only integration tests (requires Everything.exe running)
dotnet test tests/Everything.Integration.Tests/ --configuration Release

Testing the MCP Server

# List tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | dotnet run --project src/Everything.Mcp/

# Search example
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"*.txt !temp","scope":"system","max_results":5}}}' | dotnet run --project src/Everything.Mcp/

Performance

Typical Performance Characteristics

• First query: ~100ms (includes window creation overhead)
• QUERY1 (basic search): 20-30ms
• QUERY2 (with metadata): 50-100ms
• Tested with: ~1M indexed files
• Memory usage: ~10-20MB

Optimization Tips

• Use include_metadata: false for fastest searches
• Use appropriate scope to limit search space
• Set reasonable max_results limits
• Consider using search_files with QUERY1 for bulk operations

Troubleshooting

Common Issues

• "Everything not running": Ensure Everything Search Engine is installed and running
• "No results": Verify Everything has finished indexing (check Everything GUI)
• Slow performance: Check if Everything database is busy rebuilding
• Permission issues: Both Everything and MCP server should have similar privilege levels

Debugging

1. Enable logging in appsettings.json
2. Check log files for detailed error information
3. Test queries directly in Everything's GUI first
4. Verify Everything IPC is working with the test console

Project Status

Version 0.0.3 - Production Ready

✅ Completed Features

• Complete Everything IPC integration with QUERY1/QUERY2 support
• 6 production-ready MCP tools
• Comprehensive XML documentation
• Full test suite (unit + integration tests)
• Thread-safe queue-based architecture
• Cross-privilege communication support

License

Mozilla Public License 2.0

Acknowledgments

• Everything Search Engine by David Carpenter
• Model Context Protocol by Anthropic