Automatyzacja przeglądarek za pomocą zdalnego serwera MCP Playwright Workspaces

Zdalny serwer MCP Playwright Workspaces zapewnia agentom AI zarządzaną zdalną przeglądarkę oraz zestaw narzędzi do automatyzacji przeglądarki. Agent może otworzyć sesję przeglądarki, nawigować po stronach, znaleźć i wchodzić w interakcje z elementami, sprawdzać aktywność przeglądarki, robić zrzuty ekranu i zamykać sesję. Nie musisz instalować Playwrighta ani przeglądarki w środowisku agenta.

Serwer korzysta z Model Context Protocol zamiast Streamable HTTP. Obsługuje uwierzytelnianie Microsoft Entra ID oraz tokeny dostępu do przestrzeni roboczej. Współpracuje ze zdalnymi klientami MCP, w tym Microsoft Foundry Agent Service oraz Visual Studio Code.

W tym artykule dowiesz się, jak:

• Zbuduj endpoint MCP dla przestrzeni roboczej Playwright.
• Uwierzytelnij się, używając Microsoft Entra ID lub tokena dostępu do przestrzeni roboczej.
• Połącz serwer z usługą Microsoft Foundry Agent Service lub Visual Studio Code.
• Uruchamiaj kompletne przepływy automatyzacji przeglądarki opartych na agentach.
• Wybierz i bezpiecznie korzystaj z dostępnych narzędzi przeglądarkowych.
• Zajmij się wygaśnięciem sesji, timeoutami i innymi częstymi błędami.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

• Konto platformy Azure z aktywną subskrypcją.
• Miejsce pracy dla dramaturgów z dostępem do zdalnego podglądu MCP.
• Identyfikator przestrzeni roboczej i region platformy Azure tej przestrzeni roboczej.
• Tożsamość z uprawnieniami do tworzenia i korzystania z sesji przeglądarkowych w przestrzeni roboczej.
• Dla Microsoft Foundry, projekt Foundry oraz uprawnienia do tworzenia połączeń projektów i konfigurowania agentów.
• W przypadku programu Visual Studio Code: aktualna wersja programu Visual Studio Code z dostępem do GitHub Copilot i włączoną obsługą MCP.

Wybieranie metody uwierzytelniania

Używaj Microsoft Entra ID, gdy twój klient MCP obsługuje OAuth lub zarządzaną tożsamość. Zdalny serwer MCP używa tego identyfikatora zasobów i delegowanego zakresu:

Resource: https://mcp.playwright.microsoft.com
Scope: https://mcp.playwright.microsoft.com/Playwright.Mcp.Tools

Serwer publikuje metadane chronionych zasobów OAuth. Klienci obsługujący mechanizm OAuth Discovery, w tym Visual Studio Code, mogą wykryć serwer autoryzacji i wymagany zakres uprawnień na podstawie punktu końcowego MCP przypisanego do obszaru roboczego. Zalogowana tożsamość musi mieć dostęp do obszaru roboczego Playwright poprzez kontrolę dostępu opartą na rolach na platformie Azure (RBAC).

Stwórz token dostępu do przestrzeni roboczej dla kompatybilności

Pomiń tę sekcję, gdy używasz Microsoft Entra ID. Jeśli uwierzytelnianie za pomocą tokena dostępu nie jest jeszcze włączone dla przestrzeni roboczej:

1. Zaloguj się do portalu Azure.
2. Otwórz swoją przestrzeń do pracy dla dramaturgów.
3. W Ustawieniach wybierz Zarządzanie dostępem.
4. Włącz token dostępu do usługi Playwright.
5. Wybierz pozycję Generuj token.
6. Wprowadź nazwę i datę ważności, a następnie wygeneruj token.
7. Natychmiast skopiuj token. Nie da się odzyskać jej wartości później.

Przechowuj token w zarządzanym tajnym magazynie lub w bezpiecznym systemie uwierzytelniania udostępnionym przez klienta MCP. Cofnij i wymień go, jeśli był odsłonięty. Aby utworzyć token dostępu do przestrzeni roboczej, zobacz Zarządzaj tokenami dostępu do przestrzeni roboczej.

