🦊 LittleFoxMCP

Firefox ↔ Model Context Protocol Bridge

LittleFoxMCP connects Firefox with the Model Context Protocol (MCP), enabling AI assistants and automation tools to interact with your browser, access web content, manage cookies/storage, and perform automated actions.

📋 Table of Contents

• Features
• Architecture
• Installation
• Usage
• MCP Tools
• Browser Actions
• Configuration
• Development
• API Reference
• Troubleshooting

✨ Features

Core Capabilities

• MCP Protocol Support - Full JSON-RPC 2.0 implementation over HTTP
• Real-time Communication - WebSocket bridge for bidirectional messaging
• DOM Access - Extract content from any webpage
• Cookie Management - Get, set, and delete cookies
• Storage Access - Interact with localStorage and sessionStorage
• Browser Automation - Click, type, navigate, scroll, and more
• JavaScript Injection - Execute arbitrary code in page context
• Network Interception - Monitor HTTP requests/responses
• Debug Console - Execute commands and capture console logs
• DevTools Inspector - Inspect DOM elements with DevTools-like detail
• Debugger Control - Set breakpoints and step-through debugging
• Performance Profiler - Measure web performance metrics

Advanced Actions

| Action | Description | |--------|-------------| | injectJS | Execute JavaScript in page context | | typeNative | Character-by-character typing with full event support | | fillNative | Native input filling for React/Angular/Vue forms | | press | Press specific keys | | hover | Mouse hover over elements |

DevTools Suite (New in v1.2.0)

| Tool | Description | |------|-------------| | debug_console | Execute commands and capture console logs | | devtools_inspector | Inspect elements with box model, styles, events | | debugger_control | Set breakpoints, step-through, evaluate expressions | | performance_profiler | Measure FPS, memory, navigation timing, resources |

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     EXTERNAL MCP CLIENT                         │
│                    (Claude Desktop, etc.)                       │
│                         HTTP localhost:3000                     │
└────────────────────────────┬────────────────────────────────────┘
                             │ JSON-RPC 2.0
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                   NATIVE HOST (Node.js)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  MCP Server  │  │  WebSocket   │  │   Native     │          │
│  │  (HTTP:3000) │  │  Bridge:3001 │  │  Messaging   │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                    │               │                            │
│                    └───────┬───────┘                            │
│                            │ Event Bus                          │
│  ┌─────────────────────────┴─────────────────────────┐          │
│  │              TOOL FACTORY                         │          │
│  │  DOM  │  Cookies  │  Storage  │  Actions  │ Net │          │
│  └───────────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              │ WebSocket / Native Messaging│
              ▼                             ▼
┌─────────────────────┐         ┌─────────────────────┐
│  BACKGROUND.JS      │         │   CONTENT SCRIPT    │
│  (Persistent)       │◄───────►│   (Web Page)        │
│  - WebSocket Bridge │         │   - DOM Access      │
│  - Message Handler  │         │   - Storage         │
│  - Tool Routing     │         │   - Actions         │
└─────────────────────┘         │   - injectJS()      │
                                │   - typeNative()    │
                                │   - fillNative()    │
                                └─────────────────────┘

Components

| Component | Port | Description | |-----------|------|-------------| | MCP Server | 3000 | HTTP server for external MCP clients | | WebSocket Bridge | 3001 | Real-time communication with Firefox extension | | Native Messaging | stdio | Direct Firefox ↔ Node.js communication |

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• Firefox >= 78.0

Step 1: Install Dependencies

cd native-host
npm install

Step 2: Configure Native Messaging

1. Edit firefox-mcp-host.json:

{
  "name": "littlefox_mcp_host",
  "description": "LittleFoxMCP - Native Messaging Host",
  "path": "/absolute/path/to/littlefox-mcp/native-host/start.sh",
  "type": "stdio",
  "allowed_extensions": ["littlefox-mcp@localhost"]
}

2. Copy the manifest to Firefox's native messaging directory:

# Linux
cp firefox-mcp-host.json ~/.mozilla/native-messaging-hosts/

# macOS
cp firefox-mcp-host.json ~/Library/Application Support/Mozilla/NativeMessagingHosts/

# Windows
# Copy to: %APPDATA%\Mozilla\NativeMessagingHosts\

