Fast Playwright MCP

Fast Playwright MCP

Этот MCP-сервер является форком сервера Microsoft. https://github.com/microsoft/playwright-mcp

Сервер Model Context Protocol (MCP), предоставляющий возможности автоматизации браузера с помощью Playwright. Этот сервер позволяет LLM взаимодействовать с веб-страницами через структурированные снимки дерева доступности, обходя необходимость в скриншотах или моделях, настроенных на визуальное восприятие.

Ключевые возможности

• Быстрый и легковесный. Использует дерево доступности Playwright, а не ввод на основе пикселей.

• Дружелюбный к LLM. Не требуются модели зрения, работает исключительно на структурированных данных.

• Детерминированное применение инструментов. Избегает неоднозначности, характерной для подходов на основе скриншотов.

Возможности Fast-сервера (этот форк)

• Оптимизация токенов. Все инструменты поддерживают параметр expectation для управления содержимым ответа:

  • includeCode: false — подавить генерацию кода Playwright для уменьшения токенов

  • includeSnapshot: false — пропустить снимок страницы для минимальных ответов (сокращение токенов на 70–80%)

  • includeConsole: false — исключить сообщения консоли

  • includeTabs: false — скрыть информацию о вкладках

• Сжатие изображений. Инструмент скриншотов поддерживает imageOptions:

  • format: 'jpeg' — использовать JPEG вместо PNG

  • quality: 1-100 — сжимать изображения (например, 50 для качества 50%)

  • maxWidth: number — изменять размер изображений до максимальной ширины

• Пакетное выполнение. Используйте browser_batch_execute для нескольких операций:

  • Значительное сокращение токенов за счёт устранения избыточных ответов

  • Пошаговая и глобальная конфигурация ожиданий

  • Обработка ошибок с опциями continueOnError и stopOnFirstError

• Управление снимками. Ограничьте размер снимка с помощью snapshotOptions:

  • selector: string — захватывать только определённые разделы страницы (рекомендуется вместо maxLength)

  • format: "aria" — формат дерева доступности для обработки LLM

• Обнаружение изменений. Отслеживайте только изменения с помощью diffOptions:

  • enabled: true — показывать только то, что изменилось по сравнению с предыдущим состоянием (огромная экономия токенов)

  • format: "minimal" — сверхкомпактный вывод изменений

  • Идеально для мониторинга изменений состояния во время навигации или взаимодействий

• Диагностическая система. Расширенные инструменты отладки и обнаружения элементов:

  • browser_find_elements — поиск элементов по нескольким критериям (текст, роль, атрибуты)

  • browser_diagnose — комплексный анализ страницы с метриками производительности и устранением неполадок

  • Улучшенная обработка ошибок с предложениями альтернативных элементов

  • Анализ структуры страницы (iframe, модальные окна, метрики доступности)

  • Мониторинг производительности со временем выполнения менее 300 мс

• Улучшенная система селекторов. Единый выбор элементов с несколькими стратегиями:

  • Массивы селекторов: все инструменты на основе элементов теперь поддерживают несколько селекторов с автоматическим резервным вариантом

  • 4 типа селекторов:

    • ref: сгенерированные системой идентификаторы элементов из предыдущих результатов инструментов (наивысший приоритет)

    • role: роли ARIA с необязательным сопоставлением текста (например, {role: "button", text: "Submit"})

    • css: стандартные CSS-селекторы (например, {css: "#submit-btn"})

    • text: поиск по текстовому содержимому с необязательной фильтрацией по тегу (например, {text: "Click me", tag: "button"})

  • Интеллектуальное разрешение: параллельное разрешение CSS, последовательное сопоставление ролей, автоматический резервный выбор

  • Обработка нескольких совпадений: при совпадении нескольких элементов возвращается список кандидатов для выбора LLM

  • HTML-инспекция: новый инструмент browser_inspect_html для интеллектуального извлечения содержимого с контролем глубины

Адаптивный каталог инструментов