Zbuduj zdalny punkt końcowy MCP

Punkt końcowy jest ograniczony do jednej przestrzeni roboczej i regionu:

https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp

Replace:

• <region>z regionem Azure przestrzeni roboczej.
• <workspace-id> z identyfikatorem obszaru roboczego wyświetlonym w portalu Azure.

Przykład:

https://eastus.mcp.playwright.microsoft.com/playwrightworkspaces/00000000-0000-0000-0000-000000000000/mcp

Wartość w x-api-key nagłówku żądania musi być tokenem dostępu utworzonym dla tej samej przestrzeni roboczej co <workspace-id>. Użyj punktu końcowego dla regionu przestrzeni roboczej, a nie regionu najbliższego klientowi MCP.

Zrozum cykl życia sesji przeglądarki

Przepływ automatyzacji przeglądarki składa się z trzech etapów:

1. Zadzwoń do create_browser_session. Wynik zawiera niejawny browserSessionId i może zawierać adres URL widoku na żywo.
2. Przekaż to browserSessionId każdemu narzędziu przeglądarki używanemu w tym przepływie.
3. Wywołaj close_browser_session w kroku czyszczenia, nawet jeśli przepływ się nie powiedzie.

Transport HTTP MCP nie zachowuje stanu przeglądarki. browserSessionId identyfikuje zdalną przeglądarkę w ramach oddzielnych wywołań narzędzia. Zachowaj to w tajemnicy i używaj tylko z przestrzenią roboczą i tożsamością, która ją stworzyła.

Obecne zachowanie podglądu obejmuje następujące ograniczenia:

• Sesja należy do jej twórcy i nie może być współdzielona z innym podmiotem.
• Połączenia na jedną sesję są przetwarzane w kolejności. Nie wnosz jednoczesnych działań przeciwko tej samej sesji.
• Nieaktywna sesja jest sprzątana po 15 minutach. Wymagane jest jawne czyszczenie.
• Zamknięta lub wygasła sesja nie może zostać ponownie otworzyta.
• Utrata połączenia jest kluczowa dla sesji. Stwórz nową sesję, aby kontynuować.
• Wynik może zawierać element liveViewUrl. Dostępność trybu na żywo zależy od sesji.

Połącz się z usługą agenta Microsoft Foundry

Użyj Microsoft Entra Agent Identity, aby uwierzytelnić agenta za pomocą zarządzanej tożsamości projektu Foundry. Nadaj tej tożsamości dostęp do przestrzeni roboczej Playwright przed podłączeniem narzędzia MCP.

Utwórz połączenie projektu

1. Otwórz swój projekt w portalu Microsoft Foundry.
2. Otwórz doświadczenie zarządzania projektem, a następnie wybierz Połączone zasoby.
3. Stwórz połączenie dla zdalnego serwera MCP.
4. Wprowadź opisową nazwę połączenia, taką jak playwright-mcp-connection.
5. Wybierz Microsoft Entra Agent Identity jako metodę uwierzytelniania.
6. Dołącz jako widz: https://mcp.playwright.microsoft.com.
7. Zapisz połączenie.

Zarządzana tożsamość projektu musi pełnić rolę umożliwiającą operacje sesji przeglądarki na docelowej przestrzeni roboczej Playwright. Nie używaj tokena tożsamości z jednego projektu jako wspólnego sekreta w innym projekcie.

Jeśli Microsoft Entra Agent Identity nie jest dostępna dla klienta lub środowiska, utwórz połączenie Klucze niestandardowe z kluczem o nazwie x-api-key i tokenem dostępu do obszaru roboczego jako wartością tego klucza.

Dodaj zdalne narzędzie MCP

1. Stwórz lub otwórz agenta w portalu Foundry.

2. Dodaj zdalny serwer MCP lub narzędzie MCP.

