trash-cleaner-mcp-server

trash-cleaner-mcp-server

中文 README

主に macOS 向けに最適化された、不要なファイルのスキャン、分析、クリーンアップを行うツールを提供するデスクトップ向け MCP サービスです。

注記： クリーニングツールの大半（cleanAppCaches、cleanTempFiles、cleanAppRemnants、smartCleanSystem）は、macOS 専用に設計・テストされています。他のシステムで実行すると、動作しない場合や予期しない挙動が発生する場合があります。

機能

• クロスプラットフォーム：（予定）Windows、macOS、Linux に対応。
• インテリジェントスキャン： さまざまな種類の不要なファイル（キャッシュ、ログ、一時ファイルなど）を特定します。
• 選択的クリーンアップ： アプリケーションキャッシュ、一時ファイル、アプリケーションの残存ファイルなど、特定の領域をクリーンアップするツールを提供します。
• VS Code 拡張機能の管理： 古い、または使われていない VS Code 拡張機能を検索してクリーンアップするツールを提供します。
• ファイルシステムユーティリティ： ディレクトリ分析、ファイル検索、サイズ計算、削除などのツールを提供します。
• システム情報： 基本的な OS 検出機能を提供します。
• 監査ログ： [Audit] ツールを通じて操作を追跡します。
• スケジュールタスク： 柔軟なスケジューラーを使って、クリーンアップなどのタスクを自動化します。
  • cron 式またはシンプルな間隔を使ってタスクを定義します。
  • 登録済みの任意のツールを実行対象にできます。
  • ファジーマッチングを使い、ツール名（toolName）または自然言語クエリ（toolQuery）でタスクを作成・更新できます。
  • タスク管理機能をすべて備えています（一覧表示、詳細表示、更新、有効化／無効化、削除）。
  • 手動実行と実行履歴の追跡が可能です。

利用可能なツール（機能）

このサーバーは、MCP プロトコル経由で呼び出せる複数のツールを登録します。

macOS クリーニングツール（macOS 向けに最適化）：

• macOSWarning: macOS 以外のシステムで実行された場合に警告を表示します。
• cleanAppCaches: 各種アプリケーションキャッシュ（ユーザーキャッシュ、保存済みアプリケーション状態）を削除します。
  • オプション：dryRun（bool、デフォルト：true）、olderThan（int、任意 - 日数）。
• cleanTempFiles: システムの一時ファイルを削除します。
  • オプション：dryRun（bool、デフォルト：true）、olderThan（int、任意、デフォルト：7 days）。
• cleanAppRemnants: アンインストールされたアプリケーションが残した設定ファイルやキャッシュファイルをスキャンして削除します。
  • オプション：appName（string、任意 - 部分一致する名前）、dryRun（bool、デフォルト：true）。
• smartCleanSystem: 定義済みのレベルに基づいてシステムをクリーニングします（一般的な不要ファイルの保存場所が対象です）。
  • オプション：cleanLevel（enum："safe"、"normal"、"deep"、デフォルト："safe"）、dryRun（bool、デフォルト：true）。

クロスプラットフォームツール（スキャン、ファイルシステム、OS）：

• cleanVSCodeExtensions: 古いバージョンの VS Code（および VSCodium、Cursor などの互換エディター）の拡張機能を削除します。
  • オプション：editorPath（string、任意 - 特定のエディターの拡張機能のパス。デフォルトでは既知のすべての場所をスキャン）、dryRun（bool、デフォルト：true）。
• reportVSCodeExtensions: 削除可能な古い VS Code 拡張機能の一覧を含むレポートを生成します。
  • オプション：editorPath（string、任意）。
• findLargeFiles: ディレクトリ内で、指定したサイズを超えるファイルを検索します。
  • オプション：path（string）、minSize（int、デフォルト：100MB）、maxDepth（int、デフォルト：3）。
• scanFullSystem: システム全体のファイル構造をスキャンし（除外対象を考慮）、ディスク使用量を報告します。
  • オプション：excludePaths（string[]、任意）、maxDepth（int、デフォルト：10）。
• scanDirectory: 特定のディレクトリの内容とサイズ分布を分析します。
  • オプション：path（string）、excludePaths（string[]、任意）、maxDepth（int、デフォルト：10）、includeSubdirs（bool、デフォルト：true）。
