{
  "markdown": "# Huoshui File Search\n\nA Desktop Extension (DXT) that provides fast file search capabilities for macOS using the native `mdfind` command (Spotlight search).\n\n⚠️ **IMPORTANT**: This extension only works on macOS systems. Windows and Linux are not supported.\n\n## Features\n\n- Fast file search using macOS Spotlight index\n- Multiple filtering options:\n  - Path-based search restrictions\n  - Case-sensitive/insensitive search\n  - Regular expression matching\n  - Sort results by name, size, or date\n- Configurable search limits\n- Clean JSON-structured responses\n- Built with FastMCP framework for optimal performance\n\n## Installation\n\n### From MCP Registry (Recommended)\n\nThis server is available in the Model Context Protocol Registry. Install it using your MCP client.\n\nmcp-name: io.github.huoshuiai42/huoshui-file-search\n\n### Via PyPI (Recommended)\n\n```bash\nuvx huoshui-file-search\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/huoshui/huoshui-file-search.git\ncd huoshui-file-search\nuv sync\n```\n\n## Usage\n\n### As a Desktop Extension (DXT)\n\n1. Install the extension via your DXT-compatible application (e.g., Claude Desktop)\n2. The extension will be automatically configured and ready to use\n3. Use the `search_files` tool with various parameters\n\n### Direct Usage\n\n```python\nfrom server.main import search_files, FileSearchParams\n\n# Basic search\nparams = FileSearchParams(query=\"report.pdf\")\nresult = await search_files(None, params)\n\n# Search with filters\nparams = FileSearchParams(\n    query=\"*.py\",\n    path=\"/Users/username/Documents\",\n    case_sensitive=True,\n    sort_by=\"size\",\n    limit=50\n)\nresult = await search_files(None, params)\n```\n\n## Tool Parameters\n\n- `query` (required): Search query string\n- `path` (optional): Directory to limit search scope\n- `case_sensitive` (optional): Enable case-sensitive search (default: false)\n- `regex` (optional): Regex pattern to filter results by filename\n- `sort_by` (optional): Sort results by 'name', 'size', or 'date'\n- `limit` (optional): Maximum number of results (default: 100, max: 1000)\n\n## mdfind Query Syntax\n\nThe `query` parameter uses macOS Spotlight's mdfind syntax:\n\n- **Simple text search**: `report` - finds files containing \"report\"\n- **File kind**: `kind:pdf`, `kind:image`, `kind:movie`\n- **Filename search**: `kMDItemFSName == \"*.py\"` - finds Python files\n- **Combined queries**: `invoice AND kind:pdf` - finds PDF files containing \"invoice\"\n- **Date queries**: `date:today`, `modified:this week`\n\n**Note**: If your query like `'寻找工程车' kind:movie` returns no results, it might mean:\n\n1. No files match both criteria\n2. The syntax needs adjustment (try `寻找工程车 AND kind:movie`)\n3. Spotlight hasn't indexed the files yet\n\n## Examples\n\n### Basic File Search\n\n```json\n{\n  \"query\": \"document.pdf\"\n}\n```\n\n### Search in Specific Directory\n\n```json\n{\n  \"query\": \"*.txt\",\n  \"path\": \"/Users/username/Documents\"\n}\n```\n\n### Case-Sensitive Search\n\n```json\n{\n  \"query\": \"README\",\n  \"case_sensitive\": true\n}\n```\n\n### Search with Regex Filter\n\n```json\n{\n  \"query\": \"kind:text\",\n  \"regex\": \"log.*2024.*\\\\.txt$\"\n}\n```\n\n### Sorted and Limited Results\n\n```json\n{\n  \"query\": \"*.jpg\",\n  \"sort_by\": \"size\",\n  \"limit\": 20\n}\n```\n\n## Configuration\n\nThe extension supports user configuration through the DXT manifest:\n\n- `allowed_directories`: List of directories to limit search scope\n- `default_limit`: Default maximum number of search results\n- `enable_logging`: Enable debug logging\n\n## Development\n\n### Project Structure\n\n```\nhuoshui-file-search/\n├── manifest.json       # DXT manifest file\n├── server/            # MCP server implementation\n│   ├── __init__.py\n│   ├── __main__.py\n│   └── main.py\n├── pyproject.toml     # Python package configuration\n├── requirements.txt   # Python dependencies\n├── LICENSE           # MIT License\n└── README.md         # This file\n```\n\n### Testing Locally\n\n1. Install dependencies:\n\n   ```bash\n   uv sync\n   ```\n\n2. Run the server:\n\n   ```bash\n   uv run python -m server\n   ```\n\n   Or after publishing to PyPI:\n\n   ```bash\n   uvx huoshui-file-search\n   ```\n\n3. The server will communicate via stdio according to the MCP protocol\n\n### Publishing to PyPI\n\n1. Build the package:\n\n   ```bash\n   uv build\n   ```\n\n2. Upload to PyPI:\n   ```bash\n   uv publish\n   ```\n\n## System Requirements\n\n- macOS 10.15 or later\n- Python 3.10 or later\n- uv package manager (install with: `curl -LsSf https://astral.sh/uv/install.sh | sh`)\n- Spotlight indexing enabled\n\n## Troubleshooting\n\n### \"Platform not supported\" Error\n\nThis extension only works on macOS. Ensure you're running it on a Mac.\n\n### \"mdfind command not found\" Error\n\nEnsure Spotlight is enabled on your Mac. You can check this in System Preferences > Spotlight.\n\n### No Search Results\n\n- Spotlight may still be indexing new files\n- Check if the file path is included in Spotlight's search scope\n- Verify the search query syntax\n\n### Search Timeout\n\nLarge searches may timeout after 30 seconds. Try:\n\n- Limiting the search path\n- Using more specific queries\n- Reducing the result limit\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## Support\n\nFor issues and feature requests, please visit:\nhttps://github.com/huoshui/huoshui-file-search/issues\n",
  "bytes": 5358,
  "sha": "b70f0980a263fcbe6f1b6b075b9fb16eac7dfdb253c8ae40e1c7e9b933fd4bcf",
  "repo_slug": "huoshuiai42/huoshui-file-search",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_huoshuiai42_huoshui_file_searc_685a506d/readme"
}