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

npm install
npx playwright install chromium
npm run build

Run

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:

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:

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:

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

Run deterministic tests without external side effects:

npm run test:unit

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

Use 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.