browserd

지속적으로 기록하는 Chromium과 프로그래밍 가능한 DevTools를 MCP를 통해 AI에 노출합니다.

"LLM이 Playwright를 조종하는" 것이 아니라, 보고 있는 모든 것을 기록하는 브라우저 데몬입니다. 그래서 에이전트는 생각하기 전에 발생한 트래픽에 대해 물어볼 수 있습니다.

이것이 실제로 무엇인가

대부분의 브라우저-MCP 서버는 Playwright를 감싸고 모델이 클릭하게 합니다. 그것은 개발자가 브라우저를 열어 하는 일의 극히 일부입니다.

browserd는 직접 사용할 수 있는 실제 헤드드(창이 있는) Chromium을 실행하고, 에이전트는 그 뒤에서 지켜봅니다. 지속적인 CDP 연결을 유지하고 네트워크, 콘솔, 예외, 탐색(navigation)을 지속적으로 기록하여 SQLite에 저장합니다. 모델이 마침내 질문을 하면 브라우저가 아닌 데이터베이스를 질의합니다.

   AI ──MCP──> browserd ──CDP──> Chromium (headed, yours to use)
                  │
                  ├── network recorder ──┐
                  ├── console recorder ──┼──> SQLite + content-addressed blobs
                  ├── page recorder ─────┤
                  └── target manager ────┘        (bodies, traces, heap snapshots)

그 차이는 중요합니다. 일반적인 브라우저 자동화 MCP에 "체크아웃이 왜 실패했지?"라고 물어보면 아무것도 없습니다 — 요청은 이미 사라졌습니다. browserd에게 물어보면 페이로드, 응답 본문, 콘솔 오류, 스택 추적, 정확한 소스 라인을 얻습니다.

에이전트가 할 수 있는 일

사람들이 기대하지 않는 기능들

시간 여행. time.run("30m")은 시계를 앞으로 진행시키고 만기가 된 모든 타이머를 실행합니다. 60초 간격 타이머는 즉시 30번 실행됩니다. time.jump("30m")은 각 타이머를 한 번만 실행하면서 점프합니다. "노트북을 세 시간 닫아둔" 경우입니다. 다른 버그 유형, 다른 도구.

time.install({ time: "2030-01-01T00:00:00Z" })   # page now believes it is 2030
time.run({ duration: "30m" })                     # 30 interval ticks, no waiting
time.freeze()                                     # pin it and inspect

장애 주입. "저장이 20초 걸리면 UI는 어떻게 하나?"라고 묻고 실제로 확인하세요.

fault.delay({ url: "**/api/save", delay: "20s" })
fault.replace_response({ url: "**/api/user", status: 500, body: {...} })
fault.drop_next({ url: "**/api/payment", count: 1 })

누수 탐지. 두 개의 힙 스냅샷과 차이를 생성자별로 보고하고 분리된 DOM 노드를 지목합니다 — 전형적인 누수 시그니처입니다.

사람 ↔ AI 핸드오프. inspector.pick은 실제 DevTools 요소 선택기를 활성화하여 당신이 고장난 것을 클릭하면, 에이전트가 노드 핸들을 읽습니다. page.highlight은 반대 방향입니다.

설치

Node ≥ 20.11이 필요합니다. Chromium은 Playwright에 번들된 빌드가 있으면 그것을 사용합니다(브랜드 Chrome 137+에서는 --load-extension이 제거되었지만 번들 빌드에는 여전히 있습니다), 없으면 시스템 설치를 사용합니다.

git clone <your-remote> browserd && cd browserd
npm install
npm run build

MCP 클라이언트에 등록하기

node scripts/install-mcp.mjs

이것은 Claude Desktop, Claude Code, Codex CLI, Cursor, Windsurf, VS Code를 감지하고 기존 설정에 병합하며(먼저 .bak 파일을 작성), 다른 서버를 덮어쓰지 않습니다.

node scripts/install-mcp.mjs --print            # show the JSON, change nothing
node scripts/install-mcp.mjs --client codex     # just one client
node scripts/install-mcp.mjs --headless         # auto-launch headless
node scripts/install-mcp.mjs --http --port 7331 # register the HTTP endpoint instead

지원 클라이언트: Claude Desktop, Claude Code, Codex CLI, Cursor, Windsurf, VS Code. Codex는 JSON 대신 [mcp_servers.browserd] TOML 섹션을 사용합니다. 설치 프로그램은 주석과 다른 설정이 유지되도록 그 파일을 정밀하게 편집합니다.

그런 다음 모든 클라이언트가 실제로 실행할 수 있는지 확인하세요:

npm run verify-mcp

  OK    Claude Code      174 tools advertised
  OK    Codex CLI        174 tools advertised
  OK    VS Code          174 tools advertised

이것은 실제 설정 파일을 읽고 지정된 항목과 MCP 핸드셰이크를 완료하므로, 오래된 경로나 수동 편집된 항목이 작동한다고 가정되는 대신 발견됩니다.

또는 직접 추가하세요:

