MCP 브라우저 운영자

LLM이 표준화된 JSON-RPC 인터페이스를 통해 웹 브라우저를 제어하고, 웹 페이지와 상호 작용하고, 웹 콘텐츠를 분석할 수 있도록 하는 브라우저 자동화를 위한 MCP(모델 제어 프로토콜) 서버입니다.

특징

• 브라우저 관리 : 브라우저 인스턴스 생성, 탐색, 작동 및 닫기
• 작업 관리 : 작업 ID를 사용하여 브라우저 작업 상태 추적
• 웹 상호작용 : OpenAI의 컴퓨터 사용 API를 사용하여 자연어 명령 실행
• 브라우저 도구 : 콘솔 로그, 네트워크 활동, 스크린샷 등에 액세스합니다.
• 감사 : 접근성, 성능, SEO 및 기타 웹 페이지 감사 실행

요구 사항

• 파이썬 3.11+
• 극작가
• OpenAI API 키(컴퓨터 사용 API용)

설치

1. 이 저장소를 복제하세요:지엑스피1
2. 종속성 설치:
   pip install -e .
3. Playwright 브라우저 설치:
   playwright install chromium
4. OpenAI API 키를 설정하세요:
   export OPENAI_API_KEY=your-api-key

용법

MCP 서버를 시작합니다.

서버는 MCP 프로토콜에 따라 stdin에서 JSON-RPC 요청을 수신하고 stdout에서 응답합니다.

실행 가능한 스크립트

• run-server - MCP 서버(주요 진입점)를 실행합니다.
  # Run the MCP server ./run-server # Run with specific log directory ./run-server --log-dir /path/to/logs # Run in debug mode ./run-server --debug
• run-tests - 모든 테스트를 실행합니다(단위 또는 통합에 대한 옵션만 있음)
  # Run all tests ./run-tests # Run only unit tests (faster) ./run-tests --unit-only # Run only integration tests ./run-tests --integration-only # Run with verbose output ./run-tests --verbose # Run a specific test ./run-tests --test TestBrowserOperatorMethods
• run-test-harness - 대화형 테스트를 위해 MCP Inspector로 서버를 실행합니다.
  # Run with the MCP Inspector for interactive testing ./run-test-harness

핵심 방법

브라우저 관리

• 브라우저 생성 : 새 브라우저 인스턴스를 초기화합니다.
  { "jsonrpc": "2.0", "id": 1, "method": "mcp__browser-operator__create-browser", "params": { "project_name": "my-project" } }
• 브라우저 탐색 : 브라우저를 지정된 URL로 이동합니다.
  { "jsonrpc": "2.0", "id": 2, "method": "mcp__browser-operator__navigate-browser", "params": { "project_name": "my-project", "url": "https://example.com" } }
• 브라우저 작동 : 브라우저 상호 작용을 위한 자연어 명령 실행
  { "jsonrpc": "2.0", "id": 3, "method": "mcp__browser-operator__operate-browser", "params": { "project_name": "my-project", "instruction": "Find the heading on this page and tell me what it says." } }
• 브라우저 닫기 : 브라우저 인스턴스 종료
  { "jsonrpc": "2.0", "id": 4, "method": "mcp__browser-operator__close-browser", "params": { "project_name": "my-project" } }

작업 관리

• 작업 상태 가져오기 : 작업 ID로 작업의 상태 및 결과를 검색합니다.
  { "jsonrpc": "2.0", "id": 5, "method": "mcp__browser-operator__get-job-status", "params": { "job_id": "job-12345" } }
• 작업 목록 : 최근 브라우저 작업 보기
  { "jsonrpc": "2.0", "id": 6, "method": "mcp__browser-operator__list-jobs", "params": { "limit": 10 } }

사용자 참고 사항

• 메모 추가 : 브라우저 작업과 관련된 메모를 생성하고 저장합니다.
  { "jsonrpc": "2.0", "id": 7, "method": "mcp__browser-operator__add-note", "params": { "name": "My Note", "content": "Important information about this browser session" } }

추가 방법

브라우저 디버깅 도구

• 콘솔 로그 가져오기 : mcp__browser-tools__getConsoleLogs
• 콘솔 오류 가져오기 : mcp__browser-tools__getConsoleErrors
• 네트워크 로그 가져오기 : mcp__browser-tools__getNetworkLogs
• 네트워크 오류 가져오기 : mcp__browser-tools__getNetworkErrors
• 스크린샷 찍기 : mcp__browser-tools__takeScreenshot
• 선택한 요소 가져오기 : mcp__browser-tools__getSelectedElement
• 로그 삭제 : mcp__browser-tools__wipeLogs

감사 도구

• 접근성 감사 실행 : mcp__browser-tools__runAccessibilityAudit
• 성능 감사 실행 : mcp__browser-tools__runPerformanceAudit
• SEO 감사 실행 : mcp__browser-tools__runSEOAudit
• NextJS 감사 실행 : mcp__browser-tools__runNextJSAudit
• 모범 사례 감사 실행 : mcp__browser-tools__runBestPracticesAudit
• 디버거 모드 실행 : mcp__browser-tools__runDebuggerMode
• 감사 모드 실행 : mcp__browser-tools__runAuditMode

비동기 워크플로 패턴

브라우저 작업은 비동기적이며 작업 기반 접근 방식을 사용합니다.

1. 작업 시작 : job_id를 반환하는 브라우저 메서드를 호출합니다.
2. 완료를 위한 투표 : 작업이 완료될 때까지 get-job-status를 사용하세요.
3. 프로세스 결과 : 작업이 완료되면 작업 상태에서 결과에 액세스합니다.

이 접근 방식은 복잡한 브라우저 작업을 완료하는 동시에 클라이언트 시간 초과를 방지합니다.

지속적인 브라우저 상태

MCP 운영자는 프로젝트 이름으로 브라우저가 생성될 때 영구 상태를 유지합니다.

• 브라우저 상태(쿠키, 로컬 스토리지, 세션 스토리지)는 세션 간에 보존됩니다.
• 여러 프로젝트가 독립적인 브라우저 상태를 유지할 수 있습니다.
• 로그인 세션, 쇼핑 카트 또는 기타 개인화된 상태를 유지하는 데 유용합니다.

프로젝트 구조

• src/mcp_operator/ : 메인 패키지
  • __init__.py : 패키지 초기화
  • __main__.py : 패키지의 진입점
  • server.py : MCP 서버 구현
  • browser.py : 브라우저 연산자 구현
  • cua/ : 컴퓨터 사용 API 구성 요소
    • agent.py : 에이전트 구현
    • computer.py : 컴퓨터 인터페이스
    • utils.py : 유틸리티 함수
• run-server : MCP 서버를 실행하는 스크립트
• run-tests : 단위 및 통합 테스트를 실행하는 스크립트
• run-test-harness : MCP Inspector로 실행할 스크립트

개발

MCP Inspector 사용

디버깅을 위해 MCP Inspector를 사용하세요.

이는 MCP 서버를 테스트하기 위한 웹 인터페이스를 제공합니다.

보안

• 잠재적으로 유해한 사이트에 대한 도메인 차단
• 탐색 전 URL 검증
• 다양한 브라우저 인스턴스 간 세션 격리
• 파일 기반 로깅(MCP 프로토콜을 보존하기 위한 stdout 없음)