everything-mcp 1.0.0__tar.gz → 1.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,19 +1,34 @@
1
- # Changelog
1
+ # Changelog
2
+
3
+ All notable changes to **everything-mcp** will be documented in this file.
4
+
5
+ ## [1.0.2] - 2026-02-04
2
6
 
3
- All notable changes to **everything-mcp** will be documented in this file.
7
+ ### Changed
4
8
 
5
- ## [1.0.0] 2026-02-04
9
+ - Updated package metadata author to `elis132` (removed author email from PyPI metadata).
10
+ - Updated LICENSE copyright holder name to `elis132`.
6
11
 
7
- ### Added
8
-
9
- - **5 AI-optimised tools**: `everything_search`, `everything_search_by_type`, `everything_find_recent`, `everything_file_details`, `everything_count_stats`
10
- - **Zero-config auto-detection**: finds es.exe via PATH, common install locations, and Windows Registry
11
- - **Everything 1.5 alpha** auto-detection (default 1.5a instance probing)
12
- - **Content preview**: read first N lines of source code and text files
13
- - **10 file type categories**: audio, video, image, document, code, archive, executable, font, 3d, data
14
- - **14 sort options**, **19 time period presets**
15
- - **Extension breakdown analytics** in count_stats tool
16
- - Comprehensive test suite with pytest
17
- - PEP 561 `py.typed` marker
18
- - Full documentation with configuration examples for Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini, Kimi, Qwen
19
- - `everything://status` MCP resource for health checks
12
+ ## [1.0.1] - 2026-02-04
13
+
14
+ ### Fixed
15
+
16
+ - Fixed `everything_count_stats` reporting `0` for `total_count` and `total_size` on some systems.
17
+ - Updated backend aggregate queries to avoid incompatible `es.exe` flag combinations (`-n 0` with `-get-result-count` / `-get-total-size`).
18
+ - Added backend tests to verify aggregate command construction.
19
+
20
+ ## [1.0.0] 2026-02-04
21
+
22
+ ### Added
23
+
24
+ - **5 AI-optimised tools**: `everything_search`, `everything_search_by_type`, `everything_find_recent`, `everything_file_details`, `everything_count_stats`
25
+ - **Zero-config auto-detection**: finds es.exe via PATH, common install locations, and Windows Registry
26
+ - **Everything 1.5 alpha** auto-detection (default → 1.5a instance probing)
27
+ - **Content preview**: read first N lines of source code and text files
28
+ - **10 file type categories**: audio, video, image, document, code, archive, executable, font, 3d, data
29
+ - **14 sort options**, **19 time period presets**
30
+ - **Extension breakdown analytics** in count_stats tool
31
+ - Comprehensive test suite with pytest
32
+ - PEP 561 `py.typed` marker
33
+ - Full documentation with configuration examples for Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini, Kimi, Qwen
34
+ - `everything://status` MCP resource for health checks
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Elis
3
+ Copyright (c) 2026 elis132
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: everything-mcp
3
- Version: 1.0.0
3
+ Version: 1.0.2
4
4
  Summary: The definitive MCP server for voidtools Everything — lightning-fast file search for AI agents
5
5
  Project-URL: Homepage, https://github.com/elis132/everything-mcp
6
6
  Project-URL: Repository, https://github.com/elis132/everything-mcp
7
7
  Project-URL: Issues, https://github.com/elis132/everything-mcp/issues
8
8
  Project-URL: Changelog, https://github.com/elis132/everything-mcp/blob/main/CHANGELOG.md
9
- Author-email: Elis <elis@egf.se>
9
+ Author: elis132
10
10
  License: MIT
11
11
  License-File: LICENSE
12
12
  Keywords: ai-agent,claude,codex,everything,file-search,gemini,mcp,model-context-protocol,voidtools
@@ -31,15 +31,18 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
31
31
  Requires-Dist: ruff>=0.4; extra == 'dev'
32
32
  Description-Content-Type: text/markdown
33
33
 
