trash-cleaner-mcp-server

trash-cleaner-mcp-server

中文 README

一款桌面 MCP 服务，提供扫描、分析和清理垃圾文件的工具，主要针对 macOS 进行了优化。

注意： 大多数清理工具（cleanAppCaches、cleanTempFiles、cleanAppRemnants、smartCleanSystem）专为 macOS 设计和测试。在其他系统上运行可能无法正常工作，或导致意外行为。

功能

• 跨平台：（计划中）支持 Windows、macOS、Linux。
• **智能扫描：**识别各种类型的垃圾文件（缓存、日志、临时文件等）。
• **选择性清理：**提供清理特定区域的工具，例如应用缓存、临时文件和应用残留。
• **VS Code 扩展管理：**提供查找和清理旧版或未使用 VS Code 扩展的工具。
• **文件系统实用工具：**提供目录分析、文件查找、大小计算、删除等工具。
• **系统信息：**检测基本操作系统信息。
• **审计日志：**通过 [Audit] 工具跟踪操作。
• **计划任务：**使用灵活的调度程序自动执行清理和其他任务。
  • 使用 cron 表达式或简单间隔定义任务。
  • 指定任意已注册工具来执行。
  • 通过模糊匹配，使用准确的工具名称（toolName）或自然语言查询（toolQuery）创建或更新任务。
  • 完整的任务管理（列表、详情、更新、启用/禁用、删除）。
  • 手动触发并跟踪执行历史。

可用工具（功能）

此服务通过 MCP 协议注册了多个可调用的工具：

macOS 清理工具（针对 macOS 优化）：

• macOSWarning：如果在非 macOS 系统上运行，则显示警告。
• cleanAppCaches：清理各种应用缓存（用户缓存、已保存的应用状态）。
  • 选项：dryRun（bool，默认值：true）、olderThan（int，可选 - 天数）。
• cleanTempFiles：清理系统临时文件。
  • 选项：dryRun（bool，默认值：true）、olderThan（int，可选，默认值：7 天）。
• cleanAppRemnants：扫描并清理已卸载应用遗留的配置和缓存文件。
  • 选项：appName（string，可选 - 部分名称匹配）、dryRun（bool，默认值：true）。
• smartCleanSystem：根据预定义级别执行系统清理（针对常见的垃圾文件位置）。
  • 选项：cleanLevel（enum："safe"、"normal"、"deep"，默认值："safe"）、dryRun（bool，默认值：true）。

跨平台工具（扫描、文件系统、操作系统）：

• 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 中。

开发

（开发指南保留在此处……）