Umbra

직접 로그인해 둔 Chrome을 AI 에이전트가 세션 단위로 제어하게 하되, 에이전트에게 쿠키를 건네주지 마세요.

Umbra는 사용자가 생성한 공유 키로 짝을 이루는 두 가지 요소로 구성됩니다: 모든 Chrome API 호출을 소유하는 MV3 Chrome 확장 프로그램과, 어떤 MCP 클라이언트든 브라우저 도구 표면을 노출하는 로컬 MCP 서버가 그것입니다. 둘은 인증된 루프백 WebSocket으로만 통신합니다. 어떤 것도 기기를 떠나지 않습니다.

존재 이유

브라우저 원격 디버깅은 에이전트에게 모든 것을 한 번에 제공합니다: 모든 탭, 모든 쿠키 저장소, 모든 프로필. Umbra는 반대 입장을 취합니다. 에이전트는 자신이 만든 탭 그룹과 그 안의 탭만 얻고, 그 외에는 아무것도 얻지 못합니다. 소유하지 않은 탭을 읽으라고 요청하면 Chrome에 닿기 전에 확장 프로그램이 거부합니다.

두 도구는 의도적으로 그 경계 밖에 있으며, 둘 다 docs/permissions.md에 그렇게 명시되어 있습니다. browser_find_tabs와 browser_find_groups는 세션이 소유하지 않은 탭의 제목과 URL을 보고합니다. 이것이 탭을 넘겨주는 방식입니다. 그리고 browser_cleanup_groups는 전체 프로필에서 탭 그룹을 제목으로 매칭하여 종료된 세션이 남긴 그룹을 정리할 수 있습니다. browser_cleanup_groups에 자신의 그룹과 겹치지 않는 제목 접두사를 주거나, 먼저 dryRun: true로 실행해 보세요.

바로 그 경계 덕분에 이미 로그인되어 있는 브라우저를 대상으로 쓸 수 있습니다. 에이전트는 로그인된 대시보드를 읽고, 양식을 채우고, CSV를 내보내고, 작업이 끝나면 자신의 탭을 닫습니다. 그동안 다른 창은 건드려지지도 않고 읽히지도 않은 채 유지됩니다.

이 프로젝트는 일부러 담백하게 설계되었습니다:

• 진짜 Chrome, 진짜 프로필, 진짜 로그인 상태 – 사용자가 직접 선택

• 하나의 브라우저에서 여러 동시 에이전트 세션, 각 세션은 자신의 탭 그룹으로 격리

• 모든 동작에 세션별 탭 소유권 강제 적용

• 쿠키 내보내기, 토큰 추출, CAPTCHA 해결, 일반적인 백그라운드 fetch 없음

• 루프백 전용 전송과 양방향 HMAC 핸드셰이크

Related MCP server: byob

설치

일반 설치에 필요한 모든 변수를 설명하는 전체 안내는 docs/install.md에 있습니다. 짧게 요약하면:

git clone https://github.com/RobertJLora/umbra
cd umbra/mcp-server
npm install
npm test

의존성은 저장소 루트가 아니라 mcp-server/에 있습니다. 그래서 루트에서 npm install을 실행하면 아무것도 설치되지 않고, 위 명령을 한 번 실행하기 전에는 루트에서 npm test도 실패합니다. 실행한 후에는 npm test, npm run doctor, npm run release:check가 모두 루트에서 작동합니다.

chrome://extensions에서 개발자 모드를 켜고 extension/을 압축 해제 상태로 로드합니다. 확장 프로그램 옵션 페이지를 열고 Generate Key를 클릭한 다음, Copy Environment Line을 클릭해 그 줄을 MCP 클라이언트 설정에 붙여넣으세요. 클라이언트를 다시 시작하면 도구들이 나타납니다. Umbra는 설치 시점에 사이트 접근 권한을 요청하지 않으므로, 첫 페이지 읽기 전에 같은 페이지의 Grant Site Access도 클릭하세요.

