Metadata-Version: 2.4
Name: priorrun-mcp
Version: 0.8.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 focus-group rooms and deep
tests on ad creatives and live pages 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

Room-first, mirroring the web app: every deep run starts from a focus-group
room. Flow: `list_custom_audiences` → `persona_audience_panel` (seats the
members) → `persona_audience_ask` (fast) → deep-run via a `create_*` tool with
`custom_audience_id` + `panel_member_indices` (the seated members, both required).

| Tool | What it does |
|---|---|
| `persona_audience_panel` | open the focus-group room — seats the members |
| `persona_audience_ask` | ask the whole room one question (fast, + actions, @-targeting) |
| `upload_room_image` | upload stimulus for a room ask (images only — no video) |
| `persona_audience_verdict` | stat-sig A/B verdict over the full audience pool (99% CI) |
| `dismiss_room_member` | replace one seated member with a fresh draw |
| `reset_room` | clear / swap / new room reset |
| `create_room_thread` / `rename_room_thread` | campaign threads |
| `get_room_turns` | server-side room transcript + field notes |
| `create_ads_single` | deep-test a single ad creative with your room |
| `create_ads_compare` | two ad creatives head-to-head with your room |
| `create_url_audit` | deep-walk a live URL with your room's members |
| `create_url_compare` | two live URLs head-to-head with your room's members |
| `create_creative_from_fieldnotes` | 3 ad creative variants (quote / editorial / bold graphic) generated from a focus-group's field notes — no memo required |
| `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 "live
page" / "walk this URL" for the URL tools.

**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)
