PureRef

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

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.

.\start-pureref-mcp.ps1

This runs:

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

HTTP transport

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

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

Equivalent direct command:

.\.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:

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:

<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.