LvcidPsyche/auto-browser

Auto Browser

!Auto Browser 데모

AI 에이전트에게 실제 브라우저를 제공하되, 사람이 개입할 수 있도록 하세요.

Auto Browser는 승인된 워크플로를 위한 MCP 네이티브 브라우저 제어 플레인입니다. MCP 클라이언트, LLM 에이전트, 운영자에게 공유 Playwright 브라우저를 제공하며, 사람의 개입, 재사용 가능한 인증 프로필, 승인, 감사 추적, 로컬 우선 배포를 지원합니다.

다음과 함께 작동합니다:

• Claude Desktop
• Cursor
• HTTP 또는 stdio를 사용할 수 있는 모든 MCP 클라이언트
• curl 기반 제어를 원할 때 직접 REST 호출자

Auto Browser를 사용하는 이유

• 처음부터 MCP 네이티브. 브라우저 표면이 사후에 추가되는 것이 아니라 이미 MCP 서버로 패키징되어 있습니다.
• 웹이 깨지기 쉬울 때 사람이 개입. noVNC는 사람이 개입해야 할 때 동일한 라이브 세션을 계속 사용할 수 있게 합니다.
• 한 번 로그인하고 나중에 재사용. 명명된 인증 프로필을 저장하고 이미 로그인된 상태로 새 세션을 다시 열 수 있습니다.
• 기본적으로 로컬 우선. Docker Compose를 사용하여 자체 시스템에서 전체 스택을 실행하거나 Codespaces를 사용하여 빠른 호스팅 데모를 실행할 수 있습니다.
• 내장된 안전 장치. 승인, 운영자 신원, PII 스크러빙, Witness 영수증, 정책 프리셋이 모두 제품 표면에 포함되어 있습니다.
• 관리되는 스킬 유도. 검증된 브라우저 추적은 서명된 출처, 검증기 어댑터, 검토 전용 졸업과 함께 단계적 스킬 후보가 될 수 있습니다. 에이전트가 한 번만 행동하는 것이 아니라 올바르게 반복할 수 있음을 증명합니다.

릴리스 하이라이트 (v1.2.1)

• PyPI에 등록. pip install auto-browser-client로 SDK, pip install auto-browser-langchain으로 LangChain/LangGraph/CrewAI 어댑터, uvx auto-browser-mcp로 제로 설정 MCP stdio 브리지를 실행할 수 있습니다. 릴리스는 태그 푸시 시 PyPI 신뢰 게시(OIDC)를 통해 게시됩니다.

v1.2.0 이후

• 검증 가능한 Witness 영수증. 영수증은 항상 쓰기 시점에 해시 체인으로 연결되었습니다. 이제 필요할 때 체인을 확인할 수 있습니다. GET /sessions/{id}/witness/verify 및 읽기 전용 browser.verify_witness MCP 도구가 전체 체인을 탐색하고 로그가 변경, 재정렬 또는 잘린 경우 첫 번째로 다른 영수증을 보고합니다.
• 더 견고한 세션 격리. 세션별 브라우저 컨테이너는 이제 메모리/PID/CPU 제한을 가지며, 컨트롤러는 시작 시 충돌로 인해 고아가 된 컨테이너를 정리합니다.
• 최신 종속성 기준. Playwright 1.60(컨트롤러와 브라우저 노드 정렬), uvicorn 0.49, 그리고 오래된 Chrome 122 시대 기본값을 대체하는 통합된 최신 사용자 에이전트 풀.
• 더 조용한 실패 모드. 이전에 오류를 삼켰던 정리 및 캡처 경로가 이제 컨텍스트와 함께 오류를 기록합니다.
• CI의 릴리스 게이트는 종속성 감사, 픽스처 평가, 클라이언트 테스트, Python 휠 빌드, 80% 컨트롤러 커버리지 게이트를 계속 적용합니다. 이제 Python 3.11 및 3.14에서 실행됩니다.

전체 릴리스 기록은 CHANGELOG.md를 참조하세요.

적합한 사용 사례

• 내부 대시보드 및 관리 도구
• 운영자 지원 QA 및 브라우저 디버깅
• 한 번 로그인하고 재사용하는 계정 워크플로
• 사람이 흐름을 복구해야 할 수 있는 깨지기 쉬운 사이트
• 실제 브라우저가 필요한 MCP 기반 에이전트 워크플로(HTML 가져오기만이 아님)

목표가 아닌 것

• CAPTCHA 해결
• 승인되지 않은 스크래핑 또는 계정 자동화
• 기만적인 신원 형성 또는 우회 도구

제공 기능

빠른 시작

git clone https://github.com/LvcidPsyche/auto-browser.git
cd auto-browser
docker compose up --build

기본 설정으로 로컬 개발에 충분합니다.

선택 사항:

cp.env.example.env
make doctor

로컬 Docker 액세스 권한과 localhost 소켓을 열 수 있는 권한이 있는 일반 터미널에서 make doctor를 실행하세요.

열기:

• API 문서: http://127.0.0.1:8000/docs
• 운영자 대시보드: http://127.0.0.1:8000/dashboard
• 시각적 개입: http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

모든 게시된 포트는 기본적으로 127.0.0.1에 바인딩됩니다.

Codespaces에서 시도하기

Codespaces는 스택을 자동으로 프로비저닝합니다. 대시보드와 noVNC 탭은 일반적으로 약 90초 안에 준비됩니다.

첫 번째 유용한 데모

이 저장소에서 가장 중요한 흐름은 다음과 같습니다:

1. 세션 생성
2. 사이트에 사람이 필요한 경우 수동으로 로그인
3. 세션을 명명된 인증 프로필로 저장
4. 해당 인증 프로필에서 새 세션 열기
5. 재인증 없이 작업 계속

