QualityMax QA MCP

What QualityMax QA MCP does

QualityMax QA MCP MCP server provides four local tools for browser-oriented quality checks. It works with URLs and uses Playwright-based browser contexts to inspect pages, measure selected quality signals, create reproducible tests, and execute a local Playwright test.

The server is intended for checking a web change before considering it complete. A scan can produce a graded report with findings, reproduction steps, suggested fixes, measured vitals, and page-weight details. Reports are available as Markdown from the CLI or as structured JSON.

How it works

scan_url loads a page and runs checks from a single page load. Supported checks cover JavaScript errors and failed requests, links, accessibility structure, Core Web Vitals, title and meta description, security headers, cookies and trackers, mixed content, and transfer or request weight. The checks option selects a subset, while names must match the supported values exactly. weightBudget allows a scan to use a project-specific performance budget.

inspect_page returns page structure and role/name locator candidates. Both scanning and inspection can load a Playwright storage-state file for authenticated pages. The state file must be selected by a workspace-relative path, and private-content acknowledgement is required.

generate_playwright_repro writes a deterministic Playwright reproduction below .qmax-mcp/repros. run_playwright_test executes one local Playwright test and returns structured status. Running a test normally requires an accepted, digest-bound MCP human-approval elicitation.

Setup and configuration

Run the local server with:

npx -y @qualitymax/qmax-mcp

A direct scan can be started with:

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

The package requires Node.js 22.13.0 or newer. The local tools do not require a QualityMax account, API key, or hosted service. Hosted workspace access is a separate authenticated connection and is not part of this local setup.

For authenticated pages, create a Playwright storage-state file through browser code generation or an existing login test, then provide its workspace-relative path. Keep the file out of source control and use a dedicated state file containing only the credentials needed for the target application.

Tools and capabilities

• scan_url: Finds page-quality issues and returns grades, findings, metrics, reproduction steps, and suggested fixes.
• inspect_page: Reports page structure and locator candidates.
• generate_playwright_repro: Creates a workspace-contained Playwright reproduction.
• run_playwright_test: Runs one local Playwright test and reports its status.
• Markdown and JSON output are supported for scan results.
• Scan metrics include measured vitals, request details, and page-weight breakdowns when applicable.

Limitations and notes

QualityMax QA MCP MCP server measures vitals from one cold load on the scanning machine, not field data. INP is not measured because it requires real user interaction. Authenticated scans may expose private page content in findings or inspected structure, although the state path and credential values are not returned.

The server makes outbound requests during scans and inspections. Scans or inspections may read an explicitly selected workspace file containing credentials, while repro generation and test execution write controlled workspace artifacts. Storage-state files over 10 MB, absolute paths, traversal, and symlink escapes are rejected. Session storage is not persisted by Playwright storage state, and expired sessions may cause a protected page to appear logged out.