Umbra

Steuere dein eigenes angemeldetes Chrome über einen KI-Agenten, jeweils eine Sitzung nach der anderen, ohne dem Agenten deine Cookies zu übergeben.

Umbra besteht aus zwei Teilen, die über einen gemeinsam genutzten Schlüssel, den du erzeugst, zusammenarbeiten: eine MV3-Chrome-Erweiterung, die jeden Chrome-API-Aufruf besitzt, und einen lokalen MCP-Server, der eine Browser-Tool-Oberfläche für jeden MCP-Client bereitstellt. Sie kommunizieren nur über einen authentifizierten Loopback-WebSocket. Nichts verlässt die Maschine.

Warum es das gibt

Remote-Debugging eines Browsers gibt einem Agenten auf einmal alles: jeden Tab, jeden Cookie-Jar, jedes Profil. Umbra vertritt die gegenteilige Position. Der Agent bekommt eine Tab-Gruppe, die er erstellt hat, die Tabs darin und sonst nichts. Wenn du es bittest, einen Tab zu lesen, der ihm nicht gehört, verweigert die Erweiterung die Aktion, bevor Chrome überhaupt berührt wird.

Zwei Tools sitzen absichtlich außerhalb dieser Grenze, und beide sind als solche in docs/permissions.md aufgeführt: browser_find_tabs und browser_find_groups melden den Titel und die URL von Tabs, die einer Sitzung nicht gehören – so übergibst du einen Tab –, und browser_cleanup_groups gleicht Tab-Gruppen anhand des Titels über das gesamte Profil ab, um Gruppen zu entfernen, die von einer nicht mehr vorhandenen Sitzung hinterlassen wurden. Gib browser_cleanup_groups ein Titel-Präfix, das deine eigenen Gruppen nicht teilen, oder führe es zuerst mit dryRun: true aus.

Diese Grenze macht es einsetzbar mit einem Browser, bei dem du bereits angemeldet bist. Der Agent kann ein Dashboard lesen, bei dem du angemeldet bist, ein Formular ausfüllen, eine CSV exportieren und seine eigenen Tabs schließen, wenn er fertig ist, während deine anderen Fenster unberührt und unlesbar bleiben.

Das Projekt ist bewusst langweilig:

• echtes Chrome, echtes Profil, echter angemeldeter Zustand, von dir gewählt

• viele gleichzeitige Agentensitzungen in einem Browser, jede isoliert in ihrer eigenen Tab-Gruppe

• pro Sitzung durchgesetzte Tab-Inhaberschaft bei jeder Aktion

• kein Cookie-Export, keine Token-Extraktion, kein CAPTCHA-Lösen, kein generischer Hintergrundabruf

• Nur-Loopback-Transport mit HMAC-Handshake in beide Richtungen

Related MCP server: byob

Installation

Eine vollständige Anleitung mit jeder Variablen, die eine normale Installation benötigt, findest du in docs/install.md. Die Kurzfassung:

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

Die Abhängigkeiten liegen in mcp-server/, nicht im Repository-Stammverzeichnis, daher installiert npm install im Stammverzeichnis nichts und npm test schlägt dort fehl, bis der obige Befehl einmal ausgeführt wurde. Danach funktionieren npm test, npm run doctor und npm run release:check alle vom Stammverzeichnis aus.

Lade extension/ als entpackte Erweiterung unter chrome://extensions bei aktiviertem Entwicklermodus, öffne die Optionsseite der Erweiterung, klicke auf Generate Key, dann auf Copy Environment Line und füge diese Zeile in deine MCP-Client-Konfiguration ein. Starte den Client neu und die Tools erscheinen. Klicke auf derselben Seite vor dem ersten Seitenlesen auf Grant Site Access, da Umbra bei der Installation keinen Site-Zugriff anfordert.

Die Installation ist ein Checkout aus dem öffentlichen Repository. Nach dem obigen Klon erzeugt node mcp-server/cli.js pair den Schlüssel, schreibt ihn nach ~/.umbra/shared-key und gibt den Client-Konfigurationsblock aus. Der öffentliche Checkout enthält keine optionalen lokalen Plugins.

