Fast Playwright MCP

Fast Playwright MCP

该 MCP 服务器是 Microsoft 官方 Playwright MCP 的一个分支。 https://github.com/microsoft/playwright-mcp

一个使用 Playwright 提供浏览器自动化能力的 Model Context Protocol (MCP) 服务器。该服务器让 LLM 通过结构化的可访问性快照与网页交互，无需截图，也不需要针对视觉调优的模型。

主要功能

• 快速且轻量。使用 Playwright 的可访问性树，而不是基于像素的输入。

• 对 LLM 友好。无需视觉模型，完全基于结构化数据运行。

• 确定性工具调用。避免了基于截图方法常见的歧义。

Fast 服务器特性（本分支）

• Token 优化。所有工具都支持 expectation 参数来控制响应内容：

  • includeCode: false - 禁止生成 Playwright 代码，减少 token 消耗

  • includeSnapshot: false - 跳过页面快照以获得最小化响应（减少 70-80% 的 token 消耗）

  • includeConsole: false - 排除控制台消息

  • includeTabs: false - 隐藏标签页信息

• 图像压缩。截图工具支持 imageOptions：

  • format: 'jpeg' - 使用 JPEG 而非 PNG

  • quality: 1-100 - 压缩图像（例如 50 表示 50% 质量）

  • maxWidth: number - 将图像缩放到指定的最大宽度

• 批量执行。使用 browser_batch_execute 执行多个操作：

  • 通过消除冗余响应显著减少 token 消耗

  • 支持按步骤和全局 expectation 配置

  • 通过 continueOnError 和 stopOnFirstError 选项处理错误

• 快照控制。使用 snapshotOptions 限制快照大小：

  • selector: string - 仅捕获特定页面部分（推荐优先于 maxLength）

  • format: "aria" - 用于 LLM 处理的可访问性树格式

• 差异检测。使用 diffOptions 仅跟踪变更：

  • enabled: true - 仅显示与之前状态不同的内容（大幅节省 token）

  • format: "minimal" - 超紧凑的差异输出

  • 非常适合监控导航或交互过程中的状态变化

• 诊断系统。高级调试和元素发现工具：

  • browser_find_elements - 使用多种搜索条件（文本、角色、属性）查找元素

  • browser_diagnose - 全面的页面分析，包含性能指标和故障排查

  • 增强的错误处理，提供备选元素建议

  • 页面结构分析（iframe、模态框、可访问性指标）

  • 性能监控，执行时间低于 300ms

• 增强的选择器系统。统一元素选择，支持多种策略：

  • 选择器数组：所有基于元素的工具现在都支持多个选择器并自动回退

  • 4 种选择器类型：

    • ref：系统根据之前工具结果生成的元素 ID（优先级最高）

    • role：ARIA 角色，可配合可选文本匹配（例如 {role: "button", text: "Submit"}）

    • css：标准 CSS 选择器（例如 {css: "#submit-btn"}）

    • text：文本内容搜索，可配合可选标签过滤（例如 {text: "Click me", tag: "button"}）

  • 智能解析：并行 CSS 解析、顺序角色匹配、自动回退

  • 多匹配处理：当匹配到多个元素时，返回候选列表供 LLM 选择

  • HTML 检查：新增 browser_inspect_html 工具，通过深度控制实现智能内容提取

自适应工具目录

Version 0.2 默认使用包含七个工具的自适应启动目录，在保留所有已注册工具访问权限的同时，减少固定的 MCP 上下文成本。

• browser_tools 搜索、启用、禁用、重置并报告目录状态。

• browser_query 分发经过 schema 校验的只读工具。

• browser_execute 分发经过 schema 校验的操作和破坏性工具。

• 已知的隐藏工具仍可直接被现有集成调用。

• --tool-profile=full 恢复之前的完整静态目录。

• --tool-profile=minimal 仅暴露发现和分发入口。

该代码库在 CI 中强制执行序列化启动预算。运行 bun run benchmark:tools -- --check 可检查当前 profile 的大小。

安全与互操作控制

CLI 和配置文件支持 CDP 请求头和连接超时、HTTP Host 允许列表、输出目录大小限制、响应中的机密脱敏、操作/导航/expectation 超时、自定义 test-id 属性以及 codegen: "none"。可选的离线 MCP 应用仪表盘通过 --caps=apps 启用。

