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)