Step 3: Load Firefox Extension

1. Open Firefox and navigate to about:debugging
2. Click "This Firefox"
3. Click "Load Temporary Add-on"
4. Select firefox-extension/manifest.json

🚀 Usage

Start the Native Host

cd native-host
npm start

Or in development mode with auto-reload:

npm run dev

Connect MCP Client

Configure your MCP client to connect to:

http://localhost:3000/mcp

Example: Initialize Connection

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {}
  },
  "id": 1
}

Example: Get DOM Content

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_dom_content",
    "arguments": {
      "selector": "body"
    }
  },
  "id": 2
}

Example: Click an Element

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "browser_actions",
    "arguments": {
      "action": "click",
      "selector": "#submit-button"
    }
  },
  "id": 3
}

🛠️ MCP Tools

1. get_dom_content

Extract DOM content from the active tab.

| Parameter | Type | Description | |-----------|------|-------------| | tabId | number | Target tab ID (default: active tab) | | selector | string | CSS selector (default: entire document) | | includeScripts | boolean | Include <script> tags (default: false) | | includeStyles | boolean | Include <style> tags (default: false) |

Response:

{
  "html": "<html>...</html>",
  "text": "Page text content",
  "url": "https://example.com",
  "title": "Example Domain"
}

2. manage_cookies

Manage browser cookies.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | get, set, delete, clear | | url | string | Cookie URL | | name | string | Cookie name | | value | string | Cookie value (for set) |

Example - Get Cookies:

{
  "name": "manage_cookies",
  "arguments": {
    "action": "get",
    "url": "https://example.com"
  }
}

3. manage_storage

Manage localStorage and sessionStorage.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | get, set, delete, clear | | storageType | string | local or session (default: local) | | tabId | number | Target tab ID | | key | string | Storage key | | value | string | Storage value (for set) |

4. browser_actions

Perform browser automation actions.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | Action type (see below) | | tabId | number | Target tab ID | | selector | string | CSS selector for target element | | value | string | Value for type/fill/navigate | | code | string | JavaScript code for injectJS | | options | object | Additional options |

5. network_interceptor

Intercept and monitor network requests.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | start_intercept, stop_intercept, get_requests | | tabId | number | Target tab ID | | urlPattern | string | URL pattern to filter | | types | array | Request types to intercept |

6. mcp_guide

Obtiene documentación completa sobre cómo usar LittleFoxMCP. Esta herramienta proporciona información detallada sobre arquitectura, herramientas disponibles, acciones, ejemplos de uso, configuración y troubleshooting.

| Parameter | Type | Description | |-----------|------|-------------| | topic | string | Tema específico a consultar (ver abajo) |

Topics disponibles:

| Topic | Descripción | |-------|-------------| | all | Guía completa (default) | | architecture | Arquitectura del sistema y flujo de comunicación | | tools | Lista detallada de todas las herramientas MCP | | actions | Todas las acciones del navegador con ejemplos | | examples | Ejemplos de uso con requests JSON-RPC completos | | configuration | Configuración de variables de entorno y native messaging | | troubleshooting | Solución de problemas comunes | | quickstart | Guía de inicio rápido paso a paso |

Example - Get Full Guide:

{
  "name": "mcp_guide",
  "arguments": {
    "topic": "all"
  }
}

Example - Get Tools Information:

{
  "name": "mcp_guide",
  "arguments": {
    "topic": "tools"
  }
}

Example - Get Actions Information:

{
  "name": "mcp_guide",
  "arguments": {
    "topic": "actions"
  }
}

Example - Get Usage Examples:

{
  "name": "mcp_guide",
  "arguments": {
    "topic": "examples"
  }
}

Response Structure (topic: all):

{
  "title": "LittleFoxMCP - Guía Completa",
  "version": "1.1.0",
  "sections": {
    "overview": { ... },
    "architecture": { ... },
    "tools": { ... },
    "actions": { ... },
    "examples": { ... },
    "quickstart": { ... }
  }
}

7. debug_console

