🗑️ Recycle Bin MCP

English | Chinese

A cross-platform recycle bin cleaning MCP (Model Context Protocol) service, supporting Windows, macOS, and Linux systems. 🚀

Features

• 🗑️ Cross-Platform Support: Supports Windows Recycle Bin, macOS Trash, and Linux Trash
• 🔍 Information Query: Get the number of files and space usage in the recycle bin
• 📋 Content List: List all files and folders in the recycle bin
• 🧹 Safe Emptying: Provides a confirmation mechanism for emptying the recycle bin
• 🛡️ Error Handling: Comprehensive error handling and logging

📦 Installation

⚡ Prerequisites

• Node.js 16+
• pnpm (recommended) or npm

📥 Install Dependencies

bash
pnpm install

🔨 Build the Project

bash
pnpm run build

🚀 Usage

🛠️ Development Mode

bash
pnpm run dev

🏭 Production Mode

bash
pnpm run start

🍒 Using in Cherry Studio

Cherry Studio is an AI client that supports the MCP protocol. To use this recycle bin cleaning service in Cherry Studio:

1️⃣ Configure MCP Service

Add the MCP service configuration in Cherry Studio's settings:

json
{
"mcpServers": {
"recycle-bin-cleaner": {
"command": "node",
"args": ["/path/to/recycle-bin-mcp/dist/index.js"],
"env": {}
}
}
}

Note: Replace /path/to/recycle-bin-mcp with the actual path to your project.

2️⃣ Restart Cherry Studio

After configuring, restart Cherry Studio to load the MCP service.

3️⃣ Use the Recycle Bin Tool

In Cherry Studio's conversation, you can directly use the following commands:

• View Recycle Bin Information:

  Please check the information of the recycle bin

• List Recycle Bin Contents:

  Please list all files in the recycle bin

• Empty Recycle Bin:

  Please help me empty the recycle bin

Cherry Studio will automatically call the corresponding MCP tool to perform these operations.

4️⃣ Safety Prompt

When using the empty recycle bin feature in Cherry Studio, the system will ask for confirmation. Please read the prompt carefully to ensure you really want to permanently delete all files in the recycle bin.

🛠️ MCP Tools

This service provides the following MCP tools:

1. empty_recycle_bin

Empties all files in the local recycle bin/trash.

Parameters:

• confirm (boolean, required): Confirm whether to empty the recycle bin, must be true

Example:
json
{
"confirm": true
}

2. get_recycle_bin_info

Gets the file occupancy information of the local recycle bin/trash.

Parameters: None

Returned Information:

• Number of files
• Number of folders
• Total number of items
• Occupied space size

3. list_recycle_bin_contents

Lists all files and folders in the recycle bin/trash.

Parameters:

• show_details (boolean, optional): Whether to show detailed information (file size, modification time, etc.), default is false

💻 Platform Support

🪟 Windows

• Supports system recycle bin
• Uses PowerShell commands for operations
• Supports multi-drive recycle bins

🍎 macOS

• Supports user trash (~/.Trash)
• Native file system operations
• Supports recursive deletion of files and folders

🐧 Linux

• Supports XDG standard trash (~/.local/share/Trash)
• Compatible with major Linux distributions
• Supports metadata according to the Trash specification

📁 Project Structure

recycle-bin-mcp/
├── src/
│ ├── index.ts # Main server file
│ └── tools/
│ ├── base.ts # Base tool class
│ ├── factory.ts # Tool factory class
│ ├── types.ts # Type definitions
│ ├── windows.ts # Windows implementation
│ ├── macos.ts # macOS implementation
│ └── linux.ts # Linux implementation
├── dist/ # Compiled output directory
├── package.json
├── tsconfig.json
└── README.md

👨‍💻 Development

📜 Script Commands

• pnpm run build - Compile TypeScript code
• pnpm run start - Run compiled code
• pnpm run dev - Run in development mode- pnpm run test - Run tests (to be implemented)

➕ Adding Support for New Platforms

1. Create a new platform implementation file under the src/tools/ directory.
2. Implement the RecycleBinTool interface.
3. Add platform detection and instantiation logic in factory.ts.

🔒 Security Precautions

⚠️ Important Notice:

• The operation of emptying the recycle bin is irreversible, and files will be permanently deleted.
• This tool requires a confirmation parameter (confirm: true) to execute the emptying operation.
• It is recommended to use get_recycle_bin_info to check the contents of the recycle bin before proceeding.
• Ensure you have sufficient permissions to access the system's recycle bin.

📄 License

ISC License

🤝 Contributions

Issues and Pull Requests are welcome!

📝 Changelog

v1.0.0

• Initial release
• Supports three major platforms: Windows, macOS, and Linux
• Provides functions for querying recycle bin information, listing contents, and emptying the bin
• Full MCP protocol support