athena-browser-mcp 2.0.4 → 2.1.0

package/README.md

@@ -1,263 +1,142 @@
 # Athena Browser MCP
 
-[![CI](https://github.com/lespaceman/athena-browser-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lespaceman/athena-browser-mcp/actions/workflows/ci.yml)
-[![npm version](https://badge.fury.io/js/athena-browser-mcp.svg)](https://www.npmjs.com/package/athena-browser-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+An MCP server for browser automation that exposes semantic, token-efficient page representations optimized for LLM agents.
 
-MCP server for AI browser automation - 18 tools with semantic element targeting.
+---
 
-## Design Philosophy
+## Motivation
 
-1. **Semantic element IDs** - Stable `eid` references survive DOM mutations
-2. **XML state responses** - Structured page state with layers, actionables, and diffs
-3. **Multi-frame support** - Extract content from iframes (cookie consent, widgets)
-4. **Automatic retry** - Stale element recovery with fresh snapshot
+LLM-based agents operate under strict context window and token constraints.
+However, most browser automation tools expose entire DOMs or full accessibility trees to the model.
 
-## Architecture
+This leads to:
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         AI Agent                                 │
-│  ┌────────────────────────────────────────────────────────────┐ │
-│  │ System Prompt: XML state (layers, actionables, atoms)      │ │
-│  └────────────────────────────────────────────────────────────┘ │
-└───────────────────────────┬─────────────────────────────────────┘
-                            │ MCP Protocol (stdio)
-┌───────────────────────────▼─────────────────────────────────────┐
-│  SESSION: launch_browser, connect_browser, close_page,          │
-│           close_session                                          │
-│  NAVIGATION: navigate, go_back, go_forward, reload               │
-│  OBSERVATION: capture_snapshot, find_elements, get_node_details  │
-│  INTERACTION: click, type, press, select, hover,                 │
-│               scroll_element_into_view, scroll_page              │
-└───────────────────────────┬─────────────────────────────────────┘
-                            │ Playwright + CDP
-┌───────────────────────────▼─────────────────────────────────────┐
-│                     Chromium Browser                             │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Tools
-
-### Session
-
-| Tool              | Purpose                   | Input               |
-| ----------------- | ------------------------- | ------------------- |
-| `launch_browser`  | Launch new browser        | `{ headless? }`     |
-| `connect_browser` | Connect to existing (CDP) | `{ endpoint_url? }` |
-| `close_page`      | Close specific page       | `{ page_id }`       |
-| `close_session`   | Close entire browser      | `{}`                |
+- Rapid token exhaustion
+- Higher inference costs
+- Reduced reliability as relevant signal is buried in noise
 
-### Navigation
+In practice, agents spend more effort _finding_ the right information than reasoning about it.
 
-| Tool         | Purpose         | Input               |
-| ------------ | --------------- | ------------------- |
-| `navigate`   | Go to URL       | `{ url, page_id? }` |
-| `go_back`    | Browser back    | `{ page_id? }`      |
-| `go_forward` | Browser forward | `{ page_id? }`      |
-| `reload`     | Refresh page    | `{ page_id? }`      |
+Athena exists to change the unit of information exposed to the model.
 
-### Observation
+---
 
-| Tool               | Purpose             | Input                                                             |
-| ------------------ | ------------------- | ----------------------------------------------------------------- |
-| `capture_snapshot` | Capture page state  | `{ page_id? }`                                                    |
-| `find_elements`    | Find by criteria    | `{ kind?, label?, region?, limit?, include_readable?, page_id? }` |
-| `get_node_details` | Get element details | `{ eid, page_id? }`                                               |
+## Core Idea: Semantic Page Snapshots
 
-### Interaction
+Instead of exposing raw DOM structures or full accessibility trees, Athena produces **semantic page snapshots**.
 
-| Tool                       | Purpose            | Input                              |
-| -------------------------- | ------------------ | ---------------------------------- |
-| `click`                    | Click element      | `{ eid, page_id? }`                |
-| `type`                     | Type text          | `{ eid, text, clear?, page_id? }`  |
-| `press`                    | Press keyboard key | `{ key, modifiers?, page_id? }`    |
-| `select`                   | Select option      | `{ eid, value, page_id? }`         |
-| `hover`                    | Hover element      | `{ eid, page_id? }`                |
-| `scroll_element_into_view` | Scroll to element  | `{ eid, page_id? }`                |
-| `scroll_page`              | Scroll viewport    | `{ direction, amount?, page_id? }` |
+These snapshots are:
 
-## Element IDs (eid)
+- Compact and structured
+- Focused on user-visible intent
+- Designed for LLM recall and reasoning, not DOM completeness
+- Stable across layout shifts and DOM churn
 
-Elements are identified by stable semantic IDs (`eid`) instead of transient DOM node IDs:
+The goal is not to mirror the browser, but to present the page in a form that aligns with how language models reason about interfaces.
 
-```xml
-<match eid="a1b2c3d4e5f6" kind="button" label="Sign In" region="header" />
-```
+---
 
-EIDs are computed from:
-
-- Role/kind (button, link, input)
-- Accessible name (label text)
-- Landmark path (region + group hierarchy)
-- Position hint (screen zone, quadrant)
-
-This means the same logical element keeps its `eid` across page updates.
-
-## Response Format
-
-Tools return XML state responses with page understanding:
-
-```xml
-<state page_id="abc123" url="https://example.com" title="Example">
-  <layer type="main" active="true">
-    <actionables count="12">
-      <el eid="a1b2c3" kind="button" label="Sign In" />
-      <el eid="d4e5f6" kind="link" label="Forgot password?" />
-      <el eid="g7h8i9" kind="input" label="Email" type="email" />
-    </actionables>
-  </layer>
-  <atoms>
-    <viewport w="1280" h="720" />
-    <scroll x="0" y="0" />
-  </atoms>
-</state>
-```
+## How It Works
 
-### Layer Types
+At a high level:
 
-| Layer     | Description                |
-| --------- | -------------------------- |
-| `main`    | Primary page content       |
-| `modal`   | Dialog overlays            |
-| `drawer`  | Slide-in panels            |
-| `popover` | Dropdowns, tooltips, menus |
+1. The browser is controlled via Playwright and CDP
+2. The page is reduced into semantic regions and actionable elements
+3. A structured snapshot is generated and sent to the LLM
+4. Actions are resolved against stable semantic identifiers rather than fragile selectors
 
-## Usage Examples
+This separation keeps:
 
-### Login Flow
+- Browser lifecycle management isolated
+- Snapshots deterministic and low-entropy
+- Agent reasoning predictable and efficient
 
-```
-1. launch_browser { }
-   → XML state with initial page
+---
 
-2. navigate { url: "https://example.com/login" }
-   → State shows login form elements
+## Benchmarks
 
-3. find_elements { kind: "input", label: "email" }
-   → <match eid="abc123" kind="input" label="Email" />
+Early benchmarks against Playwright MCP show:
 
-4. click { eid: "abc123" }
-   → Element focused
+- **~19% fewer tokens consumed**
+- **~33% faster task completion**
+- Same or better success rates on common navigation tasks
 
-5. type { eid: "abc123", text: "user@example.com" }
-   → Value filled
+Benchmarks were run using Claude Code on representative real-world tasks.
+Results are task-dependent and should be treated as directional rather than absolute.
 
-6. press { key: "Tab" }
-   → Focus moved to password field
+---
 
-7. type { eid: "def456", text: "password123" }
-   → Password filled
-
-8. press { key: "Enter" }
-   → Form submitted, navigation to dashboard
-```
+## What Athena Is (and Is Not)
 
-### Cookie Consent (Multi-Frame)
-
-```
-1. navigate { url: "https://news-site.com" }
-   → Modal layer detected (cookie consent iframe)
-
-2. find_elements { label: "Accept", kind: "button" }
-   → <match eid="xyz789" kind="button" label="Accept All" />
-
-3. click { eid: "xyz789" }
-   → Modal closed, main layer active
-```
-
-## Installation
-
-```bash
-npm install
-npm run build
-```
+### Athena is:
 
-## Configuration
+- A semantic interface between browsers and LLM agents
+- An MCP server focused on reliability and efficiency
+- Designed for agent workflows, not test automation
 
-### Claude Desktop
+### Athena is not:
 
-Add to your Claude Desktop config:
+- A general-purpose browser
+- A visual testing or screenshot framework
+- A replacement for Playwright
 
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-**Linux**: `~/.config/Claude/claude_desktop_config.json`
+Playwright remains the execution layer; Athena focuses on representation and reasoning.
 
-```json
-{
-  "mcpServers": {
-    "browser": {
-      "command": "npx",
-      "args": ["athena-browser-mcp@latest"]
-    }
-  }
-}
-```
+---
 
-### Claude Code
+## Usage
 
-```bash
-claude mcp add athena-browser-mcp npx athena-browser-mcp@latest
-```
+Athena implements the **Model Context Protocol (MCP)** and works with:
 
-### VS Code
+- Claude Code
+- Claude Desktop
+- Cursor
+- VS Code
+- Any MCP-compatible client
 
-```bash
-code --add-mcp '{"name":"athena-browser-mcp","command":"npx","args":["athena-browser-mcp@latest"]}'
-```
+Example workflows include:
 
-### Cursor
+- Navigating complex web apps
+- Handling login and consent flows
+- Performing multi-step UI interactions with lower token usage
 
-Go to **Cursor Settings → MCP → Add new MCP Server**. Use command type with:
+See the `examples/` directory for concrete agent workflows.
 
-```
-npx athena-browser-mcp@latest
-```
+---
 
-### Codex
+## Installation
 
 ```bash
-codex mcp add athena-browser-mcp npx athena-browser-mcp@latest
+git clone https://github.com/lespaceman/athena-browser-mcp
+cd athena-browser-mcp
+npm install
+npm run build
 ```
 
-### Gemini CLI
+Configure the MCP server in your client according to its MCP integration instructions.
 
-```bash
-gemini mcp add -s user athena-browser-mcp -- npx athena-browser-mcp@latest
-```
+---
 
-### Connect to Existing Browser
+## Architecture Overview
 
-To connect to an existing Chromium browser with CDP enabled:
+Athena separates concerns into three layers:
 
-```bash
-# Start Chrome with remote debugging
-google-chrome --remote-debugging-port=9222
+- **Browser lifecycle** — page creation, navigation, teardown
+- **Semantic snapshot generation** — regions, elements, identifiers
+- **Action resolution** — mapping agent intent to browser actions
 
-# Or use environment variables
-export CEF_BRIDGE_HOST=127.0.0.1
-export CEF_BRIDGE_PORT=9222
-```
+This separation allows each layer to evolve independently while keeping agent-visible behavior stable.
 
-Then use `connect_browser` instead of `launch_browser`.
+---
 
-### Environment Variables
+## Status
 
-| Variable          | Description          | Default     |
-| ----------------- | -------------------- | ----------- |
-| `CEF_BRIDGE_HOST` | CDP host for connect | `127.0.0.1` |
-| `CEF_BRIDGE_PORT` | CDP port for connect | `9223`      |
+Athena is under active development.
+APIs and snapshot formats may evolve as real-world agent usage informs the design.
 
-## Development
+Feedback from practitioners building agent systems is especially welcome.
 
-```bash
-npm run build          # Compile TypeScript
-npm run type-check     # TypeScript type checking
-npm run lint           # ESLint
-npm run format         # Prettier format
-npm run check          # Run all checks
-npm test               # Run tests
-```
+---
 
 ## License
 

package/dist/src/browser/page-network-tracker.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Page Network Tracker
+ *
+ * Tracks in-flight network requests for a page and provides a reliable
+ * "network quiet" wait mechanism. Unlike Playwright's waitForLoadState('networkidle'),
+ * this tracks requests triggered after page load (e.g., by user actions).
+ *
+ * Uses a generation counter to safely handle navigation - late events from
+ * previous documents are ignored.
+ */
+import type { Page } from 'playwright';
+/**
+ * Tracks network requests for a single page.
+ *
+ * Attach to a page via `attach()`, then use `waitForQuiet()` to wait for
+ * network activity to settle. Call `markNavigation()` when navigating to
+ * safely reset state without race conditions.
+ */
+export declare class PageNetworkTracker {
+    private page;
+    private inflightCount;
+    private generation;
+    private currentGeneration;
+    private quietTimer;
+    private quietWindowMs;
+    private quietResolvers;
+    private onRequest;
+    private onRequestFinished;
+    private onRequestFailed;
+    /**
+     * Attach network event listeners to a page.
+     *
+     * Must be called before `waitForQuiet()` can be used.
+     * Safe to call multiple times - will detach previous listeners first.
+     */
+    attach(page: Page): void;
+    /**
+     * Detach all event listeners and cleanup timers.
+     *
+     * Call this when the page is closed or no longer needs tracking.
+     */
+    detach(): void;
+    /**
+     * Mark that a navigation occurred.
+     *
+     * This safely resets state by bumping the generation counter, so any
+     * late events from the previous document are ignored. Use this instead
+     * of directly resetting state to avoid race conditions.
+     */
+    markNavigation(): void;
+    /**
+     * Wait for network to become quiet (no inflight requests for quietWindowMs).
+     *
+     * @param timeoutMs - Maximum time to wait before returning false
+     * @param quietWindowMs - Time with 0 inflight requests to consider "idle"
+     * @returns true if network became quiet, false if timed out (never throws)
+     */
+    waitForQuiet(timeoutMs: number, quietWindowMs?: number): Promise<boolean>;
+    /**
+     * Get current inflight request count (for debugging/testing).
+     */
+    getInflightCount(): number;
+    /**
+     * Check if tracker is attached to a page.
+     */
+    isAttached(): boolean;
+    private cancelQuietTimer;
+    private checkQuiet;
+    private startQuietTimer;
+}
+/**
+ * Get or create a network tracker for a page.
+ *
+ * Note: This does NOT automatically attach the tracker.
+ * Call `tracker.attach(page)` after getting the tracker.
+ */
+export declare function getOrCreateTracker(page: Page): PageNetworkTracker;
+/**
+ * Remove and detach the tracker for a page.
+ *
+ * Call this when a page is closed to ensure proper cleanup.
+ */
+export declare function removeTracker(page: Page): void;
+/**
+ * Check if a page has a tracker attached.
+ */
+export declare function hasTracker(page: Page): boolean;
+//# sourceMappingURL=page-network-tracker.d.ts.map

package/dist/src/browser/page-network-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-network-tracker.d.ts","sourceRoot":"","sources":["../../../src/browser/page-network-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,YAAY,CAAC;AAKhD;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAG9B,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,cAAc,CAAyE;IAG/F,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,eAAe,CAAyC;IAEhE;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IA6CxB;;;;OAIG;IACH,MAAM,IAAI,IAAI;IA6Bd;;;;;;OAMG;IACH,cAAc,IAAI,IAAI;IAkDtB;;;;;;OAMG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAgC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAuBnB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,UAAU,IAAI,OAAO;IAMrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,eAAe;CAexB;AAYD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,kBAAkB,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAM9C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9C"}