dsh_everything

English | 简体中文

Millisecond file search for AI agents on Windows. dsh_everything exposes the local voidtools Everything index as an MCP stdio server, so an agent can find, filter and aggregate files across millions of index entries instead of recursively scanning disks.

13 tools (7 query tools + 6 composite tools) · 3 MCP resources · no es.exe, no Everything SDK, no third-party Python dependencies beyond the official mcp SDK · loopback-only, read-only by default.

Current version: 2.0.0 — see CHANGELOG.md.

• Usage cookbook — task-oriented recipes with exact tool calls

• Capability matrix — every supported / unsupported Everything query, verified on 1.4.1.1024

• Examples — DSH profile patch, generic MCP config, custom presets

• Benchmarks — reproducible native-vs-index harness, charts and full results

Table of contents

1. Why this exists

2. Benchmarks

3. Features

4. Requirements

5. Install

6. Quick start

7. Tool reference

8. Everything query syntax cheat sheet

9. Recipes

10. Architecture

11. Security and privacy

12. Limitations

13. Troubleshooting

14. Development and tests

15. License and acknowledgements

• Changelog

Related MCP server: everything-mcp-server

1. Why this exists

An agent that needs a file usually has two bad options:

• Recursive scan. Get-ChildItem -Recurse, os.walk, find — every call touches every directory, warms the disk cache from scratch, and takes seconds to minutes on a real workstation. On a corpus of a few hundred thousand files a warm PowerShell scan already takes 16–27 s; a cold one is far worse. An agent that does this in a loop burns wall-clock time and tool-call budget on I/O, not reasoning.

• Guessing. Ask the user where the file is, or guess a path and fail.

Everything maintains a persistent NTFS index (built from the USN journal) of file names, paths, sizes and modification times. A query against that index returns in single-digit milliseconds for millions of entries, with no disk walk and no cache warm-up. dsh_everything puts that index behind an MCP server so the agent can use it directly.

Concrete agent tasks this unlocks:

• "Find the Q3 budget spreadsheet and summarize it" — everything_search on a name fragment, newest first, in milliseconds.

• "What changed in this repo this week?" — everything_changes with since=7d.

• "Why is the disk full?" — everything_summary by extension, then a top-N of the largest files.

• "Are there duplicate photos?" — everything_duplicates in name_size or hash mode.

• "Where is TODO mentioned in the backend?" — everything_grep over the candidate tree with ripgrep.

• "Export all build logs over 10 MB to CSV" — everything_export.

The server does not replace read/edit/shell tools. It replaces the search step in front of them, which is usually the slow part.

The next section quantifies that difference on three real corpora — including the cases where the index does not win.

2. Benchmarks

TL;DR — on C:\Program Files (427,637 files), finding every *.dll takes 0.9 ms through the index versus 14.5 s for a warm recursive scan: 15,504× faster. Read the fairness caveats at the end of this section before quoting any number.

Measured 2026-10-18 on Windows 10 Pro (AMD Ryzen 7 5800H, 16 GB RAM), Everything 1.4.1.1024 with 3,243,750 index entries, Python 3.11.7. Native baseline: warm PowerShell 7.6.6 in one -NoProfile process; MCP: in-process call to the function behind each tool. Median of 3 samples (2 for C:\Program Files), one warm-up discarded; speedup = native scan ÷ MCP call. The run used EV_SCAN_CAP=600000; total runtime was 517 s.

C:\Windows\System32 — 17,616 files, 25,531 index entries

C:\Program Files — 427,637 files, 554,843 index entries

synthetic corpus (30k files / 200 dirs) — 30,000 files, 30,201 index entries

The MCP side was measured as an in-process call, so these timings exclude JSON-RPC transport: a separate end-to-end MCP stdio round-trip measured 5.74 ms median — add that for whole-call latency. Grouping and duplicate detection are the weak spot for the MCP side (about 1–3×) because they paginate the index over HTTP 1000 rows at a time. The 200-file directory case is near-parity in absolute terms: 3.0 ms versus 0.7 ms.

Why counts differ. Rows marked no are legitimate differences, not errors: (a) ACL-protected subtrees such as C:\Windows\System32\config\systemprofile and C:\Program Files\WindowsApps are indexed by Everything but cannot be enumerated by a normal-user recursive scan — this is the largest difference and it makes the index counts higher; (b) Windows system directories churn, so some index entries lag the disk; (c) Everything's dm: filter is day-granular while the native baseline used an exact now-7×24h window; (d) size: units are KB-quantized. Counts are presented as information, not as a correctness gate — the query semantics and returned rows are what matter.

2.1 Methodology

The benchmark harness lives in benchmarks/ and is reproducible: benchmarks/bench.py drives both sides, benchmarks/native_baseline.ps1 contains the PowerShell baseline, and benchmarks/gen_dataset.py generates the synthetic corpus.

• Same corpus, same query, both sides. Each scenario runs against an identical file set: a native PowerShell recursive scan and the equivalent Everything index query, with the same path scope.

• Native baseline is warm, idiomatic PowerShell 7.6.6. Get-ChildItem, Where-Object and findstr run inside one pwsh -NoProfile process timed with [Diagnostics.Stopwatch]. Shell startup is excluded, one warm-up pass is discarded, and each scenario reports the median of 3 samples (2 samples for the 16–27-second C:\Program Files pass). Grouping uses an O(n) hashtable rather than Group-Object, because PowerShell 5.1's Group-Object took 36 s on 30k items — the baseline is idiomatic, not artificially slow. This is the best case for a scan.