여기서 시작하세요:

• examples/login-and-save-profile.md
• examples/README.md

최소 세션 생성:

curl -s http://127.0.0.1:8000/sessions \
  -X POST \
  -H 'content-type: application/json' \
  -d '{"name":"demo","start_url":"https://example.com"}' | jq

최소 관찰:

curl -s http://127.0.0.1:8000/sessions/<session-id>/observe | jq

MCP 클라이언트

Auto Browser는 다음을 노출합니다:

• http://127.0.0.1:8000/mcp의 HTTP MCP 엔드포인트
• http://127.0.0.1:8000/mcp/tools 및 http://127.0.0.1:8000/mcp/tools/call의 편의 엔드포인트
• stdio 브리지: PyPI의 uvx auto-browser-mcp 또는 저장소 체크아웃의 scripts/mcpstdiobridge.py

기본 MCP 도구 프로필은 curated로, 더 나은 도구 선택을 위해 브라우저 표면을 간결하게 유지합니다. 전체 내부 도구 표면을 원하면 다음을 설정하세요:

MCP_TOOL_PROFILE=full

원시 도구 호출 예시:

curl -s http://127.0.0.1:8000/mcp/tools/call \
  -X POST \
  -H 'content-type: application/json' \
  -d '{
    "name":"browser.create_session",
    "arguments":{
      "name":"demo",
      "start_url":"https://example.com"
    }
  }' | jq

클라이언트 설정 가이드:

• docs/mcp-clients.md
• examples/claude-desktop-setup.md
• examples/cursor-mcp-setup.md
• examples/claudedesktopconfig.json

수렴 하네스

Auto Browser는 에이전트 스킬 유도를 위한 Stage 0 수렴 하네스를 제공합니다. 구조화된 작업 계약을 실행하고, 변조 확인된 추적을 기록하며, 완료를 검증하고, 서명된 출처와 함께 단계적 스킬 후보를 작성합니다. 생성된 스킬은 단계적으로만 유지되며, 승격은 명시적이고 검토를 거칩니다.

읽기 전용 검사 도구(harness.listruns, harness.getstatus, harness.gettrace)는 기본 curated MCP 도구 프로필에 노출되어 에이전트가 상승된 액세스 없이 하네스 상태를 조사할 수 있습니다. 수렴 실행, 드리프트 검사, 후보 관리, 졸업은 MCPTOOL_PROFILE=full이 필요하거나 REST를 통해 직접 호출할 수 있습니다.

docs/convergence-harness.md에서 시작하세요. 결정론적 로컬 스모크 테스트는 다음과 같습니다:

python -m controller.harness.run --contract evals/contracts/example_read.json --mock-final-url https://example.com --mock-final-text "Example Domain"

MCP 클라이언트의 경우 MCPTOOLPROFILE=full을 설정하여 harness.* 도구를 노출하세요.

보안 및 규정 준수

실제 프라이빗 배포를 위해 최소한 다음을 설정하세요:

APP_ENV=production
API_BEARER_TOKEN=<strong-random-secret>
REQUIRE_OPERATOR_ID=true
AUTH_STATE_ENCRYPTION_KEY=<44-char-fernet-key>
REQUIRE_AUTH_STATE_ENCRYPTION=true
REQUEST_RATE_LIMIT_ENABLED=true
METRICS_ENABLED=true
STEALTH_ENABLED=false

COMPLIANCE_TEMPLATE은 시작 시 미리 구성된 상태를 적용할 수 있습니다:

두 프리셋 모두 업로드 승인이 필요하며 Witness 영수증을 활성화합니다. 시작 시 적용된 정책을 /data/compliance-manifest.json에 기록합니다. 레거시 이름(HIPAA, SOC2, GDPR, PCI-DSS)은 더 이상 사용되지 않는 별칭으로 계속 작동하며 시작 시 경고를 출력합니다.

예시:

COMPLIANCE_TEMPLATE=strict docker compose up

배포 세부 사항, 호스팅된 Witness 노트, CLI 인증 모드, 역방향 SSH 가이드는 다음을 참조하세요:

• docs/deployment.md
• docs/production-hardening.md

아키텍처 개요

flowchart LR
    User[인간 운영자] -->|감시 / 인수| noVNC[noVNC]
    LLM[OpenAI / Claude / Gemini] -->|공유 도구| Controller[컨트롤러 API]
    Controller -->|Playwright 프로토콜| Browser[브라우저 노드]
    noVNC --> Browser
    Browser --> Artifacts[(스크린샷 / 추적 / 인증 상태)]
    Controller --> Artifacts
    Controller --> Policy[허용 목록 + 승인 게이트]

핵심 구성 요소:

• browser-node/는 Chromium, Xvfb, x11vnc, noVNC를 실행합니다.
• controller/는 FastAPI 컨트롤러, MCP 전송, 정책 레일, 오케스트레이션 엔드포인트를 노출합니다.
• data/는 런타임 아티팩트, 인증 상태, 승인, 감사 로그, 선택적 CLI 캐시를 보관합니다.
• scripts/는 doctor, 스모크 테스트, 브리지, 릴리스 검사를 위한 로컬 도우미를 포함합니다.

저장소 가이드

일반 명령어

문서 맵

기여

기여를 원하시면 다음을 시작하세요:

• CONTRIBUTING.md
• docs/good-first-issues.md
• CODEOFCONDUCT.md

Auto Browser가 유용하다면, 별표를 눌러 다른 사람들이 찾을 수 있게 도와주세요. 후원 및 팁 옵션은 TIPS.md에 있습니다.