v0.3.4 — read_article, discard_tab, private windows, acquire_tab windowId

Bundles everything since v0.3.2: Reader View extraction, tab memory management,
private browsing window support, and windowed tab targeting — plus a native-host
concurrency fix.

Added

• read_article — extract clean article content from a page using Firefox's own
  Reader View engine (Mozilla's Readability.js). Returns {title, byline, siteName, excerpt, text, truncated}; not_an_article is a normal outcome for non-article
  pages, not a failure.
• discard_tab — unload one or more background tabs from memory
  (browser.tabs.discard). Tab and history are preserved; Firefox reloads it
  automatically next time it's focused. Idempotent, batched, does not require a
  lease (only blocks when leased by a different session). list_tabs gained
  discarded/lastAccessed fields to support this.
• open_private_window — open a new Firefox private browsing window and
  auto-lease its initial tab. Requires the extension's "Run in Private Windows"
  toggle enabled in about:addons (no API exists to flip this programmatically);
  without it, fails outright with private_window_access_denied. list_tabs
  gained an incognito field — private tabs only appear in the list at all once
  the toggle is on.
• acquire_tab windowId — open a new tab inside a specific existing window
  (e.g. a private window from open_private_window), instead of whatever window
  Firefox considers "current". list_tabs gained a windowId field so windows
  can be targeted. Rejects a private-window windowId combined with
  cookieStoreId (Multi-Account Containers don't exist in private windows) with
  a dedicated container_unavailable_in_private_window error.

Fixed

• native-host: closed a TOCTOU race in the singleton-lock takeover where two
  host processes starting concurrently against a stale lock could both believe
  they'd acquired it. Added regression tests exercising real concurrent process
  starts.
• Each feature above went through use-codex spec/plan review and a final
  whole-branch review before merging; see the design specs under
  docs/superpowers/specs/ for the specific issues each pass caught.

Install

Grab the .xpi below, drag into a Firefox window (or about:addons → gear icon →
"Install Add-on From File..."). Same add-on ID as prior releases, so this upgrades
an existing install in place — no need to remove the old one first.

v0.3.2

Adds three tab-lifecycle tools: close_tab, go_back, go_forward.

Added

• close_tab — close a tab this session has leased. Closing the last remaining tab
  in a window closes the window (expected, not a bug). The lease and any active
  start_console/start_network capture on the tab are cleared automatically.
• go_back / go_forward — navigate a leased tab through its browsing history, like
  the browser's own back/forward buttons. If the destination is on the blacklist, the
  same confirmation flow as navigate triggers; declining reverts the tab and returns
  blacklisted_denied.

Fixed (same batch, caught by final review before release)

• The initial go_back/go_forward implementation had no policy check at all, which
  could move a tab onto a blacklisted URL with zero confirmation. Fixed before this
  release shipped — see the design spec for detail.

Install

Grab the .xpi below, drag into a Firefox window (or about:addons → gear icon → "Install
Add-on From File..."). Same add-on ID as prior releases, so this upgrades an existing install
in place — no need to remove the old one first.

v0.3.1 — Interaction gaps, viewport tools, screenshot file-path, dialogOpened fix

Bundles everything since v0.2.0: the interaction-gaps batch, viewport tools, the
screenshot file-path fix, the to_be_deleted rename, and a real production bug fix
(click's dialogOpened false-positives on backgrounded tabs).

Added

• press_key / hover / drag_and_drop / upload_file — round out interactive-element
  coverage beyond click/type
• scroll_to — scroll an element or the page into view
• screenshot fullPage: true — capture the entire scrollable page in one shot instead
  of just the current viewport
• wait_for — poll a page to a target state (selector appears, text disappears, network
  idle) instead of guessing a fixed delay
• click/type/scroll_to/hover/upload_file/drag_and_drop/press_key now fall back
  to searching other frames when frameId is omitted
• list_elements includes table rows/headers as candidates, plus a per-element state
  object (checked/disabled/readonly/etc.) and domEpoch for detecting stale selectors
  across page changes

Changed

• screenshot now writes the PNG to a local file and returns its absolute path, instead
  of returning inline base64 — the inline-base64 response routinely blew past the calling
  model's context/token budget on real pages. Read the file directly instead of expecting
  image bytes in the tool response.
• move_to_pending_deletion renamed to to_be_deleted (same behavior — reversible move
  into a fixed "Pending Deletion" folder, never a real delete)
• acquire_tab waits for navigation to commit before returning url, instead of racing
  browser.tabs.create() and sometimes reporting about:blank

Fixed

• click's dialogOpened/domChanged fields were misreported on backgrounded tabs.
  Firefox throttles setTimeout/setInterval in a non-visible tab to a ~1000ms minimum
  interval, which made the click handler's dialog-detection heuristic time out and report a
  false dialogOpened: true even when the click succeeded normally. This was dangerous in
  practice: an agent reading dialogOpened: true could conclude the click didn't register
  and retry an already-successful destructive action (e.g. re-submitting a delete/apply on
  an admin panel). The fix detects tab visibility (tab.active AND the tab's window is
  OS-focused) and uses a longer timeout on backgrounded tabs instead of misreporting.

Install

Grab the .xpi below, drag into a Firefox window (or about:addons → gear icon → "Install
Add-on From File..."). Same add-on ID as prior releases, so this upgrades an existing install
in place — no need to remove the old one first.

v0.2.0 — History search, bookmarks, Multi-Account Containers

Added

• search_history — search Firefox browsing history
• add_bookmark / list_bookmarks / search_bookmarks — full bookmark read/write, with
  multi-level folder-path support across all four bookmark roots
• move_to_pending_deletion — reversible bookmark/folder cleanup tool (moves to a fixed
  "Pending Deletion" folder; never permanently deletes — see the bookmark-cleanup design spec)
• list_containers / create_container — Firefox Multi-Account Containers support
  (read + create only, no delete this round — see the containers design spec)
• acquire_tab / list_tabs now expose cookieStoreId, so a new tab can be opened inside a
  specific container and any tab's container membership is always visible

Changed

• Extension manifest bumped to 0.2.0 (new contextualIdentities/cookies permissions
  required for the containers feature — re-installing the .xpi below is required to pick
  these up over the previous 0.1.0 build)
• npm run sign shortcut + optional repo-root .env auto-load for AMO signing credentials

Install

Grab the .xpi below, drag into a Firefox window (or about:addons → gear icon → "Install
Add-on From File..."). Same add-on ID as prior releases, so this upgrades an existing install
in place — no need to remove the old one first.

v0.1.1 — Docs + AMO trademark fix

No functional/tool changes since v0.1.0 — the extension's version number stays 0.1.0 (not bumped), so the .xpi from that release is unchanged and reused here as-is.

Changed

• fix(extension): rename to avoid AMO trademark rejection — AMO's unlisted-signing submission rejected the manifest outright: "Add-on names cannot contain the Mozilla or Firefox trademarks." Renamed the extension's user-facing name from firefox-bridge to MCP Browser Bridge (the project/repo name, package names, and the gecko extension id are unaffected — those aren't the AMO-facing display name the trademark check applies to). This fix landed before the v0.1.0 .xpi was signed, so that asset already reflects it.
• docs: add README — the repo had no README since going public. Covers the why, architecture, tool list, and install steps (extension, native host, MCP server registration).
• docs: add MIT license — the repo had no LICENSE, meaning default all-rights-reserved copyright despite the intent being open source. Added MIT, matching this account's other projects, plus a license field on all three package.json files.

Install

Same as v0.1.0 — the .xpi and its checksum are re-attached to this release below for convenience.

v0.1.0 — Initial MVP

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).