### Install MCP Server via uv

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Install the MCP server using uvx, the recommended method. This provides efficient dependency management and installation.

```bash
uvx mcp-server-everything-search
```

--------------------------------

### Install MCP Server via Smithery CLI

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Install the MCP server using the Smithery CLI. This method is an alternative to uv or pip for project setup.

```bash
npx -y @smithery/cli install mcp-server-everything-search --client claude
```

--------------------------------

### Install Everything Search MCP Server with pip

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Install the server package using pip and run it directly from the command line.

```bash
pip install mcp-server-everything-search
python -m mcp_server_everything_search
```

--------------------------------

### Install and Run Everything Search MCP Server with uvx

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Use 'uvx' for a quick, non-persistent installation. On Windows, specify the path to the Everything SDK DLL.

```bash
# macOS / Linux — no extra setup required
uvx mcp-server-everything-search

# Windows — point to the Everything64.dll from the Everything SDK
EVERYTHING_SDK_PATH="C:\Everything-SDK\dll\Everything64.dll" \
  uvx mcp-server-everything-search
```

--------------------------------

### Start MCP Server (Asyncio)

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Starts the MCP server using `asyncio.run(serve())`. This coroutine registers handlers and starts the stdio transport, blocking until interrupted.

```python
import asyncio
from mcp_server_everything_search.server import serve

# Start the server directly (blocks until interrupted)
asyncio.run(serve())
```

--------------------------------

### Search Query with Syntax Example (JSON)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Example of a JSON payload for a search query utilizing specific syntax for file extension and modification date.

```json
{
  "query": "ext:py datemodified:today",
  "max_results": 10
}
```

--------------------------------

### Cross-Platform UnifiedSearchQuery Examples

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Demonstrates creating UnifiedSearchQuery objects for macOS, Linux, and Windows, showcasing platform-specific parameters and schema generation.

```python
from mcp_server_everything_search.platform_search import (
    UnifiedSearchQuery,
    MacSpecificParams,
    LinuxSpecificParams,
    WindowsSpecificParams,
)

# macOS query
mac_query = UnifiedSearchQuery(
    query="kind:pdf",
    max_results=20,
    mac_params=MacSpecificParams(search_directory="/Users/alice/Documents")
)

# Linux query
linux_query = UnifiedSearchQuery(
    query="*.log",
    max_results=100,
    linux_params=LinuxSpecificParams(ignore_case=True, existing_files=True)
)

# Windows query
win_query = UnifiedSearchQuery(
    query="ext:py datemodified:today",
    max_results=50,
    windows_params=WindowsSpecificParams(match_regex=False, sort_by=14)
)

# Get platform-appropriate JSON schema for MCP tool registration
schema = UnifiedSearchQuery.get_schema_for_platform()
print(schema["required"])
print(list(schema["properties"]))

```

--------------------------------

### MCP Tool 'search' Example Call - Windows

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

An example of calling the 'search' MCP tool on Windows to find large video files modified this week. This demonstrates the use of base query parameters and Windows-specific sorting.

```json
{
  "base": {
    "query": "ext:mp4|mkv|avi size:>500mb datemodified:thisweek",
    "max_results": 20
  },
  "windows_params": {
    "sort_by": 6
  }
}
```

--------------------------------

### Install MCP Server via pip

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Install the MCP server using pip. This is a standard Python package installation method, followed by running the module.

```bash
pip install mcp-server-everything-search
```

--------------------------------

### Create UnifiedSearchQuery for Windows

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Example of creating a UnifiedSearchQuery with Windows-specific parameters, including sorting by size in descending order.

```python
from mcp_server_everything_search.platform_search import (
    UnifiedSearchQuery, WindowsSpecificParams
)

query = UnifiedSearchQuery(
    query="size:>1gb",
    max_results=10,
    windows_params=WindowsSpecificParams(
        sort_by=WindowsSortOption.SIZE_DESC,
        match_path=False
    )
)
print(query.windows_params.sort_by)  # WindowsSortOption.SIZE_DESC (6)
```

--------------------------------

### Search Query Example (JSON)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Example of a JSON payload for a search query, specifying the file pattern, maximum results, and sorting preference.

```json
{
  "query": "*.py",
  "max_results": 50,
  "sort_by": 6
}
```