3. Użyj następujących ustawień:

   Setting	Value
   Etykieta serwera	Unikalna etykieta, taka jak playwrightWorkspace
   Adres URL serwera	Zdalny punkt końcowy MCP w zakresie obszaru roboczego
   Połączenie projektu	Utworzone wcześniej połączenie Microsoft Entra Agent Identity
   Approval	Wymagaj zatwierdzenia każdego połączenia podczas oceny integracji
   Dozwolone narzędzia	Zacznij tylko od narzędzi potrzebnych do przepływu

4. Zapisz konfigurację agenta.

5. W instrukcjach dla agenta należy wymagać, aby agent utworzył jedną sesję, ponownie używał elementu browserSessionId tej sesji i zamknął sesję po zakończeniu zadania.

Minimalna lista dozwolonych narzędzi dla przepływu nawigacji ukierunkowanego na odczyt to:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Dodaj narzędzia do interakcji, takie jak browser_click lub browser_type, tylko wtedy, gdy dany scenariusz tego wymaga. Nie włączaj browser_evaluatebrowser_run_code domyślnie.

Testuj przepływ w odlewni

Użyj promptu, który określa cel i wymóg sprzątania. Przykład:

Create a browser session, open https://example.com, inspect the page snapshot,
report the main heading and destination URL, and close the browser session.
Always close the session, including when a browser step fails.

Gdy agent prosi o zgodę:

1. Sprawdź, czy etykieta serwera to skonfigurowany serwer Playwright.
2. Przejrzyj nazwę narzędzia i wszystkie argumenty, zwłaszcza adresy URL, selektory, tekst, przesłane dane i kod.
3. Zatwierdzaj tylko oczekiwaną operację.
4. Sprawdź, czy ostateczna odpowiedź opiera się na wyniku strony.
5. Potwierdź, że przepływ nazywa się close_browser_session.

Informacje o bieżących polach połączeń usługi Foundry, obsłudze zatwierdzania, przykładach SDK oraz limitach klientów można znaleźć w artykule Łączenie agentów z punktami końcowymi serwera MCP.

Nawiązywanie połączenia z programu Visual Studio Code

Visual Studio Code może odkryć konfigurację OAuth serwera zdalnego i zalogować Cię za pomocą Microsoft Entra ID. Konfiguracja wymaga jedynie punktu końcowego o zakresie obszaru roboczego.

1. W Visual Studio Code uruchom MCP: Open User Configuration z palety poleceń.
2. Dodaj następującą konfigurację i zastąp symbole zastępcze adresów punktów końcowych.

{
  "servers": {
    "playwrightWorkspace": {
      "type": "http",
      "url": "https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp"
    }
  }
}

3. Uruchom serwer z edytora konfiguracji lub uruchom MCP: List Servers.
4. Gdy zostanie wyświetlony monit, zaloguj się przy użyciu konta Microsoft Entra, które ma dostęp do przestrzeni roboczej Playwright.
5. Zatwierdź żądane Playwright.Mcp.Tools uprawnienie, jeśli dla Twojej dzierżawy jest wymagana zgoda.
6. Przejrzyj adres URL i konfigurację serwera, a następnie popewnij, że ufasz serwerowi.
7. Otwórz czat i wybierz Konfiguruj narzędzia. Włącz tylko narzędzia Playwright potrzebne do tego zadania.
8. Uruchom przykładowe polecenie z poprzedniej sekcji Foundry.
9. Przejrzyj potwierdzenia narzędzi i sprawdź, czy sesja została zamknięta na końcu.

Używaj konfiguracji użytkownika, gdy połączenie jest osobiste. Konfiguracja przestrzeni roboczej zawierająca tylko punkt końcowy może być współdzielona. Visual Studio Code bezpiecznie buforuje dane logowania OAuth i może je ponownie wykorzystać podczas ponownego połączenia.

Jeśli uwierzytelnianie Microsoft Entra nie jest dostępne w środowisku klienta, skonfiguruj nagłówek x-api-key z chronionymi danymi wejściowymi, jak opisano w danych wejściowych konfiguracji MCP. Nigdy nie wpisuj wartości tokena dostępu do przestrzeni roboczej bezpośrednio w .mcp.json