• The MCP side is the same code path, in-process. Each measurement calls the exact function behind the MCP tool with the same query and the same path scope; a separate end-to-end stdio measurement reports JSON-RPC overhead (5.74 ms median on the reference machine).

• Correctness is checked, not assumed. Native and MCP hit counts are compared per scenario; legitimate mismatches (result caps, index scope, ACL-protected subtrees, KB-quantized size: syntax, day-granular dm:) are recorded in count_match / count_note and explained above rather than hidden.

• Corpora: C:\Windows\System32 (small, ~17.6k files), C:\Program Files (large, ~427.6k files), and a generated synthetic tree (30k files, 200 directories, known extension/size/mtime distribution, ~350 duplicate-related files). The complete run used EV_SCAN_CAP=600000 so aggregation scenarios could cover all of C:\Program Files; every other setting was default.

2.2 Fairness caveats — read this before quoting a number

Honest summary: these numbers compare a prebuilt index query with a live recursive scan. They measure the value of having an index, not a magic faster filesystem. On small or already-cached scopes the gap shrinks to near parity; on large corpora and repeated queries it is large. Everything is Windows/NTFS only, and everything_grep speed comes from ripgrep plus a small candidate set, not from the index.

• The index is prebuilt and maintained. Everything's advantage comes from having already walked the filesystem once and tracking changes via the USN journal. The benchmark compares a query against that index with a live scan; it does not compare indexing cost with scan cost. Someone still pays to build and maintain the index.

• Cold caches and tiny scopes erase the advantage. On a small directory whose metadata is already in RAM, a native scan can finish in a few milliseconds; the MCP round trip plus HTTP query may be comparable or slower. The speedup grows with corpus size and with repeated queries.

• Windows and NTFS only. Everything cannot index Linux filesystems, network shares (by default), FAT/exFAT volumes, or files outside the volumes you add to it. There is no portable equivalent here.

• Content search is ripgrep, not Everything. everything_grep speed depends on the candidate tree, file sizes, ignore rules and the pattern — not on the Everything index. It is still far faster than grepping a whole disk because the candidate set is small.

• Aggregation and duplicate detection are the weakest case for the MCP side. everything_summary and everything_duplicates page through the index 1000 rows per HTTP request, so their speedup is roughly 1–3× rather than the three-digit numbers of a single filtered query. They are bounded and predictable, but they are not where the index shines.

• Index memory and disk are real costs. Everything keeps the index in memory and on disk (hundreds of MB on a multi-million-entry machine). The benchmark numbers do not include that footprint.

• Tool-call overhead is excluded from per-operation timings except in the explicitly reported stdio round-trip measurement. An agent pays that overhead on every call.

3. Features

• 13 tools designed for agents, not humans:

  • 7 query tools — everything_search, everything_count, everything_status, everything_help, everything_presets, everything_export, everything_download.

  • 6 composite tools — everything_summary, everything_duplicates, everything_grep, everything_batch_stat, everything_changes, everything_reveal.

• 3 MCP resources — everything://help/syntax, everything://status, everything://presets.

• Everything-native query syntax — ext:, size:, dm:, path:, parent:, wfn:, wildcards, | (OR), ! (NOT), regex, quotes, Chinese file names.

• Pagination, sorting, field projection and count_only to keep responses small enough for a model context window.

• Aggregation and duplicate detection with hard scan caps so a query can never dump a whole disk into the context window.

• Content search via ripgrep — automatic detection (EV_RG_EXE → DSH-bundled rg.exe → PATH → common install locations); a missing rg produces an actionable error, not a crash.

• Export to CSV (UTF-8 BOM for Excel), JSONL, or EFU; download files through the Everything HTTP server. Both are confined to configured root directories.

• 8 built-in presets (recent_modified_7d, today_changed, large_files_100mb, screenshots_7d, archives_100mb, git_repos, node_modules, downloads_today) plus your own via EV_PRESETS_FILE.

• Loopback-only, no telemetry, no network egress. The only network traffic is HTTP to 127.0.0.1:8090 on the same machine.

• Read-only by default. Only everything_export and everything_download write files (inside their configured roots); everything_reveal is the single side-effect tool and can be disabled with EV_ALLOW_SIDE_EFFECTS=0.

• Auto-start — if Everything is not running, the server can launch it minimized (EV_AUTO_START=1, the default).

• Operational diagnostics — everything_status and everything_help explain the index, the HTTP channel, ini switches, ripgrep and query capabilities instead of failing silently.

• Works with any MCP client. DSH is the primary target (mcp__everything__* tool names), but the transport is plain MCP stdio.

4. Requirements

5. Install

5.1 Enable the Everything HTTP server

The server talks to Everything's built-in HTTP JSON API. It is disabled by default, and Everything's HTTP interface has no authentication, so it must listen on loopback only.

1. Quit Everything completely (tray icon → Exit). Editing the ini while it runs does not stick: Everything rewrites its settings on exit.

2. Open %APPDATA%\Everything\Everything.ini in a text editor. If the file does not exist there, look at C:\Program Files\Everything\Everything.ini; an app_data=1 line in it redirects settings to %APPDATA%.

3. Set exactly these keys (leave the rest untouched):

   http_server_enabled=1
   http_server_port=8090
   http_server_bindings=127.0.0.1
   http_server_allow_file_download=1

4. Start Everything again.

5. Verify from a terminal:

   curl.exe "http://127.0.0.1:8090/?search=test&count=1&json=1"

   A working server answers with JSON such as {"totalResults":123,"results":[...]}. An empty index is fine at this point as long as you get JSON back.

