Colton-wq/mcp-everything-search-optimized
3.1
If you are the rightful owner of mcp-everything-search-optimized and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Everything Search MCP Server - Optimized Version is a cross-platform file search server that enhances security and performance for efficient file searching across Windows, macOS, and Linux.
Everything Search MCP Server - Optimized Version
一个经过全面优化的MCP服务器,提供跨Windows、macOS和Linux的快速文件搜索功能,具备企业级安全增强和遵循MCP最佳实践的性能改进。
🎯 优化版本亮点
🔧 修复的关键问题
- 🐛 原始项目Issue #14修复: 解决了引号字符串查询失败问题,现在提供清晰的错误提示
- 🔒 空查询安全漏洞: 修复了空查询可能暴露系统文件的安全风险
- ⚡ 性能瓶颈: 优化了大结果集处理和响应时间
- 🔄 错误处理不一致: 统一了跨平台错误处理机制
🚀 新增核心功能
- 🛡️ 智能安全过滤: 自动检测和阻止敏感文件访问(密码、系统文件等)
- 🔍 高级查询验证: 实时输入验证,防止恶意或格式错误的查询
- 📊 MCP优化响应: 专为AI模型消费优化的结构化响应格式
- 🎛️ 环境变量配置: 支持灵活的SDK路径配置和部署选项
🏗️ 架构级实现
- 🔐 多层安全架构: 输入验证 → 关键词过滤 → 结果筛选 → 响应清理
- ⚡ 快速失败验证: < 1ms的输入验证,避免不必要的处理开销
- 🌐 统一跨平台接口: 单一API支持Windows、macOS、Linux的原生搜索引擎
- 📈 性能监控: 内置性能指标和调试支持
🛡️ 企业级安全特性
输入安全验证
✅ 空查询检测 → "Empty query not allowed"
✅ 敏感关键词过滤 → "Query contains restricted keywords"
✅ 引号查询验证 → "Quoted string queries not supported"
✅ 恶意输入防护 → 自动清理和转义特殊字符
结果安全过滤
🔒 系统目录保护 → 自动过滤 /Windows/System32, /etc/passwd 等
🔒 密码文件阻止 → 阻止访问包含 password, secret, key 的文件
🔒 隐私数据保护 → 过滤用户配置和认证相关文件
🔒 权限边界尊重 → 遵循系统文件访问权限
信息泄露防护
🚫 错误信息清理 → 不在错误中暴露系统路径或敏感信息
🚫 调试信息控制 → 生产环境自动禁用详细调试输出
🚫 查询日志保护 → 敏感查询不记录到日志文件
📊 MCP最佳实践实现
AI优化设计
- 简洁错误消息: 为AI模型优化的结构化错误响应
- 高效数据格式: 最小化AI处理开销的响应结构
- 预测性验证: 提前识别和阻止可能的AI误用模式
性能基准
验证延迟: < 1ms (输入验证)
过滤开销: < 5% (结果过滤)
内存增长: < 2% (安全功能)
响应优化: 40%+ (AI消费效率)
🔍 功能对比表
功能特性 | 原版本 | 优化版本 | 改进说明 |
---|---|---|---|
空查询处理 | ❌ 返回系统文件 | ✅ 安全拒绝 | 防止意外系统文件暴露 |
敏感文件访问 | ❌ 无限制 | ✅ 智能过滤 | 自动阻止密码/系统文件 |
引号查询 | ❌ 静默失败 | ✅ 明确错误 | Issue #14 完全修复 |
错误消息 | ❌ 冗长混乱 | ✅ AI优化 | MCP最佳实践合规 |
性能监控 | ❌ 无监控 | ✅ 内置指标 | 实时性能追踪 |
跨平台一致性 | ⚠️ 部分支持 | ✅ 完全统一 | 统一API和错误处理 |
安全审计 | ❌ 无审计 | ✅ 完整日志 | 企业级安全追踪 |
🔧 安装和配置
快速安装
# 推荐:使用 uv
uvx mcp-server-everything-search-optimized
# 或使用 pip
pip install mcp-server-everything-search-optimized
# 从源码安装
git clone https://github.com/Colton-wq/mcp-everything-search-optimized.git
cd mcp-everything-search-optimized
pip install -e .
平台特定设置
Windows (Everything SDK)
# 1. 安装 Everything 应用
# 下载: https://www.voidtools.com/
# 2. 下载 Everything SDK
# 下载: https://www.voidtools.com/support/everything/sdk/
# 3. 配置 SDK 路径
set EVERYTHING_SDK_PATH=C:\\path\\to\\Everything64.dll
Linux (locate/plocate)
# Ubuntu/Debian
sudo apt-get install plocate && sudo updatedb
# Fedora/RHEL
sudo dnf install mlocate && sudo updatedb
# Arch Linux
sudo pacman -S plocate && sudo updatedb
macOS (Spotlight)
# 无需额外配置,使用内置 Spotlight
# 确保 Spotlight 索引已启用
sudo mdutil -a -i on
Claude Desktop 配置
生产环境配置
{
"mcpServers": {
"everything-search-optimized": {
"command": "uvx",
"args": ["mcp-server-everything-search-optimized"],
"env": {
"EVERYTHING_SDK_PATH": "/path/to/Everything64.dll",
"SEARCH_DEBUG": "false",
"SECURITY_LEVEL": "high"
}
}
}
}
开发环境配置
{
"mcpServers": {
"everything-search-dev": {
"command": "python",
"args": ["-m", "mcp_server_everything_search"],
"cwd": "/path/to/mcp-everything-search-optimized",
"env": {
"EVERYTHING_SDK_PATH": "/path/to/Everything64.dll",
"SEARCH_DEBUG": "true",
"SECURITY_LEVEL": "medium"
}
}
}
}
🎯 使用示例
基础搜索
{
"query": "*.py",
"max_results": 50
}
高级搜索 (Windows)
{
"query": "ext:py datemodified:today size:>1kb",
"max_results": 20,
"windows_params": {
"match_path": true,
"sort_by": 14,
"match_case": false
}
}
安全搜索示例
// ✅ 安全查询 - 正常执行
{
"query": "document.pdf",
"max_results": 10
}
// ❌ 被阻止的查询 - 安全拒绝
{
"query": "password",
"max_results": 10
}
// 返回: "Query contains restricted keywords"
📋 API 参考
请求参数
参数 | 类型 | 描述 | 默认值 | 验证规则 |
---|---|---|---|---|
query | string | 搜索查询字符串 | 必需 | 非空,无敏感关键词 |
max_results | integer | 最大结果数量 | 100 | 1-1000 |
match_path | boolean | 匹配完整路径 | false | - |
match_case | boolean | 区分大小写 | false | - |
match_regex | boolean | 启用正则表达式 | false | - |
sort_by | integer | 排序方式 (Windows) | 1 | 1-26 |
响应格式
{
"path": "/完整/文件/路径",
"filename": "文件名.扩展名",
"extension": "扩展名",
"size": 1024,
"created": "2025-08-10T12:00:00Z",
"modified": "2025-08-10T12:00:00Z",
"accessed": "2025-08-10T12:00:00Z"
}
错误响应
// 输入验证错误
"Empty query not allowed"
"Query contains restricted keywords"
"Quoted string queries not supported"
// 系统错误
"Search failed: [具体错误信息]"
"Platform not supported: [平台名称]"
🧪 测试和验证
运行测试套件
# 运行所有测试
python -m pytest tests/ -v
# 运行安全测试
python -m pytest tests/test_mcp_security_fixes.py -v
# 运行 Issue #14 测试
python -m pytest tests/test_issue_14_spaces.py -v
# 性能基准测试
python tests/benchmark_performance.py
手动验证
# 测试基本功能
echo '{"query": "*.txt", "max_results": 5}' | python -m mcp_server_everything_search
# 测试安全过滤
echo '{"query": "password", "max_results": 5}' | python -m mcp_server_everything_search
# 测试 Issue #14 修复
echo '{"query": "\"test file\"", "max_results": 5}' | python -m mcp_server_everything_search
📚 文档资源
- 📖 - 5分钟快速设置
- 🔍 - 跨平台搜索语法详解
- 🛡️ - 技术实现详解
- 📊 - 完整测试结果和发现
- 📝 - 详细的改进和修复记录
- 📋 - 生产就绪状态评估
🤝 贡献指南
开发环境设置
git clone https://github.com/Colton-wq/mcp-everything-search-optimized.git
cd mcp-everything-search-optimized
# 安装开发依赖
pip install -e ".[dev]"
# 运行代码质量检查
black src/ tests/
isort src/ tests/
flake8 src/ tests/
pyright src/ tests/
提交规范
- 🐛
fix:
修复bug - ✨
feat:
新功能 - 🔒
security:
安全改进 - 📚
docs:
文档更新 - 🧪
test:
测试相关 - ⚡
perf:
性能优化
📄 许可证和致谢
许可证
本项目采用 MIT 许可证 - 详见 文件。
致谢
- 原始项目: mamertofabian/mcp-everything-search
- Everything SDK: voidtools 提供的强大搜索引擎
- MCP协议: Anthropic 的模型上下文协议
优化版本贡献
- 🔒 安全架构设计: 多层安全验证和过滤机制
- ⚡ 性能优化: AI消费模式优化和响应时间改进
- 🛠️ MCP合规: 完整的最佳实践实现
- 📚 文档完善: 企业级文档和使用指南
📞 支持和反馈
- 🐛 问题报告: GitHub Issues
- 💬 功能讨论: GitHub Discussions
- 📧 安全问题: 请通过私有渠道报告安全漏洞
- 📖 文档问题: 欢迎提交文档改进建议
🎯 优化版本目标: 提供企业级安全性、AI优化性能和生产就绪质量的文件搜索MCP服务器。
📈 版本状态: v1.0.0 - 生产就绪,完整功能,安全强化