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]"

Related MCP server: Local AI MCP

配置

cp .env.example .env

按需编辑 .env。关键项：

更完整注释见 .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 预估）：

各 target 策略摘要

开发

source .venv/bin/activate
pytest -v

安全提示

1. 先 plan_cleanup，确认候选后再执行。

2. 生产/共享机器上保持 MACCLEAN_ALLOW_EXECUTE=false，仅在明确需要时打开。

3. Maven 清理按版本新旧，不分析项目是否仍引用旧版本。

4. pnpm 默认保守，避免误删导致大规模重下。