{
  "mcpServers": {
    "browserd": {
      "command": "node",
      "args": ["/absolute/path/to/browserd/dist/cli.js"]
    }
  }
}

클라이언트를 다시 시작하세요. 브라우저가 열려 있을 필요는 없습니다 — 브라우저가 필요한 첫 도구 호출이 그것을 실행합니다.

사용해 보기

에이전트에게 물어보세요:

news.ycombinator.com을 열고, 스크린샷을 보여준 다음, 500ms보다 오래 걸린 모든 요청과 가장 느린 요청이 무엇을 반환했는지 알려줘.

또는 전체 피치를 위해:

localhost:3000에 있는 내 앱으로 가서 Checkout을 클릭하고 왜 실패하는지 알려줘.

그것은 실패를 스크린샷으로 찍고, 콘솔 오류를 읽고, 실패한 요청을 찾아 페이로드와 400 응답 본문을 보여주며, 로드된 소스에서 호출 함수를 grep하고 파일과 줄을 알려줍니다.

데몬 직접 실행

node dist/cli.js                 # MCP over stdio (default)
node dist/cli.js --http          # Streamable HTTP on 127.0.0.1:7331/mcp
node dist/cli.js --tools         # print the tool surface and exit
node dist/cli.js --help

환경 변수: AGENTBROWSER_HOME, AGENTBROWSER_PORT, AGENTBROWSER_LOG_LEVEL, AGENTBROWSER_HEADLESS.

HTTP 모드는 루프백에만 바인드하고 Origin을 검증합니다. 이 엔드포인트는 완전한 브라우저 제어이며, 공개 웹의 페이지가 접근할 수 없어야 합니다.

두 가지 설계 규칙

1. 먼저 기록하고 나중에 질의

Chromium이 이벤트를 푸시하면 데몬이 이를 저장합니다. 사전에 준비할 필요가 없으며 모델이 생각하는 동안 어떤 이벤트도 놓치지 않습니다. 기록은 탐색, 탭 닫기, 데몬 재시작 후에도 유지됩니다.

이것은 핵심 부하를 담당합니다: 수집기는 도메인을 활성화하기 전에 CDP 이벤트를 구독하고, 대상 관리자는 계측이 활성화될 때까지 새 대상을 waitForDebuggerOnStart에 보관합니다. 그래서 "요청을 놓치지 않았다"는 말이 개연성이 아니라 사실이 됩니다.

2. 대용량 페이로드는 컨텍스트에 들어가지 않습니다

200MB 응답은 콘텐츠 주소 지정 blob으로 저장되고 아티팩트 핸들로 반환됩니다. 에이전트는 artifact.search, artifact.read_lines 또는 artifact.json_query(JSONPath 하위 집합)로 그것을 읽습니다. 트레이스, 힙 스냅샷, DOM 덤프, 콘솔 내보내기도 마찬가지입니다.

도구는 설계상 질의 우선입니다: dom.get_html보다 dom.summary를, network.list_requests보다 network.summarize를, js.get_source보다 js.search_source를 먼저 사용합니다.

하나의 브라우저에서 사람과 AI

브라우저는 창이 있고 당신의 것입니다. browser.set_control_mode가 중재합니다:

모든 변경 도구는 이것을 확인합니다 — 원시 cdp.send 탈출구를 포함합니다.

도구 표면

174개의 도구. node dist/cli.js --tools로 모두 나열됩니다.

browser.*      list, launch, connect, status, list_targets, set_control_mode, close
page.*         navigate, screenshot, snapshot, click, type, press, scroll, extract_text,
               wait_for, highlight, dialogs, viewport, frames, tabs
dom.*          summary, query, inspect, get_html, set_html, set_attribute, remove, export
css.*          computed, matched_rules, set_style, stylesheets, explain_visibility
js.*           evaluate, list_scripts, get_source, search_source
console.*      query, exceptions, export, clear
network.*      list_requests, get_request, get_body, summarize, search_bodies,
               list_websockets, ws_messages, export_har, simulate, clear
storage.*      local/session, cookies, indexeddb, caches, usage, export
debugger.*     enable, breakpoints, pause, resume, step, call_frames,
               evaluate_on_frame, inspect_object, wait_for_pause
inspector.*    pick, picked, element, parents, children, snapshot, accessibility_tree
profile.*      start/stop/status (presets: cpu, slow-page, hang, memory-leak, full)
profiler.*     cpu, coverage, trace, long_tasks
memory.*       heap.snapshot, heap.compare, gc, usage
time.*         install, freeze, run, jump, resume, set_fixed_date, set_wall_clock, virtual
device.*       preset, viewport, orientation, reset
environment.*  timezone, locale, color_scheme, reduced_motion, vision, status, reset
fault.*        abort, delay, replace_response, drop_next, modify_headers, list, clear
artifact.*     list, stat, read, read_lines, search, json_query, export
cdp.send       escape hatch to any raw CDP method

테스트