维护文档：

• 架构

• 0.2 迁移指南

• 上游兼容性策略

• 上游兼容性矩阵

• 发布检查清单

环境要求

• Node.js 20 或更高版本

• VS Code、Cursor、Windsurf、Claude Desktop、Goose 或任何其他 MCP 客户端

快速开始

首先，在你的客户端中安装 Playwright MCP 服务器。

标准配置适用于大多数工具：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@tontoko/fast-playwright-mcp@latest"
      ]
    }
  }
}

使用 Claude Code CLI 添加 Playwright MCP 服务器：

claude mcp add fast-playwright npx @tontoko/fast-playwright-mcp@latest

请按照 MCP 安装 指南 操作，并使用上述标准配置。

点击按钮安装：

或手动安装：

转到 Cursor Settings -> MCP -> Add new MCP Server。名称可自行命名，使用 command 类型，命令为 npx @tontoko/fast-playwright-mcp@latest。你也可以点击 Edit 验证配置或添加命令行参数。

请按照 MCP 安装 指南 操作，并使用上述标准配置。

点击按钮安装：

或手动安装：

前往 Advanced Settings -> Extensions -> Add custom extension。自定义名称，使用 STDIO 类型，并将 command 设置为 npx @tontoko/fast-playwright-mcp。点击 "Add Extension"。

点击按钮安装：

或手动安装：

在右侧边栏转到 Program -> Install -> Edit mcp.json。使用上述标准配置。

请按照 MCP 服务器 文档 操作。例如，在 ~/.config/opencode/opencode.json 中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@tontoko/fast-playwright-mcp"
      ],
      "enabled": true
    }
  }
}

在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板 → 连接更多工具 → + 添加新的 MCP → 粘贴上述标准配置。

点击 Save。

点击按钮安装：

或手动安装：

请按照 MCP 安装 指南 操作，使用上述标准配置。你也可以使用 VS Code CLI 安装 Playwright MCP 服务器：

# For VS Code
code --add-mcp '{"name":"fast-playwright","command":"npx","args":["@tontoko/fast-playwright-mcp@latest"]}'

安装后，Playwright MCP 服务器将可在 VS Code 中与你的 GitHub Copilot 代理一起使用。

请按照 Windsurf MCP 文档 操作，使用上述标准配置。

配置文件

Playwright MCP 服务器可以使用 JSON 文件配置。你可以使用 --config 命令行选项指定配置文件：

npx @tontoko/fast-playwright-mcp@latest --config path/to/config.json

{
  /**
   * Tool catalog profile. Adaptive is the 0.2 default; full restores the
   * pre-0.2 static catalog and minimal exposes only the discovery gateways.
   */
  toolProfile?: 'adaptive' | 'full' | 'minimal';

  browser?: {
    /**
     * The browser to use.
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

    /**
     * Keep the browser profile in memory. By default the profile is written
     * under the operating system's temporary Playwright registry directory.
     */
    isolated?: boolean;

    /**
     * Path to the user data directory. Supplying this overrides the generated
     * persistent profile location.
     */
    userDataDir?: string;

    /**
     * Launch options passed to Playwright.
     */
    launchOptions?: {
      channel?: string;
      executablePath?: string;
      headless?: boolean;
      args?: string[];
    };

    /**
     * Browser context options passed to Playwright.
     */
    contextOptions?: Record<string, unknown>;

    /**
     * Existing Chrome DevTools Protocol endpoint.
     */
    cdpEndpoint?: string;

    /**
     * HTTP headers sent when connecting to the CDP endpoint.
     */
    cdpHeaders?: Record<string, string>;

    /**
     * CDP connection timeout in milliseconds.
     */
    cdpTimeout?: number;

    /**
     * Playwright remote browser endpoint.
     */
    remoteEndpoint?: string;
  };

  server?: {
    host?: string;
    port?: number;
    allowedHosts?: string[];
  };

  capabilities?: Array<'vision' | 'pdf' | 'apps'>;
  outputDir?: string;
  outputMode?: 'file' | 'stdio';
  outputMaxSize?: number;
  secrets?: Record<string, string>;
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  codegen?: 'typescript' | 'none';
}

用户配置

