Metadata-Version: 2.5
Name: priorrun-mcp
Version: 0.13.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` | deep-walk a live URL with your room's members, on desktop or mobile |
| `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. The URL
tools block until the panel finishes walking and return the walk itself.

## 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,
and returns the walk (~6–10 min): each panelist's journey, reaction, where they
hesitated and whether they finished. 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)
