🚀 LCBro

LCBro is a powerful MCP server for browser automation, supporting both Playwright and Chrome DevTools Protocol (CDP). It offers intelligent preprocessing, comprehensive logging, and remote browser management capabilities, aiming to optimize LLM request costs.

✨ Features

🚀 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"]
    }
  }
}

📦 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

💻 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"]
    }
  }
}

⚙️ 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

# 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:

# 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

📊 Performance & Specifications

🔧 CI/CD Pipeline Status

Automated Testing & Deployment 🚀

Pipeline	Status	Description
CI/CD		Main build, test, and deployment pipeline
Docker		Container builds and multi-platform testing
Release		Automated release and npm publishing
Nightly		Extended tests and performance benchmarks

📊 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