The bindings pitfall. http_server_bindings takes a bare IP address (127.0.0.1). Writing 127.0.0.1:8090 makes Everything silently not start the HTTP server — no error, no listener. The port is the separate http_server_port key. Never bind 0.0.0.0 or a LAN address: that exposes the full file listing and file downloads to the network without authentication.

http_server_allow_file_download=1 is only required for everything_download. With it enabled, any local process can read any indexed file over loopback HTTP — that is the point of the tool, but it is a deliberate local trust decision.

The repository ships a read-only environment doctor that checks Everything, the HTTP endpoint, Python and the MCP SDK, and prints the exact DSH profile snippet with your machine's real paths:

pwsh -File scripts\setup.ps1

Pass -EnableHttpServer to let it stop Everything, back up the ini, write the three HTTP keys (enabled, port, bindings) and restart Everything. It does not set http_server_allow_file_download; add that key manually if you want everything_download.

5.2 Clone and install

Recommended — editable install. This installs the mcp dependency and a dsh-everything-mcp console script:

git clone https://github.com/CZM1998/dsh_everything.git
cd dsh_everything
python -m pip install -e .

From then on either entry point works:

dsh-everything-mcp          # console script (installed)
python -m everything_mcp    # module entry point (installed)

Zero-install alternative — no packaging, just the one dependency and the script in the repository:

git clone https://github.com/CZM1998/dsh_everything.git
cd dsh_everything
python -m pip install "mcp>=1.2.0"
python server.py            # or: python <PATH-TO-REPO>\server.py from any cwd

The server speaks MCP over stdio. Started manually it waits for a client handshake; that is expected. On startup it performs one read-only self-check against the HTTP endpoint and logs the result to stderr (stdout is reserved for the MCP protocol). A failed self-check does not kill the process — the first tool call retries and returns actionable guidance.

5.3 Register with DSH

DSH mounts MCP servers through @deepseek-ai/dsh-mcp-client. Add an entry to the target profile's patch file:

%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml

The patch file is a top-level YAML array of loader entries; merge the item below into the existing array. Replace the three placeholders (<PYTHON>, <PATH-TO-REPO>, <WORKSPACE>) — the full commented version lives in examples/cordis.patch.yml.

- id: mcp-everything
  name: "@deepseek-ai/dsh-mcp-client"
  config:
    serverName: everything                 # tools appear as mcp__everything__*
    transport: stdio
    command: <PYTHON>                      # e.g. C:\Python311\python.exe
    args:
      - <PATH-TO-REPO>\server.py           # e.g. D:\work\dsh_everything\server.py
    cwd: <WORKSPACE>                       # e.g. D:\work
    env:
      EV_HTTP_HOST: "127.0.0.1"
      EV_HTTP_PORT: "8090"                 # must match http_server_port
      EV_AUTO_START: "1"
      EV_WORKSPACE_ROOT: "<WORKSPACE>"
      EV_EXPORT_ROOT: "<WORKSPACE>"
      EV_DOWNLOAD_ROOT: "<WORKSPACE>"
      PYTHONUTF8: "1"
      PYTHONIOENCODING: "utf-8"
    toolCallTimeoutMs: 30000
    failOnStartupError: false

Notes:

• If you did the editable install, you can use command: dsh-everything-mcp and omit args instead of pointing at server.py.

• serverName: everything is what produces the mcp__everything__<tool> prefix.

• EV_WORKSPACE_ROOT is the agent's working directory and the default parent for the export and download roots. Keep all three consistent unless you deliberately want exports somewhere else.

• Keep failOnStartupError: false so a broken MCP entry cannot prevent the harness from starting.

• DSH strips DSH_* and secret-looking environment variables from child processes; EV_* variables pass through untouched.

• Other MCP clients: use examples/mcp.json instead.

5.4 Restart dsh web

Profile changes are applied at startup. Restart dsh web after editing the patch.

Known issue: live profile edits. If a session is already running when the profile is edited, the running harness can hold stale fibers and every tool call then fails with cannot get required service "sessionProjections" in inactive context. Restarting dsh web clears it. Editing the profile and restarting is the supported path.

5.5 Verify

Ask the agent to call mcp__everything__everything_status, then mcp__everything__everything_search:

{"query": "ext:py", "max_results": 3}

everything_status returns ok: true, the Everything version, the index entry count and the HTTP endpoint state. If it reports a problem, follow its hints array or the Troubleshooting table.

5.6 Environment variables

All configuration is through environment variables. Every one has a working default; you only need the ones you want to change.

6. Quick start

Five calls that cover most agent needs. "Intent" is what the user says; the JSON is the exact tool argument object.

6.1 Find a file

"Find the Q3 budget spreadsheet, newest first."

{
  "query": "ext:xlsx \"Q3 budget\"",
  "sort": "date_modified",
  "ascending": false,
  "max_results": 20,
  "fields": ["name", "path", "size", "date_modified"]
}

Returns the newest matching workbooks with full paths. Quotes force an exact phrase; without them the two words are an AND search.

6.2 Count by extension

"How many Python files are in this project?"

{"query": "ext:py", "path_scope": "D:\\work\\my-app"}

Returns {"total": 1284, ...} and no file list — the cheapest existence check.

6.3 Search file contents

"Where is TODO mentioned in the backend?"

{
  "pattern": "TODO",
  "path_scope": "D:\\work\\my-app",
  "exts": ["py", "ts"],
  "max_results": 50
}

Returns matches[] with path, line, column and text, plus ripgrep stats. This is ripgrep over the candidate tree, not an Everything index lookup.

6.4 Top-N largest files