Версия 0.2 по умолчанию использует адаптивный каталог из семи инструментов при запуске, снижая фиксированную стоимость контекста MCP и сохраняя доступ ко всем зарегистрированным инструментам.

• browser_tools ищет, включает, отключает, сбрасывает и сообщает состояние каталога.

• browser_query отправляет проверенные по схеме инструменты только для чтения.

• browser_execute отправляет проверенные по схеме инструменты действий и деструктивные инструменты.

• Известные скрытые инструменты остаются напрямую вызываемыми для существующих интеграций.

• --tool-profile=full восстанавливает предыдущий полный статический каталог.

• --tool-profile=minimal открывает только шлюзы обнаружения и отправки.

Репозиторий обеспечивает сериализованный бюджет запуска в CI. Запустите bun run benchmark:tools -- --check, чтобы проверить текущие размеры профилей.

Контроль безопасности и совместимости

CLI и файл конфигурации поддерживают заголовки CDP и тайм-аут подключения, разрешение HTTP Host, ограничения размера выходного каталога, редактирование секретов в ответах, тайм-ауты действий/навигации/ожиданий, пользовательский атрибут test-id и codegen: "none". Необязательная офлайн-панель MCP Apps включается с помощью --caps=apps.

Документация по сопровождению:

• Архитектура

• Руководство по миграции 0.2

• Политика совместимости с upstream

• Матрица совместимости с upstream

• Контрольный список релиза

Требования

• Node.js 20 или новее

• VS Code, Cursor, Windsurf, Claude Desktop, Goose или любой другой MCP-клиент

Начало работы

Сначала установите Playwright MCP-сервер в вашем клиенте.

Стандартная конфигурация работает в большинстве инструментов:

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

Используйте CLI Claude Code, чтобы добавить 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
    }
  }
}

Откройте панель чата Qodo Gen в VSCode или IntelliJ → Connect more tools → + Add new MCP → Вставьте стандартную конфигурацию выше.

Нажмите Save.

Нажмите кнопку для установки:

Или установите вручную:

Следуйте руководству по установке MCP, используйте стандартную конфигурацию выше. Вы также можете установить Playwright MCP-сервер с помощью CLI VS Code:

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

После установки Playwright MCP-сервер будет доступен для использования с вашим агентом GitHub Copilot в VS Code.

Следуйте документации по MCP в Windsurf. Используйте стандартную конфигурацию выше.

Файл конфигурации

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-сервер поддерживает следующие аргументы. Все они необязательны:

> npx @tontoko/fast-playwright-mcp@latest --help
  --allowed-hosts <hosts>          comma-separated list of allowed HTTP Host
                                   header values
  --allowed-origins <origins>      semicolon-separated list of origins to allow
                                   the browser to request. Default is to allow
                                   all.
  --blocked-origins <origins>      semicolon-separated list of origins to block
                                   the browser from requesting. Blocklist is
                                   evaluated before allowlist.
  --block-service-workers          block service workers
  --browser <browser>              browser or chrome channel to use: chrome,
                                   firefox, webkit, or msedge
  --caps <caps>                    comma-separated optional capabilities:
                                   vision, pdf, apps
  --cdp-endpoint <endpoint>        CDP endpoint to connect to
  --cdp-header <header...>         CDP request header in Name: Value form; may
                                   be repeated
  --cdp-timeout <timeout>          CDP connection timeout in milliseconds
  --codegen <mode>                 generated code mode: typescript or none
  --config <path>                  path to the configuration file
  --device <device>                device to emulate, for example: "iPhone 15"
  --executable-path <path>         path to the browser executable
  --headless                       run browser in headless mode, headed by
                                   default
  --host <host>                    host to bind server to. Default is localhost.
                                   Use 0.0.0.0 to bind all interfaces.
  --ignore-https-errors            ignore HTTPS errors
  --isolated                       use an in-memory isolated browser profile
  --image-responses <mode>         whether image responses are allow or omit
  --no-sandbox                     disable the Chromium sandbox for process
                                   types that normally use it
  --output-dir <path>              directory for output files
  --output-max-size <bytes>        maximum output directory size in bytes; zero
                                   disables eviction
  --port <port>                    port to listen on for HTTP transport
  --proxy-bypass <bypass>          comma-separated domains to bypass the proxy
  --proxy-server <proxy>           proxy server URL
  --save-session                   save the Playwright MCP session
  --save-trace                     save the Playwright trace
  --secrets <path>                 dotenv file containing values to redact
  --storage-state <path>           path to storage state for isolated sessions
  --test-id-attribute <attribute>  attribute used by test-id selectors
  --timeout-action <timeout>       default action timeout in milliseconds
  --timeout-expect <timeout>       default expectation timeout in milliseconds
  --timeout-navigation <timeout>   default navigation timeout in milliseconds
  --timeout-settle <timeout>       delay after browser actions before capturing
                                   the response, in milliseconds
  --tool-profile <profile>         tool catalog profile: adaptive, full, or
                                   minimal
  --user-agent <ua string>         browser user-agent string
  --user-data-dir <path>           browser user data directory
  --viewport-size <size>           viewport size as width,height, for example
                                   1280,720