--------------------------------

### Programmatic MCP Server Startup with Logging

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Starts the MCP server programmatically with configured logging and Windows console adjustments. Includes basic error handling for KeyboardInterrupt.

```python
import asyncio
import logging
from mcp_server_everything_search.server import serve, configure_windows_console

logging.basicConfig(level=logging.DEBUG)
configure_windows_console()  # no-op on non-Windows

try:
    asyncio.run(serve())
except KeyboardInterrupt:
    print("Server stopped.")
```

--------------------------------

### SearchProvider.get_provider() and search_files()

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Demonstrates how to get the appropriate search provider for the current OS and perform a file search using the `search_files` method. It also shows how to iterate through the `SearchResult` objects.

```APIDOC
## SearchProvider.get_provider() and search_files()

### Description
This section shows how to use the `SearchProvider` factory to obtain an OS-specific search provider and then utilize its `search_files` method to find files. It includes an example of processing the returned `SearchResult` objects.

### Method
```python
from mcp_server_everything_search.search_interface import SearchProvider

# Automatically picks the right provider for the current OS
provider = SearchProvider.get_provider()

results = provider.search_files(
    query="*.py",
    max_results=25,
    match_case=False,
    match_regex=False
)

for r in results:
    print(f"{r.path}  |  {r.size} bytes  |  modified: {r.modified}")
```

### Response Example (Linux/macOS)
```
/home/alice/project/main.py  |  4096 bytes  |  modified: 2024-06-15 10:32:00
/home/alice/project/utils.py  |  2048 bytes  |  modified: 2024-06-14 09:00:00
```
```

--------------------------------

### Example Tool Call: Windows Regex Log Files

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Use this for regex searches on numbered log files on Windows.

```json
{
  "base": {
    "query": "app_\\d{4}-\\d{2}-\\d{2}\\.log",
    "max_results": 10
  },
  "windows_params": {
    "match_regex": true,
    "match_path": false
  }
}
```

--------------------------------

### Example Tool Call: macOS Search PDFs

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Use this to search for PDF files within the Documents directory on macOS.

```json
{
  "base": {
    "query": "kind:pdf",
    "max_results": 30
  },
  "mac_params": {
    "search_directory": "/Users/alice/Documents",
    "interpret_query": true
  }
}
```

--------------------------------

### Example Tool Call: Windows Find Python Files

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Use this to find Python files modified today on Windows.

```json
{
  "base": {
    "query": "ext:py datemodified:today",
    "max_results": 50
  },
  "windows_params": {
    "sort_by": 14,
    "match_path": false
  }
}
```

--------------------------------

### Example Tool Call: macOS Find Images This Month

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Use this to find image files modified this month on macOS.

```json
{
  "base": {
    "query": "kMDItemContentTypeTree = 'public.image' && kMDItemFSContentChangeDate >= $time.this_month()",
    "max_results": 100
  },
  "mac_params": {
    "literal_query": false
  }
}
```

--------------------------------

### Claude Desktop Configuration for pip Installation

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Configure Claude Desktop to use the Everything Search MCP Server installed via 'pip' on any platform. For Windows, the EVERYTHING_SDK_PATH environment variable should also be set.

```json
{
  "mcpServers": {
    "everything-search": {
      "command": "python",
      "args": ["-m", "mcp_server_everything_search"],
      "env": {
        "EVERYTHING_SDK_PATH": "C:\\Everything-SDK\\dll\\Everything64.dll"
      }
    }
  }
}
```

--------------------------------

### Claude Desktop Configuration for Windows (uvx)

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Configure Claude Desktop to use the Everything Search MCP Server installed via 'uvx' on Windows. Ensure the EVERYTHING_SDK_PATH environment variable is correctly set.

```json
{
  "mcpServers": {
    "everything-search": {
      "command": "uvx",
      "args": ["mcp-server-everything-search"],
      "env": {
        "EVERYTHING_SDK_PATH": "C:\\Everything-SDK\\dll\\Everything64.dll"
      }
    }
  }
}
```

--------------------------------

### Example Tool Call: Linux Case-Sensitive Regex

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Use this for case-sensitive regex searches on Linux.

