Metadata-Version: 2.5
Name: priorrun-mcp
Version: 0.14.1
Summary: Walk a page or flow with Prior.Run and get it back marked up — 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: checkout-testing,mcp,page-walk,prior-run,usability,ux-testing
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) — walk a page or flow and get it
back marked up: every problem pinned to the spot, with the fix. Also ask your
audience room. Works 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

Walk first, mirroring the web app. Flow: `list_custom_audiences` →
`persona_audience_panel` (gives the audience id + seated member indices a walk
needs) → `create_url_audit` → `get_url_audit`. The saved audience says who the
page is for; specialists walk it.

| Tool | What it does |
|---|---|
| `create_url_audit` / `get_url_audit` | walk a page or flow (or a design prototype) on desktop or mobile and get it back marked up — queued, ~45–55 min |
| `persona_audience_panel` | open the room — seats the members, and gives the ids a walk needs |
| `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 archived-memo interview (images only) |
| `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. A walk 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. If
the account has no walks left, the call fails with HTTP 402 and a plain message.

## Example prompts

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

**Walk a page** — walked in a 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 room's ids,
waits out the walk (45–55 min) and returns it: the walker's own summary, 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)
