athena-browser-mcp 2.0.3 → 2.0.5

package/README.md

@@ -4,13 +4,44 @@
 [![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)
 
-Minimal MCP server for AI browser automation - 11 simple tools.
+MCP server for AI browser automation - 18 tools with semantic element targeting.
 
-## Design Philosophy
+## Why Athena?
 
-1. **Page state in system prompt** - Agent always knows current page state without querying
-2. **Lightweight delta responses** - Tools return what changed, not full snapshots
-3. **Simple verb-based naming** - `click`, `type`, `press` instead of `action_click`, `action_type`
+LLM agents face two hard constraints: limited context windows and expensive tokens. Yet browser automation requires understanding complex, ever-changing page state. Traditional tools dump raw accessibility trees or screenshots, wasting precious context and creating needle-in-haystack problems where agents struggle to locate relevant elements.
+
+Athena solves this with **semantic page snapshots** - compact, structured representations designed for LLM consumption:
+
+- **Token-efficient** - Hierarchical layers and regions eliminate noise, fitting more page understanding into less context
+- **High recall** - Structured XML with semantic element IDs lets agents find elements without scanning entire DOM trees
+- **Intuitive querying** - `find_elements` with semantic filters (kind, label, region) so agents ask for what they need
+- **Stable references** - Semantic `eid`s survive DOM mutations, eliminating stale element errors
+
+The result: fewer tokens, faster task completion, and higher-quality outputs with fewer errors.
+
+## Benchmark
+
+Comparison between Athena Browser MCP and Playwright MCP on real-world browser automation tasks. Tests run in Claude Code with Claude Opus 4.5.
+
+| #   | Task                                                                                  | Agent          | Result     | Tokens Used | Time Taken |
+| --- | ------------------------------------------------------------------------------------- | -------------- | ---------- | ----------- | ---------- |
+| 1   | Login → Create wishlist "Summer Escapes" → Add beach property (Airbnb)                | **Athena**     | ✅ Success | 92,870      | 2m 08s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 137,063     | 5m 23s     |
+| 2   | Bangkok Experiences → Food tour → Extract itinerary & pricing (Airbnb)                | **Athena**     | ✅ Success | 87,194      | 3m 27s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 94,942      | 3m 38s     |
+| 3   | Miami → Beachfront stays under $300 → Top 3 names + prices (Airbnb)                   | **Athena**     | ✅ Success | 124,597     | 5m 38s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 122,077     | 4m 51s     |
+| 4   | Paris → "Play" section → Top 5 titles + descriptions (Airbnb)                         | **Athena**     | ❌ Failed  | 146,575     | 4m 15s     |
+|     |                                                                                       | **Playwright** | ❌ Failed  | 189,495     | 7m 37s     |
+| 5   | Navigate Apple → find iPhone → configure iPhone 17 → add 256GB Black → confirm in bag | **Athena**     | ✅ Success | 65,629      | 3m 30s     |
+|     |                                                                                       | **Playwright** | ✅ Success | 102,754     | 6m 59s     |
+
+**Total Results:**
+
+- **Tokens**: Athena used **125,341 fewer tokens** (~19.4% more efficient)
+- **Time**: Athena completed tasks **9m 30s faster** (~33.4% faster)
+
+_Benchmark on a larger dataset coming soon._
 
 ## Architecture
 
@@ -18,15 +49,17 @@ Minimal MCP server for AI browser automation - 11 simple tools.
 ┌─────────────────────────────────────────────────────────────────┐
 │                         AI Agent                                 │
 │  ┌────────────────────────────────────────────────────────────┐ │
-│  │ System Prompt: Current page state (URL, forms, actions)    │ │
+│  │ System Prompt: XML state (layers, actionables, atoms)      │ │
 │  └────────────────────────────────────────────────────────────┘ │
 └───────────────────────────┬─────────────────────────────────────┘
                             │ MCP Protocol (stdio)
 ┌───────────────────────────▼─────────────────────────────────────┐
-│  SESSION: open, close                                            │
-│  NAVIGATION: goto                                                │
-│  OBSERVATION: snapshot, find                                     │
-│  INTERACTION: click, type, press, select, hover, scroll          │
+│  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
 ┌───────────────────────────▼─────────────────────────────────────┐
@@ -38,111 +71,129 @@ Minimal MCP server for AI browser automation - 11 simple tools.
 
 ### Session
 
-| Tool    | Purpose               | Input                        |
-| ------- | --------------------- | ---------------------------- |
-| `open`  | Start browser session | `{ headless?, connect_to? }` |
-| `close` | End browser session   | `{ page_id? }`               |
+| 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      | `{}`                |
 
 ### Navigation
 
-| Tool   | Purpose                 | Input                                                        |
-| ------ | ----------------------- | ------------------------------------------------------------ |
-| `goto` | Navigate to URL         | `{ url: "https://..." }`                                     |
-|        | Go back/forward/refresh | `{ back: true }` / `{ forward: true }` / `{ refresh: true }` |
+| 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? }`      |
 
 ### Observation
 
-| Tool       | Purpose                       | Input                                   |
-| ---------- | ----------------------------- | --------------------------------------- |
-| `snapshot` | Capture fresh page state      | `{ include_factpack?, include_nodes? }` |
-| `find`     | Find elements by criteria     | `{ kind?, label?, region? }`            |
-|            | Get details for specific node | `{ node_id }`                           |
+| 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? }`                                               |
 
 ### Interaction
 
