Fast Playwright MCP

Fast Playwright MCP

Dieser MCP-Server ist ein Fork des Microsoft-Servers. https://github.com/microsoft/playwright-mcp

Ein Model Context Protocol (MCP)-Server, der Browser-Automatisierungsfunktionen mit Playwright bereitstellt. Dieser Server ermöglicht es LLMs, über strukturierte Accessibility-Snapshots mit Webseiten zu interagieren, ohne dass Screenshots oder visuell abgestimmte Modelle erforderlich sind.

Hauptfunktionen

• Schnell und leichtgewichtig. Verwendet den Accessibility-Baum von Playwright, nicht pixelbasierte Eingaben.

• LLM-freundlich. Keine Vision-Modelle erforderlich, arbeitet rein mit strukturierten Daten.

• Deterministische Tool-Anwendung. Vermeidet die bei Screenshot-basierten Ansätzen übliche Mehrdeutigkeit.

Fast-Server-Funktionen (Dieser Fork)

• Token-Optimierung. Alle Tools unterstützen einen expectation-Parameter zur Steuerung des Antwortinhalts:

  • includeCode: false – Playwright-Codegenerierung unterdrücken, um Tokens zu reduzieren

  • includeSnapshot: false – Seiten-Snapshot für minimale Antworten überspringen (70–80 % Token-Reduzierung)

  • includeConsole: false – Konsolenmeldungen ausschließen

  • includeTabs: false – Tab-Informationen ausblenden

• Bildkomprimierung. Das Screenshot-Tool unterstützt imageOptions:

  • format: 'jpeg' – JPEG statt PNG verwenden

  • quality: 1-100 – Bilder komprimieren (z. B. 50 für 50 % Qualität)

  • maxWidth: number – Bilder auf maximale Breite skalieren

• Batch-Ausführung. Verwenden Sie browser_batch_execute für mehrere Operationen:

  • Erhebliche Token-Reduzierung durch Eliminierung redundanter Antworten

  • Schrittweise und globale Expectation-Konfiguration

  • Fehlerbehandlung mit den Optionen continueOnError und stopOnFirstError

• Snapshot-Kontrolle. Snapshot-Größe mit snapshotOptions begrenzen:

  • selector: string – Nur bestimmte Seitenabschnitte erfassen (empfohlen gegenüber maxLength)

  • format: "aria" – Accessibility-Baumformat für die LLM-Verarbeitung

• Diff-Erkennung. Nur Änderungen mit diffOptions verfolgen:

  • enabled: true – Nur anzeigen, was sich gegenüber dem vorherigen Zustand geändert hat (massive Token-Ersparnis)

  • format: "minimal" – Ultra-kompakte Diff-Ausgabe

  • Ideal zur Überwachung von Zustandsänderungen während Navigation oder Interaktionen

• Diagnosesystem. Erweiterte Debugging- und Elementerkennungswerkzeuge:

  • browser_find_elements – Elemente mit mehreren Suchkriterien finden (Text, Rolle, Attribute)

  • browser_diagnose – Umfassende Seitenanalyse mit Leistungsmetriken und Fehlerbehebung

  • Erweiterte Fehlerbehandlung mit Vorschlägen für alternative Elemente

  • Seitenstrukturanalyse (iframes, Modals, Accessibility-Metriken)

  • Leistungsüberwachung mit Ausführungszeit unter 300 ms

• Erweitertes Selektor-System. Einheitliche Elementauswahl mit mehreren Strategien:

  • Selektor-Arrays: Alle elementbasierten Tools unterstützen jetzt mehrere Selektoren mit automatischem Fallback

  • 4 Selektor-Typen:

    • ref: Systemgenerierte Element-IDs aus früheren Tool-Ergebnissen (höchste Priorität)

    • role: ARIA-Rollen mit optionalem Textabgleich (z. B. {role: "button", text: "Submit"})

    • css: Standard-CSS-Selektoren (z. B. {css: "#submit-btn"})

    • text: Textinhaltsuche mit optionaler Tag-Filterung (z. B. {text: "Click me", tag: "button"})

  • Intelligente Auflösung: Parallele CSS-Auflösung, sequenzieller Rollenabgleich, automatischer Fallback

  • Behandlung mehrfacher Übereinstimmungen: Bei mehreren übereinstimmenden Elementen wird eine Kandidatenliste zur LLM-Auswahl zurückgegeben

  • HTML-Inspektion: Neues browser_inspect_html-Tool zur intelligenten Inhaltsextraktion mit Tiefenkontrolle

Adaptiver Tool-Katalog

Version 0.2 verwendet standardmäßig einen adaptiven Startkatalog mit sieben Tools, der die festen MCP-Kontextkosten reduziert und gleichzeitig den Zugriff auf alle registrierten Tools beibehält.

