everything-mcp 1.0.0__tar.gz → 1.0.1__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.
Files changed (12) hide show
  1. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/CHANGELOG.md +27 -19
  2. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/PKG-INFO +13 -10
  3. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/README.md +465 -462
  4. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/pyproject.toml +1 -1
  5. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/__init__.py +1 -1
  6. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/backend.py +4 -2
  7. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/.gitignore +0 -0
  8. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/LICENSE +0 -0
  9. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/__main__.py +0 -0
  10. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/config.py +0 -0
  11. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/py.typed +0 -0
  12. {everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/server.py +0 -0
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/CHANGELOG.md RENAMED
@@ -1,19 +1,27 @@
1
- # Changelog
2
-
3
- All notable changes to **everything-mcp** will be documented in this file.
4
-
5
- ## [1.0.0] — 2026-02-04
6
-
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
1
+ # Changelog
2
+
3
+ All notable changes to **everything-mcp** will be documented in this file.
4
+
5
+ ## [1.0.1] ? 2026-02-04
6
+
7
+ ### Fixed
8
+
9
+ - Fixed `everything_count_stats` reporting `0` for `total_count` and `total_size` on some systems.
10
+ - Updated backend aggregate queries to avoid incompatible `es.exe` flag combinations (`-n 0` with `-get-result-count` / `-get-total-size`).
11
+ - Added backend tests to verify aggregate command construction.
12
+
13
+ ## [1.0.0] — 2026-02-04
14
+
15
+ ### Added
16
+
17
+ - **5 AI-optimised tools**: `everything_search`, `everything_search_by_type`, `everything_find_recent`, `everything_file_details`, `everything_count_stats`
18
+ - **Zero-config auto-detection**: finds es.exe via PATH, common install locations, and Windows Registry
19
+ - **Everything 1.5 alpha** auto-detection (default → 1.5a instance probing)
20
+ - **Content preview**: read first N lines of source code and text files
21
+ - **10 file type categories**: audio, video, image, document, code, archive, executable, font, 3d, data
22
+ - **14 sort options**, **19 time period presets**
23
+ - **Extension breakdown analytics** in count_stats tool
24
+ - Comprehensive test suite with pytest
25
+ - PEP 561 `py.typed` marker
26
+ - Full documentation with configuration examples for Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini, Kimi, Qwen
27
+ - `everything://status` MCP resource for health checks
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: everything-mcp
3
- Version: 1.0.0
3
+ Version: 1.0.1
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
@@ -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
 
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/README.md RENAMED
@@ -1,462 +1,465 @@
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 | ❌ |
24
- | **Test suite** | ✅ pytest | ❌ | ❌ |
25
- | **Zero config** | ✅ Works out of the box | ❌ Need SDK DLL path | ❌ Need es.exe in PATH |
26
-
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
48
- ```
49
-
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
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 | ❌ |
27
+ | **Test suite** | ✅ pytest | ❌ | ❌ |
28
+ | **Zero config** | ✅ Works out of the box | ❌ Need SDK DLL path | ❌ Need es.exe in PATH |
29
+
30
+ ## Installation
31
+
32
+ ### Prerequisites
33
+
34
+ 1. **Windows** with [Everything](https://www.voidtools.com/) installed and **running**
35
+ 2. **es.exe** (Everything command-line interface):
36
+ - **Everything 1.5 alpha**: es.exe is included
37
+ - **Everything 1.4**: Download from [github.com/voidtools/es](https://github.com/voidtools/es/releases)
38
+ - Place `es.exe` in your PATH or in the Everything installation directory
39
+ 3. **Python 3.10+** or **uv**
40
+
41
+ ### Via uv (recommended — no install needed)
42
+
43
+ ```bash
44
+ uvx everything-mcp
45
+ ```
46
+
47
+ ### Via pip
48
+
49
+ ```bash
50
+ pip install everything-mcp
51
+ ```
52
+
53
+ ### From source
54
+
55
+ ```bash
56
+ git clone https://github.com/elis132/everything-mcp.git
57
+ cd everything-mcp
58
+ pip install -e ".[dev]"
59
+ ```
60
+
61
+ ---
62
+
63
+ ## Configuration
64
+
65
+ <details>
66
+ <summary>Shared MCP JSON Template</summary>
67
+
68
+ Use this server definition anywhere a client asks for MCP JSON:
69
+
70
+ ```json
71
+ {
72
+ "mcpServers": {
73
+ "everything": {
74
+ "command": "uvx",
75
+ "args": ["everything-mcp"]
76
+ }
77
+ }
78
+ }
79
+ ```
80
+ </details>
81
+
82
+ <details>
83
+ <summary>Claude Code</summary>
84
+
85
+ Use the Claude Code CLI:
86
+
87
+ ```bash
88
+ claude mcp add everything -- uvx everything-mcp
89
+ claude mcp list
90
+ ```
91
+
92
+ Or add to `.claude/settings.json`:
93
+
94
+ ```json
95
+ {
96
+ "mcpServers": {
97
+ "everything": {
98
+ "command": "uvx",
99
+ "args": ["everything-mcp"]
100
+ }
101
+ }
102
+ }
103
+ ```
104
+ </details>
105
+
106
+ <details>
107
+ <summary>Claude Desktop</summary>
108
+
109
+ Add to `%APPDATA%\Claude\claude_desktop_config.json`:
110
+
111
+ ```json
112
+ {
113
+ "mcpServers": {
114
+ "everything": {
115
+ "command": "uvx",
116
+ "args": ["everything-mcp"]
117
+ }
118
+ }
119
+ }
120
+ ```
121
+ </details>
122
+
123
+ <details>
124
+ <summary>Codex CLI</summary>
125
+
126
+ Use the Codex CLI:
127
+
128
+ ```bash
129
+ codex mcp add everything -- uvx everything-mcp
130
+ codex mcp list
131
+ ```
132
+ </details>
133
+
134
+ <details>
135
+ <summary>Gemini CLI</summary>
136
+
137
+ Use the Gemini CLI:
138
+
139
+ ```bash
140
+ gemini mcp add -s user everything uvx everything-mcp
141
+ gemini mcp list
142
+ ```
143
+ </details>
144
+
145
+ <details>
146
+ <summary>Kimi CLI</summary>
147
+
148
+ Use the Kimi CLI:
149
+
150
+ ```bash
151
+ kimi mcp add --transport stdio everything -- uvx everything-mcp
152
+ kimi mcp list
153
+ ```
154
+ </details>
155
+
156
+ <details>
157
+ <summary>Qwen CLI</summary>
158
+
159
+ Use the Qwen CLI:
160
+
161
+ ```bash
162
+ qwen mcp add -s user everything uvx everything-mcp
163
+ qwen mcp list
164
+ ```
165
+ </details>
166
+
167
+ <details>
168
+ <summary>Cursor</summary>
169
+
170
+ Cursor currently uses MCP settings/deeplinks rather than a stable `mcp add`
171
+ CLI command. Add the JSON config in Cursor's MCP settings UI.
172
+ </details>
173
+
174
+ <details>
175
+ <summary>Windsurf</summary>
176
+
177
+ Windsurf currently uses MCP settings rather than a stable `mcp add` CLI
178
+ command. On Windows, add the JSON config to:
179
+
180
+ `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
181
+ </details>
182
+
183
+ <details>
184
+ <summary>Generic MCP Clients</summary>
185
+
186
+ Any MCP-compatible client can use this format:
187
+
188
+ ```json
189
+ {
190
+ "mcpServers": {
191
+ "everything": {
192
+ "command": "uvx",
193
+ "args": ["everything-mcp"]
194
+ }
195
+ }
196
+ }
197
+ ```
198
+ </details>
199
+
200
+ <details>
201
+ <summary>Using pip Instead of uvx</summary>
202
+
203
+ ```json
204
+ {
205
+ "mcpServers": {
206
+ "everything": {
207
+ "command": "everything-mcp"
208
+ }
209
+ }
210
+ }
211
+ ```
212
+
213
+ Or with explicit Python:
214
+
215
+ ```json
216
+ {
217
+ "mcpServers": {
218
+ "everything": {
219
+ "command": "python",
220
+ "args": ["-m", "everything_mcp"]
221
+ }
222
+ }
223
+ }
224
+ ```
225
+ </details>
226
+
227
+ ---
228
+
229
+ ## Environment Variables (Optional)
230
+
231
+ Everything MCP auto-detects your setup, but you can override:
232
+
233
+ | Variable | Description | Example |
234
+ |---|---|---|
235
+ | `EVERYTHING_ES_PATH` | Path to es.exe | `C:\Program Files\Everything\es.exe` |
236
+ | `EVERYTHING_INSTANCE` | Everything instance name | `1.5a` |
237
+
238
+ ```json
239
+ {
240
+ "mcpServers": {
241
+ "everything": {
242
+ "command": "uvx",
243
+ "args": ["everything-mcp"],
244
+ "env": {
245
+ "EVERYTHING_INSTANCE": "1.5a"
246
+ }
247
+ }
248
+ }
249
+ }
250
+ ```
251
+
252
+ ---
253
+
254
+ ## Tools
255
+
256
+ ### 1. `everything_search` — The Workhorse
257
+
258
+ Search files and folders using Everything's full query syntax.
259
+
260
+ | Parameter | Default | Description |
261
+ |---|---|---|
262
+ | `query` | *(required)* | Everything search query |
263
+ | `max_results` | 50 | 1–500 |
264
+ | `sort` | `date-modified-desc` | See sort options below |
265
+ | `match_case` | false | Case-sensitive |
266
+ | `match_whole_word` | false | Whole words only |
267
+ | `match_regex` | false | Regex mode |
268
+ | `match_path` | false | Match full path |
269
+ | `offset` | 0 | Pagination offset |
270
+
271
+ **Everything Search Syntax:**
272
+
273
+ ```
274
+ *.py → All Python files
275
+ ext:py;js;ts → Multiple extensions
276
+ ext:py path:C:\Projects → Python files in Projects
277
+ size:>10mb → Larger than 10 MB
278
+ size:1kb..1mb → Between 1 KB and 1 MB
279
+ dm:today → Modified today
280
+ dm:last1week → Modified in the last week
281
+ dc:2024 → Created in 2024
282
+ "exact name.txt" → Exact filename match
283
+ project1 | project2 → OR search
284
+ !node_modules → Exclude term
285
+ ext:py !test !__pycache__ → Python, excluding tests
286
+ content:TODO → Files containing TODO (requires content indexing)
287
+ regex:^test_.*\.py$ → Regex search
288
+ parent:src ext:py → Python files in 'src' folders
289
+ dupe: → Duplicate filenames
290
+ empty: → Empty folders
291
+ ```
292
+
293
+ ### 2. `everything_search_by_type` — Category Search
294
+
295
+ Search by pre-defined file type categories.
296
+
297
+ **Categories:** `audio`, `video`, `image`, `document`, `code`, `archive`, `executable`, `font`, `3d`, `data`
298
+
299
+ | Parameter | Default | Description |
300
+ |---|---|---|
301
+ | `file_type` | *(required)* | Category name |
302
+ | `query` | `""` | Additional filter |
303
+ | `path` | `""` | Directory restriction |
304
+ | `max_results` | 50 | 1–500 |
305
+ | `sort` | `date-modified-desc` | Sort order |
306
+
307
+ ### 3. `everything_find_recent` — What Changed?
308
+
309
+ Find recently modified files. Sorted newest-first.
310
+
311
+ **Periods:** `1min`, `5min`, `10min`, `15min`, `30min`, `1hour`, `2hours`, `6hours`, `12hours`, `today`, `yesterday`, `1day`, `3days`, `1week`, `2weeks`, `1month`, `3months`, `6months`, `1year`
312
+
313
+ | Parameter | Default | Description |
314
+ |---|---|---|
315
+ | `period` | `1hour` | Time period |
316
+ | `path` | `""` | Directory restriction |
317
+ | `extensions` | `""` | Extension filter (e.g. `py,js,ts`) |
318
+ | `query` | `""` | Additional filter |
319
+ | `max_results` | 50 | 1–500 |
320
+
321
+ ### 4. `everything_file_details` — Deep Inspection
322
+
323
+ Get metadata and optional content preview for specific files.
324
+
325
+ | Parameter | Default | Description |
326
+ |---|---|---|
327
+ | `paths` | *(required)* | File paths to inspect (1–20) |
328
+ | `preview_lines` | 0 | Lines of text to preview (0–200) |
329
+
330
+ **Returns:** Full metadata (size, dates, permissions, hidden status). Directories: item count and listing. Text files with preview: first N lines of content.
331
+
332
+ ### 5. `everything_count_stats` — Quick Analytics
333
+
334
+ Get count and size statistics without listing individual files.
335
+
336
+ | Parameter | Default | Description |
337
+ |---|---|---|
338
+ | `query` | *(required)* | Search query |
339
+ | `include_size` | true | Calculate total size |
340
+ | `breakdown_by_extension` | false | Sampled per-extension stats (files only) |
341
+
342
+ ---
343
+
344
+ ## Examples
345
+
346
+ > "Find all Python files modified today in my project"
347
+
348
+ → `everything_find_recent(period="today", extensions="py", path="C:\Projects\myapp")`
349
+
350
+ > "How much disk space do my log files use?"
351
+
352
+ → `everything_count_stats(query="ext:log", include_size=true, breakdown_by_extension=true)`
353
+
354
+ > "Show me the first 50 lines of that config file"
355
+
356
+ → `everything_file_details(paths=["C:\Projects\app\config.yaml"], preview_lines=50)`
357
+
358
+ > "Find all duplicate filenames in Documents"
359
+
360
+ → `everything_search(query='dupe: path:"C:\Users\me\Documents"')`
361
+
362
+ > "Find all images larger than 5MB"
363
+
364
+ → `everything_search(query="ext:jpg;png;gif size:>5mb")`
365
+
366
+ ---
367
+
368
+ ## Troubleshooting
369
+
370
+ ### "es.exe not found"
371
+
372
+ 1. Ensure Everything is installed: https://www.voidtools.com/
373
+ 2. Download es.exe: https://github.com/voidtools/es/releases
374
+ 3. Place es.exe in your PATH or set `EVERYTHING_ES_PATH`
375
+
376
+ ### "Everything IPC window not found"
377
+
378
+ 1. Ensure Everything is **running** (check system tray)
379
+ 2. If using Everything 1.5 alpha, set `EVERYTHING_INSTANCE=1.5a`
380
+ 3. Ensure you're not running Everything Lite (no IPC support)
381
+
382
+ ### "No results for valid queries"
383
+
384
+ 1. Verify Everything's index is built (needs time on first run)
385
+ 2. Try the same query in Everything's GUI
386
+ 3. Check that the drive/path is included in Everything's index settings
387
+
388
+ ### Debugging
389
+
390
+ ```bash
391
+ # View server logs
392
+ everything-mcp 2>everything-mcp.log
393
+
394
+ # MCP Inspector
395
+ npx @modelcontextprotocol/inspector uvx everything-mcp
396
+ ```
397
+
398
+ ---
399
+
400
+ ## Architecture
401
+
402
+ ```
403
+ ┌──────────────┐ MCP (stdio) ┌──────────────────┐
404
+ │ AI Agent │◄────────────────────►│ Everything MCP │
405
+ │ (Claude, │ │ Server │
406
+ │ Codex, etc) │ │ │
407
+ └──────────────┘ │ 5 Tools: │
408
+ │ • search │
409
+ │ • search_by_type│
410
+ │ • find_recent │
411
+ │ • file_details │
412
+ │ • count_stats │
413
+ └────────┬─────────┘
414
+ │ async subprocess
415
+ ▼
416
+ ┌──────────────────┐
417
+ │ es.exe │
418
+ │ (CLI interface) │
419
+ └────────┬─────────┘
420
+ │ IPC / Named Pipes
421
+ ▼
422
+ ┌──────────────────┐
423
+ │ Everything │
424
+ │ Service │
425
+ │ (voidtools) │
426
+ │ │
427
+ │ Real-time NTFS │
428
+ │ file index │
429
+ └──────────────────┘
430
+ ```
431
+
432
+ ---
433
+
434
+ ## Development
435
+
436
+ ```bash
437
+ # Install with dev dependencies
438
+ pip install -e ".[dev]"
439
+
440
+ # Run tests
441
+ pytest
442
+
443
+ # Lint
444
+ ruff check src/ tests/
445
+ ```
446
+
447
+ ## Contributing
448
+
449
+ Contributions welcome! Areas for improvement:
450
+
451
+ - Direct named pipe IPC (bypass es.exe for lower latency)
452
+ - Everything SDK3 integration for Everything 1.5
453
+ - Content search integration
454
+ - File watching / change notifications
455
+ - Bookmark and tag support (Everything 1.5)
456
+
457
+ ## License
458
+
459
+ MIT — see [LICENSE](LICENSE)
460
+
461
+ ## Acknowledgments
462
+
463
+ - [voidtools](https://www.voidtools.com/) for the incredible Everything search engine
464
+ - [Anthropic](https://anthropic.com/) for the Model Context Protocol specification
465
+ - The MCP community for driving adoption across AI tools
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "everything-mcp"
7
- version = "1.0.0"
7
+ version = "1.0.1"
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" }
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/__init__.py RENAMED
@@ -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.1"
8
8
 
9
9
 
10
10
  def main() -> None:
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/src/everything_mcp/backend.py RENAMED
@@ -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:
{everything_mcp-1.0.0 → everything_mcp-1.0.1}/LICENSE RENAMED
File without changes