mcp-macclean

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

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

maven
pnpm
npm
yarn
pip
uv
go
macos_caches

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

调用 execute_cleanup 时 confirm=true
.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_MAX_CANDIDATES`	plan/execute 明细最多返回条数（按体积 Top-N）	`25`
`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`
`MACCLEAN_MACOS_CACHES_PATH`	`~/Library/Caches` 扫描根	`~/Library/Caches`
`MACCLEAN_MACOS_CACHES_COMMAND_TIMEOUT`	官方命令超时（秒）	`300`

更完整注释见 .env.example。

MCP 注册示例

Claude Code / MCP client 配置示例：

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

注意：

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

也可使用 venv 入口脚本启动 MCP：

.venv/bin/macclean-mcp
# 或
.venv/bin/python -m macclean.server

命令行入口（非 MCP）

安装后可用 CLI 直接 list / plan / execute，逻辑与 MCP 工具一致，门禁相同。

# 可编辑安装后
.venv/bin/macclean list
.venv/bin/macclean plan --targets maven,macos_caches
.venv/bin/macclean execute --targets macos_caches --confirm

# 未安装入口时
.venv/bin/python -m macclean list --json

常用参数：

参数	说明
`--targets a,b`	逗号分隔 targets；省略则用配置默认
`--path PATH`	仅单 target 时覆盖缓存路径
`--json`	JSON 输出
`--env-file PATH`	指定 `.env`
`--confirm`	`execute` 必填
`--mode force_store`	pnpm 强制清 store
`--go-mod` / `--no-go-mod`	Go module cache
`--go-build` / `--no-go-build`	Go build cache

示例：

.venv/bin/macclean list --targets macos_caches
.venv/bin/macclean plan --targets macos_caches --json
# 确认 .env 中 MACCLEAN_ALLOW_EXECUTE=true 后再执行
.venv/bin/macclean execute --targets macos_caches --confirm

工具说明

`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

输出限制：

size_bytes=0 的候选不展示
明细列表默认只返回体积最大的 25 条（MACCLEAN_MAX_CANDIDATES）
candidate_count / reclaimable_* 仍是全量统计；被截断时 message 会注明 showing top N of M

`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`（按体积 Top-N，默认 25）
`results[].deleted_file_count`	该 target 真实删除文件数

说明：deleted 明细可能被截断，但 deleted_count / reclaimed_* / 响应级 total 字段始终是全量真实删除统计。

各 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 需显式开启
macos_caches	规则识别 `~/Library/Caches` 开发工具项；Homebrew 走 `brew cleanup`，其它白名单目录 `delete_children`；未知不删

开发

source .venv/bin/activate
pytest -v

安全提示

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

mcp-macclean

mcp-macclean

安装

配置

MCP 注册示例

命令行入口（非 MCP）

工具说明

`list_caches`

`plan_cleanup`

`execute_cleanup`

各 target 策略摘要

开发

安全提示

Latest Blog Posts

MCP directory API