mcp-everything-search: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that provides cross-platform file search capabilities:

• Windows: Uses the Everything SDK for fast indexed search
• macOS: Uses mdfind (Spotlight) for native search
• Linux: Uses locate/plocate for filesystem search

The server exposes a single search tool with platform-specific parameter schemas and syntax support.

Development Commands

Testing and Running

# Run the server with MCP inspector for testing
npx @modelcontextprotocol/inspector uv run mcp-server-everything-search

# Run directly with uv
uv run mcp-server-everything-search

# Run as Python module (after pip install)
python -m mcp_server_everything_search

Code Quality

# Type checking
uv run pyright

# Linting
uv run ruff check

# Formatting
uv run ruff format

# Run tests
uv run pytest

Building

# Build the package
uv build

Architecture

Core Components

1. server.py - Main MCP server implementation

   • Defines the search tool with platform-specific schemas
   • Handles parameter parsing and validation using Pydantic
   • Routes search requests to appropriate platform provider
   • Returns formatted search results as TextContent

2. search_interface.py - Abstract search provider interface

   • SearchProvider: Abstract base class defining the search contract
   • WindowsSearchProvider: Everything SDK wrapper
   • MacSearchProvider: mdfind command wrapper
   • LinuxSearchProvider: locate/plocate command wrapper
   • SearchResult: Universal dataclass for all platforms

3. platform_search.py - Platform-specific parameter models

   • BaseSearchQuery: Common search parameters (query, max_results)
   • WindowsSpecificParams: Everything SDK options (match_path, match_case, etc.)
   • MacSpecificParams: mdfind options (live_updates, search_directory, etc.)
   • LinuxSpecificParams: locate options (ignore_case, regex_search, etc.)
   • UnifiedSearchQuery: Combines all parameter models with platform-aware schema generation
   • build_search_command(): Builds platform-specific command arrays