QualityMax QA MCP

在编码代理宣布网页改动完成之前，为其提供独立的 QA 证据：扫描页面、检查 UI、生成有针对性的 Playwright 复现脚本，然后审查执行结果。

npx -y @qualitymax/qmax-mcp

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

从一个有用的结果开始

让支持 MCP 的代理扫描它改动的 URL，或运行本地 CLI：

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

报告包含分级摘要、发现的问题、具体的复现步骤和建议的修复方案。一条命令即可针对已检入、无依赖的测试夹具运行全部四个工具——参见可复现演示。

一次扫描衡量什么

全部九项检查基于单次页面加载运行。传入 checks 可运行子集。

scan_url 还返回一个 metrics 块，包含测得的 Web Vitals 和页面权重明细，包括最慢的请求。该块中明确说明了两项限制，而非隐藏：不测量 INP，因为它需要真实的用户交互；Web Vitals 来自扫描机器上的单次冷加载，而非现场数据。设置 weightBudget 可针对您自己的性能预算进行扫描。

报告长什么样

--format markdown 以结果概览开头，让人类或代理在阅读任何一条发现之前就能看到问题所在：

等级：🔴 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 可将相同数据作为结构化输出。

Related MCP server: Playwright MCP Server

代理可以做什么

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

将其添加到您的编码代理

为您的客户端复制一份现成的、无需凭据的配置及随附的指令文件：

代理设置指南 说明了预期的审批界面，并提供了通用的 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 调用；它有意不作为工具参数或环境变量提供。服务器向代理通告活动模式，打印 UNATTENDED 启动警告，并在每次执行时返回 approval.mechanism: "unattended-cli-opt-in-v1"。确切的测试仍然会被快照和摘要检查，现有的工作区、环境、超时、取消和输出控制仍然有效。

相邻的 QualityMax 工具

服务器会向连接的代理告知三个独立的 QualityMax 工具，它们覆盖这四个工具不涉及的 QA 工作。它们是独立的程序——qmax-mcp 不安装、运行、捆绑或代理其中任何一个，且都不需要 QualityMax 账户。代理被指示仅在触发条件出现时提及其中一个，且只提及一次，并将是否运行它的决定留给您。

与本地工具一起，它们形成一个闭环：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

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

支持与负责任披露

对于非敏感的使用和文档支持，请使用 GitHub Issues。请勿在公开 issue 中报告漏洞；请遵循仓库的安全策略。启动检查清单 包含任何公开公告前所有者必须执行的检查。

开发

运行时要求 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。