Consola de depuración - Ejecuta comandos y captura logs del navegador. Permite ejecutar JavaScript en la consola, capturar logs (log, info, warn, error, debug), y manejar errores no capturados.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | execute, get_logs, clear_logs, start_listening, stop_listening | | command | string | Comando JavaScript a ejecutar (solo para execute) | | logLevel | array | Filtros de nivel: ["log", "info", "warn", "error", "debug"] | | tabId | number | ID de pestaña (default: activa) | | limit | number | Máximo logs a retornar (default: 100) |

Example - Execute Command:

{
  "name": "debug_console",
  "arguments": {
    "action": "execute",
    "command": "console.log('Hello from MCP'); return document.title;"
  }
}

Example - Get Error Logs:

{
  "name": "debug_console",
  "arguments": {
    "action": "get_logs",
    "logLevel": ["error", "warn"],
    "limit": 50
  }
}

Example - Clear Logs:

{
  "name": "debug_console",
  "arguments": {
    "action": "clear_logs"
  }
}

Response Structure:

{
  "success": true,
  "data": {
    "logs": [
      {
        "type": "log",
        "message": ["Hello from MCP"],
        "timestamp": 1709337600000,
        "url": "https://example.com",
        "title": "Example Page"
      },
      {
        "type": "error",
        "message": ["Uncaught TypeError: x is undefined"],
        "timestamp": 1709337601000,
        "url": "https://example.com/script.js",
        "stackTrace": "func@https://example.com/script.js:42:15"
      }
    ],
    "count": 2,
    "total": 150
  }
}

8. devtools_inspector

Inspector de elementos del DOM - Obtiene información detallada de elementos tipo DevTools.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | inspect, get_computed_style, get_event_listeners, highlight, unhighlight | | selector | string | CSS selector del elemento | | tabId | number | ID de pestaña (default: activa) | | includeInherited | boolean | Incluir estilos heredados | | color | string | Color del highlight (default: rgba(255, 0, 0, 0.3)) |

Example - Inspect Element:

{
  "name": "devtools_inspector",
  "arguments": {
    "action": "inspect",
    "selector": "#main-content"
  }
}

Example - Get Computed Styles:

{
  "name": "devtools_inspector",
  "arguments": {
    "action": "get_computed_style",
    "selector": "button.submit",
    "includeInherited": true
  }
}

Example - Highlight Element:

{
  "name": "devtools_inspector",
  "arguments": {
    "action": "highlight",
    "selector": ".important-element",
    "color": "rgba(0, 255, 0, 0.3)"
  }
}

Response Structure (inspect):

{
  "success": true,
  "data": {
    "tagName": "DIV",
    "id": "main-content",
    "className": "container main",
    "attributes": { "data-id": "123" },
    "boxModel": {
      "width": 800,
      "height": 600,
      "padding": {"top": 10, "right": 10, "bottom": 10, "left": 10},
      "margin": {"top": 20, "right": 20, "bottom": 20, "left": 20},
      "border": {"top": 1, "right": 1, "bottom": 1, "left": 1}
    },
    "computedStyles": {
      "display": "block",
      "position": "relative",
      "backgroundColor": "rgb(255, 255, 255)"
    },
    "rect": {"x": 100, "y": 200, "width": 800, "height": 600}
  }
}

9. debugger_control

Control de depuración de JavaScript - Set breakpoints, step-through debugging, evaluate expressions.

⚠️ Requires debugger permission in manifest.json

| Parameter | Type | Description | |-----------|------|-------------| | action | string | attach, detach, set_breakpoint, remove_breakpoint, pause, resume, step_over, step_into, step_out, evaluate | | tabId | number | ID de pestaña a depurar (required) | | url | string | URL del script para breakpoint | | lineNumber | number | Línea para breakpoint (0-based) | | condition | string | Condición para breakpoint condicional | | expression | string | Expresión a evaluar en contexto paused |

Example - Attach Debugger:

{
  "name": "debugger_control",
  "arguments": {
    "action": "attach",
    "tabId": 12345
  }
}

Example - Set Conditional Breakpoint:

{
  "name": "debugger_control",
  "arguments": {
    "action": "set_breakpoint",
    "tabId": 12345,
    "url": "https://example.com/app.js",
    "lineNumber": 42,
    "condition": "user.isLoggedIn === true"
  }
}

Example - Evaluate Expression:

{
  "name": "debugger_control",
  "arguments": {
    "action": "evaluate",
    "tabId": 12345,
    "expression": "window.currentUser"
  }
}

10. performance_profiler

Perfilado de rendimiento - Mide métricas de performance de páginas web.

| Parameter | Type | Description | |-----------|------|-------------| | action | string | start_profiling, stop_profiling, get_metrics, get_resource_timing, get_navigation_timing | | tabId | number | ID de pestaña | | duration | number | Duración del profiling en segundos (default: 30) | | metrics | array | Métricas: ["fps", "memory", "paint"] |

Example - Get Metrics:

{
  "name": "performance_profiler",
  "arguments": {
    "action": "get_metrics",
    "tabId": 12345
  }
}

Example - Get Resource Timing:

{
  "name": "performance_profiler",
  "arguments": {
    "action": "get_resource_timing",
    "tabId": 12345
  }
}

Response Structure (get_metrics):

{
  "success": true,
  "data": {
    "url": "https://example.com",
    "title": "Example Page",
    "navigation": {
      "domContentLoaded": 450,
      "loadComplete": 1200,
      "ttfb": 120
    },
    "paint": {
      "first-paint": 320,
      "first-contentful-paint": 450
    },
    "resourceCount": 45,
    "memory": {
      "usedJSHeapSize": "45 MB",
      "totalJSHeapSize": "120 MB"
    }
  }
}

🖱️ Browser Actions

Action Types

| Action | Description | Parameters | |--------|-------------|------------| | click | Click an element | selector | | type | Type text (basic events) | selector, value | | typeNative | Type with full event support | selector, value, options.delay | | fill | Fill input (basic) | selector, value | | fillNative | Fill with native setter | selector, value | | navigate | Navigate to URL | value (URL) | | scroll | Scroll page/element | selector, x, y, behavior | | screenshot | Capture visible tab | - | | injectJS | Execute JavaScript | code, options.timeout | | press | Press a key | selector, value (key) | | hover | Hover over element | selector |

injectJS - JavaScript Injection

Execute arbitrary JavaScript in the page context (not content script context).

Example - Get Page Title:

{
  "name": "browser_actions",
  "arguments": {
    "action": "injectJS",
    "code": "(function(){ return { title: document.title, url: window.location.href }; })()"
  }
}

Example - Modify DOM:

{
  "name": "browser_actions",
  "arguments": {
    "action": "injectJS",
    "code": "(function(){ document.body.style.background = 'yellow'; return { success: true }; })()"
  }
}

Example - Extract Data:

{
  "name": "browser_actions",
  "arguments": {
    "action": "injectJS",
    "code": "(function(){ return Array.from(document.querySelectorAll('h2')).map(h => h.textContent); })()"
  }
}

typeNative - Native Typing

Types character-by-character with full keyboard event support for modern frameworks.

Events Fired:

• focus
• compositionstart
• compositionupdate
• keydown
• beforeinput (HTML5 standard)
• input
• compositionend
• keyup
• change

Compatible Frameworks: React 16+, Angular 2+, Vue 2+, Vue 3+, Svelte

Example:

{
  "name": "browser_actions",
  "arguments": {
    "action": "typeNative",
    "selector": "input#email",
    "value": "[email protected]",
    "options": {
      "delay": 50
    }
  }
}

fillNative - Native Filling

Fills input using native DOM setter for framework bypass.

Example:

{
  "name": "browser_actions",
  "arguments": {
    "action": "fillNative",
    "selector": "textarea[aria-label='Ask a question']",
    "value": "Your question here"
  }
}

⚙️ Configuration

Environment Variables

Create a .env file in native-host/:

# Server Configuration
MCP_PORT=3000
MCP_HOST=localhost

# Logging
MCP_LOG_LEVEL=info
MCP_LOG_FORMAT=text

# Timeouts (milliseconds)
MCP_REQUEST_TIMEOUT=30000
MCP_RECONNECT_DELAY=5000

# Limits
MCP_MAX_MESSAGE_SIZE=1048576

# Extension
MCP_EXTENSION_ID=firefox-mcp-connector@localhost

Configuration Options

