Verdex MCP 使用说明

Verdex MCP 是一个强大的工具，旨在增强AI编程助手在浏览器自动化和测试生成方面的能力。它基于Model Context Protocol (MCP) 构建，提供结构化的DOM探索、多角色隔离和语义化选择器生成等功能，帮助AI创建更稳定、更易于维护的Playwright测试。

项目简介

传统的AI生成Playwright测试常常依赖脆弱的定位符（如 'nth()' 选择器），这些定位符在页面结构变化时很容易失效。Verdex MCP 通过暴露一系列高效且语义化的浏览器操作工具，引导AI理解页面的深层结构和元素间的关系，从而生成更健壮、更贴近人类意图的Playwright定位策略。它是一个运行在后台的MCP服务器，与您的AI编程助手进行通信，为AI提供可操作的浏览器上下文。

主要功能点

结构化DOM探索（三步工作流）：
- 'get_ancestors'：查找元素的祖先层级，识别稳定的容器（如带有 'data-testid' 或 'id' 的父元素），用于限定选择器范围。
- 'get_siblings'：分析特定祖先层级下兄弟元素间的模式，帮助AI理解如何通过内容区分相似元素（如不同产品卡片间的区别）。
- 'get_descendants'：探索容器内部的DOM结构，发现语义化的标识符（如标题、按钮文本、ARIA角色），用于构建精确的定位符。这三步探索能以远低于原始DOM转储的令牌成本，提供AI所需的丰富上下文。
多角色隔离测试：支持在独立的浏览器上下文（如不同的Chrome隐身模式会话）中模拟不同用户角色（例如管理员和普通用户），并可预加载身份验证状态，极大地简化了多用户场景的端到端测试。
语义化选择器生成：指导AI优先使用 'data-testid'、'getByRole()' 和内容过滤器等语义信息来构建Playwright选择器，而非依赖易碎的DOM位置。
AI优先设计：所有工具和响应都经过优化，以便LLM（大型语言模型）能够高效地理解和利用，提供紧凑、结构化的输出和清晰的工具描述。
核心浏览器操作：包括 'browser_initialize' (启动浏览器)、'browser_navigate' (导航到URL)、'browser_snapshot' (获取页面快照)、'browser_click' (点击元素)、'browser_type' (输入文本)、'browser_inspect' (检查元素详细信息)、'wait_for_browser' (暂停等待) 和 'browser_close' (关闭浏览器) 等基础功能。

安装步骤

Verdex MCP 是一个Node.js项目，推荐使用 'npx' 运行，这样无需在本地进行额外安装即可使用最新版本。

确保您已安装Node.js (版本18或更高) 和 npm。 您可以通过在终端运行 'node -v' 和 'npm -v' 来检查。
通过 'npx' 启动MCP服务器： 在终端中运行以下命令：
```
npx @verdex/mcp@latest
```
这个命令会自动下载并运行最新版本的Verdex MCP。服务器启动后，它将通过标准输入输出（Stdio）与您的MCP客户端进行通信。
（可选）全局安装： 如果您希望将 'verdex-mcp' 作为系统中的一个可执行命令使用，可以将其全局安装：
```
npm install -g @verdex/mcp
```
安装后，您可以直接运行 'verdex-mcp' 来启动服务器。

服务器配置

MCP服务器是为MCP客户端（通常是AI编程助手或IDE插件）提供服务的。您的MCP客户端需要知道如何启动Verdex MCP服务器并与其通信。这通常通过在MCP客户端的设置文件中配置服务器的启动命令和参数来完成，这些设置通常是JSON格式。

以下是一个配置Verdex MCP服务器的JSON示例，您可以将其添加到您的MCP客户端设置中（例如，对于Cline，路径可能是 '~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json'）：

