Huoshui File Search
A Desktop Extension (DXT) that provides fast file search capabilities for macOS using the native mdfind command (Spotlight search).
⚠️ IMPORTANT: This extension only works on macOS systems. Windows and Linux are not supported.
Features
- Fast file search using macOS Spotlight index
- Multiple filtering options:
- Path-based search restrictions
- Case-sensitive/insensitive search
- Regular expression matching
- Sort results by name, size, or date
- Configurable search limits
- Clean JSON-structured responses
- Built with FastMCP framework for optimal performance
Installation
From MCP Registry (Recommended)
This server is available in the Model Context Protocol Registry. Install it using your MCP client.
mcp-name: io.github.huoshuiai42/huoshui-file-search
Via PyPI (Recommended)
uvx huoshui-file-search
From Source
git clone https://github.com/huoshui/huoshui-file-search.git
cd huoshui-file-search
uv sync
Usage
As a Desktop Extension (DXT)
- Install the extension via your DXT-compatible application (e.g., Claude Desktop)
- The extension will be automatically configured and ready to use
- Use the
search_filestool with various parameters
Direct Usage
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)
Tool Parameters
query(required): Search query stringpath(optional): Directory to limit search scopecase_sensitive(optional): Enable case-sensitive search (default: false)regex(optional): Regex pattern to filter results by filenamesort_by(optional): Sort results by 'name', 'size', or 'date'limit(optional): Maximum number of results (default: 100, max: 1000)
mdfind Query Syntax
The query parameter uses macOS Spotlight's mdfind syntax:
- Simple text search:
report- finds files containing "report" - File kind:
kind:pdf,kind:image,kind:movie - Filename search:
kMDItemFSName == "*.py"- finds Python files - Combined queries:
invoice AND kind:pdf- finds PDF files containing "invoice" - Date queries:
date:today,modified:this week
Note: If your query like '寻找工程车' kind:movie returns no results, it might mean:
- No files match both criteria
- The syntax needs adjustment (try
寻找工程车 AND kind:movie) - Spotlight hasn't indexed the files yet
Examples
Basic File Search
{
"query": "document.pdf"
}
Search in Specific Directory
{
"query": "*.txt",
"path": "/Users/username/Documents"
}
Case-Sensitive Search
{
"query": "README",
"case_sensitive": true
}
Search with Regex Filter
{
"query": "kind:text",
"regex": "log.*2024.*\\.txt$"
}
Sorted and Limited Results
{
"query": "*.jpg",
"sort_by": "size",
"limit": 20
}
Configuration
The extension supports user configuration through the DXT manifest:
allowed_directories: List of directories to limit search scopedefault_limit: Default maximum number of search resultsenable_logging: Enable debug logging
Development
Project Structure
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
Testing Locally
-
Install dependencies:
uv sync -
Run the server:
uv run python -m server
Or after publishing to PyPI:
uvx huoshui-file-search -
The server will communicate via stdio according to the MCP protocol
Publishing to PyPI
-
Build the package:
uv build -
Upload to PyPI:
uv publish
System Requirements
- macOS 10.15 or later
- Python 3.10 or later
- uv package manager (install with:
curl -LsSf https://astral.sh/uv/install.sh | sh) - Spotlight indexing enabled
Troubleshooting
"Platform not supported" Error
This extension only works on macOS. Ensure you're running it on a Mac.
"mdfind command not found" Error
Ensure Spotlight is enabled on your Mac. You can check this in System Preferences > Spotlight.
No Search Results
- Spotlight may still be indexing new files
- Check if the file path is included in Spotlight's search scope
- Verify the search query syntax
Search Timeout
Large searches may timeout after 30 seconds. Try:
- Limiting the search path
- Using more specific queries
- Reducing the result limit
License
MIT License - see LICENSE file for details
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request
Support
For issues and feature requests, please visit: https://github.com/huoshui/huoshui-file-search/issues
Metadata
Release files for huoshui-file-search 1.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| huoshui_file_search-1.0.3.tar.gz | 8.1 kB | Without provenance | Details for huoshui_file_search-1.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| huoshui_file_search-1.0.3-py3-none-any.whl | Python 3 | none | any | Details for huoshui_file_search-1.0.3-py3-none-any.whl |
Total release size: 21.2 kB
Release files / huoshui_file_search-1.0.3.tar.gz
| Download URL | huoshui_file_search-1.0.3.tar.gz |
|---|---|
| Size | 8.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a76374ca0f002379dccca5fd9f882b19ef7975e01d08e270abb0562c6fb8f522
|
|
BLAKE2b-256 checksum How to use checksums |
498aee1e2701f4d8af5289823f138bc2becd643fbdd5d741ee640842817b0262
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.10
|
Release files / huoshui_file_search-1.0.3-py3-none-any.whl
| Download URL | huoshui_file_search-1.0.3-py3-none-any.whl |
|---|---|
| Size | 13.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
daee0809d983fcd068a1c9579cd1837e792afdee37e2512cee4b28ae2a3064f1
|
|
BLAKE2b-256 checksum How to use checksums |
5e1bbc098220c927c96004f88c1f6db1bcd1fef9dd2038f669543c7de96c1a44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.10
|
Security for huoshui-file-search 1.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.