QA Wrap bridge

qa-wrap-bridge

コーディングエージェント（Claude Code、Cursor、その他の MCP クライアント）が、QA Wrap に記録されたテストセッションを読み取れるようにします。

これは、次の 2 つの役割を持つ小さな Node プログラムです。

• エージェントが起動する MCP サーバー（stdio）と、
• サーバーが QA Wrap 拡張機能のデータを取得できるように、Chrome または Edge が起動する ネイティブメッセージングホスト。

これは任意の機能です。なくても QA Wrap は同じように動作し、QA Wrap の Settings で Agent bridge をオンにするまで無効です。

セットアップ

1. ターミナルでヘルパーを登録します。登録は一度だけでかまいません。

   npx qa-wrap-bridge
   

   これにより、ホストが ~/.qa-wrap-bridge/host/ にコピーされ、Chrome と Edge 用のネイティブメッセージングホストマニフェスト（Windows ではレジストリ、macOS と Linux では各ブラウザーの NativeMessagingHosts フォルダー）が書き込まれ、その隣に秘密鍵ファイルが作成されて、エージェント用の設定が出力されます。Node 20 以降が必要です。

2. QA Wrap の Settings > Privacy を開き、Agent bridge をオンにします。ブラウザーから nativeMessaging の権限を求められます。QA Wrap がこの権限を要求するのはこの時だけで、ブリッジをオフにすると権限を返します。

3. エージェントにサーバーの情報を伝えます。このコマンドは、お使いのシステム向けに次の設定を出力します。

   Claude Code：

   claude mcp add qa-wrap -- npx -y [email protected] mcp
   

   Cursor（.cursor/mcp.json）または .mcp.json を読み取るクライアント：

   { "mcpServers": { "qa-wrap": { "command": "npx", "args": ["-y", "qa-wrap-bridge", "mcp"] } } }
   

   Windows では、コマンドは /c npx -y [email protected] mcp を引数に指定した cmd です。

Microsoft Edge Add-ons 版の QA Wrap を使っていて、拡張機能 ID が異なる場合は、ID を追加してください。npx qa-wrap-bridge install --extension-id <edge://extensions の 32 文字の ID>。

すべてを削除するには、npx qa-wrap-bridge uninstall を実行します。

エージェントが要求できる情報

ツール	戻り値
list_sessions	このマシン上のセッションを新しい順に返します。内容は、ID、タイトル、開始日時と終了日時、ステータス、イベント数、失敗数です。limit は任意です。
get_session	ドキュメントで定義されている qawrap.session/1 形式のセッションを 1 件返します（extension/docs/session-json.md）。session_id は任意です。省略すると、最新のセッションが返されます。
get_failures	セッションの失敗のみを返します（失敗したリクエストとコンソールエラー。同じ内容はまとめて件数を表示します）。
get_ai_brief	「Copy for AI」で生成される、簡潔なプレーンテキストのブロックを返します。

4 つすべてのツールは、MCP で読み取り専用としてマークされています。

絶対にできないこと

• 書き込み。 何かを開始、変更、名前変更、削除するツールはありません。ホストが中継するのは上記 4 つの名前だけで、拡張機能は書き込み処理を含まないコードから応答します。どちらもテストで保証されています。
• ネットワークへのアクセス。 ホストはローカルパイプ（Windows）または Unix ソケット（macOS、Linux）で待ち受け、TCP ポートでは待ち受けません。また、外部への接続も開きません。ソースに HTTP、TLS、UDP、WebSocket のモジュールが含まれていると、テストは失敗します。
• マシン上の別のプログラムによる利用。 ~/.qa-wrap-bridge/token にあるキー（読み取り可能なのは自分のユーザーのみ。Windows ではインストーラーが icacls を使って自分だけに制限します）がソケットを通過することはありません。質問を送信する前に、サーバーとホストは一度限りのチャレンジを使って、キーを保持していることをそれぞれ証明します。そのため、ソケット名を乗っ取ったプログラムが情報を得ることはできません。macOS と Linux では、ソケットの権限は 0600 です。
• マスキングで除外された情報の漏えい。 回答の生成には、QA Wrap の AI エクスポートと同じ関数が使われます。拡張機能からテキストが外部に渡る前に、パスワード、トークン、キー、カード情報、認証情報を含む名前の URL パラメーターがマスキングされます。リクエスト本文とレスポンス本文が全体として含まれることはありません。拡張機能がブラウザーの 1 MiB 制限内に収められない内容は短縮され、その旨が示されます。

受け取ったテキストをエージェントがどう扱うか（モデルへの送信など）は、エージェントの動作によります。テストデータを任せられるエージェントにのみ、ブリッジをオンにしてください。

各要素の通信方法

agent --stdio--> qa-wrap-bridge mcp --local socket--> host (started by the browser) --native messaging--> QA Wrap extension

拡張機能は、ブリッジがオンで、かつ権限が付与されている間だけネイティブポートを開いたままにします。ブラウザーが閉じられているか、ブリッジがオフの場合、ツール呼び出しに対して QA Wrap が接続されていないことを示す文が返されます。

一度にホストを保持できるブラウザーは1つだけです（ソケットが使用中のため、2つ目のブラウザーのホストは終了します）。

開発

npm install
npm test

npm test は、実際のホストを子プロセスとして偽のブラウザーポートに接続し、公式クライアント経由で MCP サーバーを実行し、一時フォルダーを使って Windows、macOS、Linux 向けのインストーラーをテストします。拡張機能の node tools/test-agent-bridge.mjs もこれを実行し、拡張機能側もテストします。