"What are the ten biggest ISO images on this machine?"

{
  "query": "size:>100mb ext:iso",
  "sort": "size",
  "ascending": false,
  "max_results": 10,
  "fields": ["name", "path", "size"]
}

sort=size with ascending=false puts the largest first. Use raw byte values (no unit suffix) if you need exact thresholds — see §8.

6.5 Recent changes

"What changed in my project this week?"

{"since": "7d", "path_scope": "D:\\work\\my-app", "max_results": 20}

Returns files modified in the window, newest first, with a window object that documents the exact time bounds. See §7.12 for the date-granularity caveat.

7. Tool reference

All tools return JSON objects. Errors are raised as MCP tool errors with a human-readable, actionable message. In DSH, prefix every name with mcp__everything__ (e.g. mcp__everything__everything_search).

7.1 everything_search

Everything-native search with pagination and projection. regex=true switches the query to a regular expression; path_scope is composed into the Everything query as path:"..." and re-checked client-side (with regex=true it degrades to a client-side prefix filter and reports approx/warnings). fields is a subset of type/name/path/size/date_modified/extension; unrequested columns are not even fetched from Everything.

{
  "query": "ext:log size:>10mb",
  "sort": "size",
  "ascending": false,
  "max_results": 2,
  "fields": ["name", "path", "size", "date_modified"]
}

{
  "query": "ext:log size:>10mb",
  "effective_query": "ext:log size:>10mb",
  "total": 10,
  "returned": 2,
  "truncated": true,
  "next_offset": 2,
  "offset": 0,
  "max_results": 2,
  "sort": "size",
  "ascending": false,
  "results": [
    {"type": "file", "name": "build.log", "path": "D:\\work\\builds\\build.log",
     "size": 53485308, "date_modified": "2025-07-05T06:18:42Z"},
    {"type": "file", "name": "debug.log", "path": "D:\\work\\tools\\debug.log",
     "size": 35820691, "date_modified": "2025-08-30T00:36:35Z"}
  ],
  "warnings": [],
  "elapsed_ms": 4.8,
  "channel": "http"
}

Pagination: pass the returned next_offset as offset; stop when truncated=false. count_only=true returns only total (same as everything_count). sort accepts only name, path, size, date_modified; anything else produces a warning and falls back to name ascending. Name order is Everything's natural sort, not code-point order — do not assert strict lexicographic order.

7.2 everything_count

The cheapest question: does it exist, and how many are there?

{"query": "ext:py", "path_scope": "D:\\work\\my-app"}

{"query": "ext:py", "effective_query": "ext:py path:\"D:\\work\\my-app\"",
 "total": 1284, "elapsed_ms": 11.4, "channel": "http", "warnings": []}

7.3 everything_status

No arguments. Use it first when anything looks wrong.

{}

Trimmed response (paths shown with placeholders):

{
  "ok": true,
  "channel": "http",
  "http": {"url": "http://127.0.0.1:8090/", "reachable": true, "error": null},
  "everything": {"running": true, "version": "1.4.1.1024",
                 "exe": "C:\\Program Files\\Everything\\Everything.exe"},
  "index": {"total_items": 3200000, "ready": true},
  "index_db": {"path": "C:\\Users\\<USER>\\AppData\\Local\\Everything\\Everything.db",
               "size_mb": 128.8},
  "index_switches": {"index_size": "1", "index_date_modified": "1",
                     "index_date_created": "0", "index_date_accessed": "0",
                     "index_attributes": "0", "index_folder_size": "0"},
  "rg": {"available": true, "source": "dsh-bundled", "version": "ripgrep 15.0.0"},
  "presets": {"count": 8},
  "capabilities": {"columns": ["path", "size", "date_modified"],
                   "sort": ["name", "path", "size", "date_modified"]},
  "auto_start": true,
  "hints": [],
  "elapsed_ms": 45.2
}

hints[] contains actionable advice (for example, which ini switches are disabled and why dc:/da:/attrib: queries are slow).

7.4 everything_help

No arguments. The self-explaining entry point: supported syntax, unsupported syntax, slow queries, HTTP parameter matrix, all 13 tools, example calls and tips. The same content is available as a markdown string in the markdown field and as the everything://help/syntax resource. Call it before guessing whether a query prefix works.

7.5 everything_presets

{"action": "list"}

{
  "action": "list",
  "count": 8,
  "presets": [
    {"name": "recent_modified_7d", "description": "Files/directories modified in the last 7 days",
     "query": "dm:last7days", "sort": "date_modified", "ascending": false, "max_results": 100},
    {"name": "large_files_100mb", "query": "size:>100mb", "sort": "size", "ascending": false}
  ],
  "warnings": []
}

Run one, optionally overriding paging and scope:

{"action": "run", "name": "screenshots_7d", "max_results": 50}

Built-ins: recent_modified_7d, today_changed, large_files_100mb, screenshots_7d, archives_100mb, git_repos, node_modules, downloads_today. Add your own with EV_PRESETS_FILE (see §9.8).

7.6 everything_export

Writes a file inside EV_EXPORT_ROOT (default: workspace) and returns its path. CSV is UTF-8 with a BOM so Excel opens it correctly; JSONL is one object per line; EFU is an Everything file list (Filename,Size,Date Modified, FILETIME dates). Default 5000 rows, hard cap 10000; use offset to export in slices.

{
  "query": "ext:log size:>10mb",
  "out_path": "reports/big_logs.csv",
  "format": "csv",
  "max_results": 5000,
  "sort": "size",
  "ascending": false
}

