cowork-qa

cowork-qa-mcp

一个 Model Context Protocol 服务，可为大模型提供真实的 Chromium 浏览器，记录它为实现既定目标执行的每项操作，并返回结构化跟踪记录，以便大模型（或第二个大模型）判断目标是否真正达成。

基于 Playwright 构建。五个工具、一个二进制文件，无需依赖云服务。

为什么需要它

大多数浏览器工具 MCP 服务都是无状态的——大模型点击后获得 HTML，再重复操作。没有操作记录，无法事后评估运行结果，也没有目标上下文。

cowork-qa-mcp 改变了这一点：

• 每个会话都以一段通俗易懂的目标描述作为起点。
• 每项操作（goto、click、fill、press、eval）都会连同时间戳、操作后的 URL 以及页面的 aria-snapshot 一起记录。
• 会话结束时，JSON 跟踪记录会保存到磁盘，并通过单次 qa_get_trace 调用提供。

随后，负责协调的大模型可以根据跟踪记录进行推理（“这次运行真的实现目标了吗？还是点错了按钮？”），而不是盲目信任运行时的对话内容。

工具

工具	功能
session_start	打开一个新标签页，可选起始 URL，并返回会话 ID
session_act	执行以下操作之一：goto、click、fill、press、eval。记录该步骤。
session_observe	返回当前 URL 和页面完整的 aria-snapshot
session_end	关闭标签页，将跟踪记录保存到磁盘，并返回文件路径
qa_get_trace	返回目标、每个步骤、最终 URL 和最终 aria-snapshot，格式便于大模型阅读

安装

需要 Node 20+。该软件包发布在 npm 上，无需克隆。

# Try it once, no install
npx cowork-qa-mcp

# Or install globally
npm install -g cowork-qa-mcp

首次安装时，Playwright 的 postinstall 会下载 Chromium（约 150 MB）。

接入兼容 MCP 的客户端

Claude Code

claude mcp add cowork-qa --scope user -- npx -y cowork-qa-mcp

如需查看浏览器而非以无头模式运行：

claude mcp add cowork-qa --scope user \
  -e COWORK_QA_HEADED=1 \
  -- npx -y cowork-qa-mcp

在新的 claude 会话中运行 /mcp 进行验证——你应该会看到 cowork-qa ✓ connected 和 5 个工具。

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

Cursor / Windsurf / 其他 MCP 客户端

任何支持 MCP stdio 传输的客户端都可以使用。将其服务配置指向 npx -y cowork-qa-mcp。

从源代码构建（用于开发）

git clone https://github.com/inSideos-designs/cowork-qa-mcp.git
cd cowork-qa-mcp
npm install
npm run build
node dist/server.js   # stdio server, expects an MCP client

MCP Registry

此服务也已发布到官方 MCP Server Registry，名称为 io.github.inSideos-designs/cowork-qa——能够从 Registry 自动发现服务的客户端无需手动配置即可找到它。

环境变量

变量	默认值	用途
COWORK_QA_HEADED	未设置（无头模式）	设置为 1，以可见窗口启动 Chromium
COWORK_QA_DATA	<cwd>/.cowork-qa	写入 <session-id>.json 跟踪记录的目录

使用示例

负责协调的大模型执行的典型端到端流程：

session_start({ goal: "find the cheapest 14\" MacBook Pro on apple.com",
                url: "https://www.apple.com/shop/buy-mac/macbook-pro" })
  → { session_id: "abc-123" }

session_observe({ session_id: "abc-123" })
  → URL + aria-snapshot

session_act({ session_id: "abc-123", action: "click",
              target: "button:has-text('Continue')" })

# ... more acts / observes ...

session_end({ session_id: "abc-123" })
  → { steps: 7, trace_path: "~/.cowork-qa/abc-123.json" }

qa_get_trace({ session_id: "abc-123" })
  → Goal: ...
    Steps (7 total): ...
    Final URL: ...
    Final aria-snapshot: ...

跟踪记录格式

每条跟踪记录都是一个 JSON 文件：

{
  "session_id": "abc-123",
  "goal": "...",
  "steps": [
    {
      "t": 142,
      "action": "click",
      "args": { "target": "...", "value": null },
      "url_after": "...",
      "aria_after": "..."
    }
  ],
  "final": { "url": "...", "aria": "..." },
  "path": "/.../abc-123.json"
}

限制 / 已知问题

• session_observe 调用不会计入跟踪记录的步骤数——只有 session_act 调用会计入。最终 aria-snapshot 会在 session_end 时捕获。
• eval 会运行 JS 表达式，但不会将返回值交给调用方——只能观察页面上的副作用。
• 一个服务实例中的所有会话共用一个 Chromium 进程；每个会话都有独立的上下文（Cookie 等彼此隔离）。
• 选择器会直接传递给 Playwright。CSS、文本选择器（button:has-text("Send")）和 role= 选择器均可使用。

许可证

MIT——请参阅 LICENSE。

贡献

欢迎提交 PR。请保持精简：本项目旨在始终作为一个轻量、易审计的服务。