QualityMax QA MCP

QualityMax QA MCP

重要

これらのチェックは現在、9lives に搭載されています。 9lives v0.4.0 以降、9l scan と 9l inspect で同じ 9 つのページチェックとロケーターの検査を実行できます。また、9l mcp では、コーディングエージェントが scan_url、inspect_page、generate_playwright_repro を、実行、修復、評価、確認の各ツールとともに利用できます。ローカルサーバーは 1 つだけで、アカウントは不要です。qmax.run でこのプロジェクトをホストすることは終了しました。9lives.run と変更したページをチェックするをご覧ください。新機能や修正は 9lives-runner に追加されます。未解決の Issue もそちらに移動しました。0.9.2 がこのパッケージの最終リリースです。引き続きインストールできますが、今後修正は提供されません（9lives-runner#100）。

Web の変更が完了したと宣言する前に、コーディングエージェントに独立した QA の根拠を提示しましょう。ページをスキャンし、UI を検査し、対象を絞った Playwright の再現テストを生成してから、実行結果を確認します。

npx -y @qualitymax/qmax-mcp

4 つのローカルツールを利用するのに、QualityMax アカウント、API キー、ホスト型サービスは必要ありません。

ドキュメント · ホスト型 MCP のセットアップ · ローカルデモ

このパッケージは、単独で利用できる 4 つのローカルツールを提供します。ホスト型ワークスペースへのアクセスは、別途認証済みの接続が必要です。プラットフォームのプロジェクトやワークフローを利用する場合は、ホスト型 MCP のセットアップをご利用ください。

役立つ結果をまず試す

MCP 対応エージェントに、変更した URL をスキャンするよう依頼するか、ローカル CLI を実行します。

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

レポートには、評価付きの概要、検出事項、具体的な再現手順、修正案が含まれます。1 つのコマンドで、チェックイン済みの依存関係のないフィクスチャに対して 4 つのツールすべてを実行できます。詳しくは再現可能なデモをご覧ください。

1 回のスキャンで測定する内容

9 つのチェックはすべて、1 回のページ読み込みで実行されます。一部のチェックだけを実行するには、checks を渡します。

チェック	レポート内容
console	JavaScript のエラー、警告、失敗したリクエスト
links	maxLinks までのリンク切れとリダイレクトするリンク
accessibility	alt テキストの欠落、ラベルのないコントロール、名前のないインタラクティブ要素、見出し構造
performance	Core Web Vitals：LCP、CLS、TTFB、FCP
seo	タイトルとメタディスクリプション
security_headers	CSP、HSTS、X-Content-Type-Options、Referrer-Policy
cookies	Secure／HttpOnly／SameSite の欠落、サードパーティ Cookie、既知のトラッカー、同意前のトラッキング
mixed_content	HTTPS ページ上の HTTP サブリソースとフォームの送信先。ブラウザーによってブロックされるアクティブコンテンツとパッシブコンテンツに分類
weight	転送バイト数、リクエスト数、レンダリングをブロックするリソース、サイズ超過および未圧縮のアセット、サードパーティのコスト

名前は完全一致する必要があります。認識されない名前は、スキップされるのではなく、対応している名前の一覧とともに拒否されます。そのため、タイプミスによってチェックが黙って無効になり、スコアが返されることはありません。

scan_url は、測定した Web Vitals とページ容量の内訳（最も遅いリクエストを含む）を記載した metrics ブロックも返します。このブロックには、隠されることのない 2 つの制限も明記されています。実際のユーザー操作が必要なため INP は測定されません。また、Web Vitals はフィールドデータではなく、スキャンを実行するマシンでのコールドロード 1 回分の値です。独自のパフォーマンス予算に照らしてスキャンするには、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 を使用します。

エージェントができること

ツール	ローカルでの機能	確認すべき境界
scan_url	必要に応じて Playwright のストレージ状態ファイルを使用し、URL をスキャンして、コンソール、ネットワーク、テレメトリー SDK、リンク、アクセシビリティ、SEO、セキュリティヘッダー、Cookie／トラッカー、混在コンテンツ、ページ容量、Core Web Vitals に関する問題を検出します。	外部へのリクエストを送信し、認証情報を含む、明示的に選択されたワークスペースファイルを読み取る場合があり、スクリーンショットを書き込むことがあります。
inspect_page	必要に応じて、認証済みページ用の Playwright ストレージ状態ファイルを使用し、ページ構造とロケーター候補のロール／名前を返します。	外部へのリクエストを送信し、認証情報を含む、明示的に選択されたワークスペースファイルを読み取る場合があります。
generate_playwright_repro	ワークスペース内に、決定的な Playwright 再現スクリプトを書き込みます。	.qmax-mcp/repros 以下に書き込みます。上書きは明示的に行われます。
run_playwright_test	ローカルの Playwright テストを 1 件実行し、構造化されたステータスを返します。	コードを実行し、制御された成果物を書き込みます。デフォルトでは、承認済みでダイジェストに紐付けられた MCP の人間による承認確認が必要です。