{"ok": true, "format": "csv", "path": "D:\\work\\reports\\big_logs.csv",
 "rows": 137, "bytes": 24512, "total": 137, "offset": 0,
 "truncated": false, "elapsed_ms": 19.3, "channel": "http", "warnings": []}

Relative output paths resolve against EV_EXPORT_ROOT; absolute paths outside it are rejected.

7.7 everything_download

Copies an indexed file to EV_DOWNLOAD_ROOT (default: workspace) using the Everything HTTP server. dest is optional; a name collision gets a numeric suffix. max_bytes defaults to 2 GiB and the partial file is removed if it is exceeded.

{"path": "D:\\work\\builds\\release.zip"}

{"ok": true, "source": "D:\\work\\builds\\release.zip",
 "saved_path": "D:\\work\\release.zip", "bytes": 33554432,
 "size": 33554432, "max_bytes": 2147483648, "elapsed_ms": 128.7}

Requires http_server_allow_file_download=1. A 404 usually means the file moved or the index has not caught up; search again and retry.

7.8 everything_summary

Groups matches and aggregates count and bytes. group_by is one of ext, dir, type, size_bucket, month, parent. By default only files are aggregated (directory sizes are 0 and would skew results); include_folders=true adds them with aggregates="files+folders".

{
  "query": "",
  "path_scope": "D:\\work\\my-app",
  "group_by": "ext",
  "top_n": 6,
  "max_scan": 2000
}

{
  "query": "", "path_scope": "D:\\work\\my-app", "group_by": "ext",
  "total": 33, "scanned": 33, "truncated_scan": false,
  "groups": [
    {"key": "py", "count": 14, "size": 412707, "min_size": 6159, "max_size": 80833, "avg_size": 29479},
    {"key": "md", "count": 4, "size": 86907, "min_size": 15990, "max_size": 28990, "avg_size": 21727}
  ],
  "totals": {"count": 33, "size": 891287, "min": 777, "max": 92218},
  "stats": {"groups_found": 2, "returned_groups": 2, "elapsed_ms": 92.8},
  "warnings": [], "elapsed_ms": 92.8
}

Scans are capped by max_scan and EV_SCAN_CAP; truncated_scan=true means the numbers are a lower bound. With group_by=dir, dir_depth (1–12) controls the directory key depth; with a path_scope the keys are relative to it.

7.9 everything_duplicates

Read-only duplicate detection. Modes:

• name — same file name (case-insensitive); uses Everything's dupe: when available, otherwise falls back to a paged scan with a warning.

• name_size — same name and same size (the safest quick duplicate signal).

• size — files sharing a size (≥ min_size).

• hash — hashes same-size candidates (md5/sha1/sha256/sha512/blake2b) to confirm real duplicates, within max_files and max_hash_bytes budgets.

{"mode": "name_size", "path_scope": "D:\\work\\photos", "min_size": 1048576, "max_groups": 5}

{
  "mode": "name_size", "query_used": "dupe:", "total": 4, "scanned": 4,
  "groups": [
    {"key": "photo.jpg|2048", "count": 2, "size": 2048, "path_count": 2,
     "paths": ["D:\\work\\photos\\backup\\photo.jpg", "D:\\work\\photos\\photo.jpg"]}
  ],
  "stats": {"groups_found": 1, "returned_groups": 1, "dupe_support": true,
            "max_paths_per_group": 2, "payload_bytes": 1147},
  "warnings": [], "elapsed_ms": 940.1
}

Output is budgeted for a model context: 10 groups by default (max 50), only the first 2 paths per group (max 50, full count in path_count), and a 4 KiB response budget (max_response_bytes, 0 disables). It never deletes or modifies files. dupe: scans the whole index and takes ~200 ms — far slower than a normal query, so avoid calling it in tight loops.

7.10 everything_grep

Content search with ripgrep. Give either path_scope or a query; with a query, the server derives up to 8 search roots from the common parent directories of the candidate files.

{
  "pattern": "def main",
  "path_scope": "D:\\work\\my-app\\backend",
  "exts": ["py"],
  "max_results": 3
}

{
  "pattern": "def main", "path_scope": "D:\\work\\my-app\\backend",
  "roots": ["D:\\work\\my-app\\backend"],
  "matches": [{"path": "D:\\work\\my-app\\backend\\server.py", "line": 468,
               "column": 1, "text": "def main() -> None:"}],
  "stats": {"files_searched": 11, "files_matched": 1, "elapsed_ms": 118.7,
            "truncated": false, "timed_out": false, "max_results": 3},
  "truncated": false, "warnings": [], "elapsed_ms": 184.7
}

max_results ≤ 1000, max_filesize (e.g. 10M), timeout_ms default 20000 (100–300000), no_ignore=true to ignore .gitignore. A missing ripgrep returns an error listing the paths it probed and how to fix it (winget install BurntSushi.ripgrep.MSVC or set EV_RG_EXE); other tools keep working.

7.11 everything_batch_stat

Stats up to 200 paths in one call (1–200; extras are truncated with a warning, duplicates de-duplicated). Works for files, directories and missing paths; optional hashing is read-only and budgeted.

{"paths": ["D:\\work\\my-app\\README.md", "D:\\work\\missing.txt"], "include_hash": true}

{
  "items": [
    {"path": "D:\\work\\my-app\\README.md", "exists": true, "type": "file",
     "size": 28990, "date_modified": "2026-10-18T03:05:04Z",
     "date_created": "2026-10-18T02:34:20Z", "mode": "0666", "is_link": false,
     "hash": "9f2c...", "error": null},
    {"path": "D:\\work\\missing.txt", "exists": false, "type": null, "size": null,
     "error": "not found"}
  ],
  "count": 2, "exists_count": 1, "missing_count": 1,
  "include_hash": true, "hash_algo": "md5", "stats": {"elapsed_ms": 1.1, "hashed": 1}
}

