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 session = BrowserSession::launch(LaunchOptions::default())?;
39//!
40//! // Navigate to a page
41//! session.navigate("https://example.com")?;
42//!
43//! // Extract DOM with indexed elements
44//! let dom = session.extract_dom()?;
45//! println!("Found {} interactive elements", dom.count_interactive());
46//! # Ok(())
47//! # }
48//! ```
49//!
50//! ### Using the Tool System
51//!
52//! ```rust,no_run
53//! use browser_use::{BrowserSession, LaunchOptions};
54//! use browser_use::tools::{ToolRegistry, ToolContext};
55//! use serde_json::json;
56//!
57//! # fn main() -> browser_use::Result<()> {
58//! let session = BrowserSession::launch(LaunchOptions::default())?;
59//! let registry = ToolRegistry::with_defaults();
60//! let mut context = ToolContext::new(&session);
61//!
62//! // Navigate using the tool system
63//! registry.execute("navigate", json!({"url": "https://example.com"}), &mut context)?;
64//!
65//! // Click an element by index
66//! registry.execute("click", json!({"index": 5}), &mut context)?;
67//! # Ok(())
68//! # }
69//! ```
70//!
71//! ### DOM Indexing for AI Agents
72//!
73//! The library automatically indexes interactive elements (buttons, links, inputs) with numeric IDs,
74//! making it easier for AI agents to target elements without complex CSS selectors:
75//!
76//! ```rust,no_run
77//! # use browser_use::{BrowserSession, LaunchOptions};
78//! # fn main() -> browser_use::Result<()> {
79//! # let session = BrowserSession::launch(LaunchOptions::default())?;
80//! # session.navigate("https://example.com")?;
81//! let dom = session.extract_dom()?;
82//!
83//! // Interactive elements are indexed and can be accessed via tools
84//! println!("Found {} interactive elements", dom.count_interactive());
85//! # Ok(())
86//! # }
87//! ```
88//!
89//! ## Module Overview
90//!
91//! - [`browser`]: Browser session management and configuration
92//! - [`dom`]: DOM extraction, element indexing, and tree representation
93//! - [`tools`]: Browser automation tools (navigate, click, input, extract, etc.)
94//! - [`error`]: Error types and result aliases
95//! - [`mcp`]: **Model Context Protocol server** (requires `mcp-handler` feature) - **Start here for AI integration**
96
97pub mod browser;
98pub mod dom;
99pub mod error;
100pub mod tools;
101
102#[cfg(feature = "mcp-handler")]
103pub mod mcp;
104
105pub use browser::{BrowserSession, ConnectionOptions, LaunchOptions};
106pub use dom::{BoundingBox, DomTree, ElementNode};
107pub use error::{BrowserError, Result};
108pub use tools::{Tool, ToolContext, ToolRegistry, ToolResult};
109
110#[cfg(feature = "mcp-handler")]
111pub use mcp::BrowserServer;
112#[cfg(feature = "mcp-handler")]
113pub use rmcp::ServiceExt;