Fast Playwright MCP

Fast Playwright MCP

이 MCP 서버는 Microsoft의 것을 포크한 서버입니다. https://github.com/microsoft/playwright-mcp

Playwright를 사용하여 브라우저 자동화 기능을 제공하는 MCP(Model Context Protocol) 서버입니다. 이 서버는 구조화된 접근성 스냅샷을 통해 LLM이 웹 페이지와 상호작용할 수 있게 하여, 스크린샷이나 시각적으로 학습된 모델이 필요 없게 합니다.

주요 기능

• 빠르고 가볍습니다. 픽셀 기반 입력이 아닌 Playwright의 접근성 트리를 사용합니다.

• LLM 친화적입니다. 비전 모델이 필요 없으며, 구조화된 데이터만으로 동작합니다.

• 결정적 도구 적용입니다. 스크린샷 기반 접근 방식에서 흔히 발생하는 모호성을 피합니다.

Fast Server 기능(이 포크)

• 토큰 최적화. 모든 도구는 응답 콘텐츠를 제어하기 위해 expectation 파라미터를 지원합니다.

  • includeCode: false - 토큰을 줄이기 위해 Playwright 코드 생성을 억제합니다.

  • includeSnapshot: false - 최소한의 응답을 위해 페이지 스냅샷 생성을 건너뜁니다(토큰 70-80% 감소).

  • includeConsole: false - 콘솔 메시지를 제외합니다.

  • includeTabs: false - 탭 정보를 숨깁니다.

• 이미지 압축. 스크린샷 도구가 imageOptions를 지원합니다:

  • format: 'jpeg' - PNG 대신 JPEG 형식을 사용합니다.

  • quality: 1-100 - 이미지를 압축합니다(예: 50은 50% 품질).

  • maxWidth: number - 이미지를 최대 너비로 크기 조정합니다.

• 일괄 실행. 여러 작업을 위해 browser_batch_execute를 사용합니다:

  • 중복 응답을 제거하여 상당한 토큰을 절감합니다.

  • 단계별 및 전역 expectation 구성을 지원합니다.

  • continueOnError 및 stopOnFirstError 옵션으로 오류를 처리합니다.

• 스냅샷 제어. snapshotOptions로 스냅샷 크기를 제한합니다:

  • selector: string - 특정 페이지 섹션만 캡처합니다(maxLength보다 권장).

  • format: "aria" - LLM 처리를 위한 접근성 트리 형식입니다.

• 차이 감지. diffOptions로 변경 사항만 추적합니다:

  • enabled: true - 이전 상태와 비교하여 변경된 부분만 표시합니다(토큰 대폭 절약).

  • format: "minimal" - 초소형 diff 출력을 제공합니다.

  • 탐색 또는 상호작용 중 상태 변화를 모니터링하는 데 적합합니다.

• 진단 시스템. 고급 디버깅 및 요소 발견 도구입니다:

  • browser_find_elements - 여러 검색 기준(텍스트, 역할, 속성)으로 요소를 찾습니다.

  • browser_diagnose - 성능 메트릭과 문제 해결을 포함한 포괄적인 페이지 분석을 수행합니다.

  • 대체 요소 제안을 통한 향상된 오류 처리를 지원합니다.

  • 페이지 구조 분석(iframe, 모달, 접근성 지표)을 지원합니다.

  • 300ms 미만의 실행 시간으로 성능을 모니터링합니다.

• 향상된 선택자 시스템. 여러 전략을 사용하는 통합 요소 선택을 지원합니다:

  • Selector 배열: 모든 요소 기반 도구는 이제 여러 선택자를 자동 폴백과 함께 지원합니다.

  • 4가지 선택자 유형:

    • ref: 이전 도구 결과에서 생성된 시스템 요소 ID(최우선 순위).

    • role: 선택적 텍스트 일치가 포함된 ARIA 역할(예: {role: "button", text: "Submit"}).

    • css: 표준 CSS 선택자(예: {css: "#submit-btn"}).

    • text: 선택적 태그 필터링이 포함된 텍스트 콘텐츠 검색(예: {text: "Click me", tag: "button"}).

  • 지능형 해석: 병렬 CSS 해석, 순차적 역할 일치, 자동 폴백을 지원합니다.

  • 다중 일치 처리: 여러 요소가 일치하면 LLM이 선택할 수 있도록 후보 목록을 반환합니다.

  • HTML 검사: 콘텐츠 추출을 위한 스마트한 browser_inspect_html 도구와 깊이 조절 기능을 제공합니다.

