obscura-mcp

Obscura 브라우저를 Claude Desktop 도구로 연결하는 MCP 서버.
"이 URL 스크린샷 찍어줘", "페이지 내용 요약해줘" 같은 명령을 Claude가 직접 실행합니다.
스텔스 모드 우회 성능을 정량적으로 측정하는 프로브 CLI도 내장되어 있습니다.

기능

| 도구 | 설명 | |------|------| | screenshot | URL 페이지를 PNG 스크린샷으로 반환 | | fetch_markdown | 페이지 본문을 Markdown으로 변환해 반환 | | probe_stealth | 스텔스/일반 모드를 비교해 봇 감지 우회율 측정 |

요구 사항

• Rust 1.85 이상
• Obscura 설치 (obscura.exe 경로 필요)

설치

git clone https://github.com/your-org/obscura-mcp
cd obscura-mcp
cargo build --release

빌드 결과물: target/release/obscura-mcp.exe

Claude Desktop 연동

%APPDATA%\Claude\claude_desktop_config.json 에 추가합니다.

{
  "mcpServers": {
    "obscura": {
      "command": "C:/path/to/obscura-mcp.exe",
      "env": {
        "OBSCURA_PATH": "C:/obscura/obscura.exe"
      }
    }
  }
}

Claude Desktop을 재시작하면 망치 아이콘에서 screenshot, fetch_markdown, probe_stealth 도구를 확인할 수 있습니다.

사용 예시

"https://example.com 스크린샷 찍어줘"
"https://news.ycombinator.com 페이지 내용 마크다운으로 요약해줘"
"https://example.com 스텔스 모드 우회 테스트해줘"

프로브 CLI

MCP 서버 없이 커맨드라인에서 직접 우회 성능을 측정합니다.

# 기본 (Markdown 리포트)
obscura-mcp probe https://example.com https://target.com

# 병렬 4개 동시 실행
obscura-mcp probe --concurrency 4 https://site1.com https://site2.com

# JSON 출력
obscura-mcp probe --format json https://example.com

# CI 모드: pass_rate < 90% 이면 exit code 1
obscura-mcp probe --threshold 90 --format markdown https://example.com

Obscura 경로 지정

# 플래그
obscura-mcp --obscura-path "C:\obscura\obscura.exe" probe https://example.com

# 환경 변수
set OBSCURA_PATH=C:\obscura\obscura.exe
obscura-mcp probe https://example.com

리포트 출력 예시

# Obscura Stealth Detection Report

**pass_rate: 92.0%** (23/25 passed)

| URL | Stealth | Normal | HTTP | Webdriver | Improvement |
|-----|---------|--------|------|-----------|-------------|
| https://example.com | PASS | BLOCK | 200 | hidden | ✓ |
| https://target.com  | PASS | PASS  | 200 | hidden |   |

아키텍처

main.rs
├── mcp.rs        MCP JSON-RPC stdio 서버 (Claude Desktop 연결점)
├── obscura.rs    ObscuraHandle — CDP WebSocket 세션 관리
├── judge.rs      JudgeResult — HTTP 상태·차단 키워드·webdriver 판정
├── probe.rs      probe_url — 스텔스/일반 순차 비교
├── runner.rs     run_parallel — Semaphore 기반 병렬 실행
└── report.rs     Report — JSON / Markdown / HTML 출력, CI exit code

판정 신호 (judge.rs)

프로브는 세 가지 신호를 조합해 차단 여부를 판정합니다.

| 신호 | 방법 | |------|------| | HTTP 상태 코드 | Navigation Timing API (performance.getEntriesByType) | | 차단 키워드 | HTML 전체에서 "Access Denied", "cf-challenge" 등 검색 | | navigator.webdriver | Runtime.evaluate 로 JS 직접 평가 |

GitHub Actions 연동

- name: Stealth probe
  run: |
    obscura-mcp probe \
      --concurrency 4 \
      --threshold 80 \
      --format markdown \
      https://example.com >> $GITHUB_STEP_SUMMARY
  env:
    OBSCURA_PATH: /usr/local/bin/obscura

--threshold 기준 미만이면 스텝이 실패(exit code 1)하여 빌드가 중단됩니다.

라이선스

MIT