AlyBrowser

Lightweight browser SDK for AI agents. Connects via a Chrome Extension bridge that bypasses bot detection.

How it works

AI Agent  →  MCP Server  →  WebSocket  →  Chrome Extension  →  Content Script  →  Web Page

• No CDP — Uses Chrome Extension bridge instead of DevTools Protocol, avoiding bot detection
• Accessibility tree snapshots — Pages are read through @eN ref IDs for interactive elements
• Multi-session — Isolated Chrome instances with separate profiles for multi-account scenarios
• Site Knowledge — Records success/fail experiences per site, auto-attached on revisit
• Crash Recovery — Auto-restarts Chrome on crash, preserves session state (cookies, localStorage)
• Security — JWT HS256 WS auth, AES-256-GCM encrypted site knowledge, password field masking
• Minimal deps — Only 2 runtime dependencies (@modelcontextprotocol/sdk, ws)

Install

npm install aly-browser

Quick Start

As MCP Server (Claude Code / Cursor / etc.)

Add to your .mcp.json:

{
  "mcpServers": {
    "aly-browser": {
      "command": "npx",
      "args": ["aly-browser-mcp"]
    }
  }
}

As Library

import { ExtensionBridge } from 'aly-browser';

const bridge = new ExtensionBridge('my-session');
await bridge.launch({ url: 'https://example.com' });

const snapshot = await bridge.snapshot();
console.log(snapshot); // Accessibility tree with @eN refs

await bridge.click('@e1');
await bridge.type('@e2', 'Hello world');
await bridge.close();

Multi-Session Support

Each session gets an isolated Chrome instance with separate cookies/profile:

// Two Instagram accounts simultaneously
const sessionA = new ExtensionBridge('insta-a');
const sessionB = new ExtensionBridge('insta-b');

await sessionA.launch({ url: 'https://instagram.com' });
await sessionB.launch({ url: 'https://instagram.com' });
// Each has independent login state

MCP Tools (133)

Browser Control (5)

Tool	Description
browser_launch	Launch Chrome with optional URL. Each sessionId gets an isolated instance.
browser_navigate	Navigate to a URL. Auto-attaches site knowledge on first visit.
browser_back	Navigate back in browser history.
browser_forward	Navigate forward in browser history.
browser_close	Close a browser session.

Site Knowledge (2)

Tool	Description
browser_learn	Record success/fail experience for a site. Auto-shown on future visits.
browser_get_knowledge	Retrieve recorded knowledge for a URL.

Page Reading (4)

Tool	Description
browser_snapshot	Capture accessibility tree with @eN ref IDs. Supports frameId for iframes.
browser_snapshot_diff	Compare with previous snapshot, return only changes. 60-90% less tokens.
browser_html	Get full page HTML. Supports frameId.
browser_eval	Execute JavaScript in page context.

Interaction (8)

Tool	Description
browser_click	Click element by @eN ref. Returns updated snapshot.
browser_type	Type text into input. Supports {Enter}, {Tab}, {Escape}, etc.
browser_select	Select option in <select> element.
browser_hover	Hover over element.
browser_scroll	Scroll by pixel amounts (x, y).
browser_wait	Wait for CSS selector to appear/disappear (MutationObserver).
browser_wait_for_stable	Wait until DOM stops changing (500ms quiet period).
browser_sleep	Wait 1 second. Prefer browser_wait_for_stable.

Advanced Interaction (9)

Tool	Description
browser_double_click	Double-click element by @eN ref.
browser_right_click	Right-click (context menu) by CSS selector.
browser_drag_drop	Drag and drop between two elements (HTML5 DnD events).
browser_click_all	Click all elements matching a CSS selector (batch).
browser_focus	Focus element by CSS selector.
browser_blur	Remove focus from current element.
browser_press_key	Dispatch keyboard event on focused element.
browser_upload	Upload local file to input[type=file] via DataTransfer injection.
browser_shadow_dom_pierce	Query/click/type inside Shadow DOM with piercing selector (>>> syntax).

Navigation & Scrolling (7)

Tool	Description
browser_reload	Reload page. Optionally bypass cache.
browser_scroll_to_bottom	Scroll to page bottom (lazy content loading).
browser_scroll_to_top	Scroll to page top.
browser_scroll_to_element	Scroll to element by CSS selector (smooth).
browser_infinite_scroll	Auto-scroll to load all infinite scroll content.
browser_wait_for_url	Wait until URL matches pattern (OAuth redirects, SPA nav).
browser_wait_for_text	Wait until text appears/disappears on page.

Tabs (4)

Tool	Description
browser_tab_list	List all open tabs.
browser_tab_new	Create new tab. Returns tabId for parallel work.
browser_tab_close	Close a tab by ID.
browser_tab_switch	Switch active tab focus.

Frames (1)

Tool	Description
browser_frame_list	List all frames (main + iframes) with frameId and URL.

Page Info (6)