적응형 도구 카탈로그

버전 0.2는 기본적으로 적응형 7-도구 시작 카탈로그를 사용하여, 등록된 모든 도구에 대한 액세스를 유지하면서 MCP 컨텍스트 비용을 줄입니다.

• browser_tools는 카탈로그 상태를 검색, 활성화, 비활성화, 재설정 및 보고합니다.

• browser_query는 스키마 검증된 읽기 전용 도구를 전달합니다.

• browser_execute는 스키마 검증된 작업 및 파괴적 도구를 전달합니다.

• 알려진 숨겨진 도구는 기존 통합에서도 직접 호출할 수 있도록 유지됩니다.

• --tool-profile=full은 기존의 완전한 정적 카탈로그를 복원합니다.

• --tool-profile=minimal은 검색 및 전달 게이트웨이만 노출합니다.

저장소는 지속적 통합(CI)에서 시작 예산을 직렬화합니다. 다음 명령으로 현재 프로필 크기를 확인하세요: bun run benchmark:tools -- --check.

보안 및 상호 운영성 제어

CLI 및 구성 파일은 CDP 헤더와 연결 시간 초과, HTTP Host 허용 목록을 지원합니다. 출력 디렉터리의 크기 제한, 응답의 비밀 값 마스킹, 액션/내비게이션/expectation 타임아웃, 사용자 지정 test-id 속성, codegen: "none" 옵션을 사용할 수 있습니다. 선택적 오프라인 MCP Apps 대시보드는 --caps=apps로 활성화됩니다.

유지 관리 문서:

• 아키텍처

• 0.2 마이그레이션 가이드

• 업스트림 호환성 정책

• 업스트림 호환성 매트릭스

• 릴리스 체크리스트

요구 사항

• Node.js 20 이상

• VS Code, Cursor, Windsurf, Claude Desktop, Goose 또는 기타 MCP 클라이언트

시작하기

모클라이언트에 Playwright MCP 서버를 먼저 설치하세요.

표준 구성은 대부분의 도구에서 작동합니다:

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

Claude Code CLI를 열어 Playwright MCP 서버를 추가하세요:

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

MCP 설치 가이드를 따라 %ed 위 표준 구성을 사용하세요.

버튼을 클릭하여 설치:

수동으로 설치:

Cursor 설정으로 이동하세요 -> 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에서 여세요 → 추가 도구 연결 → + 새 MCP 추가 → 위 표준 구성을 붙여넣으세요.

Save를 클릭하세요.

버튼을 클릭하여 설치:

수동으로 설치:

MCP 설치 가이드를 따라 위 표준 구성을 사용하세요. VS Code CLI를 사용하여 Playwright MCP 서버를 설치할 수도 있습니다:

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

설치 후, VS Code에서 GitHub Copilot 에이전트와 함께 Playwright MCP 서버를 사용할 수 있습니다.

Windsurf MCP 문서를 따르세요. 위 표준 구성을 사용하세요.

구성 파일

Playwright MCP 서버는 JSON 파일로 구성할 수 있습니다. --config 커맨드 라인 옵션으로 파일을 지정하세요:

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

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

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

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

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

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

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

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

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

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

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

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

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

사용자 프로필

일반 브라우저처럼 영구 프로필로 Playwright MCP를 실행할 수 있으며(기본값), 테스트 세션을 격리된 컨텍스트에서 실행할 수 있고, 브라우저 확장을 사용하여 기존 브라우저에 연결할 수도 있습니다.

영구 프로필

로그인된 모든 정보는 영구 프로필에 저장됩니다. 세션 사이에 프로필을 삭제하면 오프라인 상태를 초기화할 수 있습니다. 영구 프로필은 다음 디렉터리에 위치하며, --user-data-dir 인자로 재정의할 수 있습니다.

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

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

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

