Vuda (visual Ui Debug Agent)

为兼容 MCP 的 AI 客户端提供真实浏览器、屏幕截图、DOM 检查、工作流验证、控制台捕获、API 检查和视觉对比。
_{29 个 MCP 工具 · 本地、Browserbase、Anchor 或任何 CDP 浏览器 · Node.js 20+}

VUDA 的功能

VUDA（Visual UI Debug Agent）是一个基于 Model Context Protocol 的服务，可使用 Playwright 检查和测试 Web 界面。MCP 服务通过标准输入/输出在本地运行；其浏览器可以在本地、Browserbase、Anchor Browser 上运行，也可以连接到现有的 CDP 端点。所有工具都使用同一个已选定的浏览器运行环境。

• 捕获整页、视口、元素、本地文件和批量屏幕截图。
• 映射交互元素，并检查渲染后的 DOM 和计算样式。
• 执行多步 UI 工作流，同时保留浏览器状态。
• 监控控制台输出并分析页面性能。
• 对比两种渲染状态并返回视觉差异。
• 遍历站点地图并调用 API 端点进行测试。
• 模拟受支持的 Playwright 设备。

快速开始

1. 运行 VUDA

npx -y visual-ui-debug-agent-mcp

默认的 local 模式需要兼容 Chromium 的浏览器。如果尚未安装，请安装对应的浏览器：

npx playwright install chromium

2. 将其添加到 MCP 客户端

{
  "mcpServers": {
    "vuda": {
      "command": "npx",
      "args": ["-y", "visual-ui-debug-agent-mcp"]
    }
  }
}

更改 MCP 配置后，请重启客户端。服务会将协议消息写入 stdout，并将诊断信息写入临时日志文件。

本地模式无需提供商账号。

Docker 用户可以使用相同的 stdio 传输方式：

{
  "mcpServers": {
    "vuda": {
      "command": "docker",
      "args": ["run", "--interactive", "--rm", "ghcr.io/samihalawa/visual-ui-debug-agent-mcp:latest"]
    }
  }
}

如需在 Docker 中使用文件里的提供商凭据，请在 args 数组的 "run" 后立即添加 "--env-file", "/absolute/path/to/.env"。

3. 试用

让客户端执行以下操作：

Use VUDA to inspect https://example.com, capture a screenshot, list the
interactive elements, and report console errors and obvious layout issues.

工具参考

分析与捕获

工具	用途
enhanced_page_analyzer	屏幕截图、控制台、性能和交互元素分析
screenshot_url	捕获 URL、视口、整页或指定元素
batch_screenshot_urls	捕获多个 URL，便于并排查看
screenshot_local_files	渲染并捕获本地 HTML 文件
dom_inspector	返回元素属性、子元素和计算样式
visual_comparison	对比两个渲染页面或元素

工作流、诊断和 API

工具	用途
ui_workflow_validator	执行并验证描述的用户操作流程
navigation_flow_validator	验证一系列浏览器操作
console_monitor	在一段时间内捕获浏览器控制台消息
performance_analysis	收集导航和页面性能指标
api_endpoint_tester	测试多个 HTTP 端点
sitemap_crawler	从站点地图发现并检查页面
tunnel_helper	存储或检索远程隧道 URL 和设置指南
debug_memory	在单次服务会话期间保存简短的调试笔记

直接控制 Playwright

playwright_navigate、playwright_click、playwright_iframe_click、playwright_fill、playwright_select、playwright_hover、playwright_evaluate、playwright_console_logs、playwright_get_visible_text、playwright_get_visible_html、playwright_go_back、playwright_go_forward、playwright_press_key、playwright_drag 和 playwright_screenshot。

配置

VUDA 会正常读取环境变量，并自动从其工作目录加载 .env。从源代码检出版本运行时，请复制 .env.example。对于 npx 安装，请将 .env 放在 MCP 进程的工作目录中、在客户端配置中传入变量，或将 DOTENV_CONFIG_PATH 设置为 .env 的绝对路径。

选择浏览器

