Metadata-Version: 2.5
Name: priorrun-mcp
Version: 0.14.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 (image ≤ 8 MB, or mp4/mov/webm video ≤ 100 MB) |
| `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 |
| `interview_room_member` / `get_member_interview_history` | 1:1 with a single room member |
| `persona_audience_synthesis` | transcript → themes + quotes + advisory handoff hint |
| `persona_interview` / `persona_interview_history` | 1:1 with a persona from an archived memo (+ transcript) |
| `upload_interview_image` | stimulus for a 1:1 interview (images only) |
| `create_url_audit` / `get_url_audit` | deep-walk a live URL with your room's members, on desktop or mobile — queued, ~45–55 min |
| `create_mood` / `get_mood_job` / `list_mood_reports` / `get_mood` / `list_mood_cohorts` / `regenerate_mood` / `spawn_mood_audiences` | Mood of the Internet pipeline |
| `list_audience_templates` / `list_custom_audiences` / `rename_custom_audience` / `delete_custom_audience` | audience management |
| `get_memo` | fetch an archived memo by id — nothing writes new ones |

Image arguments accept local file paths, `https://` URLs, or base64.

`create_url_audit` queues a walk and, by default (`wait=True`), polls until it
lands and returns the walk itself. One agent walks the whole page in a real
browser, which takes 45–55 minutes — so pass `wait=False` and poll
`get_url_audit(walk_id)` yourself if your host has a tool timeout under an hour,
or if you have anything else to be getting on with.

## Example prompts

The agent picks the right tool from your wording. Say "ask my room" / "what do
they think" for the room tools, or "live page" / "walk this URL" for the URL
tools.

**URL walk** — the panel walks the page in a real browser, on the screen you
name:

```
Walk brand.com/landing on a phone with my Gen Z skincare room.
```

→ agent calls `create_url_audit` with `device="mobile"` and the seated members,
waits out the walk (45–55 min) and returns it: the walker's own account of the
page, every finding pinned to the screen it was found on, and one fix per
finding in the order to do them. Leave the device out for a 1280px laptop.

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