# Magic Wand 🪄

**A Paint.NET-style magic wand that an AI can use.** Point Claude (or any
MCP-capable agent) at an image, and it removes the background the way a
careful human would: click, look at the result, adjust tolerance, zoom in,
fix mistakes, verify, save — with a live window on your desktop showing
every step as it happens. You can grab the mouse and click alongside it.

![demo](docs/demo.png)

## Why this exists

Fully automatic background removers fail on hard images (white flowers on
white paper, thin stems, soft watercolor edges) and give you no way to fix
the result. A human with a magic wand tool gets it right because they can
*see* what each click did. This gives an AI agent the same loop: every tool
call returns a rendered view of the canvas, so the model inspects its own
work before deciding the next step.

## Features

- **Wand selection** — tolerance-based flood fill, contiguous or global,
  add/subtract ops, rect-scoped clicks, live tolerance re-run
- **Multiple canvases** — parallel agents each get their own image and their
  own live viewer window (auto-tiled on screen)
- **Vision-first API** — every mutation returns the updated view plus a
  `+/- px` delta and changed-region bbox
- **Precision helpers** — `probe` (is this pixel paper or pale paint?),
  `inspect` (pixel-accurate zoom with a coordinate grid and a
  "matches background" highlight), `sweep_paper` (grab every trapped
  background pocket in one call, with size caps and exclusion rects),
  `peel_paper` (iteratively remove every leftover a viewer would actually
  see), `unselect_region`
- **Built-in QA** — `qa_check` audits the result against the pristine
  original: leftover background and possible artwork loss, with per-region
  visibility verdicts; `save_png` re-runs the audit on save
- **Human-friendly windows** — mouse wheel zoom, right-drag pan, manual
  clicks, slider, undo; everything you do is visible to the agent too
- **Undo everything** — selections and deletes alike, with labeled history

## Install

```bash
git clone https://github.com/nathandstory/magic-wand
cd magic-wand
pip install -r requirements.txt
```

Requires Python 3.10+ with tkinter (included in the standard Windows/macOS
Python installers).

## Use with Claude Code

```bash
claude mcp add magic-wand -- python /path/to/magic-wand/main.py
```

or add it to your MCP config manually:

```json
"magic-wand": {
  "type": "stdio",
  "command": "python",
  "args": ["/path/to/magic-wand/main.py"]
}
```

Then ask Claude: *"open flower.png with the magic wand and remove the
background"*. The viewer window opens automatically; watch, or intervene
with your own clicks (the agent sees your edits on its next look).

## Use as a plain GUI app

```bash
python main.py image.png
```

No MCP client required — it's a small standalone wand editor.

## Tool reference

| Tool | What it does |
|---|---|
| `open_image` | load a file onto a named canvas + open its window |
| `wand` | flood-fill select at (x,y); tolerance, contiguous/global, add/subtract, `within` rect, region-size cap |
| `set_tolerance` | re-runs the last click live at a new tolerance (add/subtract included) |
| `sweep_paper` | select every trapped background-colored pocket ≤ N px, with paint-safety guards |
| `peel_paper` | post-delete: iteratively remove every leftover a viewer would see |
| `probe` | color, selection state, and distance-from-background for one pixel |
| `inspect` | zoomed crop with original-coordinate grid + match highlighting |
| `grow_selection` / `invert_selection` / `clear_selection` / `unselect_region` | selection algebra |
| `delete_selection` | selected pixels → transparency (antialiased), then auto-clear |
| `qa_check` | audit vs the original: leftover background, artwork loss, visibility verdicts |
| `save_png` | save with transparency (+trim), includes a QA audit |
| `undo` | undo anything, with a label of what was reverted |
| `list_canvases` / `close_canvas` / `show_window` | canvas management |

## How it works

One `WandModel` per canvas holds the image, selection mask, and history;
the MCP server (FastMCP over stdio) mutates models and returns rendered
views; a Tk viewer polls each model ~12×/s so the window always shows the
truth. The GUI never owns state — agent calls and your manual clicks go
through the same model, which is why you can co-edit with the AI.

Selection semantics follow Paint.NET: tolerance is a normalized RGBA
distance, flood fill is 8-connected, deletes are antialiased with a ~1px
soft edge. The QA layer compares against a pristine copy of the original
and estimates the background color from the image border — see
`magicwand/core.py` for the details; it's readable.

## Tests

```bash
python tests/test_core.py        # headless algorithm tests
python tests/drive_mcp.py ...    # end-to-end MCP stdio driver
```

## License

MIT — see [LICENSE](LICENSE).