# PureRef MCP

PureRef MCP is a Python MCP server for generating PureRef `.pur` boards from local image assets and structured ad-review data. It is designed for open-source workflows where an AI assistant can assemble visual reference boards, campaign moodboards, and A4-style creative review reports directly into a PureRef workspace.

The project currently focuses on static creative review workflows, especially saved Meta ad-library image sets with companion `ads-data.json` metadata.

## What It Does

- Creates native PureRef `.pur` files.
- Embeds local images into PureRef boards.
- Adds PureRef text items for copy, notes, ratings, personas, and stronger creative angles.
- Builds A4-style ad review artboards.
- Optionally renders report pages as image files first, then embeds those rendered pages into PureRef for more reliable layout.

## Languages And Runtime

- Python: server, MCP tools, PureRef file generation, image processing.
- PowerShell: local launcher script for Windows.
- PureRef `.pur`: generated board output format.

## Requirements

- Python 3.10 or newer is recommended.
- PureRef installed locally to open generated `.pur` files.
- Python dependencies from `requirements.txt`:
  - `fastmcp==3.4.2`
  - `Pillow==12.2.0`

## Setup

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## Running The MCP Server

### Stdio transport

Use stdio when connecting from a local MCP client that launches the server process directly.

```powershell
.\start-pureref-mcp.ps1
```

This runs:

```powershell
.\.venv\Scripts\python.exe .\pureref_server.py
```

### HTTP transport

Use HTTP-compatible transports when your MCP client connects to a running local server.

```powershell
.\start-pureref-mcp.ps1 -Transport http -BindAddress 127.0.0.1 -Port 8765
```

Equivalent direct command:

```powershell
.\.venv\Scripts\python.exe .\pureref_http_server.py --transport http --host 127.0.0.1 --port 8765
```

## Ports And Endpoints

The launcher defaults to:

- Host: `127.0.0.1`
- Port: `8765`
- Default script transport: `stdio`
- Supported launcher transports: `stdio`, `http`, `sse`, `streamable-http`

FastMCP provides the HTTP/SSE endpoints. With the default HTTP wrapper settings:

- Streamable HTTP endpoint: `http://127.0.0.1:8765/mcp`
- SSE endpoint: `http://127.0.0.1:8765/sse`
- SSE message endpoint: `http://127.0.0.1:8765/messages/`

This project does not define custom REST routes. It exposes MCP tools through FastMCP.

## MCP Tools

### `create_ad_moodboard`

Creates a native PureRef campaign moodboard from a list of local image paths, ad copy, and commentary.

Parameters:

- `output_path`: Absolute destination path ending in `.pur`.
- `image_paths`: Local image paths to embed.
- `ad_copy`: Text for ad copy variations or script notes.
- `commentary`: Strategy notes, critique, or design feedback.
- `image_labels`: Optional labels for each image.
- `cute_notes`: Optional secondary notes for each image.
- `columns`: Maximum image columns before wrapping. Default: `3`.
- `margin_percent`: Layout spacing as a percentage. Default: `0.05`.

### `create_static_ad_artboard_moodboard`

Builds A4-style PureRef artboards from a source folder containing `ads-data.json` and `static-images/`.

Expected input structure:

```text
source_dir/
  ads-data.json
  static-images/
    image-1.jpg
    image-2.png
```

Parameters:

- `source_dir`: Folder containing `ads-data.json` and `static-images/`.
- `output_path`: Destination `.pur` file.
- `columns`: Number of A4 pages per row in the PureRef canvas. Default: `3`.
- `margin_percent`: Spacing around artboards. Default: `0.05`.
- `export_artboards`: Placeholder flag for future export support. Default: `False`.
- `artboard_output_dir`: Optional folder prepared when `export_artboards` is enabled.

Current note: PDF export is not implemented. This tool writes `.pur` files.

### `create_rendered_static_ad_report`

Renders A4 report pages as image files first, then embeds those pages into a PureRef board. This is the most reliable option when text layout needs to look clean.

Parameters:

- `source_dir`: Folder containing `ads-data.json` and `static-images/`.
- `output_path`: Destination `.pur` file.
- `columns`: Number of rendered pages per row in the PureRef canvas. Default: `3`.
- `cover_asset_path`: Optional custom cover image.
- `watermark_asset_path`: Optional custom report background/watermark image.

Generated page images are written to:

```text
<output folder>/rendered-report-pages/
```