```json
{
  "base": {
    "query": "^/etc/[A-Z].*\\.conf$",
    "max_results": 50
  },
  "linux_params": {
    "ignore_case": false,
    "regex_search": true,
    "existing_files": true
  }
}
```

--------------------------------

### SearchResult Dataclass Example

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Demonstrates the structure of a SearchResult dataclass, which contains details about a found file.

```python
from mcp_server_everything_search.search_interface import SearchResult
from datetime import datetime

# Fields populated by every provider:
result = SearchResult(
    path="/home/alice/project/main.py",   # Full filesystem path
    filename="main.py",                    # Basename
    extension="py",                        # Extension without dot (or None)
    size=4096,                             # Size in bytes (or None)
    created=datetime(2024, 1, 1, 9, 0),   # Creation time (or None)
    modified=datetime(2024, 6, 15, 10, 32),
    accessed=datetime(2024, 6, 15, 11, 0),
    attributes=None                        # Windows file attributes (or None)
)

print(f"{result.filename} ({result.extension}) — {result.size:,} bytes")
# main.py (py) — 4,096 bytes
```

--------------------------------

### SearchProvider: Get Provider and Search Files

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Automatically detects the OS and returns the correct search provider. Use this to search for files with specified parameters.

```python
from mcp_server_everything_search.search_interface import SearchProvider

# Automatically picks the right provider for the current OS
provider = SearchProvider.get_provider()

results = provider.search_files(
    query="*.py",
    max_results=25,
    match_case=False,
    match_regex=False
)

for r in results:
    print(f"{r.path}  |  {r.size} bytes  |  modified: {r.modified}")

# Output (Linux/macOS):
# /home/alice/project/main.py  |  4096 bytes  |  modified: 2024-06-15 10:32:00
# /home/alice/project/utils.py  |  2048 bytes  |  modified: 2024-06-14 09:00:00
```

--------------------------------

### Run MCP Server with Inspector

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Use this command to run the server with the MCP inspector for testing purposes. Ensure you have npx installed.

```bash
npx @modelcontextprotocol/inspector uv run mcp-server-everything-search
```

--------------------------------

### Debug MCP Server with Inspector (uvx)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Use this command to debug the MCP server when installed via uvx. It launches the MCP inspector connected to the specified server.

```bash
npx @modelcontextprotocol/inspector uvx mcp-server-everything-search
```

--------------------------------

### Configure Everything Search for Claude Desktop (Windows pip)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Add this JSON configuration to your `claude_desktop_config.json` for Windows when using a pip installation. Ensure the `EVERYTHING_SDK_PATH` environment variable points to your Everything SDK DLL.

```json
"mcpServers": {
  "everything-search": {
    "command": "python",
    "args": ["-m", "mcp_server_everything_search"],
    "env": {
      "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
    }
  }
}
```

--------------------------------

### Configure Everything Search for Claude Desktop (Linux/macOS pip)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Add this JSON configuration to your `claude_desktop_config.json` for Linux and macOS when using a pip installation.

```json
"mcpServers": {
  "everything-search": {
    "command": "python",
    "args": ["-m", "mcp_server_everything_search"]
  }
}
```

--------------------------------

### Run MCP Server as Python Module

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Install the package with pip and then run the MCP server as a Python module. This method is useful for integrated environments.

```bash
python -m mcp_server_everything_search
```

--------------------------------

### Case-sensitive search for specific file (locate)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Performs a case-sensitive search using regular expressions to match a specific file pattern starting with an uppercase letter in the '/etc' directory.

```bash
--regex "^/etc/[A-Z].*\.conf$"
```

--------------------------------

### Set Everything SDK Path (Windows)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Environment variable configuration for Windows to specify the path to the Everything SDK DLL.

```bash
EVERYTHING_SDK_PATH=path\to\Everything-SDK\dll\Everything64.dll
```

--------------------------------

### Configure Everything Search for Claude Desktop (Windows uvx)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Add this JSON configuration to your `claude_desktop_config.json` for Windows when using uvx. Ensure the `EVERYTHING_SDK_PATH` environment variable points to your Everything SDK DLL.

```json
"mcpServers": {
  "everything-search": {
    "command": "uvx",
    "args": ["mcp-server-everything-search"],
    "env": {
      "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
    }
  }
}
```

--------------------------------

