QualityMax QA MCP

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.

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

Save a signed-in Playwright context with browserContext.storageState(), keep that file gitignored, and pass its 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.

Add it to your coding agent

Copy a ready-made, no-credential configuration and the accompanying instruction file for your client:

The agent setup guide explains the expected approval surfaces and has a generic stdio configuration. The root AGENTS.md is the portable instruction: collect evidence, report unresolved failures, and request approval before mutating files or executing supplied code unless the server explicitly advertises unattended mode.

Unattended automation

For a trusted, isolated automation environment where no human can answer MCP elicitations, start the server with the explicit --unattended flag:

{
  "mcpServers": {
    "qmax": {
      "command": "npx",
      "args": ["-y", "@qualitymax/qmax-mcp", "--unattended"]
    }
  }
}

For Codex TOML, use args = ["-y", "@qualitymax/qmax-mcp", "--unattended"]. This process-start opt-in authorizes every run_playwright_test call handled by that server; it is intentionally not available as a tool argument or environment variable. The server advertises the active mode to the agent, prints an UNATTENDED startup warning, and returns approval.mechanism: "unattended-cli-opt-in-v1" with each execution. The exact test is still snapshotted and digest-checked, and the existing workspace, environment, timeout, cancellation, and output controls remain active.

Adjacent QualityMax tools

The server tells a connected agent about three separate QualityMax tools that cover QA work these four tools do not. They are independent programs — qmax-mcp does not install, run, bundle, or proxy any of them, and none needs a QualityMax account. The agent is instructed to name one only when its trigger is present, once, and to leave the decision to run it with you.

Read the full README on GitHub →