## Internal Function Breakdown

The public MCP tools are supported by smaller internal helpers:

- `_append_image`: Converts a local image to PNG bytes and appends it to a PureRef file with position, size, and layer metadata.
- `_append_text`: Appends a PureRef text item with position, scale, foreground/background colors, and layer metadata.
- `_wrap_lines`: Wraps text without breaking long words.
- `_safe_text`: Wraps and clips text to a maximum number of lines.
- `_create_panel_asset`: Creates simple panel images used as text-safe backgrounds.
- `_font`: Loads Windows fonts when available and falls back to Pillow's default font.
- `_draw_text_box`: Draws wrapped text into a raster image box.
- `_paste_contain`: Fits an image inside a target rectangle while preserving aspect ratio.
- `_page_background`: Loads a custom watermark/background or creates a neutral page background.
- `_render_cover_page`: Renders a report cover page image.
- `_render_report_page`: Renders one complete A4 creative review page.
- `_copy_text`: Extracts readable ad copy from an ad metadata record.
- `_image_metrics`: Computes basic image metrics used by the scoring heuristic.
- `_score_range`: Converts a numeric metric into a 1-10 score band.
- `_rate_ad`: Produces heuristic creative ratings from image and copy data.
- `_personas`: Generates simple customer persona suggestions from ad copy signals.
- `_better_angles`: Generates stronger story-driven ad angle suggestions from ad copy signals.
- `_create_a4_background`: Creates the default A4 artboard background artwork.

The `purformat` package provides the PureRef file primitives:

- `PurFile`: In-memory representation of a PureRef board.
- `PurFile.read`: Imports a `.pur` file.
- `PurFile.write`: Writes a `.pur` file.
- `PurFile.count_image_items`: Assigns image item IDs.
- `PurFile.count_text_items`: Assigns text item IDs.
- `PurGraphicsImageItem`: Stores image transform, crop, position, and scale.
- `PurGraphicsTextItem`: Stores text item content and display properties.
- `read_pur_file`: Reads PureRef files into `PurFile`.
- `write_pur_file`: Serializes `PurFile` to disk.

## Current Limitations

- PureRef text-item framing is difficult to control precisely. Text wrapping, safe zones, and panel alignment may not always match a polished report layout.
- The rendered report workflow exists because rasterized A4 pages are more predictable than native PureRef text objects.
- PDF export is not implemented.
- `export_artboards` is currently a placeholder that prepares a directory but does not export individual artboards.
- The creative ratings, personas, and ad angles are heuristic. They are useful for drafting and review, but they are not a substitute for human creative direction.
- The default report styling is opinionated and currently tailored toward static ad reviews.
- The code assumes local file paths. It does not download remote images.
- Font loading currently checks common Windows font paths first.
- There is no authentication layer in this project. Keep HTTP binding local unless you add your own access controls.

## Customization

You can adapt this MCP server for your own creative or open-source workflow by changing:

- Tool inputs: Add new MCP tool parameters to `pureref_server.py`.
- Board layout: Adjust positions, dimensions, columns, margins, and page sizes in the tool functions.
- Report design: Replace `_create_a4_background`, `_render_cover_page`, and `_render_report_page`.
- Scoring logic: Update `_rate_ad`, `_image_metrics`, and `_score_range`.
- Persona and angle logic: Update `_personas` and `_better_angles`.
- File format support: Extend `purformat` or add importers for other asset manifests.
- Transport defaults: Change `start-pureref-mcp.ps1` or `pureref_http_server.py`.

For the cleanest report output, customize `create_rendered_static_ad_report` first. It gives you pixel-level control through Pillow before the page is embedded into PureRef.

## Development Milestones

- Improve native PureRef text framing and panel alignment.
- Add real PDF export for generated reports.
- Add individual artboard/page export.
- Add cross-platform font discovery for macOS and Linux.
- Add tests for `.pur` serialization and generated board structure.
- Add sample input data and example output screenshots.
- Add configurable report themes.
- Add schema validation for `ads-data.json`.
- Add optional remote-image ingestion.
- Add MCP client configuration examples.

## Repository Hygiene

Generated output should not be committed. The `.gitignore` excludes:

- `.venv/`
- `__pycache__/`
- `logs/`
- `Output/`
- local `.env` files
- build and packaging artifacts

## License

This repository includes the GNU General Public License v3. See `LICENSE`.