npm test                      # build + live MCP suite + HTTP suite
npm run test:live             # 117 checks: real MCP client, real Chromium, local fixture
npm run test:live:headed      # same, with a visible window
npm run test:deep             # 35 checks against a real public site
npm run test:http             # Streamable HTTP transport + origin guard
npm run test:real             # headed narrated walkthrough on live sites

모든 스위트는 실제 서버를 실행하고 실제 MCP 클라이언트를 연결합니다. 검증은 tools/call을 통해 이루어지므로 스키마 검증, 핸들러 연결, 운영이 함께 다뤄집니다.

호출이 반환되었다는 것이 아니라 동작을 검증합니다:

• 400의 요청 페이로드와 응답 본문이 모두 읽을 수 있어야 함

• 700KB 응답이 인라인 약 500자의 아티팩트로 반환되어야 함

• time.run("30m")은 60초 간격을 정확히 30번 실행하고; time.jump는 한 번 실행해야 함

• 일시 중지된 호출 프레임에서 지역 변수를 읽어야 함 (total=75, tax=15)

• observe 모드는 읽기는 허용하면서 변경 3/3을 거부해야 함

• 내보낸 HAR가 유효한 HAR 1.2로 다시 파싱되어야 함

• 힙 스냅샷이 실제 .heapsnapshot으로 로드되어야 함

tests/deep-dive.mjs는 실제 Hacker News에 대해 실행됩니다: h2/nginx/원격 IP 세부 정보가 포함된 14개의 실제 요청, 와이어에서 읽은 34KB 응답 본문, 1285노드 DOMSnapshot, 1603노드 접근성 트리, 8MB 힙 델타가 감지됩니다.

레이아웃

src/
  cdp/        persistent WebSocket, flat-session multiplexing
  browser/    launcher, target manager (auto-attach + debugger hold), registry, faults
  collect/    network, console, page and execution-context recorders
  store/      SQLite schema, blob store, artifact store
  ops/        the actual capabilities, independent of MCP
  mcp/        tool definitions and server wiring
  cli.ts      stdio / HTTP entry point
tests/        live MCP suites
scripts/      install-mcp.mjs

MCP는 데몬 자체가 아니라 데몬에 대한 하나의 인터페이스입니다. src/index.ts는 핵심을 내보내 CLI, REST 레이어 또는 테스트 하니스가 직접 구동할 수 있습니다.

데이터는 ~/.agent-browser에 있습니다(AGENTBROWSER_HOME으로 이동 가능): browserd.db, blobs/, artifacts/, profiles/, logs/.

보안 참고 사항

• 루프백에만 바인드하세요. 이 엔드포인트는 로그인된 세션을 보유한 브라우저의 완전한 제어입니다.

• ~/.agent-browser/profiles 아래의 브라우저 프로필에는 쿠키와 세션 토큰이 포함되어 있습니다. 기록된 본문에는 방문한 페이지가 반환한 내용이 포함됩니다. 둘 다 gitignore 처리되어 있습니다. 그 상태를 유지하세요.

• --net-log-capture-mode=Everything은 와이어에서 나온 원시 바이트를 포함할 수 있습니다. 소유한 트래픽에만 사용하세요.

• cdp.send는 제한 없는 CDP이며 제어 모드로만 게이트됩니다.

알려진 제한 사항

• Debugger.setScriptSource 라이브 편집은 현재 Chromium에서 제거되었습니다 — 소스를 편집하고 다시 로드하세요.

• Network.getRequestPostData는 multipart 업로드에서 파일을 생략할 수 있으므로, "모든 업로드의 모든 바이트"가 해당 경로만으로는 보장되지 않습니다. 스택 수준의 세부 정보(DNS, 소켓, TLS)를 보려면 capture_netlog와 함께 실행하세요.

• 제어된 클록은 addScriptToEvaluateOnNewDocument를 통해 설치되는 가짜 타이머 shim이며, 데몬이 원시 CDP를 사용하므로 Playwright의 Clock API가 아닙니다. time.virtual은 Chromium 자체의 가상 시간 정책을 노출합니다; 둘은 하나의 대상에서 결합할 수 없으며, 데몬은 이를 겹쳐 사용하는 것을 거부합니다.

• 터치 에뮬레이션은 의도적으로 Emulation.setEmitTouchEventsForMouse를 설정하지 않습니다: 해당 플래그는 Chromium이 Input.dispatchMouseEvent를 영구적으로 인식하지 못하게 만듭니다. 대신 page.click이 탭을 합성합니다.

• ontouchstart in window는 문서 생성 시 결정되므로, 다시 로드한 후에 나타납니다. navigator.maxTouchPoints는 즉시 활성화됩니다.

• Target.openDevTools (devtools.open)는 실험적이며 일부 빌드에서는 거부됩니다.

• 센서 에뮬레이션은 구현되어 있지 않습니다. 원시 프로세스 메모리 읽기/쓰기는 범위를 벗어납니다 — 이를 위해서는 별도의 디버거 어댑터가 필요합니다.

라이선스

MIT