你可以使用持久配置文件运行 Playwright MCP，就像使用普通浏览器一样（默认方式），也可以在隔离的环境中运行用于测试会话，或者使用 浏览器扩展 连接现有的浏览器。

持久化配置

所有已登录的信息都将存储在持久化配置中。如果你希望清除离线状态，可以在会话之间删除配置。 持久化配置将存放在以下目录中，你可以使用 --user-data-dir 参数覆盖默认位置：

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile

隔离配置

在隔离模式下，每个会话都会在隔离的配置文件中启动。每次你要求 MCP 关闭浏览器时，会话都会关闭，且该会话的所有存储状态都将丢失。隔离模式可用于测试目的，确保每个会话彼此独立。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@tontoko/fast-playwright-mcp@latest",
        "--isolated"
      ]
    }
  }
}

浏览器扩展

Playwright MCP 浏览器扩展允许你连接到现有的浏览器标签页，并利用当前浏览器会话和已认证的状态。安装和使用说明，请参阅 extension/README.md。

配置

Playwright MCP 服务器支持以下参数。所有参数都是可选的：

自定义浏览器可执行文件（Firefox 分支和 Chrome/Chromium 分支）

默认情况下，Playwright 启动其自带浏览器。你可以通过指定可执行文件完整路径来使用自定义浏览器可执行文件（例如带有品牌的 Chromium 分支或基于 Firefox 的浏览器）。查看 CUSTOM_BROWSER_EXECUTABLES.md 获取详细的分平台平台说明和注意事项。

• CLI：--browser <chromium|firefox|webkit> 配合 --executable-path <完整路径>

• 配置文件：设置 browser.launchOptions.executablePath

示例：

npx @tontoko/fast-playwright-mcp@latest --browser chromium --executable-path "/opt/google/chrome/chrome"

npx @tontoko/fast-playwright-mcp@latest --browser firefox --executable-path "/opt/waterfox/waterfox"

重要提示：不保证第三方浏览器的兼容性。使用前请验证发布者和二进制文件；服务器会直接执行所提供的路径。Waterfox 仅作为 Firefox 系列浏览器的示例，可能不支持 Playwright 所需的 Firefox 协议补丁。

独立 MCP 服务器

当在无显示器的系统上运行有头浏览器，或从 IDE 的 worker 进程运行时， 请通过环境变量设置 DISPLAY 为有效的 X 服务器来运行 MCP 服务器。例如 DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931。

Docker

注意： 目前 Docker 实现仅支持无头模式的 Chromium。

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

或者，如果您希望将容器作为常驻服务运行，而不是让 MCP 客户端自行启动，可以使用：

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright-mcp \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931

服务器将在端口 8931 上可用，并可通过任何 MCP 客户端访问。

您可以自行构建 Docker 镜像。

docker build -t mcr.microsoft.com/playwright/mcp .

编程式使用

import http from 'node:http';

import { createConnection } from '@tontoko/fast-playwright-mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);
  // ...
});

工具

• browser_batch_execute

  • 标题：批量执行浏览器操作

  • 描述：按顺序批量执行多个已注册的浏览器操作，并返回单个响应。

  • 参数：

    • steps（数组）：按顺序执行的步骤数组。推荐用于表单填写（多次 type→click）、多步骤导航以及任何包含 2 个以上已知步骤的工作流。相比单独调用可节省 90% 的令牌。示例：[{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{selectors:[{css:"#user"}],text:"john"}},{tool:"browser_click",arguments:{selectors:[{css:"#btn"}]}}]

    • stopOnFirstError（布尔值，可选）：在第一个错误发生时停止整个批次

    • globalExpectation（对象，可选）：所有步骤的默认期望状态。推荐：{includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}。可通过 steps[].expectation 进行单步覆盖。

  • 只读：false

• browser_click

  • 标题：在网页上执行点击

  • 描述：在网页上执行点击

  • 参数：

    • selectors（数组）：元素选择器数组（最多 5 个）。选择器按顺序尝试，直到成功（回退机制）。多个匹配将触发错误并列出候选。支持：ref（最高优先级）、CSS（#id、.class、tag）、role（button、textbox 等）、文本内容。示例：[{css: "#submit"}, {role: "button", text: "Submit"}] - 先尝试 ID，再回退到 role+text

    • doubleClick（布尔值，可选）：如果为 true 则执行双击

    • button（字符串，可选）：鼠标按键（默认：left）

    • expectation（对象，可选）：页面状态捕获配置。使用 batch_execute 进行多次点击

  • 只读：false