-| Tool     | Purpose                | Input                                      |
-| -------- | ---------------------- | ------------------------------------------ |
-| `click`  | Click element          | `{ node_id }`                              |
-| `type`   | Type text into element | `{ text, node_id?, clear? }`               |
-| `press`  | Press keyboard key     | `{ key }` (Enter, Tab, Escape, etc.)       |
-| `select` | Choose dropdown option | `{ node_id, value }`                       |
-| `hover`  | Hover over element     | `{ node_id }` (reveal menus/tooltips)      |
-| `scroll` | Scroll page or element | `{ node_id? }` or `{ direction, amount? }` |
+| 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? }` |
 
-## Response Format
+## Element IDs (eid)
 
-Tools return lightweight deltas describing what changed:
+Elements are identified by stable semantic IDs (`eid`) instead of transient DOM node IDs:
 
-```json
-{
-  "delta": {
-    "action": "Clicked 'Sign In' button",
-    "changes": [
-      { "type": "navigation", "from": "/login", "to": "/dashboard" }
-    ]
-  },
-  "page_state": { ... }
-}
+```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>
 ```
 
-### Change Types
+### Layer Types
 
-| Type             | Description               |
-| ---------------- | ------------------------- |
-| `focused`        | Element received focus    |
-| `filled`         | Input field value changed |
-| `selected`       | Dropdown option selected  |
-| `clicked`        | Element was clicked       |
-| `navigation`     | URL changed               |
-| `page_changed`   | Page type changed         |
-| `modal_opened`   | Modal dialog appeared     |
-| `modal_closed`   | Modal dialog dismissed    |
-| `form_submitted` | Form was submitted        |
+| Layer     | Description                |
+| --------- | -------------------------- |
+| `main`    | Primary page content       |
+| `modal`   | Dialog overlays            |
+| `drawer`  | Slide-in panels            |
+| `popover` | Dropdowns, tooltips, menus |
 
 ## Usage Examples
 
 ### Login Flow
 
 ```
-1. open { }
-   → System prompt updated with initial page state
+1. launch_browser { }
+   → XML state with initial page
 
-2. goto { url: "https://example.com/login" }
-   → Page changed: login form detected
-   → System prompt updated with form fields
+2. navigate { url: "https://example.com/login" }
+   → State shows login form elements
 
-3. find { kind: "input", label: "email" }
-   → { matches: [{ node_id: "42", label: "Email" }] }
+3. find_elements { kind: "input", label: "email" }
+   → <match eid="abc123" kind="input" label="Email" />
 
-4. click { node_id: "42" }
-   → Focused: Email field
+4. click { eid: "abc123" }
+   → Element focused
 
-5. type { text: "user@example.com" }
-   → Filled: Email = "user@example.com"
+5. type { eid: "abc123", text: "user@example.com" }
+   → Value filled
 
 6. press { key: "Tab" }
-   → Focused: Password field
+   → Focus moved to password field
 
-7. type { text: "password123" }
-   → Filled: Password = "••••••••••••"
+7. type { eid: "def456", text: "password123" }
+   → Password filled
 
 8. press { key: "Enter" }
-   → Form submitted
-   → Navigation: /login → /dashboard
+   → Form submitted, navigation to dashboard
 ```
 
-### E-commerce Purchase
+### Cookie Consent (Multi-Frame)
 
 ```
-1. goto { url: "https://shop.example.com/product/123" }
-   → System prompt: product page, Add to Cart [node:101], Size [node:103]
+1. navigate { url: "https://news-site.com" }
+   → Modal layer detected (cookie consent iframe)
 
-2. select { node_id: "103", value: "Large" }
-   → Selected: Size = "Large"
+2. find_elements { label: "Accept", kind: "button" }
+   → <match eid="xyz789" kind="button" label="Accept All" />
 
-3. click { node_id: "101" }
-   → Clicked: Add to Cart
-   → Modal opened: "Added to cart"
+3. click { eid: "xyz789" }
+   → Modal closed, main layer active
 ```
 
 ## Installation
@@ -166,18 +217,66 @@ Add to your Claude Desktop config:
 {
   "mcpServers": {
     "browser": {
-      "command": "node",
-      "args": ["/path/to/athena-browser-mcp/dist/src/index.js"]
+      "command": "npx",
+      "args": ["athena-browser-mcp@latest"]
     }
   }
 }
 ```
 
+### Claude Code
+
+```bash
+claude mcp add athena-browser-mcp npx athena-browser-mcp@latest
+```
+
+### VS Code
+
+```bash
+code --add-mcp '{"name":"athena-browser-mcp","command":"npx","args":["athena-browser-mcp@latest"]}'
+```
+
+### Cursor
+
+Go to **Cursor Settings → MCP → Add new MCP Server**. Use command type with:
+
+```
+npx athena-browser-mcp@latest
+```
+
+### Codex
+
+```bash
+codex mcp add athena-browser-mcp npx athena-browser-mcp@latest
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add -s user athena-browser-mcp -- npx athena-browser-mcp@latest
+```
+
+### Connect to Existing Browser
+
+To connect to an existing Chromium browser with CDP enabled:
+
+```bash
+# Start Chrome with remote debugging
+google-chrome --remote-debugging-port=9222
+
+# Or use environment variables
+export CEF_BRIDGE_HOST=127.0.0.1
+export CEF_BRIDGE_PORT=9222
+```
+
+Then use `connect_browser` instead of `launch_browser`.
+
 ### Environment Variables
 
-| Variable             | Description               | Default |
-| -------------------- | ------------------------- | ------- |
-| `DEFAULT_TIMEOUT_MS` | Default operation timeout | `30000` |
+| Variable          | Description          | Default     |
+| ----------------- | -------------------- | ----------- |
+| `CEF_BRIDGE_HOST` | CDP host for connect | `127.0.0.1` |
+| `CEF_BRIDGE_PORT` | CDP port for connect | `9223`      |
 
 ## Development
 

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"}