LCBro

Low Cost Browser Remote Operations

The Cool Browser Automation MCP Server 🔥

⚡ Lightning Fast • 🎯 Zero Config • 🚀 Production Ready

LCBro is a powerful MCP server for browser automation with support for both Playwright and Chrome DevTools Protocol (CDP). It provides intelligent preprocessing, comprehensive logging, and remote browser management capabilities.

🎯 Cost Optimization Focus: This project is specifically designed to optimize LLM request costs and reduce context usage by intelligently preprocessing and cleaning data using local LLM models before sending to expensive main LLM APIs. This approach can reduce costs by up to 80% while improving result quality.

✨ Features

🎯 Browser Automation

• Real browser control with JavaScript execution

• Login flows, clicks, text input, form handling

• Screenshot capture and content extraction

• Session management with persistent contexts

🤖 Intelligent Preprocessing

• Auto-generates preprocessing prompts

• Local LLM integration (Ollama, JAN)

• Smart content analysis and optimization

• Cost-efficient data preparation

🔧 Multiple Engines

• Playwright: Full-featured automation

• CDP: Chrome DevTools Protocol support

• Remote browser connections

• Auto-detection and fallback

📊 Advanced Logging

• Comprehensive LLM interaction logs

• Performance metrics and token tracking

• Configurable log rotation and compression

• Debug and monitoring capabilities

🚀 Quick Start

Use with npx (Recommended - No Installation)

# Use directly without installation
npx lcbro

# With custom configuration
npx lcbro --config /path/to/config.yaml --port 3000

Global Installation

# Install globally via npm
npm install -g lcbro

# Start the server
lcbro

Local Development

# Clone and install
git clone https://github.com/lcbro/lcbro.git
cd lcbro
npm install
npm run build
npm start

Docker

# Run with Docker
docker run -p 3000:3000 lcbro:latest

💡 Usage Examples

Basic Browser Automation

# Navigate and extract content
npx lcbro navigate --url "https://example.com"
npx lcbro extract --format text

With Custom Configuration

# Enable CDP support
npx lcbro --cdp-enabled --port 3001

# Custom logging directory
npx lcbro --logs-dir "/custom/logs" --log-level debug

MCP Client Integration

{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro"]
    }
  }
}

📋 Installation

Prerequisites

• Node.js 18+

• npm or yarn

• Chrome/Chromium browser (for CDP support)

Global Installation (Recommended)

# Install globally
npm install -g lcbro

# Verify installation
lcbro --version

Local Development

# Clone repository
git clone https://github.com/lcbro/lcbro.git
cd lcbro

# Install dependencies
npm install

# Build project
npm run build

# Install Playwright browsers
npm run install:browsers

⚙️ Configuration

LCBro uses YAML configuration files with CLI overrides. Create a config/default.yaml file or use CLI options:

Basic Configuration

server:
  host: "localhost"
  port: 3000

browser:
  engine: playwright  # playwright | cdp
  headless: true
  defaultTimeoutMs: 30000
  maxContexts: 8
  storageDir: /data/profiles

llm:
  defaultModel: "ollama:llama3.1"
  maxOutputTokens: 2000
  temperature: 0
  host: "localhost"
  port: 11434
  janPort: 1337
  autoPreprocess: true

security:
  allowDomains: ["example.com", "gov.br"]
  blockPrivateNetworks: true

CLI Configuration Overrides

# Server settings
lcbro --port 3001 --host 0.0.0.0

# CDP browser support
lcbro --cdp-enabled --cdp-port 9222

# Remote CDP server
lcbro --remote-url https://cdp.example.com:9222 --remote-ssl-mode enabled

# Logging configuration
lcbro --log-level debug --logs-dir /tmp/lcbro-logs

🖥️ CLI Usage

LCBro provides a comprehensive command-line interface:

Main Commands

# Start the server
lcbro

# Show help
lcbro --help

# Show current configuration
lcbro config

# Launch browsers with CDP
lcbro browser:launch -b chrome -p 9222

# Manage log files
lcbro logs --command summary

# Test remote CDP connection
lcbro test:remote -u https://cdp.example.com:9222

🔧 Environment Variables

LCBro supports configuration via environment variables:

LLM Configuration

# Local LLMs (Recommended)

#### Ollama (free, no API keys required)
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3.1

# Configure LCBro
export LLM_HOST=localhost
export LLM_PORT=11434
export LLM_DEFAULT_MODEL=ollama:llama3.1

JAN AI (free, with optional API key)

# Configure LCBro for JAN AI
export LLM_HOST=localhost
export LLM_JAN_PORT=1337
export LLM_DEFAULT_MODEL=jan:llama-3.1-8b

External LLM APIs (Optional)

# OpenAI
export OPENAI_API_KEY=your_api_key_here

# Anthropic
export ANTHROPIC_API_KEY=your_api_key_here

CDP Browser Configuration

# Enable CDP support
export BROWSER_ENGINE=cdp

# CDP server settings
export CDP_HOST=localhost
export CDP_PORT=9222

# Remote CDP server
export CDP_REMOTE_URL=https://cdp.example.com:9222
export CDP_REMOTE_SSL_MODE=enabled
export CDP_REMOTE_API_KEY=your_api_key

## 🚀 Usage

