QualityMax QA MCP

QualityMax QA MCP

重要

这些检查现已集成到 9lives 中。 从 9lives v0.4.0 起，9l scan 和 9l inspect 会运行相同的九项页面检查并检查定位器；9l mcp 则会为编码 Agent 提供 scan_url、inspect_page 和 generate_playwright_repro，以及运行、修复、评估和确认工具：只需一个本地服务，无需账户。qmax.run 不再托管此项目；请参阅 9lives.run 和 检查你修改的页面。新功能和修复将在 9lives-runner 中发布；未解决的问题也已迁移到那里。0.9.2 是此软件包的最终版本：仍可安装，但不会再收到修复（9lives-runner#100）。

在编码 Agent 宣布网页更改已完成之前，为它提供独立的 QA 证据：扫描页面、检查 UI、生成针对性的 Playwright 复现，然后检查执行结果。

npx -y @qualitymax/qmax-mcp

这四个本地工具无需 QualityMax 账户、API 密钥或托管服务。

文档 · 托管 MCP 设置 · 本地演示

此软件包提供四个独立的本地工具。托管工作区访问需要单独进行身份验证；如果你需要平台项目和工作流，请使用托管 MCP 设置。

快速获得实用结果

让支持 MCP 的 Agent 扫描你修改过的 URL，或运行本地 CLI：

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

报告包含分级摘要、问题发现、具体的复现步骤和建议的修复方法。一条命令即可通过已检入、无需依赖的测试装置运行全部四个工具——请参阅可复现演示。

单次扫描的测量内容

九项检查均基于同一次页面加载运行。传入 checks 可运行部分检查。

检查项	报告内容
console	JavaScript 错误、警告和失败的请求
links	失效和重定向链接，最多 maxLinks 个
accessibility	缺少替代文本、未标注的控件、无名称的交互元素、标题结构
performance	Core Web Vitals：LCP、CLS、TTFB、FCP
seo	标题和 meta 描述
security_headers	CSP、HSTS、X-Content-Type-Options、Referrer-Policy
cookies	缺少 Secure/HttpOnly/SameSite、第三方 Cookie、已知跟踪器、同意前跟踪
mixed_content	HTTPS 页面上的 HTTP 子资源和表单操作，按浏览器阻止的主动内容和被动内容分类
weight	传输字节数、请求数、阻塞渲染的资源、超大和未压缩的资源、第三方开销

名称必须完全匹配。遇到无法识别的名称时，系统会返回支持的名称列表并拒绝执行，而不是跳过该检查；因此，拼写错误不会悄悄关闭检查，却仍然返回评分。

scan_url 还会返回一个 metrics 区块，其中包含测得的 Web Vitals 和页面权重细分，包括最慢的请求。该区块会明确说明两项限制，而不是将它们隐藏起来：不会测量 INP，因为这需要真实用户交互；此外，Web Vitals 来自扫描机器上的一次冷加载，而非实测数据。设置 weightBudget，即可根据你自己的性能预算进行扫描。

报告的样式

--format markdown 会先展示结果概况，让人或 Agent 在阅读任何具体问题之前，就能了解问题所在：

等级：🔴 F（0 / 100） · 发现 17 个问题

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

类别	问题数	最严重级别
控制台错误	██░░░░░░░░ 1	🔴 高
无障碍	████████░░ 3	🔴 高
安全标头	██████████ 4	🟠 中
Cookie 和跟踪器	█████░░░░░ 2	🟠 中
页面权重	██████████ 4	🟠 中

每个进度条都按本次运行中问题最多的类别缩放，因此最长的进度条代表应该优先修复的问题。运行 weight 时，测量结果部分还会列出字节数的归属：

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

随后会逐项列出问题，包括严重程度、可复制粘贴的复现步骤以及建议的修复方法。使用 --format json 可获取相同数据的结构化输出。

Agent 可以执行的操作

工具	本地能力	需要审查的边界
scan_url	扫描 URL，检查控制台、网络、遥测 SDK、链接、无障碍、SEO、安全标头、Cookie/跟踪器、混合内容、页面权重和 Core Web Vitals；也可选择使用 Playwright 存储状态文件。	它会发出外部请求，可能读取包含凭据的指定工作区文件，也可能写入截图。
inspect_page	返回页面结构和角色/名称定位器候选项；也可选择使用 Playwright 存储状态文件访问需身份验证的页面。	它会发出外部请求，可能读取包含凭据的指定工作区文件。
generate_playwright_repro	写入确定性的、位于工作区内的 Playwright 复现文件。	它会在 .qmax-mcp/repros 下写入文件；覆盖操作需要明确指定。
run_playwright_test	执行一个本地 Playwright 测试并返回结构化状态。	它会执行代码并写入受控产物；默认要求通过已接受且与摘要绑定的 MCP 人工审批请求。