ローカルサーバーを使用するのにアカウントは必要ありません。ホスト型プロキシモードは、アカウントに紐付けられた QualityMax 機能を利用するための、別個のオプトイン接続です。その機能が必要な場合を除き、追加しないでください。

認証済みページをスキャンまたは調査する

どちらのツールも、Playwright のストレージ状態ファイルを読み込みます。このファイルを作成するのが最初のステップです。最短の方法を 2 つ紹介します。

自分でログインするブラウザーから作成する場合 — コードは不要で、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 のストレージ状態には Cookie、ローカルストレージ、必要に応じて IndexedDB が含まれますが、セッションストレージは保持されません。

スキャン結果を以前の結果と比較する

scan_url は変更後に使用することを想定しているため、比較に適しています。スキャンし、何かを変更して、再度スキャンし、判断します。以前のスキャン結果、またはワークスペースからの相対パスで指定した以前のスキャン結果を baseline に渡すと、応答に delta が含まれ、どの検出結果が new、fixed、unchanged なのかと、1 行の判定が示されます。

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

各検出結果には、カテゴリ、メッセージ、URL またはセレクターから導出される安定した id が付与されるため、同じ問題は実行ごとに同じハッシュになります。意図的に、重大度と発生回数はその識別情報に含めていません。そのため、検出結果の分類が変わったり、発生回数が 3 回から 4 回に増えたりしても、同じ検出結果として扱われます。

CI でゲートを実用的に運用するには、この仕組みが重要です。findingCount > 0 を条件に失敗させる方法は、既知で問題のない検出結果が 1 件でもページにあると使えなくなります。一方、「前回の成功時以降に新しいものがない」ことを条件にすれば、引き続き使えます。

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 コメントで区切られています。コメントは表示されないため、1 つを貼り付けてもレポート自体の構造がチケットに持ち込まれることはありません。複数回発生した検出結果は 1 つにまとめられ、同じチケットがいくつも作成されるのではなく、発生頻度を記載した 1 つのチケットになります。

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 のようなセレクター修復ツールで、コントロールを再検出するためのアンカーを選ぶ用途に使えます。

コーディングエージェントに追加する

クライアント用の、認証情報不要ですぐに使える設定ファイルと、それに対応する指示ファイルをコピーしてください。

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

エージェント設定ガイドでは、想定される承認方法について説明し、汎用的な 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 ツール

サーバーは、接続されたエージェントに対し、この 4 つのツールでは対応しない QA 作業をカバーする、QualityMax の独立した 3 つのツールについて伝えます。これらは独立したプログラムです。qmax-mcp がインストール、実行、バンドル、プロキシすることはなく、いずれも QualityMax アカウントを必要としません。エージェントには、該当するトリガーがある場合に限り、ツールを 1 つだけ一度名前を挙げるよう指示されます。実行するかどうかの判断はユーザーに委ねられます。

ツール	使用状況	コマンド	使用する場面
9lives (MIT)		uv tool install 9lives、続いて 9l heal <spec>	以前は成功していた Playwright の spec が変更後に失敗し、その原因がずれに見える場合です。アサーションを弱めるのではなく、ロケーターを修復します。
qualitymax-grader (Apache-2.0)		npx qualitymax-grader <spec>	spec をコミットする直前、またはテストスイートがテストの品質で評価され、テストの成功では評価されない場合です。モデルもネットワークも不要な、オフラインの A-F 評価です。
free-qa-skills (Apache-2.0)		skills.sh からインストール	QA の依頼が実行中の URL ではなくリポジトリに関するものの場合、またはエージェントが MCP サーバーを利用できない場合です。

ローカルツールと合わせると、これらは 1 つのループを形成します。scan_url が失敗を検出し、generate_playwright_repro が spec を作成し、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は、何も公開せずに公式スキーマとの適合性を確認します。package.json、package-lock.json、server.json、smithery.yaml、src/metadata.tsといったすべての公開メタデータをまとめて更新するには、npm run version:sync -- <semver>を使用してください。npm run checkはそれらの整合性を確認し、不一致があれば失敗します。また、npm publishの実行は、来歴情報に裏付けられたリリースワークフローに限定されています。リリースワークフローとロールバック手順は、リリース手順書に記載されています。

ライセンス

MIT — Copyright (c) 2026 QualityMax。