Aby poznać lokalizacje konfiguracji, tajne wejścia, zaufanie serwera i diagnostykę, zobacz Dodaj i zarządzaj serwerami MCP w Visual Studio Code oraz referencją konfiguracji MCP.

Zaprojektuj przepływ automatyzacji agentycznej

Zamiast prosić agenta o wykonanie długiej sekwencji bez sprawdzania stanu strony, stosuj pętlę obserwacji-działaj-weryfikuj.

1. Utwórz: Wywołaj create_browser_session i zachowaj jego browserSessionId.
2. Nawigacja: Zadzwoń browser_navigate za pomocą wyraźnego, zatwierdzonego adresu URL.
3. Uwaga: Użyj browser_find, aby zawęzić wyszukiwanie, lub browser_snapshot, aby uzyskać szerszy obraz dostępności.
4. Działanie: Użyj odwołania do migawki lub unikalnego selektora za pomocą narzędzia do interakcji.
5. Czekaj: Wywołaj browser_wait_for dla tekstu, który ma się pojawić, tekstu, który ma zniknąć, lub określonego opóźnienia.
6. Sprawdź: Zrób kolejne zdjęcie lub sprawdź aktywność konsoli i sieci.
7. Obsługa gałęzi: Obsługa dialogu, przełączanie zakładek lub przesyłanie plików tylko wtedy, gdy stan strony tego wymaga.
8. Zbierz dowody: Wywołaj browser_take_screenshot, jeśli wynik wizualny jest przydatny. Nie używaj zrzutów ekranu do wybierania celów akcji.
9. Czyszczenie: Wywołaj close_browser_session w ścieżce czyszczenia typu finally.

Wybierz stabilne cele akcji

Preferuj odniesienia zwracane przez browser_snapshot lub browser_find. Opisują one dostępne elementy strony i zmniejszają zależność od znaczników specyficznych dla implementacji. Używaj unikalnego selektora, gdy stabilna referencja migawki nie jest dostępna.

Odśwież zrzut po nawigacji lub po wykonaniu działania zmieniającego stronę. Uprzednio zwrócony element docelowy może stać się nieaktualny, gdy strona jest renderowana ponownie.

Bezpiecznie obsługuj dialogi

Akcja może zwrócić wynik dialog-opened po uprzedniej zmianie stanu strony. Ten rezultat nie jest typową porażką działania.

1. Nie powtarzaj oryginalnej akcji.
2. Wywołaj browser_handle_dialog, ustawiając accept na true lub false.
3. W dialogu promptowym dodaj tylko promptText podczas jego przyjmowania.
4. Przed kontynuacją jeszcze raz obejrzyj stronę.

Radzenie sobie z niejednoznacznymi błędami

Przekroczenie limitu czasu lub rozłączenie przez dzwoniącego nie dowodzi, że dane działanie nie odniosło skutku. Przed ponownym podjęciem próby operacji nieidempotentnej, takiej jak kliknięcie, wysłanie formularza, przesłanie czy wykonanie kodu:

1. Uruchom browser_snapshot, browser_find lub inne narzędzie do obserwacji, jeśli sesja jest nadal dostępna.
2. Określ, czy nastąpiła oczekiwana zmiana stanu.
3. Spróbuj ponownie tylko wtedy, gdy powtarzanie czynności jest bezpieczne.
4. Jeśli sesja wygasła, utwórz nową sesję i zrestartuj od znanego stanu aplikacji.

Dokumentacja narzędzia

Wszystkie narzędzia ograniczone do przeglądarki wymagają browserSessionId. Pokazane tutaj limity dla ciągów i kolekcji to bieżące limity wersji zapoznawczej.

Narzędzia sesyjne

Narzędzia nawigacyjne i obserwacyjne

Narzędzia interakcji

Zakładki, pliki i narzędzia do kodowania

