内容
# trash-cleaner-mcp-server
[中文 README](./README_zh.md)
一个桌面 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`（布尔值，默认：true），`olderThan`（整数，可选 - 天数）。
* `cleanTempFiles`：清理系统临时文件。
* 选项：`dryRun`（布尔值，默认：true），`olderThan`（整数，可选，默认：7 天）。
* `cleanAppRemnants`：扫描并清理已卸载应用程序留下的配置/缓存文件。
* 选项：`appName`（字符串，可选 - 部分名称匹配），`dryRun`（布尔值，默认：true）。
* `smartCleanSystem`：根据预定义级别执行系统清理（目标常见垃圾位置）。
* 选项：`cleanLevel`（枚举："safe"、"normal"、"deep"，默认："safe"），`dryRun`（布尔值，默认：true）。
**跨平台工具（扫描、文件系统、操作系统）：**
* `cleanVSCodeExtensions`：清理过时版本的 VS Code（以及兼容编辑器如 VSCodium、Cursor）扩展。
* 选项：`editorPath`（字符串，可选 - 特定编辑器扩展的路径，默认：扫描所有已知位置），`dryRun`（布尔值，默认：true）。
* `reportVSCodeExtensions`：生成报告，列出可以清理的过时 VS Code 扩展。
* 选项：`editorPath`（字符串，可选）。
* `findLargeFiles`：查找目录中超过指定大小的文件。
* 选项：`path`（字符串），`minSize`（整数，默认：100MB），`maxDepth`（整数，默认：3）。
* `scanFullSystem`：扫描整个系统的文件结构（尊重排除项）以报告空间使用情况。
* 选项：`excludePaths`（字符串数组，可选），`maxDepth`（整数，默认：10）。
* `scanDirectory`：分析特定目录中的内容和大小分布。
* 选项：`path`（字符串），`excludePaths`（字符串数组，可选），`maxDepth`（整数，默认：10），`includeSubdirs`（布尔值，默认：true）。
* `getFolderSize`：计算并返回文件夹的总大小。
* 选项：`path`（字符串）。
* `listDirectory`：列出指定路径中的文件和子目录。
* 选项：`path`（字符串），`showHidden`（布尔值，默认：false）。
* `findFiles`：在目录中搜索匹配特定模式的文件（支持通配符）。
* 选项：`path`（字符串），`pattern`（字符串），`maxDepth`（整数，默认：5）。
* `analyzeDirectory`：提供目录中文件类型和大小分布的统计信息。
* 选项：`path`（字符串），`includeSubdirs`（布尔值，默认：true）。
* `getFileHash`：计算文件的 MD5、SHA1 或 SHA256 哈希值。
* 选项：`path`（字符串），`algorithm`（枚举："md5"、"sha1"、"sha256"，默认："md5"）。
* `getFileType`：检索基本文件信息，包括 MIME 类型。
* 选项：`path`（字符串）。
* `deletePath`：删除指定的文件或文件夹（需要明确确认，并对危险路径进行额外检查）。
* 选项：`path`（字符串），`confirm`（布尔值，必须为 true），`dangerConfirm`（布尔值，可选 - 对于潜在风险的删除是必需的）。
* `checkPathExists`：检查给定路径是否存在，并识别它是文件还是目录。
* 选项：`path`（字符串）。
* `getSystemType`：返回操作系统标识符（例如，'darwin'、'win32'、'linux'）。
**审计工具：**
* `viewAuditLog`：查看应用程序主日志文件（`combined.log`）中的最新行。
* 选项：`lines`（整数，默认：100，最大：1000）。
* `clearAuditLog`：**删除**主应用程序日志文件（`combined.log`）。需要确认。
* 选项：`confirm`（布尔值，必须为 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：**
```sh
bunx @childhoodandy/trash-cleaner-mcp-server
# 或使用自动安装
bunx -y @childhoodandy/trash-cleaner-mcp-server
```
**使用 npm：**
```sh
npx @childhoodandy/trash-cleaner-mcp-server
# 或使用自动安装
npx -y @childhoodandy/trash-cleaner-mcp-server
```
## 安装
```bash
# 克隆仓库
git clone <repository-url>
cd trash-cleaner-mcp-server
# 安装依赖（使用 Bun）
bun install
```
## 运行服务器
```bash
bun start
```
## 配置
* 日志配置在 `src/utils/logger.ts` 中。
* 定时任务定义存储在 `~/.trash-cleaner/schedules.json` 中。
## 开发
*(开发指南在此...)*
MCP 市场