• browser_tools durchsucht, aktiviert, deaktiviert, setzt zurück und meldet den Katalogstatus.

• browser_query leitet schema-validierte schreibgeschützte Tools weiter.

• browser_execute leitet schema-validierte Aktions- und destruktive Tools weiter.

• Bekannte versteckte Tools bleiben für bestehende Integrationen direkt aufrufbar.

• --tool-profile=full stellt den vorherigen vollständigen statischen Katalog wieder her.

• --tool-profile=minimal legt nur die Discovery- und Dispatch-Gateways offen.

Das Repository erzwingt in CI ein serialisiertes Startbudget. Führen Sie bun run benchmark:tools -- --check aus, um die aktuellen Profilgrößen zu prüfen.

Sicherheits- und Interoperabilitätskontrollen

Die CLI und die Konfigurationsdatei unterstützen CDP-Header und Verbindungs-Timeout, HTTP-Host-Allowlisting, Größenbegrenzungen für das Ausgabeverzeichnis, Schwärzung von Geheimnissen in Antworten, Aktions-/Navigations-/Expectation-Timeouts, ein benutzerdefiniertes test-id-Attribut und codegen: "none". Das optionale Offline-MCP-Apps-Dashboard wird mit --caps=apps aktiviert.

Wartungsdokumentation:

• Architektur

• 0.2-Migrationsleitfaden

• Upstream-Kompatibilitätsrichtlinie

• Upstream-Kompatibilitätsmatrix

• Release-Checkliste

Anforderungen

• Node.js 20 oder neuer

• VS Code, Cursor, Windsurf, Claude Desktop, Goose oder ein anderer MCP-Client

Erste Schritte

Installieren Sie zunächst den Playwright-MCP-Server mit Ihrem Client.

Standardkonfiguration funktioniert in den meisten Tools:

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

Verwenden Sie die Claude-Code-CLI, um den Playwright-MCP-Server hinzuzufügen:

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

Folgen Sie dem MCP-Installations-Leitfaden und verwenden Sie die Standardkonfiguration oben.

Klicken Sie auf die Schaltfläche, um zu installieren:

Oder manuell installieren:

Gehen Sie zu Cursor Settings -> MCP -> Add new MCP Server. Benennen Sie den Server nach Ihren Wünschen, verwenden Sie den Typ command mit dem Befehl npx @tontoko/fast-playwright-mcp@latest. Sie können die Konfiguration auch überprüfen oder Argumente wie Befehle hinzufügen, indem Sie auf Edit klicken.

Folgen Sie dem MCP-Installations-Leitfaden und verwenden Sie die Standardkonfiguration oben.

Klicken Sie auf die Schaltfläche, um zu installieren:

Oder manuell installieren:

Gehen Sie zu Advanced settings -> Extensions -> Add custom extension. Benennen Sie die Erweiterung nach Ihren Wünschen, verwenden Sie den Typ STDIO und setzen Sie den command auf npx @tontoko/fast-playwright-mcp. Klicken Sie auf „Add Extension“.

Klicken Sie auf die Schaltfläche, um zu installieren:

Oder manuell installieren:

Gehen Sie in der rechten Seitenleiste zu Program -> Install -> Edit mcp.json. Verwenden Sie die Standardkonfiguration oben.

Folgen Sie der Dokumentation zu MCP-Servern. Zum Beispiel in ~/.config/opencode/opencode.json:

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

Öffnen Sie das Qodo Gen-Chat-Panel in VSCode oder IntelliJ → Connect more tools → + Add new MCP → Fügen Sie die Standardkonfiguration oben ein.

Klicken Sie auf Save.

Klicken Sie auf die Schaltfläche, um zu installieren:

Oder manuell installieren:

Folgen Sie dem MCP-Installations-Leitfaden und verwenden Sie die Standardkonfiguration oben. Sie können den Playwright-MCP-Server auch über die VS-Code-CLI installieren:

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

Nach der Installation ist der Playwright-MCP-Server für die Verwendung mit Ihrem GitHub-Copilot-Agenten in VS Code verfügbar.

Folgen Sie der Windsurf-MCP-Dokumentation. Verwenden Sie die Standardkonfiguration oben.

Konfigurationsdatei

Der Playwright-MCP-Server kann über eine JSON-Datei konfiguriert werden. Sie können die Konfigurationsdatei mit der Befehlszeilenoption --config angeben:

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';
}

Benutzerprofil

Sie können Playwright MCP mit einem persistenten Profil wie in einem normalen Browser (Standard), in isolierten Kontexten für Testsitzungen ausführen oder über die Browser-Erweiterung eine Verbindung zu einem vorhandenen Browser herstellen.

Persistentes Profil

Alle angemeldeten Informationen werden im persistenten Profil gespeichert. Sie können es zwischen Sitzungen löschen, wenn Sie den Offline-Zustand zurücksetzen möchten. Das persistente Profil befindet sich in den folgenden Verzeichnissen. Sie können es mit dem Argument --user-data-dir überschreiben.

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

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

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

