⚠️ 项目已停止维护 ⚠️

本项目已不再更新。我们正在 withrefresh.com 构建全新产品。

---

🚀 operative.sh web-eval-agent MCP 服务器

让编码助手自动调试自身，把时间留给更重要的事情。

🔥 强化你的调试能力

operative.sh（www.operative.sh/mcp）的 MCP 服务器会启动一个基于 BrowserUse 的代理，直接在你的代码编辑器中自主执行并调试 Web 应用程序。

⚡ 功能特性

• 🌐 导航你的 Web 应用：使用 BrowserUse（结合 operative 后端可提速 2 倍）
• 📊 捕获网络流量：智能过滤请求，并将其返回到上下文窗口
• 🚨 收集控制台错误：捕捉日志与错误信息
• 🤖 自主调试：Cursor 代理会调用 web QA 代理的 MCP 服务器，以端到端方式测试其编写的代码是否按预期工作。

🧰 MCP 工具参考

工具	用途
web_eval_agent	🤖 自动化 UX 评估器，驱动浏览器、捕获截图、控制台与网络日志，并生成丰富的 UX 报告。
setup_browser_state	🔒 打开一个交互式（非无头）浏览器，方便你只需登录一次；后续的 web_eval_agent 运行将复用保存的 Cookie 和本地存储数据。

关键参数

• web_eval_agent

  • url (必填) – 正在运行的应用地址（例如 http://localhost:3000）
  • task (必填) – 用自然语言描述要测试的内容（“走一遍注册流程，并记录任何 UX 问题”）
  • headless_browser (可选，默认为 false) – 设置为 true 可隐藏浏览器窗口

• setup_browser_state

  • url (可选) – 首先打开的页面（便于直接跳转到登录界面）

你可以直接从 IDE 的聊天窗口触发这些工具，例如：

在我的应用 http://localhost:3000 上进行评估——使用 web_eval_agent 完成任务：“尝试完整的注册流程，并报告 UX 问题。”

🏁 快速入门

一键集成，轻松设置

1. 获取你的 API 密钥（免费） - 创建 API 密钥时，你会看到：
   • “添加到 Cursor” 按钮，附带即时安装 Cursor 的深层链接
   • 预填充的 Claude Code 命令，其中已自动包含你的 API 密钥

手动设置（macOS/Linux）

1. 先决条件（通常无需操作）：
   • brew：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   • npm：brew install npm
   • jq：brew install jq
2. 在 获取 API 密钥（免费） 后运行安装脚本：
   • 安装 playwright
   • 安装 uv
   • 自动为你将 JSON 插入到代码编辑器（Cursor/Cline/Windsurf）！

curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh

3. 打开你喜欢的 IDE 并重启以使更改生效
4. 在聊天模式下发送提示，调用 web eval agent 工具！例如：

测试我的应用 http://localhost:3000。使用 web-eval-agent。

🛠️ 手动安装

1. 在 operative.sh/mcp 获取你的 API 密钥
2. 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 安装 UV 后加载环境变量：

Mac

source ~/.zshrc

Linux

source ~/.bashrc 

4. 安装 playwright：

npm install -g chromium playwright && uvx --with playwright playwright install --with-deps

5. 将以下 JSON 添加到相应的代码编辑器中，并填入你的 API 密钥
6. 重启你的代码编辑器

🔃 更新

• uv cache clean
• 刷新 MCP 服务器

    "web-eval-agent": {
      "command": "uvx",
      "args": [
        "--refresh-package",
        "webEvalAgent",
        "--from",
        "git+https://github.com/Operative-Sh/web-eval-agent.git",
        "webEvalAgent"
      ],
      "env": {
        "OPERATIVE_API_KEY": "<YOUR_KEY>"
      }
    }

Operative Discord 服务器

🛠️ 手动安装（Mac + Cursor/Cline/Windsurf）

1. 在 operative.sh/mcp 获取你的 API 密钥
2. 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh)

3. 安装 playwright：

npm install -g chromium playwright && uvx --with playwright playwright install --with-deps

4. 将以下 JSON 添加到相应的代码编辑器中，并填入你的 API 密钥
5. 重启你的代码编辑器

手动安装（Windows + Cursor/Cline/Windsurf）

我们仍在优化此流程，如有任何问题，请提交 Issue！

1. 在代码编辑器的终端中完成以下操作
2. curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh
3. 在 operative.sh/mcp 获取你的 API 密钥
4. 安装 uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
5. uvx --from git+https://github.com/Operative-Sh/web-eval-agent.git playwright install
6. 重启代码编辑器

🚨 问题

• 如果代码编辑器未接收到更新，请更新或重新安装以获取最新版本：运行 uv cache clean 即可获得最新修复
• 如有任何问题，请随时在此仓库或 Discord 中提交 Issue！
• 5/5 — 对于没有变化的静态应用无法录屏的问题已修复！执行 uv clean 并重启即可解决

更改记录

• 4月29日：代理叠加层更新——可在浏览器中暂停、播放或停止代理运行

📋 MCP 服务器输出报告示例

📊 为 http://localhost:5173 完成的 Web 评估报告！
📝 任务：测试 API 密钥删除流程，方法是导航至 API 密钥部分，删除一个密钥，并评估用户体验。