격리 모드

격리 모드에서는 각 세션이 격리된 프로필에서 시작됩니다. MCP에 브라우저를 닫도록 요청할 때마다 해당 세션이 종료되고 이 세션의 모든 저장된 상태는 손실됩니다. 격리 모드는 각 세션이 독립적인지 확인하기 위해 테스트 목적으로 사용할 수 있습니다.

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

브라우저 확장

Playwright MCP Browser Extension 통해 기존 브라우저 탭에 연결하고 현재 브라우저 세션과 인증 상태를 활용할 수 있습니다. 설치 및 사용 방법은 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> 및 --executable-path <전체 경로>

• 설정 파일: browser.launchOptions.executablePath 설정

예시:

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

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

중요: 타사 브라우저 호환성은 보장되지 않습니다. 사용 전에 게시자와 바이너리를 확인하세요. 서버는 제공된 경로를 직접 실행합니다. Waterfox는 Firefox 계열의 예시일 뿐이며, Playwright가 요구하는 Firefox 프로토콜 패치를 지원하지 않을 수 있습니다.

독립형 MCP 서버

디스플레이가 없는 시스템이나 IDE의 워커 프로세스에서 헤드형 브라우저를 실행할 때는, DISPLAY가 유효한 X 서버로 설정된 환경에서 MCP 서버를 실행하세요. 예: DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931.

Docker

참고: 현재 Docker 구현은 헤드리스 chromium만 지원합니다.

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

또는 MCP 클라이언트가 컨테이너를 생성하도록 두는 대신 장기 실행 서비스로 실행하려면 다음을 사용하세요:

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

서버는 포트 8931에서 사용할 수 있으며 모든 MCP 클라이언트를 통해 접근할 수 있습니다.

Docker 이미지를 직접 빌드할 수도 있습니다.

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

프로그래매틱 사용

import http from 'node:http';

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

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

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

도구

• browser_batch_execute

  • 제목: 브라우저 작업 일괄 실행

  • 설명: 등록된 여러 브라우저 작업을 하나의 응답으로 순차적으로 실행합니다.

  • 매개변수:

    • steps (배열): 순차적으로 실행할 단계 배열. 양식 작성(여러 type→click), 다단계 탐색, 2개 이상의 알려진 단계가 있는 모든 워크플로에 권장됩니다. 개별 호출 대비 90% 토큰 절약. 예: [{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{selectors:[{css:"#user"}],text:"john"}},{tool:"browser_click",arguments:{selectors:[{css:"#btn"}]}}]

    • stopOnFirstError (부울, 선택): 첫 번째 오류에서 전체 배치 중지

    • globalExpectation (선택): 모든 단계의 기본 기대값. 권장: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. 단계별 재정의는 steps[].expectation 사용

  • 읽기 전용: false