### Build Package

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Build the project package using uv. This command is used to create distributable artifacts for the server.

```bash
uv build
```

--------------------------------

### EverythingSDK - Windows-only

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Provides a low-level wrapper for the Everything DLL on Windows, allowing direct interaction with the Everything search index.

```APIDOC
## EverythingSDK - Windows-only

### Description
The `EverythingSDK` class is a low-level wrapper for the Everything DLL, intended for use on Windows systems. It is used internally by `WindowsSearchProvider` but can also be instantiated directly for custom search operations.

### Initialization
Requires the path to the Everything SDK DLL, typically set via the `EVERYTHING_SDK_PATH` environment variable.

### Method
```python
import os
from mcp_server_everything_search.everything_sdk import (
    EverythingSDK,
    EverythingError,
    EVERYTHING_SORT_SIZE_DESCENDING
)

dll_path = os.environ["EVERYTHING_SDK_PATH"]  # e.g. "C:\Everything-SDK\dll\Everything64.dll"

try:
    sdk = EverythingSDK(dll_path)
    results = sdk.search_files(
        query="path:C:\\Projects ext:js",
        max_results=50,
        match_path=True,
        match_case=False,
        match_whole_word=False,
        match_regex=False,
        sort_by=EVERYTHING_SORT_SIZE_DESCENDING
    )
    for r in results:
        print(f"{r.path} | {r.size:,} bytes | modified: {r.modified}")
except EverythingError as e:
    # e.g. "IPC failed (Everything service not running?)"
    print(f"Everything SDK error: {e}")
except RuntimeError as e:
    print(f"Search failed: {e}")
```

### Parameters for `search_files`
- **query** (string) - The search query string.
- **max_results** (integer) - The maximum number of results to return.
- **match_path** (boolean) - Whether to match against the full path.
- **match_case** (boolean) - Whether the search should be case-sensitive.
- **match_whole_word** (boolean) - Whether to match whole words only.
- **match_regex** (boolean) - Whether the query is a regular expression.
- **sort_by** (integer) - Constant specifying the sort order (e.g., `EVERYTHING_SORT_SIZE_DESCENDING`).

### Error Handling
- `EverythingError`: Raised for issues communicating with the Everything service.
- `RuntimeError`: Raised for general search failures.
```

--------------------------------

### Test Local Development Changes with Claude Desktop

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Configure your `claude_desktop_config.json` to test local development changes of the MCP Everything Search server. This configuration uses `uv` to run the server from a specified directory and includes the necessary SDK path.

```json
"everything-search": {
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/mcp-everything-search/src/mcp_server_everything_search",
    "run",
    "mcp-server-everything-search"
  ],
  "env": {
    "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
  }
}
```

--------------------------------

### Configure Everything Search for Claude Desktop (Linux/macOS uvx)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Add this JSON configuration to your `claude_desktop_config.json` for Linux and macOS when using uvx.

```json
"mcpServers": {
  "everything-search": {
    "command": "uvx",
    "args": ["mcp-server-everything-search"]
  }
}
```

--------------------------------

### Build Linux Search Command

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Constructs a search command list for Linux using `build_search_command` from a `UnifiedSearchQuery` with specific Linux parameters.

```python
from mcp_server_everything_search.platform_search import (
    UnifiedSearchQuery, LinuxSpecificParams, build_search_command
)

query = UnifiedSearchQuery(
    query="*.conf",
    linux_params=LinuxSpecificParams(
        ignore_case=True,
        regex_search=False,
        existing_files=True
    )
)

cmd = build_search_command(query)
print(cmd)
# ['locate', '-i', '-e', '*.conf']

import subprocess
output = subprocess.run(cmd, capture_output=True, text=True)
print(output.stdout[:200])
```

--------------------------------

### Debug MCP Server with Inspector (local development)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Use this command for debugging when you have cloned the repository and are developing locally. It launches the MCP inspector connected to the specified server.

```bash
git clone https://github.com/mamertofabian/mcp-everything-search.git
cd mcp-everything-search/src/mcp_server_everything_search
npx @modelcontextprotocol/inspector uv run mcp-server-everything-search
```

--------------------------------

### EverythingSDK: Windows-Only Low-Level Wrapper

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Wraps the Everything DLL via ctypes for Windows. Use this for direct interaction with the Everything SDK, handling potential errors.

