# @shxiaj/everything-mcp

MCP (Model Context Protocol) server for [Everything](https://www.voidtools.com/) — the lightning-fast Windows file search engine.

> Forked and extended from [everythingsdk-mcp](https://www.npmjs.com/package/everythingsdk-mcp).

Uses [ffi-rs](https://github.com/zhangyuang/node-ffi-rs) to call the Everything SDK natively and [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) for the MCP server protocol.

## Features

- **Dual SDK support** — Auto-detects Everything 1.5 (SDK v3) or 1.4 (SDK v2)
- **Lightning-fast file search** — Leverage Everything's native search capabilities
- **Multiple tools** — Search, version check, status, and file info
- **Flexible configuration** — Environment variable overrides for SDK paths

## Prerequisites

- **Windows** (the Everything SDK is Windows-only)
- **Everything 1.4+** installed and running ([download](https://www.voidtools.com/))
- **Node.js 18+** and **npm**

## Installation

```bash
npm install
npm run build
```

## Usage

### Running the MCP server

```bash
npx @shxiaj/everything-mcp
```

The server communicates via stdin/stdout (MCP stdio transport).

### Configuring in Claude Desktop / VS Code Copilot

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "@shxiaj/everything-mcp": {
      "command": "npx",
      "args": ["@shxiaj/everything-mcp"]
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|---|---|---|
| `EVERYTHING_SDK_VERSION` | Force SDK version (`v3` or `v2`) | Auto-detect |
| `EVERYTHING_SDK_DIR` | Path to the Everything SDK v3 directory | `./everything_sdk3/dll` |
| `EVERYTHING_DLL_PATH` | Full path to the Everything SDK v3 DLL | `$SDK_DIR/Everything3_x64.dll` |
| `EVERYTHING_V2_SDK_DIR` | Path to the Everything SDK v2 directory | `./Everything-SDK/dll` |
| `EVERYTHING_V2_DLL_PATH` | Full path to the Everything SDK v2 DLL | `$V2_SDK_DIR/Everything64.dll` |
| `EVERYTHING_IPC_PIPE_NAME` | Override v3 IPC pipe name | Auto-probe |

## Tools

### `everything_search`

Search for files and folders using Everything search syntax.

**Parameters:**
- `query` (required) — Search query using Everything syntax
- `maxResults` — Max results (default: 50, max: 1000)
- `offset` — Zero-based offset for pagination
- `matchCase` — Case-sensitive search
- `matchWholeWord` — Match whole words only
- `matchPath` — Match against full path
- `regex` — Treat query as regex

**Everything search syntax examples:**
- `*.txt` — all .txt files
- `foo bar` — files containing both "foo" AND "bar"
- `foo|bar` — files containing "foo" OR "bar"
- `ext:jpg size:>1mb` — JPEGs larger than 1 MB
- `folder:node_modules` — folders named node_modules
- `content:TODO` — files containing "TODO" in their content
- `datemodified:today` — files modified today
- `parent:C:\Projects` — files under C:\Projects

### `everything_version`

Get the version information of the running Everything instance.

### `everything_status`

Check if Everything is running and its database is loaded.

### `everything_file_info`

Get Windows file attributes and run count for a specific file path.

**Parameters:**
- `path` (required) — Full path to the file or folder

## SDK Architecture

```
src/
├── index.ts              # MCP server entry point (tools, request handlers)
├── everything-client.ts  # EverythingClient + SdkProvider abstraction
├── ffi-bindings.ts       # Raw FFI bindings to Everything3_*.dll (SDK v3, Everything 1.5)
└── ffi-bindings-v14.ts   # Raw FFI bindings to Everything*.dll (SDK v2, Everything 1.4)
```

`EverythingClient` auto-detects the SDK version: tries v3 first, falls back to v2. Override with `EVERYTHING_SDK_VERSION=v2` or `v3` env var.

### SDK v3 (Everything 1.5) vs SDK v2 (Everything 1.4)

| Aspect | SDK v3 (Everything 1.5) | SDK v2 (Everything 1.4) |
|---|---|---|
| DLL names | `Everything3_x64.dll` | `Everything64.dll` |
| API prefix | `Everything3_*` | `Everything_*` |
| Connection | Explicit `ConnectW`/`DestroyClient` handles | Implicit via IPC on `QueryW` |
| State model | Per-client, per-search-state objects | Global mutable state |
| Search exec | `Search(client, state)` returns result list | `QueryW(TRUE)` populates global results |
| Result props | Must call `AddSearchPropertyRequest` first | Use `SetRequestFlags` bitmask |
| File info | Direct `GetFileAttributesW(client, path)` | Requires a search with `SetMatchPath(true)` |

## License

MIT