7.12 everything_changes

Files changed inside a window. since accepts today, 24h, 7d, 30m, last7days, or an ISO timestamp (e.g. 2026-10-17T08:00:00+08:00).

{"since": "24h", "path_scope": "D:\\work\\my-app", "exts": ["py", "ts"], "max_results": 3}

{
  "since": "24h", "query": "dm:>=2026-10-17", "path_scope": "D:\\work\\my-app",
  "items": [
    {"type": "file", "name": "server.py", "path": "D:\\work\\my-app\\backend\\server.py",
     "size": 18220, "date_modified": "2026-10-18T03:15:07Z", "extension": "py"}
  ],
  "count": 1, "total": 33, "truncated": true,
  "window": {"since": "2026-10-17T03:27:59Z", "until": "2026-10-18T03:27:59Z",
             "spec": "24h", "dm_expression": "dm:>=2026-10-17", "precise": true},
  "warnings": ["<explains that the dm: filter is date-level and the exact window is applied client-side>"]
}

Why the warning: Everything 1.4 does not understand dm:last1hour-style relative syntax (it returns 0). The server always converts since into an absolute dm:>=YYYY-MM-DD filter and then applies the exact time window client-side. total is the date-level candidate count; count is the exact in-window count.

7.13 everything_reveal

The only side-effect tool: opens File Explorer with the file selected, or opens a directory. It never deletes, moves, copies or renames anything. With EV_ALLOW_SIDE_EFFECTS=0 it starts no process and returns {"ok": false, "opened": false, "error": ..., "hint": ...}; the variable is re-read on every call, so no restart is needed to toggle it.

{"path": "D:\\work\\my-app\\README.md"}

{"ok": true, "opened": true, "mode": "select",
 "path": "D:\\work\\my-app\\README.md", "warnings": []}

7.14 MCP resources

Resource read failures return an explanatory payload instead of breaking tool calls; the tools remain available.

8. Everything query syntax cheat sheet

The query string is passed to Everything almost verbatim, so Everything's own syntax applies. This is the verified 1.4.1 subset that matters most; the full matrix with measured hit counts is in docs/CAPABILITIES.md.

8.1 Names, paths and filters

report_2025*              wildcard in the file name
"Q3 budget"               exact phrase (quotes)
ext:xlsx                  one extension
ext:py;ts;js              several extensions — SEMICOLONS only
file:report               files only
folder:node_modules       directories only
path:"D:\work\my-app"     path contains (includes subdirectories)
parent:"D:\work\my-app"   direct children of a path — must be a FULL path
wfn:*.exe                 match the whole file name
startwith:report          name prefix
endwith:.log              name suffix
len:>40                   name length
empty:                    empty directories
nopath:foo                ignore path matches

ext: accepts only semicolons: ext:exe,dll and ext:py* silently match nothing. parent: requires the complete path; parent:software returns nothing. path: is a contains match over the whole path, so it also matches subdirectories. Path filtering only works inside the search string: the HTTP API's path= parameter is a boolean match-path switch, not a filter, and filter= is ignored. The path_scope tool argument composes path:"..." into the query for you.

8.2 Boolean logic and quoting

blender ext:exe           space = AND
jpg | png                 | = OR
blender !everything.exe   ! = NOT

There is no word OR — write jpg | png. Quotes are the only way to search for a phrase containing spaces.

8.3 Size — the KB-quantization trap

size: with a unit is not byte-exact. Everything converts kb/mb/gb to a KB count U and compares ceil(size / 1024) against it. In practice:

For exact byte thresholds use a unitless value or a range: size:>104857600, size:1047553..1048576.

8.4 Dates

dm:today
dm:last7days
dm:>=2026-10-17
dm:2026-10-17..2026-10-18
dm:2026-10

dm: is modification time and is indexed by default. Hour-level relative forms (dm:last1hour, …) return 0 on 1.4 — use everything_changes or an absolute range. dc: (created), da: (accessed) and attrib: work syntactically but are not indexed by default and can take more than 5 seconds; enable the matching index switches and rebuild the index first, or just don't use them.

8.5 Everything 1.5-only prefixes

These return nothing on 1.4 and are not recommended anywhere in this project:

distinct:    sort:    run_count:    date_run:

An unknown XYZ: prefix is treated as literal text, not as an error, so a query using an unsupported function quietly returns 0. If a query returns 0 and the syntax "should" work, check the prefix in everything_help.

8.6 Other rules worth knowing

• sort is an HTTP parameter, not query syntax; only name, path, size, date_modified are effective. Unknown values silently fall back to name.

• Name sorting is Everything's natural sort (localized, numbers as numbers), not Unicode code-point order.

• Case-insensitive by default; wrap the query in case: or set case_sensitive.

• Chinese paths and file names work as UTF-8 over the HTTP channel.

• Prefer Everything-native syntax to regex: it is faster and clearer. Do not mix regex=true with ext:/path: functions.

9. Recipes

Full task-oriented versions of these (with agent-prompt examples and expected output shapes) are in docs/USAGE.md.

9.1 Search then filter

"Find large installers modified this year under Downloads."

{
  "query": "ext:msi;exe dm:>=2026-01-01 size:>100mb",
  "path_scope": "D:\\work\\Downloads",
  "sort": "size",
  "ascending": false,
  "max_results": 20,
  "fields": ["name", "path", "size", "date_modified"]
}