Tool	Description
browser_get_url	Get current page URL.
browser_get_title	Get current page title.
browser_page_info	Get page info: URL, title, domain, viewport, scroll position.
browser_element_count	Get total DOM element count (complexity check).
browser_element_info	Detailed element info: bounding box, styles, attributes, text.
browser_text_content	Extract all visible text organized by sections.

Data Extraction (7)

Tool	Description
browser_table_extract	Extract HTML table data as structured JSON.
browser_link_extract	Extract all links with href, text, internal/external flag.
browser_image_list	List all images with src, alt, dimensions, loading status.
browser_json_extract	Extract JSON-LD, microdata, meta tags as structured data.
browser_find_text	Search text on page with context and match count.
browser_media_list	List video/audio/embed elements with metadata.
browser_count_elements	Count elements matching CSS selectors.

DOM Manipulation (5)

Tool	Description
browser_element_remove	Remove elements by CSS selector (ads, banners, etc).
browser_attribute_set	Set/remove HTML attributes on elements.
browser_highlight	Highlight elements with colored border/overlay.
browser_style_override	Inject/remove custom CSS styles.
browser_popup_blocker	Detect and remove popups, modals, cookie banners.

Form Automation (2)

Tool	Description
browser_form_fill	Auto-fill form fields by semantic type (email, name, phone, etc).
browser_form_detect	Detect all form fields with type, name, autocomplete info.

Cookies (5)

Tool	Description
browser_cookie_get	Get cookies for a URL.
browser_cookie_set	Set a cookie with full options (domain, path, secure, httpOnly, expiration).
browser_cookie_delete	Delete a cookie by URL and name.
browser_cookie_export	Export all cookies for a domain as JSON profile.
browser_cookie_import	Import cookies from exported JSON profile.

Storage (3)

Tool	Description
browser_storage_get	Get data from extension local storage.
browser_storage_set	Set data in extension local storage.
browser_local_storage	Read/write/clear page localStorage (get, set, delete, clear, list).

Performance & Audit (7)

Tool	Description
browser_perf_metrics	Page load timing, DOM size, resource count, memory usage.
browser_web_vitals	Core Web Vitals: LCP, CLS, FCP, TTFB with pass/fail.
browser_js_coverage	JS analysis: script count, size, render-blocking, third-party.
browser_css_coverage	CSS analysis: stylesheets, rules, unused rule estimates.
browser_page_size	Total page weight: HTML, CSS, JS, images, fonts.
browser_resource_hints	Analyze preload/prefetch/preconnect hints, suggest missing ones.
browser_page_audit	Comprehensive audit: perf + a11y + SEO + weight (score 0-100).

SEO & Social (4)

Tool	Description
browser_meta_seo	SEO audit: title, description, OG tags, structured data, headings.
browser_open_graph_preview	Preview social media cards (Facebook, Twitter, LinkedIn).
browser_broken_links	Check all page links for broken URLs.
browser_mixed_content_check	Detect HTTP resources on HTTPS pages.

Accessibility (1)

Tool	Description
browser_a11y_audit	WCAG audit: alt text, labels, heading hierarchy, ARIA roles, contrast.

Debugging (7)

Tool	Description
browser_console_log	Read console messages (log, warn, error, info).
browser_network_log	Capture network requests via Performance API.
browser_dom_observe	Start/read/stop MutationObserver for DOM changes.
browser_event_listener_list	List event listeners on page elements.
browser_xpath_query	Query elements using XPath expressions.
browser_websocket_monitor	Monitor WebSocket connections: capture send/recv messages.
browser_fetch_intercept	Intercept fetch() API calls: method, URL, status, bodies.

Testing & Emulation (7)

Tool	Description
browser_device_emulate	Emulate device: viewport, UA, touch, DPR (presets: iPhone, Pixel, iPad).
browser_viewport_test	Test responsiveness across viewports (mobile, tablet, desktop, wide).
browser_dark_mode	Detect or toggle dark/light mode preference.
browser_timezone_set	Override timezone for time-sensitive UI testing.
browser_user_agent_set	Override user agent (presets: mobile, firefox, googlebot).
browser_geolocation_mock	Mock geolocation (presets: Tokyo, NYC, London, Seoul, Paris).
browser_network_throttle	Simulate slow network (presets: 3G, 4G, slow, offline).

Design Analysis (4)

Tool	Description
browser_color_picker	Extract page color palette sorted by frequency.
browser_font_list	Analyze fonts: families, sizes, weights, web vs system.
browser_selector_generator	Generate stable CSS/XPath selectors for elements.
browser_scroll_map	Content density analysis by scroll position.

Print & Export (2)

Tool	Description
browser_print_preview	Print preview: page count, paper size, margins, print CSS.
browser_page_to_pdf_data	Extract clean printable text (strips nav, ads).

Dialog & Security (3)

Tool	Description
browser_dialog_handler	Auto-handle JS dialogs (alert, confirm, prompt).
browser_captcha_detect	Detect CAPTCHA: reCAPTCHA, hCaptcha, Cloudflare Turnstile.
browser_permissions_check	Check browser permission states (geo, camera, mic, etc).

Browser APIs (5)