本地服务无需账户。托管代理模式是单独的可选连接，用于使用基于账户的 QualityMax 功能；除非需要该功能，否则不要添加。

扫描或检查经过身份验证的页面

这两个工具都会读取 Playwright storage-state 文件。生成该文件是入门的第一步，以下是两种最简便的方法。

使用你亲自登录的浏览器——无需编写代码，适用于任何登录方式，包括 SSO 和 MFA：

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

在打开的窗口中登录，然后关闭窗口。Playwright 会在退出时将状态写入该路径。

使用测试套件已自动执行的登录流程——可重复执行，也是 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();

从环境变量中读取凭据，而不是将它们写入脚本，并将输出路径加入 gitignore——playwright/.auth/ 是惯用位置，Playwright 自带的脚手架也已将其设为忽略项。会话会过期，因此当扫描结果开始显示为未登录状态时，请重新生成该文件；扫描受保护页面时突然报告登录表单，通常就是这种情况。

然后传入相对于当前工作区的路径：

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

scan_url 和 inspect_page 会在首次导航前将状态加载到临时浏览器上下文中，并要求显式传入 acknowledgePrivateContent:true，以确认结果可能包含私有页面内容。路径必须解析为工作区内的常规文件；绝对路径、路径遍历、符号链接逃逸以及超过 10 MB 的文件都会被拒绝。不会返回状态路径和凭据值，但发现结果或检查到的页面结构可能反映私有账户数据。请妥善处理状态文件和工具结果，并使用仅包含检查目标应用所需凭据的专用状态文件。Playwright storage state 会保存 Cookie、本地存储，以及可选的 IndexedDB；但不会持久化 session storage。

将扫描结果与先前结果进行比较

scan_url 适用于更改后使用，因此可以用于比较：先扫描，进行更改，再次扫描，然后作出判断。传入 baseline——先前的扫描结果，或指向该结果的工作区相对路径——响应中便会包含 delta，报告哪些发现是 new、fixed 和 unchanged，并附上一行结论。

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

每条发现都有一个稳定的 id，由其类别、消息以及 URL 或选择器生成，因此同一问题在不同运行中的哈希值相同。严重程度和出现次数会有意排除在该标识之外：即使某条发现被重新分类，或从出现三次变为四次，它仍是同一条发现。

在 CI 中，这能让门禁切实可用。如果遇到 findingCount > 0 就失败，那么页面一旦出现一条已知且无害的发现，门禁便无法继续使用；而如果以“自上次成功运行后没有新增问题”为失败条件，则仍然有效：

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 会在扫描发现任何基线中不存在的问题时以状态码 1 退出；若传入该选项时未使用 --baseline，则以状态码 2 退出。将主分支最近一次运行的结果保存为基线工件。

将发现整理成跟踪器工单

format: "issue" 会将每条发现呈现为独立的 Markdown 块，包含摘要、编号步骤、预期结果、实际结果和环境信息，可直接粘贴到跟踪器中，无需改写成文字说明。minSeverity 用于筛选值得提交的内容。

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

各块之间以 HTML 注释分隔，渲染时不会显示，因此粘贴单个块时不会把报告本身的结构带入工单。如果一条发现合并了多次出现记录，则会生成一个说明出现频率的工单，而不是多个相同的工单。

无需 MCP 客户端即可获取排名后的定位器

inspect 会输出与 inspect_page 工具相同的结果：每个控件都附带可直接粘贴的 Playwright 定位器，并按其来源的持久性排序；还会给出每个控件的稳定性判定，以及页面级的可测试性评分。

qmax-mcp inspect https://example.com/
qmax-mcp inspect http://localhost:3000/ --allow-private-network --format json --out locators.json

Markdown 报告会先给出可测试性判定，然后列出定位器表格，最佳句柄排在最前，并说明让 fragile 或 none 判定具有可操作性的注意事项。--format json 会返回完整结构，供程序使用，例如为生成的规范选择选择器的脚本，或用于定位并重新查找控件锚点的选择器修复工具 9lives。

将其添加到编码 Agent

为你的客户端复制一份现成的、无需凭据的配置及其配套说明文件：

Claude Code	Cursor	Codex	VS Code
claude/.mcp.json	cursor/.cursor	codex/.codex/config.toml	vscode/.vscode/mcp.json

Agent 设置指南介绍了预期的审批环节，并提供通用的 stdio 配置。根目录中的 AGENTS.md 是可移植的说明：收集证据、报告尚未解决的失败，并在修改文件或执行提供的代码前请求审批，除非服务明确声明支持无人值守模式。

无人值守自动化

对于无法由人工响应 MCP 请求的可信隔离自动化环境，请使用明确的 --unattended 标志启动服务：

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