9.2 Content grep with ripgrep

"Find every place the API base URL is hard-coded."

{
  "pattern": "https://api\\.example\\.com",
  "path_scope": "D:\\work\\my-app",
  "exts": ["ts", "tsx", "js"],
  "fixed_strings": false,
  "max_results": 100
}

9.3 Duplicate detection

"Do I have duplicate files in this photo library?"

{"mode": "name_size", "path_scope": "D:\\work\\photos", "min_size": 1048576, "max_groups": 10}

Escalate to {"mode": "hash", "hash_algo": "sha256", "max_hash_bytes": 536870912} when you need certainty.

9.4 Recent changes

"What did I touch today?"

{"action": "run", "name": "today_changed", "max_results": 50}

or, scoped to a project:

{"since": "today", "path_scope": "D:\\work\\my-app", "max_results": 50}

9.5 Large-file audit

"Where did my disk space go?" Two calls: aggregate by extension, then list the biggest files.

{"query": "", "path_scope": "D:\\", "group_by": "ext", "top_n": 15, "max_scan": 50000}

{"query": "size:>500mb", "sort": "size", "ascending": false, "max_results": 20,
 "fields": ["name", "path", "size"]}

9.6 Cluster by extension or directory

{"group_by": "ext", "path_scope": "D:\\work\\my-app", "top_n": 20}

{"group_by": "dir", "dir_depth": 1, "path_scope": "D:\\work\\my-app", "top_n": 20}

group_by=size_bucket gives a histogram, month groups by modification month, parent by immediate parent directory.

9.7 Export to CSV

"Give me every log over 10 MB as a spreadsheet."

{
  "query": "ext:log size:>10mb",
  "out_path": "reports/big_logs.csv",
  "format": "csv",
  "sort": "size",
  "ascending": false,
  "max_results": 5000
}

The file lands in EV_EXPORT_ROOT; rows, bytes and truncated tell you whether you need another slice with offset.

9.8 Custom presets

Set EV_PRESETS_FILE to a JSON file (a template is in examples/presets.json):

{
  "presets": [
    {
      "name": "recent_downloads_7d",
      "description": "Files modified in the last 7 days in Downloads",
      "query": "dm:last7days",
      "path_scope": "{downloads}",
      "sort": "date_modified",
      "ascending": false,
      "max_results": 100,
      "fields": ["name", "path", "size", "date_modified"]
    }
  ]
}

Then {"action": "run", "name": "recent_downloads_7d"}. Presets override built-ins by name; placeholders {downloads}, {userprofile} and {workspace} expand at runtime. JSON uses only the standard library; YAML needs PyYAML.

9.9 Download a file

{"path": "D:\\work\\builds\\release.zip", "dest": "artifacts/release.zip", "max_bytes": 104857600}

The destination resolves under EV_DOWNLOAD_ROOT; the call fails cleanly if the file grew beyond max_bytes or the destination escapes the root. This copies bytes over loopback HTTP — it is not a search operation.

10. Architecture

┌──────────────────────────┐
│ MCP client (DSH / other) │
│  mcp__everything__*      │
└────────────┬─────────────┘
             │ MCP stdio (JSON-RPC over stdin/stdout)
┌────────────▼─────────────┐
│ server.py                │  FastMCP server: 7 query tools + 3 resources,
│ everything_mcp/server.py │  registers 6 composite tools
└────────────┬─────────────┘
             │
     ┌───────┴────────┐
     │                │
┌────▼─────────┐  ┌───▼──────────────────────────────────────────────┐
│ client.py    │  │ compose_tools.py                                 │
│ search/count │  │ summary · duplicates · grep · batch_stat ·       │
│ status/export│  │ changes · reveal                                 │
│ download     │  │        │                                         │
└────┬─────────┘  │        ├── rg.py → ripgrep (content search)       │
     │            │        └── local read-only post-processing        │
     │            └───┬──────────────────────────────────────────────┘
┌────▼─────────┐      │
│ http_channel │      │
│ urllib, JSON │      │
└────┬─────────┘      │
     │ HTTP GET http://127.0.0.1:8090/?search=...&json=1
┌────▼─────────────────▼─────┐
│ voidtools Everything       │
│ built-in HTTP JSON API     │
│ NTFS index (USN journal)   │
└────────────────────────────┘

A tool call flows: MCP client → FastMCP dispatcher → tool function → client.py (parameter validation, query composition, warnings) → http_channel.py (URL encoding, HTTP, FILETIME/size normalization) → Everything. Composite tools page through client.search and post-process locally; everything_grep shells out to ripgrep instead of reading file contents in Python.

11. Security and privacy

• Loopback only. The server talks to http://127.0.0.1:8090/ and refuses nothing else; it never contacts the internet. No telemetry, no analytics, no update check.

• Everything's HTTP API has no authentication. Binding it to 0.0.0.0 or a LAN address exposes the entire file listing and file downloads to the network. Always use http_server_bindings=127.0.0.1. This is the single most important security setting in the whole setup.

• Read-only by default. Searching, counting, summarizing, duplicate detection, batch stat, changes and grep only read. The only writes are everything_export and everything_download, both confined to EV_EXPORT_ROOT / EV_DOWNLOAD_ROOT after path resolution and symlink checks; everything_download enforces max_bytes and removes partial files.

• One side-effect tool. everything_reveal launches Explorer. Set EV_ALLOW_SIDE_EFFECTS=0 for a strictly read-only server; it is re-read on every call, so no restart is needed.

• Bounded responses. EV_MAX_RESULTS_CAP (1000), EV_SCAN_CAP (50k), EV_HASH_MAX_BYTES (256 MiB), grep timeouts, a 4 KiB duplicate response budget and 10k-row export cap keep a single call from dumping a disk into the model context or pinning the machine.

• No file contents leave the machine. The server is local; the model only sees the JSON returned by tools.

• Auto-start is local and visible. It launches Everything.exe -startup minimized and only when no Everything process is running and the HTTP endpoint is unreachable. Set EV_AUTO_START=0 to manage Everything yourself.

• No credentials. Nothing here reads or stores secrets, tokens or keys.

12. Limitations

• Windows + NTFS only. No macOS/Linux support, and Everything does not index network shares or FAT/exFAT volumes by default.

• Needs a running Everything with its HTTP server enabled. Without it the tools return an actionable error; there is no fallback scanner.

• 1.5 is not verified. The capability matrix (supported syntax, slow queries, column behaviour) was measured on 1.4.1.1024. Everything 1.5 changes some query functions; re-run tests/test_mcp.py and the matrix commands after an upgrade.

• dc: / da: / attrib: are not indexed by default and can exceed 5 seconds. Enabling them requires ini changes and a full index rebuild.

• Hour-level relative dates do not exist in 1.4. everything_changes normalizes to date-level dm: and filters precisely client-side; total is a date-level candidate count.

• size: with units is KB-quantized, not byte-exact (see §8.3).

• Content search depends on ripgrep being installed or bundled. If it is missing, everything_grep fails with instructions; the other 12 tools are unaffected.

• everything_duplicates(mode=name) uses dupe:, which scans the whole index (~200 ms on a 3.2M-entry machine). It is much slower than a normal query.

• No IPC/ETP transport. Everything 1.4's IPC query protocol needs the official SDK; this project deliberately uses only the built-in HTTP server. IPC window probing is used only to detect whether Everything is running.

• Named Everything instances are unsupported. -instance / -config instances cannot use the Everything service (empty index), so the server always reuses the default instance.

• Aggregate numbers can be lower bounds when max_scan / EV_SCAN_CAP is hit; the truncated_scan flag says so.

• Index freshness is near-real-time, not instant. Files created by other processes are typically visible in 1–5 seconds; deletions disappear on the same order. A file just written may not be searchable for a moment.

13. Troubleshooting

14. Development and tests

git clone https://github.com/CZM1998/dsh_everything.git
cd dsh_everything
python -m pip install -e .
python tests\test_mcp.py

The test suite is an end-to-end MCP test: it starts the server over stdio (or falls back to anonymous-pipe / in-memory transport when the environment forbids named pipes), performs the initialize handshake, lists tools and resources, and exercises every tool against the real local index.

• 142 assertion checks, all expected green on a machine with Everything running. Tier A checks (handshake, registration, status, search/count shapes, export and path-escape rejection, a bad-port error, both entry points, help/status/presets/resources) do not depend on the index being fully built.

• Tier B waits up to 240 s for the index and skips rather than fails on timeout (fresh installs can still be indexing).

• Temporary data is created with Python inside the workspace so Everything indexes it within seconds; tests then delete it and poll count == 0 to confirm the index caught up. Do not create fixtures with tools whose writes Everything does not observe immediately and then assert on index visibility.

• The suite never starts or stops Everything (EV_AUTO_START=0 inside the test) and never modifies the user's index.

• Useful test environment variables: EV_HTTP_PORT, EV_TEST_INDEX_WAIT, EV_TEST_TRANSPORT=auto|stdio|memory.

Before publishing changes, run the privacy check:

python scripts\privacy_check.py          # files known to git
python scripts\privacy_check.py --all    # whole working tree

It flags real user-profile paths, e-mail addresses, mobile numbers and any terms in .privacy-blocklist / PRIVACY_TERMS.

Repository layout:

dsh_everything/
├── server.py                  # entry point (any cwd)
├── everything_mcp/            # the package
│   ├── server.py              # FastMCP server: query tools + MCP resources
│   ├── client.py              # business layer: search/count/status/export/download
│   ├── http_channel.py        # Everything HTTP client + normalization
│   ├── compose_tools.py       # 6 composite tools
│   ├── rg.py                  # ripgrep detection + content search
│   ├── presets.py             # built-in + custom presets
│   ├── help.py                # capability matrix + help rendering
│   ├── winipc.py              # process/window diagnostics (ctypes)
│   └── config.py              # environment configuration
├── tests/test_mcp.py          # end-to-end MCP suite (142 assertion checks)
├── scripts/                   # setup doctor + privacy check
├── docs/                      # usage cookbook, capability matrix
├── examples/                  # profile patch, MCP config, presets
├── benchmarks/                # native-vs-MCP harness, results, charts
├── pyproject.toml             # packaging (console script dsh-everything-mcp)
├── LICENSE                    # MIT
└── README.md / README.zh-CN.md

The project has no third-party runtime dependencies beyond the MCP SDK, uses only the Python standard library otherwise, and logs to stderr so it never corrupts the stdio protocol stream. Contributions are welcome — keep the capability matrix and tests in sync with any behavior change.

15. License and acknowledgements

MIT — see LICENSE. Copyright (c) 2026 CZM1998.

Built on the shoulders of:

• voidtools Everything — the index and HTTP API that make this whole approach possible.

• ripgrep — fast content search behind everything_grep.

• Model Context Protocol and the official Python SDK — transport and server framework.

• DeepSeek Harness — the MCP host this server was designed for.

Everything is a trademark of voidtools. This project is not affiliated with or endorsed by voidtools.