cacheout mcp
用于macOS磁盘缓存管理的MCP服务器——让AI代理按需释放磁盘空间。
为什么
当你在Mac Mini或任何macOS机器上运行AI代理（OpenClaw、Claude Code等）时，磁盘压力会悄无声息地降低性能。交换抖动、构建失败、Docker OOM——所有这些都是由于开发人员缓存中锁定的空间不足造成的。
cacheout mcp 为您的代理提供了一套实时检测和修复磁盘压力的工具：
Agent detects 2 GB free → calls cacheout_smart_clean(target_gb=15) → 15 GB freed in 3 seconds三种执行模式
| 模式 | 何时 | 如何工作 |
|---|---|---|
| 套接字 | 使用Unix套接字运行的Cacheout守护进程 | 连接到守护进程以获取实时数据、趋势分析、健康评分 |
| 应用 | Cacheout.app已安装，没有正在运行的守护进程 | 委托给Cacheout CLI二进制文件(--cli 旗帜） |
| 独立 | 无Cacheout.app（无头服务器） | 直接通过Python清理缓存，读取sysctl获取内存统计信息 |
模式为 自动检测 启动时（套接字→ app → 独立）。覆盖 CACHEOUT_MODE=standalone 或 CACHEOUT_MODE=app.
安装
# From PyPI (when published)
pip install cacheout-mcp
# From source
cd cacheout-mcp
pip install -e .MCP配置
克劳德代码/克劳德桌面
增添 ~/.claude/claude_desktop_config.json 或者你的项目 .mcp.json:
{
"mcpServers": {
"cacheout": {
"command": "cacheout-mcp",
"env": {}
}
}
}OpenClaw/定制代理
{
"mcpServers": {
"cacheout": {
"command": "python",
"args": ["-m", "cacheout_mcp.server"],
"env": {
"CACHEOUT_MODE": "standalone"
}
}
}
}带紫外线（无需安装）
{
"mcpServers": {
"cacheout": {
"command": "uvx",
"args": ["cacheout-mcp"]
}
}
}工具
cacheout_get_disk_usage
检查当前磁盘空间。没有参数。
→ {"total": "500.1 GB", "free": "23.4 GB", "used_percent": 95.3}cacheout_scan_caches
扫描所有缓存目录和报告大小。可选过滤器：
categories：要扫描的蛞蝓列表（全部省略）min_size_mb：仅显示此大小以上的类别
→ {"total_cleanable": "45.2 GB", "categories": [{"slug": "xcode_derived_data", "size_human": "15.0 GB", ...}]}cacheout_clear_cache
按slug明确具体类别。需要明确的类别列表。
categories: 必需 蛞蝓列表dry_run：预览而不删除
← {"categories": ["xcode_derived_data", "homebrew_cache"], "dry_run": false}
→ {"total_freed": "18.2 GB", "results": [...]}cacheout_smart_clean
代理的主要工具。 指定您需要多少空间；它首先清除最安全的缓存。
target_gb: 必需 --要释放多少GBdry_run：预览模式include_caution：包括Docker和其他高风险类别free_memory：在磁盘清理后也运行内存清除（添加memory_freed,purge_result回应）
← {"target_gb": 10.0}
→ {"target_met": true, "total_freed_human": "12.3 GB", "disk_after": {"free_gb": 17.5}}cacheout_status
服务器状态、模式和可用类别。
cacheout_get_memory_stats
检查RAM、交换、内存压力和内存层。没有参数。
→ {"total_physical_mb": 16384.0, "memory_tier": "comfortable", "estimated_available_mb": 6096.0, ...}cacheout_get_process_memory
列出最消耗内存的进程。可选的 top_n 和 sort_by 参数。 退回信封： {mode, capabilities, data: {processes, count, sort_by_applied}, partial}.
cacheout_get_compressor_health
检查macOS内存压缩比、压缩/解压缩率和抖动检测。没有参数。 退回信封： {mode, capabilities, data: {compressor_ratio, thrashing, ...}, partial}.
cacheout_memory_intervention
运行记忆干预。所需参数：
intervention_name：规范名称（例如。，"purge")confirm:false对于模拟运行预览，true执行
退回信封： {mode, capabilities, data: {dry_run, intervention, ...}, partial}.
cacheout_system_health
磁盘+内存+警报健康检查，0-100分。没有参数。 在套接字模式下，从守护进程获取。在独立模式下，进行本地计算。
cacheout_check_alerts
读取监视器警报（接近零成本文件读取）。可选的 acknowledge 参数。
cacheout_get_recommendations
获取预测性内存/磁盘建议。套接字模式包括基于趋势的类型 (exhaustion_imminent, compressor_degrading).Standalone仅返回快照类型。
cacheout_configure_autopilot
验证并应用自动驾驶仪/监视器配置。必需 config 参数（带字典 version, enabled，可选 rules/webhook/telegram).这是一个写/验证/应用工具。
缓存类别（共23个）
| 蛞蝓 | 风险 | 它能清除什么 |
|---|---|---|
xcode_derived_data | 安全 | 构建工件、索引 |
uv_cache | 安全 | 快速Python安装程序缓存 |
homebrew_cache | 安全 | 下载的瓶子/皮球 |
npm_cache | 安全 | npm包缓存 |
yarn_cache | 安全 | 纱线包缓存 |
pnpm_store | 安全 | pnpm内容可寻址存储 |
bun_cache | 安全 | 包管理器缓存 |
typescript_cache | 安全 | TypeScript编译器+Next.js SWC缓存 |
playwright_browsers | 安全 | Playwright浏览器二进制文件 |
cocoapods_cache | 安全 | CocoaPods规格和吊舱 |
node_gyp_cache | 安全 | 原生Node.js插件头 |
prisma_engines | 安全 | Prisma ORM查询引擎二进制文件 |
swift_pm_cache | 安全 | Swift包管理器缓存 |
gradle_cache | 安全 | Gradle构建缓存 |
pip_cache | 安全 | Python pip缓存 |
chatgpt_desktop_cache | 安全 | ChatGPT桌面应用程序缓存 |
vscode_cache | 安全 | VS代码更新和扩展 |
electron_cache | 安全 | 共享电子框架缓存 |
browser_caches | 评论 | Brave/Chrome缓存的网络内容 |
xcode_device_support | 查看 | iOS设备调试符号 |
simulator_devices | 查看 | iOS/watchOS模拟器数据（使用xcrun） |
torch_hub | 回顾 | PyTorch模型（重新下载速度慢） |
docker_disk | 警告 | Docker虚拟磁盘（所有映像/容器） |
智能清洁优先级
当 smart_clean 被调用后，类别将按以下顺序进行清理：
- 安全 类别，按clean_priority排序（首先构建工件）
- 审查 类别（浏览器缓存、设备支持）
- 小心 类别（Docker）——仅当
include_caution=true
一旦停止 target_gb 被释放。
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
CACHEOUT_MODE | 自动检测 | 强制 standalone 或 app 模式 |
CACHEOUT_BIN | 自动检测 | 缓存二进制文件的路径 |
将CLI添加到Cacheout.app
如果您维护Cacheout Swift应用程序，请添加 CLIHandler.swift 文件到您的源 并更新 CacheoutApp.swift 检查 CLIHandler.shouldHandleCLI() 在init上。 这使得 Cacheout --cli scan, Cacheout --cli clean等，用于应用模式集成。
许可证
麻省理工学院