browser-stream

browser-stream

MCP server that collapses browser act-then-observe into single tool calls. Every action returns its consequences — what appeared, disappeared, changed, or shifted — so agents see the effect of each action without a separate observation step.

~50% fewer tool calls. ~90% fewer tokens.

Tools

| Tool | Description | |---|---| | browser_navigate | Navigate to a URL. Returns a snapshot of interactive elements. | | browser_snapshot | Take a snapshot of the current page. Returns interactive elements with @e refs. | | browser_click | Click an element by ref. Returns consequences. | | browser_fill | Fill a text input by ref. Returns consequences. | | browser_press_key | Press a key or key combination (e.g. Enter, Control+a). Returns consequences. | | browser_scroll | Scroll the viewport or a container. Detects DOM churn and layout shifts. | | browser_wait_for | Wait for text to appear or a ref to become visible. Polls every 500ms. |

Refs

Every interactive element gets a globally unique ref like @e1, @e5, @e23. Refs are stable across actions — use them to target clicks, fills, and scrolls. When an element leaves the DOM, its ref is never reused.

Refs resolve through a 3-tier system: backendNodeId (fast) → CSS domPath (fallback) → REF_STALE error.

Consequences

Every action returns what changed:

• appeared — new interactive elements in the DOM
• disappeared — elements that left the DOM
• changed — elements with modified properties (name, value, checked, etc.)
• network — Fetch/XHR requests triggered by the action
• dom-churn — remove-then-re-add pairs (e.g. React re-rendering an entire list on scroll)
• layout-shift — CLS events without recent user input

Scroll detection

browser_scroll detects rendering pathologies that are invisible to before/after snapshot diffing:

→ browser_scroll({ ref: "@e12", direction: "down", amount: "page" })

consequences: [
  { type: "dom-churn", churnCount: 36, desc: "DOM churn detected: 36 remove/re-add pairs" },
  { type: "layout-shift", cls: 0.042, shiftCount: 2, desc: "Layout shift: cls=0.042 (2 shifts)" }
]

Setup

npm install
npm run build

Usage

Launch Chrome automatically:

node dist/index.js

Connect to an existing Chrome instance:

node dist/index.js --cdp-url ws://127.0.0.1:9222/devtools/browser/...

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "browser-stream": {
      "command": "node",
      "args": ["/path/to/browser-stream/dist/index.js"]
    }
  }
}

Development

npm run dev          # watch mode build
npm test             # run tests
npm run test:watch   # watch mode tests

Architecture

src/
├── index.ts              # CLI entrypoint, MCP server setup
├── types.ts              # All shared types and response schemas
├── cdp/
│   └── client.ts         # CDP connection (chrome-launcher + chrome-remote-interface)
├── state/
│   ├── ref-map.ts        # @e ref registry with 3-tier resolution
│   ├── snapshot.ts       # AX tree → ref assignment → compact line format
│   └── differ.ts         # Pre/post snapshot diffing → consequences
├── actions/
│   ├── interactable.ts   # Scroll-into-view + box model + center point
│   ├── stability.ts      # DOM mutation debounce + network tracking + churn detection
│   └── engine.ts         # Action orchestration (click, fill, scroll, etc.)
└── tools/
    ├── actions.ts        # MCP tool registrations for actions
    └── observation.ts    # MCP tool registrations for snapshot/wait_for

License

MIT