34
- # ⚡ Everything MCP
35
-
36
- **The definitive MCP server for [voidtools Everything](https://www.voidtools.com/)** — lightning-fast file search for AI agents.
37
-
38
- [![PyPI](https://img.shields.io/pypi/v/everything-mcp)](https://pypi.org/project/everything-mcp/)
39
- [![Python](https://img.shields.io/pypi/pyversions/everything-mcp)](https://pypi.org/project/everything-mcp/)
40
- [![License](https://img.shields.io/github/license/elis132/everything-mcp)](LICENSE)
41
-
42
- Search millions of files in milliseconds. Built for **Claude Code**, **Codex**, **Gemini**, **Kimi**, **Qwen**, **Cursor**, **Windsurf**, and any MCP-compatible client.
34
+ <div align="center">
35
+ <h1>⚡ Everything MCP</h1>
36
+ <p>
37
+ <strong>The definitive MCP server for <a href="https://www.voidtools.com/">voidtools Everything</a> — lightning-fast file search for AI agents.</strong>
38
+ </p>
39
+ <p>
40
+ <a href="https://pypi.org/project/everything-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/everything-mcp"></a>
41
+ <a href="https://pypi.org/project/everything-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/everything-mcp"></a>
42
+ <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/elis132/everything-mcp"></a>
43
+ </p>
44
+ <p>Search millions of files in milliseconds. Built for <strong>Claude Code</strong>, <strong>Codex</strong>, <strong>Gemini</strong>, <strong>Kimi</strong>, <strong>Qwen</strong>, <strong>Cursor</strong>, <strong>Windsurf</strong>, and any MCP-compatible client.</p>
45
+ </div>
43
46
 
44
47
  ---
45
48
 
@@ -57,6 +60,48 @@ Search millions of files in milliseconds. Built for **Claude Code**, **Codex**,
57
60
  | **Test suite** | ✅ pytest | ❌ | ❌ |
58
61
  | **Zero config** | ✅ Works out of the box | ❌ Need SDK DLL path | ❌ Need es.exe in PATH |
59
62
 
63
+ ## Performance
64
+
65
+ Real benchmark from this machine (Windows, query: `everything.exe`):
66
+
67
+ - `everything-mcp` (Everything index via `es.exe`): **220.22 ms avg** (5 runs)
68
+ - Naive filesystem walk over `C:\`: **66,539.03 ms** (single run)
69
+ - Observed speedup: **~302x faster**
70
+
71
+ Reproduce locally (PowerShell):
72
+
73
+ ```powershell
74
+ @'
75
+ import os
76
+ import subprocess
77
+ import time
78
+ import statistics
79
+
80
+ ES = os.path.expandvars(r"%LOCALAPPDATA%\Everything\es.exe")
81
+ QUERY = "everything.exe"
82
+
83
+ es_runs = []
84
+ for _ in range(5):
85
+ t0 = time.perf_counter()
86
+ subprocess.run([ES, "-n", "100", QUERY], capture_output=True, text=True)
87
+ es_runs.append((time.perf_counter() - t0) * 1000)
88
+
89
+ t0 = time.perf_counter()
90
+ matches = []
91
+ for dirpath, _, filenames in os.walk(r"C:\\"):
92
+ for name in filenames:
93
+ if name.lower() == QUERY:
94
+ matches.append(os.path.join(dirpath, name))
95
+ walk_ms = (time.perf_counter() - t0) * 1000
96
+
97
+ es_avg = statistics.mean(es_runs)
98
+ print("ES avg ms:", round(es_avg, 2))
99
+ print("Walk ms:", round(walk_ms, 2))
100
+ print("Speedup x:", round(walk_ms / es_avg, 1))
101
+ print("Matches:", len(matches))
102
+ '@ | python -
103
+ ```
104
+
60
105
  ## Installation
61
106
 
62
107
  ### Prerequisites
@@ -1,462 +1,507 @@
1
- # ⚡ Everything MCP
2
-
3
- **The definitive MCP server for [voidtools Everything](https://www.voidtools.com/)** — lightning-fast file search for AI agents.
4
-
5
- [![PyPI](https://img.shields.io/pypi/v/everything-mcp)](https://pypi.org/project/everything-mcp/)
6
- [![Python](https://img.shields.io/pypi/pyversions/everything-mcp)](https://pypi.org/project/everything-mcp/)
7
- [![License](https://img.shields.io/github/license/elis132/everything-mcp)](LICENSE)
8
-
9
- Search millions of files in milliseconds. Built for **Claude Code**, **Codex**, **Gemini**, **Kimi**, **Qwen**, **Cursor**, **Windsurf**, and any MCP-compatible client.
10
-
11
- ---
12
-
13
- ## Why This One?
14
-
15
- | Feature | everything-mcp (this) | mamertofabian (271⭐) | essovius (0⭐) |
16
- |---|---|---|---|
17
- | **Tools** | 5 well-designed | 1 generic | 16 granular |
18
- | **Auto-detection** | Finds Everything + es.exe automatically | Manual DLL path | Manual setup |
19
- | **Everything 1.5** | ✅ Auto-detects instance | ❌ No support | ⚠️ Manual flag |
20
- | **Content preview** | Read first N lines | | |
21
- | **File type categories** | ✅ 10 categories | ❌ | |
22
- | **Stats & counts** | ✅ Size stats, extension breakdown | ❌ | Partial |
23
- | **Error handling** | ✅ All tools return clean errors | ❌ Raw exceptions | ❌ |
1
+ <div align="center">
2
+ <h1>⚡ Everything MCP</h1>
3
+ <p>
4
+ <strong>The definitive MCP server for <a href="https://www.voidtools.com/">voidtools Everything</a> — lightning-fast file search for AI agents.</strong>
5
+ </p>
6
+ <p>
7
+ <a href="https://pypi.org/project/everything-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/everything-mcp"></a>
8
+ <a href="https://pypi.org/project/everything-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/everything-mcp"></a>
9
+ <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/elis132/everything-mcp"></a>
10
+ </p>
11
+ <p>Search millions of files in milliseconds. Built for <strong>Claude Code</strong>, <strong>Codex</strong>, <strong>Gemini</strong>, <strong>Kimi</strong>, <strong>Qwen</strong>, <strong>Cursor</strong>, <strong>Windsurf</strong>, and any MCP-compatible client.</p>
12
+ </div>
13
+
14
+ ---
15
+
16
+ ## Why This One?
17
+
18
+ | Feature | everything-mcp (this) | mamertofabian (271⭐) | essovius (0⭐) |
19
+ |---|---|---|---|
20
+ | **Tools** | 5 well-designed | 1 generic | 16 granular |
21
+ | **Auto-detection** | ✅ Finds Everything + es.exe automatically | ❌ Manual DLL path | Manual setup |
22
+ | **Everything 1.5** | ✅ Auto-detects instance | ❌ No support | ⚠️ Manual flag |
23
+ | **Content preview** | ✅ Read first N lines | ❌ | ❌ |
24
+ | **File type categories** | ✅ 10 categories | ❌ | ✅ |
25
+ | **Stats & counts** | ✅ Size stats, extension breakdown | ❌ | Partial |
26
+ | **Error handling** | ✅ All tools return clean errors | ❌ Raw exceptions | ❌ |
24
27
  | **Test suite** | ✅ pytest | ❌ | ❌ |
25
28
  | **Zero config** | ✅ Works out of the box | ❌ Need SDK DLL path | ❌ Need es.exe in PATH |
26
29
 
27
- ## Installation
28
-
29
- ### Prerequisites
30
-
31
- 1. **Windows** with [Everything](https://www.voidtools.com/) installed and **running**
32
- 2. **es.exe** (Everything command-line interface):
33
- - **Everything 1.5 alpha**: es.exe is included
34
- - **Everything 1.4**: Download from [github.com/voidtools/es](https://github.com/voidtools/es/releases)
35
- - Place `es.exe` in your PATH or in the Everything installation directory
36
- 3. **Python 3.10+** or **uv**
37
-
38
- ### Via uv (recommended — no install needed)
39
-
40
- ```bash
41
- uvx everything-mcp
42
- ```
43
-
44
- ### Via pip
45
-
46
- ```bash
47
- pip install everything-mcp
30
+ ## Performance
31
+
32
+ Real benchmark from this machine (Windows, query: `everything.exe`):
33
+
34
+ - `everything-mcp` (Everything index via `es.exe`): **220.22 ms avg** (5 runs)
35
+ - Naive filesystem walk over `C:\`: **66,539.03 ms** (single run)
36
+ - Observed speedup: **~302x faster**
37
+
38
+ Reproduce locally (PowerShell):
39
+
40
+ ```powershell
41
+ @'
42
+ import os
43
+ import subprocess
44
+ import time
45
+ import statistics
46
+
47
+ ES = os.path.expandvars(r"%LOCALAPPDATA%\Everything\es.exe")
48
+ QUERY = "everything.exe"
49
+
50
+ es_runs = []
51
+ for _ in range(5):
52
+ t0 = time.perf_counter()
53
+ subprocess.run([ES, "-n", "100", QUERY], capture_output=True, text=True)
54
+ es_runs.append((time.perf_counter() - t0) * 1000)
55
+
56
+ t0 = time.perf_counter()
57
+ matches = []
58
+ for dirpath, _, filenames in os.walk(r"C:\\"):
59
+ for name in filenames:
60
+ if name.lower() == QUERY:
61
+ matches.append(os.path.join(dirpath, name))
62
+ walk_ms = (time.perf_counter() - t0) * 1000
63
+
64
+ es_avg = statistics.mean(es_runs)
65
+ print("ES avg ms:", round(es_avg, 2))
66
+ print("Walk ms:", round(walk_ms, 2))
67
+ print("Speedup x:", round(walk_ms / es_avg, 1))
68
+ print("Matches:", len(matches))
69
+ '@ | python -
48
70
  ```
49
71
 
50
- ### From source
51
-
52
- ```bash
53
- git clone https://github.com/elis132/everything-mcp.git
54
- cd everything-mcp
55
- pip install -e ".[dev]"
56
- ```
57
-
58
- ---
59
-
60
- ## Configuration
61
-
62
- <details>
63
- <summary>Shared MCP JSON Template</summary>
64
-
65
- Use this server definition anywhere a client asks for MCP JSON:
66
-
67
- ```json
68
- {
69
- "mcpServers": {
70
- "everything": {
71
- "command": "uvx",
72
- "args": ["everything-mcp"]
73
- }
74
- }
75
- }
76
- ```
77
- </details>
78
-
79
- <details>
80
- <summary>Claude Code</summary>
81
-
82
- Use the Claude Code CLI:
83
-
84
- ```bash
85
- claude mcp add everything -- uvx everything-mcp
86
- claude mcp list
87
- ```
88
-
89
- Or add to `.claude/settings.json`:
90
-
91
- ```json
92
- {
93
- "mcpServers": {
94
- "everything": {
95
- "command": "uvx",
96
- "args": ["everything-mcp"]
97
- }
98
- }
99
- }
100
- ```
101
- </details>
102
-
103
- <details>
104
- <summary>Claude Desktop</summary>
105
-
106
- Add to `%APPDATA%\Claude\claude_desktop_config.json`:
107
-
108
- ```json
109
- {
110
- "mcpServers": {
111
- "everything": {
112
- "command": "uvx",
113
- "args": ["everything-mcp"]
114
- }
115
- }
116
- }
117
- ```
118
- </details>
119
-
120
- <details>
121
- <summary>Codex CLI</summary>
122
-
123
- Use the Codex CLI:
124
-
125
- ```bash
126
- codex mcp add everything -- uvx everything-mcp
127
- codex mcp list
128
- ```
129
- </details>
130
-
131
- <details>
132
- <summary>Gemini CLI</summary>
133
-
134
- Use the Gemini CLI:
135
-
136
- ```bash
137
- gemini mcp add -s user everything uvx everything-mcp
138
- gemini mcp list
139
- ```
140
- </details>
141
-
142
- <details>
143
- <summary>Kimi CLI</summary>
144
-
145
- Use the Kimi CLI:
146
-
147
- ```bash
148
- kimi mcp add --transport stdio everything -- uvx everything-mcp
149
- kimi mcp list
150
- ```
151
- </details>
152
-
153
- <details>
154
- <summary>Qwen CLI</summary>
155
-
156
- Use the Qwen CLI:
157
-
158
- ```bash
159
- qwen mcp add -s user everything uvx everything-mcp
160
- qwen mcp list
161
- ```
162
- </details>
163
-
164
- <details>
165
- <summary>Cursor</summary>
166
-
167
- Cursor currently uses MCP settings/deeplinks rather than a stable `mcp add`
168
- CLI command. Add the JSON config in Cursor's MCP settings UI.
169
- </details>
170
-
171
- <details>
172
- <summary>Windsurf</summary>
173
-
174
- Windsurf currently uses MCP settings rather than a stable `mcp add` CLI
175
- command. On Windows, add the JSON config to:
176
-
177
- `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
178
- </details>
179
-
180
- <details>
181
- <summary>Generic MCP Clients</summary>
182
-
183
- Any MCP-compatible client can use this format:
184
-
185
- ```json
186
- {
187
- "mcpServers": {
188
- "everything": {
189
- "command": "uvx",
190
- "args": ["everything-mcp"]
191
- }
192
- }
193
- }
194
- ```
195
- </details>
196
-
197
- <details>
198
- <summary>Using pip Instead of uvx</summary>
199
-
200
- ```json
201
- {
202
- "mcpServers": {
203
- "everything": {
204
- "command": "everything-mcp"
205
- }
206
- }
207
- }
208
- ```
209
-
210
- Or with explicit Python:
211
-
212
- ```json
213
- {
214
- "mcpServers": {
215
- "everything": {
216
- "command": "python",
217
- "args": ["-m", "everything_mcp"]
218
- }
219
- }
220
- }
221
- ```
222
- </details>
223
-
224
- ---
225
-
226
- ## Environment Variables (Optional)
227
-
228
- Everything MCP auto-detects your setup, but you can override:
229
-
230
- | Variable | Description | Example |
231
- |---|---|---|
232
- | `EVERYTHING_ES_PATH` | Path to es.exe | `C:\Program Files\Everything\es.exe` |
233
- | `EVERYTHING_INSTANCE` | Everything instance name | `1.5a` |
234
-
235
- ```json
236
- {
237
- "mcpServers": {
238
- "everything": {
239
- "command": "uvx",
240
- "args": ["everything-mcp"],
241
- "env": {
242
- "EVERYTHING_INSTANCE": "1.5a"
243
- }
244
- }
245
- }
246
- }
247
- ```
248
-
249
- ---
250
-
251
- ## Tools
252
-
253
- ### 1. `everything_search` The Workhorse
254
-
255
- Search files and folders using Everything's full query syntax.
256
-
257
- | Parameter | Default | Description |
258
- |---|---|---|
259
- | `query` | *(required)* | Everything search query |
260
- | `max_results` | 50 | 1–500 |
261
- | `sort` | `date-modified-desc` | See sort options below |
262
- | `match_case` | false | Case-sensitive |
263
- | `match_whole_word` | false | Whole words only |
264
- | `match_regex` | false | Regex mode |
265
- | `match_path` | false | Match full path |
266
- | `offset` | 0 | Pagination offset |
267
-
268
- **Everything Search Syntax:**
269
-
270
- ```
271
- *.py → All Python files
272
- ext:py;js;ts → Multiple extensions
273
- ext:py path:C:\Projects → Python files in Projects
274
- size:>10mb → Larger than 10 MB
275
- size:1kb..1mb → Between 1 KB and 1 MB
276
- dm:today → Modified today
277
- dm:last1week → Modified in the last week
278
- dc:2024 → Created in 2024
279
- "exact name.txt" → Exact filename match
280
- project1 | project2 → OR search
281
- !node_modules → Exclude term
282
- ext:py !test !__pycache__ → Python, excluding tests
283
- content:TODO → Files containing TODO (requires content indexing)
284
- regex:^test_.*\.py$ → Regex search
285
- parent:src ext:py → Python files in 'src' folders
286
- dupe: → Duplicate filenames
287
- empty: → Empty folders
288
- ```
289
-
290
- ### 2. `everything_search_by_type` — Category Search
291
-
292
- Search by pre-defined file type categories.
293
-
294
- **Categories:** `audio`, `video`, `image`, `document`, `code`, `archive`, `executable`, `font`, `3d`, `data`
295
-
296
- | Parameter | Default | Description |
297
- |---|---|---|
298
- | `file_type` | *(required)* | Category name |
299
- | `query` | `""` | Additional filter |
300
- | `path` | `""` | Directory restriction |
301
- | `max_results` | 50 | 1–500 |
302
- | `sort` | `date-modified-desc` | Sort order |
303
-
304
- ### 3. `everything_find_recent` — What Changed?
305
-
306
- Find recently modified files. Sorted newest-first.
307
-
308
- **Periods:** `1min`, `5min`, `10min`, `15min`, `30min`, `1hour`, `2hours`, `6hours`, `12hours`, `today`, `yesterday`, `1day`, `3days`, `1week`, `2weeks`, `1month`, `3months`, `6months`, `1year`
309
-
310
- | Parameter | Default | Description |
311
- |---|---|---|
312
- | `period` | `1hour` | Time period |
313
- | `path` | `""` | Directory restriction |
314
- | `extensions` | `""` | Extension filter (e.g. `py,js,ts`) |
315
- | `query` | `""` | Additional filter |
316
- | `max_results` | 50 | 1–500 |
317
-
318
- ### 4. `everything_file_details` — Deep Inspection
319
-
320
- Get metadata and optional content preview for specific files.
321
-
322
- | Parameter | Default | Description |
323
- |---|---|---|
324
- | `paths` | *(required)* | File paths to inspect (1–20) |
325
- | `preview_lines` | 0 | Lines of text to preview (0–200) |
326
-
327
- **Returns:** Full metadata (size, dates, permissions, hidden status). Directories: item count and listing. Text files with preview: first N lines of content.
328
-
329
- ### 5. `everything_count_stats` Quick Analytics
330
-
331
- Get count and size statistics without listing individual files.
332
-
333
- | Parameter | Default | Description |
334
- |---|---|---|
335
- | `query` | *(required)* | Search query |
336
- | `include_size` | true | Calculate total size |
337
- | `breakdown_by_extension` | false | Sampled per-extension stats (files only) |
338
-
339
- ---
340
-
341
- ## Examples
342
-
343
- > "Find all Python files modified today in my project"
344
-
345
- `everything_find_recent(period="today", extensions="py", path="C:\Projects\myapp")`
346
-
347
- > "How much disk space do my log files use?"
348
-
349
- → `everything_count_stats(query="ext:log", include_size=true, breakdown_by_extension=true)`
350
-
351
- > "Show me the first 50 lines of that config file"
352
-
353
- → `everything_file_details(paths=["C:\Projects\app\config.yaml"], preview_lines=50)`
354
-
355
- > "Find all duplicate filenames in Documents"
356
-
357
- → `everything_search(query='dupe: path:"C:\Users\me\Documents"')`
358
-
359
- > "Find all images larger than 5MB"
360
-
361
- → `everything_search(query="ext:jpg;png;gif size:>5mb")`
362
-
363
- ---
364
-
365
- ## Troubleshooting
366
-
367
- ### "es.exe not found"
368
-
369
- 1. Ensure Everything is installed: https://www.voidtools.com/
370
- 2. Download es.exe: https://github.com/voidtools/es/releases
371
- 3. Place es.exe in your PATH or set `EVERYTHING_ES_PATH`
372
-
373
- ### "Everything IPC window not found"
374
-
375
- 1. Ensure Everything is **running** (check system tray)
376
- 2. If using Everything 1.5 alpha, set `EVERYTHING_INSTANCE=1.5a`
377
- 3. Ensure you're not running Everything Lite (no IPC support)
378
-
379
- ### "No results for valid queries"
380
-
381
- 1. Verify Everything's index is built (needs time on first run)
382
- 2. Try the same query in Everything's GUI
383
- 3. Check that the drive/path is included in Everything's index settings
384
-
385
- ### Debugging
386
-
387
- ```bash
388
- # View server logs
389
- everything-mcp 2>everything-mcp.log
390
-
391
- # MCP Inspector
392
- npx @modelcontextprotocol/inspector uvx everything-mcp
393
- ```
394
-
395
- ---
396
-
397
- ## Architecture
398
-
399
- ```
400
- ┌──────────────┐ MCP (stdio) ┌──────────────────┐
401
- │ AI Agent │◄────────────────────►│ Everything MCP │
402
- (Claude, │ │ Server │
403
- │ Codex, etc) │ │ │
404
- └──────────────┘ │ 5 Tools: │
405
- │ • search │
406
- │ • search_by_type│
407
- │ • find_recent │
408
- │ • file_details │
409
- │ • count_stats │
410
- └────────┬─────────┘
411
- async subprocess
412
-
413
- ┌──────────────────┐
414
- │ es.exe │
415
- │ (CLI interface) │
416
- └────────┬─────────┘
417
- │ IPC / Named Pipes
418
-
419
- ┌──────────────────┐
420
- │ Everything │
421
- │ Service │
422
- │ (voidtools) │
423
- │ │
424
- Real-time NTFS
425
- file index
426
- └──────────────────┘
427
- ```
428
-
429
- ---
430
-
431
- ## Development
432
-
433
- ```bash
434
- # Install with dev dependencies
435
- pip install -e ".[dev]"
436
-
437
- # Run tests
438
- pytest
439
-
440
- # Lint
441
- ruff check src/ tests/
442
- ```
443
-
444
- ## Contributing
445
-
446
- Contributions welcome! Areas for improvement:
447
-
448
- - Direct named pipe IPC (bypass es.exe for lower latency)
449
- - Everything SDK3 integration for Everything 1.5
450
- - Content search integration
451
- - File watching / change notifications
452
- - Bookmark and tag support (Everything 1.5)
453
-
454
- ## License
455
-
456
- MIT — see [LICENSE](LICENSE)
457
-
458
- ## Acknowledgments
459
-
460
- - [voidtools](https://www.voidtools.com/) for the incredible Everything search engine
461
- - [Anthropic](https://anthropic.com/) for the Model Context Protocol specification
462
- - The MCP community for driving adoption across AI tools
72
+ ## Installation
73
+
74
+ ### Prerequisites
75
+
76
+ 1. **Windows** with [Everything](https://www.voidtools.com/) installed and **running**
77
+ 2. **es.exe** (Everything command-line interface):
78
+ - **Everything 1.5 alpha**: es.exe is included
79
+ - **Everything 1.4**: Download from [github.com/voidtools/es](https://github.com/voidtools/es/releases)
80
+ - Place `es.exe` in your PATH or in the Everything installation directory
81
+ 3. **Python 3.10+** or **uv**
82
+
83
+ ### Via uv (recommended — no install needed)
84
+
85
+ ```bash
86
+ uvx everything-mcp
87
+ ```
88
+
89
+ ### Via pip
90
+
91
+ ```bash
92
+ pip install everything-mcp
93
+ ```
94
+
95
+ ### From source
96
+
97
+ ```bash
98
+ git clone https://github.com/elis132/everything-mcp.git
99
+ cd everything-mcp
100
+ pip install -e ".[dev]"
101
+ ```
102
+
103
+ ---
104
+
105
+ ## Configuration
106
+
107
+ <details>
108
+ <summary>Shared MCP JSON Template</summary>
109
+
110
+ Use this server definition anywhere a client asks for MCP JSON:
111
+
112
+ ```json
113
+ {
114
+ "mcpServers": {
115
+ "everything": {
116
+ "command": "uvx",
117
+ "args": ["everything-mcp"]
118
+ }
119
+ }
120
+ }
121
+ ```
122
+ </details>
123
+
124
+ <details>
125
+ <summary>Claude Code</summary>
126
+
127
+ Use the Claude Code CLI:
128
+
129
+ ```bash
130
+ claude mcp add everything -- uvx everything-mcp
131
+ claude mcp list
132
+ ```
133
+
134
+ Or add to `.claude/settings.json`:
135
+
136
+ ```json
137
+ {
138
+ "mcpServers": {
139
+ "everything": {
140
+ "command": "uvx",
141
+ "args": ["everything-mcp"]
142
+ }
143
+ }
144
+ }
145
+ ```
146
+ </details>
147
+
148
+ <details>
149
+ <summary>Claude Desktop</summary>
150
+
151
+ Add to `%APPDATA%\Claude\claude_desktop_config.json`:
152
+
153
+ ```json
154
+ {
155
+ "mcpServers": {
156
+ "everything": {
157
+ "command": "uvx",
158
+ "args": ["everything-mcp"]
159
+ }
160
+ }
161
+ }
162
+ ```
163
+ </details>
164
+
165
+ <details>
166
+ <summary>Codex CLI</summary>
167
+
168
+ Use the Codex CLI:
169
+
170
+ ```bash
171
+ codex mcp add everything -- uvx everything-mcp
172
+ codex mcp list
173
+ ```
174
+ </details>
175
+
176
+ <details>
177
+ <summary>Gemini CLI</summary>
178
+
179
+ Use the Gemini CLI:
180
+
181
+ ```bash
182
+ gemini mcp add -s user everything uvx everything-mcp
183
+ gemini mcp list
184
+ ```
185
+ </details>
186
+
187
+ <details>
188
+ <summary>Kimi CLI</summary>
189
+
190
+ Use the Kimi CLI:
191
+
192
+ ```bash
193
+ kimi mcp add --transport stdio everything -- uvx everything-mcp
194
+ kimi mcp list
195
+ ```
196
+ </details>
197
+
198
+ <details>
199
+ <summary>Qwen CLI</summary>
200
+
201
+ Use the Qwen CLI:
202
+
203
+ ```bash
204
+ qwen mcp add -s user everything uvx everything-mcp
205
+ qwen mcp list
206
+ ```
207
+ </details>
208
+
209
+ <details>
210
+ <summary>Cursor</summary>
211
+
212
+ Cursor currently uses MCP settings/deeplinks rather than a stable `mcp add`
213
+ CLI command. Add the JSON config in Cursor's MCP settings UI.
214
+ </details>
215
+
216
+ <details>
217
+ <summary>Windsurf</summary>
218
+
219
+ Windsurf currently uses MCP settings rather than a stable `mcp add` CLI
220
+ command. On Windows, add the JSON config to:
221
+
222
+ `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
223
+ </details>
224
+
225
+ <details>
226
+ <summary>Generic MCP Clients</summary>
227
+
228
+ Any MCP-compatible client can use this format:
229
+
230
+ ```json
231
+ {
232
+ "mcpServers": {
233
+ "everything": {
234
+ "command": "uvx",
235
+ "args": ["everything-mcp"]
236
+ }
237
+ }
238
+ }
239
+ ```
240
+ </details>
241
+
242
+ <details>
243
+ <summary>Using pip Instead of uvx</summary>
244
+
245
+ ```json
246
+ {
247
+ "mcpServers": {
248
+ "everything": {
249
+ "command": "everything-mcp"
250
+ }
251
+ }
252
+ }
253
+ ```
254
+
255
+ Or with explicit Python:
256
+
257
+ ```json
258
+ {
259
+ "mcpServers": {
260
+ "everything": {
261
+ "command": "python",
262
+ "args": ["-m", "everything_mcp"]
263
+ }
264
+ }
265
+ }
266
+ ```
267
+ </details>
268
+
269
+ ---
270
+
271
+ ## Environment Variables (Optional)
272
+
273
+ Everything MCP auto-detects your setup, but you can override:
274
+
275
+ | Variable | Description | Example |
276
+ |---|---|---|
277
+ | `EVERYTHING_ES_PATH` | Path to es.exe | `C:\Program Files\Everything\es.exe` |
278
+ | `EVERYTHING_INSTANCE` | Everything instance name | `1.5a` |
279
+
280
+ ```json
281
+ {
282
+ "mcpServers": {
283
+ "everything": {
284
+ "command": "uvx",
285
+ "args": ["everything-mcp"],
286
+ "env": {
287
+ "EVERYTHING_INSTANCE": "1.5a"
288
+ }
289
+ }
290
+ }
291
+ }
292
+ ```
293
+
294
+ ---
295
+
296
+ ## Tools
297
+
298
+ ### 1. `everything_search` — The Workhorse
299
+
300
+ Search files and folders using Everything's full query syntax.
301
+
302
+ | Parameter | Default | Description |
303
+ |---|---|---|
304
+ | `query` | *(required)* | Everything search query |
305
+ | `max_results` | 50 | 1–500 |
306
+ | `sort` | `date-modified-desc` | See sort options below |
307
+ | `match_case` | false | Case-sensitive |
308
+ | `match_whole_word` | false | Whole words only |
309
+ | `match_regex` | false | Regex mode |
310
+ | `match_path` | false | Match full path |
311
+ | `offset` | 0 | Pagination offset |
312
+
313
+ **Everything Search Syntax:**
314
+
315
+ ```
316
+ *.py → All Python files
317
+ ext:py;js;ts → Multiple extensions
318
+ ext:py path:C:\Projects → Python files in Projects
319
+ size:>10mb → Larger than 10 MB
320
+ size:1kb..1mb → Between 1 KB and 1 MB
321
+ dm:today → Modified today
322
+ dm:last1week → Modified in the last week
323
+ dc:2024 → Created in 2024
324
+ "exact name.txt" → Exact filename match
325
+ project1 | project2 → OR search
326
+ !node_modules → Exclude term
327
+ ext:py !test !__pycache__ → Python, excluding tests
328
+ content:TODO → Files containing TODO (requires content indexing)
329
+ regex:^test_.*\.py$ → Regex search
330
+ parent:src ext:py → Python files in 'src' folders
331
+ dupe: → Duplicate filenames
332
+ empty: → Empty folders
333
+ ```
334
+
335
+ ### 2. `everything_search_by_type` Category Search
336
+
337
+ Search by pre-defined file type categories.
338
+
339
+ **Categories:** `audio`, `video`, `image`, `document`, `code`, `archive`, `executable`, `font`, `3d`, `data`
340
+
341
+ | Parameter | Default | Description |
342
+ |---|---|---|
343
+ | `file_type` | *(required)* | Category name |
344
+ | `query` | `""` | Additional filter |
345
+ | `path` | `""` | Directory restriction |
346
+ | `max_results` | 50 | 1–500 |
347
+ | `sort` | `date-modified-desc` | Sort order |
348
+
349
+ ### 3. `everything_find_recent` What Changed?
350
+
351
+ Find recently modified files. Sorted newest-first.
352
+
353
+ **Periods:** `1min`, `5min`, `10min`, `15min`, `30min`, `1hour`, `2hours`, `6hours`, `12hours`, `today`, `yesterday`, `1day`, `3days`, `1week`, `2weeks`, `1month`, `3months`, `6months`, `1year`
354
+
355
+ | Parameter | Default | Description |
356
+ |---|---|---|
357
+ | `period` | `1hour` | Time period |
358
+ | `path` | `""` | Directory restriction |
359
+ | `extensions` | `""` | Extension filter (e.g. `py,js,ts`) |
360
+ | `query` | `""` | Additional filter |
361
+ | `max_results` | 50 | 1–500 |
362
+
363
+ ### 4. `everything_file_details` — Deep Inspection
364
+
365
+ Get metadata and optional content preview for specific files.
366
+
367
+ | Parameter | Default | Description |
368
+ |---|---|---|
369
+ | `paths` | *(required)* | File paths to inspect (1–20) |
370
+ | `preview_lines` | 0 | Lines of text to preview (0–200) |
371
+
372
+ **Returns:** Full metadata (size, dates, permissions, hidden status). Directories: item count and listing. Text files with preview: first N lines of content.
373
+
374
+ ### 5. `everything_count_stats` — Quick Analytics
375
+
376
+ Get count and size statistics without listing individual files.
377
+
378
+ | Parameter | Default | Description |
379
+ |---|---|---|
380
+ | `query` | *(required)* | Search query |
381
+ | `include_size` | true | Calculate total size |
382
+ | `breakdown_by_extension` | false | Sampled per-extension stats (files only) |
383
+
384
+ ---
385
+
386
+ ## Examples
387
+
388
+ > "Find all Python files modified today in my project"
389
+
390
+ → `everything_find_recent(period="today", extensions="py", path="C:\Projects\myapp")`
391
+
392
+ > "How much disk space do my log files use?"
393
+
394
+ → `everything_count_stats(query="ext:log", include_size=true, breakdown_by_extension=true)`
395
+
396
+ > "Show me the first 50 lines of that config file"
397
+
398
+ `everything_file_details(paths=["C:\Projects\app\config.yaml"], preview_lines=50)`
399
+
400
+ > "Find all duplicate filenames in Documents"
401
+
402
+ → `everything_search(query='dupe: path:"C:\Users\me\Documents"')`
403
+
404
+ > "Find all images larger than 5MB"
405
+
406
+ → `everything_search(query="ext:jpg;png;gif size:>5mb")`
407
+
408
+ ---
409
+
410
+ ## Troubleshooting
411
+
412
+ ### "es.exe not found"
413
+
414
+ 1. Ensure Everything is installed: https://www.voidtools.com/
415
+ 2. Download es.exe: https://github.com/voidtools/es/releases
416
+ 3. Place es.exe in your PATH or set `EVERYTHING_ES_PATH`
417
+
418
+ ### "Everything IPC window not found"
419
+
420
+ 1. Ensure Everything is **running** (check system tray)
421
+ 2. If using Everything 1.5 alpha, set `EVERYTHING_INSTANCE=1.5a`
422
+ 3. Ensure you're not running Everything Lite (no IPC support)
423
+
424
+ ### "No results for valid queries"
425
+
426
+ 1. Verify Everything's index is built (needs time on first run)
427
+ 2. Try the same query in Everything's GUI
428
+ 3. Check that the drive/path is included in Everything's index settings
429
+
430
+ ### Debugging
431
+
432
+ ```bash
433
+ # View server logs
434
+ everything-mcp 2>everything-mcp.log
435
+
436
+ # MCP Inspector
437
+ npx @modelcontextprotocol/inspector uvx everything-mcp
438
+ ```
439
+
440
+ ---
441
+
442
+ ## Architecture
443
+
444
+ ```
445
+ ┌──────────────┐ MCP (stdio) ┌──────────────────┐
446
+ AI Agent │◄────────────────────►│ Everything MCP
447
+ (Claude, │ Server │
448
+ │ Codex, etc) │ │ │
449
+ └──────────────┘ │ 5 Tools: │
450
+ │ • search │
451
+ │ • search_by_type│
452
+ │ • find_recent │
453
+ │ • file_details │
454
+ │ • count_stats │
455
+ └────────┬─────────┘
456
+ async subprocess
457
+
458
+ ┌──────────────────┐
459
+ │ es.exe │
460
+ │ (CLI interface) │
461
+ └────────┬─────────┘
462
+ IPC / Named Pipes
463
+
464
+ ┌──────────────────┐
465
+ │ Everything │
466
+ │ Service │
467
+ │ (voidtools) │
468
+ │ │
469
+ │ Real-time NTFS │
470
+ │ file index │
471
+ └──────────────────┘
472
+ ```
473
+
474
+ ---
475
+
476
+ ## Development
477
+
478
+ ```bash
479
+ # Install with dev dependencies
480
+ pip install -e ".[dev]"
481
+
482
+ # Run tests
483
+ pytest
484
+
485
+ # Lint
486
+ ruff check src/ tests/
487
+ ```
488
+
489
+ ## Contributing
490
+
491
+ Contributions welcome! Areas for improvement:
492
+
493
+ - Direct named pipe IPC (bypass es.exe for lower latency)
494
+ - Everything SDK3 integration for Everything 1.5
495
+ - Content search integration
496
+ - File watching / change notifications
497
+ - Bookmark and tag support (Everything 1.5)
498
+
499
+ ## License
500
+
501
+ MIT — see [LICENSE](LICENSE)
502
+
503
+ ## Acknowledgments
504
+
505
+ - [voidtools](https://www.voidtools.com/) for the incredible Everything search engine
506
+ - [Anthropic](https://anthropic.com/) for the Model Context Protocol specification
507
+ - The MCP community for driving adoption across AI tools
@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "everything-mcp"
7
- version = "1.0.0"
7
+ version = "1.0.2"
8
8
  description = "The definitive MCP server for voidtools Everything — lightning-fast file search for AI agents"
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
11
11
  requires-python = ">=3.10"
12
12
  authors = [
13
- { name = "Elis", email = "elis@egf.se" },
13
+ { name = "elis132" },
14
14
  ]
15
15
  keywords = [
16
16
  "mcp", "everything", "voidtools", "file-search", "claude",
@@ -4,7 +4,7 @@ Everything MCP — The definitive MCP server for voidtools Everything.
4
4
  Lightning-fast file search for AI agents.
5
5
  """
6
6
 
7
- __version__ = "1.0.0"
7
+ __version__ = "1.0.2"
8
8
 
9
9
 
10
10
  def main() -> None:
@@ -199,7 +199,8 @@ class EverythingBackend:
199
199
  async def count(self, query: str) -> int:
200
200
  """Return the number of results for *query* without listing them."""
201
201
  cmd = self._base_cmd()
202
- cmd.extend(["-n", "0", "-get-result-count", query])
202
+ # Important: do not combine with "-n 0" because es.exe then reports 0.
203
+ cmd.extend(["-get-result-count", query])
203
204
  stdout, stderr, rc = await self._run(cmd)
204
205
 
205
206
  if rc != 0:
@@ -213,7 +214,8 @@ class EverythingBackend:
213
214
  async def get_total_size(self, query: str) -> int:
214
215
  """Return the total size in bytes of all files matching *query*."""
215
216
  cmd = self._base_cmd()
216
- cmd.extend(["-n", "0", "-get-total-size", query])
217
+ # Important: do not combine with "-n 0" because es.exe then reports 0.
218
+ cmd.extend(["-get-total-size", query])
217
219
  stdout, stderr, rc = await self._run(cmd)
218
220
 
219
221
  if rc != 0: