everything-mcp-server 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Everything Search MCP contributors
+
+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.

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# Everything Search MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[简体中文](README.zh-CN.md)
+
+Search Windows files from your AI assistant using [Everything](https://www.voidtools.com/).
+
+Find files across indexed drives by name, path, type, size, or date. Browse folders, compare their sizes, and get counts or total file sizes in a single request. Searches use Everything's existing index, with paginated results and optional metadata.
+
+## Prerequisites
+
+- **OS**: Windows (x64, x86, ARM64, ARM)
+- **Node.js**: v22.0.0 or newer
+- **Everything**: [Everything](https://www.voidtools.com/) 1.4.1+ or 1.5 Alpha installed and running.
+
+The ES helper is included. The server automatically checks the default Everything instance, `1.5a`, and `1.5` and connects through local IPC.
+
+## Installation & Configuration
+
+On Windows, launch `npx` through `cmd.exe` as shown below. Choose your client, add the configuration, then reload its MCP connections. (DeepSeek Harness is the exception: it spawns the command directly, so plain `npx` works — see its section below.)
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=everything&config=eyJjb21tYW5kIjoiY21kLmV4ZSIsImFyZ3MiOlsiL2QiLCIvYyIsIm5weCIsIi15IiwiZXZlcnl0aGluZy1tY3Atc2VydmVyIl19)
+
+<details>
+<summary>OpenAI Codex</summary>
+
+Add to your Codex configuration file (`%USERPROFILE%/.codex/config.toml` or project-level `.codex/config.toml`):
+
+```toml
+[mcp_servers.everything]
+command = "cmd.exe"
+args = ["/d", "/c", "npx", "-y", "everything-mcp-server"]
+```
+
+Or add via Codex CLI:
+
+```powershell
+codex mcp add everything -- cmd.exe /d /c npx -y everything-mcp-server
+```
+
+</details>
+
+<details>
+<summary>OpenCode</summary>
+
+Add to your project's `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "everything": {
+      "type": "local",
+      "command": ["cmd.exe", "/d", "/c", "npx", "-y", "everything-mcp-server"]
+    }
+  }
+}
+```
+
+Or run the OpenCode setup wizard and enter the command above:
+
+```powershell
+opencode mcp add
+```
+
+</details>
+
+<details>
+<summary>DeepSeek Harness</summary>
+
+Install the plugin, then restart the profile:
+
+```powershell
+dsh plugin --profile <profile> add dsh-everything-mcp
+```
+
+Or install straight from this repository:
+
+```powershell
+dsh plugin --profile <profile> add github:EcRal5t/everything-search-mcp#path:/plugins/dsh-everything-mcp
+```
+
+The tools appear as `mcp__everything__search` and `mcp__everything__status`. To wire it by hand instead, add this row to the profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: mcp-everything
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: everything
+        transport: stdio
+        command: npx
+        args: ['-y', 'everything-mcp-server']
+```
+
+DSH spawns commands directly, so no `cmd.exe` wrapper is needed. See [`plugins/dsh-everything-mcp`](plugins/dsh-everything-mcp) for the bundle itself.
+
+</details>
+
+<details>
+<summary>Claude Desktop and other MCP clients</summary>
+
+Add to your MCP client configuration (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "cmd.exe",
+      "args": ["/d", "/c", "npx", "-y", "everything-mcp-server"]
+    }
+  }
+}
+```
+
+VS Code uses `servers` as the top-level key.
+
+</details>
+
+## What to ask
+
+After connecting, ask your assistant to use Everything for tasks such as:
+
+- **Locate a missing file:** “Find quarterly-report PDFs modified last month across my indexed drives.”
+- **Investigate large files:** “Show the ten largest log files or archives over 1 GB on C:, including their paths and sizes.”
+- **Find project artifacts:** “Find folders named node_modules or target under D:/Projects and tell me how many there are.”
+- **Compare folder sizes:** “Compare the sizes of the folders directly inside D:/Projects.”
+
+## Tools
+
+Both tools are read-only.
+
+| Tool | Purpose |
+| --- | --- |
+| `search` | Find paths, browse folders, count matches, and retrieve sizes or other indexed metadata. |
+| `status` | Check the connection, selected Everything instance, and version. |
+
+## Connection settings
+
+Default settings cover common local installations. Use `EVERYTHING_INSTANCE` for a custom instance name. Setting `EVERYTHING_URL` selects an Everything HTTP service; credentials go in `EVERYTHING_USERNAME` and `EVERYTHING_PASSWORD` when needed.
+
+<details>
+<summary>All environment variables</summary>
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `EVERYTHING_INSTANCE` | auto-detect | Probes the default instance, `1.5a`, and `1.5`. Set this for a custom instance; `""` selects the default instance. |
+| `EVERYTHING_URL` | `""` | Everything HTTP server URL (e.g. `http://127.0.0.1:17603/`). When set, uses HTTP transport instead of IPC. |
+| `EVERYTHING_USERNAME` | `""` | Basic auth username for HTTP server. |
+| `EVERYTHING_PASSWORD` | `""` | Basic auth password for HTTP server. |
+| `EVERYTHING_MAX_RESULTS` | `1000` | Row cap for each query and the whole batch (1–1000). |
+| `EVERYTHING_OUTPUT_BYTES` | `16384` | Maximum output size budget per tool call (4096–65536). |
+| `EVERYTHING_TIMEOUT_MS` | `15000` | Query timeout in milliseconds (100–120000). |
+| `EVERYTHING_ES_PATH` | bundled | Custom path to `es.exe`. |
+
+</details>
+
+## CLI & Diagnostics
+
+Test your Everything installation and backend connection:
+
+```powershell
+npx -y everything-mcp-server doctor
+```
+
+Run queries from the command line:
+
+```powershell
+npx -y everything-mcp-server search '{"requests": [{"query": "ext:pdf", "count": 5}]}'
+```
+
+---
+
+## Tool reference
+
+<details>
+<summary>Parameters and result format</summary>
+
+### `search`
+
+Search, browse directories, count items, and retrieve indexed metadata.
+
+Pass 1–8 queries in the required `requests` array:
+
+```json
+{"requests": [{"query": "ext:pdf", "count": 5}]}
+```
+
+**Parameters for each query:**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `query` | string | `""` | Everything search query (e.g. `*.pdf`, `size:>100mb`, `ext:ts;js`). |
+| `root` | string | optional | Directory to search within (e.g. `D:/Projects`). Omitted for global search. |
+| `recursive` | boolean | `true` | When `root` is set: `true` searches descendants; `false` lists direct children. |
+| `kind` | string | `"any"` | Filter entry type: `"any"`, `"file"`, or `"folder"`. |
+| `regex` | boolean | `false` | Treat `query` as a regular expression. |
+| `count` | number | `20` | Maximum rows to return (max 1000). Use `0` to count matches; add `kind:"file"` and `fields:["size"]` to get `total_size_bytes`. |
+| `offset` | number | `0` | Zero-based pagination offset. |
+| `sort` | string | `"path"` | Sort field: `path`, `name`, `size`, `extension`, `date_modified`, `date_created`, `date_accessed`, `attributes`, `run_count`. |
+| `ascending` | boolean | `true` | Sort ascending (`true`) or descending (`false`). |
+| `fields` | string[] | `[]` | Additional columns: `size`, `date_modified`, `date_created`, `date_accessed`, `attributes`, `run_count`. |
+
+IPC provides all listed fields and sorts. HTTP sorts by name, path, size, or modified time; it provides size and modified-time fields, with other metadata depending on the service.
+
+**Output Format:**
+
+Results label columns once, followed by row arrays:
+
+```json
+{
+  "results": [
+    {
+      "base": "D:/Projects",
+      "total": 42,
+      "next_offset": 2,
+      "columns": ["path", "type", "size_bytes"],
+      "rows": [
+        ["src/index.ts", "file", 1024],
+        ["package.json", "file", 512]
+      ],
+      "size_basis": "indexed_logical"
+    }
+  ]
+}
+```
+Combine `base` with relative paths in `rows` to obtain full file paths.
+File and folder sizes use logical byte counts from Everything's index.
+
+### `status`
+
+Check backend connectivity, Everything version, selected instance, and index status.
+
+**Parameters:**
+
+- `verbose` (boolean, default `false`): Include total indexed items and limits.
+
+</details>
+
+## Local Development
+
+```powershell
+git clone https://github.com/EcRal5t/everything-search-mcp.git
+cd everything-search-mcp
+npm install
+npm test
+```
+
+To configure an MCP client with a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "node",
+      "args": ["D:/path/to/everything-search-mcp/src/cli.js"]
+    }
+  }
+}
+```
+
+## License
+
+MIT. Bundled `es.exe` is also MIT licensed by voidtools. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/README.zh-CN.md

@@ -0,0 +1,263 @@
+# Everything Search MCP
+
+[English](README.md)
+
+让 AI 助手通过 [Everything](https://www.voidtools.com/) 查找 Windows 上的文件。
+
+按名称、路径、类型、大小或日期搜索各个已索引的驱动器，也能浏览目录、比较文件夹大小，或一次取得匹配数量和文件总大小。搜索使用 Everything 已有的索引，结果支持分页，并可按需附带文件信息。
+
+## 环境要求
+
+- **操作系统**：Windows (x64, x86, ARM64, ARM)
+- **Node.js**：v22.0.0 或更新版本
+- **Everything**：已安装并运行 [Everything](https://www.voidtools.com/) 1.4.1+ 或 1.5 Alpha。
+
+包内已附带 ES 工具。服务会自动探测默认实例、`1.5a` 和 `1.5`，通过本机 IPC 连接。
+
+## 安装与配置
+
+Windows 下按以下示例，通过 `cmd.exe` 启动 `npx`。选择对应客户端，添加配置后重新加载 MCP 连接。（DeepSeek Harness 例外：它直接 spawn 命令，用裸 `npx` 即可，见下方小节。）
+
+[![安装到 Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=everything&config=eyJjb21tYW5kIjoiY21kLmV4ZSIsImFyZ3MiOlsiL2QiLCIvYyIsIm5weCIsIi15IiwiZXZlcnl0aGluZy1tY3Atc2VydmVyIl19)
+
+<details>
+<summary>OpenAI Codex</summary>
+
+在 Codex 配置文件（用户全局 `%USERPROFILE%/.codex/config.toml` 或项目 `.codex/config.toml`）中添加：
+
+```toml
+[mcp_servers.everything]
+command = "cmd.exe"
+args = ["/d", "/c", "npx", "-y", "everything-mcp-server"]
+```
+
+或通过 Codex CLI 命令行添加：
+
+```powershell
+codex mcp add everything -- cmd.exe /d /c npx -y everything-mcp-server
+```
+
+</details>
+
+<details>
+<summary>OpenCode</summary>
+
+在项目的 `opencode.json` 中添加：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "everything": {
+      "type": "local",
+      "command": ["cmd.exe", "/d", "/c", "npx", "-y", "everything-mcp-server"]
+    }
+  }
+}
+```
+
+也可运行 OpenCode 设置向导，填写上面的命令：
+
+```powershell
+opencode mcp add
+```
+
+</details>
+
+<details>
+<summary>DeepSeek Harness</summary>
+
+安装插件后重启该 profile：
+
+```powershell
+dsh plugin --profile <profile> add dsh-everything-mcp
+```
+
+也可以直接从仓库安装：
+
+```powershell
+dsh plugin --profile <profile> add github:EcRal5t/everything-search-mcp#path:/plugins/dsh-everything-mcp
+```
+
+工具以 `mcp__everything__search` 和 `mcp__everything__status` 出现。也可以手工在 profile 的 `cordis.patch.yml` 里加：
+
+```yaml
+- insert:
+    - id: mcp-everything
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: everything
+        transport: stdio
+        command: npx
+        args: ['-y', 'everything-mcp-server']
+```
+
+DSH 直接 spawn 命令，不需要 `cmd.exe` 包装。配置包本身见 [`plugins/dsh-everything-mcp`](plugins/dsh-everything-mcp)。
+
+</details>
+
+<details>
+<summary>Claude Desktop 及其他 MCP 客户端</summary>
+
+在客户端配置（例如 `claude_desktop_config.json`）中添加：
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "cmd.exe",
+      "args": ["/d", "/c", "npx", "-y", "everything-mcp-server"]
+    }
+  }
+}
+```
+
+VS Code 的顶层字段使用 `servers`。
+
+</details>
+
+## 使用示例
+
+连接后，可以让助手使用 Everything 完成这些任务：
+
+- **找回文件**：“在各个已索引的驱动器上，找出上个月修改过、文件名包含 quarterly-report 的 PDF。”
+- **排查大文件**：“列出 C 盘超过 1 GB 的日志和压缩包中最大的十个，附上路径和大小。”
+- **查找工程产物**：“查找 D:/Projects 下名为 node_modules 或 target 的文件夹，并统计数量。”
+- **比较目录大小**：“比较 D:/Projects 下各个直接子文件夹的大小。”
+
+## 工具
+
+两个工具均为只读。
+
+| 工具 | 用途 |
+| --- | --- |
+| `search` | 查找路径、浏览目录、统计数量，以及取得大小或其他索引元数据。 |
+| `status` | 查看连接状态、所选 Everything 实例和版本。 |
+
+## 连接设置
+
+常见本机安装使用默认设置即可。自定义实例通过 `EVERYTHING_INSTANCE` 指定；设置 `EVERYTHING_URL` 后会连接指定的 Everything HTTP 服务。需要认证时，使用 `EVERYTHING_USERNAME` 和 `EVERYTHING_PASSWORD` 提供账号密码。
+
+<details>
+<summary>全部环境变量</summary>
+
+| 环境变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `EVERYTHING_INSTANCE` | 自动探测 | 自动探测默认实例、`1.5a` 和 `1.5`。自定义实例通过此项指定；`""` 选择默认实例。 |
+| `EVERYTHING_URL` | `""` | Everything HTTP 服务地址（例如 `http://127.0.0.1:17603/`）。设置后优先使用 HTTP 通道。 |
+| `EVERYTHING_USERNAME` | `""` | HTTP 服务的基础认证用户名。 |
+| `EVERYTHING_PASSWORD` | `""` | HTTP 服务的基础认证密码。 |
+| `EVERYTHING_MAX_RESULTS` | `1000` | 每项查询及整批查询的总行数上限（1–1000）。 |
+| `EVERYTHING_OUTPUT_BYTES` | `16384` | 单次工具调用的输出字节上限预算（4096–65536）。 |
+| `EVERYTHING_TIMEOUT_MS` | `15000` | 查询超时毫秒数（100–120000）。 |
+| `EVERYTHING_ES_PATH` | 内置路径 | 自定义 `es.exe` 可执行文件路径。 |
+
+</details>
+
+## 命令行与连接诊断
+
+检查当前环境中的 Everything 连接状态：
+
+```powershell
+npx -y everything-mcp-server doctor
+```
+
+直接在命令行运行查询：
+
+```powershell
+npx -y everything-mcp-server search '{"requests": [{"query": "ext:pdf", "count": 5}]}'
+```
+
+---
+
+## 工具参考
+
+<details>
+<summary>参数与结果格式</summary>
+
+### `search`
+
+搜索文件/目录、浏览文件夹、统计数量及获取元数据。
+
+通过必填的 `requests` 数组提交 1–8 项查询：
+
+```json
+{"requests": [{"query": "ext:pdf", "count": 5}]}
+```
+
+**每项查询的参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `query` | string | `""` | Everything 查询语句（如 `*.pdf`、`size:>100mb`、`ext:ts;js`）。 |
+| `root` | string | 可选 | 检索根目录绝对路径（如 `D:/Projects`）。省略则检索所有已索引驱动器。 |
+| `recursive` | boolean | `true` | 指定 `root` 时生效：`true` 搜索所有子孙项；`false` 仅列出直接子项。 |
+| `kind` | string | `"any"` | 筛选类型：`"any"`、`"file"` 或 `"folder"`。 |
+| `regex` | boolean | `false` | 将 `query` 作为正则表达式处理。 |
+| `count` | number | `20` | 最大返回行数（上限 1000）。设为 `0` 可统计数量；配合 `kind:"file"` 和 `fields:["size"]` 可取得总字节数 `total_size_bytes`。 |
+| `offset` | number | `0` | 分页偏移量（基于 0）。 |
+| `sort` | string | `"path"` | 排序字段：`path`、`name`、`size`、`extension`、`date_modified`、`date_created`、`date_accessed`、`attributes`、`run_count`。 |
+| `ascending` | boolean | `true` | 是否升序（`true` 为升序，`false` 为降序）。 |
+| `fields` | string[] | `[]` | 额外获取的元数据列：`size`、`date_modified`、`date_created`、`date_accessed`、`attributes`、`run_count`。 |
+
+IPC 提供上述全部字段与排序。HTTP 支持按名称、路径、大小和修改时间排序，提供大小和修改时间字段，其他元数据取决于所选服务。
+
+**输出格式：**
+
+输出先列出列名，再逐行返回数据：
+
+```json
+{
+  "results": [
+    {
+      "base": "D:/Projects",
+      "total": 42,
+      "next_offset": 2,
+      "columns": ["path", "type", "size_bytes"],
+      "rows": [
+        ["src/index.ts", "file", 1024],
+        ["package.json", "file", 512]
+      ],
+      "size_basis": "indexed_logical"
+    }
+  ]
+}
+```
+将 `base` 与 `rows` 中的相对路径拼接即可得到完整路径。
+文件与文件夹大小采用 Everything 索引中的逻辑字节数。
+
+### `status`
+
+检查 Everything 连接状态、运行实例、版本及索引就绪情况。
+
+**参数说明：**
+
+- `verbose`（boolean，默认 `false`）：包含已索引条目总数与当前限制配置。
+
+</details>
+
+## 本地开发
+
+```powershell
+git clone https://github.com/EcRal5t/everything-search-mcp.git
+cd everything-search-mcp
+npm install
+npm test
+```
+
+使用本地源码配置 MCP 客户端：
+
+```json
+{
+  "mcpServers": {
+    "everything": {
+      "command": "node",
+      "args": ["D:/path/to/everything-search-mcp/src/cli.js"]
+    }
+  }
+}
+```
+
+## 许可证
+
+MIT 许可证。内置的 `es.exe` 工具同样由 voidtools 采用 MIT 许可证分发。详情参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third party notices
+
+The package bundles unmodified ES 1.1.0.38 executables for Windows x64, x86, ARM64 and ARM from voidtools.
+
+- Source: https://github.com/voidtools/ES/tree/1.1.0.38
+- License: MIT, preserved in vendor/es/LICENSE.
+- Download URLs and SHA-256 hashes: vendor/es/manifest.json. These hashes identify the downloaded artifacts; they are not upstream signatures.
+
+Everything itself is not bundled. It must be installed and its client must be running. This project is independent of voidtools.

package/examples/c-drive-folders.json

@@ -0,0 +1,11 @@
+{
+  "requests": [
+    {
+      "root": "C:\\",
+      "recursive": false,
+      "kind": "folder",
+      "count": 20,
+      "fields": ["size"]
+    }
+  ]
+}

package/examples/c-drive-largest.json

@@ -0,0 +1,15 @@
+{
+  "requests": [
+    {
+      "root": "C:\\",
+      "kind": "file",
+      "sort": "size",
+      "ascending": false,
+      "count": 20,
+      "fields": [
+        "size",
+        "date_modified"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "everything-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Fast Windows file search MCP server powered by Everything",
+  "mcpName": "io.github.EcRal5t/everything-search-mcp",
+  "author": "EcRal5t",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EcRal5t/everything-search-mcp.git"
+  },
+  "homepage": "https://github.com/EcRal5t/everything-search-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/EcRal5t/everything-search-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "everything",
+    "file-search",
+    "windows",
+    "voidtools"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "cli": "node src/cli.js",
+    "test": "node --test test/*.test.js",
+    "test:live": "node scripts/verify-live.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "4.6.7"
+  },
+  "license": "MIT",
+  "bin": {
+    "everything-mcp-server": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "vendor/es/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "examples/"
+  ]
+}