priorrun-mcp 0.1.0__tar.gz

priorrun_mcp-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+.env.local
+.mcp.json
+api/.env
+web/.env.local
+api/venv/
+web/node_modules/
+web/.next/
+.next/
+CSV/
+.DS_Store
+*.egg-info/
+dist/
+build/
+.modal/
+data/ab_tests/screenshots/
+.gstack/
+.claude/

priorrun_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: priorrun-mcp
+Version: 0.1.0
+Summary: Run Prior.Run audience simulations from Claude Desktop, Claude Code, Cursor, or any MCP-compatible agent.
+Project-URL: Homepage, https://prior.run
+Project-URL: Documentation, https://prior.run/docs/mcp
+Project-URL: API Reference, https://prior.run/docs/api
+Author-email: "Prior.Run" <hello@prior.run>
+License: MIT
+Keywords: ab-testing,audience-simulation,creative-testing,mcp,prior-run,synthetic-users
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# priorrun-mcp
+
+MCP server for [Prior.Run](https://prior.run) — run synthetic-audience simulations
+on design variants and ad creatives from Claude Desktop, Claude Code, Cursor, or
+any MCP-compatible agent.
+
+## Install
+
+Requires Python 3.11+. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it.
+
+```bash
+uvx priorrun-mcp
+```
+
+That's it — `uvx` fetches and runs the server on demand.
+
+## Configure
+
+Grab an API key from [prior.run/settings](https://prior.run/settings), then register the server with your agent host.
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "prior-run": {
+      "command": "uvx",
+      "args": ["priorrun-mcp"],
+      "env": {
+        "PRIORRUN_API_KEY": "pr_live_xxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Code / Cursor
+
+`~/.claude/mcp.json` (Claude Code) or `.cursor/mcp.json` (Cursor):
+
+```json
+{
+  "mcpServers": {
+    "prior-run": {
+      "command": "uvx",
+      "args": ["priorrun-mcp"],
+      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `create_memo_review` | single design review |
+| `create_memo_compare` | two design variants head-to-head |
+| `create_memo_multi` | 3–5 design variants |
+| `create_memo_flow` | two funnel flows (each 2–5 screens) |
+| `create_ads_single` | single ad creative evaluation |
+| `create_ads_compare` | two ad creatives head-to-head |
+| `create_ads_multi` | 3–5 ad creatives |
+| `get_memo` | fetch status + full memo JSON by id |
+| `wait_for_memo` | block until synthesis completes |
+
+Image arguments accept local file paths, `https://` URLs, or base64. Create
+tools default to `wait=True` — the agent gets the completed memo in one tool
+call.
+
+## Example prompt
+
+```
+Run a Prior.Run compare on ~/desktop/landing-a.png vs ~/desktop/landing-b.png
+for a Gen Z skincare awareness campaign. Hypothesis: the warmer palette
+will lift click-through.
+```
+
+The agent calls `create_memo_compare`, waits ~90s for synthesis, and hands
+you back the verdict, audience quotes, and memo URL.
+
+## Environment variables
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `PRIORRUN_API_KEY` | yes | — | `pr_live_...` format. Generate at [prior.run/settings](https://prior.run/settings). |
+| `PRIORRUN_API_BASE` | no | `https://api.prior.run` | Override for staging or local dev. |
+
+## Links
+
+- Product: [prior.run](https://prior.run)
+- API docs: [prior.run/docs/api](https://prior.run/docs/api)
+- MCP docs: [prior.run/docs/mcp](https://prior.run/docs/mcp)

priorrun_mcp-0.1.0/README.md

@@ -0,0 +1,95 @@
+# priorrun-mcp
+
+MCP server for [Prior.Run](https://prior.run) — run synthetic-audience simulations
+on design variants and ad creatives from Claude Desktop, Claude Code, Cursor, or
+any MCP-compatible agent.
+
+## Install
+
+Requires Python 3.11+. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it.
+
+```bash
+uvx priorrun-mcp
+```
+
+That's it — `uvx` fetches and runs the server on demand.
+
+## Configure
+
+Grab an API key from [prior.run/settings](https://prior.run/settings), then register the server with your agent host.
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "prior-run": {
+      "command": "uvx",
+      "args": ["priorrun-mcp"],
+      "env": {
+        "PRIORRUN_API_KEY": "pr_live_xxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Code / Cursor
+
+`~/.claude/mcp.json` (Claude Code) or `.cursor/mcp.json` (Cursor):
+
+```json
+{
+  "mcpServers": {
+    "prior-run": {
+      "command": "uvx",
+      "args": ["priorrun-mcp"],
+      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `create_memo_review` | single design review |
+| `create_memo_compare` | two design variants head-to-head |
+| `create_memo_multi` | 3–5 design variants |
+| `create_memo_flow` | two funnel flows (each 2–5 screens) |
+| `create_ads_single` | single ad creative evaluation |
+| `create_ads_compare` | two ad creatives head-to-head |
+| `create_ads_multi` | 3–5 ad creatives |
+| `get_memo` | fetch status + full memo JSON by id |
+| `wait_for_memo` | block until synthesis completes |
+
+Image arguments accept local file paths, `https://` URLs, or base64. Create
+tools default to `wait=True` — the agent gets the completed memo in one tool
+call.
+
+## Example prompt
+
+```
+Run a Prior.Run compare on ~/desktop/landing-a.png vs ~/desktop/landing-b.png
+for a Gen Z skincare awareness campaign. Hypothesis: the warmer palette
+will lift click-through.
+```
+
+The agent calls `create_memo_compare`, waits ~90s for synthesis, and hands
+you back the verdict, audience quotes, and memo URL.
+
+## Environment variables
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `PRIORRUN_API_KEY` | yes | — | `pr_live_...` format. Generate at [prior.run/settings](https://prior.run/settings). |
+| `PRIORRUN_API_BASE` | no | `https://api.prior.run` | Override for staging or local dev. |
+
+## Links
+
+- Product: [prior.run](https://prior.run)
+- API docs: [prior.run/docs/api](https://prior.run/docs/api)
+- MCP docs: [prior.run/docs/mcp](https://prior.run/docs/mcp)

priorrun_mcp-0.1.0/priorrun_mcp/server.py

@@ -0,0 +1,271 @@
+"""
+Prior.Run MCP server — exposes memo generation as tools for Claude Desktop, Cursor, Claude Code.
+
+Env:
+  PRIORRUN_API_KEY   — required, format pr_live_...
+  PRIORRUN_API_BASE  — optional, defaults to https://api.prior.run
+
+Run:
+  uvx priorrun-mcp                    (from PyPI — recommended)
+  python -m priorrun_mcp.server       (from a local clone)
+
+Tools:
+  create_memo_compare — two-variant design comparison (non-ads)
+  create_ads_single   — single ad creative evaluation
+  create_ads_compare  — two ad creatives head-to-head
+  get_memo            — fetch memo by id (polls-friendly)
+  wait_for_memo       — block until a memo reaches status=complete
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import os
+import pathlib
+import time
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+API_KEY = os.environ.get("PRIORRUN_API_KEY", "")
+API_BASE = os.environ.get("PRIORRUN_API_BASE", "https://api.prior.run").rstrip("/")
+
+if not API_KEY:
+    raise SystemExit("PRIORRUN_API_KEY is required (create one at /account/api-keys)")
+
+mcp = FastMCP("prior-run")
+
+
+def _headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
+
+
+def _load_image(src: str) -> str:
+    """
+    Normalize image input to base64.
+    Accepts: local file path, https URL (passed through), or already-base64 string.
+    """
+    if src.startswith("http://") or src.startswith("https://"):
+        return src  # let server fetch
+    path = pathlib.Path(os.path.expanduser(src))
+    if path.exists() and path.is_file():
+        return base64.b64encode(path.read_bytes()).decode()
+    return src  # assume already base64
+
+
+async def _post(endpoint: str, payload: dict[str, Any]) -> dict[str, Any]:
+    async with httpx.AsyncClient(timeout=600) as client:
+        r = await client.post(f"{API_BASE}{endpoint}", json=payload, headers=_headers())
+    if r.status_code >= 400:
+        raise RuntimeError(f"{endpoint} failed ({r.status_code}): {r.text[:400]}")
+    return r.json()
+
+
+async def _get(endpoint: str) -> dict[str, Any]:
+    async with httpx.AsyncClient(timeout=60) as client:
+        r = await client.get(f"{API_BASE}{endpoint}", headers=_headers())
+    if r.status_code >= 400:
+        raise RuntimeError(f"{endpoint} failed ({r.status_code}): {r.text[:400]}")
+    return r.json()
+
+
+@mcp.tool()
+async def create_memo_compare(
+    image_a: str,
+    image_b: str,
+    audience_template: str = "general_consumer",
+    custom_audience: str | None = None,
+    metric: str = "conversion rate",
+    hypothesis: str = "",
+) -> dict:
+    """
+    Create a two-variant comparison memo. Returns {memo_id, url, status, memo}.
+
+    image_a / image_b: local file path, https URL, or base64 string.
+    audience_template: e.g. general_consumer, enterprise_buyer, gen_z (see Prior.Run docs).
+    custom_audience: Pro+ only — natural-language audience description.
+    """
+    payload = {
+        "image_a": _load_image(image_a),
+        "image_b": _load_image(image_b),
+        "audience_template": audience_template,
+        "metric": metric,
+        "hypothesis": hypothesis,
+    }
+    if custom_audience:
+        payload["custom_audience"] = custom_audience
+    return await _post("/api/v1/memo/compare", payload)
+
+
+@mcp.tool()
+async def create_ads_single(
+    image: str,
+    campaign_context: str,
+    creative_name: str = "Untitled Creative",
+    run_platform: str | None = None,
+    wait: bool = True,
+) -> dict:
+    """
+    Evaluate a single ad creative. Returns memo_id + url; with wait=True blocks until complete.
+
+    image: local file path, https URL, or base64.
+    campaign_context: what is this ad trying to accomplish? (required, min 10 chars)
+    run_platform: meta | tiktok | google (optional — tailors benchmarks).
+    """
+    payload = {
+        "image": _load_image(image),
+        "campaign_context": campaign_context,
+        "creative_name": creative_name,
+    }
+    if run_platform:
+        payload["run_platform"] = run_platform
+    created = await _post("/api/v1/ads/single", payload)
+    if wait:
+        return await wait_for_memo(created["memo_id"])
+    return created
+
+
+@mcp.tool()
+async def create_memo_review(
+    image: str,
+    audience_template: str = "general_consumer",
+    custom_audience: str | None = None,
+    metric: str = "conversion rate",
+    hypothesis: str = "",
+    wait: bool = True,
+) -> dict:
+    """Single-variant design review memo. With wait=True blocks until complete."""
+    payload = {
+        "image": _load_image(image),
+        "audience_template": audience_template,
+        "metric": metric,
+        "hypothesis": hypothesis,
+    }
+    if custom_audience:
+        payload["custom_audience"] = custom_audience
+    created = await _post("/api/v1/memo/review", payload)
+    return await wait_for_memo(created["memo_id"]) if wait else created
+
+
+@mcp.tool()
+async def create_memo_multi(
+    images: list[str],
+    audience_template: str = "general_consumer",
+    custom_audience: str | None = None,
+    metric: str = "conversion rate",
+    hypothesis: str = "",
+    wait: bool = True,
+) -> dict:
+    """Compare 3–5 design variants. images: list of paths/URLs/base64."""
+    payload = {
+        "images": [_load_image(i) for i in images],
+        "audience_template": audience_template,
+        "metric": metric,
+        "hypothesis": hypothesis,
+    }
+    if custom_audience:
+        payload["custom_audience"] = custom_audience
+    created = await _post("/api/v1/memo/multi", payload)
+    return await wait_for_memo(created["memo_id"]) if wait else created
+
+
+@mcp.tool()
+async def create_memo_flow(
+    flow_a: list[str],
+    flow_b: list[str],
+    audience_template: str = "general_consumer",
+    custom_audience: str | None = None,
+    metric: str = "conversion rate",
+    hypothesis: str = "",
+    wait: bool = True,
+) -> dict:
+    """Compare two ordered funnel flows (each 2–5 screens)."""
+    payload = {
+        "flow_a": [_load_image(i) for i in flow_a],
+        "flow_b": [_load_image(i) for i in flow_b],
+        "audience_template": audience_template,
+        "metric": metric,
+        "hypothesis": hypothesis,
+    }
+    if custom_audience:
+        payload["custom_audience"] = custom_audience
+    created = await _post("/api/v1/memo/flow", payload)
+    return await wait_for_memo(created["memo_id"]) if wait else created
+
+
+@mcp.tool()
+async def create_ads_multi(
+    images: list[str],
+    campaign_context: str,
+    names: list[str] | None = None,
+    run_platform: str | None = None,
+    wait: bool = True,
+) -> dict:
+    """Compare 3–5 ad creatives in one memo."""
+    payload: dict = {
+        "images": [_load_image(i) for i in images],
+        "campaign_context": campaign_context,
+    }
+    if names:
+        payload["names"] = names
+    if run_platform:
+        payload["run_platform"] = run_platform
+    created = await _post("/api/v1/ads/multi", payload)
+    return await wait_for_memo(created["memo_id"]) if wait else created
+
+
+@mcp.tool()
+async def create_ads_compare(
+    image_a: str,
+    image_b: str,
+    campaign_context: str,
+    name_a: str = "Creative A",
+    name_b: str = "Creative B",
+    run_platform: str | None = None,
+    wait: bool = True,
+) -> dict:
+    """Compare two ad creatives. With wait=True (default) blocks until synthesis finishes."""
+    payload = {
+        "image_a": _load_image(image_a),
+        "image_b": _load_image(image_b),
+        "campaign_context": campaign_context,
+        "name_a": name_a,
+        "name_b": name_b,
+    }
+    if run_platform:
+        payload["run_platform"] = run_platform
+    created = await _post("/api/v1/ads/compare", payload)
+    if wait:
+        return await wait_for_memo(created["memo_id"])
+    return created
+
+
+@mcp.tool()
+async def get_memo(memo_id: str) -> dict:
+    """Fetch memo JSON. Returns {memo_id, status, url, memo, created_at}."""
+    return await _get(f"/api/v1/memo/{memo_id}")
+
+
+@mcp.tool()
+async def wait_for_memo(memo_id: str, timeout_seconds: int = 300) -> dict:
+    """Poll GET /memo/{id} until status == 'complete' or timeout."""
+    deadline = time.time() + timeout_seconds
+    delay = 2.0
+    while time.time() < deadline:
+        data = await _get(f"/api/v1/memo/{memo_id}")
+        if data.get("status") == "complete":
+            return data
+        await asyncio.sleep(delay)
+        delay = min(delay * 1.3, 10.0)
+    raise TimeoutError(f"Memo {memo_id} did not complete within {timeout_seconds}s")
+
+
+def main() -> None:
+    """Entry point for `uvx priorrun-mcp` / console_scripts."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

priorrun_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "priorrun-mcp"
+version = "0.1.0"
+description = "Run Prior.Run audience simulations from Claude Desktop, Claude Code, Cursor, or any MCP-compatible agent."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Prior.Run", email = "hello@prior.run" },
+]
+keywords = ["mcp", "prior-run", "synthetic-users", "ab-testing", "creative-testing", "audience-simulation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://prior.run"
+Documentation = "https://prior.run/docs/mcp"
+"API Reference" = "https://prior.run/docs/api"
+
+[project.scripts]
+priorrun-mcp = "priorrun_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["priorrun_mcp"]