Tool-Oberfläche

Sitzung und Tabs 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

Übernahme bereits geöffneter Tabs browser_find_tabs, browser_adopt_tab, browser_find_groups, browser_adopt_group

Navigation browser_navigate, browser_navigate_back, browser_navigate_forward, browser_wait, browser_resize

Lesen browser_get_page_content, browser_read_page, browser_read_interactive, browser_find, browser_get_technical_snapshot, browser_screenshot, browser_console_messages

Interaktion 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

Zusammengesetzte Aktionen, die Roundtrips sparen browser_batch, browser_wait_click_read, browser_navigate_wait_read, browser_click_wait_selector_read

Escape-Hatches browser_javascript, browser_run_page_action, browser_wait_for_download

browser_reload_extension existiert nur für entpackte Entwicklerinstallationen. Es wird angezeigt, wenn UMBRA_ALLOW_EXTENSION_RELOAD=1 gesetzt ist, und Store-Installationen lehnen es ab. Der Reload-Button auf der Optionsseite deckt denselben Arbeitsablauf ab, ohne ein sitzungsübergreifendes Tool bereitzustellen.

Die obige Liste ist die gesamte Oberfläche jedes veröffentlichten Builds. Ein Checkout kann optionale lokale Page-Rezept-Plugins enthalten, die nicht Teil eines veröffentlichten Builds sind: ein Modul in mcp-server/plugins/ zusammen mit einem Page-Rezept in extension/recipes/. Beide Ordner sind unversioniert und unveröffentlicht, und ein Plugin fügt seine eigenen Tools und seine eigenen browser_run_page_action-Werte nur in der Installation hinzu, die es enthält.

Hinweise, die du kennen solltest, bevor du diese aufrufst:

• browser_get_page_content ist standardmäßig auf nur Text eingestellt und unterstützt Selektor-Eingrenzung sowie ein maxChars-Limit. Übergib includeImages: true nur, wenn du die Auflistung der sichtbaren Bilder benötigst.

• browser_batch führt einen begrenzten Arbeitsablauf aus create, navigate, wait, read, click, fill, press, scroll, close in einem einzigen MCP-Aufruf aus. Untergeordnete Parameter können frühere Ergebnisse referenzieren mit {"$ref":"prev.tabId"} für den letzten erfolgreichen Schritt, {"$ref":"0.tabId"} für einen Schritt per Index oder {"$ref":"create.tabId"}, wenn der frühere Aufruf label: "create" gesetzt hat.

• browser_read_interactive gibt eine kompakte Liste sichtbarer Steuerelemente mit kurzlebigen Referenzen zurück, die an die aktuelle DOM-Version gebunden sind. browser_click, browser_fill, browser_scroll und browser_screenshot akzeptieren diese Referenzen; eine veraltete Referenz gibt einen Fehler zurück, der den Aufrufer auffordert, erneut zu lesen.

• browser_get_bridge_pressure meldet den Druck einer Sitzung: die Anzahl der von ihr besessenen Tabs und eine Stichprobe dieser Tabs, die Anzahl verbundener Listener und die Tiefe der Content-Agent-Warteschlange. Es räumt auch Inhaberschaftsdatensätze für Tabs ab, die nicht mehr existieren, ist also nicht rein lesend.

• browser_freeze_session_tabs verwirft besessene inaktive Tabs mit chrome.tabs.discard, um Renderer-Speicher freizugeben. Standardmäßig ist dryRun: true gesetzt, und es zielt nie auf einen Tab, der einer anderen Sitzung gehört.

• browser_run_page_action führt vordefinierte, benannte Seitenaktionen aus und gibt JSON-sichere Ausgabe zurück. Es ist kein Tool für beliebige Skripte; das ist browser_javascript, und es läuft über den Debugger auf dem besessenen Tab.

Wie es zusammenpasst