• browser_close

  • 标题：关闭浏览器

  • 描述：关闭页面

  • 参数：无

  • 只读：false

• browser_console_messages

  • 标题：获取控制台消息

  • 描述：返回所有控制台消息

  • 参数：

    • consoleOptions（对象，可选）：undefined

  • 只读：true

• browser_diagnose

  • 标题：诊断页面

  • 描述：分析页面复杂度、iframe 数量、DOM 大小、模态框状态、元素统计和性能特征。

  • 参数：

    • searchForElements（对象，可选）：搜索特定元素并将其包含在报告中

    • includePerformanceMetrics（布尔值，可选）：在报告中包含性能指标

    • includeAccessibilityInfo（布尔值，可选）：包含可访问性信息

    • includeTroubleshootingSuggestions（布尔值，可选）：包含故障排除建议

    • diagnosticLevel（字符串，可选）：诊断详细程度级别：none（无诊断）、basic（仅关键信息）、standard（默认）、detailed（含指标）、full（含所有信息）

    • useParallelAnalysis（布尔值，可选）：使用第二阶段并行分析以提高性能和资源监控

    • useUnifiedSystem（布尔值，可选）：使用第三阶段统一诊断系统，增强错误处理和监控

    • configOverrides（对象，可选）：诊断系统的运行时配置覆盖

    • includeSystemStats（布尔值，可选）：包含统一系统统计和健康信息

    • expectation（对象，可选）：undefined

  • 只读：true

• browser_drag

  • 标题：拖拽鼠标

  • 描述：在两个元素之间执行拖放操作

  • 参数：

    • startSelectors（数组）：拖拽起始的源元素选择器

    • endSelectors（数组）：拖拽结束的目标元素选择器

    • expectation（对象，可选）：拖拽后的页面状态。使用 batch_execute 进行工作流

  • 只读：false

• browser_evaluate

  • 标题：执行 JavaScript

  • 描述：在页面或元素上执行 JavaScript 表达式并返回结果

  • 参数：

    • function（字符串）：JS 函数：() => {...} 或 (element) => {...}

    • selectors（数组，可选）：可选元素选择器。如果提供，函数将接收元素作为参数

    • expectation（对象，可选）：页面状态配置。false 用于数据提取，true 用于 DOM 更改

  • 只读：false

• browser_file_upload

  • 标题：上传文件

  • 描述：向文件输入框上传一个或多个文件

  • 参数：

    • paths（数组）：要上传的文件的绝对路径（数组）

    • expectation（对象，可选）：页面状态配置。使用 batch_execute 进行 click→upload

  • 只读：false

• browser_find

  • 标题：在页面快照中查找

  • 描述：搜索当前可访问性快照并返回紧凑的匹配上下文。

  • 参数：

    • query（字符串）：undefined

    • regex（布尔值，可选）：undefined

    • caseSensitive（布尔值，可选）：undefined

    • maxResults（整数，可选）：undefined

    • contextLines（整数，可选）：undefined

    • expectation（对象，可选）：undefined

  • 只读：true

• browser_find_elements

  • 标题：查找元素

  • 描述：使用多种搜索条件（如文本、角色、标签名或属性）在页面上查找元素。返回按置信度排序的匹配元素。

  • 参数：

    • searchCriteria（对象）：用于查找元素的搜索条件

    • maxResults（数字，可选）：返回的最大结果数

    • includeDiagnosticInfo（布尔值，可选）：包含有关页面的诊断信息

    • useUnifiedSystem（布尔值，可选）：使用统一诊断系统以增强错误处理

    • enableEnhancedDiscovery（布尔值，可选）：启用增强的元素发现功能，提供上下文相关建议

    • performanceThreshold（数字，可选）：元素发现的性能阈值（毫秒）

    • expectation（对象，可选）：undefined

  • 只读：true

• browser_handle_dialog

  • 标题：处理对话框

  • 描述：处理对话框（alert、confirm、prompt）

  • 参数：

    • accept（布尔值）：接受（true）或拒绝（false）

    • promptText（字符串，可选）：提示对话框的文本

    • expectation（对象，可选）：对话框处理后的页面状态。使用 batch_execute 进行工作流

  • 只读：false

