# Firefox Bridge

<p><samp>Local Firefox control and debugging through the Model Context Protocol.</samp></p>

Read pages, interact with forms, manage tabs, and investigate browser issues through your AI assistant. Firefox Bridge connects your existing Firefox session to a local MCP server, with access rules you control in the extension.

**0.1.0 is being prepared for its first release.** Public downloads will be available after Mozilla signs the extension. The source workflow below is for development and testing.

[Demonstration](#demonstration) · [Quick start](#quick-start) · [Documentation](#documentation)

## Demonstration

The extension panel with example requests and site access controls.

<img src="docs/assets/panel.png" alt="Firefox Bridge panel showing automatic connection, pending requests, and expandable settings" width="360">

## Quick start

You need **Firefox 142+**, **Node.js 22+**, and an MCP client that supports local `stdio` servers. Windows includes setup helpers; see the [installation guide](docs/installation.md) for manual setup and platform limits.

### 1. Prepare the project

```sh
git clone https://github.com/matrodrigs/firefox-bridge.git
cd firefox-bridge
npm ci
npm run build
npm run setup
```

### 2. Connect Firefox and your client

1. In Firefox, open `about:debugging#/runtime/this-firefox`, choose **Load Temporary Add-on**, and select `extension/manifest.json`.
2. Open **Firefox Bridge**. The registered native host connects automatically; there is no pairing key to copy or manual reconnect step.
3. Enable access in the panel and review site permissions. Browsing defaults to all HTTP/HTTPS sites; specific blocks take precedence. Uploads, downloads, and debugging have separate grants.
4. Register the local MCP server with your client. For Codex, run `codex mcp add firefox-bridge -- node "<absolute-path>/dist/mcp.cjs"`. Other clients use the same command and absolute path. See [client setup](docs/installation.md#connect-a-client).

A temporary add-on disappears when Firefox restarts. Permanent installation in standard Firefox will use the signed XPI from the release. Local packaging produces an unsigned submission candidate, not a public release. See [installation and updates](docs/installation.md).

### 3. Make your first request

> Use Firefox Bridge. Check the connection, list my authorized tabs, and read the page I am working on. Show the available fields before changing anything.

For debugging, enable debug access for the target site in the panel, then ask your assistant to inspect an element, collect console errors, or examine request timings. Run `npm run doctor` to check local readiness. See the [workflows and examples](docs/workflows.md).

## Features

- **Work with pages:** read visible content and observed elements, fill forms, select options, use keyboard actions, and interact with open shadow roots.
- **Click with context:** use current element references, actionability checks, or coordinates tied to a recent screenshot.
- **Investigate issues:** collect console messages and page errors, inspect DOM and computed styles, and examine performance and network metadata.
- **Manage your browser:** work with tabs, frames, tab groups, bookmarks, history, HTML5 media, and controlled file transfers.
- **Connect automatically:** use Firefox native messaging, authenticated local transport, per-origin access rules, and pause/release controls.

See the [capability and tool reference](docs/reference.md) for limits and permissions.

## Access controls

The extension starts paused. Once enabled, the panel's browsing default and exact-origin rules determine access. The assistant cannot change permissions or retrieve internal credentials through MCP. Private tabs and protected browser pages are excluded.

Element references belong to a page snapshot; screenshot coordinates belong to a recent capture. Navigation and permission changes invalidate operations. If an action times out after delivery, inspect the page before repeating it: the action may already have occurred.

Read the [behavioral specification](docs/spec.md) for authorization, observation, and recovery rules.

## Limitations

- Input events are synthetic. Websites requiring trusted input, native dialogs, closed shadow roots, or browser chrome can require manual interaction.
- Debugging covers page instrumentation and browser-exposed metadata. It does not provide a CDP session, JavaScript breakpoints, arbitrary evaluation, or a complete DevTools replacement.
- Console collection begins when started, is bounded and temporary, and can be affected by page code. Network inspection excludes headers, cookies, bodies, and URL query strings.
- Uploads require files chosen in the extension panel. Downloads accept direct URLs with size limits. See the [reference](docs/reference.md#file-transfers).

## Documentation

| Guide | What you will find |
| --- | --- |
| [Installation](docs/installation.md) | Requirements, client setup, updates, and troubleshooting |
| [Workflows and examples](docs/workflows.md) | Page interaction, debugging, and file transfers |
| [Technical reference](docs/reference.md) | Tools, permissions, limits, and configuration |
| [Behavioral specification](docs/spec.md) | Authorization, lifecycle, and compatibility contracts |
| [Architecture](docs/architecture.md) | Module responsibilities and dependency direction |

Clients receive complete tool schemas and guidance at runtime. Most users can work through natural-language requests.

## Development

See [Contributing](CONTRIBUTING.md) for quality checks, real Firefox integration tests, and packaging; [Changelog](CHANGELOG.md) for changes; [Issues](https://github.com/matrodrigs/firefox-bridge/issues) for bugs; and [Security](SECURITY.md) for reporting guidance.

## License

Licensed under the [MIT License](LICENSE). This is an independent community project, not affiliated with or endorsed by Mozilla or OpenAI. Firefox is a trademark of the Mozilla Foundation. This repository contains no code from OpenAI's Chrome extension.

<sub>Created by <a href="https://github.com/matrodrigs">matrodrigs</a>.</sub>