1. Dein MCP-Client spricht über stdio mit dem lokalen Server.

2. Der Server registriert eine Sitzung, entweder direkt auf einem Loopback-Bridge-Listener oder über den Rust-Broker.

3. Das Offscreen-Dokument der Chrome-Erweiterung hält den WebSocket und hält ihn über Service-Worker-Neustarts hinweg am Leben.

4. Die Erweiterung authentifiziert jede Verbindung mit einer HMAC-Herausforderung über den gemeinsamen Schlüssel plus sitzungsspezifische Nonces.

5. Der Background-Service-Worker weist jeder Sitzung ihre eigene Tab-Gruppe zu und prüft die Inhaberschaft vor jedem Chrome-Aufruf.

Es gibt zwei Transporte. Der Rust-Broker ist die Standardeinstellung des Launchers: eine Erweiterungs-WebSocket, viele leichtgewichtige MCP-Shims, die dahinter Sitzungen über einen lokalen Unix-Socket registrieren, wobei der Broker Routing, Authentifizierung, Druckzähler und Anfragebereinigung übernimmt. Der Legacy-Modus gibt jeder Sitzung einen eigenen Loopback-Listener und ist mit UMBRA_BROKER_MODE=legacy nur eine Einstellung entfernt. In beiden Fällen ist die Erweiterung das Einzige, das eine Chrome-API berührt.

Nebenläufigkeit und Inhaberschaft

• Ein Chrome-Profil hostet viele Sitzungen gleichzeitig.

• Jede Sitzung erhält eine Sitzungs-ID, eine benannte cyanfarbene Chrome-Tab-Gruppe und ihre eigene Sicht auf den Browser.

• Öffnen, Navigieren und DOM-Interaktion verwenden standardmäßig inaktive Tabs, sodass Routinearbeit Chrome nie in den Vordergrund holt. Übergib activate: true, wenn du tatsächlich Fokus benötigst.

• Umbra merkt sich ein dediziertes Chrome-Fenster für seine Tabs und leitet neue Sitzungs-Tabs dorthin. Es weigert sich, dieses Fenster wiederzuverwenden, solange es fokussiert ist, und fügt daher nie Tabs zu dem Fenster hinzu, in dem du arbeitest.

• Die Navigation ist an der Erweiterungsgrenze auf Schemata begrenzt: http:, https:, file: und about:blank sind erlaubt, und riskante Schemata wie javascript: und data: werden abgelehnt, bevor Chrome sie sieht.

• Bei Abschluss der Aufgabe sollte der Agent browser_close_session_tabs aufrufen, das die gesamte besessene Gruppe schließt. Es schließt ein ganzes Fenster nur, wenn jeder Tab in diesem Fenster zur Sitzung gehört, sodass nicht besessene leere Tabs überleben.

• Ein sauberes Herunterfahren des Servers führt standardmäßig dieselbe Bereinigung durch. Setze UMBRA_KEEP_TABS_OPEN=1 oder UMBRA_CLOSE_ON_SHUTDOWN=0, wenn ein Lauf Tabs zur Überprüfung offen lassen soll.

• Der Standard-Portbereich ist 47821-47852, was breit genug ist, dass gewöhnliche Multi-Agent-Arbeit nie ohne Platz dasteht. Die Erweiterung begrenzt einen konfigurierten Port auf 1024-65535; setze denselben Bereich auf beiden Seiten.

Was Umbra nicht tut

• Cookies ausgeben oder synchronisieren

• Tokens extrahieren

• Speicher-Lesen und -Schreiben als Tools bereitstellen

• im Hintergrund im Auftrag einer Seite abrufen

• CAPTCHAs lösen

• Lesezeichen, Verlauf oder Zwischenablage anfassen

• Native Messaging verwenden

• irgendetwas automatisch aktualisieren, automatisch pullen oder automatisch installieren

Bekannte Einschränkungen