• browser_hover

  • 标题：悬停鼠标

  • 描述：将鼠标悬停在页面元素上

  • 参数：

    • selectors（数组）：元素选择器数组（最多 5 个）。选择器按顺序尝试，直到成功（回退机制）。多个匹配将触发错误并列出候选。支持：ref（最高优先级）、CSS（#id、.class、tag）、role（button、textbox 等）、文本内容。示例：[{css: "#submit"}, {role: "button", text: "Submit"}] - 先尝试 ID，再回退到 role+text

    • expectation（对象，可选）：悬停后的页面状态。使用 batch_execute 进行 hover→click

  • 只读：false

• browser_inspect_html

  • 标题：HTML 检查

  • 描述：提取过滤后的 HTML，支持可配置深度、输出格式、大小限制和自动截断。

  • 参数：

    • selectors（数组）：要检查的元素选择器数组

    • depth（数字，可选）：要提取的最大层级深度

    • includeStyles（布尔值，可选）：包含计算后的 CSS 样式

    • maxSize（数字，可选）：最大大小（字节）（1KB-500KB）

    • format（字符串，可选）：输出格式

    • includeAttributes（布尔值，可选）：包含元素属性

    • preserveWhitespace（布尔值，可选）：保留内容中的空白字符

    • excludeSelector（字符串，可选）：用于排除元素的 CSS 选择器

    • includeSuggestions（布尔值，可选）：在输出中包含 CSS 选择器建议

    • includeChildren（布尔值，可选）：在提取中包含子元素

    • optimizeForLLM（布尔值，可选）：优化提取的 HTML 以供 LLM 使用

    • expectation（对象，可选）：页面状态配置（对于 HTML 检查，使用最小配置）

  • 只读：true

• browser_navigate

  • 标题：导航到 URL

  • 描述：导航到 URL

  • 参数：

    • url（字符串）：要导航到的 URL

    • expectation（对象，可选）：导航后的页面状态

  • 只读：false

• browser_navigate_back

  • 标题：返回上一页

  • 描述：返回上一页

  • 参数：

    • expectation（对象，可选）：返回后的页面状态

  • 只读：false

• browser_navigate_forward

  • 标题：前进到下一页

  • 描述：前进到下一页

  • 参数：

    • expectation（对象，可选）：前进后的页面状态

  • 只读：false

• browser_network_requests

  • 标题：列出网络请求

  • 描述：返回自页面加载以来的网络请求，支持可选过滤

  • 参数：

    • urlPatterns（数组，可选）：要过滤的 URL 模式（支持正则表达式）

    • excludeUrlPatterns（数组，可选）：要排除的 URL 模式（优先于包含模式）

    • statusRanges（数组，可选）：状态码范围（例如，[{min:200,max:299}]）

    • methods（数组，可选）：要过滤的 HTTP 方法

    • maxRequests（数字，可选）：返回的最大请求数（默认：20）

    • newestFirst（布尔值，可选）：按时间戳排序（默认：最新的在前）

  • 只读：true

• browser_press_key

  • 标题：按下按键

  • 描述：在键盘上按下某个键

  • 参数：

    • key（字符串）：要按下的键

    • expectation（对象，可选）：页面状态配置。使用 batch_execute 进行多次按键

  • 只读：false

• browser_resize

  • 标题：调整浏览器窗口大小

  • 描述：调整浏览器窗口大小

  • 参数：

    • width（数字）：浏览器窗口的宽度

    • height（数字）：浏览器窗口的高度

    • expectation（对象，可选）：未定义

  • 只读：false

• browser_select_option

  • 标题：选择选项

  • 描述：在下拉菜单中选择选项

  • 参数：

    • selectors（数组）：元素选择器数组（最多 5 个）。选择器按顺序尝试，直到其中一个成功（回退机制）。多个匹配会触发错误并显示候选列表。支持：ref（最高优先级）、CSS（#id、.class、tag）、role（button、textbox 等）、文本内容。示例：[{css: "#submit"}, {role: "button", text: "Submit"}] - 先尝试 ID，回退到 role+text

    • values（数组）：要选择的值（数组）

    • expectation（对象，可选）：选择后的页面状态。对于表单请使用 batch_execute

  • 只读：false

