Trash Cleaner MCP Server

🚀 Trash Cleaner MCP Service

This is an MCP (Message Handler Program) service designed for macOS, mainly used to scan, analyze, and clean up junk files. The service offers a variety of functional modules, including junk file cleaning, task scheduling, and audit log management.

🚀 Quick Start

1. Clone the repository:

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

2. Install dependencies:

   bun install
   

3. Start the service:

   bun start
   

✨ Features

• Cross - platform Support: Although primarily targeting macOS, some functions are also applicable to Windows and Linux.
• Intelligent Scanning: It can automatically identify and classify various types of junk files.
• Selective Cleaning: Users can choose specific files or directories for cleaning operations.
• Task Scheduling: It provides a powerful task scheduling function, supporting the automatic execution of cleaning tasks through cron expressions.
• Audit Logs: Detailed log information of system operations is recorded for subsequent tracing and analysis.

📦 Tools

macOS - Specific Tools

1. TrashCleaner_CleanAppCaches
   Clean application cache files.

2. TrashCleaner_DeletePath
   Delete specified files or directories. The deletion operation requires a secondary confirmation, especially for high - risk paths, additional verification will be carried out.

3. TrashCleaner_ViewAuditLog
   View the latest audit log content. By default, the last 100 records are displayed.

Cross - platform Tools

4. TrashCleaner_GetSystemType
   Return the operating system identifier (e.g., 'darwin' for macOS, 'win32' for Windows, 'linux' for Linux).

5. TrashCleaner_CheckPathExists
   Check if the specified path exists and determine whether it is a file or a directory.

6. TrashCleaner_DeletePath
   Delete specified files or directories. The deletion operation requires a secondary confirmation, especially for high - risk paths, additional verification will be carried out.

📚 Audit Tools

• viewAuditLog: View the recent records in the main application log file (combined.log).
• clearAuditLog: Delete the main application log file (combined.log). The operation requires confirmation.

📚 Task Scheduler (TrashCleaner_Scheduler Tool)

Create a Task

To create a new task, you need to specify name and cronExpression, and provide the name or query description of the target tool. You can also set task parameters and the enabled status.

List Tasks

List all configured tasks and their status information.

Get Task Details

Get detailed information through the task ID, including the task name, execution plan, target tool, etc.

Update a Task

Update the information of an existing task, including the task name, execution plan, target tool (by exact name or fuzzy description), parameters, and enabled status.

Enable/Disable a Task

You can start or stop a task to flexibly control its execution status.

Delete a Task

Permanently delete the specified task.

Manually Execute a Task

Manually trigger a task to execute immediately, which is convenient for testing and emergency handling.

🔧 Technical Details

• Programming Language: TypeScript
• Runtime Environment: Bun.js

📚 Configuration Information

• Log configuration is located in src/utils/logger.ts.
• Task scheduling definitions are stored in ~/.trash - cleaner/schedules.json in the user's directory.

📚 Development Guide

(Specific development specifications and process descriptions will be added here)