Disk Inventory MCP

Disk Inventory MCP

macOS 向けのローカルで読み取り専用のディスク分析ツールです。CLI と MCP サーバーを単一のネイティブ実行ファイルにまとめています。容量の大きなファイルやフォルダーを見つけ、ファイル拡張子ごとの内訳を調べ、スキャンが完了しなかった箇所を正確に確認できます。

v0.1.0 は読み取り専用のプレビュー版です。 削除、ゴミ箱、クリーンアップの実行、コンテンツの読み取りを行うツールはありません。macOS 13 以降が必要です。macOS フレームワーク以外のランタイム依存関係はありません。

インストール

推奨：プロジェクトの Homebrew tap からインストールします（ソースからビルドします。Swift 5.9 以降を含む Xcode Command Line Tools が必要です）。

brew install LemmaLemming/tap/disk-inventory-mcp
disk-inventory --version

GitHub リリースでは、Intel／Apple Silicon 両対応の .tar.gz、MCP バンドル（.mcpb）、対応するソース、SHA256SUMS も提供しています。ダウンロード可能なバイナリはアドホック署名されており、Developer ID 署名も Apple の公証も受けていません。Homebrew はソースからビルドします。MCP バンドルのインポートはクライアントの対応状況に依存し、macOS のセキュリティチェックの対象となる場合があります。

CLI

disk-inventory scan ~/Downloads
disk-inventory scan ~/Downloads --json
disk-inventory scan ~/Downloads --json --limit 50 --max-entries 200000 --max-seconds 60

JSON 出力には summary、top_children、file_types が含まれます。64 ビット精度を維持するため、バイト数は 10 進数の文字列で出力されます。最上位の子要素はルートの直下にある子要素です。ディレクトリの合計には、その配下の要素が含まれます。CLI の終了コード：0 は完了、2 は無効な呼び出し、3 は未完了（JSON は引き続き使用できます）。

MCP の設定

ローカルの stdio サーバーを起動する任意の MCP クライアントを設定します。例にあるパスを、お使いのコンピューター上の絶対パスに置き換えてください。インストールされた実行ファイルの場所を調べるには、command -v disk-inventory を使用します。以下の例では、Apple Silicon で一般的な Homebrew の場所を使用しています。

{
  "mcpServers": {
    "disk-inventory": {
      "command": "/opt/homebrew/bin/disk-inventory",
      "args": ["mcp", "--root", "/Users/YOU/Downloads"]
    }
  }
}

追加のディレクトリへのアクセスを許可するには、--root と PATH の組を追加します。明示的なルートを指定せずにサーバーを起動することはできません。また、シンボリックリンクによるルート外への移動も含め、指定したルートの外にあるスキャンパスは拒否されます。代わりに、MCPB 対応クライアントでリリースバンドルをインポートし、アクセスを許可するディレクトリを 1 つ指定することもできます。

プロンプトの例：

• 「Downloads ディレクトリ内の容量が大きいフォルダーを表示し、スキャンで見落としたものがないか教えてください。」
• 「そのスキャンの中から、容量が最も大きい .zip ファイルを見つけてください。」
• 「確認されたファイルを拡張子ごとに分類し、論理バイト数と割り当て済みバイト数の違いを説明してください。」

ツール	用途
list_roots	起動時にアクセスを許可されたディレクトリを表示します
scan_start	範囲を限定したバックグラウンドのメタデータスキャンを開始し、スキャン ID を返します
scan_status	進捗、最終集計、スキップされたパス、集計上の注意事項を表示します
scan_cancel	実行中のスキャンを協調的に停止します
query_usage	結果の並べ替えやフィルタリング、ページ分割、ディレクトリ ID による詳細表示を行います
file_types	ファイル拡張子グループをページ分割して表示します

サーバーは、stdio 経由の改行区切り JSON-RPC、初期化、ping、ツールを実装しています。プロトコルバージョン 2025-11-25、2025-06-18、2025-03-26 をネゴシエートします。ツールの結果には、構造化 JSON とシリアライズされたテキストの両方が含まれます。スキャンジョブはアプリケーションレベルの ID で管理されます。このリリースでは、任意の MCP Tasks 機能を提供していません。適切な間隔（たとえば 1 秒に 1 回）でステータスを確認してください。

計上と制限

