huoshui-file-search

Huoshui File Search

macOS のネイティブな mdfind コマンド（Spotlight 検索）を使用して、高速なファイル検索機能を提供するデスクトップ拡張機能（DXT）です。

⚠️ 重要：この拡張機能は 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

使用方法

デスクトップ拡張機能（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 - 詳細は LICENSE ファイルを参照してください

貢献

貢献を歓迎します！次の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新機能のテストを追加します
4. プルリクエストを送信します

サポート

問題の報告や機能のリクエストは、次のページをご覧ください。 https://github.com/huoshui/huoshui-file-search/issues