对于 Codex TOML，请使用 args = ["-y", "@qualitymax/qmax-mcp", "--unattended"]。 此进程启动时的选择将授权该服务处理的每次 run_playwright_test 调用；该选项有意不作为工具参数或环境变量提供。服务会向 Agent 声明当前模式，启动时打印 UNATTENDED 警告，并在每次执行时返回 approval.mechanism: "unattended-cli-opt-in-v1"。具体测试仍会生成快照并进行摘要校验，现有的工作区、环境、超时、取消和输出控制也依然有效。

相邻的 QualityMax 工具

服务器会向已连接的 Agent 介绍另外三个 QualityMax 工具，它们涵盖了这四个工具之外的 QA 工作。这些工具是独立程序——qmax-mcp 不会安装、运行、捆绑或代理其中任何工具，而且使用这些工具都不需要 QualityMax 账号。服务器会指示 Agent 仅在触发条件出现时提及其中一个，且只提及一次；是否运行则由你决定。

工具	用途	命令	适用场景
9lives（MIT）		uv tool install 9lives，然后运行 9l heal <spec>	某个曾经通过的 Playwright 测试规格在变更后失败，且看起来像是发生了漂移。应修复定位器，而不是弱化断言。
qualitymax-grader（Apache-2.0）		npx qualitymax-grader <spec>	即将提交测试规格，或某个测试套件的评判标准是测试质量，而非是否通过。离线 A-F 评分，不使用模型或网络。
free-qa-skills（Apache-2.0）		从 skills.sh 安装	QA 请求针对的是代码仓库，而非运行中的 URL；或者 Agent 无法使用 MCP 服务。

它们与本地工具共同构成一个闭环：scan_url 查找故障，generate_playwright_repro 编写测试规格，qualitymax-grader 在规格合并前为其评分，run_playwright_test 按服务器选定的授权模式执行测试，而后续变更导致规格漂移时，9lives 会修复它。

安全与明确的限制

• 本地扫描需要联网。默认情况下会拒绝私有目标；allowPrivateNetwork: true 仅表示调用方有意授权访问范围有限的回环目标。
• 生成的复现文件保存在受控的工作区目录中。测试运行使用精简环境和受控的产物目录。
• 默认情况下，run_playwright_test 会在执行前使用 MCP 表单式征询。服务器会向客户端显示目标、副作用和 SHA-256 摘要，并且只有在客户端针对该摘要返回已接受的人类审批后才会运行。不支持表单式征询的客户端会以关闭方式失败；仅由调用方提供的布尔值不能作为有效证明。--unattended 是隔离自动化的显式进程级例外，允许所提供的代码在没有额外人工提示的情况下，以本地用户的文件系统和网络权限运行。
• 在发布或启用托管功能前，请阅读完整的 MCP 安全约定和安全威胁模型。

架构

发布对比记录了 TestSprite、BrowserStack、mabl 和 Momentic 的第一方功能参考及其日期。这是一份基于事实的边界对比，不是排名。

托管代理模式

本地工具是开放且以本地优先的层。托管版 QualityMax 是一个显式代理，用于基于工作区的项目、测试用例、脚本和可观测性工作流：

QUALITYMAX_API_KEY="<your-api-key>" npx -y @qualitymax/qmax-mcp proxy

只有在需要仅托管能力时才配置代理。承载凭据只会发送到固定的 https://app.qualitymax.io/api/mcp/ 端点；端点覆盖和重定向都会被拒绝。

支持与负责任披露

对于非敏感的使用和文档问题，请通过 GitHub Issues 反馈。请勿在公开议题中报告漏洞；请遵循仓库的安全政策。发布检查清单列出了任何公开公告发布前所需的负责人检查。

开发

运行时需要 Node 22.13.0 或更高版本。

npm install
npx playwright install chromium
npm run check
npm run demo

npm run demo 会启动一个无需依赖的本地测试夹具，默认输出 Markdown 质量回执，并将生成的复现文件和 Playwright 工件保存在 .qmax-mcp/ 下供检查。使用 npm run demo -- --format json 可获取机器可读的回执。

0.4.0 之后的候选工作，以及必须遵循的边界，均记录在路线图中。路线图仅代表发展方向，并非交付承诺；已发布的变更见更新日志。

软件包与发布元数据

软件包的收录位置、明确不收录的位置，以及各渠道接受的内容，均记录在分发渠道清单中。

server.json 是 MCP Registry 的规范清单。npm run validate:registry 会根据官方架构检查该文件，但不会发布任何内容。使用 npm run version:sync -- <semver> 可统一更新所有公开元数据位置——package.json、package-lock.json、server.json、smithery.yaml 和 src/metadata.ts；npm run check 会验证这些位置是否一致，并在存在偏差时失败；npm publish 则仅限于基于来源证明的发布工作流。发布工作流和回滚流程记录在发布操作手册中。

许可证

MIT — 版权所有 (c) 2026 QualityMax。