parruda/headless-browser-tool

Headless Browser Tool

A headless browser control tool that provides an MCP (Model Context Protocol) server with tools to control a headless browser using Capybara and Selenium. Features multi-session support, session persistence, and both HTTP and stdio communication modes.

Features

• Headless Chrome browser automation - Full browser control via Selenium WebDriver
• MCP server with 40+ browser control tools - Comprehensive API for browser interactions
• Multi-session support - Isolated browser sessions for each client
• Session persistence - Sessions survive server restarts with cookies and state preservation
• Two server modes - HTTP server mode and stdio mode for different integration patterns
• Smart screenshot tools - With annotations, highlighting, and visual diff capabilities
• AI-assisted tools - Auto-narration and intelligent page analysis
• Comprehensive logging - Separate log files for stdio mode to avoid protocol interference
• Structured responses - All tools return rich, structured data instead of simple strings
• Smart element selectors - Tools returning multiple elements include selectors for each

Installation

Add this line to your application's Gemfile:

gem 'headless_browser_tool'

And then execute:

bundle install

Or install it yourself as:

gem install headless_browser_tool

Prerequisites

You need to have Chrome/Chromium browser installed on your system. The gem will use Chrome in headless mode by default.

Usage

Command Line Interface

The hbt command provides three main commands:

hbt start - Start HTTP Server Mode

Starts the MCP server as an HTTP server with SSE (Server-Sent Events) support:

hbt start [OPTIONS]

Options:

• --port PORT - Port for the MCP server (default: 4567)
• --headless / --no-headless - Run browser in headless mode (default: true)
• --single-session - Use single shared browser session instead of multi-session mode
• --session-id SESSION_ID - Enable session persistence for single session mode (requires --single-session)
• --show-headers - Show HTTP request headers for debugging session issues

Examples:

# Start with default settings (multi-session, headless, port 4567)
hbt start

# Start in non-headless mode for debugging
hbt start --no-headless

# Start in single session mode (legacy compatibility)
hbt start --single-session

# Start in single session mode with persistence
hbt start --single-session --session-id my-app-session

# Start with request header logging
hbt start --show-headers

hbt stdio - Start Stdio Server Mode

Starts the MCP server in stdio mode for direct integration with tools that spawn subprocesses:

hbt stdio [OPTIONS]

Options:

• --headless / --no-headless - Run browser in headless mode (default: true)

Notes:

• Always runs in single-session mode
• Logs to .hbt/logs/PID.log instead of stdout to avoid interfering with MCP protocol
• Ideal for editor integrations and tools that communicate via stdin/stdout
• Supports optional session persistence via HBT_SESSION_ID environment variable

Session Persistence in Stdio Mode:

You can enable session persistence by setting the HBT_SESSION_ID environment variable:

# First run - creates and saves session
HBT_SESSION_ID=my-editor-session hbt stdio

# Later run - restores previous session state
HBT_SESSION_ID=my-editor-session hbt stdio

When HBT_SESSION_ID is set:

• Session state is saved to .hbt/sessions/{session_id}.json on exit
• On startup, if the session file exists, it restores:
  • Current URL
  • Cookies
  • localStorage
  • sessionStorage
  • Window size

This is useful for editor integrations that want to maintain browser state across multiple tool invocations.

Examples:

# Start in stdio mode (headless by default, no persistence)
hbt stdio

# Start with session persistence
HBT_SESSION_ID=vscode-session hbt stdio

# Start in stdio mode with visible browser
hbt stdio --no-headless

hbt version - Display Version

Shows the current version of HeadlessBrowserTool:

hbt version

Session Management

Multi-Session Mode (Default for HTTP Server)

In multi-session mode, each client connection gets its own isolated browser session with:

• Separate cookies and localStorage - Complete isolation between sessions
• Independent navigation history - Each session maintains its own browser state
• Session persistence - Sessions are saved to .hbt/sessions/ and restored on restart
• Automatic cleanup - Idle sessions are closed after 30 minutes
• LRU eviction - When at capacity (10 sessions), least recently used sessions are closed

Session Identification in Multi-Session Mode:

For HTTP server mode, sessions require an X-Session-ID header:

# Connect with session ID "alice"
curl -H "X-Session-ID: alice" -H "Accept: text/event-stream" http://localhost:4567/

# Different session ID gets different browser
curl -H "X-Session-ID: bob" -H "Accept: text/event-stream" http://localhost:4567/

# Without X-Session-ID header, connection is rejected
curl -H "Accept: text/event-stream" http://localhost:4567/
# Returns: 400 Bad Request - X-Session-ID header is required

Session ID Requirements:

• Must be provided via X-Session-ID header
• Can only contain alphanumeric characters, underscores, and hyphens
• Maximum length: 64 characters
• Invalid formats are rejected with 400 error

Single Session Mode

Use --single-session flag for legacy mode where all clients share one browser:

hbt start --single-session

Session Persistence in Single Session Mode:

You can enable session persistence with the --session-id flag:

# First run - creates and saves session
hbt start --single-session --session-id my-app

# Server restart - restores previous session
hbt start --single-session --session-id my-app

When --session-id is provided:

• Session state is saved to .hbt/sessions/{session_id}.json on shutdown
• On startup, if the session file exists, it restores browser state
• All clients share this single persistent session
• Compatible with stdio mode session files

