Playwright MCP + JEV (Browser Intent Layer)

Semantyczny wrapper nad Playwright MCP z autonomicznym modelem decyzyjnym JEV (Decisions API).
Redukuje zużycie tokenów w kontekście głównego LLM o 94% – 99.8%, ukrywa niskopoziomowe drzewo DOM i pozwala na autonomiczną nawigację w stronę celu biznesowego.

📑 Spis Treści

1. Jak to działa?

2. Architektura Systemu

3. Narzędzia MCP (Intent-Only Mode)

4. Jak Odpalić? (Instalacja i Konfiguracja)

5. Opcje i Flagi Uruchomieniowe

6. Wyniki Benchmarków na Żywych Portalach

7. Uruchamianie Benchmarków i Testów

Related MCP server: Navigator MCP

💡 Jak to działa?

Problem z klasycznym Playwright MCP:

Tradycyjne integracje MCP z przeglądarką zrzucają całe drzewo dostępności (DOM/A11y) bezpośrednio do promptu głównego LLM przy każdym pojedynczym kroku:

• Na portalach takich jak Orange.pl czy Empik.com pojedynczy snapshot ma od 36 KB do aż 245 KB (ponad 65 000 tokenów!).

• Kilkukrokowa sesja potrafi zużyć 100 000 – 200 000 tokenów, kosztując kilkadziesiąt centów i błyskawicznie zapychając okno kontekstowe modelu.

• Ponadto klasyczny MCP eksponuje ponad 20 niskopoziomowych narzędzi mikrozarządzania (browser_click, browser_fill_form, browser_snapshot), których same opisy w promptcie systemowym zajmują ponad 2 500 tokenów i prowokują halucynacje refów selektorów.

Rozwiązanie: Browser Intent Layer (BIL + JEV):

1. Główny LLM staje się czystym orkiestratorem — wysyła wyłącznie zwięzłą intencję:

   { "goal": "dodaj do koszyka telefon iphone najnowszy z abonamentem najmniejszym i przejdź na dane zamawiającego" }

2. Drzewo DOM nigdy nie trafia do głównego LLM — zużycie tokenów orchestratora spada z ~65 000 do zaledwie ~150 tokenów (98–99.8% oszczędności).

3. Lokalny model decyzyjny JEV (Decisions API) — tani, wyspecjalizowany model micro-decyzji analizuje kandydatów i ocenia ich przydatność w skali 0–100% (noul), kosztując ułamki promila grosza per krok.

4. Wbudowana autonomia i bezpieczeństwo:

   • Automatyczny Consent Bypass neutralizuje blokujące nakładki RODO/cookies (Didomi, OneTrust, CookieBot).

   • LoopDetector chroni przed wpadnięciem w pętle decyzyjne.

   • Safety Escalation Policy eskaluje do głównego LLM tylko wtedy, gdy pewność wyboru spadnie poniżej progu bezpieczeństwa (< 0.60).

🏛️ Architektura Systemu

┌─────────────────────────────────────────────────────────────┐
│                    Główny LLM (Orchestrator)                │
│            Claude 3.5 Sonnet / GPT-4o / Gemini Pro          │
└──────────────────────────────┬──────────────────────────────┘
                               │  { goal: "..." } (~150 tokenów)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│             BROWSER INTENT LAYER (JEV Proxy Server)         │
│                                                             │
│  1. Snapshot Adapter     → pobiera drzewo A11y              │
│  2. Normalizer           → kompresuje i deduplikuje elementy│
│  3. Stop-Words Filter    → eliminuje szum językowy (PL/EN)  │
│  4. Candidate Retriever  → wyłuskuje top 30 kandydatów      │
│  5. JEV Resolver         → model 'noul' (skala 0.0–1.0)     │
│  6. Loop Detector        → wykrywa cykle i limity kroków    │
│  7. Playwright Executor  → zarządza akcjami w Playwright    │
└──────────────────────────────┬──────────────────────────────┘
                               │  Wewnętrzne JSON-RPC (ref / target)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│              Playwright MCP Child + Przeglądarka            │
│                                                             │
│  • Consent Bypass Script (Didomi / OneTrust auto-bypass)    │
│  • 25 000 ms Action Timeout (odporność na ciężkie portale)  │
│  • Silnik Chromium (Headed lub Headless)                    │
└─────────────────────────────────────────────────────────────┘

Kluczowe komponenty (src/jev-proxy/):

• bil-controller.js — serce pętli decyzyjnej: pobranie snapshotu ➡️ normalizacja ➡️ wybór kandydatów ➡️ rezolucja JEV ➡️ wykonanie akcji lub eskalacja.

• jev-resolver.js — integracja z OpenRouter Decisions API z niezależnym ocenianiem prawdopodobieństwa w skali 0–100% (noul).

• candidate-retriever.js — leksykalno-semantyczny filtr kandydatów z mechanizmem eliminacji słów posiłkowych (stop-words).

