Everything Search MCP

一切搜索MCP服务器

一个模型上下文协议（MCP）服务器，用于使用Everything（Windows）进行快速文件搜索，并为macOS（Spotlight）和Linux（ripgrep/locate）提供跨平台回退。

特性

搜索功能

• 视窗：Everything CLI集成（es.exe）

- 快速索引文件搜索 - 通配符、运算符（AND、OR、NOT） - 正则表达式支持 - 按名称、大小、日期等排序。 - 文件元数据检索 - npm安装时自动下载e.exe

• macOS：通过mdfind集成聚光灯

- 原生macOS搜索 - 文件和文件夹搜索 - Spotlight查询语法

• Linux：ripgrep和查找支持

- 使用ripgrep快速搜索（首选） - 回退以定位 - 模式匹配和正则表达式

安全特性

• 输入验证：所有用户输入都经过验证和消毒
• 命令注入保护：从查询中删除Shell元字符
• 路径横向保护：防止访问预期目录之外的内容
• 资源限制：内置超时和缓冲区大小限制
• 错误处理：安全错误消息，无信息泄露
• 类型安全：严格的TypeScript类型防止运行时错误

安装

安装MCP服务器

npm install -g everything-search-mcp

或者为了当地发展：

npm install
npm run build
npm link

平台特定设置

windows用户

自动设置（推荐）

在npm安装过程中会自动下载.exe CLI工具：

• 支持x64、x86和ARM64架构
• 从GitHub下载最新稳定版本
• 无需手动安装
• .exe存储在本地包目录中

自动下载：

1. 检测您的系统体系结构（x64/x86/ARM64）
2. 从voidtools/ES版本下载相应的ES zip文件
3. 将.exe解压缩到本地bin目录
4. 清理zip文件

手动设置（可选）

如果你想要完整的Everything应用程序来提供其他功能：

1. 从安装所有内容 voidtools.com
2. 确保一切正常运行
3. 启用“以管理员身份运行”以获得最佳结果

备注：MCP服务器仅与.exe CLI工具配合使用。安装完整的Everything应用程序是可选的。

macOS用户

无需额外安装-Spotlight内置于macOS中。

Linux用户

安装ripgrep以获得最佳性能：

sudo apt install ripgrep  # Ubuntu/Debian
sudo dnf install ripgrep  # Fedora
sudo pacman -S ripgrep    # Arch Linux

或者使用locate（较慢）：

sudo apt install mlocate  # Ubuntu/Debian
sudo dnf install mlocate  # Fedora
sudo pacman -S mlocate    # Arch Linux

配置

Claude桌面配置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "everything-search": {
      "command": "everything-search-mcp",
      "args": []
    }
  }
}

高级配置

MCP服务器使用标准配置，不需要额外的环境变量。在Windows上，在npm安装过程中会自动下载.exe。在Linux上，确保ripgrep/locate已安装并可在系统PATH中访问。

用法

搜索文件

基本搜索：

{
  "name": "search_files",
  "arguments": {
    "query": "*.txt"
  }
}

具有排序和选项的高级搜索：

{
  "name": "search_files",
  "arguments": {
    "query": "invoice AND (pdf OR docx)",
    "maxResults": 50,
    "sortBy": "date_modified",
    "sortOrder": "descending",
    "matchPath": true,
    "regex": false
  }
}

获取文件信息

{
  "name": "get_file_info",
  "arguments": {
    "path": "C:\\Documents\\report.pdf"
  }
}

检查状态

{
  "name": "check_status",
  "arguments": {}
}

工具参考

搜索文件

使用平台的搜索引擎搜索文件和文件夹。

参数：

验证：

• 空查询被拒绝
• 超过1000个字符的查询被拒绝
• Shell元字符会自动删除
• 路径遍历尝试被阻止

答复：

{
  "success": true,
  "count": 5,
  "results": [
    {
      "name": "document.txt",
      "path": "C:\\Documents",
      "fullPath": "C:\\Documents\\document.txt",
      "size": 1024,
      "modified": "2024-01-20T10:30:00.000Z",
      "created": "2024-01-15T08:00:00.000Z",
      "extension": "txt",
      "isFolder": false,
      "isFile": true
    }
  ]
}

获取_文件_信息

获取特定文件或文件夹的详细元数据。

参数：

验证：

• 空路径被拒绝
• 超过4096个字符的路径被拒绝
• 路径遍历尝试被阻止
• 外壳元字符被拒绝

答复：

{
  "success": true,
  "info": {
    "name": "document.txt",
    "path": "C:\\Documents",
    "size": 1024,
    "created": "2024-01-15T08:00:00.000Z",
    "modified": "2024-01-20T10:30:00.000Z",
    "accessed": "2024-01-20T10:30:00.000Z",
    "attributes": 32,
    "extension": "txt",
    "isFolder": false,
    "isFile": true
  }
}

