haden-browser

haden-browser는 로컬 Model Context Protocol 서버로 노출되는 빠르고 AI 우선(AI-first) 웹 브라우저입니다. 매 턴마다 스크린샷과 원시 페이지 소스를 보내는 대신, AI에게 현재 목표에 가장 유용한 최소한의 페이지 표현을 제공합니다.

벤치마크: AI 브라우저 컨텍스트 33% 감소

주요 결과: Haden은 핵심 브라우징 세션에서 7,822 참조 토큰을 사용했습니다—Playwright MCP보다 32.7% 적고 Chrome DevTools MCP 전체 모드보다 32.5% 적습니다. 시맨틱 액션 refs와 이미지 alt 커버리지를 반환한 테스트된 브라우저 MCP 중에서 Haden이 가장 낮은 토큰 사용량을 기록했습니다.

† Chrome Slim은 절대적인 최소 토큰이지만, 저수준 JavaScript 제어 기준선입니다. 모델이 페이지 스크립트를 직접 작성해야 하며, 테스트된 경로는 시맨틱 액션 refs나 이미지 alt 텍스트를 반환하지 않았습니다. 따라서 투명하게 표시되지만 시맨틱 브라우저와 동등한 것으로 취급되지는 않습니다.

핵심 컨텍스트에는 도구 스키마 전체 로드 1회와 문서 읽기, 폼 제출, 계산된 스타일 검사에 대한 직렬화된 MCP 도구 호출 및 결과가 포함됩니다. 카운트는 o200k_base 토크나이저를 사용합니다. 이미지 픽셀, 사용자/시스템 프롬프트, 모델 추론 또는 산문은 제외되므로 실제 청구 사용량은 MCP 호스트와 모델에 따라 달라집니다.

전체 벤치마크 보고서, 실행별 원시 데이터, 재현 방법을 참조하세요.

Related MCP server: browsegrab

왜 다른가

• 목표 기반 뷰 — 연구에는 간결한 시맨틱 텍스트, 구조에는 정화된 DOM, 시각적 작업에는 제한된 계산된 스타일을 사용합니다.

• 이미지는 지연 로드 유지 — 이미지는 alt 텍스트 또는 [image img1]로 표현됩니다. 픽셀 데이터는 AI가 명시적으로 haden_image를 호출할 때만 반환됩니다.

• 낮은 왕복 제어 — 모든 상호작용이 새로운 스냅샷을 반환하므로 대부분의 클릭/입력 흐름은 단계당 도구 호출 한 번만 필요합니다.

• 안정적인 액션 참조 — 표시되는 컨트롤은 e1, e2 등이 되며, 모델이 CSS 선택자를 직접 만들도록 요청하는 것보다 저렴하고 안정적입니다.

• 기본적으로 빠름 — 일반 브라우징 중에는 이미지, 미디어, 글꼴 요청이 차단됩니다. CSS는 visual 뷰에서 계속 사용할 수 있습니다.

• 더 안전한 로컬 실행 — 사용자가 명시적으로 옵트인하지 않는 한 비HTTP 스킴, 자격 증명이 포함된 URL, 사설 네트워크 대상이 차단됩니다.

flowchart LR
    AI[AI / MCP host] -->|stdio tools| MCP[haden-browser]
    MCP --> PW[Playwright Chromium]
    PW --> PAGE[Web page]
    PAGE -->|semantic text / DOM / computed CSS| MCP
    MCP -.->|only haden_image imgN| PIXELS[Image bytes]
    PIXELS -.-> AI

뷰

text가 기본값이며, 작업에 구조나 표현 세부 정보가 정말로 필요하지 않은 한 text를 우선해야 합니다.

MCP 도구

텍스트 출력 예시:

# Example Domain
URL: https://example.com/
View: text
Interactive elements: 1
Images: 1 (use haden_image with an img ref only when visual inspection is needed)

# Example Domain
This domain is for use in illustrative examples.
[e1] link "More information" -> https://iana.org/domains/example
[image img1: "Example diagram"]

참조는 최신 스냅샷으로 범위가 제한됩니다. 페이지가 크게 변경된 후에는 이전 e 또는 img ref를 재사용하기 전에 다시 읽으세요.

요구 사항

• Node.js 20 이상

• Playwright를 통해 설치된 Chromium

이 저장소에서 설치

git clone https://github.com/Haden-Min/haden-browser.git
cd haden-browser
npm ci
npm run setup-browser
npm run build

그런 다음 MCP 호스트가 빌드된 stdio 서버를 실행하도록 구성하세요. 실제 구성에서는 절대 경로를 사용하세요:

{
  "mcpServers": {
    "haden-browser": {
      "command": "node",
      "args": ["/absolute/path/to/haden-browser/dist/index.js"]
    }
  }
}

개발 중에는 호스트가 npx tsx /absolute/path/to/haden-browser/src/index.ts를 대신 실행할 수 있습니다.

패키지가 npm에 게시된 후 의도된 구성은 다음과 같습니다:

{
  "mcpServers": {
    "haden-browser": {
      "command": "npx",
      "args": ["-y", "haden-browser"]
    }
  }
}

해당 머신에서 첫 브라우저 호출 전에 npx playwright install chromium을 한 번 실행하세요.

구성

불리언 변수는 true/false, 1/0, yes/no, on/off를 허용합니다.

로컬 개발 페이지

SSRF 위험을 줄이기 위해 사설 호스트는 기본적으로 차단됩니다. localhost에서 애플리케이션을 탐색하려면 해당 MCP 프로세스에 대해서만 옵트인하세요:

{
  "mcpServers": {
    "haden-browser-local": {
      "command": "node",
      "args": ["/absolute/path/to/haden-browser/dist/index.js"],
      "env": { "HADEN_ALLOW_PRIVATE_HOSTS": "true" }
    }
  }
}

개발

npm install
npm run setup-browser
npm run check
npm run build

테스트 스위트는 네트워크 정책, 텍스트 셰이핑, 실제 Chromium 추출, ref 기반 상호작용, 지연 이미지 검색, 인메모리 MCP 클라이언트/서버 연결을 다룹니다.

현재 제한 사항

• stdio MCP 연결당 하나의 활성 브라우저 컨텍스트가 유지됩니다.

• 이미지 refs는 현재 표시되는 HTML <img> 요소만 다루며, CSS 배경 이미지, 캔버스, 비디오 프레임, iframe 콘텐츠는 다루지 않습니다.

• visual 뷰는 계산된 속성을 보고하며, 모든 스타일시트 규칙을 덤프하지는 않습니다.

• 다운로드, 파일 업로드, 브라우저 확장 프로그램, 영구 프로필, CAPTCHA 해결은 MVP 범위 밖입니다.

• 사설 호스트 필터링은 SSRF 노출을 줄이지만, 적대적인 멀티테넌트 환경에서 OS/컨테이너 수준 네트워크 격리를 대체하지는 않습니다.

개발 지침은 CONTRIBUTING.md를, 취약점 신고는 SECURITY.md를 참조하세요.

라이선스

MIT