mcp-everything-search 教育資料

に公開

mcp-everything-search 教育資料

1. はじめに

1.1. mcp-everything-search とは?

このプロジェクトは、Windows、macOS、Linux オペレーティングシステム全体で高速なファイル検索機能を提供するMCP (Model Context Protocol) サーバーです。

  • Windows: Everything SDK を利用します。
  • macOS: 標準搭載の mdfind コマンドを利用します。
  • Linux: locate または plocate コマンドを利用します。

1.2. この資料の目的

この資料は、mcp-everything-search の基本的な使い方、各OSでの設定方法、検索構文、応用的な使い方を理解し、効果的に活用できるようになることを目的としています。

2. 主な機能 (ツール)

2.1. search ツール

システム全体のファイルやフォルダを検索します。検索機能と構文サポートはプラットフォームによって異なります。

2.1.1. パラメータ

  • query (必須): 検索クエリ文字列。プラットフォーム固有の注意点があります。
  • max_results (オプション): 返す結果の最大数 (デフォルト: 100, 最大: 1000)。
  • match_path (オプション): ファイル名だけでなくフルパスに対して照合します (デフォルト: false)。
  • match_case (オプション): 大文字と小文字を区別する検索を有効にします (デフォルト: false)。
  • match_whole_word (オプション): 単語全体のみを照合します (デフォルト: false)。
  • match_regex (オプション): 正規表現検索を有効にします (デフォルト: false)。
  • sort_by (オプション): 結果のソート順 (デフォルト: 1)。利用可能なオプションは以下の通りです。
    • 1: ファイル名でソート (A から Z)
    • 2: ファイル名でソート (Z から A)
    • 3: パスでソート (A から Z)
    • 4: パスでソート (Z から A)
    • 5: サイズでソート (小さい順)
    • 6: サイズでソート (大きい順)
    • 7: 拡張子でソート (A から Z)
    • 8: 拡張子でソート (Z から A)
    • 11: 作成日でソート (古い順)
    • 12: 作成日でソート (新しい順)
    • 13: 更新日でソート (古い順)
    • 14: 更新日でソート (新しい順)

2.1.2. 使用例

{
  "query": "*.py",
  "max_results": 50,
  "sort_by": 6
}
{
  "query": "ext:py datemodified:today",
  "max_results": 10
}

2.1.3. レスポンス

  • ファイル/フォルダのパス
  • ファイルサイズ (バイト単位)
  • 最終更新日時

3. 各OSでの利用方法と検索構文

3.1. Windows (Everything SDK)

3.1.1. 前提条件

  1. Everything 検索ユーティリティ:
    • https://www.voidtools.com/ からダウンロードしてインストールします。
    • Everything サービスが実行されていることを確認してください。
  2. Everything SDK:

3.1.2. 設定方法

環境変数 EVERYTHING_SDK_PATHEverything64.dll (または Everything32.dll) へのパスを設定します。
例: EVERYTHING_SDK_PATH=C:\path\to\Everything-SDK\dll\Everything64.dll

3.1.3. 検索構文

Windows で Everything SDK を使用する場合、以下の高度な検索機能が利用可能です。

基本演算子
  • space: AND 演算子 (例: hello world -> "hello" AND "world" を含むファイルを検索)
  • |: OR 演算子 (例: jpg | png -> ".jpg" OR ".png" を含むファイルを検索)
  • !: NOT 演算子 (例: !txt -> ".txt" を含まないファイルを検索)
  • < >: グループ化 (例: (cat | dog) pic -> ("cat" OR "dog") AND "pic" を含むファイルを検索)
  • " ": 完全一致検索 (例: "happy hour" -> "happy hour" というフレーズを完全に含むファイルを検索)
ワイルドカード
  • *: 0文字以上の任意の文字列に一致 (例: doc*.txt -> "doc" で始まり ".txt" で終わるファイル)
  • ?: 任意の一文字に一致 (例: report?.doc -> "report" の後に1文字あり ".doc" で終わるファイル)
    注意: デフォルトではファイル名全体に一致します。ファイル名のどこにでもワイルドカードを一致させるには、「ファイル名全体に一致」オプションを無効にします。
関数
サイズとカウント
  • size:<サイズ>[kb|mb|gb]: ファイルサイズで検索 (例: size:>10mb)
  • count:<最大数>: 結果の数を制限 (例: count:100)
  • childcount:<数>: 特定数の子を持つフォルダ (例: childcount:0 -> 空のフォルダ)
  • childfilecount:<数>: 特定数のファイルを持つフォルダ
  • childfoldercount:<数>: 特定数のサブフォルダを持つフォルダ
  • len:<長さ>: ファイル名の長さに一致 (例: len:5)