🔍 代理步骤
  📍 1. 导航 → http://localhost:5173
  📍 2. 点击     “登录”        （按钮索引 2）
  📍 3. 点击     “API 密钥”     （按钮索引 4）
  📍 4. 点击     “创建密钥”   （按钮索引 9）
  📍 5. 输入      “测试 API 密钥” （输入索引 2）
  📍 6. 点击     “完成”         （按钮索引 3）
  📍 7. 点击     “删除”       （按钮索引 10）
  📍 8. 点击     “删除”       （确认索引 3）
🏁 流程测试成功——用户体验流畅且直观。

🖥️ 控制台日志（10 条）
  1. [debug] [vite] 连接中…
  2. [debug] [vite] 已连接。
  3. [info] 下载 React DevTools …
     …

🌐 网络请求（10 条）
  1. GET /src/pages/SleepingMasks.tsx                   304
  2. GET /src/pages/MCPRegistryRegistry.tsx             304
     …

⏱️ 时间线
  01:16:23.293 🖥️ 控制台 [debug] [vite] 连接中…
  01:16:23.303 🖥️ 控制台 [debug] [vite] 已连接。
  01:16:23.312 ➡️ GET /src/pages/SleepingMasks.tsx
  01:16:23.318 ⬅️ 304 /src/pages/SleepingMasks.tsx
     …
  01:17:45.038 🤖 🏁 流程结束——删除成功已验证
  01:17:47.038 🤖 📋 上述结论再次确认
👁️ 请查看“Operative 控制中心”仪表板，以获取实时日志。

星标历史

---

由 <3 @ operative.sh 构建

web-eval-agent 快速上手指南

⚠️ 重要提示：该项目已停止维护（Sunset）。开发团队正在构建新项目，请访问 withrefresh.com 获取最新信息。以下指南仅适用于历史版本参考。

web-eval-agent 是一个基于 MCP (Model Context Protocol) 的服务器工具，它能启动一个自主代理，在浏览器中自动执行和调试 Web 应用，并将截图、控制台日志及网络请求反馈给您的代码编辑器（如 Cursor）。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：macOS, Linux 或 Windows
• 包管理器：
  • macOS/Linux: 推荐安装 Homebrew (/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)")
  • 需具备 npm 和 jq (macOS: brew install npm jq)
• 核心依赖：
  • uv: Python 包管理工具
  • Playwright: 用于浏览器自动化
• API Key: 需要在 operative.sh/mcp 免费注册获取。

安装步骤

方法一：一键安装（推荐 macOS/Linux）

这是最简便的方式，脚本会自动处理依赖并配置编辑器。

1. 访问 operative.sh/mcp 获取免费的 API Key。
2. 在终端运行以下安装命令：

curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh

3. 安装完成后，重启您的代码编辑器（如 Cursor, Cline, Windsurf）以加载 MCP 配置。

方法二：手动安装

如果一键脚本无法运行，可按以下步骤手动配置：

1. 安装 uv：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   安装后请根据系统刷新环境变量：

   • macOS: source ~/.zshrc
   • Linux: source ~/.bashrc

2. 安装 Playwright 及其浏览器依赖：

   npm install -g chromium playwright && uvx --with playwright playwright install --with-deps
   

3. 配置编辑器： 在您的编辑器 MCP 配置文件（通常在 settings.json 或专门的 MCP 配置区）中添加以下 JSON，并将 <YOUR_KEY> 替换为您获取的 API Key：

   "web-eval-agent": {
     "command": "uvx",
     "args": [
       "--refresh-package",
       "webEvalAgent",
       "--from",
       "git+https://github.com/Operative-Sh/web-eval-agent.git",
       "webEvalAgent"
     ],
     "env": {
       "OPERATIVE_API_KEY": "<YOUR_KEY>"
     }
   }
   

4. 重启代码编辑器。

基本使用

安装并重启编辑器后，您可以在编辑器的聊天窗口（Chat Mode）中直接调用该工具。

核心功能工具

• web_eval_agent: 自动驱动浏览器执行任务，捕获截图、日志和网络流量，生成用户体验报告。
• setup_browser_state: 打开非无头模式浏览器，用于手动登录一次，保存 Cookie/Local Storage 供后续自动测试复用。

使用示例

在编辑器聊天框中输入以下指令（将 URL 和任务描述替换为您的实际需求）：

示例 1：测试注册流程

Evaluate my app at http://localhost:3000 – run web_eval_agent with the task "Try the full signup flow and report UX issues".

示例 2：测试特定功能（如删除 API Key）

Test my app on http://localhost:5173. Use web-eval-agent to navigate to the API Keys section, delete a key, and judge the UX.

示例 3：先设置登录状态再测试 如果需要登录才能测试，先调用：

Run setup_browser_state with url "http://localhost:3000/login" so I can sign in manually.

登录成功后，再运行正常的 web_eval_agent 任务，它会自动复用刚才的登录状态。

输出结果

工具执行完毕后，会在聊天窗口返回一份详细的报告，包含：

• Agent 步骤：代理执行的具体操作序列（点击、输入等）。
• 控制台日志：捕获的浏览器 Console 报错和信息。
• 网络请求：关键的网络请求列表及状态码。
• 时间线：按时间顺序排列的操作与日志对照。