{
  "mcpServers": {
    "verdex-browser-automation": {
      "command": "npx",
      "args": ["@verdex/mcp@latest"],
      "comment": "配置默认的Verdex MCP服务器。建议使用 '@latest' 参数来确保始终运行最新版本，以获得最佳功能和修复。"
    },
    "verdex-multirole-test": {
      "command": "npx",
      "args": [
        "@verdex/mcp@latest",
        "--role", "admin", "/path/to/admin-auth.json", "https://admin.example.com",
        "--role", "user", "/path/to/user-auth.json", "https://app.example.com",
        "--role", "guest", "/path/to/guest-auth.json"
      ],
      "comment": "配置支持多角色的Verdex MCP服务器。每个'--role'参数后跟角色名称、Playwright存储状态文件路径和可选的默认起始URL。认证文件（例如 admin-auth.json）应包含用户的会话状态，如 cookies 和 localStorage。如果未指定默认URL，则该角色启动时不会自动导航到特定页面。"
    }
  }
}

配置说明：

'verdex-browser-automation': 这是您为MCP服务器实例指定的名称，可以根据您的偏好命名。
- '"command": "npx"': 指定启动服务器的命令是 'npx'。
- '"args": ["@verdex/mcp@latest"]': 'npx' 命令的参数，这里是运行 '@verdex/mcp' 的最新版本。
'verdex-multirole-test': 这是另一个支持多角色的MCP服务器实例名称。
- '"command": "npx"': 同样使用 'npx'。
- '"args": [...]': 这里的参数列表包含了 '--role' 标志，用于定义不同的用户角色。
  - 每个 '--role' 后面需要提供：
    1. '角色名称' (例如 '"admin"', '"user"', '"guest"')：在AI调用 'select_role' 工具时使用。
    2. '认证文件路径' (例如 '"/path/to/admin-auth.json"')：这是一个Playwright 'storageState' 格式的JSON文件，包含用户的登录会话信息。您可以使用Playwright的测试设置 ('auth.setup.ts') 来生成这些文件。
    3. '可选的默认起始URL' (例如 '"https://admin.example.com"')：当切换到此角色且该角色尚未导航过任何页面时，浏览器会自动导航到此URL。

基本使用方法

一旦Verdex MCP服务器在您的MCP客户端中配置并启动，您的AI编程助手就可以通过调用其提供的工具来与浏览器进行交互。以下是一个典型的AI辅助Playwright测试生成流程：

用户向AI提出测试需求： “帮我写一个Playwright测试，将商品‘iPhone 15 Pro’添加到购物车。”
AI调用Verdex MCP工具进行页面探索和操作：
- 启动浏览器并导航： AI调用 'browser_initialize()' 启动浏览器，然后 'browser_navigate("https://shop.example.com")' 访问目标页面。
- 获取页面快照： AI调用 'browser_snapshot()' 获取页面可访问性树的文本快照，识别出页面上的交互元素及其 'ref' (例如，一个“添加到购物车”按钮的 'ref="e3"')。
- 结构化DOM探索（理解元素上下文）：
  - AI调用 'get_ancestors(ref="e3")'：发现 'e3' 所在的容器层级，找到一个稳定的产品卡片容器（例如带有 'data-testid="product-card"' 的 'div' 元素）。
  - AI调用 'get_siblings(ref="e3", ancestorLevel=1)'：分析在产品卡片层级上的兄弟元素，理解如何区分不同的产品（例如通过它们的标题文本）。
  - AI调用 'get_descendants(ref="e3", ancestorLevel=1)'：深入探索产品卡片内部结构，发现“iPhone 15 Pro”标题和真正的“Add to Cart”按钮。
- 生成Playwright代码： 根据探索到的语义信息，AI生成稳定且可读的Playwright选择器和操作：
```
await page
  .locator('section > div')
  .filter({ hasText: "iPhone 15 Pro" })
  .getByRole("button", { name: "Add to Cart" })
  .click();
```
- 多角色测试示例： 如果需要测试不同用户权限下的流程，AI可以调用 'select_role("admin")' 切换到管理员会话，执行管理员操作（如创建促销），然后调用 'select_role("user")' 切换到普通用户会话，验证促销效果。

通过这种方式，Verdex MCP显著提升了AI生成浏览器自动化测试的准确性、稳定性和可维护性。

关键词