Po każdym przepływie pracy automatyzacji wywołaj close_browser_session przy użyciu aktywnego browserSessionId.

Kształt pola formularza

Każde browser_fill_form pole ma taki kształt:

{
  "target": "<snapshot-reference-or-selector>",
  "value": "<string-or-boolean>",
  "name": "<optional-display-name>",
  "type": "<optional-field-type>"
}

Wartość ciągu dla pola może zawierać maksymalnie 100 KiB znaków. name może zawierać maksymalnie 1 024 znaki, a type maksymalnie 128 znaków.

Kształt przesyłania pliku

Każdy browser_file_upload plik używa tego kształtu:

{
  "name": "example.txt",
  "data": "SGVsbG8sIHdvcmxkIQ==",
  "mimeType": "text/plain"
}

mimeType parametr jest opcjonalny i domyślnie ma wartość application/octet-stream.

Limity przesyłania plików

• Od 1 do 20 plików na każde wywołanie narzędzia.
• Maksymalny rozmiar dekodowany 10 MiB dla każdego pliku.
• Maksymalny łączny rozmiar dekodowany 50 MiB.
• Maksymalna nazwa pliku o długości 4 096 znaków.
• Maksymalny typ MIME o 1024 znakach.
• Wymagane są ważne dane base64.

Kształty narzędzi JavaScript

Dla browser_evaluate przekaż wyrażenie funkcji:

() => document.title

Gdy podamy target, funkcja otrzymuje element dopasowania:

element => element.textContent

Dla browser_run_code przekaż instrukcje stanowiące treść funkcji asynchronicznej, której parametrem page jest obiekt page Playwright. Zwracaj tylko dane serializowalne JSON i utrzymuj je w granicach limitu odpowiedzi inline.

Ograniczenia i bieżące zachowanie

Odpowiedzi są zwracane w linii. Ten podgląd nie ujawnia zasobów MCP ani trwałego przechowywania artefaktów dla dużych migawek, zrzutów ekranu czy pobranych plików. Nadpisania przeglądarki, systemu operacyjnego, viewportu, ustawień regionalnych i user-agentu nie są udostępniane jako parametry tworzenia sesji.

Obsługa błędów

Błąd narzędzia zawiera stabilny kod błędu, bezpieczny dla klienta komunikat, wartość retryable oraz informacje o korelacji. Użyj zwróconej retryable wartości jako sygnału podstawowego, wraz z efektami ubocznymi operacji.

Rozwiązywanie typowych problemów

Klient MCP zgłasza błąd „Brak autoryzacji”

• Potwierdź, że uwierzytelnianie za pomocą tokenów dostępu jest włączone dla przestrzeni roboczej.
• Potwierdź, że token nie jest wygasły ani cofnięty.
• Użyj surowej wartości tokena jako wartości x-api-key. Nie dodawaj przedrostka Bearer .
• Potwierdź, że token i endpoint należą do tej samej przestrzeni roboczej.
• Jeśli błędnie skopiowałeś sekret, stwórz nowy token, ponieważ nie możesz odzyskać istniejących wartości z portalu.

Klient MCP zgłasza odmowę dostępu

• Potwierdź, że użytkownik powiązany z tokenem nadal ma uprawnienia do tworzenia sesji przeglądarkowych.
• Używaj tego samego połączenia projektu lub tokena dla wszystkich wywołań w jednej sesji przeglądarki.
• Nie przekazuj browserSessionId między użytkownikami, agentami używającymi różnych danych uwierzytelniających ani przestrzeniami roboczymi.

Narzędzia nie zostały wykryte

• Zweryfikuj cały punkt końcowy, w tym /playwrightworkspaces/<workspace-id>/mcp.
• Sprawdź, czy region punktu końcowego jest zgodny z regionem obszaru roboczego.
• Potwierdź, że klient korzysta z transportu HTTP MCP i wysyła x-api-key podczas wykrywania i wywołań narzędzi.
• W Visual Studio Code uruchom MCP: List Servers, wybierz serwer, a następnie wybierz Show Output.
• Zrestartuj połączenie MCP lub zresetuj narzędzia z pamięci podręcznej po zmianie endpointu.

