QA Wrap bridge

qa-wrap-bridge

让编码 Agent（Claude Code、Cursor 或任何 MCP 客户端）读取 QA Wrap 中记录的测试会话。

这是一个小型 Node 程序，有两项功能：

• 一个由 Agent 启动的 MCP 服务（stdio），以及
• 一个由 Chrome 或 Edge 启动的 原生消息传递主机，让服务能够向 QA Wrap 扩展询问其保存的内容。

这是可选功能。不启用它，QA Wrap 也能照常工作；只有在 QA Wrap 的 Settings 中开启 Agent bridge 后，它才会运行。

设置

1. 在终端中安装此辅助工具的注册信息，只需安装一次：

   npx qa-wrap-bridge
   

   这会将主机复制到 ~/.qa-wrap-bridge/host/，为 Chrome 和 Edge 写入原生消息传递主机清单（Windows 上写入注册表，macOS 和 Linux 上写入浏览器的 NativeMessagingHosts 文件夹），在其旁边创建一个私钥文件，并输出 Agent 的配置。需要 Node 20 或更高版本。

2. 在 QA Wrap 中打开 Settings > Privacy，并开启 Agent bridge。浏览器会请求一项权限：nativeMessaging。QA Wrap 只会在此时请求该权限，并会在你关闭桥接功能时归还权限。

3. 告知 Agent 此服务。命令会为你的系统输出以下配置：

   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 上，命令为 cmd，参数为 /c npx -y [email protected] mcp。

如果使用的 QA Wrap 是 Microsoft Edge Add-ons 版本（其扩展 ID 不同），请添加：npx qa-wrap-bridge install --extension-id <the 32-letter id from edge://extensions>。

要移除所有内容：npx qa-wrap-bridge uninstall。

Agent 可以请求的内容

工具	返回内容
list_sessions	此设备上的会话，按时间从新到旧排列：ID、标题、开始和结束时间、状态、事件和失败数量。可选参数 limit。
get_session	一个会话，采用已记录的 qawrap.session/1 格式（extension/docs/session-json.md）。可选参数 session_id；若省略，则返回最新会话。
get_failures	一个会话中仅包含失败的内容（失败的请求和控制台错误；重复项会合并并附带计数）。
get_ai_brief	“Copy for AI”生成的精简纯文本块。

在 MCP 中，这四项均标记为只读。

它绝对无法做到的事

• 写入。 没有任何工具可以启动、更改、重命名或删除内容。主机只转发上面列出的四个名称，扩展也只通过不包含写入调用的代码来响应。两项测试对此进行了验证。
• 连接网络。 主机监听本地管道（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 如何处理收到的文本（包括是否发送给模型）属于 Agent 自身的行为。只有当你信任某个 Agent 可以访问测试数据时，才开启桥接功能。

各组件如何通信

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

只有在桥接已开启 且 已授予权限时，扩展才会保持原生端口开放。如果浏览器已关闭或桥接已关闭，工具调用会返回一句说明 QA Wrap 未连接的消息。

同一时间只能有一个浏览器占用主机（第二个浏览器的主机进程会因套接字已被占用而退出）。

开发

npm install
npm test

npm test 会启动真实主机作为子进程，通过虚拟浏览器端口进行测试；通过官方客户端测试 MCP 服务；并在临时文件夹中测试适用于 Windows、macOS 和 Linux 的安装程序。扩展也会运行 node tools/test-agent-bridge.mjs，并测试扩展端的功能。