# Firefox MCP Server

> **Advanced Firefox browser automation with comprehensive debugging capabilities**

A powerful Model Context Protocol (MCP) server that provides sophisticated Firefox browser automation through 28 specialized tools. Designed for AI assistants and automation workflows requiring multi-session management, real-time debugging, and comprehensive web interaction capabilities.

## 🌟 Key Features

### Multi-Session Architecture
- **Isolated Browser Sessions**: Each session runs in a completely separate context with independent cookies, storage, and debugging
- **Perfect for Multiplayer Testing**: Test multiplayer games and multi-user applications seamlessly
- **Concurrent Operations**: Manage multiple browser sessions simultaneously from a single interface

### Comprehensive Debugging Suite
- **Real-time Console Monitoring**: Capture all console output (log, error, warn, info, debug)
- **JavaScript Error Tracking**: Monitor unhandled errors with full stack traces
- **Network Activity Monitoring**: Track HTTP requests, responses, and timing data
- **WebSocket Traffic Capture**: Perfect for Phoenix LiveView and real-time application debugging
- **Performance Metrics**: Monitor DOM timing, paint events, and memory usage

### Advanced Interaction Capabilities
- **Precise Element Interaction**: Click, type, and interact with any web element
- **Keyboard Event Simulation**: Send complex key combinations and shortcuts
- **Drag & Drop Operations**: Smooth drag operations with customizable timing and steps
- **JavaScript Execution**: Run custom JavaScript in browser contexts

## 🚀 Quick Start

### Installation

```bash
npm install firefox-mcp-server
npx playwright install firefox
```

### Basic Usage

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "firefox": {
      "command": "npx",
      "args": ["firefox-mcp-server"],
      "env": {}
    }
  }
}
```

### Example: Multi-User Testing

```javascript
// Launch browser and create isolated sessions
await browser_launch({headless: false})
await session_create({sessionId: "user1", url: "https://app.example.com"})
await session_create({sessionId: "user2", url: "https://app.example.com"})

// User 1 creates a game
await element_click({sessionId: "user1", selector: "button.create-game"})

// User 2 joins the game
await element_click({sessionId: "user2", selector: "button.join-game"})
await input_type({sessionId: "user2", selector: "input.game-code", text: "ABC123"})

// Monitor both sessions for real-time updates
await debug_websocket_messages({sessionId: "user1", limit: 10})
await debug_websocket_messages({sessionId: "user2", limit: 10})
```

## 🛠️ Complete Tool Reference

### Browser Management
- `browser_launch` - Launch Firefox with debugging capabilities
- `browser_close` - Close browser and clean up all resources

### Session Management
- `session_create` - Create isolated browser session with independent state
- `session_list` - List all active sessions with URLs and status
- `session_close` - Close specific session and free resources
- `session_set_active` - Set default session for subsequent operations

### Page Navigation
- `page_navigate` - Navigate to any URL
- `page_reload` - Refresh current page
- `history_back` / `history_forward` - Browser history navigation
- `url_get_current` - Get current page URL

### Element Interaction
- `element_click` - Click elements by selector or coordinates
- `element_drag` - Drag and drop with smooth animations
- `input_type` - Type text into input fields and text areas
- `keyboard_press` - Send keyboard events with modifier support
- `element_wait` - Wait for elements to appear or become visible

### Content Extraction
- `html_extract` - Extract HTML content from page or elements
- `text_extract` - Get visible text content
- `page_screenshot` - Capture screenshots with flexible options

### Advanced Capabilities
- `javascript_execute` - Run custom JavaScript in browser context

### Comprehensive Debugging Tools
- `debug_console_logs` - Monitor browser console output
- `debug_javascript_errors` - Track JavaScript errors and exceptions
- `debug_network_activity` - Monitor HTTP requests and responses
- `debug_websocket_messages` - Capture WebSocket traffic (LiveView-friendly)
- `debug_performance_metrics` - Get timing and memory usage data
- `debug_activity_all` - Combined feed of all debugging information
- `debug_monitoring_start` - Start comprehensive monitoring
- `debug_buffers_clear` - Clear accumulated debug data
- `debug_helpers_inject` - Inject custom debugging utilities

## 🎯 Use Cases

### Web Application Testing
- Automated UI testing with visual verification
- Form submission and validation testing
- Cross-browser compatibility verification
- Performance monitoring and optimization

### Multiplayer Game Development
- Multi-player session simulation
- Real-time state synchronization testing
- WebSocket message flow debugging
- Client-side prediction validation

### Phoenix LiveView Development
- LiveView event flow monitoring
- Real-time update verification
- WebSocket connection debugging
- Multi-user interaction testing

### E-commerce and SaaS Testing
- Multi-user checkout flows
- Session isolation for different user roles
- Real-time inventory updates
- Payment flow testing

## 📊 Debugging Capabilities

### Console Monitoring
```javascript
// Get recent console activity
await debug_console_logs({
  sessionId: "user1",
  types: ["error", "warn"],
  limit: 20,
  since: Date.now() - 60000  // Last minute
})
```

### Network Analysis
```javascript
// Monitor API calls and responses
await debug_network_activity({
  sessionId: "user1",
  filter: "xhr",
  limit: 10
})
```

### WebSocket Debugging
```javascript
// Perfect for Phoenix LiveView
await debug_websocket_messages({
  sessionId: "user1",
  limit: 5
})
```

### Performance Monitoring
```javascript
// Get comprehensive performance data
await debug_performance_metrics({
  sessionId: "user1"
})
```

## ⚙️ Troubleshooting

### Playwright Browser Not Found Error
If you encounter an error like:
```
browserType.launch: Executable doesn't exist at /home/luke/.cache/ms-playwright/firefox-1482/firefox/firefox
```

**Solution**: The Playwright browsers need to be installed. Run:
```bash
# From the firefox-mcp-server directory
./node_modules/.bin/playwright install firefox
```

This downloads the Firefox browser binary that Playwright uses for automation. This issue was resolved on 2025-08-03 when the MCP server failed to launch due to missing browser binaries.

## 🔧 Claude Code Configuration

### Local Configuration
Claude Code uses a project-specific configuration located at:
```
/home/luke/workbench/drabardi/.claude/settings.local.json
```

This configuration includes:
1. **Enabled MCP Servers**: The `firefox-control` server is enabled in `enabledMcpjsonServers`
2. **Permissions**: Various tool permissions are whitelisted including all Firefox MCP tools

### MCP Server Configuration
The Firefox MCP server is configured in Claude Code using:
```bash
# Check configured MCP servers
claude mcp list