• browser_snapshot

  • 标题：页面快照

  • 描述：捕获当前页面的无障碍快照

  • 参数：

    • expectation（对象，可选）：页面状态配置

  • 只读：true

• browser_take_screenshot

  • 标题：截取屏幕截图

  • 描述：截取当前页面的屏幕截图并返回图像数据

  • 参数：

    • type（字符串，可选）：图像格式。省略时，根据文件名推断或默认为 png。

    • filename（字符串，可选）：保存截图的文件名。如果未指定，默认为 page-{timestamp}.{png|jpeg|webp}。

    • selectors（数组，可选）：用于元素截图的元素选择器。如果未提供，将截取视口截图。

    • scale（字符串，可选）：使用 CSS 像素或设备像素进行截图。

    • fullPage（布尔值，可选）：为 true 时，截取整个可滚动页面的截图，而不是当前可见的视口。不能与元素截图一起使用。

    • expectation（对象，可选）：额外的页面状态配置

  • 只读：false

• browser_type

  • 标题：输入文本

  • 描述：在可编辑元素中输入文本

  • 参数：

    • selectors（数组）：元素选择器数组（最多 5 个），支持 ref、role、CSS 或基于文本的选择

    • text（字符串）：要输入到元素中的文本

    • submit（布尔，可选）：如果为 true，则在输入后按 Enter

    • slowly（布尔，可选）：如果为 true，则缓慢输入以支持自动补全

    • expectation（对象，可选）：页面状态配置。对于表单使用 batch_execute

  • 只读：false

• browser_wait_for

  • 标题：等待

  • 描述：等待文本出现或消失，或等待指定时间过去

  • 参数：

    • time（数字，可选）：等待时间（秒）

    • text（字符串，可选）：未定义

    • textGone（字符串，可选）：未定义

    • expectation（对象，可选）：等待后的页面状态

  • 只读：true

• browser_tab_close

  • 标题：关闭标签页

  • 描述：按索引关闭标签页或关闭当前标签页

  • 参数：

    • index（数字，可选）：要关闭的标签页索引（省略则关闭当前标签页）

    • expectation（对象，可选）：关闭后的页面状态

  • 只读：false

• browser_tab_list

  • 标题：列出标签页

  • 描述：列出带有标题和 URL 的浏览器标签页

  • 参数：

    • expectation（对象，可选）：页面状态配置

  • 只读：true

• browser_tab_new

  • 标题：打开新标签页

  • 描述：打开一个新标签页

  • 参数：

    • url（字符串，可选）：新标签页的 URL（可选）

    • expectation（对象，可选）：新标签页的页面状态

  • 只读：false

• browser_tab_select

  • 标题：选择标签页

  • 描述：按索引选择标签页

  • 参数：

    • index（数字）：要选择的标签页索引

    • expectation（对象，可选）：切换标签页后的页面状态

  • 只读：false

• browser_install

  • 标题：安装配置中指定的浏览器

  • 描述：安装配置中指定的浏览器。如果遇到浏览器未安装的错误，请调用此工具。

  • 参数：无

  • 只读：false

• browser_mouse_click_xy

  • 标题：点击

  • 描述：在特定坐标处点击

  • 参数：

    • element（字符串）：未定义

    • x（数字）：X 坐标（需要 --caps=vision）

    • y（数字）：Y 坐标（需要 --caps=vision）

    • expectation（对象，可选）：点击后的页面状态。优先使用元素 ref 而不是坐标

  • 只读：false

• browser_mouse_drag_xy

  • 标题：拖拽鼠标

  • 描述：从一个坐标拖拽到另一个坐标

  • 参数：

    • element（字符串）：未定义

    • startX（数字）：起始 X（需要 --caps=vision）

    • startY（数字）：起始 Y（需要 --caps=vision）

    • endX（数字）：结束 X

    • endY（数字）：结束 Y

    • expectation（对象，可选）：拖拽后的页面状态。优先使用元素 ref 而不是坐标

  • 只读：false

• browser_mouse_move_xy

  • 标题：移动鼠标

  • 描述：将鼠标移动到坐标位置。需要视觉能力；尽可能优先使用基于元素的交互。

  • 参数：

    • element（字符串）：未定义

    • x（数字）：X 坐标

    • y（数字）：Y 坐标

    • expectation（对象，可选）：未定义

  • 只读：false

