Skip to content

v0.1.0 — Initial MVP

Choose a tag to compare

View all tags
@raychao-oao raychao-oao released this 01 Aug 15:19
v0.1.0
13557b4

Initial MVP: lets MCP-capable CLIs (Claude Code, Codex, etc.) operate your real, already-logged-in Firefox tabs — a claude-in-chrome-style bridge, but for Firefox, and without any OS-level input simulation.

Architecture

3-tier bridge: MCP Server ↔ Unix socket (token-authenticated) ↔ Native Host ↔ Native Messaging ↔ Firefox Extension. Tab-lease concurrency for multiple simultaneous sessions, a central policy gate with a blacklist + one-time confirmation popup for sensitive sites, and a temp-file/opaque-handle payload path for large data like screenshots.

Tools

navigate, click, type, read_page, list_elements, list_frames, screenshot, start_console/get_console, start_network/get_network, acquire_tab/release_tab, list_tabs.

  • list_elements discovers real CSS selectors for interactive elements instead of guessing blindly — each one is guaranteed to match exactly the inspected element on a follow-up click/type.
  • click/type/read_page/list_elements are frame-aware: they can target a specific <iframe> (via list_frames for discovery), and each frame is gated by its own blacklist policy independently.
  • Live-tested against real websites and a real LAN router admin UI (plain-HTTP, nested iframes) — not just synthetic test pages.

Known limitations

  • list_tabs isn't policy-gated yet (returns all tab URLs/titles, including blacklisted ones)
  • Console/network capture is top-frame only, not frame-aware
  • Text truncation is char-count-based, not byte-based (risk on CJK-heavy pages)
  • WebMCP integration deferred to a future version

Install

1. Firefox extension

This release includes a signed, permanently-installable .xpi:

  • Download e8496ece122b4f71ad17-0.1.0.xpi from this release's assets below
  • (Optional) verify its integrity: shasum -a 256 -c e8496ece122b4f71ad17-0.1.0.xpi.sha256
  • Drag the .xpi into a Firefox window, or about:addons → gear icon → "Install Add-on From File..."
  • Unlike loading extension/manifest.json as a Temporary Add-on via about:debugging, this survives Firefox restarts

To build and sign your own .xpi from source instead (e.g. after making changes): get an API key/secret from AMO, then AMO_API_KEY=... AMO_API_SECRET=... node scripts/sign-extension.js.

2. Native messaging host

node scripts/install-native-manifest.js

Registers the native messaging manifest so Firefox can spawn the native host. Restart Firefox after this and after installing the extension.

3. MCP server

Register with Claude Code (or any MCP-capable CLI):

claude mcp add firefox-bridge -s user -- node mcp-server/src/index.js

-s user makes it available in every session, not just this repo. Verify with claude mcp list — should show firefox-bridge: ... - ✔ Connected once the extension is loaded and connected.

44/44 automated tests passing (native-host + mcp-server; the extension itself has no automated harness, see docs/manual-verification-checklist.md).

Assets 4
Loading