check_status

检查搜索引擎和平台的状态。

参数： 无

答复：

{
  "success": true,
  "status": {
    "platform": "windows",
    "searchEngine": "Everything (es.exe CLI)",
    "available": true,
    "version": "1.1.0.36",
    "message": "Everything command-line interface available"
  }
}

平台特定功能

Windows（一切）

自动下载.exe：

在...期间 npm install，包裹自动：

1. 检测系统架构（x64、x86或ARM64）
2. 从GitHub下载最新的ES版本
3. 将.exe解压缩到本地bin目录
4. 将.exe存储在包旁边

这消除了手动安装Everything或配置.exe的需要。

查询运算符：

• AND -两个术语必须匹配
• OR -任何一个术语都可以匹配
• NOT -排除术语
• "" -精确短语
• * -多个字符的通配符
• ? -单个字符的通配符

示例：

• *.txt -所有.txt文件
• invoice AND pdf -包含“发票”和“pdf”的文件
• report NOT draft -带有“报告”而非“草稿”的文件
• "my document".pdf -扩展名为.pdf的精确短语

macOS（聚光灯）

查询语法：

• 基本文本搜索
• kind:pdf -文件类型筛选器
• date:today -日期筛选器
• name:document -姓名搜索

示例：

• document -搜索“文档”
• kind:pdf document -带有“文档”的PDF文件
• date:today -今天修改

Linux（ripgrep/locate）

查询语法：

• 基本图案匹配
• 支持正则表达式
• 默认情况下不区分大小写

示例：

• document -搜索“文档”
• \.txt$ -.txt文件的正则表达式
• invoice.*pdf -正则表达式模式

安全

概述

此MCP服务器实施了全面的安全措施，以防止常见漏洞：

• 命令注入保护：所有用户输入都经过净化，以删除shell元字符(;, &, |, $, (, ), ` `, ~`)
• 路径横向保护：检测和阻止 .. 序列和主目录访问(~)
• 输入验证：严格验证查询长度（最多1000个字符）、路径长度（最多4096个字符）和参数边界
• 资源限制：命令超时（30秒）和缓冲区大小限制（50MB）可防止DoS攻击
• 错误处理：不会泄露系统信息的安全错误消息
• 类型安全：TypeScript严格模式可防止与类型相关的漏洞

安全性测试

所有安全措施都经过44次自动化测试验证：

• 22安全测试：输入验证、净化和保护机制
• 22集成测试：真实世界的攻击场景和边缘案例

有关详细的测试结果，请参阅 TEST_RESULTS.md.

最佳实践

使用此MCP服务器时：

1. 使用特定查询：将搜索范围缩小到特定的文件模式，而不是通配符
2. 设定合理的限制：保持 maxResults 典型用例低于100
3. 验证结果：在访问文件之前，始终验证文件路径
4. 监控日志：检查服务器日志中的验证错误和安全警告

故障排除

视窗

错误：“找不到.exe”

在npm安装过程中，应自动下载.exe CLI工具。如果您看到此错误：

1. 手动运行下载脚本：

   node node_modules/everything-search-mcp/scripts/download-es.js

1. 检查您是否可以从GitHub下载互联网连接
2. 验证npm安装成功完成
3. 尝试重新安装软件包：

   npm uninstall everything-search-mcp
   npm install -g everything-search-mcp

npm安装过程中下载失败

如果自动下载失败：

1. 检查您的互联网连接
2. 确保GitHub可以从您的网络访问
3. 从手动下载.exehttps://github.com/voidtools/ES/releases
4. 将.exe放入包的 bin/ 目录

搜索未返回任何结果

1. 确保所有内容（完整应用程序）都在运行，并且有索引文件
2. 运行Everything并让它完成索引
3. 检查文件路径是否可访问
4. 尝试更广泛的搜索查询

macOS

错误：“找不到mdfind命令”

• 这不应该发生，因为mdfind内置于macOS中
• 检查Spotlight是否在系统设置中启用

Linux

错误：“未找到ripgrep或locate”

• 安装ripgrep以获得最佳性能：

  sudo apt install ripgrep

• 或者安装locate作为回退：

  sudo apt install mlocate
  sudo updatedb

发展

建筑

npm run build

在发展中奔跑

npm run dev

测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- tests/security.test.ts
npm test -- tests/integration.test.ts

测试覆盖范围：

• 44个自动化测试，涵盖安全、验证和边缘案例
• 看 TEST_RESULTS.md 查看详细的测试结果
• 看 手册_测试_GUIDE.md 用于手动测试程序

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。

致谢

• 通过voidtools.com搜索所有内容
• 基于Anthropic的模型上下文协议