# AllRight Charlie Quiz MCP

Standalone MCP server for adaptive, agent-driven testing of the Charlie
registration quiz:

`https://stage.allright.com/uk/app/sign-up/long/charlie/age-range`

The server observes the currently rendered UI after every action instead of
assuming a fixed step order, copy, selectors, or A/B assignment.

## Architecture

- `src/mcp` owns browser observation, actions, safety and artifacts.
- `src/agent` chooses actions, generates synthetic data and logs decisions.
- `src/domain` verifies deterministic business evidence.
- `tests/stage.mcp.e2e.ts` only connects those layers into an executable run.

The agent adapts to ordinary A/B screens, while phone, email, safety and
completion remain deterministic.

## Install and build

```bash
npm install
npx playwright install chromium
npm run build
```

## Run

```bash
npm run mcp
```

The MCP server uses stdio, so a manually started process waits silently for an
MCP client. To run the automated test against the real AllRight stage:

```bash
npm test
```

The test launches the compiled MCP server as a child process, performs the MCP
handshake, opens the real Charlie stage quiz, navigates its current dynamic
steps, submits synthetic names and a generated Ukrainian phone, and requires the
terminal text `Дякуємо! Ваш запит отримано`.

It also requires a successful non-GET backend response. That confirms that the
terminal UI was accompanied by a server-side mutation. Definitive database
assertions for both `user created` and `trial booked` require a trusted company
stage API or database access; this limitation is reported rather than hidden.

The runner does not assume that the quiz contains 21 steps. It continues through
the currently assigned A/B path until the terminal text appears. A high action
budget exists only as loop protection; reaching a particular step number is
never treated as success.

To watch the complete flow in a visible Chromium window:

```bash
npm run test:headed
```

Actions are slowed down so each real stage transition remains visible. Chromium
stays open on the final screen for 20 seconds before the test closes it. On the
phone step the runner selects Ukraine (`+380`) and generates operator code `63`
plus seven random digits. This flow submits the form and creates real stage
entities.

## Safety

MCP starts with `allowSideEffects: false`. Both generic and named-button tools
block the phone/email commit boundary in this mode. The real E2E runner opts in
explicitly because it is intended to create an authorized synthetic stage
registration. Never point it at production.

Synthetic names use valid Ukrainian test values; the unique email contains the
`mcp.e2e` marker and run ID. Cleanup can be added behind the domain layer when
an authorized company test-data API is available.

## Diagnostics and CI

Each run writes `test-results/<run-id>/trace.zip`, browser video,
`evidence.png`, `business-evidence.json`, and `agent-decisions.json`. Open a
trace with:

```bash
npx playwright show-trace test-results/<run-id>/trace.zip
```

Run deterministic tests without external side effects:

```bash
npm run test:unit
```

Recommended CI: `test:unit` on every PR and `test:ci` on a protected schedule.

Use [`mcp.json`](./mcp.json) as the MCP client configuration. If the client
resolves paths outside this directory, replace the relative script path with the
absolute path to `dist/src/mcp/server.js`.

Available tools:

- `quiz_start`
- `quiz_observe`
- `quiz_act`
- `quiz_click_named_button`
- `quiz_named_button_state`
- `quiz_select_phone_country`
- `quiz_scroll`
- `quiz_wait`
- `quiz_dismiss_overlays`
- `quiz_evidence`
- `quiz_close`

`quiz_start` defaults to `allowSideEffects: false`, which blocks final
registration/booking actions through every click tool.

The test approach, CI/CD proposal, assumptions, risks, and limitations are in
[`docs/CHARLIE_QUIZ_TEST_STRATEGY.md`](./docs/CHARLIE_QUIZ_TEST_STRATEGY.md).