macOS磁盘缓存管理工具

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

三种执行模式

模式为 自动检测 启动时（套接字→ 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: 必需 --要释放多少GB
• dry_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个）

智能清洁优先级

当 smart_clean 被调用后，类别将按以下顺序进行清理：

1. 安全 类别，按clean_priority排序（首先构建工件）
2. 审查 类别（浏览器缓存、设备支持）
3. 小心 类别（Docker）——仅当 include_caution=true

一旦停止 target_gb 被释放。

环境变量

将CLI添加到Cacheout.app

如果您维护Cacheout Swift应用程序，请添加 CLIHandler.swift 文件到您的源 并更新 CacheoutApp.swift 检查 CLIHandler.shouldHandleCLI() 在init上。 这使得 Cacheout --cli scan, Cacheout --cli clean等，用于应用模式集成。

许可证

麻省理工学院