日付
  • datemodified:<日付>, dm:<日付>: 更新日 (例: dm:today, dm:2023-10-26)
  • dateaccessed:<日付>, da:<日付>: アクセス日
  • datecreated:<日付>, dc:<日付>: 作成日
  • daterun:<日付>, dr:<日付>: 最終実行日
  • recentchange:<日付>, rc:<日付>: 最近変更された日
    日付形式: YYYY[-MM[-DD[Thh[:mm[:ss[.sss]]]]]] または today, yesterday, lastweek など。
ファイル属性と種類
  • attrib:<属性>, attributes:<属性>: ファイル属性で検索 (A:アーカイブ, H:隠しファイル, S:システムファイルなど。例: attrib:H)
  • type:<種類>: ファイルの種類で検索 (例: type:document)
  • ext:<拡張子リスト>: セミコロン区切りの拡張子で検索 (例: ext:jpg;png;gif)
パスと名前
  • path:<パス>: 特定のパス内で検索 (例: path:C:\Users\Me\Documents)
  • parent:<パス>, infolder:<パス>, nosubfolders:<パス>: サブフォルダを除外してパス内を検索
  • startwith:<テキスト>: 指定したテキストで始まるファイル (例: startwith:report_)
  • endwith:<テキスト>: 指定したテキストで終わるファイル (例: endwith:.bak)
  • child:<ファイル名>: 特定の子を含むフォルダ
  • depth:<階層数>, parents:<階層数>: 特定のフォルダ階層にあるファイル
  • root: 親フォルダのないファイル
  • shell:<名前>: 既知のシェルフォルダ内を検索 (例: shell:Desktop)
重複とリスト
  • dupe, namepartdupe, attribdupe, dadupe, dcdupe, dmdupe, sizedupe: 重複ファイルを検索
  • filelist:<リスト>: パイプ(|)区切りのファイルリストを検索
  • filelistfilename:<ファイル名>: リストファイルからファイルを検索
  • frn:<FRNリスト>: ファイル参照番号 (FRN) で検索
  • fsi:<インデックス>: ファイルシステムインデックスで検索
  • empty: 空のフォルダを検索
関数構文
  • function:value: 値に等しい
  • function:<=value: 値以下
  • function:<value: 値より小さい
  • function:=value: 値に等しい (明示的)
  • function:>value: 値より大きい
  • function:>=value: 値以上
  • function:start..end: 値の範囲 (start から end まで、両端を含む)
  • function:start-end: 値の範囲 (同上)
修飾子

検索クエリの動作を変更します。

  • case: / nocase:: 大文字・小文字の区別を有効/無効 (例: case:Report.docx)
  • file: / folder:: ファイルのみ/フォルダのみを対象 (例: file: *.txt)
  • path: / nopath:: フルパスで照合/ファイル名のみで照合
  • regex: / noregex:: 正規表現を有効/無効 (例: regex:^[a-z]+\.zip$)
  • wfn: / nowfn:: ファイル名全体で照合/ファイル名の一部で照合
  • wholeword: / ww:: 単語全体で照合
  • wildcards: / nowildcards:: ワイルドカードを有効/無効
使用例
  1. 今日更新された Python ファイルを検索:
    ext:py datemodified:today
  2. 1GB より大きい動画ファイル (mp4, mkv, avi) を検索:
    ext:mp4;mkv;avi size:>1gb
  3. C:\Projects フォルダ内の JavaScript ファイルを検索:
    path:C:\Projects *.js

3.2. macOS (mdfind)

3.2.1. 前提条件

追加のセットアップは不要です。サーバーは標準搭載の mdfind コマンドを使用します。

3.2.2. 設定方法

追加の設定は不要です。

3.2.3. 検索構文

macOS では、Spotlight のメタデータ検索機能を mdfind コマンド経由で利用します。

コマンドオプション (mdfind 自体のオプション)
  • -live: ファイルが変更されると検索結果をライブ更新します。
  • -count: 一致した数のみを表示します。
  • -onlyin <ディレクトリ>: 特定のディレクトリに検索を限定します (例: mdfind -onlyin ~/Documents "レポート")。
  • -literal: クエリを解釈せずにリテラルテキストとして扱います。
  • -interpret: Spotlight メニューに入力されたかのようにクエリを解釈します。
