everything-mcp 1.0.0__tar.gz

everything_mcp-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

everything_mcp-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to **everything-mcp** will be documented in this file.
+
+## [1.0.0] — 2026-02-04
+
+### Added
+
+- **5 AI-optimised tools**: `everything_search`, `everything_search_by_type`, `everything_find_recent`, `everything_file_details`, `everything_count_stats`
+- **Zero-config auto-detection**: finds es.exe via PATH, common install locations, and Windows Registry
+- **Everything 1.5 alpha** auto-detection (default → 1.5a instance probing)
+- **Content preview**: read first N lines of source code and text files
+- **10 file type categories**: audio, video, image, document, code, archive, executable, font, 3d, data
+- **14 sort options**, **19 time period presets**
+- **Extension breakdown analytics** in count_stats tool
+- Comprehensive test suite with pytest
+- PEP 561 `py.typed` marker
+- Full documentation with configuration examples for Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini, Kimi, Qwen
+- `everything://status` MCP resource for health checks

everything_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everything_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,495 @@
+Metadata-Version: 2.4
+Name: everything-mcp
+Version: 1.0.0
+Summary: The definitive MCP server for voidtools Everything — lightning-fast file search for AI agents
+Project-URL: Homepage, https://github.com/elis132/everything-mcp
+Project-URL: Repository, https://github.com/elis132/everything-mcp
+Project-URL: Issues, https://github.com/elis132/everything-mcp/issues
+Project-URL: Changelog, https://github.com/elis132/everything-mcp/blob/main/CHANGELOG.md
+Author-email: Elis <elis@egf.se>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude,codex,everything,file-search,gemini,mcp,model-context-protocol,voidtools
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ⚡ Everything MCP
+
+**The definitive MCP server for [voidtools Everything](https://www.voidtools.com/)** — lightning-fast file search for AI agents.
+
+[![PyPI](https://img.shields.io/pypi/v/everything-mcp)](https://pypi.org/project/everything-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/everything-mcp)](https://pypi.org/project/everything-mcp/)
+[![License](https://img.shields.io/github/license/elis132/everything-mcp)](LICENSE)
+
+Search millions of files in milliseconds. Built for **Claude Code**, **Codex**, **Gemini**, **Kimi**, **Qwen**, **Cursor**, **Windsurf**, and any MCP-compatible client.
+
+---
+
+## Why This One?
+
+| Feature | everything-mcp (this) | mamertofabian (271⭐) | essovius (0⭐) |
+|---|---|---|---|
+| **Tools** | 5 well-designed | 1 generic | 16 granular |
+| **Auto-detection** | ✅ Finds Everything + es.exe automatically | ❌ Manual DLL path | ❌ Manual setup |
+| **Everything 1.5** | ✅ Auto-detects instance | ❌ No support | ⚠️ Manual flag |
+| **Content preview** | ✅ Read first N lines | ❌ | ❌ |
+| **File type categories** | ✅ 10 categories | ❌ | ✅ |
+| **Stats & counts** | ✅ Size stats, extension breakdown | ❌ | Partial |
+| **Error handling** | ✅ All tools return clean errors | ❌ Raw exceptions | ❌ |
+| **Test suite** | ✅ pytest | ❌ | ❌ |
+| **Zero config** | ✅ Works out of the box | ❌ Need SDK DLL path | ❌ Need es.exe in PATH |
+
+## Installation
+
+### Prerequisites
+
+1. **Windows** with [Everything](https://www.voidtools.com/) installed and **running**
+2. **es.exe** (Everything command-line interface):
+   - **Everything 1.5 alpha**: es.exe is included
+   - **Everything 1.4**: Download from [github.com/voidtools/es](https://github.com/voidtools/es/releases)
+   - Place `es.exe` in your PATH or in the Everything installation directory
+3. **Python 3.10+** or **uv**
+
+### Via uv (recommended — no install needed)
+
+```bash
+uvx everything-mcp
+```
+
+### Via pip
+
+```bash
+pip install everything-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/elis132/everything-mcp.git
+cd everything-mcp
+pip install -e ".[dev]"
+```
+
+---
+
+## Configuration
+
+<details>
+<summary>Shared MCP JSON Template</summary>
+
+Use this server definition anywhere a client asks for MCP JSON:
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "uvx",
+      "args": ["everything-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+Use the Claude Code CLI:
+
+```bash
+claude mcp add everything -- uvx everything-mcp
+claude mcp list
+```
+
+Or add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "uvx",
+      "args": ["everything-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "uvx",
+      "args": ["everything-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Codex CLI</summary>
+
+Use the Codex CLI:
+
+```bash
+codex mcp add everything -- uvx everything-mcp
+codex mcp list
+```
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Use the Gemini CLI:
+
+```bash
+gemini mcp add -s user everything uvx everything-mcp
+gemini mcp list
+```
+</details>
+
+<details>
+<summary>Kimi CLI</summary>
+
+Use the Kimi CLI:
+
+```bash
+kimi mcp add --transport stdio everything -- uvx everything-mcp
+kimi mcp list
+```
+</details>
+
+<details>
+<summary>Qwen CLI</summary>
+
+Use the Qwen CLI:
+
+```bash
+qwen mcp add -s user everything uvx everything-mcp
+qwen mcp list
+```
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Cursor currently uses MCP settings/deeplinks rather than a stable `mcp add`
+CLI command. Add the JSON config in Cursor's MCP settings UI.
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Windsurf currently uses MCP settings rather than a stable `mcp add` CLI
+command. On Windows, add the JSON config to:
+
+`%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+</details>
+
+<details>
+<summary>Generic MCP Clients</summary>
+
+Any MCP-compatible client can use this format:
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "uvx",
+      "args": ["everything-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Using pip Instead of uvx</summary>
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "everything-mcp"
+    }
+  }
+}
+```
+
+Or with explicit Python:
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "python",
+      "args": ["-m", "everything_mcp"]
+    }
+  }
+}
+```
+</details>
+
+---
+
+## Environment Variables (Optional)
+
+Everything MCP auto-detects your setup, but you can override:
+
+| Variable | Description | Example |
+|---|---|---|
+| `EVERYTHING_ES_PATH` | Path to es.exe | `C:\Program Files\Everything\es.exe` |
+| `EVERYTHING_INSTANCE` | Everything instance name | `1.5a` |
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "uvx",
+      "args": ["everything-mcp"],
+      "env": {
+        "EVERYTHING_INSTANCE": "1.5a"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tools
+
+### 1. `everything_search` — The Workhorse
+
+Search files and folders using Everything's full query syntax.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `query` | *(required)* | Everything search query |
+| `max_results` | 50 | 1–500 |
+| `sort` | `date-modified-desc` | See sort options below |
+| `match_case` | false | Case-sensitive |
+| `match_whole_word` | false | Whole words only |
+| `match_regex` | false | Regex mode |
+| `match_path` | false | Match full path |
+| `offset` | 0 | Pagination offset |
+
+**Everything Search Syntax:**
+
+```
+*.py                          → All Python files
+ext:py;js;ts                  → Multiple extensions
+ext:py path:C:\Projects       → Python files in Projects
+size:>10mb                    → Larger than 10 MB
+size:1kb..1mb                 → Between 1 KB and 1 MB
+dm:today                      → Modified today
+dm:last1week                  → Modified in the last week
+dc:2024                       → Created in 2024
+"exact name.txt"              → Exact filename match
+project1 | project2           → OR search
+!node_modules                 → Exclude term
+ext:py !test !__pycache__     → Python, excluding tests
+content:TODO                  → Files containing TODO (requires content indexing)
+regex:^test_.*\.py$           → Regex search
+parent:src ext:py             → Python files in 'src' folders
+dupe:                         → Duplicate filenames
+empty:                        → Empty folders
+```
+
+### 2. `everything_search_by_type` — Category Search
+
+Search by pre-defined file type categories.
+
+**Categories:** `audio`, `video`, `image`, `document`, `code`, `archive`, `executable`, `font`, `3d`, `data`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `file_type` | *(required)* | Category name |
+| `query` | `""` | Additional filter |
+| `path` | `""` | Directory restriction |
+| `max_results` | 50 | 1–500 |
+| `sort` | `date-modified-desc` | Sort order |
+
+### 3. `everything_find_recent` — What Changed?
+
+Find recently modified files. Sorted newest-first.
+
+**Periods:** `1min`, `5min`, `10min`, `15min`, `30min`, `1hour`, `2hours`, `6hours`, `12hours`, `today`, `yesterday`, `1day`, `3days`, `1week`, `2weeks`, `1month`, `3months`, `6months`, `1year`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `period` | `1hour` | Time period |
+| `path` | `""` | Directory restriction |
+| `extensions` | `""` | Extension filter (e.g. `py,js,ts`) |
+| `query` | `""` | Additional filter |
+| `max_results` | 50 | 1–500 |
+
+### 4. `everything_file_details` — Deep Inspection
+
+Get metadata and optional content preview for specific files.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `paths` | *(required)* | File paths to inspect (1–20) |
+| `preview_lines` | 0 | Lines of text to preview (0–200) |
+
+**Returns:** Full metadata (size, dates, permissions, hidden status). Directories: item count and listing. Text files with preview: first N lines of content.
+
+### 5. `everything_count_stats` — Quick Analytics
+
+Get count and size statistics without listing individual files.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `query` | *(required)* | Search query |
+| `include_size` | true | Calculate total size |
+| `breakdown_by_extension` | false | Sampled per-extension stats (files only) |
+
+---
+
+## Examples
+
+> "Find all Python files modified today in my project"
+
+→ `everything_find_recent(period="today", extensions="py", path="C:\Projects\myapp")`
+
+> "How much disk space do my log files use?"
+
+→ `everything_count_stats(query="ext:log", include_size=true, breakdown_by_extension=true)`
+
+> "Show me the first 50 lines of that config file"
+
+→ `everything_file_details(paths=["C:\Projects\app\config.yaml"], preview_lines=50)`
+
+> "Find all duplicate filenames in Documents"
+
+→ `everything_search(query='dupe: path:"C:\Users\me\Documents"')`
+
+> "Find all images larger than 5MB"
+
+→ `everything_search(query="ext:jpg;png;gif size:>5mb")`
+
+---
+
+## Troubleshooting
+
+### "es.exe not found"
+
+1. Ensure Everything is installed: https://www.voidtools.com/
+2. Download es.exe: https://github.com/voidtools/es/releases
+3. Place es.exe in your PATH or set `EVERYTHING_ES_PATH`
+
+### "Everything IPC window not found"
+
+1. Ensure Everything is **running** (check system tray)
+2. If using Everything 1.5 alpha, set `EVERYTHING_INSTANCE=1.5a`
+3. Ensure you're not running Everything Lite (no IPC support)
+
+### "No results for valid queries"
+
+1. Verify Everything's index is built (needs time on first run)
+2. Try the same query in Everything's GUI
+3. Check that the drive/path is included in Everything's index settings
+
+### Debugging
+
+```bash
+# View server logs
+everything-mcp 2>everything-mcp.log
+
+# MCP Inspector
+npx @modelcontextprotocol/inspector uvx everything-mcp
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────┐     MCP (stdio)     ┌──────────────────┐
+│  AI Agent    │◄────────────────────►│  Everything MCP  │
+│ (Claude,     │                      │  Server          │
+│  Codex, etc) │                      │                  │
+└──────────────┘                      │  5 Tools:        │
+                                      │  • search        │
+                                      │  • search_by_type│
+                                      │  • find_recent   │
+                                      │  • file_details  │
+                                      │  • count_stats   │
+                                      └────────┬─────────┘
+                                               │ async subprocess
+                                               ▼
+                                      ┌──────────────────┐
+                                      │     es.exe       │
+                                      │  (CLI interface)  │
+                                      └────────┬─────────┘
+                                               │ IPC / Named Pipes
+                                               ▼
+                                      ┌──────────────────┐
+                                      │   Everything     │
+                                      │   Service        │
+                                      │  (voidtools)     │
+                                      │                  │
+                                      │  Real-time NTFS  │
+                                      │  file index      │
+                                      └──────────────────┘
+```
+
+---
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src/ tests/
+```
+
+## Contributing
+
+Contributions welcome! Areas for improvement:
+
+- Direct named pipe IPC (bypass es.exe for lower latency)
+- Everything SDK3 integration for Everything 1.5
+- Content search integration
+- File watching / change notifications
+- Bookmark and tag support (Everything 1.5)
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Acknowledgments
+
+- [voidtools](https://www.voidtools.com/) for the incredible Everything search engine
+- [Anthropic](https://anthropic.com/) for the Model Context Protocol specification
+- The MCP community for driving adoption across AI tools