# Output shows:
firefox-control: node /home/luke/workbench/firefox-mcp-server/index.js
tidewave: http://localhost:4000/tidewave/mcp (SSE)
```

The server runs from `/home/luke/workbench/firefox-mcp-server/` using the main `index.js` file (which internally uses the `index-multi-debug.js` implementation).

## 🔧 Configuration Options

### Session Creation
```javascript
await session_create({
  sessionId: "unique-id",
  url: "https://example.com",
  contextId: "optional-context",
  enableMonitoring: true  // Enable real-time debugging
})
```

### Screenshot Options
```javascript
await page_screenshot({
  sessionId: "user1",
  path: "screenshot.png",
  fullPage: true  // Capture entire page
})
```

### Drag Operations
```javascript
await element_drag({
  sessionId: "user1",
  selector: ".slider",
  offsetX: 100,
  duration: 1000,  // Smooth 1-second animation
  steps: 20        // 20 intermediate positions
})
```

## 📁 Project Structure

```
firefox-mcp-server/
├── index.js              # Main MCP server implementation
├── package.json           # Project configuration
├── README.md             # This file
├── CLAUDE.md             # Claude Code integration guide
├── examples/             # Usage examples
│   ├── demo-tibia-simple.js
│   ├── demo-tibia.js
│   └── demo-multiplayer.js
├── tests/                # Test files
│   └── test.js
└── docs/                 # Additional documentation
    ├── ENHANCEMENT_USAGE.md
    └── README-multi.md
```

## 🤝 Contributing

We welcome contributions! This project is designed to be:
- **LLM-Friendly**: Tool names and descriptions optimized for AI assistant discovery
- **Extensible**: Easy to add new browser automation capabilities
- **Well-Documented**: Comprehensive examples and documentation

## 📋 Requirements

- **Node.js**: 18.0.0 or higher
- **Firefox**: Automatically installed via Playwright
- **MCP Client**: Claude Code, Cline, or other MCP-compatible tools

## 🔒 Security

This server provides comprehensive browser automation capabilities. Use with trusted MCP clients only. The server can:
- Execute arbitrary JavaScript in browser contexts
- Monitor all network traffic and WebSocket messages
- Access page content and user interactions
- Take screenshots and access media devices

## 📄 License

MIT License - see LICENSE file for details.

---

**Perfect for AI assistants working with web applications, multiplayer games, and real-time debugging scenarios.**