This is useful for:

• Development servers that need to maintain login state
• Testing environments where you want consistent browser state
• Applications that don't need multi-user isolation

Note: The --session-id flag can only be used with --single-session. In multi-session mode, session IDs are provided by clients via headers.

Session Management Endpoints

View active sessions:

curl http://localhost:4567/sessions | jq

Response:

{
  "active_sessions": ["alice", "bob"],
  "session_count": 2,
  "session_data": {
    "alice": {
      "created_at": "2024-01-20T10:00:00Z",
      "last_activity": "2024-01-20T10:05:00Z",
      "idle_time": 300.5
    }
  }
}

Close a specific session:

curl -X DELETE http://localhost:4567/sessions/alice

Directory Structure

HeadlessBrowserTool creates a .hbt/ directory with:

.hbt/
├── .gitignore      # Contains "*" to ignore all contents
├── screenshots/    # Screenshot storage
├── sessions/       # Session persistence files
└── logs/          # Log files (stdio mode only)
    └── PID.log    # Process-specific log file

MCP API

The server implements the Model Context Protocol (MCP) and responds to JSON-RPC requests.

Using with MCP Clients

For HTTP mode with proper MCP clients:

# Start server
hbt start

# MCP client should:
# 1. Connect with X-Session-ID header
# 2. Use SSE endpoint for streaming: http://localhost:4567/mcp/sse
# 3. Send commands via JSON-RPC

For stdio mode:

# MCP client spawns the process directly
hbt stdio
# Communication happens via stdin/stdout

Available Browser Tools

All tools are available through the MCP protocol. Here's a complete reference:

Navigation Tools

Element Interaction Tools

Element Finding Tools

Form Interaction Tools

Page Information Tools

Search Tools

JavaScript Execution Tools

Screenshot and Capture Tools

Window Management Tools

Session Management Tools

Smart Tools (experimental)

Tool Response Structure

All tools now return structured data instead of simple strings. This makes it easier to:

• Extract specific information from responses
• Check operation success/failure
• Access element properties and metadata
• Navigate to specific elements using returned selectors

Example responses:

// visit tool response
{
  "url": "https://example.com",
  "current_url": "https://example.com/",
  "title": "Example Domain",
  "status": "success"
}

// find_all tool response with selectors
{
  "selector": ".item",
  "count": 3,
  "elements": [
    {
      "index": 0,
      "selector": ".item:nth-of-type(1)",
      "tag_name": "div",
      "text": "Item 1",
      "visible": true,
      "attributes": {"class": "item active"}
    },
    // ... more elements
  ]
}

// select tool response with option selectors
{
  "dropdown_selector": "#country",
  "selected_value": "US",
  "selected_text": "United States",
  "options": [
    {
      "selector": "#country option:nth-of-type(1)",
      "value": "US",
      "text": "United States",
      "selected": true
    },
    // ... more options
  ],
  "status": "selected"
}

Example Tool Calls

Here are examples using curl with the HTTP server:

# Navigate to a URL
curl -X POST http://localhost:4567/ \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: alice" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", 
       "params": {"name": "visit", "arguments": {"url": "https://example.com"}}}'

# Take an annotated screenshot
curl -X POST http://localhost:4567/ \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: alice" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {"name": "screenshot", 
                  "arguments": {"filename": "example", 
                              "highlight_selectors": [".error", ".warning"],
                              "annotate": true,
                              "full_page": true}}}'

# Search page content with highlighting
curl -X POST http://localhost:4567/ \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: alice" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
       "params": {"name": "search_page",
                  "arguments": {"query": "error|warning",
                              "regex": true,
                              "highlight": true}}}'

Environment Variables

• HBT_SINGLE_SESSION=true - Force single session mode in HTTP server
• HBT_SHOW_HEADERS=true - Enable request header logging in HTTP server
• HBT_SESSION_ID=<session_name> - Enable session persistence in stdio mode

Logging

• HTTP mode: Logs to stdout
• Stdio mode: Logs to .hbt/logs/PID.log to avoid interfering with MCP protocol

Tool calls are logged with format:

INFO -- HBT: CALL: ToolName [] {args} -> result
ERROR -- HBT: ERROR: ToolName [] {args} -> error_message

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt.

To install this gem onto your local machine, run bundle exec rake install.

Running Tests and Linting

# Run tests
rake test

# Run linter
rake rubocop

# Run linter with auto-fix
rake rubocop -A

# Run both tests and linter (default task)
rake

Recent Improvements

Version 0.1.0

• Structured tool responses - All tools now return rich JSON objects instead of simple strings
• Element selectors in arrays - Tools returning multiple elements include unique selectors for each
• Session persistence - Both stdio and single-session HTTP modes support persistent sessions
• Strict session management - Multi-session mode requires X-Session-ID header (no auto-creation)
• Improved logging - Fixed stdio mode logging to properly write to .hbt/logs/PID.log
• DRY refactoring - Extracted common functionality into SessionPersistence and DirectorySetup modules
• Better error handling - Tools return structured error information
• Enhanced tool responses:
  • Navigation tools return before/after URLs and navigation status
  • Form tools return element state before/after interaction
  • Window tools return comprehensive window state information
  • Screenshot tool returns file metadata
  • All element-finding tools return complete element information

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/parruda/headless_browser_tool.