Isoliert

Im isolierten Modus wird jede Sitzung in einem isolierten Profil gestartet. Jedes Mal, wenn Sie MCP bitten, den Browser zu schließen, wird die Sitzung beendet und der gesamte Speicherzustand dieser Sitzung geht verloren. Der isolierte Modus kann zu Testzwecken verwendet werden, um sicherzustellen, dass jede Sitzung unabhängig ist.

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

Browser-Erweiterung

Die Playwright-MCP-Browser-Erweiterung ermöglicht es Ihnen, eine Verbindung zu vorhandenen Browser-Tabs herzustellen und Ihre aktuelle Browsersitzung sowie den authentifizierten Zustand zu nutzen. Installations- und Verwendungshinweise finden Sie in der extension/README.md.

Konfiguration

Der Playwright-MCP-Server unterstützt die folgenden Argumente. Alle sind optional:

> 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

Benutzerdefinierte Browser-Executables (Firefox-Forks und Chrome/Chromium-Forks)

Standardmäßig startet Playwright seine gebündelten Browser. Sie können ein benutzerdefiniertes Browser-Executable (z. B. einen gebrandeten Chromium-Fork oder einen Firefox-basierten Browser) verwenden, indem Sie den vollständigen Pfad zum Executable angeben. Detaillierte, plattformspezifische Anweisungen und Warnhinweise finden Sie in CUSTOM_BROWSER_EXECUTABLES.md.

• CLI: --browser <chromium|firefox|webkit> mit --executable-path <voller Pfad>

• Konfigurationsdatei: browser.launchOptions.executablePath festlegen

Beispiele:

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"

Wichtig: Die Kompatibilität mit Browsern von Drittanbietern ist nicht garantiert. Überprüfen Sie Herausgeber und Binärdatei vor der Verwendung; der Server führt den angegebenen Pfad direkt aus. Waterfox ist nur ein veranschaulichendes Beispiel aus der Firefox-Familie und unterstützt möglicherweise nicht die von Playwright benötigten Firefox-Protokoll-Patches.

Eigenständiger MCP-Server

Wenn Sie einen Browser mit grafischer Oberfläche auf einem System ohne Display oder aus Worker-Prozessen der IDEs ausführen, starten Sie den MCP-Server aus einer Umgebung, in der DISPLAY auf einen gültigen X-Server gesetzt ist. Zum Beispiel DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931.

Docker

HINWEIS: Die Docker-Implementierung unterstützt derzeit nur headless Chromium.

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

Oder wenn Sie den Container lieber als langlebigen Dienst ausführen möchten, anstatt ihn vom MCP-Client starten zu lassen, verwenden Sie:

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

Der Server ist auf Port 8931 verfügbar und kann über jeden MCP-Client erreicht werden.

Sie können das Docker-Image selbst erstellen.

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

Programmgesteuerte Verwendung

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);
  // ...
});

Tools

