# Everything MCP

> 基于 Voidtools Everything 的极速文件搜索 MCP 服务器
> Ultra-lightweight MCP server for Voidtools Everything search engine

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 📖 简介 | Introduction

**Everything MCP** 是一个极轻量的 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，将 Voidtools Everything 的极速文件搜索能力暴露给 AI 代理（Claude Code、Codex、DeepSeek Harness 等）。

通过调用 `Everything.exe -create-file-list` 导出搜索结果并解析 EFU 格式，实现毫秒级文件检索。

**English:** Everything MCP is an ultra-lightweight MCP server that exposes Voidtools Everything's blazing-fast file search to AI agents (Claude Code, Codex, DeepSeek Harness, etc.). It uses `Everything.exe -create-file-list` to export search results and parses the EFU format.

---

## ✨ 特性 | Features

- ⚡ **极速搜索** — 基于 Everything 的 NTFS 索引，毫秒级检索百万文件
- 🪶 **极致轻量** — 单文件 5KB，零冗余代码，秒级启动
- 🔧 **零配置集成** — 自动适配 Claude Code、Codex、DSH
- 🎯 **智能触发** — 配置 CLAUDE.md 让 AI 自动识别何时调用
- 🪟 **原生 Windows** — 完美适配 Windows NTFS 文件系统

**English:**
- ⚡ **Blazing fast** — Leverages Everything's NTFS index for millisecond search across millions of files
- 🪶 **Ultra lightweight** — Single 5KB file, zero bloat, instant startup
- 🔧 **Zero-config integration** — Auto-adapts to Claude Code, Codex, DSH
- 🎯 **Smart triggering** — CLAUDE.md configures AI to auto-select when to search
- 🪟 **Native Windows** — Perfectly optimized for Windows NTFS

---

## 📋 前提条件 | Prerequisites

- **Windows** 操作系统 (需要 NTFS 文件系统)
- [**Everything**](https://www.voidtools.com/) v1.4+ 已安装并**以管理员权限运行**
- **Node.js** v18+（测试环境 v24）
- **npm**（用于安装依赖）

> 💡 Everything 需要管理员权限以读取 NTFS 索引。可在 Everything → 工具 → 选项 → 常规中勾选"以管理员身份运行"，或安装 Everything 服务。

**English:**
- **Windows** OS (requires NTFS filesystem)
- [**Everything**](https://www.voidtools.com/) v1.4+ installed and **running as administrator**
- **Node.js** v18+ (tested with v24)
- **npm** (for dependency installation)

> 💡 Everything needs admin privileges to read the NTFS index. Check "Run as administrator" in Everything → Tools → Options → General, or install the Everything service.

---

## 🚀 安装 | Installation

```bash
# 克隆仓库 | Clone the repository
git clone https://github.com/ixijxjgxidj-cmd/everything-MCP.git
cd everything-MCP

# 安装依赖 | Install dependencies
npm install

# 启动测试 | Quick test
node src/index.js
# 输出: everything-mcp ready
```

---

## 🔌 配置 | Configuration

### Claude Code (全局 | Global)

自动配置已在 `~/.claude/settings.json` 中添加。手动配置：

```json
{
  "mcpServers": {
    "everything": {
      "command": "node",
      "args": ["C:/Users/hulk cheng/Desktop/公司/everything-mcp-server/src/index.js"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Codex CLI

项目级配置在 `.codex/config.json` 中，或手动添加：

```json
{
  "mcpServers": {
    "everything": {
      "command": "node",
      "args": ["C:/Users/hulk cheng/Desktop/公司/everything-mcp-server/src/index.js"]
    }
  }
}
```

### DeepSeek Harness (DSH)

在 DSH 的插件配置中添加：

```yaml
plugins:
  mcp-client:
    servers:
      everything:
        transport: stdio
        command: node
        args:
          - "C:/Users/hulk cheng/Desktop/公司/everything-mcp-server/src/index.js"
        cwd: "C:/Users/hulk cheng/Desktop/公司/everything-mcp-server"
```

---

## 🛠️ 工具 | Tools

| 工具 | 描述 | 参数 |
|------|------|------|
| `everything_search` | 搜索文件 | `query` (必填), `path`, `maxResults` |
| `everything_count` | 统计文件数 | `query` (必填), `path` |
| `everything_health` | 检查服务状态 | 无 |

### 示例 | Examples

```
# 搜索文件 | Search for files
everything_search(query: "node.exe", maxResults: 10)

# 限定路径搜索 | Search within a specific path
everything_search(query: "*.pdf", path: "C:\\Users\\hulk cheng\\Desktop")

# 统计文件 | Count files
everything_count(query: "*.py")

# 检查状态 | Health check
everything_health()
```

---

## 📁 项目结构 | Project Structure

```
everything-MCP/
├── src/
│   └── index.js          # MCP 服务器 (单文件, 5KB)
│                          # MCP server (single file, 5KB)
├── .claude/
│   └── settings.json     # Claude Code 项目配置
├── .codex/
│   └── config.json       # Codex 配置
├── CLAUDE.md             # 自动触发规则
├── package.json
└── README.md
```

---

## ⚙️ 工作原理 | How It Works

```
AI Agent (Claude Code/Codex/DSH)
        │
        │ MCP Protocol (JSON-RPC over stdio)
        ▼
┌─────────────────────────────────┐
│   everything-mcp (index.js)     │
│                                 │
│   tools/list  ← 注册 3 个工具   │
│   tools/call  ← 处理搜索请求    │
└────────────────┬────────────────┘
                 │
                 │ spawn Everything.exe -create-file-list
                 ▼
┌─────────────────────────────────┐
│   Everything (NTFS 搜索引擎)     │
│   毫秒级检索百万文件              │
└─────────────────────────────────┘
                 │
                 │ EFU (CSV) 格式导出
                 ▼
┌─────────────────────────────────┐
│   解析 -> JSON -> 返回给 AI      │
└─────────────────────────────────┘
```

---

## ❓ 故障排除 | Troubleshooting

### 搜索返回 0 条结果

1. 确保 Everything 正在运行（系统托盘中有图标）
2. 确保 Everything 以管理员权限运行
3. 或安装 Everything 服务：Everything → 工具 → 选项 → 常规 → 安装服务
4. 首次使用时调 `everything_health` 检查状态

### 服务启动失败

1. 检查 `C:\\Program Files\\Everything\\Everything.exe` 是否存在
2. 确保 Node.js 版本 >= 18
3. 重新运行 `npm install`

**English:**
### Search returns 0 results

1. Make sure Everything is running (check system tray)
2. Run Everything as administrator
3. Or install the Everything service: Everything → Tools → Options → General → Install Service
4. Call `everything_health` first to check status

### Server fails to start

1. Verify `C:\\Program Files\\Everything\\Everything.exe` exists
2. Ensure Node.js >= 18
3. Re-run `npm install`

---

## 📄 许可证 | License

[MIT](LICENSE)

---

## 🙏 致谢 | Acknowledgments

- [Voidtools Everything](https://www.voidtools.com/) — 极致的 Windows 文件搜索引擎
- [Model Context Protocol](https://modelcontextprotocol.io/) — AI 工具协议标准