QualityMax QA MCP

QualityMax QA MCP

[!IMPORTANT]

These checks now ship in 9lives. From 9lives v0.4.0, 9l scan and 9l inspect run the same nine page checks and locator inspection, and 9l mcp gives coding agents scan_url, inspect_page and generate_playwright_repro next to its run, heal, assess and confirm tools: one local server, no account. qmax.run no longer hosts this project; see 9lives.run and Check the page you changed. New features and fixes land in 9lives-runner; open issues moved there. 0.9.2 is the final release of this package: it stays installable but receives no further fixes (9lives-runner#100).

Give a coding agent independent QA evidence before it declares a web change done: scan the page, inspect the UI, generate a focused Playwright repro, then review the execution result.

npx -y @qualitymax/qmax-mcp

The four local tools require no QualityMax account, API key, or hosted service.

Documentation · Hosted MCP setup · Local demo

This package provides four standalone local tools. Hosted workspace access is a separate authenticated connection; use the hosted MCP setup when you need platform projects and workflows.

Start with a useful result

Ask an MCP-enabled agent to scan the URL it changed, or run the local CLI:

npx -y @qualitymax/qmax-mcp scan https://example.com --format markdown

The report includes a graded summary, findings, concrete reproduction steps, and suggested fixes. One command exercises all four tools against a checked-in, dependency-free fixture — see the reproducible demo.

What one scan measures

All nine checks run off a single page load. Pass checks to run a subset.

Names must match exactly. An unrecognised name is rejected with the supported list rather than skipped, so a typo cannot quietly turn a check off and still return a score.

scan_url also returns a metrics block with the measured vitals and the page-weight breakdown, including the slowest requests. Two limits are stated in that block rather than hidden: INP is not measured, because it needs real user interaction, and vitals come from one cold load on the scanning machine, not from field data. Set weightBudget to scan against your own performance budget.

What the report looks like

--format markdown opens with the shape of the result, so a human or an agent can see where the problems are before reading a single finding:

Grade: 🔴 F (0 / 100) · 17 issues found

░░░░░░░░░░░░░░░░░░░░░░░░ 0 / 100

| Category | Issues | Worst |

|----------|--------|:-----:|

| Console errors | ██░░░░░░░░ 1 | 🔴 high |

| Accessibility | ████████░░ 3 | 🔴 high |

| Security headers | ██████████ 4 | 🟠 medium |

| Cookies and trackers | █████░░░░░ 2 | 🟠 medium |

| Page weight | ██████████ 4 | 🟠 medium |

Each bar is scaled to the noisiest category in that run, so the tallest bar is the thing to fix first. When weight runs, the measurements section also attributes the bytes:

script      ████████████████  18 kB

document ██░░░░░░░░░░░░░░ 3 kB stylesheet ██░░░░░░░░░░░░░░ 1 kB image ░░░░░░░░░░░░░░░░ 417 B

Then every finding follows with its severity, a copy-pasteable reproduction, and a suggested fix. Use --format json for the same data as structured output.

What the agent can do

The local server does not require an account. Hosted proxy mode is a separate, opt-in connection for account-backed QualityMax capabilities; do not add it unless that capability is needed.

Scan or inspect an authenticated page

Both tools read a Playwright storage-state file. Producing that file is the on-ramp, so here are the two shortest ways.

From a browser you log into yourself — no code, and it works against any login, including SSO and MFA:

npx playwright codegen --save-storage=playwright/.auth/user.json https://example.com/login

Sign in in the window that opens, then close it. Playwright writes the state to that path on exit.

From a login your test suite already automates — repeatable, and the one to use in CI:

// scripts/save-storage-state.mjs — run with: node scripts/save-storage-state.mjs

import { chromium } from 'playwright';

const browser = await chromium.launch(); const page = await browser.newPage();

await page.goto('https://example.com/login'); await page.getByLabel('Email').fill(process.env.APP_USER); // never hardcode await page.getByLabel('Password').fill(process.env.APP_PASSWORD); await page.getByRole('button', { name: 'Sign in' }).click(); await page.waitForURL('**/account'); // wait for the session, not a timeout

await page.context().storageState({ path: 'playwright/.auth/user.json' }); await browser.close();

Read the credentials from the environment rather than writing them into the script, and gitignore the output — playwright/.auth/ is the conventional location and Playwright's own scaffolding already ignores it. A session expires, so regenerate the file when scans start coming back as though logged out; a scan of a protected page that suddenly reports a login form is the usual symptom.

Then pass the path relative to the active workspace:

{

"url": "https://example.com/account", "storageStatePath": "playwright/.auth/user.json", "acknowledgePrivateContent": true }

scan_url and inspect_page load the state into a throwaway browser context before the first navigation and require acknowledgePrivateContent:true as explicit consent that the result may contain private page content. The path must resolve to a regular file inside the workspace; absolute paths, traversal, symlink escapes, and files over 10 MB are rejected. The state path and credential values are not returned, but findings or inspected page structure may reflect private account data. Treat both the state file and the tool result accordingly, and use a dedicated state file containing only the credentials needed by the inspected application. Playwright storage state covers cookies, local storage, and optionally IndexedDB; it does not persist session storage.

Compare a scan against a previous one

scan_url is documented for use after a change, which makes it a comparison: scan, change something, scan again, decide. Pass baseline — a previous scan result, or a workspace-relative path to one — and the response carries a delta reporting which findings are new, fixed, and unchanged, plus a one-line verdict.

{

"url": "https://example.com/", "baseline": "artifacts/scan-main.json" }

Each finding carries a stable id derived from its category, message, and URL or selector, so the same problem hashes the same across runs. Severity and occurrence count are excluded from that identity on purpose: a finding that is reclassified, or seen four times instead of three, is still the same finding.

In CI this is what makes a gate usable. Failing on findingCount > 0 stops working the moment a page has one known-benign finding, whereas failing on "nothing new since the last green run" keeps working:

qmax-mcp scan https://example.com/ --format json --out scan.json

qmax-mcp scan https://example.com/ --baseline artifacts/scan-main.json --fail-on-new

--fail-on-new exits 1 when the scan finds anything absent from the baseline, and 2 when it was passed without --baseline. Persist the last main-branch result as the baseline artifact.

Turn findings into tracker tickets

format: "issue" renders each finding as a self-contained Markdown block — summary, numbered steps, expected result, actual result, environment — ready to paste into a tracker without rewriting it as prose. minSeverity limits the export to what is worth filing.

qmax-mcp scan https://example.com/ --format issue --min-severity medium

Blocks are separated by HTML comments, which render as nothing, so pasting one does not carry the report's own structure into the ticket. A finding collapsed from several occurrences files as one ticket that states the frequency, rather than as several identical tickets.

Get ranked locators without an MCP client

inspect prints the same result as the inspect_page tool: every control with a ready-to-paste Playwright locator ranked by how durable its source is, a per-control stability verdict, and a page-level testability score.

qmax-mcp inspect https://example.com/

qmax-mcp inspect htt