```python
import os
from mcp_server_everything_search.everything_sdk import (
    EverythingSDK,
    EverythingError,
    EVERYTHING_SORT_SIZE_DESCENDING,
)

dll_path = os.environ["EVERYTHING_SDK_PATH"]  # e.g. "C:\\Everything-SDK\\dll\\Everything64.dll"

try:
    sdk = EverythingSDK(dll_path)
    results = sdk.search_files(
        query="path:C:\\Projects ext:js",
        max_results=50,
        match_path=True,
        match_case=False,
        match_whole_word=False,
        match_regex=False,
        sort_by=EVERYTHING_SORT_SIZE_DESCENDING
    )
    for r in results:
        print(f"{r.path} | {r.size:,} bytes | modified: {r.modified}")
except EverythingError as e:
    # e.g. "IPC failed (Everything service not running?)"
    print(f"Everything SDK error: {e}")
except RuntimeError as e:
    print(f"Search failed: {e}")
```

--------------------------------

### Monitor for new matches

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Continuously monitors for new files matching the query using the '-live' option. This is useful for tracking changes in real-time.

```bash
mdfind -live "kind:pdf"
```

--------------------------------

### Find files created by application

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for files created by a specific application, using a wildcard for partial name matching.

```bash
kMDItemCreator = "Pixelmator*"
```

--------------------------------

### Run MCP Server Directly

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Execute the MCP server directly using uv. This is a streamlined way to run the server for development or testing.

```bash
uv run mcp-server-everything-search
```

--------------------------------

### Formatting with Ruff

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Automatically format the code according to project standards using Ruff's formatting tool. This ensures a consistent code style.

```bash
uv run ruff format
```

--------------------------------

### View MCP Server Logs (Linux/macOS)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Use the `tail -f` command to continuously monitor MCP server logs on Linux and macOS. Logs are typically located in `~/.config/Claude/logs/`.

```bash
tail -f ~/.config/Claude/logs/mcp*.log
```

--------------------------------

### Find files in a specific folder

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use the 'path:' function to specify a directory and a wildcard to find files within that path.

```text
path:C:\Projects *.js
```

--------------------------------

### Find large video files

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Combine 'ext' for multiple video file extensions with 'size:>' to find files larger than a specified amount.

```text
ext:mp4|mkv|avi size:>1gb
```

--------------------------------

### Equality and inequality search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use '=', '==', or '!=' operators for exact or non-exact matches on metadata values.

```bash
mdfind "kMDItemFSSize = 1024"
```

```bash
mdfind "kMDItemFSSize != 1024"
```

--------------------------------

### View MCP Server Logs (Windows PowerShell)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/README.md

Use the `Get-Content` cmdlet in PowerShell to view the last 20 lines of MCP server logs and wait for new entries on Windows. Logs are typically located in `%APPDATA%\Claude\logs\`.

```powershell
Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Execute the project's test suite using pytest. This command is essential for verifying the correctness of the code.

```bash
uv run pytest
```

--------------------------------

### MCP tool: search

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

The Everything Search MCP Server exposes a single tool named 'search'. This tool's JSON schema is dynamically generated based on the platform and accepts base parameters common to all platforms, along with optional platform-specific parameters.

```APIDOC
## MCP tool: `search`

The only tool exposed by the server. Its JSON schema is generated dynamically by `UnifiedSearchQuery.get_schema_for_platform()` and contains a required `base` object plus an optional platform-specific object (`windows_params`, `mac_params`, or `linux_params`).

### Base parameters (all platforms)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | — | Search query string (required) |
| `max_results` | integer | 100 | Maximum results to return (1–1000) |

### Windows-specific parameters (`windows_params`)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `match_path` | boolean | false | Match against full path instead of filename |
| `match_case` | boolean | false | Case-sensitive matching |
| `match_whole_word` | boolean | false | Whole-word matching |
| `match_regex` | boolean | false | Enable regex in the query |
| `sort_by` | integer | 1 | Sort order (see `WindowsSortOption` enum) |

### macOS-specific parameters (`mac_params`)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `live_updates` | boolean | false | Stream live results as files change |
| `search_directory` | string | null | Restrict search to a directory (`-onlyin`) |
| `literal_query` | boolean | false | Treat query as literal text |
| `interpret_query` | boolean | false | Interpret query as Spotlight input |

### Linux-specific parameters (`linux_params`)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ignore_case` | boolean | true | Case-insensitive search (`-i`) |
| `regex_search` | boolean | false | Use regex patterns (`-r`) |
| `existing_files` | boolean | true | Only return files that currently exist (`-e`) |
| `count_only` | boolean | false | Return only the count of matches (`-c`) |

