my-agent-browser

chrome-devtools-mcp를 위한 프로덕션 레디 래퍼입니다. chrome-devtools-mcp는 브라우저 MCP 도구를 제공하지만, Chrome 프로세스 관리, 다중 세션 공유, 장애 복구는 전적으로 사용자에게 맡깁니다. 이 프로젝트는 AI 에이전트가 브라우저를 안정적으로 사용할 수 있도록 운영 계층을 추가합니다.

• 시스템에서 Chrome 자동 검색 (macOS/Linux/Windows, Edge/Brave/Arc/Chromium 등 10개 이상의 경로 검색)

• 지연 시작(Lazy start) — 에이전트 시작 시가 아닌 첫 사용 시에만 Chrome 실행
  tools/call

• 여러 에이전트 세션이 browser.lock을 통해 하나의 Chrome 인스턴스를 공유합니다 (참조 카운팅).

• 마지막으로 종료하는 세션이 자동으로 Chrome을 닫습니다.

• 에이전트 충돌 후 고아 프로세스 없음: 부모 하트비트 감지 + 시작 시 고아 프로세스 정리

• WSL / 헤드리스 Linux: DISPLAY 자동 감지 및 구성 (WSLg, Wayland, X11)

• CDP 포트 탐색을 통한 Chrome 충돌 감지 — 에러 텍스트만으로는 절대 신뢰하지 않음

• 확정된 충돌 → Chrome 자동 재실행, MCP 응답 수정하여 에이전트에게 다시 탐색하도록 지시

• MCP의 오래된 상태 (닫힌 탭 참조) → MCP 자식 프로세스만 재시작하고, Chrome은 유지

• 프로필 잠금 잔여물 (하드 종료 후 SingletonLock) → 실행 전에 자동 정리

• 헤드리스 모드, 프록시, 뷰포트 크기, 사용자 지정 시작 인자 — 모든 Chrome 시작 플래그 구성 가능
  evaluate_script

스택 트레이스는 pptr: 마커와 MCP 설치 경로(일반적으로 OS 사용자 이름을 노출함)가 제거됩니다. 이는 사이트 출처 함정(site-origin trap)과 비교하여 측정되며, anti-detection.md를 참조하세요.

• 플래그 권장 사항은 민간 전승이 아닌 한 플래그씩 측정한 결과를 기반으로 합니다.

• 기존 Chrome에 직접 연결 ( browserUrl 모드, 사전 인증된 장기 세션용)

• 무거운 페이지: DOM 오버플로우 충돌 방지를 위한 파일 기반 스냅샷

• 오류 복구: 오래된 UID, 시간 초과, Chrome 재시작 — 각각에 맞는 올바른 응답 제공

• 다중 탭: 열기/추출/닫기 패턴, 탭 간 UID 격리

• 스크래핑: URL 기반 페이지네이션, 지연 로드 트리거링, JS 추출

• 로그인 플로우: 영구 프로필, 자동화된 자격 증명, 기존 세션 연결

npx skills add briqt/my-agent-browser -g -y
npm install -g chrome-devtools-mcp@^1.8.0
mkdir -p ~/.config/agent-skills/my-agent-browser
...

그런 다음 에이전트에 MCP 서버를 등록합니다:

claude mcp add browser -s user -- node ~/.agents/skills/my-agent-browser/scripts/start-mcp.js

또는 프로젝트의 .mcp.json에 추가합니다:

:

{
"mcpServers": {
"browser": {
...

codex mcp add browser -- node ~/.agents/skills/my-agent-browser/scripts/start-mcp.js

또는 ~/.codex/config.toml에 추가합니다:

:

[mcp_servers.browser]
command = "node"
args = ["~/.agents/skills/my-agent-browser/scripts/start-mcp.js"]
...

각 에이전트의 문서에 MCP 서버 항목을 추가하세요:

• 명령어(Command):
  node

• 인자(Args):
  ["~/.agents/skills/my-agent-browser/scripts/start-mcp.js"]

Agent (Claude Code / Codex / Cursor / Kiro / 등)
↓ MCP 툴 호출 (네이티브)
start-mcp.js
...

• Chrome은 분리된 프로세스로 실행되며 여러 MCP 세션에서 공유됩니다.
  browser.lock
  활성 클라이언트 수를 추적하며, 마지막으로 종료하는 클라이언트가 Chrome을 종료합니다. 모든 브라우저 설정은
  ~/.config/agent-skills/my-agent-browser/config.json에 저장됩니다.

• 구성 변경 사항은 다음 에이전트 세션에서 적용됩니다.

번들된 SKILL.md는 워크플로우 지침을 제공하여 에이전트가 일반적인 함정을 피하도록 돕습니다:

복잡한 페이지(Heavy pages)— DOM 오버플로우 충돌 방지를 위한 파일 기반 스냅샷
스크래핑 패턴(Scraping patterns)— URL 기반 페이지네이션, 지연 로드 트리거링, JS 추출
다중 탭(Multi-tab)— 열기/추출/닫기 패턴, 탭 간 UID 격리
오류 복구(Error recovery)— 오래된 UID, 시간 초과, Chrome 재시작
로그인 흐름(Login flows)— 영구 프로필, 자동화된 자격 증명, 기존 세션

├── skills/my-agent-browser/
│ ├── SKILL.md # 에이전트 워크플로우 가이드
│ ├── scripts/
...

npx skills update my-agent-browser -g -y
npm install -g chrome-devtools-mcp@^1.8.0

v1.0.x에서 업그레이드하는 경우, v1.1 플래그 권장 사항에 따라 구성을 마이그레이션하세요 (먼저 건너뛰기(dry run)를 수행한 다음 --apply):

node ~/.claude/skills/my-agent-browser/scripts/migrate-config.js
node ~/.claude/skills/my-agent-browser/scripts/migrate-config.js --apply

파일을 백업하고, 도움이 되기보다 해를 끼치는 세 개의 플래그를 제거하며, 스택 트레이스 숨김 기능을 활성화합니다. 이후 에이전트 세션을 다시 시작하세요.

LINUX DO에서 공유됨