mcp-macclean

本机多包管理器缓存清理 MCP 服务。

支持统一发现、预览并（经确认后）清理：

• maven
• pnpm
• npm
• yarn
• pip
• uv
• go

默认安全策略：只预览，不删除。真正删除需要同时满足：

1. 调用 execute_cleanup 时 confirm=true
2. .env 中 MACCLEAN_ALLOW_EXECUTE=true

安装

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

配置

cp .env.example .env

按需编辑 .env。关键项：

配置	含义	默认
MACCLEAN_ALLOW_EXECUTE	是否允许真实删除	false
MACCLEAN_DEFAULT_TARGETS	默认 targets	全部
MACCLEAN_MAVEN_PATH	Maven 本地仓库父目录（含 repository）	~/.m2
MACCLEAN_NPM_CACHE	npm cache 根目录	~/.npm
MACCLEAN_YARN_CACHE	yarn cache，空则自动探测	空
MACCLEAN_PNPM_STORE	pnpm store，空则自动探测	空
MACCLEAN_PIP_CACHE	pip cache，空则自动探测	空
MACCLEAN_UV_CACHE	uv cache，空则自动探测	空
MACCLEAN_GO_MODCACHE	Go module cache	空
MACCLEAN_GO_BUILDCACHE	Go build cache	空
MACCLEAN_GO_CLEAN_MOD	默认是否清理 Go mod	false
MACCLEAN_GO_CLEAN_BUILD	默认是否清理 Go build	true

更完整注释见 .env.example。

MCP 注册示例

Claude Code / MCP client 配置示例：

{
  "mcpServers": {
    "macclean": {
      "command": "/绝对路径/mcp-macclean/.venv/bin/python",
      "args": ["-m", "macclean.server"],
      "cwd": "/绝对路径/mcp-macclean"
    }
  }
}

注意：

1. 必须使用虚拟环境里的 Python（或已 pip install -e . 的解释器），不要写裸的 python。在本机若 python 指向 pyenv 的 2.7，会立刻 No module named macclean，MCP 表现为 Connection closed。
2. command 与 cwd 请写绝对路径；~ 在部分 MCP 客户端中不会展开。

也可使用 venv 入口脚本：

.venv/bin/macclean

工具说明

list_caches

发现缓存位置与占用。

参数：

• targets：可选，如 ["maven","uv"]
• path：可选，仅单 target 时作为自定义路径

plan_cleanup

生成删除计划，不会删除任何文件。

参数：

• targets
• path
• options：
  • mode: default | force_store（pnpm）
  • go_mod / go_build
  • retain_latest（maven）

候选 path 为相对该 target 缓存根的路径，便于浏览与筛选，例如 Maven：

• 缓存根：~/.m2/repository
• 候选：com/example/demo/1.0.0-SNAPSHOT

execute_cleanup

执行清理。

参数：

• confirm：必须为 true
• targets / path / options

若 MACCLEAN_ALLOW_EXECUTE=false 或未确认，将拒绝执行。

成功执行后会返回真实删除统计（删除前实测，非 plan 预估）：

字段	含义
total_deleted_count	删除的候选根目录/条目数
total_deleted_file_count	真实删除的文件数
total_reclaimed_bytes / total_reclaimed_human	真实回收体积
results[].deleted	每项：path、file_count、size_bytes、size_human
results[].deleted_file_count	该 target 真实删除文件数

各 target 策略摘要

target	默认策略
maven	每个 groupId:artifactId 仅保留最新版本目录
npm	清理 ~/.npm/_cacache 内容
yarn	清理 yarn cache 内容
pnpm	默认只报告；mode=force_store 才清理 store 内容
pip	清理 pip cache 内容
uv	清理 uv cache 内容
go	默认清理 build cache；mod 需显式开启

开发

source .venv/bin/activate
pytest -v

安全提示

1. 先 plan_cleanup，确认候选后再执行。
2. 生产/共享机器上保持 MACCLEAN_ALLOW_EXECUTE=false，仅在明确需要时打开。
3. Maven 清理按版本新旧，不分析项目是否仍引用旧版本。
4. pnpm 默认保守，避免误删导致大规模重下。