# crowd-test-mcp 🔥

**The mob, on tap — an MCP server for [crowd-test](https://github.com/anhhuyn411-alt/crowd-test).**

Ask Claude Desktop, Claude Code, Cursor, or any MCP client to unleash a crowd
of AI virtual users — impatient shoppers, confused seniors, keyboard-only
users, chaos monkeys — on your website. They browse it in real Chromium,
file findings, and hand back a damage report with a **survival grade** (S–F).

> *"Send the mob at https://staging.myapp.com and tell me what to fix first."*

That's the whole workflow now.

## Install

```bash
pip install crowd-test-mcp
```

An LLM key is required in the server's environment: `ANTHROPIC_API_KEY` or
`OPENAI_API_KEY`.

### Claude Code

```bash
claude mcp add crowd-test -e ANTHROPIC_API_KEY=sk-... -- crowd-test-mcp
```

### Claude Desktop / Cursor / anything MCP

```json
{
  "mcpServers": {
    "crowd-test": {
      "command": "crowd-test-mcp",
      "env": { "ANTHROPIC_API_KEY": "sk-..." }
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `run_crowd_test` | Send the crowd at a URL. Pick personas, add a random `mob`, set a `goal`, choose the verification depth (`none` / `detective` / `cross` / `tribunal`). Returns a compact damage summary; full markdown/HTML reports land in `~/crowd-test-reports/`. |
| `list_personas` | The ten built-in ringleaders and what each one catches. |
| `preview_mob` | Preview the random mob a given `count`/`seed` would generate. |
| `read_report` | Fetch the newest full markdown report from disk. |

## The verification tribunal

Findings can be cross-examined by up to three independent harnesses before
they count against the grade — a skeptical detective agent, a raw Playwright
probe, and a [Microsoft Webwright](https://github.com/microsoft/Webwright)
agent. Automation artifacts get disputed instead of panicking you. Details in
the [crowd-test README](https://github.com/anhhuyn411-alt/crowd-test#the-tribunal-%EF%B8%8F).

Deeper layers need one-time extras:

```bash
pip install crowd-test[probe] && playwright install chromium   # verify="cross"
pip install git+https://github.com/microsoft/Webwright         # verify="tribunal"
```

## Good to know

- **Runs take minutes, not seconds** — every persona drives a real browser.
  Start with 2–3 personas; escalate to `mob=10` when you mean it.
- **Only test what you own.** The mob is for your own staging and production
  sites, not other people's.
- Reports default to `~/crowd-test-reports/<host>-<timestamp>/`.

## License

[MIT](LICENSE)