基本検索
  • 単純なテキスト検索は、任意のメタデータ属性内の一致を探します。
  • 検索文字列内でワイルドカード (*) がサポートされます。
  • 複数の単語は AND 条件として扱われます (例: 年間 報告書 -> "年間" AND "報告書" を含むものを検索)。
  • クエリ内の空白は重要です。
  • 式をグループ化するには括弧 () を使用します。
検索演算子
  • | (OR): いずれかの単語に一致 (例: "画像|写真")
  • - (NOT): 一致を除外 (例: -スクリーンショット)
  • = , ==: 等しい
  • !=: 等しくない
  • < , >: より小さい / より大きい
  • <= , >=: 以下 / 以上
値比較修飾子

これらの修飾子を角括弧 [] と共に使用します。

  • [c]: 大文字・小文字を区別しない比較 (例: kMDItemFSName ==[c] "*.jpg")
  • [d]: 発音区別符号を区別しない比較
  • 組み合わせ可能 (例: [cd] で両方)
コンテンツタイプ (kind:)

特定の種類のファイルを検索します。

  • application, app: アプリケーション
  • audio, music: オーディオ/音楽ファイル
  • bookmark: ブックマーク
  • contact: 連絡先
  • email, mail message: メールメッセージ
  • event: カレンダーイベント
  • folder: フォルダ
  • font: フォント
  • image: 画像 (例: kind:image)
  • movie: 動画
  • pdf: PDF ドキュメント (例: kind:pdf "契約書")
  • preferences: システム環境設定
  • presentation: プレゼンテーション
  • todo: カレンダーの ToDo
日付フィルタ (date:)

時間ベースの検索には以下のキーワードを使用します。

  • today, yesterday, tomorrow
  • this week, next week
  • this month, next month
  • this year, next year
    または、以下の時間関数を使用します。
  • $time.today()
  • $time.yesterday()
  • $time.this_week()
  • $time.this_month()
  • $time.this_year()
  • $time.tomorrow()
  • $time.next_week()
  • $time.next_month()
  • $time.next_year()
    例: kMDItemFSContentChangeDate >= $time.this_month() (今月以降に変更されたファイル)
一般的なメタデータ属性

特定のメタデータを検索するには、これらの属性を使用します。

  • kMDItemAuthors: ドキュメントの作成者 (例: kMDItemAuthors == "山田太郎")
  • kMDItemContentType: ファイルタイプ (例: kMDItemContentType = "public.png")
  • kMDItemContentTypeTree: ファイルタイプの階層
  • kMDItemCreator: 作成したアプリケーション (例: kMDItemCreator = "Microsoft Word")
  • kMDItemDescription: ファイルの説明
  • kMDItemDisplayName: 表示名
  • kMDItemFSContentChangeDate: ファイルの変更日 (例: kMDItemFSContentChangeDate > 2023-01-01)
  • kMDItemFSCreationDate: ファイルの作成日
  • kMDItemFSName: ファイル名 (例: kMDItemFSName = "*.docx")
  • kMDItemKeywords: キーワード/タグ
  • kMDItemLastUsedDate: 最終使用日
  • kMDItemNumberOfPages: ページ数 (例: kMDItemNumberOfPages > 10)
  • kMDItemTitle: ドキュメントのタイトル
  • kMDItemUserTags: ユーザーが割り当てたタグ (例: kMDItemUserTags = "重要")
使用例
  1. 昨日更新された画像を検索:
    kind:image date:yesterday
  2. 作成者でドキュメントを検索 (大文字小文字区別なし):
    kMDItemAuthors ==[c] "John Doe"
  3. 特定のディレクトリ内のファイルを検索 (mdfind コマンドライン):
    mdfind -onlyin ~/Documents "レポート"
  4. タグでファイルを検索:
    kMDItemUserTags = "重要"
  5. 特定のアプリケーションで作成されたファイルを検索 (ワイルドカード使用):
    kMDItemCreator = "Pixelmator*"
  6. 特定のテキストを含む PDF を検索:
    kind:pdf "検索語句"
  7. 最近のプレゼンテーションを検索:
    kind:presentation date:this week
  8. 一致するファイルの数をカウント (mdfind コマンドライン):
    mdfind -count "kind:image date:today"
  9. 複雑なメタデータ検索:
    kMDItemContentTypeTree = "public.image" && kMDItemUserTags = "vacation" && kMDItemFSContentChangeDate >= $time.this_month()

注意: 特定のファイルの利用可能なすべてのメタデータ属性を確認するには、ターミナルで mdls <ファイル名> を使用します。

