Metadata-Version: 2.4
Name: priorrun-mcp
Version: 0.2.2
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, Codex,
Gemini CLI, Cursor, Windsurf, Cline, Zed, 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

`~/.claude/mcp.json` (global) or `.mcp.json` in a project root:

```json
{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
    }
  }
}
```

### Codex (OpenAI)

`~/.codex/config.toml` — TOML, not JSON:

```toml
[mcp_servers.prior-run]
command = "uvx"
args = ["priorrun-mcp"]

[mcp_servers.prior-run.env]
PRIORRUN_API_KEY = "pr_live_..."
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
    }
  }
}
```

### Windsurf / Cline / Zed / other MCP hosts

All modern MCP hosts share the same `mcpServers` JSON shape used by Claude Code.
Drop the same block into the host's MCP config file — check the host's docs for
the exact path.

## Tools

| Tool | What it does |
|---|---|
| `create_design_review` | single design review |
| `create_design_compare` | two design variants head-to-head |
| `create_design_multi` | 3–5 design variants |
| `create_design_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 prompts

The agent picks the right tool from your wording. Say "ad creative" / "creative
compare" / name a platform (Meta/TikTok/Google) for the ads tools, or "landing
page" / "design compare" / "variant" for the design tools.

**Design compare** — evaluates the page itself (layout, hierarchy, CTA clarity,
conversion readiness):

```
Run a Prior.Run design compare on ~/desktop/landing-a.png vs
~/desktop/landing-b.png targeting the gen_z audience template. Hypothesis:
the warmer palette will lift click-through.
```

→ agent calls `create_design_compare`, full page-level synthesis, burns 1 analysis credit.

**Ads compare** — evaluates the creative as it would appear in-feed (scroll-stop,
hook clarity, brand recall), platform-aware:

```
Run a Prior.Run ads compare on ~/desktop/creative-a.jpg vs
~/desktop/creative-b.jpg. Campaign context: Gen Z skincare awareness on TikTok.
```

→ agent calls `create_ads_compare` with `run_platform="tiktok"`, ads-specific
synthesis (scroll-stop, hook, brand recall, no landing-page critique).

Both return a completed memo (~90s) with verdict, audience quotes, and a 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)
