火水文件搜索
一个桌面扩展（DXT），利用原生功能为macOS提供快速文件搜索能力 mdfind 命令（Spotlight 搜索）。
⚠️ 重要此扩展仅适用于macOS系统。Windows和Linux系统不受支持。
特点/特性
- 使用 macOS Spotlight 索引快速搜索文件
- 多种过滤选项：
- 基于路径的搜索限制 - 区分大小写/不区分大小写的搜索 - 正则表达式匹配 - 按名称、大小或日期排序结果
- 可配置的搜索限制
- 结构清晰的JSON格式响应
- 采用FastMCP框架构建，以实现最佳性能
安装
来自MCP注册表（推荐）
此服务器可在模型上下文协议注册表中找到。请使用您的MCP客户端进行安装。
mcp-name: io.github.huoshuiai42/huoshui-file-search 翻译为中文是：模块名称（或组件名称）：io.github.huoshuiai42/huoshui-file-search（注：这里的“mcp-name”可能是一个特定上下文中的术语，通常可理解为模块名称或组件名称，但具体含义需根据上下文确定。在中文中，我们通常直接翻译其后的内容，即模块或组件的具体名称。）
通过 PyPI（推荐）
uvx huoshui-file-search来自来源
git clone https://github.com/huoshui/huoshui-file-search.git
cd huoshui-file-search
uv sync使用方法
作为桌面扩展（DXT）
- 通过您的DXT兼容应用程序（例如，Claude Desktop）安装扩展
- 该扩展将自动配置并准备好使用
- 使用
search_files具有各种参数的工具
直接使用
from server.main import search_files, FileSearchParams
# Basic search
params = FileSearchParams(query="report.pdf")
result = await search_files(None, params)
# Search with filters
params = FileSearchParams(
query="*.py",
path="/Users/username/Documents",
case_sensitive=True,
sort_by="size",
limit=50
)
result = await search_files(None, params)工具参数
query（必填）：搜索查询字符串path（可选）：用于限制搜索范围的目录case_sensitive（可选）：启用大小写敏感搜索（默认：false）regex（可选）：使用正则表达式模式按文件名过滤结果sort_by（可选）：按“名称”、“大小”或“日期”排序结果limit（可选）：最大结果数量（默认：100，最大：1000）
mdfind 查询语法
该 query 参数使用 macOS Spotlight 的 mdfind 语法：
- 简单文本搜索：
report- 查找包含“report”的文件 - 文件类型：
kind:pdf，kind:image，kind:movie - 文件名搜索:
kMDItemFSName == "*.py"- 查找Python文件 - 组合查询:
invoice AND kind:pdf- 查找包含“发票”的PDF文件 - 日期查询：
date:today，modified:this week
注如果你的查询像 '寻找工程车' kind:movie 未返回结果，可能意味着：
- 没有文件同时满足这两个条件
- 语法需要调整（试试
寻找工程车 AND kind:movie) - Spotlight 尚未对这些文件进行索引
示例
基本文件搜索
{
"query": "document.pdf"
}在特定目录中搜索
{
"query": "*.txt",
"path": "/Users/username/Documents"
}区分大小写的搜索
{
"query": "README",
"case_sensitive": true
}使用正则表达式过滤器进行搜索
{
"query": "kind:text",
"regex": "log.*2024.*\\.txt$"
}排序后的有限结果
{
"query": "*.jpg",
"sort_by": "size",
"limit": 20
}配置
该扩展支持通过DXT清单进行用户配置：
allowed_directories限制搜索范围的目录列表default_limit默认的最大搜索结果数量enable_logging启用调试日志记录
发展
项目结构
huoshui-file-search/
├── manifest.json # DXT manifest file
├── server/ # MCP server implementation
│ ├── __init__.py
│ ├── __main__.py
│ └── main.py
├── pyproject.toml # Python package configuration
├── requirements.txt # Python dependencies
├── LICENSE # MIT License
└── README.md # This file本地测试
- 安装依赖项：
uv sync- 运行服务器：
uv run python -m server或者在发布到PyPI之后：
uvx huoshui-file-search- 服务器将根据MCP协议通过标准I/O进行通信
发布到PyPI（Python Package Index）
- 构建包：
uv build- 上传到PyPI：
uv publish系统要求
- macOS 10.15 或更高版本
- Python 3.10 或更高版本
- UV 包管理器（通过以下方式安装：
curl -LsSf https://astral.sh/uv/install.sh | sh) - 已启用Spotlight索引功能
故障排除
“平台不受支持”错误
这个扩展程序仅适用于 macOS。请确保您在 Mac 上运行它。
“mdfind 命令未找到”错误
确保您的Mac上已启用Spotlight。您可以在“系统偏好设置”>“Spotlight”中检查此设置。
没有找到搜索结果
- Spotlight 可能仍在索引新文件
- 检查文件路径是否包含在Spotlight的搜索范围内
- 验证搜索查询语法
搜索超时
大型搜索可能会在30秒后超时。请尝试：
- 限制搜索路径
- 使用更具体的查询
- 减少结果限制
许可证
MIT 许可证 - 详情请参见 LICENSE 文件
贡献；做出贡献
欢迎投稿！请：
- 为仓库创建分支副本
- 创建一个特性分支
- 为新功能添加测试
- 提交一个拉取请求
支持
如需了解问题和功能请求，请访问： https://github.com/huoshui/huoshui-file-search/issues 翻译为中文是：“https://github.com/huoshui/huoshui文件搜索/issues”（注：在实际中文语境中，网址通常不翻译，此处仅为说明翻译方式，实际使用时网址保持原样）。不过，更自然的表达可能是直接说“这是GitHub上huoshui/huoshui-file-search项目的issues页面”