huoshui-file-search

Huoshui File Search

一款 Desktop Extension（DXT），使用 macOS 原生的 mdfind 命令（Spotlight 搜索）提供快速文件搜索功能。

⚠️ 重要提示：此扩展仅适用于 macOS 系统，不支持 Windows 和 Linux。

功能

• 使用 macOS Spotlight 索引快速搜索文件
• 多种筛选选项：
  • 按路径限制搜索范围
  • 区分大小写或不区分大小写搜索
  • 正则表达式匹配
  • 按名称、大小或日期排序结果
• 可配置搜索上限
• 清晰的 JSON 结构化响应
• 使用 FastMCP 框架构建，性能出色

安装

从 MCP Registry 安装（推荐）

此服务已列入 Model Context Protocol Registry。使用你的 MCP 客户端进行安装。

mcp-name: io.github.huoshuiai42/huoshui-file-search

通过 PyPI 安装（推荐）

uvx huoshui-file-search

从源代码安装

git clone https://github.com/huoshui/huoshui-file-search.git
cd huoshui-file-search
uv sync

使用方法

作为 Desktop Extension（DXT）使用

1. 通过兼容 DXT 的应用（例如 Claude Desktop）安装此扩展
2. 扩展将自动完成配置并可供使用
3. 使用 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（可选）：按 'name'、'size' 或 'date' 对结果排序
• limit（可选）：结果数量上限（默认值：100，最大值：1000）

mdfind 查询语法

query 参数使用 macOS Spotlight 的 mdfind 语法：

• 简单文本搜索：report - 查找包含“report”的文件
• 文件类型：kind:pdf、kind:image、kind:movie
• 文件名搜索：kMDItemFSName == "*.py" - 查找 Python 文件
• 组合查询：invoice AND kind:pdf - 查找包含“invoice”的 PDF 文件
• 日期查询：date:today、modified:this week

注意：如果查询 '寻找工程车' kind:movie 没有返回结果，可能是因为：

1. 没有文件同时符合这两个条件
2. 语法需要调整（尝试 寻找工程车 AND kind:movie）
3. 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

本地测试

1. 安装依赖：

   uv sync
   

2. 运行服务：

   uv run python -m server
   

   或者，在发布到 PyPI 后：

   uvx huoshui-file-search
   

3. 服务将根据 MCP 协议通过 stdio 进行通信

发布到 PyPI

1. 构建软件包：

   uv build
   

2. 上传到 PyPI：

   uv publish
   

系统要求

• macOS 10.15 或更高版本
• Python 3.10 或更高版本
• uv 包管理器（使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装）
• 已启用 Spotlight 索引

故障排除

“Platform not supported” 错误

此扩展仅适用于 macOS。请确保在 Mac 上运行。

“mdfind command not found” 错误

请确保 Mac 上已启用 Spotlight。可在“系统偏好设置”>“Spotlight”中检查。

没有搜索结果

• Spotlight 可能仍在为新文件建立索引
• 检查文件路径是否包含在 Spotlight 的搜索范围内
• 检查搜索查询语法

搜索超时

大型搜索可能会在 30 秒后超时。请尝试：

• 限制搜索路径
• 使用更具体的查询
• 降低结果数量上限

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

参与贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

支持

如需反馈问题或提出功能请求，请访问： https://github.com/huoshui/huoshui-file-search/issues