설치는 공개 저장소에서 체크아웃하는 방식입니다. 위 클론 후, node mcp-server/cli.js pair 명령이 키를 생성해 ~/.umbra/shared-key에 기록하고 클라이언트 설정 블록을 출력합니다. 공개 체크아웃에는 선택적 로컬 플러그인이 포함되어 있지 않습니다.

도구 표면

세션 및 탭 browser_create_tab, browser_list_tabs, browser_switch_tab, browser_close_tab, browser_close_session_tabs, browser_freeze_session_tabs, browser_group_tabs, browser_cleanup_groups, browser_mark_debug_group, browser_tabs_context, browser_get_session_status, browser_get_bridge_pressure

이미 연 탭 가져오기 browser_find_tabs, browser_adopt_tab, browser_find_groups, browser_adopt_group

탐색 browser_navigate, browser_navigate_back, browser_navigate_forward, browser_wait, browser_resize

읽기 browser_get_page_content, browser_read_page, browser_read_interactive, browser_find, browser_get_technical_snapshot, browser_screenshot, browser_console_messages

상호작용 browser_click, browser_click_text, browser_type, browser_fill, browser_form_input, browser_select_option, browser_hover, browser_press_key, browser_shortcut, browser_scroll, browser_file_upload

왕복을 줄여주는 복합 도구 browser_batch, browser_wait_click_read, browser_navigate_wait_read, browser_click_wait_selector_read

탈출구 browser_javascript, browser_run_page_action, browser_wait_for_download

browser_reload_extension은 압축 해제된 개발자 설치에서만 존재합니다. UMBRA_ALLOW_EXTENSION_RELOAD=1일 때만 광고되며, 스토어 설치는 거부합니다. 옵션 페이지의 Reload 버튼은 교차 세션 도구를 노출하지 않고 동일한 워크플로를 처리합니다.

위 목록은 모든 출시 빌드의 전체 도구 표면입니다. 체크아웃에는 출시 빌드의 일부가 아닌 선택적 로컬 페이지 레시피 플러그인이 포함될 수 있습니다. mcp-server/plugins/의 모듈과 extension/recipes/의 페이지 레시피가 짝을 이루는 구조이며, 두 폴더 모두 추적되지 않고 출시되지 않습니다. 플러그인은 해당 플러그인을 보유한 설치에서만 그 목록에 자체 도구와 고유한 browser_run_page_action 값을 추가합니다.

이 도구들을 호출하기 전에 알아야 할 참고 사항:

• browser_get_page_content는 기본적으로 텍스트만 제공하며 선택자 범위 지정과 maxChars 상한을 지원합니다. 표시 중인 이미지 목록이 필요할 때만 includeImages: true를 전달하세요.

• browser_batch는 하나의 MCP 호출로 제한된 create, navigate, wait, read, click, fill, press, scroll, close 워크플로를 실행합니다. 하위 매개변수는 이전 결과를 참조할 수 있습니다: 마지막으로 성공한 단계는 {"$ref":"prev.tabId"}, 인덱스 단계는 {"$ref":"0.tabId"}, 그리고 이전 호출이 label: "create"를 설정했다면 {"$ref":"create.tabId"}로 참조합니다.

• browser_read_interactive는 현재 DOM 버전에 연결된 수명이 짧은 refs와 함께 표시 중인 컨트롤의 간결한 목록을 반환합니다. browser_click, browser_fill, browser_scroll, browser_screenshot은 그 refs를 받아들이며, 만료된 ref는 호출자에게 다시 읽으라고 알려주는 오류를 반환합니다.

• browser_get_bridge_pressure는 세션 하나의 부하를 보고합니다: 소유한 탭 수와 해당 탭들의 표본, 연결된 리스너 수, 콘텐츠 에이전트 대기열 깊이가 그것입니다. 또한 더 이상 존재하지 않는 탭의 소유권 기록을 정리하므로 순수한 읽기 전용이 아닙니다.