• consent-bypass.js — wstrzykiwany do przeglądarki skrypt neutralizujący nakładki cookies/RODO przechwytujące zdarzenia wskaźnika myszy.

• loop-detector.js — detektor cykli oparty na hashowaniu stanu stron (fingerprinting).

• playwright-executor.js — jedyny moduł w systemie znający selektory i refy, odpowiedzialny za klikanie, wypełnianie formularzy i obsługę timeoutów.

🧰 Narzędzia MCP (Intent-Only Mode)

Domyślnie serwer działa w trybie Intent-Only Mode, eksponując dla zewnętrznego klienta wyłącznie 7 narzędzi semantycznych:

🔒 Dlaczego ukryliśmy niskopoziomowe narzędzia DOM?
W klasycznym MCP narzędzia takie jak browser_click, browser_fill_form, browser_snapshot zaśmiecają prompt klienta (+2 500 tokenów na każde zapytanie) i zmuszają go do mikrozarządzania refami. Ukrycie ich wymusza czystą komunikację intencyjną. W razie potrzeby można je przywrócić flagą --full-tools.

🚀 Jak Odpalić?

Krok 1: Wymagania wstępne

• Node.js w wersji >= 18

• Klucz API serwisu OpenRouter z dostępem do modelu Decisions API (domyślnie typesafe/jev-1.13)

Krok 2: Instalacja i konfiguracja .env

# Sklonuj repozytorium i zainstaluj zależności
git clone https://github.com/rossik86/playwright-mcp-jev.git
cd playwright-mcp-jev
npm install

# Utwórz plik .env na podstawie szablonu
cp .env.example .env

Wypełnij plik .env:

JEV_API_KEY=sk-or-v1-twoj_klucz_openrouter
JEV_MODEL=typesafe/jev-1.13
JEV_BASE_URL=https://openrouter.ai/api
INTENT_ONLY=true

Krok 3: Konfiguracja w klientach MCP

Dodaj serwer do konfiguracji swojego klienta MCP (np. mcp.json w Cursor / VS Code / Claude Desktop / Antigravity):

{
  "mcpServers": {
    "playwright-jev": {
      "command": "node",
      "args": [
        "c:/workspace/playwright/src/jev-proxy/cli.js",
        "--headless"
      ],
      "env": {
        "JEV_API_KEY": "sk-or-v1-twoj_klucz_openrouter"
      }
    }
  }
}

Krok 4: Uruchomienie bezpośrednio z linii poleceń (CLI)

# 1. Tryb z widocznym oknem przeglądarki (headed)
node src/jev-proxy/cli.js

# 2. Tryb bezgłowy w tle (headless)
node src/jev-proxy/cli.js --headless

# 3. Uruchomienie z jawnymi parametrami
node src/jev-proxy/cli.js --headless --jev-api-key sk-or-v1-... --jev-model typesafe/jev-1.13

⚙️ Opcje i Flagi Uruchomieniowe

📊 Wyniki Benchmarków na Żywych Portalach

Przetestowano działanie systemu na realnych, złożonych portalach e-commerce i serwisach transakcyjnych w Polsce:

📈 Podsumowanie Zysków:

• Redukcja tokenów kontekstu: o 94.4% – 99.8% w porównaniu z klasycznym zrzucaniem snapshota A11y.

• Czysty kontekst roboczy: Główny model nie jest zaśmiecany dziesiątkami kilobajtów kodu HTML/DOM.

• Koszty wykonania: Pojedynczy wieloetapowy proces kosztuje w JEV Decisions API od $0.0001 do $0.0004 (mniej niż pół promila centa), podczas gdy w klasycznym podejściu wysłanie 65 000 tokenów do Claude 3.5 Sonnet / GPT-4o kosztuje $0.20 – $0.50 za pojedynczy krok.

🧪 Uruchamianie Benchmarków i Testów

W projekcie przygotowano dedykowane skrypty npm ułatwiające uruchamianie benchmarków i testów jednostkowych:

# 1. Uruchomienie benchmarku dla konkretnych portali:
npm run bil:benchmark:grandbazaar   # GrandBazaar.pl (kebab kraftowy - 100% sukces)
npm run bil:benchmark:orange        # Orange.pl (iPhone + konfigurator planu)
npm run bil:benchmark:empik         # Empik.com (Stephen King Misery - 99.8% redukcji)

# 2. Uruchomienie pełnego benchmarku porównawczego dla wszystkich scenariuszy
npm run bil:benchmark:both

# 3. Uruchomienie tylko silnika BIL (z tokenami i kosztami)
npm run bil:benchmark

# 4. Uruchomienie tylko silnika klasycznego Playwright MCP
npm run bil:benchmark:classic

# 5. Uruchomienie zestawu testów jednostkowych (55 testów, 100% pass)
npm run bil:test