• browser_batch_execute

  • Titel: Browser-Aktionen stapelweise ausführen

  • Beschreibung: Führt mehrere registrierte Browser-Aktionen nacheinander mit einer Antwort aus.

  • Parameter:

    • steps (array): Array von Schritten, die nacheinander ausgeführt werden. Empfohlen für Formularausfüllung (mehrere type→click), mehrstufige Navigation, jeden Workflow mit 2+ bekannten Schritten. Spart 90 % Tokens im Vergleich zu einzelnen Aufrufen. Beispiel: [{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, optional): Gesamten Stapel beim ersten Fehler stoppen

    • globalExpectation (optional): Standard-Erwartung für alle Schritte. Empfohlen: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. Überschreibung pro Schritt mit steps[].expectation

  • Schreibgeschützt: false

• browser_click

  • Titel: Klick auf Webseite ausführen

  • Beschreibung: Klick auf Webseite ausführen

  • Parameter:

    • selectors (array): Array von Elementselektoren (max. 5). Selektoren werden der Reihe nach versucht, bis einer erfolgreich ist (Fallback-Mechanismus). Mehrfache Übereinstimmungen lösen einen Fehler mit Kandidatenliste aus. Unterstützt: ref (höchste Priorität), CSS (#id, .class, tag), Rolle (button, textbox, usw.), Textinhalt. Beispiel: [{css: "#submit"}, {role: "button", text: "Submit"}] – versucht zuerst die ID, fällt dann auf Rolle+Text zurück

    • doubleClick (boolean, optional): Doppelklick, wenn true

    • button (string, optional): Maustaste (Standard: links)

    • expectation (object, optional): Konfiguration zur Erfassung des Seitenzustands. Verwenden Sie batch_execute für Mehrfachklicks

  • Schreibgeschützt: false

• browser_close

  • Titel: Browser schließen

  • Beschreibung: Seite schließen

  • Parameter: Keine

  • Schreibgeschützt: false

• browser_console_messages

  • Titel: Konsolenmeldungen abrufen

  • Beschreibung: Gibt alle Konsolenmeldungen zurück

  • Parameter:

    • consoleOptions (object, optional): undefined

  • Schreibgeschützt: true

• browser_diagnose

  • Titel: Seite diagnostizieren

  • Beschreibung: Analysiert Seitenkomplexität, iframe-Anzahl, DOM-Größe, Modalzustand, Elementstatistiken und Leistungsmerkmale.

  • Parameter:

    • searchForElements (object, optional): Nach bestimmten Elementen suchen und in den Bericht aufnehmen

    • includePerformanceMetrics (boolean, optional): Leistungsmetriken in den Bericht aufnehmen

    • includeAccessibilityInfo (boolean, optional): Barrierefreiheitsinformationen aufnehmen

    • includeTroubleshootingSuggestions (boolean, optional): Vorschläge zur Fehlerbehebung aufnehmen

    • diagnosticLevel (string, optional): Detaillierungsgrad der Diagnose: none (keine Diagnose), basic (nur kritisch), standard (Standard), detailed (mit Metriken), full (alle Informationen)

    • useParallelAnalysis (boolean, optional): Phase-2-Parallelanalyse für verbesserte Leistung und Ressourcenüberwachung verwenden

    • useUnifiedSystem (boolean, optional): Phase-3-vereinheitlichtes Diagnosesystem mit verbesserter Fehlerbehandlung und Überwachung verwenden

    • configOverrides (object, optional): Laufzeit-Konfigurationsüberschreibungen für das Diagnosesystem

    • includeSystemStats (boolean, optional): Vereinheitlichte Systemstatistiken und Gesundheitsinformationen aufnehmen

    • expectation (object, optional): undefined

  • Schreibgeschützt: true

• browser_drag

  • Titel: Maus ziehen

  • Beschreibung: Drag-and-Drop zwischen zwei Elementen ausführen

  • Parameter:

    • startSelectors (array): Quellelement-Selektoren für den Drag-Start

    • endSelectors (array): Zielelement-Selektoren für das Drag-Ende

    • expectation (object, optional): Seitenzustand nach dem Ziehen. Verwenden Sie batch_execute für Workflows

  • Schreibgeschützt: false

• browser_evaluate

  • Titel: JavaScript auswerten

  • Beschreibung: JavaScript-Ausdruck auf Seite oder Element auswerten und Ergebnis zurückgeben

  • Parameter:

    • function (string): JS-Funktion: () => {...} oder (element) => {...}

    • selectors (array, optional): Optionale Elementselektoren. Wenn angegeben, erhält die Funktion das Element als Parameter

    • expectation (object, optional): Seitenzustandskonfiguration. false für Datenextraktion, true für DOM-Änderungen

  • Schreibgeschützt: false

• browser_file_upload

  • Titel: Dateien hochladen

  • Beschreibung: Eine oder mehrere Dateien in die Dateieingabe hochladen

  • Parameter:

    • paths (array): Absolute Pfade zum Hochladen (Array)

    • expectation (object, optional): Seitenzustandskonfiguration. Verwenden Sie batch_execute für Klick→Upload

  • Schreibgeschützt: false

• browser_find

  • Titel: Im Seiten-Snapshot suchen

  • Beschreibung: Durchsucht den aktuellen Barrierefreiheits-Snapshot und gibt kompakten passenden Kontext zurück.

  • Parameter:

    • query (string): undefined

    • regex (boolean, optional): undefined

    • caseSensitive (boolean, optional): undefined

    • maxResults (integer, optional): undefined

    • contextLines (integer, optional): undefined

    • expectation (object, optional): undefined

  • Schreibgeschützt: true

• browser_find_elements

  • Titel: Elemente finden

  • Beschreibung: Findet Elemente auf der Seite mithilfe mehrerer Suchkriterien wie Text, Rolle, Tag-Name oder Attribute. Gibt passende Elemente nach Konfidenz sortiert zurück.

  • Parameter:

    • searchCriteria (object): Suchkriterien zum Finden von Elementen

    • maxResults (number, optional): Maximale Anzahl der zurückzugebenden Ergebnisse

    • includeDiagnosticInfo (boolean, optional): Diagnoseinformationen über die Seite aufnehmen

    • useUnifiedSystem (boolean, optional): Vereinheitlichtes Diagnosesystem für verbesserte Fehlerbehandlung verwenden

    • enableEnhancedDiscovery (boolean, optional): Erweiterte Elementerkennung mit kontextuellen Vorschlägen aktivieren

    • performanceThreshold (number, optional): Leistungsschwelle in Millisekunden für die Elementerkennung

    • expectation (object, optional): undefined

  • Schreibgeschützt: true

• browser_handle_dialog

  • Titel: Dialog behandeln

  • Beschreibung: Dialog behandeln (alert, confirm, prompt)

  • Parameter:

    • accept (boolean): Akzeptieren (true) oder ablehnen (false)

    • promptText (string, optional): Text für Prompt-Dialoge

    • expectation (object, optional): Seitenzustand nach dem Dialog. Verwenden Sie batch_execute für Workflows

  • Schreibgeschützt: false

• browser_hover

  • Titel: Maus über Element bewegen

  • Beschreibung: Über Element auf der Seite fahren

  • Parameter:

    • selectors (array): Array von Elementselektoren (max. 5). Selektoren werden der Reihe nach versucht, bis einer erfolgreich ist (Fallback-Mechanismus). Mehrfache Übereinstimmungen lösen einen Fehler mit Kandidatenliste aus. Unterstützt: ref (höchste Priorität), CSS (#id, .class, tag), Rolle (button, textbox, usw.), Textinhalt. Beispiel: [{css: "#submit"}, {role: "button", text: "Submit"}] – versucht zuerst die ID, fällt dann auf Rolle+Text zurück

    • expectation (object, optional): Seitenzustand nach dem Hover. Verwenden Sie batch_execute für Hover→Klick

  • Schreibgeschützt: false

• browser_inspect_html

  • Titel: HTML-Inspektion

  • Beschreibung: Extrahiert gefiltertes HTML mit konfigurierbarer Tiefe, Ausgabeformat, Größenbegrenzungen und automatischer Kürzung.

  • Parameter:

    • selectors (array): Array von Elementselektoren zur Inspektion

    • depth (number, optional): Maximale Hierarchietiefe zum Extrahieren

    • includeStyles (boolean, optional): Berechnete CSS-Stile aufnehmen

    • maxSize (number, optional): Maximale Größe in Bytes (1KB-500KB)

    • format (string, optional): Ausgabeformat

    • includeAttributes (boolean, optional): Elementattribute aufnehmen

    • preserveWhitespace (boolean, optional): Leerzeichen im Inhalt beibehalten

    • excludeSelector (string, optional): CSS-Selektor zum Ausschließen von Elementen

    • includeSuggestions (boolean, optional): CSS-Selektor-Vorschläge in die Ausgabe aufnehmen

    • includeChildren (boolean, optional): Untergeordnete Elemente in die Extraktion aufnehmen

    • optimizeForLLM (boolean, optional): Extrahiertes HTML für die LLM-Nutzung optimieren

    • expectation (object, optional): Seitenzustandskonfiguration (minimal für HTML-Inspektion)

  • Schreibgeschützt: true

• browser_navigate

  • Titel: Zu einer URL navigieren

  • Beschreibung: Zu einer URL navigieren

  • Parameter:

    • url (string): Die URL, zu der navigiert werden soll

    • expectation (object, optional): Seitenzustand nach der Navigation

  • Schreibgeschützt: false

• browser_navigate_back

  • Titel: Zur vorherigen Seite zurückgehen

  • Beschreibung: Zur vorherigen Seite zurückgehen

  • Parameter:

    • expectation (object, optional): Seitenzustand nach dem Zurückgehen

  • Schreibgeschützt: false

• browser_navigate_forward

  • Titel: Zur nächsten Seite weitergehen

  • Beschreibung: Zur nächsten Seite weitergehen

  • Parameter:

    • expectation (object, optional): Seitenzustand nach dem Weitergehen

  • Schreibgeschützt: false

• browser_network_requests

  • Titel: Netzwerkanfragen auflisten

  • Beschreibung: Gibt Netzwerkanfragen seit dem Laden der Seite mit optionaler Filterung zurück

  • Parameter:

    • urlPatterns (array, optional): URL-Muster zum Filtern (unterstützt Regex)

    • excludeUrlPatterns (array, optional): URL-Muster zum Ausschließen (hat Vorrang)

    • statusRanges (array, optional): Statuscode-Bereiche (z. B. [{min:200,max:299}])

    • methods (array, optional): HTTP-Methoden zum Filtern

    • maxRequests (number, optional): Maximale Anzahl zurückzugebender Anfragen (Standard: 20)

    • newestFirst (boolean, optional): Nach Zeitstempel sortieren (Standard: neueste zuerst)

  • Schreibgeschützt: true

• browser_press_key

  • Titel: Taste drücken

  • Beschreibung: Eine Taste auf der Tastatur drücken

  • Parameter:

    • key (string): Zu drückende Taste

    • expectation (object, optional): Seitenzustandskonfiguration. Verwenden Sie batch_execute für mehrere Tasten

  • Schreibgeschützt: false

• browser_resize

  • Titel: Browserfenster vergrößern/verkleinern

  • Beschreibung: Browserfenster vergrößern/verkleinern

  • Parameter:

    • width (Zahl): Breite des Browserfensters

    • height (Zahl): Höhe des Browserfensters

    • expectation (Objekt, optional): undefined

  • Schreibgeschützt: false

• browser_select_option

  • Titel: Option auswählen

  • Beschreibung: Option im Dropdown auswählen

  • Parameter:

    • selectors (Array): Array von Elementselektoren (max. 5). Die Selektoren werden der Reihe nach ausprobiert, bis einer erfolgreich ist (Fallback-Mechanismus). Mehrfachtreffer lösen einen Fehler mit einer Kandidatenliste aus. Unterstützt: ref (höchste Priorität), CSS (#id, .class, tag), Rolle (button, textbox usw.), Textinhalt. Beispiel: [{css: "#submit"}, {role: "button", text: "Submit"}] – versucht zuerst die ID, fällt dann auf Rolle+Text zurück

    • values (Array): Auszuwählende Werte (Array)

    • expectation (Objekt, optional): Seitenstatus nach der Auswahl. Für Formulare batch_execute verwenden

  • Schreibgeschützt: false

• browser_snapshot

  • Titel: Seiten-Snapshot

  • Beschreibung: Barrierefreiheits-Snapshot der aktuellen Seite erfassen

  • Parameter:

    • expectation (Objekt, optional): Konfiguration des Seitenstatus

  • Schreibgeschützt: true

• browser_take_screenshot

  • Titel: Screenshot aufnehmen

  • Beschreibung: Screenshot der aktuellen Seite aufnehmen und Bilddaten zurückgeben

  • Parameter:

    • type (Zeichenfolge, optional): Bildformat. Wenn nicht angegeben, wird es aus dem Dateinamen abgeleitet oder standardmäßig png verwendet.

    • filename (Zeichenfolge, optional): Dateiname zum Speichern des Screenshots. Standardmäßig page-{timestamp}.{png|jpeg|webp}, falls nicht angegeben.

    • selectors (Array, optional): Optionale Elementselektoren für Element-Screenshots. Wenn nicht angegeben, wird ein Viewport-Screenshot aufgenommen.

    • scale (Zeichenfolge, optional): Verwendung von CSS-Pixeln oder Gerätepixeln für den Screenshot.

    • fullPage (boolesch, optional): Bei true wird ein Screenshot der gesamten scrollbaren Seite statt des aktuell sichtbaren Viewports aufgenommen. Kann nicht mit Element-Screenshots verwendet werden.

    • expectation (Objekt, optional): Zusätzliche Konfiguration des Seitenstatus

  • Schreibgeschützt: false

• browser_type

  • Titel: Text eingeben

  • Beschreibung: Text in ein bearbeitbares Element eingeben

  • Parameter:

    • selectors (Array): Array von Elementselektoren (max. 5) mit Unterstützung für ref-, Rollen-, CSS- oder textbasierte Auswahl

    • text (Zeichenfolge): Text, der in das Element eingegeben werden soll

    • submit (boolesch, optional): Bei true nach der Eingabe die Eingabetaste drücken

    • slowly (boolesch, optional): Bei true für die Autovervollständigung langsam tippen

    • expectation (Objekt, optional): Konfiguration des Seitenstatus. Für Formulare batch_execute verwenden

  • Schreibgeschützt: false

• browser_wait_for

  • Titel: Warten auf

  • Beschreibung: Warten, bis Text erscheint oder verschwindet oder eine bestimmte Zeit vergangen ist

  • Parameter:

    • time (Zahl, optional): Wartezeit in Sekunden

    • text (Zeichenfolge, optional): undefined

    • textGone (Zeichenfolge, optional): undefined

    • expectation (Objekt, optional): Seitenstatus nach dem Warten

  • Schreibgeschützt: true

• browser_tab_close

  • Titel: Tab schließen

  • Beschreibung: Einen Tab nach Index schließen oder den aktuellen Tab schließen

  • Parameter:

    • index (Zahl, optional): Index des zu schließenden Tabs (für aktuellen Tab weglassen)

    • expectation (Objekt, optional): Seitenstatus nach dem Schließen

  • Schreibgeschützt: false

• browser_tab_list

  • Titel: Tabs auflisten

  • Beschreibung: Browser-Tabs mit Titeln und URLs auflisten

  • Parameter:

    • expectation (Objekt, optional): Konfiguration des Seitenstatus

  • Schreibgeschützt: true

• browser_tab_new

  • Titel: Neuen Tab öffnen

  • Beschreibung: Einen neuen Tab öffnen

  • Parameter:

    • url (Zeichenfolge, optional): URL für den neuen Tab (optional)

    • expectation (Objekt, optional): Seitenstatus des neuen Tabs

  • Schreibgeschützt: false

• browser_tab_select

  • Titel: Tab auswählen

  • Beschreibung: Einen Tab nach Index auswählen

  • Parameter:

    • index (Zahl): Der Index des auszuwählenden Tabs

    • expectation (Objekt, optional): Seitenstatus nach dem Tab-Wechsel

  • Schreibgeschützt: false

• browser_install

  • Titel: Den in der Konfiguration angegebenen Browser installieren

  • Beschreibung: Den in der Konfiguration angegebenen Browser installieren. Rufen Sie dies auf, wenn Sie eine Fehlermeldung erhalten, dass der Browser nicht installiert ist.

  • Parameter: Keine

  • Schreibgeschützt: false

• browser_mouse_click_xy

  • Titel: Klicken

  • Beschreibung: An bestimmten Koordinaten klicken

  • Parameter:

    • element (Zeichenfolge): undefined

    • x (Zahl): X-Koordinate (erfordert --caps=vision)

    • y (Zahl): Y-Koordinate (erfordert --caps=vision)

    • expectation (Objekt, optional): Seitenstatus nach dem Klick. Elementreferenz gegenüber Koordinaten bevorzugen

  • Schreibgeschützt: false

• browser_mouse_drag_xy

  • Titel: Maus ziehen

  • Beschreibung: Von einer Koordinate zu einer anderen ziehen

  • Parameter:

    • element (Zeichenfolge): undefined

    • startX (Zahl): Start-X (erfordert --caps=vision)

    • startY (Zahl): Start-Y (erfordert --caps=vision)

    • endX (Zahl): End-X

    • endY (Zahl): End-Y

    • expectation (Objekt, optional): Seitenstatus nach dem Ziehen. Elementreferenzen gegenüber Koordinaten bevorzugen

  • Schreibgeschützt: false

• browser_mouse_move_xy

  • Titel: Maus bewegen

  • Beschreibung: Die Maus zu Koordinaten bewegen. Erfordert die Vision-Funktion; nach Möglichkeit elementbasierte Interaktionen bevorzugen.

  • Parameter:

    • element (Zeichenfolge): undefined

    • x (Zahl): X-Koordinate

    • y (Zahl): Y-Koordinate

    • expectation (Objekt, optional): undefined

  • Schreibgeschützt: false

• browser_pdf_save

  • Titel: Als PDF speichern

  • Beschreibung: Seite als PDF speichern

  • Parameter:

    • filename (Zeichenfolge, optional): Dateiname zum Speichern des PDFs. Standardmäßig page-{timestamp}.pdf, falls nicht angegeben.

  • Schreibgeschützt: false

• browser_dashboard

  • Titel: Browser-Dashboard öffnen

  • Beschreibung: Die gebündelte Browser-Vorschau und das Dashboard zur Tab-Auswahl öffnen.

  • Parameter: Keine

  • Schreibgeschützt: true

Beispiele zur Token-Optimierung

Der Fast Server bietet eine erweiterte Token-Optimierung durch Erwartungssteuerung und Stapelausführung:

Grundlegende Erwartungssteuerung

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

Erwartungsoptionen

• includeSnapshot (boolesch, Standard: je nach Werkzeug unterschiedlich): Barrierefreiheits-Snapshot der Seite einbeziehen

• includeConsole (boolesch, Standard: je nach Werkzeug unterschiedlich): Konsolennachrichten des Browsers einbeziehen

• includeDownloads (boolesch, Standard: true): Download-Informationen einbeziehen

• includeTabs (boolesch, Standard: je nach Werkzeug unterschiedlich): Tab-Informationen einbeziehen

• includeCode (boolesch, Standard: true): Ausgeführten Code in die Antwort einbeziehen

Erweiterte Snapshot-Optionen

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

Optionen zum Filtern der Konsole

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

Stapelausführung

Führen Sie mehrere Browseraktionen in einer einzigen Anfrage aus – mit optimierter Antwortverarbeitung und flexibler Fehlersteuerung.

Grundlegende Stapelausführung

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

Erweiterte Stapelkonfiguration

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

Optionen zur Fehlerbehandlung

• continueOnError (pro Schritt): Stapelausführung auch bei Fehlern in diesem Schritt fortsetzen

• stopOnFirstError (global): Gesamten Stapel beim ersten Fehler anhalten

• Die flexible Kombination ermöglicht robuste Automatisierungsworkflows

Werkzeugspezifische Standardwerte

Jedes Werkzeug hat optimierte Standardwerte basierend auf typischen Nutzungsmustern:

• Navigationswerkzeuge (browser_navigate): Vollständigen Kontext zur Überprüfung einbeziehen

• Interaktive Werkzeuge (browser_click, browser_type): Snapshot einbeziehen, aber minimale Protokollierung

• Screenshot-/Snapshot-Werkzeuge: Zusätzlichen Kontext ausschließen

• Code-Auswertung: Konsolenausgabe einbeziehen, aber minimale sonstige Informationen

• Wartevorgänge: Minimale Ausgabe für Effizienz

Leistungsvorteile

• Token-Reduzierung: 50–80 % weniger Token-Verbrauch durch optimierte Erwartungen

• Schnellere Ausführung: 2–5-fache Geschwindigkeitsverbesserung durch Stapelausführung

• Geringere Latenz: Weniger Roundtrips zwischen Client und Server

• Kostenoptimierung: Geringere API-Kosten durch reduzierten Token-Verbrauch

Erkennung von Antwortunterschieden

Der Fast Server enthält eine automatische Differenzerkennung, um Änderungen zwischen aufeinanderfolgenden Werkzeugausführungen effizient zu verfolgen:

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

Vorteile der Differenzerkennung

• Minimaler Token-Verbrauch: Nur geänderte Inhalte werden statt vollständiger Snapshots angezeigt

• Änderungsverfolgung: Erkennt automatisch, was sich nach Aktionen geändert hat

• Flexible Formate: Auswahl zwischen einheitlichen, geteilten oder minimalen Diff-Formaten

• Intelligentes Caching: Vergleicht mit der vorherigen Antwort desselben Werkzeugs

Wann die Differenzerkennung verwendet werden sollte

1. UI-Interaktionen ohne Navigation: Klicks, Tippen, Hover-Effekte

2. Dynamische Inhaltsaktualisierungen: Laden weiterer Elemente, Echtzeit-Updates

3. Formularinteraktionen: Änderungen verfolgen, während Benutzer Formulare ausfüllen

4. Selektive Überwachung: Mit CSS-Selektoren verwenden, um bestimmte Bereiche zu verfolgen

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

Bewährte Vorgehensweisen

1. Stapelausführung für mehrstufige Workflows verwenden

2. Differenzerkennung für Aktionen ohne Seitennavigation aktivieren

3. Snapshots deaktivieren für Zwischenschritte, die keine Überprüfung erfordern

4. Selektive Snapshots mit CSS-Selektoren für große Seiten verwenden

5. Konsolennachrichten auf relevante Ebenen filtern

6. Globale und schrittspezifische Erwartungen kombinieren für eine fein abgestimmte Steuerung

7. Minimales Diff-Format für maximale Token-Ersparnis verwenden

Beispiele für das Diagnosesystem

Alternative Elemente finden, wenn Selektoren fehlschlagen:

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

Umfassende Seitendiagnose erzeugen:

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

Automatisierungsfehler mit erweiterten Meldungen beheben: Alle Werkzeuge liefern automatisch erweiterte Fehlermeldungen mit:

• Vorschlägen für alternative Elemente

• Seitenstrukturanalyse

• Kontextbezogenen Tipps zur Fehlerbehebung

• Leistungseinblicken

Filtern von Netzwerkanfragen

Das Werkzeug browser_network_requests bietet erweiterte Filterfunktionen, um den Token-Verbrauch bei der Arbeit mit Netzwerkprotokollen um bis zu 80–95 % zu reduzieren.

Grundlegende Verwendungsbeispiele

// 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
  }
}

Erweiterte Filterung

// 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
  }
}