• Standard-Screenshots aktivieren den von der Sitzung besessenen Tab vor der Aufnahme. silent: true vermeidet das, indem chrome.debugger für ein Page.captureScreenshot an den besessenen Tab angehängt wird, wodurch Chrome sein Automatisierungsbanner anzeigt.

• Site-Zugriff ist eine optionale Berechtigung, die über den Grant-Site-Access-Button auf der Optionsseite angefordert wird, nicht bei der Installation. Bis sie gewährt wird, schlagen Seitenlesungen und Screenshots mit Chromes eigenem Berechtigungsfehler fehl, da Chrome für die programmatische Erfassung sichtbarer Tabs eine explizite breite Host-Berechtigung benötigt. docs/permissions.md begründet jede Berechtigung, die die Erweiterung deklariert.

• Der Abschluss von Downloads wird durch Beobachten des Dateisystems erkannt, da die Erweiterung nicht die downloads-Berechtigung von Chrome anfordert. Richte UMBRA_DOWNLOAD_DIR auf den Download-Ordner deines Browsers, falls du ihn verschoben hast.

• browser_read_interactive ist bewusst kompakt. Umbra stellt keinen vollständigen Accessibility-Tree-Dump bereit.

• Generische Textklicks können bei dichten App-Oberflächen wie Suchpaginierung das falsche Steuerelement treffen. Verwende browser_read_interactive mit Referenzen oder browser_run_page_action mit inspect_controls und dann click_control, anstatt zu raten.

• Eine Änderung des Portbereichs erfordert ein Neuladen auf beiden Seiten: Starte den MCP-Client neu, damit neue Serverprozesse die Umgebung erben, und lade die entpackte Erweiterung neu, damit der persistierte Erweiterungsspeicher normalisiert wird.

Aufbau

• extension/ – MV3-Erweiterung: Background-Worker, Offscreen-Bridge, Content-Agent, Optionsseite, Popup

• extension/recipes/ – optionale seitenbezogene Page-Rezepte, bei Bedarf injiziert und im veröffentlichten Paket nicht enthalten

• mcp-server/ – Stdio-MCP-Server, Loopback-Bridge, Rust-Broker-Shim-Client und die lokale Entwicklungsumgebung

• rust-broker/ – Tokio-Broker-Laufzeit, die Sitzungen über eine einzige Erweiterungs-WebSocket multiplexiert

• tests/ – Abdeckung für Authentifizierung, Inhaberschaft, Sitzungsisolierung, Erweiterungslebenszyklus und Paketierung

• scripts/ – isolierter Chrome-Testprofil-Launcher und Smoke-Test-Wrapper

• launchd/ – Vorlage für den optionalen macOS-Job, der den Broker am Laufen hält

• docs/ – Installations-, Architektur-, Berechtigungs- und Smoke-Test-Hinweise

Dokumentation

• docs/install.md – Einrichtung vom Klon bis zu einer verbundenen Sitzung, plus jede Umgebungsvariable

• docs/architecture.md – Komponenten, Ablauf und die Begründung für die Aufteilung in Offscreen und Background

• docs/permissions.md – jede Chrome-Berechtigung mit ihrem Risiko und ihrer Gegenmaßnahme

• docs/smoke-test.md – automatisierte und manuelle Verifikationspfade

• docs/performance/performance-work.md – was der Performance-Durchgang geändert hat und was er gemessen hat

• MCP_PROTOCOL.md – das Drahtprotokoll zwischen Erweiterung und Server

• THREAT_MODEL.md – Assets, Vertrauensgrenzen, Angreifer und Gegenmaßnahmen

• SECURITY_REVIEW.md – Review-Haltung, die Behalten-Entfernen-Matrix und Ergebnisse des Upstream-Audits

• rust-broker/README.md – Broker-Umfang und wie man ihn ausführt

• rust-broker/LEGACY_FALLBACK.md – Rollback-Auslöser und die Form des Übergangs

Lies THREAT_MODEL.md und SECURITY_REVIEW.md, bevor du dies auf einen Browser richtest, der etwas enthält, das dir wichtig ist.