关键词

网页可视化分析UI自动化测试Web调试工具Playwright集成AI代理能力

项目简介

这是一个基于 Model Context Protocol (MCP) 构建的服务器应用，专注于为大型语言模型 (LLM) 提供与网页用户界面 (UI) 交互、分析和调试的能力。它通过集成 Playwright 浏览器自动化工具，使得任何支持 MCP 协议的 LLM 客户端都能像人类用户一样“看到”和操作网页。

主要功能点

  • 全面的网页分析: 能够访问指定 URL，捕获页面截图，获取浏览器控制台日志，并智能识别和映射页面上的交互元素（如按钮、链接、输入框），将视觉信息转化为结构化数据。
  • 自动化UI工作流验证: 支持定义一系列用户操作步骤（如导航、点击、填写、验证文本/元素可见性），并自动化执行这些步骤，验证用户流程是否按预期工作。
  • API端点测试: 除了 UI，还能测试应用程序的后端 API，发送 HTTP 请求并验证响应，帮助诊断前后端交互问题。
  • DOM及性能分析: 深入检查页面元素的详细属性、计算样式及层级结构，并收集页面加载时间、资源加载情况等性能指标。
  • 视觉对比: 对比两个 URL 或 UI 状态的截图，突出显示差异，用于进行视觉回归测试。
  • 屏幕截图服务: 提供灵活的截图功能，支持单个 URL、指定元素、批量 URL 截图，甚至本地 HTML 文件的截图。
  • 低级别Playwright控制: 提供了更底层的浏览器控制工具，允许客户端直接执行导航、点击、填写、悬停、JS求值等 Playwright 操作，实现精细化控制。

安装步骤

本项目通常作为后台服务通过 MCP 兼容网关或客户端启动和管理。以下是几种常见的安装和启动方式：

  1. 通过 MCP 网关 (推荐): 如果你使用的 LLM 客户端集成了 MCP 网关功能（例如 Smithery 或 Claude Gateway），通常可以直接通过网关的应用商店或命令行安装：

    # 示例: 使用 claude-gateway
claude-gateway install visual-ui-debug-agent-mcp

    安装后，网关会自动负责启动和管理该服务器进程。

  2. 使用 NPM 全局安装: 你也可以通过 Node.js 的包管理器 npm 进行全局安装：

    npm install -g mcp-ai-vision-debug-ui-automation

    安装完成后，可以通过命令行启动服务器：

    mcp-ai-vision-debug-ui-automation

    （注意：此方式通常需要配合 MCP 客户端手动启动）

  3. 使用 Docker: 如果你使用 Docker 环境，可以拉取官方 Docker 镜像并运行：

    docker pull samihalawa/visual-ui-debug-agent-mcp:latest
docker run -p <端口号>:<容器端口> samihalawa/visual-ui-debug-agent-mcp:latest

    （请参考 Docker 文档配置端口映射和环境变量）

注意: 本项目需要 Node.js 环境才能通过 NPM 方式运行。Playwright 依赖会自动安装所需的浏览器二进制文件。

服务器配置

MCP 服务器通常由 MCP 客户端或网关根据配置信息启动。本服务器通过标准输入输出 (Stdio) 协议与客户端通信。客户端启动本服务器时，可以传递以下配置参数（通常通过环境变量或命令行参数）：

  • 'PORT': MCP 服务器监听的端口号（如果使用 HTTP 或 WebSocket 传输，Stdio 传输通常不需要此项）。
  • 'DEBUG': 布尔值，是否开启调试模式。
  • 'HEADLESS': 布尔值，Playwright 是否以无头模式运行浏览器 (默认是无头)。
  • 'MAX_CONCURRENT_SESSIONS': 数字，允许的最大并发浏览器会话数。
  • 'SCREENSHOT_DIR': 字符串，存放截图文件的临时目录路径。

MCP 客户端在启动本服务器时，会根据其内部配置或用户提供的配置，构建启动命令 (command) 和参数 (args)，并将这些配置项作为环境变量或命令行参数传递给服务器进程。MCP客户端负责管理本服务器的生命周期。

基本使用方法

本服务器不是一个独立的应用，它为 MCP 客户端（如支持 MCP 的 LLM 网关或 AI 代理）提供服务。用户通过与 MCP 客户端交互，由客户端自动调用本服务器提供的工具和访问其资源。

例如，当你在一个支持 MCP 的 AI 聊天界面中请求 AI "分析一下这个网页：https://example.com"，客户端会：

  1. 检查其是否已连接到本视觉 UI 调试代理 MCP 服务器。
  2. 查询服务器的能力（例如，通过 'ListTools' 请求）。
  3. 识别你需要的功能对应服务器的哪个工具（例如 'enhanced_page_analyzer' 工具）。
  4. 根据你的请求和工具的输入 schema，构造一个 'CallTool' 请求（包含 URL 参数）。
  5. 通过 Stdio 协议将 'CallTool' 请求发送给本服务器。
  6. 本服务器执行 'enhanced_page_analyzer' 工具（启动浏览器、访问 URL、分析、截图等）。
  7. 本服务器将分析结果（包含文本、截图数据等）封装在 'CallTool' 响应中，通过 Stdio 返回给客户端。
  8. 客户端接收响应，处理其中的数据和图片，并将其呈现给用户或用于指导 AI 的后续行为。

通过 'ListResources' 请求，客户端可以获取服务器当前可用的资源列表（如历史截图、控制台日志），并使用 'ReadResource' 请求获取资源的具体内容。

总之，作为最终用户，你主要与 MCP 客户端交互，本服务器在后台提供强大的网页分析和自动化能力。

信息

分类

开发者工具

访问项目