• デフォルトの予算は、エントリー数が100,000件、時間が30秒です。スキャンごとの上限は、エントリー数が500,000件、時間が300秒です。ディレクトリの走査深度は128に制限されています。時間とキャンセルの確認はファイルシステム呼び出しの合間に行われます。ファイルシステム上でOS呼び出しがブロックされると、いずれかが遅れる可能性があります。
• メモリには、実行中のスキャン1件と、直近で完了したスキャン2件が保持されます。さらにスキャンを開始すると、古い完了済みの結果が破棄されます。プロセスを再起動すると、すべてのスキャンが破棄されます。永続データベースやスキャンの比較機能はまだありません。
• クエリで返されるエントリーは、1ページあたり最大200件です。ルートのIDは0です。IDはスキャン内でのみ有効です。parent_idを指定すると直下の子が返され、省略するとすべての子孫が対象になります。ディレクトリの合計とその子の合計を足し合わせないでください。
• 論理バイト数は、確認された通常ファイルまたはシンボリックリンクの各パスについてカウントします。割り当て済みバイト数は、ハードリンクをデバイス／inodeで重複排除したうえで、st_blocks * 512を使用します。共有されたハードリンクのストレージは最初に検出されたパスに計上されるため、フォルダーごとの内訳は列挙順によって変わることがあります。
• ディレクトリのメタデータは対象外です。APFSクローンとスナップショットによって保持されるブロックは重複排除されません。割り当て済みバイト数は、解放可能なバイト数ではありません。ここで示される情報から、ファイルを安全に削除できるとは判断できません。
• 子孫のシンボリックリンクは、リンク先をたどらずに測定されます。他のファイルシステムはスキップされ、その旨が報告されます。ルートパスは起動時に正規化され、走査ではシンボリックリンクをたどらずに各構成要素が開かれます。Disk Inventory Xにある特殊なfirmlink走査は、この実装には引き継がれていません。
• アクセス権エラー、消失したエントリー、制限、マウント境界、無効なUTF-8名があると、complete=falseになります。この場合、合計は確認できたデータのみを表します。問題の詳細は最大100件返され、問題の総数も示されます。エントリーの確認済みバイト数が0で、complete=falseと報告される場合がありますが、これは空であることを意味するものではありません。
• スキャンはライブ状態の観測であり、アトミックなファイルシステムのスナップショットではありません。走査中に内容やディレクトリが変わる可能性があります。このツールは、昇格された権限を要求したり、macOSのプライバシー保護を回避したりしません。
• ファイルの種類はファイル名の拡張子のみから推測され、内容やアプリケーションの所有権は考慮されません。スキャナーがファイルの内容を読み取ることはありません。ただし、クラウドプロバイダーのディレクトリを参照すると、プロバイダーのメタデータにアクセスすることがあります。

プライバシー

実行ファイルはネットワークリクエストを行わず、テレメトリーを含まず、スキャンキャッシュを書き込みません。呼び出し元のCLIまたはMCPクライアントに、パス、サイズ、エラーの詳細を返します。そのクライアントは、独自の設定に従ってツールの結果をモデルプロバイダーに送信したり、ログを保持したりする場合があります。ファイル名は信頼できないデータとして扱ってください。許可するルートは、分析する予定の範囲に限定してください。

開発

swift build -c release
DISK_INVENTORY_BIN="$PWD/.build/release/disk-inventory" python3 tests/integration.py
bash scripts/package.sh

統合テストでは、通常ファイル、ハードリンク、スパースファイル、シンボリックリンクのループ／脱出、読み取り不可のディレクトリ、悪意のあるファイル名、ページネーション、キャンセル、CLIの終了コード、MCPプロトコルエラーを含む、一時的なテスト用データを生成して使用します。個人用ディレクトリはスキャンしません。任意の相互運用性テストでは、公式のPython MCP SDKを使用します。tests/sdk_interop.pyを参照してください。

ライセンスと来歴

GPL-3.0-or-later。詳しくはLICENSEを参照してください。これは、Tjark DerlienのDisk Inventory XおよびTreeMapViewの評価を参考にした、新しいSwift実装です。これらのObjective-Cソース、アートワーク、TreeMapView、Omniフレームワーク、CocoaTechコンポーネントはバンドルしておらず、Disk Inventory Xの公式リリースでもありません。GPLライセンスの本文は、公開されているDisk Inventory Xのチェックアウトから転載しています。元の上流プロジェクトに関する権利と告知は、それぞれのリポジトリに引き続き記載されています。

今後の予定：永続的なスキャン比較、根拠に基づくクリーンアップのプレビュー、その後、別途レビューを行ったうえでのクリーンアップ実行。これらはv0.1.0の機能ではありません。