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)

1. Install the extension via your DXT-compatible application (e.g., Claude Desktop)
2. The extension will be automatically configured and ready to use
3. Use the search_files tool 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 string
• path (optional): Directory to limit search scope
• case_sensitive (optional): Enable case-sensitive search (default: false)
• regex (optional): Regex pattern to filter results by filename
• sort_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:

1. No files match both criteria
2. The syntax needs adjustment (try 寻找工程车 AND kind:movie)
3. 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 scope
• default_limit: Default maximum number of search results
• enable_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

1. Install dependencies:

   uv sync
   

2. Run the server:

   uv run python -m server
   

   Or after publishing to PyPI:

   uvx huoshui-file-search
   

3. The server will communicate via stdio according to the MCP protocol

# # Publishing to PyPI

1. Build the package:

   uv build
   

2. 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:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

# Support

For issues and feature requests, please visit:
https://github.com/huoshui/huoshui-file-search/issues