• browser_pdf_save

  • 标题：另存为 PDF

  • 描述：将页面另存为 PDF

  • 参数：

    • filename（字符串，可选）：保存 PDF 的文件名。如果未指定，默认为 page-{timestamp}.pdf。

  • 只读：false

• browser_dashboard

  • 标题：打开浏览器仪表板

  • 描述：打开捆绑的浏览器预览和标签页选择仪表板。

  • 参数：无

  • 只读：true

令牌优化示例

Fast Server 通过期望控制和批量执行提供高级令牌优化：

基本期望控制

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "expectation": {
      "includeSnapshot": false,
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

期望选项

• includeSnapshot（布尔，默认：因工具而异）：包含页面无障碍快照

• includeConsole（布尔，默认：因工具而异）：包含浏览器控制台消息

• includeDownloads（布尔，默认：true）：包含下载信息

• includeTabs（布尔，默认：因工具而异）：包含标签页信息

• includeCode（布尔，默认：true）：在响应中包含已执行的代码

高级快照选项

{
  "name": "browser_click",
  "arguments": {
    "element": "Login button",
    "ref": "#login-btn",
    "expectation": {
      "includeSnapshot": true,
      "snapshotOptions": {
        "selector": ".dashboard",
        "maxLength": 1000,
        "format": "text"
      }
    }
  }
}

控制台过滤选项

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "expectation": {
      "includeConsole": true,
      "consoleOptions": {
        "levels": ["error", "warn"],
        "maxMessages": 5,
        "patterns": ["^Error:"],
        "removeDuplicates": true
      }
    }
  }
}

批量执行

在单个请求中执行多个浏览器操作，并优化响应处理和灵活的错误控制。

基本批量执行

{
  "name": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com/login" }
      },
      {
        "tool": "browser_type",
        "arguments": { 
          "element": "username field", 
          "ref": "#username", 
          "text": "testuser" 
        }
      },
      {
        "tool": "browser_type",
        "arguments": { 
          "element": "password field", 
          "ref": "#password", 
          "text": "password" 
        }
      },
      {
        "tool": "browser_click",
        "arguments": { "element": "login button", "ref": "#login-btn" }
      }
    ]
  }
}

高级批量配置

