# Directory Structure
```
├── .github
│ ├── addon_badge.svg
│ └── workflows
│ └── release.yml
├── .gitignore
├── CLAUDE.md
├── common
│ ├── extension-messages.ts
│ ├── index.ts
│ └── server-messages.ts
├── CONTRIBUTING.md
├── Dockerfile
├── firefox-extension
│ ├── __tests__
│ │ ├── message-handler.test.ts
│ │ └── setup.ts
│ ├── assets
│ │ └── caret.svg
│ ├── auth.ts
│ ├── background.ts
│ ├── client.ts
│ ├── extension-config.ts
│ ├── jest.config.js
│ ├── manifest.json
│ ├── message-handler.ts
│ ├── nx.json
│ ├── options.html
│ ├── options.ts
│ ├── package-lock.json
│ ├── package.json
│ ├── tsconfig.json
│ └── types
│ └── browserTabGroups.d.ts
├── LICENSE
├── mcp-server
│ ├── browser-api.ts
│ ├── manifest.json
│ ├── package-lock.json
│ ├── package.json
│ ├── server.ts
│ ├── tsconfig.json
│ └── util.ts
├── nx.json
├── package-lock.json
├── package.json
├── pnpm-workspace.yaml
└── README.md
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
.pnpm-debug.log*
# Dependency directories
node_modules/
jspm_packages/
# TypeScript cache
*.tsbuildinfo
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional stylelint cache
.stylelintcache
# dotenv environment variable files and config files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local
dist
.temp
.cache
# Stores VSCode versions used for testing VSCode extensions
.vscode
.vscode-test
# yarn v2
.yarn/cache
.yarn/unplugged
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*
.nx
# DXT
*.dxt
# Web extension dist
web-ext-artifacts/
.DS_Store
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# Browser Control MCP
[](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/)
An MCP server paired with a Firefox browser extension that provides AI assistants with access to tab management, browsing history, and webpage text content.
## Features
The MCP server supports the following tools:
- Open or close tabs
- Get the list of opened tabs
- Create tab groups with name and color
- Reorder opened tabs
- Read and search the browser's history
- Read a webpage's text content and links (requires user consent)
- Find and highlight text in a browser tab (requires user consent)
## Example use-cases:
### Tab management
- *"Close all non-work-related tabs in my browser."*
- *"Group all development related tabs in my browser into a new group called 'Development'."*
- *"Rearrange tabs in my browser in an order that makes sense."*
- *"Close all tabs in my browser that haven't been accessed within the past 24 hours"*
### Browser history search
- *"Help me find an article in my browser history about the Milford track in NZ."*
- *"Open all the articles about AI that I visited during the last week, up to 10 articles, avoid duplications."*
### Browsing and research
- *"Open hackernews in my browser, then open the top story, read it, also read the comments. Do the comments agree with the story?"*
- *"In my browser, use Google Scholar to search for papers about L-theanine in the last 3 years. Open the 3 most cited papers. Read them and summarize them for me."*
- *"Use Google search in my browser to look for flower shops. Open the 10 most relevant results. Show me a table of each flower shop with location and opening hours."*
## Comparison to web automation MCP servers
The MCP server and Firefox extension combo is designed to be more secure than web automation MCP servers, enabling safer use with the user's personal browser.
* It does not support web page modification, page interactions, or arbitrary scripting.
* Reading webpage content requires the user's explicit consent in the browser for each domain. This is enforced at the extension's manifest level.
* It uses a local-only connection with a shared secret between the MCP server and extension.
* No remote data collection or tracking.
* It provides an extension-side audit log for tool calls and tool enable/disable configuration.
* The extension includes no runtime third-party dependencies.
**Important note**: Browser Control MCP is still experimental. Use at your own risk. You should practice caution as with any other MCP server and authorize/monitor tool calls carefully.
## Installation
Update: Due to [an issue with MCP startup](https://github.com/modelcontextprotocol/servers/issues/812), the MCP server does not currently work with **Claude Desktop**.
### Option 1: Install the Firefox and Claude Desktop extensions
The Firefox extension / add-on is [available on addons.mozilla.org](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/). You can also download and open the latest pre-built version from this GitHub repository: [browser-control-mcp-1.5.0.xpi](https://github.com/eyalzh/browser-control-mcp/releases/download/v1.5.0/browser-control-1.5.0.xpi). Complete the installation based on the instructions in the "Manage extension" page, which will open automatically after installation.
The add-on's "Manage extension" page will include a link to the Claude Desktop DXT file. You can also download it here: [mcp-server-v1.5.1.dxt](
https://github.com/eyalzh/browser-control-mcp/releases/download/v1.5.1/mcp-server-v1.5.1.dxt). After downloading the file, open it or drag it into Claude Desktop's settings window. Make sure to enable the DXT extension after installing it. This will only work with the latest versions of Claude Desktop. If you wish to install the MCP server locally, see the MCP configuration below.
### Option 2: Build from code
To build from code, clone this repository, then run the following commands in the main repository directory to build both the MCP server and the browser extension.
```
npm install
npm run build
```
#### Installing a Firefox Temporary Add-on
To install the extension on Firefox as a Temporary Add-on:
1. Type `about:debugging` in the Firefox URL bar
2. Click on "This Firefox"
3. click on "Load Temporary Add-on..."
4. Select the `manifest.json` file under the `firefox-extension` folder in this project
5. The extension's preferences page will open. Copy the secret key to your clipboard. It will be used to configure the MCP server.
Alternatively, to install a permanent add-on, you can install the [Browser Control MCP on addons.mozilla.org](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/) and then configure the MCP Server as detailed below.
If you prefer not to run the extension on your personal Firefox browser, an alternative is to download a separate Firefox instance (such as Firefox Developer Edition, available at https://www.mozilla.org/en-US/firefox/developer/).
#### MCP Server configuration
After installing the browser extension, add the following configuration to your mcpServers configuration (e.g. `claude_desktop_config.json` for Claude Desktop):
```json
{
"mcpServers": {
"browser-control": {
"command": "node",
"args": [
"/path/to/repo/mcp-server/dist/server.js"
],
"env": {
"EXTENSION_SECRET": "<secret_on_firefox_extension_options_page>",
"EXTENSION_PORT": "8089"
}
}
}
}
```
Replace `/path/to/repo` with the correct path.
Set the EXTENSION_SECRET to the value shown on the extension's preferences page in Firefox (you can access it at `about:addons`). You can also set the EXTENSION_PORT environment variable to specify the port that the MCP server will use to communicate with the extension (default is 8089).
It might take a few seconds for the MCP server to connect to the extension.
##### Configure the MCP server with Docker
Alternatively, you can use a Docker-based configuration. To do so, build the mcp-server Docker image:
```
docker build -t browser-control-mcp .
```
and use the following mcpServers configuration:
```json
{
"mcpServers": {
"browser-control": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-p", "127.0.0.1:8089:8089",
"-e", "EXTENSION_SECRET=<secret_from_extension>",
"-e", "CONTAINERIZED=true",
"browser-control-mcp"
]
}
}
}
```
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
# Contributing to Browser Control MCP
We welcome pull requests for adding new features and tools to the extension, as well as for bug fixes.
## Development Guidelines
### Testing Requirements
- Make sure to update the Firefox extension unit tests when making changes
- Test the MCP server integration with Claude Desktop
- Test the Firefox extension on Firefox Developer Edition
### Compatibility
- Keep backwards and forward compatibility in mind when making changes
- Ensure changes work across different versions of Firefox and Claude Desktop
### Security and Privacy
Security and privacy are the core design principles of this solution. Please ensure that:
- All browser interactions require explicit user consent
- No sensitive data is logged or transmitted unnecessarily
- Extension permissions are minimal and justified
- WebSocket communication uses proper authentication
## Getting Started
See the main README.md for setup instructions and the CLAUDE.md file for development commands.
## Pull Request Process
1. Fork the repository
2. Create a feature branch
3. Make your changes with appropriate tests
4. Run the test suite: `cd firefox-extension && npm test`
5. Build all projects: `npm run build`
6. Test manually with Claude Desktop and Firefox Developer Edition
7. Submit a pull request with a clear description of changes
```
--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
```markdown
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Commands
### Installation
```bash
npm install # Install all dependencies (includes subproject dependencies)
```
### Build
```bash
npm run build # Build all projects using nx
```
### Individual project builds
```bash
# MCP Server
cd mcp-server && npm run build
# Firefox Extension
cd firefox-extension && npm run build
```
### Test
```bash
cd firefox-extension && npm test
```
### Start MCP Server
```bash
cd mcp-server && npm start
```
### Package DXT
```bash
cd mcp-server && npm run pack-dxt
```
## Architecture
This is a monorepo with three main components:
1. **mcp-server**: Node.js MCP server that communicates with Claude Desktop and the browser extension via WebSocket
2. **firefox-extension**: Firefox browser extension that executes browser actions
3. **common**: Shared TypeScript interfaces for message passing between server and extension
### Communication Flow
- MCP Server ↔ Claude Desktop: MCP protocol over stdio
- MCP Server ↔ Firefox Extension: WebSocket with authentication via shared secret
- Extension uses Firefox WebExtensions API for browser control
### Key Files
- `mcp-server/server.ts`: Main MCP server with tool definitions
- `mcp-server/browser-api.ts`: WebSocket client for extension communication
- `firefox-extension/background.ts`: Extension background script
- `firefox-extension/message-handler.ts`: Handles server messages and executes browser actions
- `common/server-messages.ts`: Messages sent from server to extension
- `common/extension-messages.ts`: Messages sent from extension to server
### Authentication
The extension generates a random secret key that must be configured in the MCP server's environment as `EXTENSION_SECRET`. The server connects to the extension on port 8089 (configurable via `EXTENSION_PORT`).
### Development Notes
- Uses esbuild for extension bundling
- TypeScript throughout with shared interfaces
- Jest for testing (extension only)
- Nx for monorepo management
- Extension requires user consent for accessing webpage content by default
```
--------------------------------------------------------------------------------
/pnpm-workspace.yaml:
--------------------------------------------------------------------------------
```yaml
packages:
- 'firefox-extension'
- 'mcp-server'
```
--------------------------------------------------------------------------------
/firefox-extension/nx.json:
--------------------------------------------------------------------------------
```json
{
"$schema": "./node_modules/nx/schemas/nx-schema.json"
}
```
--------------------------------------------------------------------------------
/nx.json:
--------------------------------------------------------------------------------
```json
{
"$schema": "./node_modules/nx/schemas/nx-schema.json"
}
```
--------------------------------------------------------------------------------
/common/index.ts:
--------------------------------------------------------------------------------
```typescript
export * from "./server-messages";
export * from "./extension-messages";
```
--------------------------------------------------------------------------------
/firefox-extension/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "commonjs",
"outDir": "dist/",
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"strict": true,
"skipLibCheck": true
}
}
```
--------------------------------------------------------------------------------
/mcp-server/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "commonjs",
"outDir": "dist/",
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"strict": true,
"skipLibCheck": true
}
}
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "browser-control-mcp",
"version": "1.5.0",
"private": true,
"scripts": {
"postinstall": "npm install --prefix mcp-server && npm install --prefix firefox-extension",
"build": "nx run-many --target=build --all --parallel"
},
"devDependencies": {
"nx": "20.6.0"
}
}
```
--------------------------------------------------------------------------------
/firefox-extension/assets/caret.svg:
--------------------------------------------------------------------------------
```
<?xml version="1.0" encoding="utf-8"?>
<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
<svg width="800px" height="800px" viewBox="0 0 1024 1024" class="icon" version="1.1" xmlns="http://www.w3.org/2000/svg"><path d="M106.666667 659.2L172.8 725.333333 512 386.133333 851.2 725.333333l66.133333-66.133333L512 256z" fill="#2196F3" /></svg>
```
--------------------------------------------------------------------------------
/firefox-extension/jest.config.js:
--------------------------------------------------------------------------------
```javascript
/** @type {import('ts-jest').JestConfigWithTsJest} */
module.exports = {
preset: 'ts-jest',
testEnvironment: 'jsdom',
setupFilesAfterEnv: ['<rootDir>/__tests__/setup.ts'],
moduleNameMapper: {
'^@browser-control-mcp/common$': '<rootDir>/../common'
},
transform: {
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: 'tsconfig.json',
}],
},
testMatch: ['**/__tests__/**/*.test.ts'],
};
```
--------------------------------------------------------------------------------
/firefox-extension/manifest.json:
--------------------------------------------------------------------------------
```json
{
"manifest_version": 2,
"name": "Browser Control MCP",
"version": "1.5.0",
"description": "An extension that allows a local MCP server to perform actions on the browser.",
"permissions": [
"tabs",
"tabGroups",
"history",
"storage"
],
"optional_permissions": [
"*://*/*",
"find"
],
"background": {
"scripts": ["dist/background.js"]
},
"options_ui": {
"page": "options.html"
}
}
```
--------------------------------------------------------------------------------
/mcp-server/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "mcp-server",
"version": "1.5.1",
"main": "dist/server.js",
"engines": {
"node": ">=22.0.0"
},
"scripts": {
"build": "tsc",
"start": "node dist/server.js",
"pack-dxt": "npx @anthropic-ai/dxt pack"
},
"license": "MIT",
"description": "Browser Control MCP Server",
"dependencies": {
"@browser-control-mcp/common": "../common",
"@modelcontextprotocol/sdk": "^1.7.0",
"dayjs": "^1.11.13",
"readline": "^1.3.0",
"ws": "^8.18.1"
},
"devDependencies": {
"@types/ws": "^8.18.0",
"typescript": "^5.8.2"
}
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
FROM node:22-alpine
# Set working directory
WORKDIR /app
# Copy package files for dependency installation
COPY mcp-server/package*.json ./mcp-server/
# Copy common directory (shared dependency)
COPY common/ ./common/
# Set working directory to mcp-server for installation
WORKDIR /app/mcp-server
# Install dependencies
RUN npm install
# Copy mcp-server source code
COPY mcp-server/ ./
# Build mcp-server
RUN npm run build
# Set default port (EXTENSION_SECRET should be provided at runtime)
ENV EXTENSION_PORT=8089
# Expose port (default WebSocket port for extension communication)
EXPOSE 8089
# Start the MCP server
CMD ["npm", "start"]
```
--------------------------------------------------------------------------------
/firefox-extension/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "firefox-extension",
"version": "1.5.0",
"main": "dist/background.js",
"scripts": {
"build": "esbuild background.ts --bundle --outfile=dist/background.js && esbuild options.ts --bundle --outfile=dist/options.js",
"test": "jest"
},
"license": "MIT",
"description": "Browser Control MCP Firefox Extension / Add-on",
"devDependencies": {
"@types/jest": "^29.5.14",
"esbuild": "0.25.1",
"jest": "^30.0.4",
"jest-environment-jsdom": "^30.0.4",
"nx": "20.6.0",
"ts-jest": "^29.4.0",
"typescript": "^5.8.2",
"@types/firefox-webext-browser": "^120.0.4",
"@browser-control-mcp/common": "../common"
},
"nx": {}
}
```
--------------------------------------------------------------------------------
/firefox-extension/auth.ts:
--------------------------------------------------------------------------------
```typescript
function buf2hex(buffer: ArrayBuffer) {
return Array.from(new Uint8Array(buffer))
.map((x) => x.toString(16).padStart(2, "0"))
.join("");
}
export async function getMessageSignature(
message: string,
secretKey: string
): Promise<string> {
if (secretKey.length === 0) {
throw new Error("Secret key is empty");
}
const encoder = new TextEncoder();
const keyData = encoder.encode(secretKey);
const messageData = encoder.encode(message);
const key = await crypto.subtle.importKey(
"raw",
keyData,
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"]
);
const rawSignature = await crypto.subtle.sign(
{ name: "HMAC" },
key,
messageData
);
return buf2hex(rawSignature);
}
```
--------------------------------------------------------------------------------
/firefox-extension/types/browserTabGroups.d.ts:
--------------------------------------------------------------------------------
```typescript
// See: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabGroups/update
// This is a partial type representation of the browser.tabGroups API.
declare namespace browser.tabGroups {
type Color =
| "blue"
| "cyan"
| "grey"
| "green"
| "orange"
| "pink"
| "purple"
| "red"
| "yellow";
interface TabGroup {
id: number;
}
interface GroupUpdateProperties {
collapsed?: boolean;
color?: Color;
title?: string;
}
function update(
groupId: number,
updateProperties: GroupUpdateProperties
): Promise<TabGroup>;
}
declare namespace browser.tabs {
interface GroupOptions {
tabIds: number[];
}
function group(options: GroupOptions): Promise<number>;
}
```
--------------------------------------------------------------------------------
/firefox-extension/__tests__/setup.ts:
--------------------------------------------------------------------------------
```typescript
// Jest setup file for browser API mocking
// Mock the browser API completely
const mockBrowser = {
tabs: {
create: jest.fn(),
remove: jest.fn(),
query: jest.fn(),
get: jest.fn(),
executeScript: jest.fn(),
move: jest.fn(),
update: jest.fn(),
group: jest.fn(),
},
tabGroups: {
update: jest.fn(),
},
history: {
search: jest.fn(),
},
find: {
find: jest.fn(),
highlightResults: jest.fn(),
},
storage: {
local: {
get: jest.fn(),
set: jest.fn(),
},
},
permissions: {
contains: jest.fn(),
},
runtime: {
getURL: jest.fn(),
},
};
// Override the global browser object
Object.defineProperty(global, 'browser', {
value: mockBrowser,
writable: true,
configurable: true,
});
// Export for use in tests
export { mockBrowser };
```
--------------------------------------------------------------------------------
/mcp-server/util.ts:
--------------------------------------------------------------------------------
```typescript
import * as net from 'net';
export function isPortInUse(port: number) {
return new Promise((resolve) => {
const server = net.createServer();
server.once('error', (err: NodeJS.ErrnoException) => {
// If the error is because the port is already in use
if (err.code === 'EADDRINUSE') {
resolve(true);
} else {
// Some other error occurred
console.error('Error checking port:', err);
resolve(false);
}
});
server.once('listening', () => {
// If we get here, the port is free
// Close the server and resolve with false (port not in use)
server.close(() => {
resolve(false);
});
});
// Try to listen on the port (bind to localhost)
server.listen(port, 'localhost');
});
}
```
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
```yaml
name: Build and Release MCP Server as DXT
on:
release:
types: [published]
jobs:
build-and-upload:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: 'npm'
- name: Install root dependencies
run: npm install
- name: Install MCP server dependencies
run: npm install --prefix mcp-server
- name: Build MCP server package
run: cd mcp-server && npm run build && npm run pack-dxt
- name: Rename package file with version
run: |
cd mcp-server
mv mcp-server.dxt mcp-server-${{ github.event.release.tag_name }}.dxt
- name: Upload package to release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh release upload ${{ github.event.release.tag_name }} \
./mcp-server/mcp-server-${{ github.event.release.tag_name }}.dxt \
--clobber
```
--------------------------------------------------------------------------------
/.github/addon_badge.svg:
--------------------------------------------------------------------------------
```
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="140" height="20" role="img" aria-label="Firefox Add-on: v1.5.0">
<title>Firefox Add-on: v1.5.0</title>
<a href="https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/" target="_blank">
<linearGradient id="s" x2="0" y2="100%">
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
<stop offset="1" stop-opacity=".1"/>
</linearGradient>
<clipPath id="r">
<rect width="140" height="20" rx="3" fill="#fff"/>
</clipPath>
<g clip-path="url(#r)">
<rect width="89" height="20" fill="#555"/>
<rect x="89" width="51" height="20" fill="#6a7d8a"/>
<rect width="140" height="20" fill="url(#s)"/>
</g>
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
<text aria-hidden="true" x="455" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="790">Firefox Add-on</text>
<text x="455" y="140" transform="scale(.1)" fill="#fff" textLength="790">Firefox Add-on</text>
<text aria-hidden="true" x="1135" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="410">v1.5.0</text>
<text x="1135" y="140" transform="scale(.1)" fill="#fff" textLength="410">v1.5.0</text>
</g>
</a>
</svg>
```
--------------------------------------------------------------------------------
/common/server-messages.ts:
--------------------------------------------------------------------------------
```typescript
export interface ServerMessageBase {
cmd: string;
}
export interface OpenTabServerMessage extends ServerMessageBase {
cmd: "open-tab";
url: string;
}
export interface CloseTabsServerMessage extends ServerMessageBase {
cmd: "close-tabs";
tabIds: number[];
}
export interface GetTabListServerMessage extends ServerMessageBase {
cmd: "get-tab-list";
}
export interface GetBrowserRecentHistoryServerMessage extends ServerMessageBase {
cmd: "get-browser-recent-history";
searchQuery?: string;
}
export interface GetTabContentServerMessage extends ServerMessageBase {
cmd: "get-tab-content";
tabId: number;
offset?: number;
}
export interface ReorderTabsServerMessage extends ServerMessageBase {
cmd: "reorder-tabs";
tabOrder: number[];
}
export interface FindHighlightServerMessage extends ServerMessageBase {
cmd: "find-highlight";
tabId: number;
queryPhrase: string;
}
export interface GroupTabsServerMessage extends ServerMessageBase {
cmd: "group-tabs";
tabIds: number[];
isCollapsed: boolean;
groupColor: string;
groupTitle: string;
}
export type ServerMessage =
| OpenTabServerMessage
| CloseTabsServerMessage
| GetTabListServerMessage
| GetBrowserRecentHistoryServerMessage
| GetTabContentServerMessage
| ReorderTabsServerMessage
| FindHighlightServerMessage
| GroupTabsServerMessage;
export type ServerMessageRequest = ServerMessage & { correlationId: string };
```
--------------------------------------------------------------------------------
/firefox-extension/background.ts:
--------------------------------------------------------------------------------
```typescript
import { WebsocketClient } from "./client";
import { MessageHandler } from "./message-handler";
import { getConfig, generateSecret } from "./extension-config";
function initClient(port: number, secret: string) {
const wsClient = new WebsocketClient(port, secret);
const messageHandler = new MessageHandler(wsClient);
wsClient.connect();
wsClient.addMessageListener(async (message) => {
console.log("Message from server:", message);
try {
await messageHandler.handleDecodedMessage(message);
} catch (error) {
console.error("Error handling message:", error);
if (error instanceof Error) {
await wsClient.sendErrorToServer(message.correlationId, error.message);
}
}
});
}
async function initExtension() {
let config = await getConfig();
if (!config.secret) {
console.log("No secret found, generating new one");
await generateSecret();
// Open the options page to allow the user to view the config:
await browser.runtime.openOptionsPage();
config = await getConfig();
}
return config;
}
initExtension()
.then((config) => {
const secret = config.secret;
if (!secret) {
console.error("Secret not found in storage - reinstall extension");
return;
}
const portList = config.ports;
if (portList.length === 0) {
console.error("No ports configured in extension config");
return;
}
for (const port of portList) {
initClient(port, secret);
}
console.log("Browser extension initialized");
})
.catch((error) => {
console.error("Error initializing extension:", error);
});
```
--------------------------------------------------------------------------------
/common/extension-messages.ts:
--------------------------------------------------------------------------------
```typescript
export interface ExtensionMessageBase {
resource: string;
correlationId: string;
}
export interface TabContentExtensionMessage extends ExtensionMessageBase {
resource: "tab-content";
tabId: number;
fullText: string;
isTruncated: boolean;
totalLength: number;
links: { url: string; text: string }[];
}
export interface BrowserTab {
id?: number;
url?: string;
title?: string;
lastAccessed?: number;
}
export interface TabsExtensionMessage extends ExtensionMessageBase {
resource: "tabs";
tabs: BrowserTab[];
}
export interface OpenedTabIdExtensionMessage extends ExtensionMessageBase {
resource: "opened-tab-id";
tabId: number | undefined;
}
export interface BrowserHistoryItem {
url?: string;
title?: string;
lastVisitTime?: number;
}
export interface BrowserHistoryExtensionMessage extends ExtensionMessageBase {
resource: "history";
historyItems: BrowserHistoryItem[];
}
export interface ReorderedTabsExtensionMessage extends ExtensionMessageBase {
resource: "tabs-reordered";
tabOrder: number[];
}
export interface FindHighlightExtensionMessage extends ExtensionMessageBase {
resource: "find-highlight-result";
noOfResults: number;
}
export interface TabsClosedExtensionMessage extends ExtensionMessageBase {
resource: "tabs-closed";
}
export interface TabGroupCreatedExtensionMessage extends ExtensionMessageBase {
resource: "new-tab-group";
groupId: number;
}
export type ExtensionMessage =
| TabContentExtensionMessage
| TabsExtensionMessage
| OpenedTabIdExtensionMessage
| BrowserHistoryExtensionMessage
| ReorderedTabsExtensionMessage
| FindHighlightExtensionMessage
| TabsClosedExtensionMessage
| TabGroupCreatedExtensionMessage;
export interface ExtensionError {
correlationId: string;
errorMessage: string;
}
```
--------------------------------------------------------------------------------
/mcp-server/manifest.json:
--------------------------------------------------------------------------------
```json
{
"dxt_version": "0.1",
"name": "browser-control-firefox",
"version": "1.5.1",
"display_name": "Firefox Control",
"description": "Control Mozilla Firefox: tabs, history and web content (privacy aware)",
"long_description": "This MCP server provides AI assistants with access to the browser's tab management, browsing history, page search, and webpage text content through a local MCP (Model Context Protocol) connection.\n\nBefore accessing any webpage content, explicit user consent is required for each domain through browser-side permissions.\n\n**Note:** This extension requires a separate Firefox add-on component, which is available at [https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/). Start by installing the Firefox add-on, then copy the secret key from the add-on settings page (it will open automatically) and paste it into this extension's configuration.",
"author": {
"name": "eyalzh",
"url": "https://github.com/eyalzh"
},
"repository": {
"type": "git",
"url": "https://github.com/eyalzh/browser-control-mcp"
},
"support": "https://github.com/eyalzh/browser-control-mcp/issues",
"documentation": "https://github.com/eyalzh/browser-control-mcp",
"license": "MIT",
"keywords": [
"browser",
"firefox"
],
"server": {
"type": "node",
"entry_point": "dist/server.js",
"mcp_config": {
"command": "node",
"args": [
"${__dirname}/dist/server.js"
],
"env": {
"EXTENSION_SECRET": "${user_config.extension_secret}",
"EXTENSION_PORT": "${user_config.port}"
}
}
},
"user_config": {
"extension_secret": {
"type": "string",
"title": "Firefox Extension Secret",
"description": "The secret key provided by the Firefox extension",
"sensitive": true,
"required": true
},
"port": {
"type": "string",
"title": "Extension Port",
"description": "The port that the MCP server will use to communicate with the Firefox extension (default is 8089)",
"default": "8089",
"required": false
}
},
"tools": [
{
"name": "open-browser-tab",
"description": "Open a new tab in the browser"
},
{
"name": "close-browser-tabs",
"description": "Close tabs in the browser"
},
{
"name": "get-list-of-open-tabs",
"description": "Get the list of open tabs in the browser"
},
{
"name": "get-recent-browser-history",
"description": "Get the list of recent browser history"
},
{
"name": "get-tab-web-content",
"description": "Get the full text content of the webpage and the list of links in the webpage (requires user consent)"
},
{
"name": "reorder-browser-tabs",
"description": "Change the order of open browser tabs"
},
{
"name": "group-browser-tabs",
"description": "Group browser tabs into a new tab group"
},
{
"name": "find-highlight-in-browser-tab",
"description": "Find and highlight text in a browser tab"
}
]
}
```
--------------------------------------------------------------------------------
/firefox-extension/client.ts:
--------------------------------------------------------------------------------
```typescript
import type {
ExtensionMessage,
ExtensionError,
ServerMessageRequest,
} from "@browser-control-mcp/common";
import { getMessageSignature } from "./auth";
const RECONNECT_INTERVAL = 2000; // 2 seconds
export class WebsocketClient {
private socket: WebSocket | null = null;
private readonly port: number;
private readonly secret: string;
private reconnectTimer: number | null = null;
private connectionAttempts: number = 0;
private messageCallback: ((data: ServerMessageRequest) => void) | null = null;
constructor(port: number, secret: string) {
this.port = port;
this.secret = secret;
}
public connect(): void {
console.log("Connecting to WebSocket server at port", this.port);
this.socket = new WebSocket(`ws://localhost:${this.port}`);
this.socket.addEventListener("open", () => {
console.log("Connected to WebSocket server at port", this.port);
this.connectionAttempts = 0;
});
this.socket.addEventListener("close", () => {
console.log("WebSocket connection closed event at port", this.port);
this.connectionAttempts = 0;
});
this.socket.addEventListener("error", (event) => {
console.error("WebSocket error:", event);
});
this.socket.addEventListener("message", async (event) => {
if (this.messageCallback === null) {
return;
}
try {
const signedMessage = JSON.parse(event.data);
const messageSig = await getMessageSignature(
JSON.stringify(signedMessage.payload),
this.secret
);
if (messageSig.length === 0 || messageSig !== signedMessage.signature) {
console.error("Invalid message signature");
await this.sendErrorToServer(
signedMessage.payload.correlationId,
"Invalid message signature - extension and server not in sync"
);
return;
}
this.messageCallback(signedMessage.payload);
} catch (error) {
console.error("Failed to parse message:", error);
}
});
// Start reconnection timer if not already running
if (this.reconnectTimer === null) {
this.startReconnectTimer();
}
}
public addMessageListener(
callback: (data: ServerMessageRequest) => void
): void {
this.messageCallback = callback;
}
private startReconnectTimer(): void {
this.reconnectTimer = window.setInterval(() => {
if (this.socket && this.socket.readyState === WebSocket.CONNECTING) {
this.connectionAttempts++;
if (this.connectionAttempts > 2) {
// Avoid long retry backoff periods by resetting the connection
this.socket.close();
}
}
if (!this.socket || this.socket.readyState === WebSocket.CLOSED) {
this.connect();
}
}, RECONNECT_INTERVAL);
}
public async sendResourceToServer(resource: ExtensionMessage): Promise<void> {
if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
console.error("Socket is not open");
return;
}
const signedMessage = {
payload: resource,
signature: await getMessageSignature(
JSON.stringify(resource),
this.secret
),
};
this.socket.send(JSON.stringify(signedMessage));
}
public async sendErrorToServer(
correlationId: string,
errorMessage: string
): Promise<void> {
if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
console.error("Socket is not open", this.socket);
return;
}
const extensionError: ExtensionError = {
correlationId,
errorMessage: errorMessage,
};
this.socket.send(JSON.stringify(extensionError));
}
public disconnect(): void {
if (this.reconnectTimer !== null) {
window.clearInterval(this.reconnectTimer);
this.reconnectTimer = null;
}
if (this.socket) {
this.socket.close();
this.socket = null;
}
}
}
```
--------------------------------------------------------------------------------
/mcp-server/server.ts:
--------------------------------------------------------------------------------
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { BrowserAPI } from "./browser-api";
import dayjs from "dayjs";
import relativeTime from "dayjs/plugin/relativeTime";
dayjs.extend(relativeTime);
const mcpServer = new McpServer({
name: "BrowserControl",
version: "1.5.1",
});
mcpServer.tool(
"open-browser-tab",
"Open a new tab in the user's browser (useful when the user asks to open a website)",
{ url: z.string() },
async ({ url }) => {
const openedTabId = await browserApi.openTab(url);
if (openedTabId !== undefined) {
return {
content: [
{
type: "text",
text: `${url} opened in tab id ${openedTabId}`,
},
],
};
} else {
return {
content: [{ type: "text", text: "Failed to open tab", isError: true }],
};
}
}
);
mcpServer.tool(
"close-browser-tabs",
"Close tabs in the user's browser by tab IDs",
{ tabIds: z.array(z.number()) },
async ({ tabIds }) => {
await browserApi.closeTabs(tabIds);
return {
content: [{ type: "text", text: "Closed tabs" }],
};
}
);
mcpServer.tool(
"get-list-of-open-tabs",
"Get the list of open tabs in the user's browser",
{},
async () => {
const openTabs = await browserApi.getTabList();
return {
content: openTabs.map((tab) => {
let lastAccessed = "unknown";
if (tab.lastAccessed) {
lastAccessed = dayjs(tab.lastAccessed).fromNow(); // LLM-friendly time ago
}
return {
type: "text",
text: `tab id=${tab.id}, tab url=${tab.url}, tab title=${tab.title}, last accessed=${lastAccessed}`,
};
}),
};
}
);
mcpServer.tool(
"get-recent-browser-history",
"Get the list of recent browser history (to get all, don't use searchQuery)",
{ searchQuery: z.string().optional() },
async ({ searchQuery }) => {
const browserHistory = await browserApi.getBrowserRecentHistory(
searchQuery
);
if (browserHistory.length > 0) {
return {
content: browserHistory.map((item) => {
let lastVisited = "unknown";
if (item.lastVisitTime) {
lastVisited = dayjs(item.lastVisitTime).fromNow(); // LLM-friendly time ago
}
return {
type: "text",
text: `url=${item.url}, title="${item.title}", lastVisitTime=${lastVisited}`,
};
}),
};
} else {
// If nothing was found for the search query, hint the AI to list
// all the recent history items instead.
const hint = searchQuery ? "Try without a searchQuery" : "";
return { content: [{ type: "text", text: `No history found. ${hint}` }] };
}
}
);
mcpServer.tool(
"get-tab-web-content",
`
Get the full text content of the webpage and the list of links in the webpage, by tab ID.
Use "offset" only for larger documents when the first call was truncated and if you require more content in order to assist the user.
`,
{ tabId: z.number(), offset: z.number().default(0) },
async ({ tabId, offset }) => {
const content = await browserApi.getTabContent(tabId, offset);
let links: { type: "text"; text: string }[] = [];
if (offset === 0) {
// Only include the links if offset is 0 (default value). Otherwise, we can
// assume this is not the first call. Adding the links again would be redundant.
links = content.links.map((link: { text: string; url: string }) => {
return {
type: "text",
text: `Link text: ${link.text}, Link URL: ${link.url}`,
};
});
}
let text = content.fullText;
let hint: { type: "text"; text: string }[] = [];
if (content.isTruncated || offset > 0) {
// If the content is truncated, add a "tip" suggesting
// that another tool, search in page, can be used to
// discover additional data.
const rangeString = `${offset}-${offset + text.length}`;
hint = [
{
type: "text",
text:
`The following text content is truncated due to size (includes character range ${rangeString} out of ${content.totalLength}). ` +
"If you want to read characters beyond this range, please use the 'get-tab-web-content' tool with an offset. ",
},
];
}
return {
content: [...hint, { type: "text", text }, ...links],
};
}
);
mcpServer.tool(
"reorder-browser-tabs",
"Change the order of open browser tabs",
{ tabOrder: z.array(z.number()) },
async ({ tabOrder }) => {
const newOrder = await browserApi.reorderTabs(tabOrder);
return {
content: [
{ type: "text", text: `Tabs reordered: ${newOrder.join(", ")}` },
],
};
}
);
mcpServer.tool(
"find-highlight-in-browser-tab",
"Find and highlight text in a browser tab (use a query phrase that exists in the web content)",
{ tabId: z.number(), queryPhrase: z.string() },
async ({ tabId, queryPhrase }) => {
const noOfResults = await browserApi.findHighlight(tabId, queryPhrase);
return {
content: [
{
type: "text",
text: `Number of results found and highlighted in the tab: ${noOfResults}`,
},
],
};
}
);
mcpServer.tool(
"group-browser-tabs",
"Organize opened browser tabs in a new tab group",
{
tabIds: z.array(z.number()),
isCollapsed: z.boolean().default(false),
groupColor: z
.enum([
"grey",
"blue",
"red",
"yellow",
"green",
"pink",
"purple",
"cyan",
"orange",
])
.default("grey"),
groupTitle: z.string().default("New Group"),
},
async ({ tabIds, isCollapsed, groupColor, groupTitle }) => {
const groupId = await browserApi.groupTabs(
tabIds,
isCollapsed,
groupColor,
groupTitle
);
return {
content: [
{
type: "text",
text: `Created tab group "${groupTitle}" with ${tabIds.length} tabs (group ID: ${groupId})`,
},
],
};
}
);
const browserApi = new BrowserAPI();
browserApi.init().catch((err) => {
console.error("Browser API init error", err);
process.exit(1);
});
const transport = new StdioServerTransport();
mcpServer.connect(transport).catch((err) => {
console.error("MCP Server connection error", err);
process.exit(1);
});
process.stdin.on("close", () => {
browserApi.close();
mcpServer.close();
process.exit(0);
});
```
--------------------------------------------------------------------------------
/mcp-server/browser-api.ts:
--------------------------------------------------------------------------------
```typescript
import WebSocket from "ws";
import type {
ExtensionMessage,
BrowserTab,
BrowserHistoryItem,
ServerMessage,
TabContentExtensionMessage,
ServerMessageRequest,
ExtensionError,
} from "@browser-control-mcp/common";
import { isPortInUse } from "./util";
import * as crypto from "crypto";
const WS_DEFAULT_PORT = 8089;
const EXTENSION_RESPONSE_TIMEOUT_MS = 1000;
interface ExtensionRequestResolver<T extends ExtensionMessage["resource"]> {
resource: T;
resolve: (value: Extract<ExtensionMessage, { resource: T }>) => void;
reject: (reason?: string) => void;
}
export class BrowserAPI {
private ws: WebSocket | null = null;
private wsServer: WebSocket.Server | null = null;
private sharedSecret: string | null = null;
// Map to persist the request to the extension. It maps the request correlationId
// to a resolver, fulfulling a promise created when sending a message to the extension.
private extensionRequestMap: Map<
string,
ExtensionRequestResolver<ExtensionMessage["resource"]>
> = new Map();
async init() {
const { secret, port } = readConfig();
if (!secret) {
throw new Error(
"EXTENSION_SECRET env var missing. See the extension's options page."
);
}
this.sharedSecret = secret;
if (await isPortInUse(port)) {
throw new Error(
`Configured port ${port} is already in use. Please configure a different port.`
);
}
// Unless running in a container, bind to localhost only
const host = process.env.CONTAINERIZED ? "0.0.0.0" : "localhost";
this.wsServer = new WebSocket.Server({
host,
port,
});
console.error(`Starting WebSocket server on ${host}:${port}`);
this.wsServer.on("connection", async (connection) => {
this.ws = connection;
console.error("WebSocket connection established on port", port);
this.ws.on("message", (message) => {
const decoded = JSON.parse(message.toString());
if (isErrorMessage(decoded)) {
this.handleExtensionError(decoded);
return;
}
const signature = this.createSignature(JSON.stringify(decoded.payload));
if (signature !== decoded.signature) {
console.error("Invalid message signature");
return;
}
this.handleDecodedExtensionMessage(decoded.payload);
});
});
this.wsServer.on("error", (error) => {
console.error("WebSocket server error:", error);
});
}
close() {
this.wsServer?.close();
}
getSelectedPort() {
return this.wsServer?.options.port;
}
async openTab(url: string): Promise<number | undefined> {
const correlationId = this.sendMessageToExtension({
cmd: "open-tab",
url,
});
const message = await this.waitForResponse(correlationId, "opened-tab-id");
return message.tabId;
}
async closeTabs(tabIds: number[]) {
const correlationId = this.sendMessageToExtension({
cmd: "close-tabs",
tabIds,
});
await this.waitForResponse(correlationId, "tabs-closed");
}
async getTabList(): Promise<BrowserTab[]> {
const correlationId = this.sendMessageToExtension({
cmd: "get-tab-list",
});
const message = await this.waitForResponse(correlationId, "tabs");
return message.tabs;
}
async getBrowserRecentHistory(
searchQuery?: string
): Promise<BrowserHistoryItem[]> {
const correlationId = this.sendMessageToExtension({
cmd: "get-browser-recent-history",
searchQuery,
});
const message = await this.waitForResponse(correlationId, "history");
return message.historyItems;
}
async getTabContent(
tabId: number,
offset: number
): Promise<TabContentExtensionMessage> {
const correlationId = this.sendMessageToExtension({
cmd: "get-tab-content",
tabId,
offset,
});
return await this.waitForResponse(correlationId, "tab-content");
}
async reorderTabs(tabOrder: number[]): Promise<number[]> {
const correlationId = this.sendMessageToExtension({
cmd: "reorder-tabs",
tabOrder,
});
const message = await this.waitForResponse(correlationId, "tabs-reordered");
return message.tabOrder;
}
async findHighlight(tabId: number, queryPhrase: string): Promise<number> {
const correlationId = this.sendMessageToExtension({
cmd: "find-highlight",
tabId,
queryPhrase,
});
const message = await this.waitForResponse(
correlationId,
"find-highlight-result"
);
return message.noOfResults;
}
async groupTabs(
tabIds: number[],
isCollapsed: boolean,
groupColor: string,
groupTitle: string
): Promise<number> {
const correlationId = this.sendMessageToExtension({
cmd: "group-tabs",
tabIds,
isCollapsed,
groupColor,
groupTitle,
});
const message = await this.waitForResponse(correlationId, "new-tab-group");
return message.groupId;
}
private createSignature(payload: string): string {
if (!this.sharedSecret) {
throw new Error("Shared secret not initialized");
}
const hmac = crypto.createHmac("sha256", this.sharedSecret);
hmac.update(payload);
return hmac.digest("hex");
}
private sendMessageToExtension(message: ServerMessage): string {
if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
throw new Error("WebSocket is not open");
}
const correlationId = Math.random().toString(36).substring(2);
const req: ServerMessageRequest = { ...message, correlationId };
const payload = JSON.stringify(req);
const signature = this.createSignature(payload);
const signedMessage = {
payload: req,
signature: signature,
};
// Send the signed message to the extension
this.ws.send(JSON.stringify(signedMessage));
return correlationId;
}
private handleDecodedExtensionMessage(decoded: ExtensionMessage) {
const { correlationId } = decoded;
const { resolve, resource } = this.extensionRequestMap.get(correlationId)!;
if (resource !== decoded.resource) {
console.error("Resource mismatch:", resource, decoded.resource);
return;
}
this.extensionRequestMap.delete(correlationId);
resolve(decoded);
}
private handleExtensionError(decoded: ExtensionError) {
const { correlationId, errorMessage } = decoded;
const { reject } = this.extensionRequestMap.get(correlationId)!;
this.extensionRequestMap.delete(correlationId);
reject(errorMessage);
}
private async waitForResponse<T extends ExtensionMessage["resource"]>(
correlationId: string,
resource: T
): Promise<Extract<ExtensionMessage, { resource: T }>> {
return new Promise<Extract<ExtensionMessage, { resource: T }>>(
(resolve, reject) => {
this.extensionRequestMap.set(correlationId, {
resolve: resolve as (value: ExtensionMessage) => void,
resource,
reject,
});
setTimeout(() => {
this.extensionRequestMap.delete(correlationId);
reject("Timed out waiting for response");
}, EXTENSION_RESPONSE_TIMEOUT_MS);
}
);
}
}
function readConfig() {
return {
secret: process.env.EXTENSION_SECRET,
port: process.env.EXTENSION_PORT
? parseInt(process.env.EXTENSION_PORT, 10)
: WS_DEFAULT_PORT,
};
}
export function isErrorMessage(message: any): message is ExtensionError {
return (
message.errorMessage !== undefined && message.correlationId !== undefined
);
}
```
--------------------------------------------------------------------------------
/firefox-extension/extension-config.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Configuration management for Browser Control MCP extension
*/
import { ServerMessageRequest } from "@browser-control-mcp/common/server-messages";
const DEFAULT_WS_PORT = 8089;
const AUDIT_LOG_SIZE_LIMIT = 100; // Maximum number of audit log entries to keep
// Define all available tools with their IDs and descriptions
export interface ToolInfo {
id: string;
name: string;
description: string;
}
export const AVAILABLE_TOOLS: ToolInfo[] = [
{
id: "open-browser-tab",
name: "Open Browser Tab",
description: "Allows the MCP server to open new browser tabs"
},
{
id: "close-browser-tabs",
name: "Close Browser Tabs",
description: "Allows the MCP server to close browser tabs"
},
{
id: "get-list-of-open-tabs",
name: "Get List of Open Tabs",
description: "Allows the MCP server to get a list of all open tabs"
},
{
id: "get-recent-browser-history",
name: "Get Recent Browser History",
description: "Allows the MCP server to access your recent browsing history"
},
{
id: "get-tab-web-content",
name: "Get Tab Web Content",
description: "Allows the MCP server to read the content of web pages"
},
{
id: "reorder-browser-tabs",
name: "Reorder/Group Browser Tabs",
description: "Allows the MCP server to reorder/group your browser tabs"
},
{
id: "find-highlight-in-browser-tab",
name: "Find and Highlight in Browser Tab",
description: "Allows the MCP server to search for and highlight text in web pages"
}
];
// Map command names to tool IDs
export const COMMAND_TO_TOOL_ID: Record<ServerMessageRequest["cmd"], string> = {
"open-tab": "open-browser-tab",
"close-tabs": "close-browser-tabs",
"get-tab-list": "get-list-of-open-tabs",
"get-browser-recent-history": "get-recent-browser-history",
"get-tab-content": "get-tab-web-content",
"reorder-tabs": "reorder-browser-tabs",
"find-highlight": "find-highlight-in-browser-tab",
"group-tabs": "reorder-browser-tabs",
};
// Storage schema for tool settings
export interface ToolSettings {
[toolId: string]: boolean;
}
// Audit log entry interface
export interface AuditLogEntry {
toolId: string;
command: string;
timestamp: number;
url?: string;
}
// Extended config interface
export interface ExtensionConfig {
secret: string;
toolSettings?: ToolSettings;
domainDenyList?: string[];
ports: number[];
auditLog?: AuditLogEntry[];
}
/**
* Gets the default tool settings (all enabled)
*/
export function getDefaultToolSettings(): ToolSettings {
const settings: ToolSettings = {};
AVAILABLE_TOOLS.forEach(tool => {
settings[tool.id] = true;
});
return settings;
}
/**
* Gets the extension configuration from storage
* @returns A Promise that resolves with the extension configuration
*/
export async function getConfig(): Promise<ExtensionConfig> {
const configObj = await browser.storage.local.get("config");
const config: ExtensionConfig = configObj.config || { secret: "" };
// Initialize toolSettings if it doesn't exist
if (!config.toolSettings) {
config.toolSettings = getDefaultToolSettings();
}
if (!config.ports) {
config.ports = [DEFAULT_WS_PORT];
}
return config;
}
/**
* Saves the extension configuration to storage
* @param config The configuration to save
* @returns A Promise that resolves when the configuration is saved
*/
export async function saveConfig(config: ExtensionConfig): Promise<void> {
await browser.storage.local.set({ config });
}
/**
* Gets the secret from storage
* @returns A Promise that resolves with the secret
*/
export async function getSecret(): Promise<string> {
const config = await getConfig();
return config.secret;
}
/**
* Generates a new secret and saves it to storage
* @returns A Promise that resolves with the new secret
*/
export async function generateSecret(): Promise<string> {
const config = await getConfig();
config.secret = crypto.randomUUID();
await saveConfig(config);
return config.secret;
}
/**
* Checks if a tool is enabled
* @param toolId The ID of the tool to check
* @returns A Promise that resolves with true if the tool is enabled, false otherwise
*/
export async function isToolEnabled(toolId: string): Promise<boolean> {
const config = await getConfig();
// Default to true if not explicitly set to false
return config.toolSettings?.[toolId] !== false;
}
/**
* Checks if a command is allowed based on the tool permissions
* @param command The command to check
* @returns A Promise that resolves with true if the command is allowed, false otherwise
*/
export async function isCommandAllowed(command: ServerMessageRequest["cmd"]): Promise<boolean> {
const toolId = COMMAND_TO_TOOL_ID[command];
if (!toolId) {
console.error(`Unknown command: ${command}`);
return false;
}
return isToolEnabled(toolId);
}
/**
* Sets the enabled status of a tool
* @param toolId The ID of the tool to update
* @param enabled Whether the tool should be enabled
* @returns A Promise that resolves when the setting is saved
*/
export async function setToolEnabled(toolId: string, enabled: boolean): Promise<void> {
const config = await getConfig();
// Update the setting
if (!config.toolSettings) {
config.toolSettings = getDefaultToolSettings();
}
config.toolSettings[toolId] = enabled;
// Save back to storage
await saveConfig(config);
}
/**
* Gets all tool settings
* @returns A Promise that resolves with the current tool settings
*/
export async function getAllToolSettings(): Promise<ToolSettings> {
const config = await getConfig();
return config.toolSettings || getDefaultToolSettings();
}
/**
* Gets the domain deny list
* @returns A Promise that resolves with the domain deny list
*/
export async function getDomainDenyList(): Promise<string[]> {
const config = await getConfig();
return config.domainDenyList || [];
}
/**
* Sets the domain deny list
* @param domains Array of domains to deny
* @returns A Promise that resolves when the setting is saved
*/
export async function setDomainDenyList(domains: string[]): Promise<void> {
const config = await getConfig();
config.domainDenyList = domains;
await saveConfig(config);
}
/**
* Checks if a domain is in the deny list
* @param url The URL to check
* @returns A Promise that resolves with true if the domain is in the deny list, false otherwise
*/
export async function isDomainInDenyList(url: string): Promise<boolean> {
try {
// Extract the domain from the URL
const urlObj = new URL(url);
const domain = urlObj.hostname;
// Get the deny list
const denyList = await getDomainDenyList();
// Check if the domain is in the deny list
return denyList.some(deniedDomain =>
domain.toLowerCase() === deniedDomain.toLowerCase() ||
domain.toLowerCase().endsWith(`.${deniedDomain.toLowerCase()}`)
);
} catch (error) {
console.error(`Error checking domain in deny list: ${error}`);
// If there's an error parsing the URL, return false
return false;
}
}
/**
* Gets the WebSocket ports list
* @returns A Promise that resolves with the ports list
*/
export async function getPorts(): Promise<number[]> {
const config = await getConfig();
return config.ports || [DEFAULT_WS_PORT];
}
/**
* Sets the WebSocket ports list
* @param ports Array of port numbers
* @returns A Promise that resolves when the setting is saved
*/
export async function setPorts(ports: number[]): Promise<void> {
const config = await getConfig();
config.ports = ports;
await saveConfig(config);
}
/**
* Adds an entry to the audit log
* @param entry The audit log entry to add
* @returns A Promise that resolves when the entry is saved
*/
export async function addAuditLogEntry(entry: AuditLogEntry): Promise<void> {
const config = await getConfig();
if (!config.auditLog) {
config.auditLog = [];
}
// Add the new entry at the beginning
config.auditLog.unshift(entry);
// Keep only the last AUDIT_LOG_SIZE_LIMIT entries
if (config.auditLog.length > AUDIT_LOG_SIZE_LIMIT) {
config.auditLog = config.auditLog.slice(0, AUDIT_LOG_SIZE_LIMIT);
}
await saveConfig(config);
}
/**
* Gets the audit log entries
* @returns A Promise that resolves with the audit log entries
*/
export async function getAuditLog(): Promise<AuditLogEntry[]> {
const config = await getConfig();
return config.auditLog || [];
}
/**
* Clears the audit log
* @returns A Promise that resolves when the audit log is cleared
*/
export async function clearAuditLog(): Promise<void> {
const config = await getConfig();
config.auditLog = [];
await saveConfig(config);
}
/**
* Gets the tool name by tool ID
* @param toolId The tool ID to look up
* @returns The tool name or the tool ID if not found
*/
export function getToolNameById(toolId: string): string {
const tool = AVAILABLE_TOOLS.find(t => t.id === toolId);
return tool ? tool.name : toolId;
}
```
--------------------------------------------------------------------------------
/firefox-extension/message-handler.ts:
--------------------------------------------------------------------------------
```typescript
import type { ServerMessageRequest } from "@browser-control-mcp/common";
import { WebsocketClient } from "./client";
import { isCommandAllowed, isDomainInDenyList, COMMAND_TO_TOOL_ID, addAuditLogEntry } from "./extension-config";
export class MessageHandler {
private client: WebsocketClient;
constructor(client: WebsocketClient) {
this.client = client;
}
public async handleDecodedMessage(req: ServerMessageRequest): Promise<void> {
const isAllowed = await isCommandAllowed(req.cmd);
if (!isAllowed) {
throw new Error(`Command '${req.cmd}' is disabled in extension settings`);
}
this.addAuditLogForReq(req).catch((error) => {
console.error("Failed to add audit log entry:", error);
});
switch (req.cmd) {
case "open-tab":
await this.openUrl(req.correlationId, req.url);
break;
case "close-tabs":
await this.closeTabs(req.correlationId, req.tabIds);
break;
case "get-tab-list":
await this.sendTabs(req.correlationId);
break;
case "get-browser-recent-history":
await this.sendRecentHistory(req.correlationId, req.searchQuery);
break;
case "get-tab-content":
await this.sendTabsContent(req.correlationId, req.tabId, req.offset);
break;
case "reorder-tabs":
await this.reorderTabs(req.correlationId, req.tabOrder);
break;
case "find-highlight":
await this.findAndHighlightText(
req.correlationId,
req.tabId,
req.queryPhrase
);
break;
case "group-tabs":
await this.groupTabs(
req.correlationId,
req.tabIds,
req.isCollapsed,
req.groupColor as browser.tabGroups.Color,
req.groupTitle
);
break;
default:
const _exhaustiveCheck: never = req;
console.error("Invalid message received:", req);
}
}
private async addAuditLogForReq(req: ServerMessageRequest) {
// Get the URL in context (either from param or from the tab)
let contextUrl: string | undefined;
if ("url" in req && req.url) {
contextUrl = req.url;
}
if ("tabId" in req) {
try {
const tab = await browser.tabs.get(req.tabId);
contextUrl = tab.url;
} catch (error) {
console.error("Failed to get tab URL for audit log:", error);
}
}
const toolId = COMMAND_TO_TOOL_ID[req.cmd];
const auditEntry = {
toolId,
command: req.cmd,
timestamp: Date.now(),
url: contextUrl
};
await addAuditLogEntry(auditEntry);
}
private async openUrl(correlationId: string, url: string): Promise<void> {
if (!url.startsWith("https://")) {
console.error("Invalid URL:", url);
throw new Error("Invalid URL");
}
if (await isDomainInDenyList(url)) {
throw new Error("Domain in user defined deny list");
}
const tab = await browser.tabs.create({
url,
});
await this.client.sendResourceToServer({
resource: "opened-tab-id",
correlationId,
tabId: tab.id,
});
}
private async closeTabs(
correlationId: string,
tabIds: number[]
): Promise<void> {
await browser.tabs.remove(tabIds);
await this.client.sendResourceToServer({
resource: "tabs-closed",
correlationId,
});
}
private async sendTabs(correlationId: string): Promise<void> {
const tabs = await browser.tabs.query({});
await this.client.sendResourceToServer({
resource: "tabs",
correlationId,
tabs,
});
}
private async sendRecentHistory(
correlationId: string,
searchQuery: string | null = null
): Promise<void> {
const historyItems = await browser.history.search({
text: searchQuery ?? "", // Search for all URLs (empty string matches everything)
maxResults: 200, // Limit to 200 results
startTime: 0, // Search from the beginning of time
});
const filteredHistoryItems = historyItems.filter((item) => {
return !!item.url;
});
await this.client.sendResourceToServer({
resource: "history",
correlationId,
historyItems: filteredHistoryItems,
});
}
// Check that the user has granted permission to access the URL's domain.
// This will open the options page with a URL parameter to request permission
// and throw an error to indicate that the request cannot proceed until permission is granted.
private async checkForUrlPermission(url: string | undefined): Promise<void> {
if (url) {
const origin = new URL(url).origin;
const granted = await browser.permissions.contains({
origins: [`${origin}/*`],
});
if (!granted) {
// Open the options page with a URL parameter to request permission:
const optionsUrl = browser.runtime.getURL("options.html");
const urlWithParams = `${optionsUrl}?requestUrl=${encodeURIComponent(
url
)}`;
await browser.tabs.create({ url: urlWithParams });
throw new Error(
`The user has not yet granted permission to access the domain "${origin}". A dialog is now being opened to request permission. If the user grants permission, you can try the request again.`
);
}
}
}
private async checkForGlobalPermission(permissions: string[]): Promise<void> {
const granted = await browser.permissions.contains({
permissions,
});
if (!granted) {
// Open the options page with a URL parameter to request permission:
const optionsUrl = browser.runtime.getURL("options.html");
const urlWithParams = `${optionsUrl}?requestPermissions=${encodeURIComponent(
JSON.stringify(permissions)
)}`;
await browser.tabs.create({ url: urlWithParams });
throw new Error(
`The user has not yet granted permission for the following operations: ${permissions.join(
", "
)}. A dialog is now being opened to request permission. If the user grants permission, you can try the request again.`
);
}
}
private async sendTabsContent(
correlationId: string,
tabId: number,
offset?: number
): Promise<void> {
const tab = await browser.tabs.get(tabId);
if (tab.url && (await isDomainInDenyList(tab.url))) {
throw new Error(`Domain in tab URL is in the deny list`);
}
await this.checkForUrlPermission(tab.url);
const MAX_CONTENT_LENGTH = 50_000;
const results = await browser.tabs.executeScript(tabId, {
code: `
(function () {
function getLinks() {
const linkElements = document.querySelectorAll('a[href]');
return Array.from(linkElements).map(el => ({
url: el.href,
text: el.innerText.trim() || el.getAttribute('aria-label') || el.getAttribute('title') || ''
})).filter(link => link.text !== '' && link.url.startsWith('https://') && !link.url.includes('#'));
}
function getTextContent() {
let isTruncated = false;
let text = document.body.innerText.substring(${Number(offset) || 0});
if (text.length > ${MAX_CONTENT_LENGTH}) {
text = text.substring(0, ${MAX_CONTENT_LENGTH});
isTruncated = true;
}
return {
text, isTruncated
}
}
const textContent = getTextContent();
return {
links: getLinks(),
fullText: textContent.text,
isTruncated: textContent.isTruncated,
totalLength: document.body.innerText.length
};
})();
`,
});
const { isTruncated, fullText, links, totalLength } = results[0];
await this.client.sendResourceToServer({
resource: "tab-content",
tabId,
correlationId,
isTruncated,
fullText,
links,
totalLength,
});
}
private async reorderTabs(
correlationId: string,
tabOrder: number[]
): Promise<void> {
// Reorder the tabs sequentially
for (let newIndex = 0; newIndex < tabOrder.length; newIndex++) {
const tabId = tabOrder[newIndex];
await browser.tabs.move(tabId, { index: newIndex });
}
await this.client.sendResourceToServer({
resource: "tabs-reordered",
correlationId,
tabOrder,
});
}
private async findAndHighlightText(
correlationId: string,
tabId: number,
queryPhrase: string
): Promise<void> {
const tab = await browser.tabs.get(tabId);
if (tab.url && (await isDomainInDenyList(tab.url))) {
throw new Error(`Domain in tab URL is in the deny list`);
}
await this.checkForGlobalPermission(["find"]);
const findResults = await browser.find.find(queryPhrase, {
tabId,
caseSensitive: true,
});
// If there are results, highlight them
if (findResults.count > 0) {
// But first, activate the tab. In firefox, this would also enable
// auto-scrolling to the highlighted result.
await browser.tabs.update(tabId, { active: true });
browser.find.highlightResults({
tabId,
});
}
await this.client.sendResourceToServer({
resource: "find-highlight-result",
correlationId,
noOfResults: findResults.count,
});
}
private async groupTabs(
correlationId: string,
tabIds: number[],
isCollapsed: boolean,
groupColor: browser.tabGroups.Color,
groupTitle: string
): Promise<void> {
const groupId = await browser.tabs.group({
tabIds,
});
let tabGroup = await browser.tabGroups.update(groupId, {
collapsed: isCollapsed,
color: groupColor,
title: groupTitle,
});
await this.client.sendResourceToServer({
resource: "new-tab-group",
correlationId,
groupId: tabGroup.id,
});
}
}
```
--------------------------------------------------------------------------------
/firefox-extension/options.html:
--------------------------------------------------------------------------------
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Browser Control MCP Options</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
padding: 20px;
max-width: 800px;
margin: 0 auto;
}
.container {
background-color: #f9f9f9;
border-radius: 8px;
padding: 20px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
h1 {
color: #333;
margin-top: 0;
}
h2 {
margin-top: 12px;
margin-bottom: 8px;
color: #333;
cursor: pointer;
display: flex;
align-items: center;
justify-content: space-between;
}
h2::after {
content: "";
display: inline-block;
width: 16px;
height: 16px;
background-image: url("assets/caret.svg");
background-size: contain;
background-repeat: no-repeat;
}
h2.collapsed::after {
transform: rotate(180deg);
}
.section-container {
margin-top: 20px;
background-color: #fff;
border: 1px solid #ddd;
border-radius: 4px;
padding: 15px;
}
.section-content {
transition: max-height 0.3s ease, opacity 0.3s ease;
max-height: 2000px;
opacity: 1;
overflow: hidden;
}
.section-content.collapsed {
max-height: 0;
opacity: 0;
padding-top: 0;
padding-bottom: 0;
}
.secret-value {
font-family: monospace;
word-break: break-all;
background-color: #f5f5f5;
padding: 10px;
border-radius: 4px;
border: 1px solid #e0e0e0;
}
.copy-button {
margin-top: 10px;
background-color: #4285f4;
color: white;
border: none;
padding: 8px 16px;
border-radius: 4px;
cursor: pointer;
font-size: 14px;
}
.copy-button:hover {
background-color: #3367d6;
}
.status {
margin-top: 10px;
color: #4caf50;
font-size: 14px;
height: 20px;
}
.tool-row {
display: flex;
justify-content: space-between;
align-items: center;
padding: 10px 0;
border-bottom: 1px solid #eee;
}
.tool-row:last-child {
border-bottom: none;
}
.tool-label-container {
flex: 1;
padding-right: 20px;
}
.tool-name {
font-weight: bold;
margin-bottom: 5px;
}
.tool-description {
font-size: 14px;
color: #666;
}
/* Toggle switch styles */
.toggle-switch {
position: relative;
display: inline-block;
width: 50px;
height: 24px;
}
.toggle-switch input {
opacity: 0;
width: 0;
height: 0;
}
.slider {
position: absolute;
cursor: pointer;
top: 0;
left: 0;
right: 0;
bottom: 0;
background-color: #ccc;
transition: .4s;
border-radius: 24px;
}
.slider:before {
position: absolute;
content: "";
height: 16px;
width: 16px;
left: 4px;
bottom: 4px;
background-color: white;
transition: .4s;
border-radius: 50%;
}
input:checked+.slider {
background-color: #4285f4;
}
input:focus+.slider {
box-shadow: 0 0 1px #4285f4;
}
input:checked+.slider:before {
transform: translateX(26px);
}
/* Permission modal styles */
.permission-modal {
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
background-color: rgba(0, 0, 0, 0.5);
display: flex;
justify-content: center;
align-items: center;
z-index: 1000;
}
.permission-modal.hidden {
display: none;
}
.permission-modal-content {
background-color: white;
padding: 30px;
border-radius: 8px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
max-width: 500px;
width: 90%;
text-align: center;
}
.permission-modal h2 {
margin-top: 0;
margin-bottom: 20px;
color: #333;
cursor: default;
}
.permission-modal h2::after {
display: none;
}
.permission-modal p {
margin-bottom: 20px;
color: #666;
line-height: 1.5;
}
.permission-domain {
font-family: monospace;
background-color: #f5f5f5;
padding: 8px 12px;
border-radius: 4px;
border: 1px solid #e0e0e0;
display: inline-block;
margin: 0 4px;
font-weight: bold;
}
.permission-buttons {
display: flex;
gap: 10px;
justify-content: center;
margin-top: 25px;
}
.grant-button {
background-color: #4285f4;
color: white;
border: none;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
font-size: 14px;
font-weight: bold;
}
.grant-button:hover {
background-color: #3367d6;
}
.cancel-button {
background-color: #f1f3f4;
color: #333;
border: 1px solid #dadce0;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
font-size: 14px;
}
.cancel-button:hover {
background-color: #e8eaed;
}
.main-content.modal-open {
filter: blur(2px);
pointer-events: none;
}
/* Audit log styles */
.audit-log-table {
width: 100%;
border-collapse: collapse;
margin-top: 10px;
font-size: 14px;
}
.audit-log-table th,
.audit-log-table td {
padding: 8px 12px;
text-align: left;
border-bottom: 1px solid #eee;
}
.audit-log-table th {
background-color: #f5f5f5;
font-weight: bold;
color: #333;
}
.audit-log-table td {
color: #666;
}
.audit-log-url {
font-family: monospace;
font-size: 12px;
max-width: 200px;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.audit-log-timestamp {
white-space: nowrap;
font-size: 12px;
}
.audit-log-empty {
text-align: center;
color: #999;
font-style: italic;
padding: 20px;
}
</style>
</head>
<body>
<!-- Permission Request Modal -->
<div id="permission-modal" class="permission-modal hidden">
<div class="permission-modal-content">
<h2>Permission Required</h2>
<p>The Browser Control MCP extension needs permission to access:</p>
<div class="permission-domain" id="permission-domain"></div>
<p id="permission-text">This will allow the extension to interact with pages on this domain as requested by the MCP server.</p>
<div class="permission-buttons">
<button id="grant-btn" class="grant-button">Grant Permission</button>
<button id="cancel-btn" class="cancel-button">Cancel</button>
</div>
</div>
</div>
<div class="container main-content" id="main-content">
<h1>Browser Control MCP Options</h1>
<p>Configure settings for the Browser Control MCP extension.</p>
<div class="section-container">
<h2>MCP Server Installation</h2>
<div class="section-content">
<p>To use this extension, you need to install the local MCP server. Choose one of the following options:</p>
<div style="margin: 15px 0;">
<h3 style="margin: 10px 0; font-size: 16px; color: #333;">Option 1: Download DXT Package (Claude Desktop only)</h3>
<p>Download and open the pre-built DXT package:</p>
<a href="https://github.com/eyalzh/browser-control-mcp/releases/download/v1.5.0/mcp-server-v1.5.0.dxt"
style="display: inline-block; background-color: #4285f4; color: white; padding: 8px 16px;
text-decoration: none; border-radius: 4px; margin: 5px 0; font-size: 14px;">
Download DXT Package
</a>
</div>
<div style="margin: 15px 0;">
<h3 style="margin: 10px 0; font-size: 16px; color: #333;">Option 2: Manual MCP Installation</h3>
<p>Follow the detailed setup instructions in the github repository:</p>
<a href="https://github.com/eyalzh/browser-control-mcp?tab=readme-ov-file#installation"
target="_blank" rel="noopener noreferrer"
style="display: inline-block; background-color: #f1f3f4; color: #333; padding: 8px 16px;
text-decoration: none; border-radius: 4px; border: 1px solid #dadce0; margin: 5px 0; font-size: 14px;">
View Installation Guide
</a>
</div>
<p style="margin-top: 15px; color: #666; font-size: 14px;">
After installing the MCP server, you'll need to configure it with the secret key shown below.
</p>
</div>
</div>
<div class="section-container">
<h2>Secret Key</h2>
<div class="section-content">
<p>This secret key is automatically generated when the extension is installed and is used to authenticate
connections to the MCP server:</p>
<div class="secret-value" id="secret-display">Loading...</div>
<button class="copy-button" id="copy-button">Copy to Clipboard</button>
<div class="status" id="status"></div>
</div>
</div>
<div class="section-container">
<h2>WebSocket Ports</h2>
<div class="section-content">
<p>Configure the WebSocket ports for MCP server connections (comma-separated list). Note: Changing this value will reload the extension.</p>
<input type="text" id="ports-input" placeholder="8089, 8090, 8091" style="width: 100%; padding: 8px; border: 1px solid #ddd; border-radius: 4px; font-family: monospace; margin-bottom: 10px;" />
<button class="copy-button" id="save-ports">Save Ports</button>
<div class="status" id="ports-status"></div>
</div>
</div>
<div class="section-container">
<h2>Tool Permissions</h2>
<div class="section-content">
<p>Enable or disable specific MCP tools that can interact with your browser:</p>
<div id="tool-settings-container">
<!-- Tool settings will be dynamically inserted here -->
<div class="loading">Loading tool settings...</div>
</div>
</div>
</div>
<div class="section-container">
<h2 class="collapsed" role="button" aria-expanded="false" tabindex="0" id="domain-filtering-header">Domain Filtering</h2>
<div class="section-content collapsed" aria-labelledby="domain-filtering-header">
<p>Configure which domains the extension can interact with:</p>
<div class="domain-list-container" style="margin-top: 20px;">
<h3>Domain Deny List</h3>
<p>The extension will not open tabs or get content from tabs with these domains (one domain per line):</p>
<textarea id="domain-deny-list" rows="6" style="width: 100%; font-family: monospace;"></textarea>
</div>
<button id="save-domain-lists" class="copy-button" style="margin-top: 15px;">Save Domain Lists</button>
<div class="status" id="domain-status"></div>
</div>
</div>
<div class="section-container">
<h2 class="collapsed" role="button" aria-expanded="false" tabindex="0" id="audit-log-header">Audit Log</h2>
<div class="section-content collapsed" aria-labelledby="audit-log-header">
<p>View recent tool usage history:</p>
<div id="audit-log-container" style="margin-top: 20px;">
<div class="loading">Loading audit log...</div>
</div>
<div style="margin-top: 15px;">
<button id="clear-audit-log" class="copy-button">Clear Log</button>
<div class="status" id="audit-log-status"></div>
</div>
</div>
</div>
</div>
<script src="dist/options.js"></script>
</body>
</html>
```
--------------------------------------------------------------------------------
/firefox-extension/__tests__/message-handler.test.ts:
--------------------------------------------------------------------------------
```typescript
import { MessageHandler } from "../message-handler";
import { WebsocketClient } from "../client";
import type { ServerMessageRequest } from "@browser-control-mcp/common";
import { ExtensionConfig } from "../extension-config";
// Mock the WebsocketClient
jest.mock("../client", () => {
return {
WebsocketClient: jest.fn().mockImplementation(() => {
return {
sendResourceToServer: jest.fn().mockResolvedValue(undefined),
sendErrorToServer: jest.fn().mockResolvedValue(undefined),
};
}),
};
});
describe("MessageHandler", () => {
let messageHandler: MessageHandler;
let mockClient: jest.Mocked<WebsocketClient>;
beforeEach(() => {
// Clear all mocks before each test
jest.clearAllMocks();
// Create a new instance of WebsocketClient and MessageHandler
mockClient = new WebsocketClient(
8080,
"test-secret"
) as jest.Mocked<WebsocketClient>;
messageHandler = new MessageHandler(mockClient);
// Mock browser.storage.local.get to return default config
const defaultConfig: ExtensionConfig = {
secret: "test-secret",
toolSettings: {
"open-browser-tab": true,
"close-browser-tabs": true,
"get-list-of-open-tabs": true,
"get-recent-browser-history": true,
"get-tab-web-content": true,
"reorder-browser-tabs": true,
"find-highlight-in-browser-tab": true,
},
domainDenyList: [],
ports: [8089],
auditLog: [],
};
(browser.storage.local.get as jest.Mock).mockResolvedValue({
config: defaultConfig,
});
});
describe("handleDecodedMessage", () => {
it("should throw an error if command is not allowed", async () => {
// Arrange
const configWithDisabledOpenTab: ExtensionConfig = {
secret: "test-secret",
toolSettings: {
"open-browser-tab": false, // Disable open-tab command
"close-browser-tabs": true,
"get-list-of-open-tabs": true,
"get-recent-browser-history": true,
"get-tab-web-content": true,
"reorder-browser-tabs": true,
"find-highlight-in-browser-tab": true,
},
domainDenyList: [],
ports: [8089],
auditLog: [],
};
(browser.storage.local.get as jest.Mock).mockResolvedValue({
config: configWithDisabledOpenTab,
});
const request: ServerMessageRequest = {
cmd: "open-tab",
url: "https://example.com",
correlationId: "test-correlation-id",
};
// Act & Assert
await expect(
messageHandler.handleDecodedMessage(request)
).rejects.toThrow("Command 'open-tab' is disabled in extension settings");
});
describe("open-tab command", () => {
it("should open a new tab and send the tab ID to the server", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "open-tab",
url: "https://example.com",
correlationId: "test-correlation-id",
};
const mockTab = { id: 123 };
(browser.tabs.create as jest.Mock).mockResolvedValue(mockTab);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.create).toHaveBeenCalledWith({
url: "https://example.com",
});
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "opened-tab-id",
correlationId: "test-correlation-id",
tabId: 123,
});
});
it("should throw an error if URL does not start with https://", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "open-tab",
url: "http://example.com",
correlationId: "test-correlation-id",
};
// Act & Assert
await expect(
messageHandler.handleDecodedMessage(request)
).rejects.toThrow("Invalid URL");
expect(browser.tabs.create).not.toHaveBeenCalled();
});
it("should throw an error if domain is in deny list", async () => {
// Arrange
const configWithDenyList: ExtensionConfig = {
secret: "test-secret",
toolSettings: {
"open-browser-tab": true,
"close-browser-tabs": true,
"get-list-of-open-tabs": true,
"get-recent-browser-history": true,
"get-tab-web-content": true,
"reorder-browser-tabs": true,
"find-highlight-in-browser-tab": true,
},
domainDenyList: ["example.com", "another.com"],
ports: [8089],
auditLog: [],
};
(browser.storage.local.get as jest.Mock).mockResolvedValue({
config: configWithDenyList,
});
const request: ServerMessageRequest = {
cmd: "open-tab",
url: "https://example.com",
correlationId: "test-correlation-id",
};
// Act & Assert
await expect(
messageHandler.handleDecodedMessage(request)
).rejects.toThrow("Domain in user defined deny list");
expect(browser.tabs.create).not.toHaveBeenCalled();
});
it("should open a new tab in the domain is not in the deny list", async () => {
// Arrange
const configWithDenyList: ExtensionConfig = {
secret: "test-secret",
toolSettings: {
"open-browser-tab": true,
"close-browser-tabs": true,
"get-list-of-open-tabs": true,
"get-recent-browser-history": true,
"get-tab-web-content": true,
"reorder-browser-tabs": true,
"find-highlight-in-browser-tab": true,
},
domainDenyList: ["example.com", "another.com"],
ports: [8089],
auditLog: [],
};
(browser.storage.local.get as jest.Mock).mockResolvedValue({
config: configWithDenyList,
});
const request: ServerMessageRequest = {
cmd: "open-tab",
url: "https://allowed.com",
correlationId: "test-correlation-id",
};
const mockTab = { id: 123 };
(browser.tabs.create as jest.Mock).mockResolvedValue(mockTab);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.create).toHaveBeenCalledWith({
url: "https://allowed.com",
});
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "opened-tab-id",
correlationId: "test-correlation-id",
tabId: 123,
});
});
});
describe("close-tabs command", () => {
it("should close tabs and send confirmation to the server", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "close-tabs",
tabIds: [123, 456],
correlationId: "test-correlation-id",
};
(browser.tabs.remove as jest.Mock).mockResolvedValue(undefined);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.remove).toHaveBeenCalledWith([123, 456]);
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "tabs-closed",
correlationId: "test-correlation-id",
});
});
});
describe("get-tab-list command", () => {
it("should get tabs and send them to the server", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "get-tab-list",
correlationId: "test-correlation-id",
};
const mockTabs = [{ id: 123, url: "https://example.com" }];
(browser.tabs.query as jest.Mock).mockResolvedValue(mockTabs);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.query).toHaveBeenCalledWith({});
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "tabs",
correlationId: "test-correlation-id",
tabs: mockTabs,
});
});
});
describe("get-browser-recent-history command", () => {
it("should get history items and send them to the server", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "get-browser-recent-history",
searchQuery: "test",
correlationId: "test-correlation-id",
};
const mockHistoryItems = [
{ url: "https://example.com", title: "Example" },
{ url: "https://test.com", title: "Test" },
];
(browser.history.search as jest.Mock).mockResolvedValue(
mockHistoryItems
);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.history.search).toHaveBeenCalledWith({
text: "test",
maxResults: 200,
startTime: 0,
});
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "history",
correlationId: "test-correlation-id",
historyItems: mockHistoryItems,
});
});
it("should use empty string for search query if not provided", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "get-browser-recent-history",
correlationId: "test-correlation-id",
};
const mockHistoryItems = [
{ url: "https://example.com", title: "Example" },
];
(browser.history.search as jest.Mock).mockResolvedValue(
mockHistoryItems
);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.history.search).toHaveBeenCalledWith({
text: "",
maxResults: 200,
startTime: 0,
});
});
it("should filter out history items without URLs", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "get-browser-recent-history",
correlationId: "test-correlation-id",
};
const mockHistoryItems = [
{ url: "https://example.com", title: "Example" },
{ title: "No URL" }, // This should be filtered out
];
(browser.history.search as jest.Mock).mockResolvedValue(
mockHistoryItems
);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "history",
correlationId: "test-correlation-id",
historyItems: [{ url: "https://example.com", title: "Example" }],
});
});
});
describe("get-tab-content command", () => {
it("should get tab content and send it to the server", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "get-tab-content",
tabId: 123,
correlationId: "test-correlation-id",
};
const mockTab = { id: 123, url: "https://example.com" };
(browser.tabs.get as jest.Mock).mockResolvedValue(mockTab);
(browser.permissions.contains as jest.Mock).mockResolvedValue(true);
const mockScriptResult = [
{
links: [{ url: "https://example.com/page", text: "Page" }],
fullText: "Page content",
isTruncated: false,
totalLength: 12,
},
];
(browser.tabs.executeScript as jest.Mock).mockResolvedValue(
mockScriptResult
);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.get).toHaveBeenCalledWith(123);
expect(browser.permissions.contains).toHaveBeenCalledWith({
origins: ["https://example.com/*"],
});
expect(browser.tabs.executeScript).toHaveBeenCalled();
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "tab-content",
tabId: 123,
correlationId: "test-correlation-id",
isTruncated: false,
fullText: "Page content",
links: [{ url: "https://example.com/page", text: "Page" }],
totalLength: 12,
});
});
it("should throw an error if tab URL domain is in deny list", async () => {
// Arrange
const configWithDenyList: ExtensionConfig = {
secret: "test-secret",
toolSettings: {
"open-browser-tab": true,
"close-browser-tabs": true,
"get-list-of-open-tabs": true,
"get-recent-browser-history": true,
"get-tab-web-content": true,
"reorder-browser-tabs": true,
"find-highlight-in-browser-tab": true,
},
domainDenyList: ["example.com"], // Add example.com to deny list
ports: [8089],
auditLog: [],
};
(browser.storage.local.get as jest.Mock).mockResolvedValue({
config: configWithDenyList,
});
const request: ServerMessageRequest = {
cmd: "get-tab-content",
tabId: 123,
correlationId: "test-correlation-id",
};
const mockTab = { id: 123, url: "https://example.com" };
(browser.tabs.get as jest.Mock).mockResolvedValue(mockTab);
// Act & Assert
await expect(
messageHandler.handleDecodedMessage(request)
).rejects.toThrow("Domain in tab URL is in the deny list");
expect(browser.tabs.executeScript).not.toHaveBeenCalled();
});
it("should throw an error if permissions are denied", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "get-tab-content",
tabId: 123,
correlationId: "test-correlation-id",
};
const mockTab = { id: 123, url: "https://example.com" };
(browser.tabs.get as jest.Mock).mockResolvedValue(mockTab);
(browser.permissions.contains as jest.Mock).mockResolvedValue(false);
// Act & Assert
await expect(
messageHandler.handleDecodedMessage(request)
).rejects.toThrow();
expect(browser.tabs.executeScript).not.toHaveBeenCalled();
});
});
describe("reorder-tabs command", () => {
it("should reorder tabs and send confirmation to the server", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "reorder-tabs",
tabOrder: [123, 456, 789],
correlationId: "test-correlation-id",
};
(browser.tabs.move as jest.Mock).mockResolvedValue(undefined);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.move).toHaveBeenCalledTimes(3);
expect(browser.tabs.move).toHaveBeenNthCalledWith(1, 123, { index: 0 });
expect(browser.tabs.move).toHaveBeenNthCalledWith(2, 456, { index: 1 });
expect(browser.tabs.move).toHaveBeenNthCalledWith(3, 789, { index: 2 });
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "tabs-reordered",
correlationId: "test-correlation-id",
tabOrder: [123, 456, 789],
});
});
});
describe("find-highlight command", () => {
it("should find and highlight text in a tab", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "find-highlight",
tabId: 123,
queryPhrase: "test",
correlationId: "test-correlation-id",
};
const mockFindResults = { count: 5 };
(browser.find.find as jest.Mock).mockResolvedValue(mockFindResults);
(browser.tabs.update as jest.Mock).mockResolvedValue(undefined);
(browser.permissions.contains as jest.Mock).mockResolvedValue(true);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.find.find).toHaveBeenCalledWith("test", {
tabId: 123,
caseSensitive: true,
});
expect(browser.tabs.update).toHaveBeenCalledWith(123, { active: true });
expect(browser.find.highlightResults).toHaveBeenCalledWith({
tabId: 123,
});
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "find-highlight-result",
correlationId: "test-correlation-id",
noOfResults: 5,
});
});
it("should not highlight or activate tab if no results found", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "find-highlight",
tabId: 123,
queryPhrase: "test",
correlationId: "test-correlation-id",
};
const mockFindResults = { count: 0 };
const mockTab = { id: 123, url: "https://example.com" };
(browser.tabs.get as jest.Mock).mockResolvedValue(mockTab);
(browser.find.find as jest.Mock).mockResolvedValue(mockFindResults);
(browser.permissions.contains as jest.Mock).mockResolvedValue(true);
// Act
await messageHandler.handleDecodedMessage(request);
// Assert
expect(browser.tabs.update).not.toHaveBeenCalled();
expect(browser.find.highlightResults).not.toHaveBeenCalled();
expect(mockClient.sendResourceToServer).toHaveBeenCalledWith({
resource: "find-highlight-result",
correlationId: "test-correlation-id",
noOfResults: 0,
});
});
it("should throw an error if permissions are denied", async () => {
// Arrange
const request: ServerMessageRequest = {
cmd: "find-highlight",
tabId: 123,
queryPhrase: "test",
correlationId: "test-correlation-id",
};
const mockTab = { id: 123, url: "https://example.com" };
(browser.tabs.get as jest.Mock).mockResolvedValue(mockTab);
(browser.permissions.contains as jest.Mock).mockResolvedValue(false);
// Act & Assert
await expect(
messageHandler.handleDecodedMessage(request)
).rejects.toThrow();
expect(browser.find.find).not.toHaveBeenCalled();
});
});
});
});
```
--------------------------------------------------------------------------------
/firefox-extension/options.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Options page script for Browser Control MCP extension
*/
import {
getSecret,
AVAILABLE_TOOLS,
getAllToolSettings,
setToolEnabled,
getDomainDenyList,
setDomainDenyList,
getPorts,
setPorts,
getAuditLog,
clearAuditLog,
getToolNameById,
} from "./extension-config";
const secretDisplay = document.getElementById(
"secret-display"
) as HTMLDivElement;
const copyButton = document.getElementById("copy-button") as HTMLButtonElement;
const statusElement = document.getElementById("status") as HTMLDivElement;
const toolSettingsContainer = document.getElementById(
"tool-settings-container"
) as HTMLDivElement;
const domainDenyListTextarea = document.getElementById(
"domain-deny-list"
) as HTMLTextAreaElement;
const saveDomainListsButton = document.getElementById(
"save-domain-lists"
) as HTMLButtonElement;
const domainStatusElement = document.getElementById(
"domain-status"
) as HTMLDivElement;
const portsInput = document.getElementById("ports-input") as HTMLInputElement;
const savePortsButton = document.getElementById("save-ports") as HTMLButtonElement;
const portsStatusElement = document.getElementById("ports-status") as HTMLDivElement;
const auditLogContainer = document.getElementById("audit-log-container") as HTMLDivElement;
const clearAuditLogButton = document.getElementById("clear-audit-log") as HTMLButtonElement;
const auditLogStatusElement = document.getElementById("audit-log-status") as HTMLDivElement;
/**
* Loads the secret from storage and displays it
*/
async function loadSecret() {
try {
const secret = await getSecret();
// Check if secret exists
if (secret) {
secretDisplay.textContent = secret;
} else {
secretDisplay.textContent =
"No secret found. Please reinstall the extension.";
secretDisplay.style.color = "red";
copyButton.disabled = true;
}
} catch (error) {
console.error("Error loading secret:", error);
secretDisplay.textContent =
"Error loading secret. Please check console for details.";
secretDisplay.style.color = "red";
copyButton.disabled = true;
}
}
/**
* Copies the secret to clipboard
*/
async function copyToClipboard(event: MouseEvent) {
if (!event.isTrusted) {
return;
}
try {
const secret = secretDisplay.textContent;
if (
!secret ||
secret === "Loading..." ||
secret.includes("No secret found") ||
secret.includes("Error loading")
) {
return;
}
await navigator.clipboard.writeText(secret);
// Show success message
statusElement.textContent = "Secret copied to clipboard!";
setTimeout(() => {
statusElement.textContent = "";
}, 3000);
} catch (error) {
console.error("Error copying to clipboard:", error);
statusElement.textContent = "Failed to copy to clipboard";
statusElement.style.color = "red";
setTimeout(() => {
statusElement.textContent = "";
statusElement.style.color = "";
}, 3000);
}
}
/**
* Creates the tool settings UI
*/
async function createToolSettingsUI() {
const toolSettings = await getAllToolSettings();
// Clear existing content
toolSettingsContainer.innerHTML = "";
// Create a toggle switch for each tool
AVAILABLE_TOOLS.forEach((tool) => {
const isEnabled = toolSettings[tool.id] !== false; // Default to true if not set
const toolRow = document.createElement("div");
toolRow.className = "tool-row";
const labelContainer = document.createElement("div");
labelContainer.className = "tool-label-container";
const toolName = document.createElement("div");
toolName.className = "tool-name";
toolName.textContent = tool.name;
const toolDescription = document.createElement("div");
toolDescription.className = "tool-description";
toolDescription.textContent = tool.description;
labelContainer.appendChild(toolName);
labelContainer.appendChild(toolDescription);
const toggleContainer = document.createElement("label");
toggleContainer.className = "toggle-switch";
const checkbox = document.createElement("input");
checkbox.type = "checkbox";
checkbox.checked = isEnabled;
checkbox.dataset.toolId = tool.id;
checkbox.addEventListener("change", handleToolToggle);
const slider = document.createElement("span");
slider.className = "slider";
toggleContainer.appendChild(checkbox);
toggleContainer.appendChild(slider);
toolRow.appendChild(labelContainer);
toolRow.appendChild(toggleContainer);
toolSettingsContainer.appendChild(toolRow);
});
}
/**
* Handles toggling a tool on/off
*/
async function handleToolToggle(event: Event) {
const checkbox = event.target as HTMLInputElement;
const toolId = checkbox.dataset.toolId;
const isEnabled = checkbox.checked;
if (!toolId) {
console.error("Tool ID not found");
return;
}
try {
await setToolEnabled(toolId, isEnabled);
// No status message displayed
} catch (error) {
console.error("Error saving tool setting:", error);
// Revert the checkbox state
checkbox.checked = !isEnabled;
}
}
/**
* Loads the domain lists from storage and displays them
*/
async function loadDomainLists() {
try {
// Load deny list
const denyList = await getDomainDenyList();
domainDenyListTextarea.value = denyList.join("\n");
} catch (error) {
console.error("Error loading domain lists:", error);
domainStatusElement.textContent =
"Error loading domain lists. Please check console for details.";
domainStatusElement.style.color = "red";
setTimeout(() => {
domainStatusElement.textContent = "";
domainStatusElement.style.color = "";
}, 3000);
}
}
/**
* Saves the domain lists to storage
*/
async function saveDomainLists(event: MouseEvent) {
if (!event.isTrusted) {
return;
}
try {
// Parse deny list (split by newlines and filter out empty lines)
const denyListText = domainDenyListTextarea.value.trim();
const denyList = denyListText
? denyListText
.split("\n")
.map((domain) => domain.trim())
.filter(Boolean)
: [];
// Save to storage
await setDomainDenyList(denyList);
// Show success message
domainStatusElement.textContent = "Domain deny list saved successfully!";
domainStatusElement.style.color = "#4caf50";
setTimeout(() => {
domainStatusElement.textContent = "";
domainStatusElement.style.color = "";
}, 3000);
} catch (error) {
console.error("Error saving domain lists:", error);
domainStatusElement.textContent = "Failed to save domain lists";
domainStatusElement.style.color = "red";
setTimeout(() => {
domainStatusElement.textContent = "";
domainStatusElement.style.color = "";
}, 3000);
}
}
/**
* Loads the ports from storage and displays them
*/
async function loadPorts() {
try {
const ports = await getPorts();
portsInput.value = ports.join(", ");
} catch (error) {
console.error("Error loading ports:", error);
portsStatusElement.textContent =
"Error loading ports. Please check console for details.";
portsStatusElement.style.color = "red";
setTimeout(() => {
portsStatusElement.textContent = "";
portsStatusElement.style.color = "";
}, 3000);
}
}
/**
* Saves the ports to storage
*/
async function savePorts(event: MouseEvent) {
if (!event.isTrusted) {
return;
}
try {
// Parse ports (split by commas and filter out empty values)
const portsText = portsInput.value.trim();
const portStrings = portsText
? portsText
.split(",")
.map((port) => port.trim())
.filter(Boolean)
: [];
// Validate and convert to numbers
const ports: number[] = [];
for (const portStr of portStrings) {
const port = parseInt(portStr, 10);
if (isNaN(port) || port < 1 || port > 65535) {
throw new Error(`Invalid port number: ${portStr}. Ports must be between 1 and 65535.`);
}
ports.push(port);
}
// Ensure at least one port is provided
if (ports.length === 0) {
throw new Error("At least one port must be specified.");
}
// Save to storage
await setPorts(ports);
// Reload the extension:
browser.runtime.reload();
} catch (error) {
console.error("Error saving ports:", error);
portsStatusElement.textContent = error instanceof Error ? error.message : "Failed to save ports";
portsStatusElement.style.color = "red";
setTimeout(() => {
portsStatusElement.textContent = "";
portsStatusElement.style.color = "";
}, 3000);
}
}
/**
* Loads the audit log from storage and displays it
*/
async function loadAuditLog() {
try {
const auditLog = await getAuditLog();
// Clear existing content
auditLogContainer.innerHTML = "";
if (auditLog.length === 0) {
// Show empty state
const emptyDiv = document.createElement("div");
emptyDiv.className = "audit-log-empty";
emptyDiv.textContent = "No tool usage recorded yet.";
auditLogContainer.appendChild(emptyDiv);
return;
}
// Create table
const table = document.createElement("table");
table.className = "audit-log-table";
// Create header
const thead = document.createElement("thead");
const headerRow = document.createElement("tr");
const headers = ["Tool", "Timestamp", "Domain"];
headers.forEach(headerText => {
const th = document.createElement("th");
th.textContent = headerText;
headerRow.appendChild(th);
});
thead.appendChild(headerRow);
table.appendChild(thead);
// Create body
const tbody = document.createElement("tbody");
auditLog.forEach(entry => {
const row = document.createElement("tr");
// Tool name
const toolCell = document.createElement("td");
toolCell.textContent = getToolNameById(entry.toolId);
row.appendChild(toolCell);
// Timestamp
const timestampCell = document.createElement("td");
timestampCell.className = "audit-log-timestamp";
const date = new Date(entry.timestamp);
timestampCell.textContent = date.toLocaleString();
row.appendChild(timestampCell);
// URL Domain
const urlCell = document.createElement("td");
urlCell.className = "audit-log-url";
if (entry.url) {
// Show only the domain part of the URL
try {
const urlObj = new URL(entry.url);
urlCell.textContent = urlObj.hostname;
} catch (e) {
console.error("Invalid URL in audit log entry:", e);
urlCell.textContent = "Invalid URL";
}
} else {
urlCell.textContent = "-";
}
row.appendChild(urlCell);
tbody.appendChild(row);
});
table.appendChild(tbody);
auditLogContainer.appendChild(table);
} catch (error) {
console.error("Error loading audit log:", error);
auditLogContainer.innerHTML = '<div class="audit-log-empty">Error loading audit log. Please check console for details.</div>';
}
}
/**
* Clears the audit log
*/
async function handleClearAuditLog(event: MouseEvent) {
if (!event.isTrusted) {
return;
}
try {
await clearAuditLog();
// Reload the audit log display
await loadAuditLog();
// Show success message
auditLogStatusElement.textContent = "Audit log cleared successfully!";
auditLogStatusElement.style.color = "#4caf50";
setTimeout(() => {
auditLogStatusElement.textContent = "";
auditLogStatusElement.style.color = "";
}, 3000);
} catch (error) {
console.error("Error clearing audit log:", error);
auditLogStatusElement.textContent = "Failed to clear audit log";
auditLogStatusElement.style.color = "red";
setTimeout(() => {
auditLogStatusElement.textContent = "";
auditLogStatusElement.style.color = "";
}, 3000);
}
}
/**
* Initializes the collapsible sections
*/
function initializeCollapsibleSections() {
const sectionHeaders = document.querySelectorAll(".section-container > h2");
sectionHeaders.forEach((header) => {
// Add click event listener to toggle section visibility
header.addEventListener("click", (event) => {
event.preventDefault();
// Toggle the collapsed class on the header
header.classList.toggle("collapsed");
// Toggle the collapsed class on the section content
const sectionContent = header.nextElementSibling as HTMLElement;
sectionContent.classList.toggle("collapsed");
});
});
}
function showPermissionRequest(url: string) {
const domain = new URL(url).hostname;
const origin = new URL(url).origin;
// Show the modal and hide the main content
const modal = document.getElementById("permission-modal") as HTMLDivElement;
const mainContent = document.getElementById("main-content") as HTMLDivElement;
const domainElement = document.getElementById("permission-domain") as HTMLDivElement;
const grantBtn = document.getElementById("grant-btn") as HTMLButtonElement;
const cancelBtn = document.getElementById("cancel-btn") as HTMLButtonElement;
const permissionText = document.getElementById("permission-text") as HTMLParagraphElement;
// Set the domain in the modal
domainElement.textContent = domain;
// Update permission text for URL permission
permissionText.textContent = "This will allow the extension to interact with pages on this domain as requested by the MCP server.";
// Show modal and blur main content
modal.classList.remove("hidden");
mainContent.classList.add("modal-open");
// Handle grant permission button click
const handleGrant = async () => {
try {
const granted = await browser.permissions.request({
origins: [`${origin}/*`],
});
if (granted) {
// Permission granted, close the window or redirect back
window.close();
} else {
// Permission denied, hide modal and show main content
hidePermissionModal();
}
} catch (error) {
console.error("Error requesting permission:", error);
hidePermissionModal();
}
};
// Handle cancel button click
const handleCancel = () => {
hidePermissionModal();
};
// Add event listeners
grantBtn.addEventListener("click", handleGrant);
cancelBtn.addEventListener("click", handleCancel);
// Store references to remove listeners later
(window as any).permissionHandlers = {
handleGrant,
handleCancel,
grantBtn,
cancelBtn
};
}
function showGlobalPermissionRequest(permissions: string[]) {
// Show the modal and hide the main content
const modal = document.getElementById("permission-modal") as HTMLDivElement;
const mainContent = document.getElementById("main-content") as HTMLDivElement;
const domainElement = document.getElementById("permission-domain") as HTMLDivElement;
const grantBtn = document.getElementById("grant-btn") as HTMLButtonElement;
const cancelBtn = document.getElementById("cancel-btn") as HTMLButtonElement;
const permissionText = document.getElementById("permission-text") as HTMLParagraphElement;
// Set the permissions in the modal
domainElement.textContent = permissions.join(", ");
// Update permission text for global permissions
permissionText.textContent = "This will allow the extension to use these browser capabilities as requested by the MCP server.";
// Show modal and blur main content
modal.classList.remove("hidden");
mainContent.classList.add("modal-open");
// Handle grant permission button click
const handleGrant = async () => {
try {
const granted = await browser.permissions.request({
permissions: permissions as browser.permissions.Permissions["permissions"],
});
if (granted) {
// Permission granted, close the window or redirect back
window.close();
} else {
// Permission denied, hide modal and show main content
hidePermissionModal();
}
} catch (error) {
console.error("Error requesting permission:", error);
hidePermissionModal();
}
};
// Handle cancel button click
const handleCancel = () => {
hidePermissionModal();
};
// Add event listeners
grantBtn.addEventListener("click", handleGrant);
cancelBtn.addEventListener("click", handleCancel);
// Store references to remove listeners later
(window as any).permissionHandlers = {
handleGrant,
handleCancel,
grantBtn,
cancelBtn
};
}
function hidePermissionModal() {
const modal = document.getElementById("permission-modal") as HTMLDivElement;
const mainContent = document.getElementById("main-content") as HTMLDivElement;
// Hide modal and restore main content
modal.classList.add("hidden");
mainContent.classList.remove("modal-open");
// Clean up event listeners
const handlers = (window as any).permissionHandlers;
if (handlers) {
handlers.grantBtn.removeEventListener("click", handlers.handleGrant);
handlers.cancelBtn.removeEventListener("click", handlers.handleCancel);
delete (window as any).permissionHandlers;
}
}
// Initialize the page
copyButton.addEventListener("click", copyToClipboard);
saveDomainListsButton.addEventListener("click", saveDomainLists);
savePortsButton.addEventListener("click", savePorts);
clearAuditLogButton.addEventListener("click", handleClearAuditLog);
document.addEventListener("DOMContentLoaded", () => {
loadSecret();
createToolSettingsUI();
loadDomainLists();
loadPorts();
loadAuditLog();
initializeCollapsibleSections();
// Ensure modal is hidden by default
const modal = document.getElementById("permission-modal") as HTMLDivElement;
const mainContent = document.getElementById("main-content") as HTMLDivElement;
modal.classList.add("hidden");
mainContent.classList.remove("modal-open");
const params = new URLSearchParams(window.location.search);
const requestUrl = params.get("requestUrl");
const requestPermissions = params.get("requestPermissions");
if (requestUrl) {
// Show UI for requesting permission for this specific URL
showPermissionRequest(requestUrl);
} else if (requestPermissions) {
// Show UI for requesting global permissions
try {
const permissions = JSON.parse(decodeURIComponent(requestPermissions));
showGlobalPermissionRequest(permissions);
} catch (error) {
console.error("Error parsing requestPermissions:", error);
}
}
// Add interval to refresh the audit log every 5 seconds:
setInterval(() => {
loadAuditLog();
}, 5000);
});
```