Metadata-Version: 2.4
Name: crowd-test-mcp
Version: 0.1.0
Summary: MCP server for crowd-test: unleash a mob of AI virtual users on your website from Claude Desktop, Claude Code, Cursor, or any MCP client.
Project-URL: Homepage, https://github.com/anhhuyn411-alt/crowd-test-mcp
Project-URL: Repository, https://github.com/anhhuyn411-alt/crowd-test-mcp
Project-URL: Issues, https://github.com/anhhuyn411-alt/crowd-test-mcp/issues
Project-URL: crowd-test core, https://github.com/anhhuyn411-alt/crowd-test
Author-email: Huy Nguyen <anhhuyn411@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,browser-automation,mcp,qa,testing,ux
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: crowd-test>=0.5.0
Requires-Dist: mcp>=1.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

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