### Starting the Server
```bash
# Start with default configuration
lcbro

# Start with specific port
lcbro --port 3001

# Start with CDP support
lcbro --cdp-enabled

# Start with custom config file
lcbro --config /path/to/config.yaml

MCP Client Integration

# Claude Desktop configuration
# Add to ~/.claude/claude_desktop_config.json:
{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro"]
    }
  }
}

# Cursor IDE configuration
# Add to ~/.cursor/mcp.json:
{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro"]
    }
  }
}

# With CDP support
{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro", "--cdp-enabled"]
    }
  }
}

# With custom configuration
{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro", "--config", "/path/to/config.yaml"]
    }
  }
}

## 🛠️ Advanced Features

### Intelligent Preprocessing
LCBro automatically cleans and optimizes data before sending to LLMs:

```bash
# Enable intelligent preprocessing
lcbro --auto-preprocess

# Configure preprocessing thresholds
lcbro --preprocessing-threshold-html 5000
lcbro --preprocessing-threshold-text 8000

CDP Browser Management

# Launch browsers with CDP
lcbro browser:launch -b chrome -p 9222 -n 3

# Connect to remote CDP server
lcbro --remote-url https://cdp.example.com:9222

# Test remote connection
lcbro test:remote -u https://cdp.example.com:9222

Log Management

# View log summary
lcbro logs --command summary

# Clean old logs
lcbro logs --command cleanup --age 30

# Compress log files
lcbro logs --command compress

📚 Documentation

• Intelligent Preprocessing - Automatic data cleaning and optimization

• LLM Logging Guide - Comprehensive logging system

• CDP Browser Support - Chrome DevTools Protocol integration

• Remote CDP Support - Remote browser management

• Logs Directory Configuration - Log management setup

🎯 MCP Tools Available

LCBro provides the following MCP tools:

Navigation Tools

• navigate_open - Open a new URL in a browser context

• navigate_goto - Navigate to a URL in an existing context

Interaction Tools

• interact_click - Click on elements by selector, text, or role

• interact_type - Type text into input fields

• interact_wait - Wait for conditions (selector, network idle, URL change)

Extraction Tools

• extract_content - Extract page content in various formats

• extract_table - Extract table data as JSON

• extract_attributes - Extract attributes from elements

• extract_screenshot - Take screenshots of pages or elements

Session Tools

• session_auth - Perform authentication sequences

• session_manage - Manage browser sessions and contexts

LLM Tools

• llm_transform - Transform data using LLM with custom instructions

• llm_analyze - Analyze content with LLM preprocessing

🏆 Project Status

✅ Production Ready - All features implemented and tested
✅ npm Package Ready - Can be installed globally via npm
✅ CLI Interface - Full command-line interface available
✅ Documentation - Comprehensive documentation provided
✅ Multi-language Support - English, Russian, Portuguese
✅ Zero Breaking Changes - All original functionality preserved
✅ Continuous Integration - Automated testing and deployment
✅ Docker Support - Multi-stage builds and container testing
✅ Security Scanning - Automated vulnerability detection

🚀 Quick Start

Option 1: Use with npx (Recommended - No Installation Required)

# Use directly without installation
npx lcbro --help

# Start server
npx lcbro

# With CDP support
npx lcbro --cdp-enabled

Option 2: Global Installation

# Install globally
npm install -g lcbro

# Verify installation
lcbro --version

# Start server
lcbro

Configure MCP Client

// Claude Desktop: ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro"]
    }
  }
}

// Cursor IDE: ~/.cursor/mcp.json
{
  "mcpServers": {
    "lcbro": {
      "command": "npx",
      "args": ["-y", "lcbro"]
    }
  }
}

📊 Performance & Specifications

• Package Size: 147.7 kB compressed, 759.7 kB unpacked

• Startup Time: < 2 seconds

• Memory Usage: < 100 MB typical

• Concurrent Sessions: Up to 8 browser contexts

• Supported Browsers: Chrome, Chromium, Edge (CDP), Playwright browsers

• Node.js: 18.x, 20.x, 22.x

• Operating Systems: Windows, macOS, Linux

🔧 CI/CD Pipeline Status

Automated Testing & Deployment 🚀

📊 Quality Metrics

• Test Coverage: >80% (Unit + E2E)

• Build Time: ~3-5 minutes

• Docker Build: Multi-stage with layer caching

• Security: CodeQL analysis + dependency scanning

📋 View all workflows → | 🚀 View pipeline runs →

🛠️ Development

Prerequisites

npm install
npm run install:browsers

Build & Test

# Build the project
npm run build

# Run tests
npm test

# Run E2E tests
npm run test:e2e

# Run CI pipeline locally
make ci

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 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

📞 Support & Community

• 🐛 Bug Reports: GitHub Issues

• 💬 Discussions: GitHub Discussions

• 📚 Documentation: Full Documentation

• 💡 Examples: Usage Examples

• 🔧 CI/CD Workflows: Workflows Documentation

• 🚀 Pipeline Status: GitHub Actions

• 🛡️ Security Reports: Security Tab

• ⭐ Star Us: Help us grow by starring the repository!

🙏 Acknowledgments

• Playwright - Browser automation framework

• Chrome DevTools Protocol - Remote browser debugging

• MCP SDK - Model Context Protocol framework

• Claude Desktop - MCP client integration

• Cursor IDE - Development environment

Made with ❤️ by the LCBro Team

LCBro - Low Cost Browser Remote Operations
Version: 1.0.10 • Status: ✅ Production Ready • License: MIT

⬆ Back to Top