• browser_freeze_session_tabs는 chrome.tabs.discard로 소유한 비활성 탭을 메모리에서 해제하여 렌더러 메모리를 확보합니다. 기본값은 dryRun: true이며, 다른 세션이 소유한 탭은 절대로 대상으로 삼지 않습니다.

• browser_run_page_action은 미리 정의된 이름 붙은 페이지 액션을 실행하고 JSON-safe 출력을 반환합니다. 임의 스크립트 도구가 아닙니다. 임의 스크립트 도구는 browser_javascript이며, 소유 탭에서 디버거를 거쳐 실행됩니다.

동작 원리

1. MCP 클라이언트는 stdio로 로컬 서버와 통신합니다.

2. 서버는 루프백 bridge 리스너에 직접 또는 Rust broker를 통해 세션을 등록합니다.

3. Chrome 확장 프로그램의 offscreen 문서가 WebSocket을 보유하고 서비스 워커가 교체되어도 계속 살아 있게 합니다.

4. 확장 프로그램은 공유 키와 세션별 nonce를 사용하는 HMAC 챌린지로 모든 연결을 인증합니다.

5. 백그라운드 서비스 워커는 각 세션에 자신의 탭 그룹을 배정하고, 모든 Chrome 호출 전에 소유권을 확인합니다.

두 가지 전송이 존재합니다. Rust broker가 런처의 기본값입니다: 확장 WebSocket 하나, 그 뒤에서 로컬 Unix 소켓을 통해 세션을 등록하는 여러 경량 MCP 서(bridge), 그리고 라우팅, 인증, 부하 카운터, 요청 정리를 소유하는 broker 하나. 레거시 모드는 각 세션에 자체 루프백 리스너를 제공하며, UMBRA_BROKER_MODE=legacy라는 설정 하나로 전환할 수 있습니다. 어느 쪽이든 Chrome API에 닿는 것은 확장 프로그램뿐입니다.

동시성과 소유권

• 하나의 Chrome 프로필이 여러 세션을 동시에 호스팅합니다.

• 각 세션마다 세션 ID 하나, 이름이 있는 청록색 Chrome 탭 그룹 하나, 그리고 브라우저에 대한 자체 뷰를 갖습니다.

• 탭 열기, 탐색, DOM 상호작용은 기본적으로 비활성 탭을 사용하므로 일상적인 작업은 Chrome을 전경으로 가져오지 않습니다. 실제로 초점이 필요할 때는 activate: true를 전달하세요.

• Umbra는 자체 탭을 위한 전용 Chrome 창을 기억하고 새 세션 탭을 그곳으로 라우팅합니다. 그 창이 포커스를 받는 동안에는 재사용을 거부하므로, 작업 중인 창에 탭을 추가하지 않습니다.

• 탐색은 확장 경계에서 scheme으로 제한됩니다: http:, https:, file:, about:blank는 허용되고 그러한, 위험한 scheme은 Chrome에 도닿기 전에 거부됩니다.

• 작업이 끝나면 에이전트는 소유한 전체 그룹을 닫는 browser_close_session_tabs를 호출해야 합니다. 창의 모든 탭이 해당 세션 소유일 때만 전체 창이 닫히므로, 소유하지 않은 빈 탭은 남아 있습니다.

• 서버를 정리 종료하면 기본적으로 동일한 정리를 실행합니다. 실행 결과는 열어 두고 싶다면 UMBRA_KEEP_TABS_OPEN=1 또는 UMBRA_CLOSE_ON_SHUTDOWN=0을 설정하세요.

• 기본 포트 범위는 47821-47852이며, 일반적인 다중 에이전트 작업에서 항상 여유가 충분합니다. 확장 프로그램은 설정된 포트를 1024-65535로 제한합니다. 양쪽에 같은 범위를 설정하세요.

Umbra가 하지 않는 일

• 쿠키 덤프-또는 동기화

• 토큰 추출

• 스토리지 읽기/쓰기를 도구로 노출

