shutil-mcp

aioshutilを使用した非同期シェルユーティリティを提供するMCPサーバー。

このプロジェクトは、AIエージェント向けに設計されたファイルシステムツール群を提供し、 生のテキストではなく構造化されたJSON出力を返します。これにより、AIモデルによる ファイルシステムデータのより正確かつ直接的な消費が可能になります。

機能

• 非同期操作: aioshutilとスレッドエグゼキュータを活用し、ノンブロッキングなファイルシステムタスクを実現します。

• JSON出力: すべてのツールは、AIエージェント向けに最適化された最小化JSONを返します。

• ジャイルサポート: セキュリティのため、ファイルシステムアクセスを特定のディレクトリツリーに制限します。

• 検証と整合性: mvとcpは、リンク解除または確定の前に宛先データを検証し、部分的な失敗によるデータ損失を防ぎます。

• 可逆的な変更と元に戻す: chmodとchownは、以前のモードと所有権を返して即時の元に戻す/やり直しを容易にし、失敗時には自動ロールバックします。

• ソフト削除と復元: rmはtrash=Trueによるソフト削除と、対応するrestoreツールをサポートします。

• Zip-Slip保護: unpack_archiveは、すべてのアーカイブメンバーパスをディレクトリトラバーサル/Zip-Slip攻撃に対して検証します。

• 詳細なメタデータ: lsやstatなどのツールは、包括的な情報（サイズ、mtime、モード、所有者など）を提供します。

• HTTPトランスポートサポート: SSEおよびStreamable HTTPトランスポートの組み込みサポートを含みます。

Related MCP server: File Manager MCP Server

利用可能なツール

• ls: 詳細なメタデータを含むディレクトリ内容を一覧表示します。

• cp: 検証付きでファイルまたはディレクトリを再帰的にコピーします。

• mv: 安全な削除前検証付きでファイルまたはディレクトリを移動/名前変更します。

• rm: ファイルまたはディレクトリを削除します（trash=Trueによるソフト削除をサポート）。

• restore: ゴミ箱からファイルまたはディレクトリを復元します。

• chmod: ロールバックと以前のモード付きでファイル/ディレクトリの権限を変更します。

• chown: ロールバックと以前の所有者付きでファイル/ディレクトリの所有権を変更します。

• disk_usage: パスのディスク使用量統計を取得します。

• which: 実行可能ファイルへのパスを検索します。

• cat: ファイル内容を読み取ります。オプションで特定の行範囲に制限できます。

• glob: globパターンに一致するファイルを検索します。

• grep: 正規表現パターンを使用してファイル内容を検索します。

• tree: 再帰的なディレクトリツリーをネストされたJSONとして取得します。

• make_archive: 上書きガード付きでアーカイブファイル（zip、tarなど）を作成します。

• unpack_archive: Zip-Slip保護付きでアーカイブファイルを安全に展開します。

• get_archive_formats: サポートされているアーカイブ形式を一覧表示します。

インストール

pip install shutil-mcp

使用方法

stdioトランスポートで実行

shutil-mcp --transport stdio

ジャイル制限付きで実行

shutil-mcp --transport stdio --jail /path/to/projects

SSEサーバーとして実行

shutil-mcp --transport sse --jail /path/to/projects --port 8000

開発

詳細な開発手順については、DEVELOPMENT.mdを参照してください。

ライセンス

MIT