browser_use/lib.rs
1//! # browser-use
2//!
3//! A Rust library for browser automation via Chrome DevTools Protocol (CDP), designed for AI agent integration.
4//!
5//! ## Features
6//!
7//! - **MCP Server**: Model Context Protocol server for AI-driven browser automation
8//! - **Browser Session Management**: Launch or connect to Chrome/Chromium instances
9//! - **Tool System**: High-level browser operations (navigate, click, input, extract, screenshot, etc.)
10//! - **DOM Extraction**: Extract page structure with indexed interactive elements for AI-friendly targeting
11//!
12//! ## MCP Server
13//!
14//! The recommended way to use this library is via the Model Context Protocol (MCP) server,
15//! which exposes browser automation tools to AI agents like Claude:
16//!
17//! ### Running the MCP Server
18//!
19//! ```bash
20//! # Run headless browser
21//! cargo run --bin mcp-server
22//!
23//! # Run with visible browser (useful for debugging)
24//! cargo run --bin mcp-server -- --headed
25//! ```
26//!
27//! ## Library Usage (Advanced)
28//!
29//! For direct integration in Rust applications:
30//!
31//! ### Basic Browser Automation
32//!
33//! ```rust,no_run
34//! use browser_use::{BrowserSession, LaunchOptions};
35//!
36//! # fn main() -> browser_use::Result<()> {
37//! // Launch a browser
38//! let mut session = BrowserSession::launch(LaunchOptions::default())?;
39//!
40//! // Navigate to a page
41//! session.navigate("https://example.com", None)?;
42//!
43//! // Extract DOM with indexed elements
44//! let dom = session.extract_dom()?;
45//! println!("Found {} interactive elements", dom.selector_map().len());
46//! # Ok(())
47//! # }
48//! ```
49//!
50//! ### Using the Tool System
51//!
52//! ```rust,no_run
53//! use browser_use::{BrowserSession, LaunchOptions, ToolRegistry, ToolContext};
54//! use serde_json::json;
55//!
56//! # fn main() -> browser_use::Result<()> {
57//! let mut session = BrowserSession::launch(LaunchOptions::default())?;
58//! let registry = ToolRegistry::new();
59//! let mut context = ToolContext::new(&mut session);
60//!
61//! // Navigate using the tool system
62//! registry.execute_tool("navigate", json!({"url": "https://example.com"}), &mut context)?;
63//!
64//! // Click an element by index
65//! registry.execute_tool("click", json!({"index": 5}), &mut context)?;
66//! # Ok(())
67//! # }
68//! ```
69//!
70//! ### DOM Indexing for AI Agents
71//!
72//! The library automatically indexes interactive elements (buttons, links, inputs) with numeric IDs,
73//! making it easier for AI agents to target elements without complex CSS selectors:
74//!
75//! ```rust,no_run
76//! # use browser_use::{BrowserSession, LaunchOptions};
77//! # fn main() -> browser_use::Result<()> {
78//! # let mut session = BrowserSession::launch(LaunchOptions::default())?;
79//! # session.navigate("https://example.com", None)?;
80//! let dom = session.extract_dom()?;
81//!
82//! // Access elements by numeric index
83//! if let Some(selector) = dom.selector_map().get_selector(5) {
84//! println!("Element 5 selector: {}", selector);
85//! }
86//! # Ok(())
87//! # }
88//! ```
89//!
90//! ## Module Overview
91//!
92//! - [`browser`]: Browser session management and configuration
93//! - [`dom`]: DOM extraction, element indexing, and tree representation
94//! - [`tools`]: Browser automation tools (navigate, click, input, extract, etc.)
95//! - [`error`]: Error types and result aliases
96//! - [`mcp`]: **Model Context Protocol server** (requires `mcp-server` feature) - **Start here for AI integration**
97
98pub mod browser;
99pub mod dom;
100pub mod error;
101pub mod tools;
102
103#[cfg(feature = "mcp-server")]
104pub mod mcp;
105
106pub use browser::{BrowserSession, ConnectionOptions, LaunchOptions};
107pub use dom::{BoundingBox, DomTree, ElementNode, ElementSelector, SelectorMap};
108pub use error::{BrowserError, Result};
109pub use tools::{Tool, ToolContext, ToolRegistry, ToolResult};
110
111#[cfg(feature = "mcp-server")]
112pub use mcp::BrowserServer;