Unterstützung von Regex-Mustern

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

Vorteile der Token-Optimierung

• Massive Reduzierung: 80–95 % weniger Token bei großen Anwendungen

• Gezielte Fehlersuche: Nur relevante Netzwerkaktivitäten anzeigen

• Leistungsüberwachung: Bestimmte Endpunkte oder Fehlermuster verfolgen

• Kosteneinsparungen: Geringere API-Kosten durch reduzierten Token-Verbrauch

Wann die Netzwerkfilterung verwendet werden sollte

1. API-Fehlerbehebung: Auf bestimmte Endpunkte und Methoden konzentrieren

2. Fehlerüberwachung: Nur fehlgeschlagene Anfragen verfolgen

3. Leistungsanalyse: Langsame oder problematische Endpunkte überwachen

4. Große Anwendungen: Überwältigende Netzwerkprotokolle reduzieren

5. Token-Verwaltung: Innerhalb der LLM-Kontextgrenzen bleiben

Migrationsanleitung

Vorhandener Code funktioniert ohne Änderungen weiter. Zur Optimierung:

1. Beginnen Sie damit, expectation: { includeSnapshot: false } zu Zwischenschritten hinzuzufügen.

2. Verwenden Sie Batch-Ausführung für Sequenzen von 3+ Operationen.

3. Passen Sie Erwartungen schrittweise an Ihre spezifischen Bedürfnisse an.

4. Verwenden Sie Diagnosetools, wenn Automatisierung fehlschlägt oder Debugging erfordert.

5. Setzen Sie --tool-profile=full vor einem Upgrade, wenn ein Client von der vollständigen statischen tools/list-Antwort abhängt.