模式	所需配置	账户状态
本地（默认）	VUDA_BROWSER_PROVIDER=local	VUDA_STORAGE_STATE_PATH、Cookie JSON 或 Cookie 文件
Browserbase	VUDA_BROWSER_PROVIDER=browserbase、BROWSERBASE_API_KEY	重用 BROWSERBASE_CONTEXT_ID 或注入 Cookie
Anchor Browser	VUDA_BROWSER_PROVIDER=anchor、ANCHOR_API_KEY	在 VUDA_ANCHOR_SESSION_JSON 中使用 Anchor 配置文件，或注入 Cookie
现有浏览器	VUDA_BROWSER_PROVIDER=cdp、VUDA_CDP_URL	使用该浏览器上下文；Cookie 注入为可选项

Browserbase 示例：

VUDA_BROWSER_PROVIDER=browserbase
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
BROWSERBASE_CONTEXT_ID=your_saved_context_id

使用持久化认证配置文件的 Anchor Browser 示例：

VUDA_BROWSER_PROVIDER=anchor
ANCHOR_API_KEY=your_api_key
VUDA_ANCHOR_SESSION_JSON={"browser":{"profile":{"name":"vuda","persist":true}}}

所有 29 个工具在每种模式下都保留原有名称和输入。读取 MCP 资源 browser://status，确认所选提供商、当前连接状态、会话 ID，以及是否有可用的实时视图。绝不会返回 CDP 和实时视图 URL。

导入 Cookie 或本地状态

所有提供商都支持注入 Cookie。可内联提供 Playwright Cookie 数组，也可通过文件提供：

VUDA_COOKIES_FILE=/absolute/path/to/cookies.json
# VUDA_COOKIES_JSON=[{"name":"session","value":"...","domain":"example.com","path":"/"}]

对于本地模式，VUDA_STORAGE_STATE_PATH 会加载 Playwright 存储状态文件。设置 VUDA_PERSIST_STORAGE_STATE=true 后，VUDA 正常退出时会将更新后的状态写回。对于需要在多个云端会话之间保留的状态，Browserbase Contexts 和 Anchor 配置文件是提供商原生的选择。

无需额外的包装器或 SDK，即可使用特定于提供商的会话选项：

• VUDA_BROWSERBASE_SESSION_JSON 会合并到 Browserbase 的创建会话请求中。
• VUDA_ANCHOR_SESSION_JSON 会作为 Anchor 的创建会话请求发送。

超时

所有超时设置均为可选：

变量	默认值	用途
VUDA_DEFAULT_TIMEOUT	15000	Playwright 通用超时，单位为毫秒
VUDA_NAVIGATION_TIMEOUT	15000	导航超时
VUDA_SELECTOR_TIMEOUT	12000	选择器等待超时
VUDA_STABILITY_WAIT	5000	导航后、捕获前的延迟
VUDA_UI_UPDATE_WAIT	1000	短暂 UI 更新的延迟
VUDA_PERFORMANCE_THRESHOLD	15000	慢速页面阈值
VUDA_INTERACTION_DELAY	500	直接交互之间的延迟

示例：

{
  "mcpServers": {
    "vuda": {
      "command": "npx",
      "args": ["-y", "visual-ui-debug-agent-mcp"],
      "env": {
        "VUDA_NAVIGATION_TIMEOUT": "30000",
        "VUDA_STABILITY_WAIT": "2000"
      }
    }
  }
}

开发

git clone https://github.com/samihalawa/visual-ui-debug-agent-mcp.git
cd visual-ui-debug-agent-mcp
npm ci
npm test

npm test 会构建 TypeScript 服务，通过 MCP stdio 传输启动该服务，验证准确的 29 个工具清单，读取捆绑资源，执行有状态的工具调用，并捕获真实的浏览器截图。

它还会验证 Browserbase 和 Anchor 的会话请求与清理格式、CDP 选择、Cookie 加载，以及爬虫的浏览器初始化。在 CI 中，提供商调用使用确定性模拟；如需建立实时云端会话，请使用你自己的 .env。

提交拉取请求前，还请运行：

npm audit
npm pack --dry-run

架构

VUDA 在所有提供商之间共用一个 Playwright 控制平面。本地模式会为页面级分析创建隔离上下文；远程模式会复用提供商上下文，让经过身份验证的状态在不同工具之间保留。VUDA 会将截图作为 MCP 图像内容返回，并将生成的截图、浏览器状态和调试提示词作为 MCP 资源公开。

贡献

欢迎提交问题和聚焦明确的拉取请求。开发工作流和审查清单请参阅 CONTRIBUTING.md。发布历史记录在 CHANGELOG.md 中。

许可证

ISC © 2023–2026 Sami Halawa 和贡献者。