ff-mcp

ff-mcp gibt lokalen MCP-Clients kontrollierten Zugriff auf das Firefox-Profil, das Sie bereits verwenden. Es besteht aus einer Firefox-Manifest-V3-WebExtension und einem Python-Native-Messaging-Host, der MCP über Streamable HTTP auf 127.0.0.1 bereitstellt.

Die Erweiterung – nicht der Localhost-Prozess – ist die endgültige Autorisierungsgrenze. Das Auflisten von Tab-Metadaten gewährt keinen Zugriff auf Seiteninhalte. Lesen, Interaktion und Screenshots erfordern unabhängige, widerrufbare Fähigkeiten.

Aktuelle Fähigkeiten

• Tab-Metadaten ohne Seitenzugriff auflisten.

• READ, INTERACT, SCRIPT und SCREENSHOT für einen bestimmten Tab anfordern.

• Zugriff einmalig, für ein Dokument, für eine Tab-Sitzung oder dauerhaft für einen Host gewähren.

• Begrenzte serialisierte Snapshots und CSS-Query-Ergebnisse lesen. Live-DOM-Objekte überqueren die Brücke nie.

• Klicken, Tippen, Scrollen und Navigieren durch strukturierte Operationen.

• Einen Tab nur mit einer separaten Screenshot-Genehmigung erfassen.

• Beliebigen JavaScript-Code in der isolierten User-Script-Welt oder der Hauptwelt der Seite nur mit einer separaten SCRIPT-Genehmigung und Firefox' optionaler userScripts-Berechtigung ausführen.

• Dauerhafte Richtlinien mit host-, glob-, regex- und scheme-Prädikaten abgleichen, die mit AND, OR und NOT verknüpft sind.

• Autorisierungsentscheidungen und sensible Operationen in Firefox protokollieren.

• MCP nur an Loopback binden, ein generiertes Bearer-Token verlangen und HTTP-Origins standardmäßig ablehnen.

Anforderungen

• Firefox 150 oder neuer.

• Python 3.14 (das Paket ist auf die Minor-Linie 3.14 festgelegt).

• uv wird für die Installation empfohlen.

Einmalige SCRIPT-Ausführung erfordert Firefox 153 oder neuer, da diese Version userScripts.execute() eingeführt hat. Die übrigen Fähigkeiten unterstützen Firefox 150 und neuer.

Installation aus einem Checkout

Installieren Sie den nativen Begleiter als dauerhaftes Tool und registrieren Sie ihn dann bei Firefox:

uv tool install .
ff-mcp install-native

Für die Entwicklung laden Sie extension/manifest.json über about:debugging → Dieses Firefox → Temporäres Add-on laden.

Öffnen Sie das Popup der ff-mcp-Symbolleiste und klicken Sie auf Start. Der erste Start erstellt eine private Konfigurationsdatei mit einem zufälligen Token:

• Linux: $XDG_CONFIG_HOME/ff-mcp/config.json oder ~/.config/ff-mcp/config.json

• macOS: ~/.config/ff-mcp/config.json

• Windows: %APPDATA%\ff-mcp\config.json

Das Popup zeigt ein generisches Verbindungsobjekt an und kann es kopieren:

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_GENERATED_TOKEN"
  }
}

Konfigurieren Sie diese Werte in einem MCP-Client, der Streamable HTTP und benutzerdefinierte Header unterstützt. Der Endpunkt existiert nur, solange die Erweiterung ihre Native-Messaging-Verbindung offen hält.

Berechtigungsablauf

1. Rufen Sie browser_tabs auf und wählen Sie eine Tab-ID.

2. Rufen Sie browser_request_access mit einer oder mehreren Fähigkeiten auf.

3. Genehmigen Sie die Anfrage in der Firefox-Symbolleiste.

4. Rufen Sie das Lese-, Interaktions- oder Screenshot-Tool auf.

5. Widerrufen Sie die Genehmigung über die Symbolleiste oder mit browser_revoke.

READ ist standardmäßig nur für localhost, Subdomains von .localhost, 127.0.0.0/8 und ::1 erlaubt. Diese Standardeinstellung beinhaltet keine Interaktion, Skriptausführung oder Screenshots.

Policy-Regeln

Die Optionsseite enthält einen visuellen Policy-Editor. Jede neue Regel beginnt mit einem Haupt-AND-Container, der eine OR-Erlaubnisgruppe und eine NAND-Ausschlussgruppe enthält. Fügen Sie Host-, URL-Muster-, Regex- oder Scheme-Bedingungen hinzu; verschachteln Sie bei Bedarf weitere AND-, OR-, NAND- oder NOR-Container; und wählen Sie dann die Fähigkeiten aus, die die passende Regel gewährt.

