Metadata-Version: 2.4
Name: diskclean-mcp
Version: 0.1.0
Summary: MCP server for diskclean.sh — agent-driven Mac disk cleanup
Project-URL: Homepage, https://github.com/matigumma/macbook-always-run-out-of-disk-space
Project-URL: Issues, https://github.com/matigumma/macbook-always-run-out-of-disk-space/issues
Author: Mati Gummá
License-Expression: MIT
Keywords: claude,disk-cleanup,macos,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# diskclean-mcp

MCP server that wraps [`diskclean.sh`](../diskclean.sh), letting agents like Claude Desktop, Claude Code, or any MCP client scan and clean a Mac's reclaimable disk space — with safety guardrails baked in.

## Tools exposed

| Tool | Returns | Notes |
|---|---|---|
| `scan_disk()` | `{ disk, items: [...] }` | Read-only. Items include stable `id`, size, risk level, path. |
| `clean_items(ids, mode, confirm_risky)` | `{ results, summary }` | Destructive. Defaults to Trash; risky items gated by flag. |
| `disk_status()` | `{ total, used, available }` | Cheap, no full scan. Good for before/after checks. |

## Quick start (uvx, once published)

```bash
uvx diskclean-mcp
```

> Not yet on PyPI — for now, use the **dev install** below.

### Add to Claude Desktop

```json
{
  "mcpServers": {
    "diskclean": {
      "command": "uvx",
      "args": ["diskclean-mcp"]
    }
  }
}
```

### Add to Claude Code

```bash
claude mcp add diskclean -- uvx diskclean-mcp
```

## Dev install (from this repo)

```bash
cd mcp/
uv venv
uv pip install -e .
diskclean-mcp                  # runs on stdio — test with an MCP inspector
```

To register the local server with Claude Code:

```bash
claude mcp add diskclean -- uv --directory /absolute/path/to/repo/mcp run diskclean-mcp
```

For Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "diskclean": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/repo/mcp", "run", "diskclean-mcp"]
    }
  }
}
```

## Safety model (how an agent should use this)

1. **Scan first.** Call `scan_disk()` and present a summary to the user (totals by risk level, biggest items). Never auto-clean.
2. **Get explicit consent** before calling `clean_items()`. Quote item names and sizes.
3. **Default to Trash.** `mode="trash"` is recoverable. Only pass `mode="delete"` if the user explicitly says so.
4. **Risky items need double opt-in.** Items with `risk="risky"` (browsers, WhatsApp, Downloads, Android SDK) are skipped unless you pass `confirm_risky=True`. Don't pass this flag without the user confirming.
5. **Sudo-required items will fail** in non-interactive mode. Surface their `command` field so the user can run them manually.
6. **Verify after.** Call `disk_status()` after cleanup to confirm space was freed. Trash items still occupy space until the Trash is emptied.

## Configuration

| Env var | Purpose |
|---|---|
| `DISKCLEAN_SCRIPT` | Override the path to `diskclean.sh` (otherwise auto-discovered: bundled in wheel, or sibling of `mcp/` in dev). |

## How it works

The server is a thin wrapper around `diskclean.sh`:

```
agent → MCP tool call → server.py → bash diskclean.sh --json | --execute → JSON → agent
```

All scanning logic lives in the bash script (single source of truth). The Python layer handles MCP protocol, argument validation, and safety messaging. Adding a new scan category means editing `diskclean.sh` only — the MCP server picks it up automatically via the dynamic item list.

## License

MIT — same as the parent project.