| Variable | Default | Description | |----------|---------|-------------| | MCP_PORT | 3000 | HTTP server port | | MCP_HOST | localhost | Server bind address | | MCP_LOG_LEVEL | info | Logging level (error, warn, info, debug, trace) | | MCP_REQUEST_TIMEOUT | 30000 | Request timeout in ms | | MCP_RECONNECT_DELAY | 5000 | WebSocket reconnect delay in ms | | MCP_MAX_MESSAGE_SIZE | 1048576 | Max message size in bytes (1MB) |

👨‍💻 Development

Project Structure

littlefox-mcp/
├── firefox-extension/
│   ├── manifest.json          # Extension manifest
│   ├── icons/                 # Extension icons
│   ├── lib/
│   │   └── event-bridge.js    # Event system
│   └── src/
│       ├── background/        # Background scripts
│       │   ├── background.js
│       │   ├── websocket-bridge.js
│       │   └── *.handler.js
│       ├── content/
│       │   └── content-script.js
│       └── popup/
│           ├── popup.html
│           └── popup.js
├── native-host/
│   ├── package.json
│   ├── firefox-mcp-host.json  # Native messaging manifest
│   ├── start.sh               # Startup script
│   ├── src/
│   │   ├── main.js            # Entry point
│   │   ├── core/              # Core services
│   │   │   ├── mcp-server.js
│   │   │   ├── websocket-server.js
│   │   │   ├── native-messaging.js
│   │   │   └── event-bus.js
│   │   ├── factories/         # Factory pattern
│   │   │   ├── tool-factory.js
│   │   │   └── register-tools.js
│   │   ├── tools/             # MCP tools
│   │   │   ├── base-tool.js
│   │   │   ├── dom-tool.js
│   │   │   ├── cookies-tool.js
│   │   │   ├── storage-tool.js
│   │   │   ├── actions-tool.js
│   │   │   └── network-tool.js
│   │   ├── config/            # Configuration
│   │   │   └── index.js
│   │   └── utils/             # Utilities
│   │       └── logger.js
│   └── types/
│       └── index.js           # JSDoc types
└── change/
    └── CHANGELOG.md

Scripts

# Start native host
npm start

# Development mode with auto-reload
npm run dev

# Run linter
npm run lint

# Run tests
npm test

Debugging

1. Native Host Logs:

   # Set log level to debug
   MCP_LOG_LEVEL=debug npm start

2. Extension Logs:

   • Open Firefox Developer Tools (F12)
   • Enable "Debug Add-ons" in about:debugging
   • Click "Inspect" on LittleFoxMCP

3. WebSocket Monitoring:

   • Use WebSocket clients like wscat to test:

   wscat -c ws://localhost:3001

📡 API Reference

MCP Protocol Methods

initialize

Initialize connection with MCP server.

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": 1
}

tools/list

Get list of available tools.

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}

tools/call

Call a specific tool.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {}
  },
  "id": 3
}

ping

Health check.

{
  "jsonrpc": "2.0",
  "method": "ping",
  "id": 4
}

HTTP Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check | | /tools | GET | List available tools | | /mcp | POST | MCP JSON-RPC endpoint |

🔧 Troubleshooting

Common Issues

1. "Cannot connect to Native Host"

Solution:

• Ensure npm start is running
• Check that port 3000 and 3001 are not in use
• Verify .env configuration

2. "Extension not connected"

Solution:

• Reload extension in about:debugging
• Check Firefox console for errors
• Verify native messaging manifest path

3. "Action not working on React/Vue forms"

Solution:

• Use typeNative or fillNative instead of type/fill
• These actions fire all necessary events for framework compatibility

4. "injectJS timeout"

Solution:

• Ensure code returns serializable result
• Add explicit return statement
• Check for JavaScript errors in browser console

Error Codes

| Code | Description | |------|-------------| | -32700 | Parse error | | -32600 | Invalid Request | | -32601 | Method not found | | -32602 | Invalid params | | -32603 | Internal error |

📄 License

MIT License

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📚 Resources

• Source Code (GitLab)
• Model Context Protocol Specification
• Firefox Native Messaging
• JSON-RPC 2.0 Specification

Built with ❤️ by the LittleFoxMCP Team

🔗 Repository: https://gitlab.com/bytedogssyndicate1/littlefox-mcp