3.3. Linux (locate/plocate)

3.3.1. 前提条件

  1. locate または plocate コマンドをインストールして初期化します。
    • Ubuntu/Debian: sudo apt-get install plocate または sudo apt-get install mlocate
    • Fedora: sudo dnf install mlocate
  2. インストール後、データベースを更新します。
    • plocate の場合: sudo updatedb
    • mlocate の場合: sudo /etc/cron.daily/mlocate

3.3.2. 設定方法

追加の設定は不要です。

3.3.3. 検索構文

Linux では、高速なファイル名検索のために locate または plocate コマンドを使用します。

基本検索
  • 単純なテキスト検索はファイル名に対して一致を探します。
  • 複数の単語は AND 条件として扱われます (例: apache config -> "apache" AND "config" を名前に含むファイルを検索)。
  • ワイルドカード (* および ?) がサポートされています。
    • *: 0文字以上の任意の文字列 (例: *.log)
    • ?: 任意の一文字 (例: file?.txt)
  • デフォルトでは大文字と小文字を区別しません。
検索オプション (locate/plocate コマンドのオプション)
  • -i: 大文字と小文字を区別しない検索 (デフォルトの動作であることが多いですが、明示的に指定できます)。
  • -c: 一致した数を表示します (ファイル名自体は表示しません)。
  • -r または --regex: POSIX 基本正規表現ではなく、拡張正規表現を使用してパターンを照合します。 (注意: locate のバージョンや plocate によっては、デフォルトで基本的なグロブパターンのみをサポートし、正規表現にはこのオプションが必要な場合があります。)
  • -b または --basename: パスのディレクトリ部分を無視し、ファイル名 (ベース名) のみにパターンを照合します。
  • -w または --wholename: パターンをパス名全体に対して照合します (デフォルトの動作)。 -b とは逆です。
使用例
  1. すべての Python ファイルを検索:
    *.py
    または、より確実にベース名のみを対象とする場合:
    locate -b "*.py"
  2. ホームディレクトリ (/home/username/) 内の特定のパターンのファイルを検索:
    /home/username/*report*.pdf
  3. 正規表現を使用して、/etc/ ディレクトリ内の大文字で始まり .conf で終わるファイルを大文字小文字を区別して検索 (plocate の場合、--regex が必要で、locate の場合は -r や、正規表現の構文が異なる場合があります):
    locate --regex "^/etc/[A-Z].*\.conf$"
    (注意: locate はデータベースの更新頻度に依存するため、大文字小文字の区別オプションがない場合、パターンで工夫する必要があります。)
  4. 一致するファイルの数をカウント:
    locate -c "*.txt"

注意: 正確な結果を得るためには、locate データベースが最新である必要があります。データベースを手動で更新するには sudo updatedb を実行してください (plocate の場合も同様)。

4. インストール方法

4.1. Smithery を使用したインストール

npx -y @smithery/cli install mcp-server-everything-search --client claude

4.2. uv を使用したインストール (推奨)

uv を使用する場合、特定のインストールは不要です。uvx を使用して mcp-server-everything-search を直接実行します。

4.3. PIP を使用したインストール

pip install mcp-server-everything-search

インストール後、スクリプトとして実行できます。

python -m mcp_server_everything_search

5. Claude Desktop での利用設定

claude_desktop_config.json にプラットフォームに応じた設定を追加します。

5.1. Windows (uvx を使用)

"mcpServers": {
  "everything-search": {
    "command": "uvx",
    "args": ["mcp-server-everything-search"],
    "env": {
      "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
    }
  }
}

5.2. Linux および macOS (uvx を使用)

"mcpServers": {
  "everything-search": {
    "command": "uvx",
    "args": ["mcp-server-everything-search"]
  }
}

6. デバッグ方法

6.1. MCP inspector の利用

uvx インストールの場合:

npx @modelcontextprotocol/inspector uvx mcp-server-everything-search

6.2. ログの確認方法

  • Linux/macOS:
    tail -f ~/.config/Claude/logs/mcp*.log
    
  • Windows (PowerShell):
    Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait
    

7. 開発者向け情報

ローカルでの変更をテストするには、MCP inspector を使用するか、Claude Desktop アプリで直接テストします。
(詳細は README.md を参照)

8. ライセンス

この MCP サーバーは MIT ライセンスの下でライセンスされています。

9. 免責事項

このプロジェクトは、voidtools (Everything 検索ユーティリティの作成者) とは提携、承認、後援されていません。

Discussion