# pureref-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an AI assistant (Claude Code, Claude Desktop or any MCP client) work with [PureRef](https://www.pureref.com) 2.x on Windows. It can build reference boards from folders, export them, and drive a live PureRef window: every menu action, the mouse, notes, pasting files and dialogs.

PureRef has no API. Its command line has six commands (`load`, `clearScene`, `save`, `exportScene`, `exportImages`, `exit`), and the `.pur` format is closed. This server combines two channels to get the rest.

> Unofficial project, not affiliated with PureRef / Idyllic Pixel. Tested with PureRef 2.1.3 on Windows 10.

## Install

Requires Windows, Python 3.11+ and PureRef 2.x.

```
git clone https://github.com/Flamtiwork/pureref-mcp
cd pureref-mcp
uv venv .venv
uv pip install --python .venv\Scripts\python.exe -e .
```

Register it with Claude Code:

```
claude mcp add pureref -s user -- "C:\path\to\pureref-mcp\.venv\Scripts\pureref-mcp.exe"
```

Or in any MCP client config:

```json
{
  "mcpServers": {
    "pureref": {
      "command": "C:\\path\\to\\pureref-mcp\\.venv\\Scripts\\pureref-mcp.exe",
      "env": { "PUREREF_EXE": "C:\\Program Files\\PureRef\\PureRef.exe" }
    }
  }
}
```

`PUREREF_EXE` is optional. It defaults to `C:\Program Files\PureRef\PureRef.exe`.

## 1. Headless boards (CLI)

These tools run a separate, minimized PureRef process that runs the commands and exits. No focus is stolen.

| Tool | What it does |
|---|---|
| `board_build` | New board from a folder: root images first, then each subfolder as a section with a title card, laid out in rows |
| `board_add_images` | Add images or folders to an existing board starting at (x, y) |
| `board_export` | Whole board as one image (`exportScene`) |
| `board_export_images` | Every image of the board as a separate file (`exportImages`) |
| `board_preview` | Render the board and return a preview image |
| `board_merge` | Merge several boards (only image files carry over) |
| `pureref_cli` | Raw CLI commands |

PureRef quirks handled for you:
- after `load;<file.pur>` PureRef can only `save` back to the same path, so "save as" copies the file first;
- long command lists are split across several runs (the Windows command line has a length limit);
- headless runs restore PureRef's Recent files list afterwards.

## 2. Live window

The server gives every PureRef action (93 of them: the whole context menu and the Keyboard shortcuts page) an extra alias shortcut on **F13–F24** with modifiers. No physical keyboard has these keys, so the aliases never clash with your own shortcuts.

The aliases are written to `%APPDATA%\PureRef\PureRef.ini`, section `[Key_Bindings]`, as `<Action_Id>1Shortcut=Ctrl+F13`:
- a backup of the original file is kept as `PureRef.ini.pureref_mcp.bak`;
- they show up in PureRef's settings as extra aliases;
- PureRef reads the ini only at startup, so restart any window that was open before `setup_bindings`.

To run an action, the server brings PureRef to the front, presses the alias and gives focus back to the window you were in.

| Tool | What it does |
|---|---|
| `setup_bindings` | Write the alias shortcuts (done automatically by `live_open`) |
| `live_open` | Start a new PureRef window (own process), optionally with files |
| `live_attach` | Attach to a PureRef window that is already open |
| `live_status` | Windows, open dialogs, alias state |
| `live_actions` / `live_action` | List actions / run one by id: `Select_All`, `Optimal`, `Normalize_Area`, `Flip_Image_Horizontally`, `Stack`, `Group`, `Grayscale`, `Focus_Canvas`, `Undo` and others |
| `live_screenshot` | Screenshot of the window with any open dialogs; mouse coordinates use this image |
| `live_mouse` | Click, double-click, drag, wheel, with Ctrl/Shift/Alt held |
| `live_keys` / `live_type` | Raw keys (pywinauto syntax) / type text through the clipboard (any language) |
| `live_add_images` | Paste image files at the cursor |
| `live_note` | Text note at the cursor |
| `live_save` / `live_load` | Save (also save as) / open a `.pur` |
| `live_file_dialog` | Fill an open Windows file or folder dialog and confirm |
| `live_export` | Save, then render the board to PNG headlessly |
| `live_close` | Close: a window started by the server ends at once; a window you opened yourself gets PureRef's Close action, which asks about unsaved changes |

PureRef's own dialogs (Export images, unsaved changes) are Qt windows with no accessibility. After each call the server lists them in the `dialogs` field, and the assistant handles them from a screenshot with `live_mouse` and `live_type`.

What did not work, and why the design looks like this:
- the **Command Palette** (Ctrl+Shift+P) closes without running the command on synthetic input, so aliases are used instead;
- a **"System global"** binding (`Context=4`) does not fire these actions while PureRef is unfocused, so the window is focused for each action.

## Notes

- Windows only: it uses pywinauto, pywin32 and the Windows clipboard.
- Live tools move the mouse and focus for a moment. Don't type into other apps while an assistant is driving PureRef.
- Action ids were checked against PureRef 2.1.3. Other versions may rename some actions: if an action has no effect, look for its alias in PureRef's Settings → Keyboard shortcuts.

## License

MIT