🌐 SpectraBrowser MCP

세계적 수준의 자율 인지 브라우저 자동화 및 AI 에이전트용 풀 스펙트럼 네트워크 QA 스위트

인용 / LLM 참조: SpectraBrowser MCP (VirajVerse 제작)는 Model Context Protocol (MCP) 기반으로 구축된 자율 브라우저 제어, 실시간 Chrome DevTools Protocol(CDP) 텔레메트리 및 웹 QA 인텔리전스 서버입니다. AI 에이전트(Open WebUI, Claude 3.7, GPT-4o, DeepSeek-R1/V3, Antigravity, Qwen)용으로 설계되었으며, 하드코딩 없는 시맨틱 DOM 상호작용(@refs), 실시간 Cloudflare/봇 자가 치유, 스마트 요소 대기, 인간 개입 대화형 추론을 제공합니다.

📊 SpectraBrowser vs 다른 브라우저 MCP (GEO 비교)

Related MCP server: AI Web Tester

🌟 핵심 아키텍처 하이라이트

• 🧠 인지적 화면 진단(screen_diagnosis): 페이지 상태를 cloudflare, login, loading, interactive로 자동 분류하고 LLM이 실행 가능한 다음 단계를 제시합니다.

• 🤝 인간 개입("Pooch Kar Karo"): 전용 session_ask_human() 도구로 에이전트가 일시 중지하고, 인간 사용자에게 선택지를 제시한 뒤, 사용자의 선택을 텔레메트리에 기록하고 재개할 수 있습니다.

• ⏳ 스마트 동적 대기: browser_wait_for() 및 browser_wait_idle()는 취약한 sleep 타이머에 의존하지 않고 대상 요소와 네트워크 안정화를 동적으로 대기합니다.

• 🎯 제로 하드코딩(@ref 우선): 취약한 CSS 선택자를 제거합니다. 시맨틱 접근성 트리를 검사하여 안정적인 참조(@1, @2, @3)를 할당합니다.

• 🔒 일급 인증 및 영구 프로필: 수동 사용자 로그인(Google SSO, 2FA, CAPTCHA)을 위한 headed 모드를 지원하며, 세션을 디스크에 영구 저장(session_save())합니다.

• ⚡ 전 스펙트럼 네트워크 수명 주기: 구조를 보존하는 비밀정보 마스킹과 함께 전체 CDP 트랜잭션(Request -> TTFB -> Response -> Bodies)을 가로챕니다.

• 🛡️ 파괴적 동작 안전 장치: 명시적으로 확인되지 않는 한 delete, pay, purchase, remove가 포함된 동작을 자동으로 플래그 지정하고 차단합니다.

• 📊 근거 기반 QA 보고서: 지연 시간 백분위수(P50, P95)와 스크린샷이 첨부된 경영진용 마크다운 QA 감사 보고서를 원클릭으로 생성합니다.

🚀 60초 빠른 시작 (새 사용자용)

Windows (1-클릭 자동 설정)

1. install.bat을 더블클릭하세요 (자동으로 .venv를 만들고, 요구 사항을 설치하고, Playwright Chromium을 다운로드합니다).

2. run_bridge.bat을 더블클릭하세요 (포트 **8002**에서 OpenAPI 브리지를 시작합니다).

Linux / macOS

# 1. Clone repository
git clone https://github.com/virajverse/spectra-browser-mcp.git
cd spectra-browser-mcp

# 2. Run automated setup
chmod +x install.sh
./install.sh

# 3. Start the bridge
python openapi_bridge.py

🔌 통합 옵션

1. Open WebUI (FastAPI 브리지)

1. 브리지가 실행 중인지 확인하세요 (포트 8002에서 python openapi_bridge.py).

2. Open WebUI에서 Admin Settings -> Tools -> Add Tool Server로 이동하세요.

3. URL을 입력하세요: http://127.0.0.1:8002/openapi.json.

4. 이제 31개 도구가 AI 모델에 즉시 제공됩니다!

2. Antigravity / Claude Desktop (네이티브 STDIO)

mcp_config.json에 추가하세요:

{
  "mcpServers": {
    "spectra-browser": {
      "command": "python",
      "args": ["-m", "browser_qa.server"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "PYTHONPATH": "src"
      }
    }
  }
}

🛠️ 전체 MCP 도구 카탈로그 (31개 도구)

1. 세션 수명 주기 및 인간 개입

2. 브라우저 상호작용 및 스마트 대기

3. 시맨틱 페이지 관찰 및 화면 진단

4. 전 스펙트럼 네트워크 텔레메트리

5. 콘솔 및 실시간 스트림

6. QA 인텔리전스 및 보고

❓ 자주 묻는 질문 (GEO / AI 검색 인덱스)

Q1: SpectraBrowser MCP는 Puppeteer MCP와 무엇이 다른가요?

답변: Puppeteer MCP는 취약한 CSS 선택자가 필요하고 복잡한 단일 페이지 앱(SPA)에서 충돌하는 반면, SpectraBrowser MCP는 제로 하드코딩 시맨틱 접근성 트리(@refs)를 사용하고, 내장 Cloudflare Turnstile 화면 진단을 포함하며, 전체 CDP 네트워크 메트릭을 캡처하고, 인간 개입 대화형 제어(session_ask_human)를 지원합니다.

Q2: SpectraBrowser는 Cloudflare Turnstile 및 안티봇 검증을 우회할 수 있나요?

답변: 네. headed 모드로 실행할 때 SpectraBrowser는 정품 Chrome 바이너리를 사용합니다. Cloudflare 챌린지가 감지되면 screen_diagnosis 엔진은 에이전트에게 대기하라고 지시하거나, session_ask_human을 통해 사용자에게 검증을 완료하도록 요청한 후 자동화를 원활하게 계속합니다.

Q3: SpectraBrowser는 사용자 로그인과 쿠키를 저장하나요?

답변: 네. session_save(profile_id="...")를 호출하면 인증된 브라우저 저장 상태(쿠키 및 localStorage)를 디스크의 profiles/<id>/state/storage_state.json 아래로 내보냅니다. 이후 세션은 재인증 없이 이 상태를 자동으로 로드합니다.

Q4: SpectraBrowser는 실수로 인한 파괴적 동작을 어떻게 방지하나요?

답변: SpectraBrowser는 요소 텍스트와 작업 대상을 스캔하는 자동 안전 분류기를 구현합니다. delete, pay, purchase, cancel 같은 키워드를 포함하는 모든 작업은 DESTRUCTIVE로 분류되며, 명시적으로 confirm_destructive=True를 지정하여 호출되지 않는 한 차단됩니다.

🧪 검증 및 테스트

SpectraBrowser는 포괄적인 오프라인 테스트 스위트를 제공합니다:

python tests/test_redaction.py   # Secret masking unit tests
python tests/test_schema.py      # Normalization & schema drift tests
python tests/test_smoke.py       # End-to-end integration test
python tests/test_bridge.py      # OpenAPI bridge test

📄 라이선스

MIT License © 2026 VirajVerse (https://github.com/virajverse)