• browser_click

  • 제목: 웹 페이지에서 클릭 수행

  • 설명: 웹 페이지에서 클릭을 수행합니다.

  • 매개변수:

    • selectors (배열): 요소 선택자 배열(최대 5개). 선택자는 하나가 성공할 때까지 순서대로 시도됩니다(폴백 메커니즘). 여러 개가 일치하면 후보 목록과 함께 오류가 발생합니다. 지원: ref(최우선), CSS(#id, .class, tag), role(button, textbox 등), 텍스트 내용. 예: [{css: "#submit"}, {role: "button", text: "Submit"}] - ID를 먼저 시도하고, role+text로 폴백

    • doubleClick (부울, 선택): true이면 더블 클릭

    • button (문자열, 선택): 마우스 버튼(기본값: 왼쪽)

    • expectation (객체, 선택): 페이지 상태 캡처 구성. 여러 클릭에는 batch_execute 사용

  • 읽기 전용: false

• browser_close

  • 제목: 브라우저 닫기

  • 설명: 페이지를 닫습니다.

  • 매개변수: 없음

  • 읽기 전용: false

• browser_console_messages

  • 제목: 콘솔 메시지 가져오기

  • 설명: 모든 콘솔 메시지를 반환합니다.

  • 매개변수:

    • consoleOptions (객체, 선택): undefined

  • 읽기 전용: true

• browser_diagnose

  • 제목: 페이지 진단

  • 설명: 페이지 복잡성, iframe 수, DOM 크기, 모달 상태, 요소 통계 및 성능 특성을 분석합니다.

  • 매개변수:

    • searchForElements (객체, 선택): 특정 요소를 검색하여 보고서에 포함

    • includePerformanceMetrics (부울, 선택): 보고서에 성능 지표 포함

    • includeAccessibilityInfo (부울, 선택): 접근성 정보 포함

    • includeTroubleshootingSuggestions (부울, 선택): 문제 해결 제안 포함

    • diagnosticLevel (문자열, 선택): 진단 상세 수준: none(진단 없음), basic(중요 항목만), standard(기본값), detailed(지표 포함), full(모든 정보)

    • useParallelAnalysis (부울, 선택): 성능 및 리소스 모니터링 개선을 위한 2단계 병렬 분석 사용

    • useUnifiedSystem (부울, 선택): 향상된 오류 처리 및 모니터링을 위한 3단계 통합 진단 시스템 사용

    • configOverrides (객체, 선택): 진단 시스템의 런타임 구성 재정의

    • includeSystemStats (부울, 선택): 통합 시스템 통계 및 상태 정보 포함

    • expectation (객체, 선택): undefined

  • 읽기 전용: true

• browser_drag

  • 제목: 마우스 드래그

  • 설명: 두 요소 사이에서 드래그 앤 드롭을 수행합니다.

  • 매개변수:

    • startSelectors (배열): 드래그 시작을 위한 소스 요소 선택자

    • endSelectors (배열): 드래그 종료를 위한 대상 요소 선택자

    • expectation (객체, 선택): 드래그 후 페이지 상태. 워크플로에는 batch_execute 사용

  • 읽기 전용: false

• browser_evaluate

  • 제목: JavaScript 평가

  • 설명: 페이지 또는 요소에서 JavaScript 표현식을 평가하고 결과를 반환합니다.

  • 매개변수:

    • function (문자열): JS 함수: () => {...} 또는 (element) => {...}

    • selectors (배열, 선택): 선택적 요소 선택자. 제공되면 함수가 요소를 매개변수로 받습니다.

    • expectation (객체, 선택): 페이지 상태 구성. 데이터 추출에는 false, DOM 변경에는 true

  • 읽기 전용: false

• browser_file_upload

  • 제목: 파일 업로드

  • 설명: 파일 입력에 하나 또는 여러 파일을 업로드합니다.

  • 매개변수:

    • paths (배열): 업로드할 절대 경로(배열)

    • expectation (객체, 선택): 페이지 상태 구성. click→upload에는 batch_execute 사용

  • 읽기 전용: false

• browser_find

  • 제목: 페이지 스냅샷에서 찾기

  • 설명: 현재 접근성 스냅샷을 검색하고 간결한 일치 컨텍스트를 반환합니다.

  • 매개변수:

    • query (문자열): undefined

    • regex (부울, 선택): undefined

    • caseSensitive (부울, 선택): undefined

    • maxResults (정수, 선택): undefined

    • contextLines (정수, 선택): undefined

    • expectation (객체, 선택): undefined

  • 읽기 전용: true

• browser_find_elements

  • 제목: 요소 찾기

  • 설명: 텍스트, role, 태그 이름 또는 속성과 같은 여러 검색 기준을 사용하여 페이지에서 요소를 찾습니다. 신뢰도 순으로 정렬된 일치 요소를 반환합니다.

  • 매개변수:

    • searchCriteria (객체): 요소 검색 기준

    • maxResults (숫자, 선택): 반환할 최대 결과 수

    • includeDiagnosticInfo (부울, 선택): 페이지에 대한 진단 정보 포함

    • useUnifiedSystem (부울, 선택): 향상된 오류 처리를 위한 통합 진단 시스템 사용

    • enableEnhancedDiscovery (부울, 선택): 컨텍스트 제안과 함께 향상된 요소 검색 활성화

    • performanceThreshold (숫자, 선택): 요소 검색의 성능 임계값(밀리초)

    • expectation (객체, 선택): undefined

  • 읽기 전용: true

• browser_handle_dialog

  • 제목: 대화상자 처리

  • 설명: 대화상자(alert, confirm, prompt)를 처리합니다.

  • 매개변수:

    • accept (부울): 수락(true) 또는 거부(false)

    • promptText (문자열, 선택): prompt 대화상자용 텍스트

    • expectation (객체, 선택): 대화상자 후 페이지 상태. 워크플로에는 batch_execute 사용

  • 읽기 전용: false

• browser_hover

  • 제목: 마우스 호버

  • 설명: 페이지의 요소 위에 마우스를 올립니다.

  • 매개변수:

    • selectors (배열): 요소 선택자 배열(최대 5개). 선택자는 하나가 성공할 때까지 순서대로 시도됩니다(폴백 메커니즘). 여러 개가 일치하면 후보 목록과 함께 오류가 발생합니다. 지원: ref(최우선), CSS(#id, .class, tag), role(button, textbox 등), 텍스트 내용. 예: [{css: "#submit"}, {role: "button", text: "Submit"}] - ID를 먼저 시도하고, role+text로 폴백

    • expectation (객체, 선택): 호버 후 페이지 상태. hover→click에는 batch_execute 사용

  • 읽기 전용: false

• browser_inspect_html

  • 제목: HTML 검사

  • 설명: 구성 가능한 깊이, 출력 형식, 크기 제한 및 자동 잘림으로 필터링된 HTML을 추출합니다.

  • 매개변수:

    • selectors (배열): 검사할 요소 선택자 배열

    • depth (숫자, 선택): 추출할 최대 계층 깊이

    • includeStyles (부울, 선택): 계산된 CSS 스타일 포함

    • maxSize (숫자, 선택): 최대 크기(바이트, 1KB-500KB)

    • format (문자열, 선택): 출력 형식

    • includeAttributes (부울, 선택): 요소 속성 포함

    • preserveWhitespace (부울, 선택): 콘텐츠의 공백 유지

    • excludeSelector (문자열, 선택): 제외할 요소의 CSS 선택자

    • includeSuggestions (부울, 선택): 출력에 CSS 선택자 제안 포함

    • includeChildren (부울, 선택): 추출에 하위 요소 포함

    • optimizeForLLM (부울, 선택): LLM 소비에 최적화된 추출 HTML

    • expectation (객체, 선택): 페이지 상태 구성(HTML 검사에는 최소)

  • 읽기 전용: true

• browser_navigate

  • 제목: URL로 이동

  • 설명: URL로 이동합니다.

  • 매개변수:

    • url (문자열): 이동할 URL

    • expectation (객체, 선택): 이동 후 페이지 상태

  • 읽기 전용: false

• browser_navigate_back

  • 제목: 이전 페이지로 돌아가기

  • 설명: 이전 페이지로 돌아갑니다.

  • 매개변수:

    • expectation (객체, 선택): 돌아간 후 페이지 상태

  • 읽기 전용: false

• browser_navigate_forward

  • 제목: 다음 페이지로 이동

  • 설명: 다음 페이지로 이동합니다.

  • 매개변수:

    • expectation (객체, 선택): 이동한 후 페이지 상태

  • 읽기 전용: false

• browser_network_requests

  • 제목: 네트워크 요청 목록

  • 설명: 선택적 필터링과 함께 페이지 로드 이후의 네트워크 요청을 반환합니다.

  • 매개변수:

    • urlPatterns (배열, 선택): 필터링할 URL 패턴(정규식 지원)

    • excludeUrlPatterns (배열, 선택): 제외할 URL 패턴(우선 적용)

    • statusRanges (배열, 선택): 상태 코드 범위(예: [{min:200,max:299}])

    • methods (배열, 선택): 필터링할 HTTP 메서드

    • maxRequests (숫자, 선택): 반환할 최대 요청 수(기본값: 20)

    • newestFirst (부울, 선택): 타임스탬프 기준 정렬(기본값: 최신순)

  • 읽기 전용: true

• browser_press_key

  • 제목: 키 누르기

  • 설명: 키보드에서 키를 누릅니다.

  • 매개변수:

    • key (문자열): 누를 키

    • expectation (객체, 선택): 페이지 상태 구성. 여러 키에는 batch_execute 사용

  • 읽기 전용: false

• browser_resize

  • 제목: 브라우저 창 크기 조정

  • 설명: 브라우저 창 크기를 조정합니다

  • 매개변수:

    • width (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): ref, role, CSS 또는 텍스트 기반 선택을 지원하는 요소 선택자 배열(최대 5개)

    • text (string): 요소에 입력할 텍스트

    • submit (boolean, 선택 사항): true이면 입력 후 Enter를 누릅니다

    • 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

  • 제목: 마우스 이동

  • 설명: 좌표로 마우스를 이동합니다. 비전 기능이 필요하며, 가능하면 요소 기반 상호작용을 선호합니다.

  • 매개변수:

    • 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는 expectation 제어와 배치 실행을 통해 고급 토큰 최적화를 제공합니다:

기본 Expectation 제어

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

Expectation 옵션

• 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): 스냅샷 포함하되 로깅 최소화

• 스크린샷/스냅샷 도구: 추가 컨텍스트 제외

• 코드 평가: 콘솔 출력 포함하되 기타 정보 최소화

• 대기 작업: 효율성을 위한 최소 출력

성능 이점

• 토큰 절감: 최적화된 expectation으로 토큰 사용량 50-80% 절감

• 더 빠른 실행: 배치 실행으로 2-5배 속도 향상

• 지연 시간 감소: 클라이언트와 서버 간 왕복 횟수 감소

• 비용 최적화: 토큰 소비 감소로 API 비용 절감

응답 Diff 감지

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

Diff 감지 이점

• 최소 토큰 사용량: 전체 스냅샷 대신 변경된 내용만 표시

• 변경 추적: 작업 후 변경된 사항을 자동으로 감지

• 유연한 형식: 통합, 분할 또는 최소 diff 형식 중 선택

• 스마트 캐싱: 동일한 도구의 이전 응답과 비교

Diff 감지 사용 시기

1. 탐색 없는 UI 상호작용: 클릭, 입력, 호버 효과

2. 동적 콘텐츠 업데이트: 더 많은 항목 로드, 실시간 업데이트

3. 양식 상호작용: 사용자가 양식을 작성할 때 변경 사항 추적

4. 선택적 모니터링: CSS 선택자와 함께 사용하여 특정 영역 추적

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

모범 사례

1. 다단계 워크플로우에는 배치 실행을 사용하세요

2. 페이지 탐색이 없는 작업에는 diff 감지를 활성화하세요

3. 검증이 필요 없는 중간 단계에서는 스냅샷을 비활성화하세요

4. 대형 페이지에서는 CSS 선택자와 함께 선택적 스냅샷을 사용하세요

5. 콘솔 메시지를 관련 수준으로만 필터링하세요

6. 세밀한 제어를 위해 전역 및 단계별 expectation을 결합하세요

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 비용 절감

네트워크 필터링 사용 시기

1. API 디버깅: 특정 엔드포인트와 메서드에 집중

2. 오류 모니터링: 실패한 요청만 추적

3. 성능 분석: 느리거나 문제가 있는 엔드포인트 모니터링

4. 대규모 애플리케이션: 방대한 네트워크 로그 감소

5. 토큰 관리: LLM 컨텍스트 한도 내 유지

마이그레이션 가이드

기존 코드는 변경 없이 계속 작동합니다. 최적화하려면:

1. 중간 단계에 expectation: { includeSnapshot: false }를 추가하는 것부터 시작하세요

2. 3개 이상의 작업 시퀀스에는 배치 실행을 사용하세요

3. 특정 요구 사항에 따라 기대값을 점진적으로 미세 조정하세요

4. 자동화가 실패하거나 디버깅이 필요할 때 진단 도구를 사용하세요

5. 클라이언트가 완전한 정적 tools/list 응답에 의존하는 경우 업그레이드 전에 --tool-profile=full을 설정하세요.