• 페이지를 대신한 백그라운드 fetch

• CAPTCHA 해결

• 북마크, 방문 기록 또는 클립보드 접근

• 네이티브 메시징 사용

• 자동 업데이트나 자동 가져오기, 자동 설치

알려진 제한 사항

• 기본 스크린샷은 촬영 전에 세션 소유 탭을 활성화합니다. silent: true는 소유 탭에 chrome.debugger를 부착하고 Page.captureScreenshot 한 번만 실행하는 방식으로 이를 피하지만, Chrome은 자동화 배너를 표시하게 됩니다.

• 사이트 접근 권한은 선택적 권한이며, 옵션 페이지의 Grant Site Access 버튼으로 설치가 아닌 그때 요청합니다. 부여되기 전까지 Chrome 자체의 권한 오류와 함께 페이지 읽기와 스크린샷이 실패합니다. Chrome이 프로그래밍 방식의 표시 탭 캡처를 위해 리터럴 broad host permission을 요구하기 때문입니다.

• 다운로드 완료는 파일시스템을 관찰해서 감지합니다. 확장 프로그램이 Chrome의 downloads 권한을 요청하지 않기 때문입니다. 브라우저의 다운로드 폴더를 옮겼다면 UMBRA_DOWNLOAD_DIR을 해당 폴더로 설정하세요.

• browser_read_interactive는 의도적으로 간결합니다. Umbra는 전체 접근성 트리 덤프를 노출하지 않습니다.

• 일반 텍스트 클릭은 검색 페이지네이션 같은 밀집된 앱 UI에서 잘못된 컨트롤을 누를 수 있습니다. 추측하지 말고 refs와 함께 browser_read_interactive를 사용하거나, browser_run_page_action에서 inspect_controls 후 click_control을 실행하세요.

• 포트 범위를 변경하면 양쪽을 모두 다시 시작해야 합니다. 서버가 새 환경 값을 상속하도록 MCP 클라이언트를 다시 시작하고, 저장된 확장 스토리지가 정규화되도록 압축 해제된 확장을 다시 로드하세요.

구성

• extension/ - MV3 확장: service worker, 숨겨진(offscreen) bridge, 콘텐츠 에이전트, 옵션 페이지, 팝업

• extension/recipes/ - 선택적 사이트별 페이지 레시피, 요청 시 주입되며 출시 패키지에는 없음

• mcp-server/ - stdio MCP 서버, 루프백 bridge, Rust broker shim 클라이언트, 로컬 개발 하네스

• rust-broker/ - Tokio broker 런타임, 하나의 확장 WebSocket에서 여러 세션을 멀티플렉싱

• tests/ - 인증, 소유권, 세션 격리, 확장 프로그램 수명주기, 패키징 검증

• scripts/ - 격리된 Chrome 테스트 프로필 런처와 스모크 래퍼

• launchd/ - broker를 계속 실행해 두는 선택적 macOS 작업용 템플릿

• docs/ - 설치, 아키텍처, 권한, 스모크 테스트 노트

문서

• docs/install.md - 클론부터 연결된 세션까지의 설정과 모든 환경 변수

• docs/architecture.md - 구성 요소, 흐름, offscreen과 background 분리의 근거

• docs/permissions.md - 각 Chrome 권한의 위험성과 완화 방안

• docs/smoke-test.md - 자동 및 수동 검증 경로

• docs/performance/performance-work.md - 성능 작업이 변경한 내용과 측정 결과

• MCP_PROTOCOL.md - 확장 프로그램과 서버 간의 와이어 프로토콜

• THREAT_MODEL.md - 자산, 신뢰경계, 공격자, 완화 방안

• SECURITY_REVIEW.md - 리뷰 입장, 유지·제거 행렬, 그리고 상위 감

소중한 것이 담긴 브라우저에 이 도구를 사용하기 전에 THREAT_MODEL.md와 SECURITY_REVIEW.md를 읽으세요.