mcp-server-webdriver: Instructions file for Codex

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Unit tests only (no browser required — used by Debian build):
pytest tests/ -m "not integration"

# All tests including browser integration (requires geckodriver on PATH):
pytest tests/

# Run a single test class or function:
pytest tests/test_server.py::TestNormaliseUrl
pytest tests/test_server.py::TestBrowserIntegration::test_navigate_and_title

# Install dev dependencies:
pip install -e ".[dev]"

# Run the server (normally launched by MCP client, not by hand):
mcp-server-webdriver --help

Installation (VitexSoftware APT repository)

sudo curl -fsSL http://repo.vitexsoftware.com/KEY.gpg -o /usr/share/keyrings/vitexsoftware-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/vitexsoftware-archive-keyring.gpg] http://repo.vitexsoftware.com trixie main" \
  | sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo apt update && sudo apt install python3-mcp-server-webdriver

Architecture

The entire server is a single file: server.py. There are no submodules.

Core components

BrowserState dataclass — owns the Firefox session and all captured DevTools data. It holds:

• The webdriver.Firefox driver instance
• Three in-memory buffers (protected by threading.Lock): _console, _js_errors, _network
• A _pending dict tracking in-flight network requests by request ID, used to calculate duration_ms when a response arrives
• BiDi handler IDs for cleanup on re-attach

BiDi event capture — _attach_bidi() registers four async callbacks on the Selenium BiDi API (driver.script for console/JS errors, driver.network for request/response/fail events). Handlers write to the shared buffers under the lock. Network timing is derived from (response.timestamp - request.timestamp) * 1000. If the Selenium version doesn't support network BiDi, the network handlers are silently skipped.

FastMCP server — mcp = FastMCP(...) at module level. Tools are decorated with @mcp.tool(). State is passed to every tool via Context using the lifespan pattern: ctx.lifespan_context["browser"] returns the BrowserState. The helper _st(ctx) wraps this lookup.