{
  "name": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com" },
        "expectation": { "includeSnapshot": false },
        "continueOnError": true
      },
      {
        "tool": "browser_click",
        "arguments": { "element": "button", "ref": "#submit" },
        "expectation": { 
          "includeSnapshot": true,
          "snapshotOptions": { "selector": ".result-area" }
        }
      }
    ],
    "stopOnFirstError": false,
    "globalExpectation": {
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

错误处理选项

• continueOnError（每个步骤）：即使此步骤失败也继续批量执行

• stopOnFirstError（全局）：在第一个错误时停止整个批量执行

• 灵活组合可实现稳健的自动化工作流

工具特定默认值

每个工具根据典型使用模式具有优化的默认值：

• 导航工具（browser_navigate）：包含完整上下文以进行验证

• 交互工具（browser_click、browser_type）：包含快照但最小化日志记录

• 截图/快照工具：排除额外上下文

• 代码评估：包含控制台输出但最小化其他信息

• 等待操作：最小化输出以提高效率

性能优势

• 令牌减少：通过优化期望，令牌使用量减少 50-80%

• 更快执行：批量执行速度提升 2-5 倍

• 降低延迟：客户端和服务器之间的往返次数更少

• 成本优化：由于令牌消耗减少，API 成本更低

响应差异检测

Fast Server 包含自动差异检测，以高效跟踪连续工具执行之间的变化：

{
  "name": "browser_click",
  "arguments": {
    "element": "Load more button",
    "ref": "#load-more",
    "expectation": {
      "includeSnapshot": true,
      "diffOptions": {
        "enabled": true,
        "threshold": 0.1,
        "format": "unified",
        "maxDiffLines": 50,
        "context": 3
      }
    }
  }
}

差异检测优势

• 最小化令牌使用：仅显示变化的内容，而不是完整快照

• 变化跟踪：自动检测操作后发生了什么变化

• 灵活格式：选择统一、拆分或最小化差异格式

• 智能缓存：与同一工具的上一次响应进行比较

何时使用差异检测

1. 不涉及导航的 UI 交互：点击、输入、悬停效果

2. 动态内容更新：加载更多项目、实时更新

3. 表单交互：跟踪用户填写表单时的变化

4. 选择性监控：使用 CSS 选择器跟踪特定区域

{
  "name": "browser_type",
  "arguments": {
    "element": "Search input",
    "ref": "#search",
    "text": "playwright",
    "expectation": {
      "includeSnapshot": true,
      "snapshotOptions": {
        "selector": "#search-results"
      },
      "diffOptions": {
        "enabled": true,
        "format": "minimal"
      }
    }
  }
}

最佳实践

1. 对多步骤工作流使用批量执行

2. 对不涉及页面导航的操作启用差异检测

3. 对不需要验证的中间步骤禁用快照

4. 对大型页面使用 CSS 选择器进行选择性快照

5. 将控制台消息过滤到仅相关级别

6. 结合全局和步骤特定的期望以实现细粒度控制

7. 使用最小化差异格式以获得最大令牌节省

诊断系统示例

当选择器失败时查找替代元素：

{
  "name": "browser_find_elements",
  "arguments": {
    "searchCriteria": {
      "text": "Submit",
      "role": "button"
    },
    "maxResults": 5
  }
}

生成全面的页面诊断：

{
  "name": "browser_diagnose",
  "arguments": {
    "includePerformanceMetrics": true,
    "includeAccessibilityInfo": true,
    "includeTroubleshootingSuggestions": true
  }
}

使用增强错误调试自动化失败： 所有工具自动提供增强的错误消息，包括：

• 替代元素建议

• 页面结构分析

• 上下文感知的故障排除提示

• 性能洞察

网络请求过滤

browser_network_requests 工具提供高级过滤功能，在处理网络日志时可将令牌使用量减少高达 80-95%。

基本使用示例

// Filter API requests only
{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["api/", "/graphql"]
  }
}

// Exclude analytics and tracking
{
  "name": "browser_network_requests", 
  "arguments": {
    "excludeUrlPatterns": ["analytics", "tracking", "ads"]
  }
}

// Success responses only
{
  "name": "browser_network_requests",
  "arguments": {
    "statusRanges": [{ "min": 200, "max": 299 }]
  }
}

// Recent errors only
{
  "name": "browser_network_requests",
  "arguments": {
    "statusRanges": [{ "min": 400, "max": 599 }],
    "maxRequests": 5,
    "newestFirst": true
  }
}

高级过滤

// Complex filtering for API debugging
{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["/api/users", "/api/posts"],
    "excludeUrlPatterns": ["/api/health"],
    "methods": ["GET", "POST"],
    "statusRanges": [
      { "min": 200, "max": 299 },
      { "min": 400, "max": 499 }
    ],
    "maxRequests": 10,
    "newestFirst": true
  }
}

// Monitor only failed requests
{
  "name": "browser_network_requests", 
  "arguments": {
    "statusRanges": [
      { "min": 400, "max": 499 },
      { "min": 500, "max": 599 }
    ],
    "maxRequests": 3
  }
}

正则表达式模式支持

{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["^/api/v[0-9]+/users$"],
    "excludeUrlPatterns": ["\\.(css|js|png)$"]
  }
}

令牌优化优势

• 大幅减少：对于大型应用，令牌减少 80-95%

• 聚焦调试：仅查看相关的网络活动

• 性能监控：跟踪特定端点或错误模式

• 成本节省：由于令牌使用量减少，API 成本更低

何时使用网络过滤

1. API 调试：聚焦特定端点和方法

2. 错误监控：仅跟踪失败的请求

3. 性能分析：监控缓慢或有问题的端点

4. 大型应用：减少压倒性的网络日志

5. 令牌管理：保持在 LLM 上下文限制内

迁移指南

现有代码无需更改即可继续工作。要进行优化：

1. 首先在中间步骤中添加 expectation: { includeSnapshot: false }

2. 对 3 个或更多操作的序列使用批量执行

3. 根据您的具体需求逐步微调期望

4. 当自动化失败或需要调试时使用诊断工具

5. 当客户端依赖完整的静态 tools/list 响应时，在升级前设置 --tool-profile=full