# relief-mcp

An MCP server that turns parts of a photo into a layered 3D relief — like a museum bas-relief — that tilts
with the pointer. Claude looks at the photo, picks the parts with boxes, you approve the overlay it shows
you, and the server writes one GLB per part plus `relief.html`, a single self-contained file you can open in
any browser — no server needed, no dependencies to install to view it.

## Install

With [Claude Code](https://docs.claude.com/en/docs/claude-code):

```bash
claude mcp add relief -- npx -y @noon0ri/relief-mcp
```

### From source

```bash
git clone https://github.com/noon0ri/relief-mcp.git
claude mcp add relief -s user -- node /path/to/relief-mcp/mcp/server.mjs
```

Then ask, for example: "Make a relief of the dog and the person in ~/Pictures/dog.jpg".

## What you need

- Node 20.9 or newer.
- The first call downloads the segmentation and depth models, about 89 MB, cached at `~/.cache/relief-mcp`
  (override with `RELIEF_MCP_CACHE`). Later calls use the cache.
- Installing the package pulls in about 530 MB of dependencies (`onnxruntime-node` and `sharp` are most of
  it). The server uses about 1.4 GB of memory while it runs.

## How it works / tools

| Tool | What it does |
|---|---|
| `open_image(image)` | Loads the photo, returns it with a coordinate grid and its working size (long side at most 1024 px). |
| `segment_parts(image, parts, open?)` | Selects parts, front-most first. Each part is `{ box: [x0, y0, x1, y1], include?, exclude? }`. Returns an overlay and per-part warnings, and opens the overlay image on your screen (`open`, default true) so you can check it before anything is built. |
| `make_relief(image, parts, out_dir?, open?)` | Writes `part-N.glb`, `relief.html` and `relief.json` to `<photo folder>/<photo name>-relief/` and opens `relief.html`. Refuses if the parts weren't just picked with `segment_parts`, and asks you to confirm in a dialog (MCP elicitation) before it writes anything — decline or cancel and nothing is written. |

The intended loop: `segment_parts` shows you an overlay (each part tinted and numbered) and Claude describes
what it picked; only after you say it looks right does Claude call `make_relief`, and you get one more chance
to confirm in the dialog before files are written.

## Privacy

Your photo never leaves your computer. The only thing downloaded over the network is the model files, from
Hugging Face, once, and cached locally. Results are written next to the photo, in `<photo folder>/<photo
name>-relief/`. The overlay image and a small log of confirmation-dialog answers are written to a temp
folder (`elicit.log` and the overlay JPEG) so you can review them later.

## Tested / not tested

Checked on macOS (arm64) with Claude Code 2.1.278. Claude Desktop, Windows and Linux have not been run.
`relief.html` was checked in Chrome (headless) and confirmed to open correctly in Safari; other browsers are
untested.

## License

MIT. The two models it downloads at runtime are each licensed separately and are not redistributed by this
package: [`facebook/sam2.1-hiera-tiny`](https://huggingface.co/facebook/sam2.1-hiera-tiny) and
[`depth-anything/Depth-Anything-V2-Small-hf`](https://huggingface.co/depth-anything/Depth-Anything-V2-Small-hf),
both Apache-2.0.