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. 主な機能 (ツール)
search
ツール
2.1. システム全体のファイルやフォルダを検索します。検索機能と構文サポートはプラットフォームによって異なります。
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. 前提条件
-
Everything 検索ユーティリティ:
- https://www.voidtools.com/ からダウンロードしてインストールします。
- Everything サービスが実行されていることを確認してください。
-
Everything SDK:
- https://www.voidtools.com/support/everything/sdk/ からダウンロードします。
- SDK ファイルをシステム上の場所に展開します。
3.1.2. 設定方法
環境変数 EVERYTHING_SDK_PATH
に Everything64.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:
: ワイルドカードを有効/無効
使用例
- 今日更新された Python ファイルを検索:
ext:py datemodified:today
- 1GB より大きい動画ファイル (mp4, mkv, avi) を検索:
ext:mp4;mkv;avi size:>1gb
-
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 = "重要"
)
使用例
- 昨日更新された画像を検索:
kind:image date:yesterday
- 作成者でドキュメントを検索 (大文字小文字区別なし):
kMDItemAuthors ==[c] "John Doe"
- 特定のディレクトリ内のファイルを検索 (mdfind コマンドライン):
mdfind -onlyin ~/Documents "レポート"
- タグでファイルを検索:
kMDItemUserTags = "重要"
- 特定のアプリケーションで作成されたファイルを検索 (ワイルドカード使用):
kMDItemCreator = "Pixelmator*"
- 特定のテキストを含む PDF を検索:
kind:pdf "検索語句"
- 最近のプレゼンテーションを検索:
kind:presentation date:this week
- 一致するファイルの数をカウント (mdfind コマンドライン):
mdfind -count "kind:image date:today"
- 複雑なメタデータ検索:
kMDItemContentTypeTree = "public.image" && kMDItemUserTags = "vacation" && kMDItemFSContentChangeDate >= $time.this_month()
注意: 特定のファイルの利用可能なすべてのメタデータ属性を確認するには、ターミナルで mdls <ファイル名>
を使用します。
3.3. Linux (locate/plocate)
3.3.1. 前提条件
-
locate
またはplocate
コマンドをインストールして初期化します。- Ubuntu/Debian:
sudo apt-get install plocate
またはsudo apt-get install mlocate
- Fedora:
sudo dnf install mlocate
- Ubuntu/Debian:
- インストール後、データベースを更新します。
- plocate の場合:
sudo updatedb
- mlocate の場合:
sudo /etc/cron.daily/mlocate
- plocate の場合:
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
とは逆です。
使用例
- すべての Python ファイルを検索:
*.py
または、より確実にベース名のみを対象とする場合:
locate -b "*.py"
- ホームディレクトリ (
/home/username/
) 内の特定のパターンのファイルを検索:
/home/username/*report*.pdf
- 正規表現を使用して、
/etc/
ディレクトリ内の大文字で始まり.conf
で終わるファイルを大文字小文字を区別して検索 (plocate の場合、--regex
が必要で、locate
の場合は-r
や、正規表現の構文が異なる場合があります):
locate --regex "^/etc/[A-Z].*\.conf$"
(注意:locate
はデータベースの更新頻度に依存するため、大文字小文字の区別オプションがない場合、パターンで工夫する必要があります。) - 一致するファイルの数をカウント:
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