Tool	Description
browser_alarm_create	Create scheduled alarm with delay or period.
browser_alarm_list	List active alarms.
browser_alarm_clear	Clear alarm(s) by name.
browser_alarm_events	Get fired alarm events since last poll.
browser_notify	Show a Chrome notification.

PWA & Service Worker (2)

Tool	Description
browser_indexeddb_list	List IndexedDB databases and object stores.
browser_service_worker_info	Service Worker status: active/installing/waiting, scope, caches.

Downloads & History (2)

Tool	Description
browser_download	Download a file from a URL.
browser_history_search	Search browser history.

Bookmarks (3)

Tool	Description
browser_bookmark_list	List or search bookmarks.
browser_bookmark_create	Create a bookmark.
browser_bookmark_delete	Delete a bookmark.

Clipboard (2)

Tool	Description
browser_clipboard_read	Read clipboard text.
browser_clipboard_write	Write text to clipboard.

Sessions (7)

Tool	Description
browser_session_list	List active sessions with port and connection status.
browser_session_close_all	Close all browser sessions.
browser_session_clone	Clone session (copies cookies for parallel work).
browser_session_broadcast	Execute an action across multiple sessions in parallel (navigate, click, type, eval, scroll, snapshot).
browser_batch_snapshot	Capture snapshots from multiple sessions simultaneously.
browser_screenshot_diff	Compare screenshots between two sessions for visual regression detection.
browser_top_sites	Get most visited sites.

Page Watch (4)

Tool	Description
browser_watch_start	Start monitoring a page for changes. Captures initial snapshot for comparison.
browser_watch_check	Check a watched page for changes since last check. Returns diff summary.
browser_watch_list	List all active page watches with status.
browser_watch_stop	Stop monitoring a page and remove the watch.

Screen Tools (5)

Tool	Description
screen_capture	Capture screenshot. Supports window title targeting.
screen_click	Click at screen coordinates. Supports double-click.
screen_type	Type text at current cursor position.
screen_key	Press key with optional modifiers.
screen_scroll	Scroll at current cursor position.

Security

WS Token Authentication

Per-session JWT HS256 token is generated on launch and validated on every WS connection.

• Chrome for Testing — Token is auto-injected into the extension. Fully authenticated.
• Pre-installed extension — Token-less connections accepted with warning by default. Set ALY_REQUIRE_AUTH=1 to enforce token auth for all connections.
• Token storage — Written to ~/.aly-browser/sessions/<id>/token with 0600 permissions. Cleaned up on close().

Site Knowledge Security

• Sensitive data filtering — Passwords, tokens, API keys, JWTs, and other secrets are automatically redacted before storage via pattern matching.
• Encrypted storage — AES-256-GCM encryption with per-installation key (0600 permissions). Transparent migration from plaintext.

Password Protection

Password input field values are masked with •••••••• in accessibility tree snapshots. Actual passwords are never exposed to AI agents.

Extension Bridge Security Model

• Content Script isolation — Runs in Chrome's isolated world, invisible to page JavaScript.
• No CDP exposure — No DevTools port (9222) is opened. No chrome.debugger API is used.
• Sideloading only — Requires --load-extension flag. Not publishable to Chrome Web Store due to broad permissions.

Site Knowledge & Prompt Injection

• Risk — A malicious site could craft text designed to be stored as site knowledge.
• Mitigations — 200 entries/domain cap, 1000 chars/field, entries are advisory only (not executable), sensitive data auto-redacted.

Crash Recovery

Chrome crashes are auto-detected and recovered:

• Non-zero exit code or unexpected WS disconnect triggers recovery
• Exponential backoff: 1s → 2s → 4s (max 3 attempts)
• Profile directory is reused — cookies, localStorage, IndexedDB are preserved
• close() sets an intentional flag to skip recovery

Environment Variables

Variable	Default	Description
ALY_REQUIRE_AUTH	(unset)	Set to 1 to reject WS connections without a valid JWT token

AI Framework Integration

AlyBrowser is MCP-native and works with any MCP-compatible AI framework.

LangChain

# pip install langchain-mcp-adapters
from langchain_mcp_adapters import MCPToolkit

toolkit = MCPToolkit(server_command="npx", server_args=["aly-browser-mcp"])
tools = toolkit.get_tools()
# Use tools in your LangChain agent

CrewAI

# crewai.yaml
tools:
  - type: mcp
    command: npx
    args: ["aly-browser-mcp"]

Claude Code

{
  "mcpServers": {
    "aly-browser": {
      "command": "npx",
      "args": ["aly-browser-mcp"]
    }
  }
}

Direct SDK Usage

import { ExtensionBridge } from 'aly-browser';

const browser = new ExtensionBridge('session-1');
await browser.launch({ url: 'https://example.com' });

// Full API: snapshot, click, type, evaluate, upload, cookies...
const tree = await browser.snapshot();
await browser.click('@e1');
await browser.close();

Requirements

• Node.js >= 18
• Chrome or Chromium installed
• macOS, Linux (screen tools are macOS-only)

Changelog

See CHANGELOG.md for version history.

License

MIT