• getFolderSize: フォルダーの合計サイズを計算して返します。
  • オプション：path（string）。
• listDirectory: 指定したパスにあるファイルとサブディレクトリを一覧表示します。
  • オプション：path（string）、showHidden（bool、デフォルト：false）。
• findFiles: ディレクトリ内で、指定したパターン（ワイルドカード対応）に一致するファイルを検索します。
  • オプション：path（string）、pattern（string）、maxDepth（int、デフォルト：5）。
• analyzeDirectory: ディレクトリ内のファイルの種類とサイズ分布に関する統計情報を提供します。
  • オプション：path（string）、includeSubdirs（bool、デフォルト：true）。
• getFileHash: ファイルの MD5、SHA1、または SHA256 ハッシュを計算します。
  • オプション：path（string）、algorithm（enum："md5"、"sha1"、"sha256"、デフォルト："md5"）。
• getFileType: MIME タイプを含む基本的なファイル情報を取得します。
  • オプション：path（string）。
• deletePath: 指定したファイルまたはフォルダーを削除します（明示的な確認が必要です。危険なパスに対しては追加のチェックが行われます）。
  • オプション：path（string）、confirm（bool、true が必須）、dangerConfirm（bool、任意 - リスクの可能性がある削除では必須）。
• checkPathExists: 指定したパスが存在するかを確認し、ファイルかディレクトリかを特定します。
  • オプション：path（string）。
• getSystemType: オペレーティングシステムの識別子（例：'darwin'、'win32'、'linux'）を返します。

監査ツール：

• viewAuditLog: アプリケーションのメインログファイル（combined.log）の最新行を表示します。
  • オプション：lines（int、デフォルト：100、最大：1000）。
• clearAuditLog: アプリケーションのメインログファイル（combined.log）を削除します。確認が必要です。
  • オプション：confirm（bool、true が必須）。

スケジュールタスク（TrashCleaner_Scheduler ツール）

登録済みのほかのツールの実行をスケジュールする機能を提供します。

• TrashCleaner_Scheduler_CreateTask：新しいスケジュールタスクを作成します。
  • name、cronExpression が必要です。
  • toolName（"TrashCleaner_CleanAppCaches" のような正確なツール名）または toolQuery（"clean app caches" のような曖昧な説明）のいずれかが必要です。
  • toolParams、enabled は任意です。
• TrashCleaner_Scheduler_ListTasks：設定済みのすべてのスケジュールタスクとそのステータスを一覧表示します。
• TrashCleaner_Scheduler_GetTaskDetails：ID を指定して、特定のタスクの詳細情報を取得します。
• TrashCleaner_Scheduler_UpdateTask：既存のタスクを更新します。名前、スケジュール、対象ツール（toolName または toolQuery を使用）、パラメーター、有効状態を変更できます。
• TrashCleaner_Scheduler_EnableTask：無効なタスクを有効にします。
• TrashCleaner_Scheduler_DisableTask：有効なタスクを無効にします。
• TrashCleaner_Scheduler_DeleteTask：スケジュールタスクを完全に削除します。
• TrashCleaner_Scheduler_RunTaskNow：タスクの実行を直ちに手動で開始します。
• TrashCleaner_Scheduler_GetTaskHistory：タスクの最近の実行履歴（成功／失敗）を取得します。

技術スタック

• Bun.js
• TypeScript

使用方法

npm に公開した後、Bun または npm を使用して MCP サーバーを実行できます。

Bun を使用する場合：

bunx @childhoodandy/trash-cleaner-mcp-server
# or with auto-install
bunx -y @childhoodandy/trash-cleaner-mcp-server

npm を使用する場合：

npx @childhoodandy/trash-cleaner-mcp-server
# or with auto-install
npx -y @childhoodandy/trash-cleaner-mcp-server

インストール

# Clone the repository
git clone <repository-url>
cd trash-cleaner-mcp-server

# Install dependencies (using Bun)
bun install

サーバーの実行

bun start

設定

• ログ設定は src/utils/logger.ts にあります。
• スケジュールタスクの定義は ~/.trash-cleaner/schedules.json に保存されます。

開発

(開発ガイドラインはここに記載されています...)