Agent nie wywołuje narzędzia przeglądarki

• Wyraźnie powiedz agentowi, aby korzystał z skonfigurowanego serwera Playwright MCP.
• Sprawdź, czy wymagane narzędzie pojawia się na liście włączonych lub dozwolonych narzędzi klienta.
• Uwzględnij cykl tworzenia, użycia i zamknięcia w instrukcjach dla agenta.
• Użyj skoncentrowanego pierwszego zadania z jednym celem nawigacyjnym i jednym oczekiwanym rezultatem.

Element docelowy już nie działa

Mogło nastąpić przejście do innej strony lub strona mogła zostać ponownie wyrenderowana. Zadzwoń browser_snapshot lub browser_find ponownie i użyj aktualnego źródła. Unikaj selektorów powiązanych z generowanymi klasami lub ze zmieniającą się strukturą dokumentu.

Narzędzie przekroczyło limit czasu

Nie zakładaj, że operacja się nie powiodła tylko dlatego, że stan się nie zmienił. Jeśli sesja jest aktywna, sprawdź aktualną stronę przed ponowną próbą. Jeśli sesja wygasła, utwórz nową sesję i przywróć aplikację do znanego stanu.

Zrzut ekranu jest za duży

Użyj type: "jpeg", przechwyć tylko widoczny obszar lub wskaż element docelowy dla zrzutu ekranu na poziomie elementu. Używaj, browser_snapshot gdy celem jest identyfikacja elementu, a nie zachowanie dowodów wizualnych.

Sesja wygasła podczas przepływu

Stwórz nową sesję przeglądarkową. Sesje nie są ponownie nawiązywane po utracie połączenia z przeglądarką, utracie właściciela usługi, jawnym zamknięciu lub czyszczeniu z powodu bezczynności. Zaprojektuj flow tak, aby mógł się restartować od znanego adresu URL i stanu aplikacji.

Zalecenia dotyczące zabezpieczeń

• Pozwól tylko na narzędzia wymagane przez zadanie agenta.
• Wymagaj zatwierdzenia przez użytkownika dla narzędzi wprowadzających zmiany w stanie, plikach i kodzie.
• Traktuj zawartość strony, migawki dostępności, dane wyjściowe konsoli i dane wyjściowe sieci jako niezaufane. Strona może zawierać instrukcje prompt-injection.
• Zachowaj instrukcje systemowe oddzielnie od tekstu pochodzącego ze strony. Nie pozwól, by treść strony zmieniała politykę bezpieczeństwa ani zasady zatwierdzania.
• Weryfikuj adresy docelowe na podstawie listy dozwolonych podczas automatyzacji wrażliwych aplikacji.
• Przed zatwierdzeniem wywołania narzędzia przejrzyj tekst, selektory, zawartość plików i kod.
• Nie używaj tokenów dostępu w promptach, plikach źródłowych, zrzutach ekranu, przesłanych plikach ani fragmentach JavaScript.
• Używaj krótkotrwałych tokenów, regularnie je rotuj i cofnij nieużywane połączenia.
• Używaj dedykowanej przestrzeni roboczej i tożsamości o minimalnych uprawnieniach dla każdej granicy zaufania.
• Rejestruj zatwierdzenia i nazwy narzędzi do audytu, ale nie rejestruj poświadczeń, przesłanych treści ani wrażliwych danych stron.

Dostępność regionalna

Playwright Workspaces jest dostępny w następujących regionach Azure:

Treści powiązane

• Zarządzanie tokenami dostępu do przestrzeni roboczej
• Zarządzaj dostępem do przestrzeni roboczej dla dramaturga
• Połącz agenty Microsoft Foundry z punktami końcowymi serwera MCP
• Dodawaj i zarządzaj serwerami MCP w Visual Studio Code
• Dokumentacja protokołu kontekstowego modelu