# mcp-macclean

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

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

- `maven`
- `pnpm`
- `npm`
- `yarn`
- `pip`
- `uv`
- `go`
- `macos_caches`

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

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

## 安装

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

## 配置

```bash
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 配置示例：

```json
{
  "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 入口脚本启动 MCP：

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

## 命令行入口（非 MCP）

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

```bash
# 可编辑安装后
.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 |

示例：

```bash
.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`；未知不删 |

## 开发

```bash
source .venv/bin/activate
pytest -v
```

## 安全提示

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