Leere nicht-negierte Container entsprechen nichts. Leere negierte Container entsprechen allem, daher bleibt eine neue Regel inaktiv, bis ihre Erlaubnisgruppe mindestens eine Bedingung enthält. Die immer aktive localhost-READ-Regel wird separat angezeigt und kann nicht bearbeitet oder entfernt werden.

Vorhandene ausdrucksbasierte Regeln werden beim Öffnen der Einstellungsseite in den visuellen Baum überführt. Das Ausdrucksformat bleibt aus Gründen der Abwärtskompatibilität die gespeicherte Darstellung.

Regex-Muster sind in der Länge begrenzt und lehnen Rückreferenzen, Lookarounds und offensichtliche verschachtelte Quantoren ab. Dies ist eine Sicherheits-Teilmenge, keine vollständige RE2-Implementierung.

Entwicklung

UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv sync --group dev
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q
# Opt-in: launches the installed Firefox headlessly with a fresh temporary profile.
FF_MCP_RUN_FIREFOX_TESTS=1 UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q tests/test_firefox_integration.py
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff check .
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff format --check .
node tests/policy.test.js
node tests/rule-model.test.js
node tests/background.test.js
node tests/content.test.js
node --check extension/background.js
node --check extension/content.js
node --check extension/options.js
node --check scripts/check-web-ext-lint.js

Setzen Sie FIREFOX_BINARY für Installationen, die Selenium nicht automatisch finden kann. Der Integrationstest erkennt den standardmäßigen Linux-Snap-Speicherort ohne zusätzliche Konfiguration.

Die Firefox-Erweiterung hat keine Laufzeitabhängigkeiten von Drittanbietern und keinen Build-Schritt.

Releases

Tags mit dem Namen vX.Y.Z führen den Release-Workflow aus. Die Tag-Version muss sowohl mit project.version in pyproject.toml als auch mit version in extension/manifest.json übereinstimmen. Der Workflow fordert Mozilla Add-ons auf, die Erweiterung auf dem unlisted-Kanal zu signieren, überprüft das zurückgegebene XPI und hängt das signierte XPI sowie seine SHA-256-Prüfsumme an ein GitHub-Release an. Die erzeugten Artefakte bleiben unversioniert.

Konfigurieren Sie diese Secrets in der release-Umgebung des Repositorys, bevor Sie einen Tag pushen:

• AMO_JWT_ISSUER: der Issuer aus einer AMO-API-Anmeldeinformation.

• AMO_JWT_SECRET: das zugehörige AMO-API-Secret.

Erstellen Sie die Zugangsdaten über die AMO-API-Schlüsselseite. Unlisted-Signierung veröffentlicht die Erweiterung nicht in der AMO-Suche oder in den Auflistungen.

Sicherheitsgrenzen

• Die Erweiterung fordert notwendigerweise breiten Website-Zugriff an, um beliebige Tabs zu vermitteln und die Screenshot-API von Firefox für Hintergrund-Tabs zu nutzen. Daher sind ihre internen Fähigkeitsprüfungen entscheidend.

• Genehmigte Browser-Metadaten, Website-Inhalte und Website-Aktivitäten werden an den lokalen nativen Host und den MCP-Client übertragen. AMO deklariert diese erforderlichen Datenkategorien während der Installation.

• Von Firefox eingeschränkte Seiten wie about: und der Add-ons-Store können von Content-Scripts nicht gelesen werden.

• Eine Tab-Sitzungs-Genehmigung übersteht eine Navigation in diesem Tab absichtlich; Dokument-Genehmigungen nicht.

• Die MCP-Client-Identität ist innerhalb der einen Bearer-Token-Vertrauensdomäne deskriptiv. Verwenden Sie eine separate Konfiguration und ein separates Token, wenn lokale Clients, die einander nicht vertrauen, isoliert werden müssen.

• Strukturierte Klicks und Eingaben können weiterhin Seitenverhalten auslösen. Gewähren Sie INTERACT sparsam.

• SCRIPT bedeutet praktisch die vollständige Kontrolle über die Seite. Firefox fragt während der Genehmigung nach seiner optionalen userScripts-Berechtigung, und ff-mcp verlangt weiterhin eine separate Tab-Fähigkeit. MAIN-Welt-Skripte können auf den JavaScript-Zustand der Seite zugreifen und ihn verändern; gewähren Sie dies nur Clients und Websites, denen Sie vertrauen.

Siehe firefox_mcp_extension_findings.html für die Designforschung, die dieser Implementierung vorausging.

Lizenz

MIT. Siehe LICENSE und THIRD_PARTY.md.