Пользовательские исполняемые файлы браузера (форки Firefox и Chrome/Chromium)

По умолчанию Playwright запускает свои встроенные браузеры. Вы можете использовать пользовательский исполняемый файл браузера (например, брендированный форк Chromium или браузер на основе Firefox), указав полный путь к исполняемому файлу. См. CUSTOM_BROWSER_EXECUTABLES.md для подробных инструкций и предупреждений для конкретных платформ.

• CLI: --browser <chromium|firefox|webkit> with --executable-path <full path>

• Config file: set 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 запускайте MCP-сервер в окружении с переменной DISPLAY, указывающей на действующий X-сервер. Например: DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931.

Docker

ПРИМЕЧАНИЕ: Текущая реализация Docker поддерживает только headless-режим 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 (array): Массив шагов для последовательного выполнения. Рекомендуется для заполнения форм (несколько 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 (boolean, необязательно): Остановить весь пакет при первой ошибке

    • globalExpectation (необязательно): Ожидание по умолчанию для всех шагов. Рекомендуется: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. Переопределение на уровне шага через steps[].expectation

  • Только чтение: false

• browser_click

  • Заголовок: Выполнить клик на веб-странице

  • Описание: Выполнить клик на веб-странице

  • Параметры:

    • selectors (array): Массив селекторов элементов (макс. 5). Селекторы перебираются по порядку, пока один не сработает (механизм резервирования). Несколько совпадений вызывают ошибку со списком кандидатов. Поддерживает: ref (наивысший приоритет), CSS (#id, .class, tag), роль (button, textbox и т. д.), текстовое содержимое. Пример: [{css: "#submit"}, {role: "button", text: "Submit"}] — сначала пробует ID, затем резервный вариант role+text

    • doubleClick (boolean, необязательно): Двойной клик, если true

    • button (string, необязательно): Кнопка мыши (по умолчанию: левая)

    • expectation (object, необязательно): Конфигурация захвата состояния страницы. Используйте batch_execute для нескольких кликов

  • Только чтение: false

• browser_close

  • Заголовок: Закрыть браузер

  • Описание: Закрыть страницу

  • Параметры: нет

  • Только чтение: false

• browser_console_messages

  • Заголовок: Получить сообщения консоли

  • Описание: Возвращает все сообщения консоли

  • Параметры:

    • consoleOptions (object, необязательно): undefined

  • Только чтение: true

• browser_diagnose

  • Заголовок: Диагностика страницы

  • Описание: Анализ сложности страницы, количества iframe, размера DOM, состояния модальных окон, статистики элементов и характеристик производительности.

  • Параметры:

    • searchForElements (object, необязательно): Поиск конкретных элементов и включение их в отчёт

    • includePerformanceMetrics (boolean, необязательно): Включить метрики производительности в отчёт

    • includeAccessibilityInfo (boolean, необязательно): Включить информацию о доступности

    • includeTroubleshootingSuggestions (boolean, необязательно): Включить предложения по устранению неполадок

    • diagnosticLevel (string, необязательно): Уровень детализации диагностики: none (без диагностики), basic (только критические), standard (по умолчанию), detailed (с метриками), full (вся информация)

    • useParallelAnalysis (boolean, необязательно): Использовать параллельный анализ Phase 2 для улучшения производительности и мониторинга ресурсов

    • useUnifiedSystem (boolean, необязательно): Использовать единую диагностическую систему Phase 3 с улучшенной обработкой ошибок и мониторингом

    • configOverrides (object, необязательно): Переопределения конфигурации во время выполнения для диагностической системы

    • includeSystemStats (boolean, необязательно): Включить статистику единой системы и информацию о состоянии

    • expectation (object, необязательно): undefined

  • Только чтение: true

• browser_drag

  • Заголовок: Перетаскивание мышью

  • Описание: Выполнить перетаскивание между двумя элементами

  • Параметры:

    • startSelectors (array): Селекторы исходного элемента для начала перетаскивания

    • endSelectors (array): Селекторы целевого элемента для окончания перетаскивания

    • expectation (object, необязательно): Состояние страницы после перетаскивания. Используйте batch_execute для рабочих процессов

  • Только чтение: false

• browser_evaluate

  • Заголовок: Выполнить JavaScript

  • Описание: Выполнить JavaScript-выражение на странице или элементе и вернуть результат

  • Параметры:

    • function (string): JS-функция: () => {...} или (element) => {...}

    • selectors (array, необязательно): Необязательные селекторы элементов. Если указаны, функция получает элемент в качестве параметра

    • expectation (object, необязательно): Конфигурация состояния страницы. false для извлечения данных, true для изменений DOM

  • Только чтение: false

• browser_file_upload

  • Заголовок: Загрузить файлы

  • Описание: Загрузить один или несколько файлов в поле ввода файла

  • Параметры:

    • paths (array): Абсолютные пути для загрузки (массив)

    • expectation (object, необязательно): Конфигурация состояния страницы. Используйте batch_execute для click→upload

  • Только чтение: false

• browser_find

  • Заголовок: Поиск в снимке страницы

  • Описание: Поиск по текущему снимку доступности и возврат компактного контекста совпадений.

  • Параметры:

    • query (string): undefined

    • regex (boolean, необязательно): undefined

    • caseSensitive (boolean, необязательно): undefined

    • maxResults (integer, необязательно): undefined

    • contextLines (integer, необязательно): undefined

    • expectation (object, необязательно): undefined

  • Только чтение: true

• browser_find_elements

  • Заголовок: Поиск элементов

  • Описание: Поиск элементов на странице по нескольким критериям, таким как текст, роль, имя тега или атрибуты. Возвращает совпадающие элементы, отсортированные по уверенности.

  • Параметры:

    • searchCriteria (object): Критерии поиска элементов

    • maxResults (number, необязательно): Максимальное количество возвращаемых результатов

    • includeDiagnosticInfo (boolean, необязательно): Включить диагностическую информацию о странице

    • useUnifiedSystem (boolean, необязательно): Использовать единую диагностическую систему для улучшенной обработки ошибок

    • enableEnhancedDiscovery (boolean, необязательно): Включить расширенное обнаружение элементов с контекстными подсказками

    • performanceThreshold (number, необязательно): Порог производительности в миллисекундах для обнаружения элементов

    • expectation (object, необязательно): undefined

  • Только чтение: true

• browser_handle_dialog

  • Заголовок: Обработка диалогового окна

  • Описание: Обработать диалоговое окно (alert, confirm, prompt)

  • Параметры:

    • accept (boolean): Принять (true) или отклонить (false)

    • promptText (string, необязательно): Текст для диалоговых окон prompt

    • expectation (object, необязательно): Состояние страницы после диалога. Используйте batch_execute для рабочих процессов

  • Только чтение: false

• browser_hover

  • Заголовок: Наведение мыши

  • Описание: Навести указатель на элемент страницы

  • Параметры:

    • selectors (array): Массив селекторов элементов (макс. 5). Селекторы перебираются по порядку, пока один не сработает (механизм резервирования). Несколько совпадений вызывают ошибку со списком кандидатов. Поддерживает: ref (наивысший приоритет), CSS (#id, .class, tag), роль (button, textbox и т. д.), текстовое содержимое. Пример: [{css: "#submit"}, {role: "button", text: "Submit"}] — сначала пробует ID, затем резервный вариант role+text

    • expectation (object, необязательно): Состояние страницы после наведения. Используйте batch_execute для hover→click

  • Только чтение: false

• browser_inspect_html

  • Заголовок: Инспекция HTML

  • Описание: Извлечение отфильтрованного HTML с настраиваемой глубиной, форматом вывода, ограничениями размера и автоматическим усечением.

  • Параметры:

    • selectors (array): Массив селекторов элементов для инспекции

    • depth (number, необязательно): Максимальная глубина иерархии для извлечения

    • includeStyles (boolean, необязательно): Включить вычисленные CSS-стили

    • maxSize (number, необязательно): Максимальный размер в байтах (1KB–500KB)

    • format (string, необязательно): Формат вывода

    • includeAttributes (boolean, необязательно): Включить атрибуты элементов

    • preserveWhitespace (boolean, необязательно): Сохранять пробельные символы в содержимом

    • excludeSelector (string, необязательно): CSS-селектор для исключения элементов

    • includeSuggestions (boolean, необязательно): Включить предложения CSS-селекторов в вывод

    • includeChildren (boolean, необязательно): Включить дочерние элементы в извлечение

    • optimizeForLLM (boolean, необязательно): Оптимизировать извлечённый HTML для потребления LLM

    • expectation (object, необязательно): Конфигурация состояния страницы (минимальная для инспекции HTML)

  • Только чтение: true

• browser_navigate

  • Заголовок: Перейти по URL

  • Описание: Перейти по URL

  • Параметры:

    • url (string): URL для перехода

    • expectation (object, необязательно): Состояние страницы после перехода

  • Только чтение: false

• browser_navigate_back

  • Заголовок: Вернуться на предыдущую страницу

  • Описание: Вернуться на предыдущую страницу

  • Параметры:

    • expectation (object, необязательно): Состояние страницы после возврата

  • Только чтение: false

• browser_navigate_forward

  • Заголовок: Перейти на следующую страницу

  • Описание: Перейти на следующую страницу

  • Параметры:

    • expectation (object, необязательно): Состояние страницы после перехода вперёд

  • Только чтение: false

• browser_network_requests

  • Заголовок: Список сетевых запросов

  • Описание: Возвращает сетевые запросы с момента загрузки страницы с возможностью фильтрации

  • Параметры:

    • urlPatterns (array, необязательно): Шаблоны URL для фильтрации (поддерживает regex)

    • excludeUrlPatterns (array, необязательно): Шаблоны URL для исключения (имеют приоритет)

    • statusRanges (array, необязательно): Диапазоны кодов состояния (например, [{min:200,max:299}])

    • methods (array, необязательно): HTTP-методы для фильтрации

    • maxRequests (number, необязательно): Максимальное количество возвращаемых запросов (по умолчанию: 20)

    • newestFirst (boolean, необязательно): Сортировка по времени (по умолчанию: сначала новые)

  • Только чтение: true

• browser_press_key

  • Заголовок: Нажать клавишу

  • Описание: Нажать клавишу на клавиатуре

  • Параметры:

    • key (string): Нажимаемая клавиша

    • expectation (object, необязательно): Конфигурация состояния страницы. Используйте batch_execute для нескольких клавиш

  • Только чтение: false

• browser_resize

  • Название: Изменить размер окна браузера

  • Описание: Изменить размер окна браузера

  • Параметры:

    • width (number): Ширина окна браузера

    • height (number): Высота окна браузера

    • expectation (object, необязательно): undefined

  • Только чтение: false

• browser_select_option

  • Название: Выбрать вариант

  • Описание: Выбрать вариант в выпадающем списке

  • Параметры:

    • selectors (array): Массив селекторов элементов (максимум 5). Селекторы перебираются по порядку, пока один из них не сработает (механизм запасных вариантов). Несколько совпадений вызывают ошибку со списком кандидатов. Поддерживаются: ref (наивысший приоритет), CSS (#id, .class, tag), role (button, textbox и т.п.), текстовое содержимое. Пример: [{css: "#submit"}, {role: "button", text: "Submit"}] — сначала пробуется ID, затем возвращается к role+text

    • values (array): Значения для выбора (массив)

    • expectation (object, необязательно): Состояние страницы после выбора. Для форм используйте batch_execute

  • Только чтение: false

• browser_snapshot

  • Название: Снимок страницы

  • Описание: Создать снимок доступности текущей страницы

  • Параметры:

    • expectation (object, необязательно): Конфигурация состояния страницы

  • Только чтение: true

• browser_take_screenshot

  • Название: Сделать скриншот

  • Описание: Сделать скриншот текущей страницы и вернуть данные изображения

  • Параметры:

    • type (string, необязательно): Формат изображения. Если не указан, определяется из имени файла или по умолчанию используется png.

    • filename (string, необязательно): Имя файла для сохранения скриншота. По умолчанию используется page-{timestamp}.{png|jpeg|webp}, если не указано.

    • selectors (array, необязательно): Необязательные селекторы элементов для скриншотов отдельных элементов. Если не указаны, будет сделан скриншот области просмотра.

    • scale (string, необязательно): Использовать CSS-пиксели или физические пиксели для скриншота.

    • fullPage (boolean, необязательно): Если true, делается скриншот всей прокручиваемой страницы вместо текущей видимой области просмотра. Нельзя использовать со скриншотами отдельных элементов.

    • expectation (object, необязательно): Дополнительная конфигурация состояния страницы

  • Только чтение: false

• browser_type

  • Название: Ввод текста

  • Описание: Ввести текст в редактируемый элемент

  • Параметры:

    • selectors (array): Массив селекторов элементов (максимум 5), поддерживающих выбор по ref, role, CSS или по тексту

    • text (string): Текст для ввода в элемент

    • submit (boolean, необязательно): Нажать Enter после ввода, если true

    • slowly (boolean, необязательно): Вводить медленно для автодополнения, если true

    • expectation (object, необязательно): Конфигурация состояния страницы. Для форм используйте batch_execute

  • Только чтение: false

• browser_wait_for

  • Название: Ожидание

  • Описание: Ожидать появления или исчезновения текста либо наступления заданного времени

  • Параметры:

    • time (number, необязательно): Время ожидания в секундах

    • text (string, необязательно): undefined

    • textGone (string, необязательно): undefined

    • expectation (object, необязательно): Состояние страницы после ожидания

  • Только чтение: true

• browser_tab_close

  • Название: Закрыть вкладку

  • Описание: Закрыть вкладку по индексу или закрыть текущую вкладку

  • Параметры:

    • index (number, необязательно): Индекс вкладки для закрытия (не указывайте для текущей)

    • expectation (object, необязательно): Состояние страницы после закрытия

  • Только чтение: false

• browser_tab_list

  • Название: Список вкладок

  • Описание: Вывести список вкладок браузера с заголовками и URL

  • Параметры:

    • expectation (object, необязательно): Конфигурация состояния страницы

  • Только чтение: true

• browser_tab_new

  • Название: Открыть новую вкладку

  • Описание: Открыть новую вкладку

  • Параметры:

    • url (string, необязательно): URL новой вкладки (необязательно)

    • expectation (object, необязательно): Состояние страницы новой вкладки

  • Только чтение: false

• browser_tab_select

  • Название: Выбрать вкладку

  • Описание: Выбрать вкладку по индексу

  • Параметры:

    • index (number): Индекс выбираемой вкладки

    • expectation (object, необязательно): Состояние страницы после переключения вкладки

  • Только чтение: false

• browser_install

  • Название: Установить браузер, указанный в конфигурации

  • Описание: Установить браузер, указанный в конфигурации. Вызывайте это, если вы получили ошибку о том, что браузер не установлен.

  • Параметры: нет

  • Только чтение: false

• browser_mouse_click_xy

  • Название: Клик

  • Описание: Клик по указанным координатам

  • Параметры:

    • element (string): undefined

    • x (number): Координата X (требуется --caps=vision)

    • y (number): Координата Y (требуется --caps=vision)

    • expectation (object, необязательно): Состояние страницы после клика. Предпочитайте ref-ссылки на элементы координатам

  • Только чтение: false

• browser_mouse_drag_xy

  • Название: Перетаскивание мыши

  • Описание: Перетащить от одной координаты к другой

  • Параметры:

    • element (string): undefined

    • startX (number): Начальная X (требуется --caps=vision)

    • startY (number): Начальная Y (требуется --caps=vision)

    • endX (number): Конечная X

    • endY (number): Конечная Y

    • expectation (object, необязательно): Состояние страницы после перетаскивания. Предпочитайте ref-элементы координатам

  • Только чтение: false

• browser_mouse_move_xy

  • Название: Переместить мышь

  • Описание: Переместить мышь в указанные координаты. Требуется возможность vision; при возможности предпочитайте взаимодействие через элементы.

  • Параметры:

    • element (string): undefined

    • x (number): Координата X

    • y (number): Координата Y

    • expectation (object, необязательно): undefined

  • Только чтение: false

• browser_pdf_save

  • Название: Сохранить как PDF

  • Описание: Сохранить страницу в PDF

  • Параметры:

    • filename (string, необязательно): Имя файла для сохранения 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 (boolean, по умолчанию: зависит от инструмента): Включать снимок доступности страницы

• includeConsole (boolean, по умолчанию: зависит от инструмента): Включать сообщения консоли браузера

• includeDownloads (boolean, по умолчанию: true): Включать информацию о загрузках

• includeTabs (boolean, по умолчанию: зависит от инструмента): Включать информацию о вкладках

• includeCode (boolean, по умолчанию: 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 включает автоматическое обнаружение различий (diff) для эффективного отслеживания изменений между последовательными выполнениями инструментов:

{
  "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
      }
    }
  }
}

Преимущества обнаружения изменений

• Минимальное использование токенов: отображается только изменившийся контент вместо полных снимков

• Отслеживание изменений: автоматически определяет, что изменилось после действий

• Гибкие форматы: выберите между объединённым, split или минимальным форматом diff

• Умное кэширование: сравнение с предыдущим ответом того же инструмента

Когда использовать обнаружение изменений

1. Взаимодействия с интерфейсом без навигации: клики, ввод текста, эффекты наведения

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. Используйте минимальный формат diff для максимальной экономии токенов

Примеры диагностической системы

Поиск альтернативных элементов при неработающих селекторах:

{
  "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 благодаря уменьшенному использованию токенов

Когда использовать сетевую фильтрацию

• Отладка API: сосредоточьтесь на конкретных конечных точках и методах

• Мониторинг ошибок: отслеживайте только неудачные запросы

• Анализ производительности: наблюдайте за медленными или проблемными конечными точками

• Большие приложения: сократите перегружающие сетевые журналы

• Управление токенами: оставайтесь в пределах контекстного ограничения LLM

Руководство по миграции

Существующий код продолжает работать без изменений. Оптимизация:

1. Начните с добавления expectation: { includeSnapshot: false } к промежуточным шагам

2. Используйте пакетное выполнение для последовательностей из 3+ операций

3. Постепенно уточняйте ожидания в соответствии с вашими конкретными потребностями

4. Используйте диагностические инструменты, когда автоматизация дает сбой или требует отладки

5. Установите --tool-profile=full перед обновлением, если клиент зависит от полного статического ответа tools/list.