### Example tool call — Windows: find large video files modified this week

```json
{
  "base": {
    "query": "ext:mp4|mkv|avi size:>500mb datemodified:thisweek",
    "max_results": 20
  },
  "windows_params": {
    "sort_by": 6
  }
}
```

Expected response:
```
Path: C:\Users\alice\Videos\holiday.mp4
Filename: holiday.mp4 (mp4)
Size: 1,234,567,890 bytes
Created: 2024-06-01T10:00:00
Modified: 2024-06-15T18:32:11
Accessed: 2024-06-15T18:32:11

Path: C:\Users\alice\Videos\demo.mkv
Filename: demo.mkv (mkv)
Size: 987,654,321 bytes
...
```
```

--------------------------------

### Find all Python files (locate)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Finds all files with the '.py' extension using the locate command. Wildcards are supported.

```bash
*.py
```

--------------------------------

### Live search with mdfind on macOS

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

The '-live' option for mdfind provides real-time updates to search results as files change.

```bash
mdfind -live "some search query"
```

--------------------------------

### Find files in home directory (locate)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for files within the specified directory path using wildcards.

```bash
/home/username/*
```

--------------------------------

### Search by content type with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use the 'kind:' specifier followed by a content type alias to filter search results.

```bash
mdfind "kind:image"
```

```bash
mdfind "kind:movie"
```

```bash
mdfind "kind:email"
```

--------------------------------

### Count matching files (locate)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Counts the number of files matching a query using the '-c' option with locate/plocate.

```bash
Use with -c parameter
```

--------------------------------

### Comparison operators with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use '<', '>', '<=', '>=' operators for numerical or date comparisons on metadata values.

```bash
mdfind "kMDItemFSSize < 1024"
```

```bash
mdfind "kMDItemFSCreationDate >= $time"
```

--------------------------------

### Basic text search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

A simple text search in mdfind matches the query string against any metadata attribute. Wildcards are supported.

```bash
mdfind "search term"
```

--------------------------------

### Type Checking with Pyright

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Perform static type checking on the codebase using Pyright. This command helps ensure type safety and code quality.

```bash
uv run pyright
```

--------------------------------

### Find files by tag

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for files tagged with 'Important' using the kMDItemUserTags metadata attribute.

```bash
kMDItemUserTags = "Important"
```

--------------------------------

### Count matching files

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Counts the number of files that match the specified search query using the '-count' option.

```bash
mdfind -count "kind:image date:today"
```

--------------------------------

### Find Python files modified today

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use the 'ext' function to specify file extensions and 'datemodified' with 'today' to filter by modification date.

```text
ext:py datemodified:today
```

--------------------------------

### Linting with Ruff

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/CLAUDE.md

Check the code for style and potential errors using Ruff's linting capabilities. This command helps maintain code consistency.

```bash
uv run ruff check
```

--------------------------------

### WindowsSortOption Enum

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Provides strongly-typed sort constants for Windows searches. Use these constants to specify sorting preferences.

```python
from mcp_server_everything_search.platform_search import WindowsSortOption

# All available values:
# WindowsSortOption.NAME_ASC     = 1   NAME_DESC    = 2
# WindowsSortOption.PATH_ASC     = 3   PATH_DESC    = 4
# WindowsSortOption.SIZE_ASC     = 5   SIZE_DESC    = 6
# WindowsSortOption.EXT_ASC      = 7   EXT_DESC     = 8
# WindowsSortOption.CREATED_ASC  = 11  CREATED_DESC = 12
```

--------------------------------

### Find recent presentations

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for presentation files modified within the current week.

```bash
kind:presentation date:this week
```

--------------------------------

### Find documents by author (case-insensitive)

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for documents where the author metadata matches 'John Doe', ignoring case. Uses the kMDItemAuthors attribute.

```bash
kMDItemAuthors ==[c] "John Doe"
```

--------------------------------

### Interpret query with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

The '-interpret' option makes mdfind process the query as if it were typed directly into the macOS Spotlight menu.

```bash
mdfind -interpret "some search query"
```

--------------------------------

### Count search results with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use the '-count' option with mdfind to display only the number of matching files instead of the file paths.

```bash
mdfind -count "some search query"
```

--------------------------------

### Literal search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use the '-literal' option to ensure the search query is treated as plain text without any special interpretation.

```bash
mdfind -literal "search * query"
```

--------------------------------

### OR condition search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Use the '|' operator within quotes to perform an OR search, matching either of the specified terms.

```bash
mdfind "image|photo"
```

--------------------------------

### AND condition search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Multiple words in an mdfind query are treated as an AND condition, requiring all terms to be present.

```bash
mdfind "word1 word2"
```

--------------------------------

### Find images modified yesterday

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for files of kind 'image' that were modified yesterday. This uses the date filter.

```bash
kind:image date:yesterday
```

--------------------------------

### Find files in specific directory

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Limits the search to files within the specified directory, using the '-onlyin' option.

```bash
mdfind -onlyin ~/Documents "query"
```

--------------------------------

### Limit mdfind search to a directory

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

The '-onlyin' option restricts the mdfind search to a specified directory.

```bash
mdfind -onlyin "/path/to/directory" "some search query"
```

--------------------------------

### Find PDFs with specific text

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Searches for PDF files containing the specified text.

```bash
kind:pdf "search term"
```

--------------------------------

### Case and diacritical insensitive search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Append '[c]' for case-insensitivity or '[d]' for diacritical marks insensitivity within brackets to comparison operators.

```bash
mdfind "kMDItemDisplayName = 'MyDocument'[c]"
```

```bash
mdfind "kMDItemDisplayName = 'Résumé'[d]"
```

```bash
mdfind "kMDItemDisplayName = 'MyDocument'[cd]"
```

--------------------------------

### NOT condition search with mdfind

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Prefix a term with '-' to exclude results containing that term.

```bash
mdfind "-screenshot"
```

--------------------------------

### SearchResult Dataclass

Source: https://context7.com/mamertofabian/mcp-everything-search/llms.txt

Details the structure of the `SearchResult` dataclass, which is used to return file information from search operations.

```APIDOC
## SearchResult Dataclass

### Description
The `SearchResult` dataclass serves as a universal container for file information returned by any search provider. It includes fields such as path, filename, extension, size, and timestamps.

### Fields
- **path** (string) - Full filesystem path to the file.
- **filename** (string) - The base name of the file.
- **extension** (string | None) - The file extension without the leading dot, or None if no extension.
- **size** (integer | None) - The file size in bytes, or None.
- **created** (datetime | None) - The creation timestamp of the file, or None.
- **modified** (datetime | None) - The last modification timestamp of the file, or None.
- **accessed** (datetime | None) - The last access timestamp of the file, or None.
- **attributes** (any | None) - Windows-specific file attributes, or None.

### Example Usage
```python
from mcp_server_everything_search.search_interface import SearchResult
from datetime import datetime

result = SearchResult(
    path="/home/alice/project/main.py",   # Full filesystem path
    filename="main.py",                    # Basename
    extension="py",                        # Extension without dot (or None)
    size=4096,                             # Size in bytes (or None)
    created=datetime(2024, 1, 1, 9, 0),   # Creation time (or None)
    modified=datetime(2024, 6, 15, 10, 32),
    accessed=datetime(2024, 6, 15, 11, 0),
    attributes=None                        # Windows file attributes (or None)
)

print(f"{result.filename} ({result.extension}) — {result.size:,} bytes")
```

### Output Example
```
main.py (py) — 4,096 bytes
```
```

--------------------------------

### Complex metadata search

Source: https://github.com/mamertofabian/mcp-everything-search/blob/main/SEARCH_SYNTAX.md

Performs a complex search combining content type, user tags, and modification date within the current month.

```bash
kMDItemContentTypeTree = "public.image" && kMDItemUserTags = "vacation" && kMDItemFSContentChangeDate >= $time.this_month()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.