Skip to main content
Glama

An AI agent with a browser is powerful. An AI agent that understands what it sees in the browser is unstoppable.

Brocogni is an open-source MCP server that sits between your AI agent and Playwright. Instead of dumping raw HTML into your agent's context (noisy, fragile, token-wasting), it compiles pages into a structured semantic map the agent can navigate, reason about, and act on in real time.

Two modes:

  • Agentic browsing loop -- The agent calls Brocogni tools directly: navigate, observe, click, extract, diff. Each step feeds back into reasoning. The browser is the environment, the agent is the brain.

  • Self-healing script generation -- The agent observes a page and generates vanilla Playwright code with automatic fallback selectors that survive frontend rebuilds.

No SaaS. No data leaves your machine. MIT.

▶️ Watch the 15-second demo


Before / After

Before -- fragile selectors that break on every deploy:

await page.click('.btn-primary');
await page.fill('.css-x83kf2 > input', 'hello');

Works today. Fails tomorrow when Tailwind classes rebuild.

After -- semantic selectors with self-healing fallbacks:

await page.click('role=button[name="Sign in"]');
await page.fill('role=textbox[name="Email"]', 'hello');

If the primary selector breaks, the fallback chain handles it:

role=button[name='Sign in']
  -> button:has-text('Sign in')
  -> xpath=//button[contains(text(),'Sign in')]
  -> css=div:has(> button) + button

The engine anchors unnamed elements to named siblings using relational XPath and CSS adjacent selectors. If a button has no accessible name but sits next to a labeled input, Brocogni finds it anyway.


Related MCP server: Helm

How it works

AI Agent
   |
   | MCP protocol (stdio)
   v
Brocogni MCP Server
   |
   | Playwright + CDP
   v
 AX Tree  -->  DOM Geometry  -->  Selector Engine
                                       |
                                       v
                         Self-healing selectors
                         (ARIA / CSS / XPath / relational)

The agent calls MCP tools in a loop: navigate to a URL, observe the page as structured semantic nodes, find targets by role or name, click to trigger new states, diff before/after to catch dynamic content. Actionable nodes carry role, name, bounding box, visibility, enabled state, and ranked selectors with fallback chains. The agent never sees raw HTML.


Benchmark

Brocogni is 81% cheaper than @playwright/mcp for the full workflow: observe → act → export a working Playwright script.

The ref iteration problem

@playwright/mcp returns a raw AX tree with temporary refs (e5, e10). Refs work inside the MCP session. When the LLM wants to export a persistent script, they expire.

@playwright/mcp                          Brocogni
──────────────                            ────────
Try 1: write ref-based script             Try 1: copy pre-computed selectors
       → refs expire, script broken              → #search-input works
Try 2: re-observe, guess getByRole               → One shot. Done.
       → 75% correct
Try 3: debug failed selectors
       → script finally works

Cost: $0.04 per script                    Cost: $0.01 per script
(3 attempts, trial & error)               (1 attempt, one-shot)

Cost at scale

Scripts/mo

@playwright/mcp

Brocogni

50

$1.78

$0.33

200

$7.11

$1.33

1,000

$35.53

$6.64

Pricing based on Claude Sonnet 4 ($3/M input, $15/M output).

Signal density

What the LLM must parse

@playwright/mcp

Brocogni

Elements returned

62–93 AX nodes

9 semantic nodes

Actionable

mixed

9 of 9 (100%)

LLM must filter

yes

no

Pre-computed selectors

no (refs)

yes (CSS/XPath/ARIA)

Bounding boxes

no

yes

Purpose inference

no

yes

Fallback chains

no

yes

Confidence scores

no

yes

@playwright/mcp gives the LLM raw data and says "figure it out." Brocogni gives the LLM understanding and says "here's what to do."


Install

npx playwright install chromium
npx browser-cognition-mcp

Then connect your agent:

Claude Code

claude mcp add brocogni -- npx -y browser-cognition-mcp

Cursor

Settings -> Features -> MCP -> Add New
Name: brocogni  |  Type: stdio  |  Command: npx -y browser-cognition-mcp

Claude Desktop

npx browser-cognition-mcp install

OpenCode Zero setup -- reads opencode.json automatically.


MCP Tools

Tool

What it does

browser_navigate

Open a URL

browser_observe

Compile page into semantic node map

browser_find_targets

Search by role, name, or purpose

browser_get_selector_plan

Get primary + fallback selectors

browser_act

Click, fill, or hover

browser_verify

Preflight: visible, enabled, compatible

browser_delta

Diff two page states

browser_screenshot

Capture viewport as PNG

browser_evaluate

Run JS in page context

browser_save_cookies

Persist session cookies

browser_info

Page URL, title, iframe count

Also exposes a write-robust-playwright-script prompt that teaches agents how to use these tools effectively.


Tests

npm test

Deterministic, no browser required. Covers semantic extraction, DOM fusion, selector ranking, relational fallbacks, delta computation, and action verification.


FAQ

Does it need API keys? No. Every observation runs locally. No accounts, no telemetry, no data leaves your machine.

Which agents does it work with? Any MCP-compatible agent: Claude Code, Claude Desktop, Cursor, OpenCode, and others.

Does it add runtime bloat to my project? No. Brocogni is a dev-time MCP server. It generates vanilla Playwright code -- no runtime dependencies introduced.

What happens when a selector fails? The fallback chain activates automatically. ARIA -> text -> XPath -> relational sibling. The agent tries each one in order.


Contributing

Bug reports, feature requests, and PRs welcome. See CONTRIBUTING.md. Security issues? SECURITY.md.


License

MIT. Go build something.

Available Tools

12 tools
browser_actA

Execute an action (click, fill, hover) on a node using its ID. Optional: pass 'state' if querying offline; otherwise defaults to last observed state.

Inputs: action (required), nodeId (required), text, state.

browser_deltaA

Compute the difference between two semantic states. Optional: pass parameters if querying offline; otherwise defaults to comparing the last two observed page states in memory.

Inputs: newState, oldState.

browser_evaluateB

Execute arbitrary JavaScript code in the page context and return the result. Fast and direct.

Inputs: code (required).

browser_find_targetsA

Search the last observed page state for nodes matching specific criteria (role, name content, enabled state). Extremely fast and token-efficient.

Inputs: role, onlyEnabled, nameIncludes.

browser_get_selector_planA

Retrieve the pre-computed selector plan (primary + healed fallback locators) for a specific semantic node. Optional: pass 'state' if querying offline; otherwise defaults to last observed state.

Inputs: nodeId (required), state.

browser_list_pagesA

List all open tabs/pages in the browser session. Returns index, title, and URL for each.

Inputs: no named parameters.

browser_navigateB

Launch the browser and navigate to a URL, or navigate the active tab to a new URL.

Inputs: url (required).

browser_observeA

Observe and extract the structured semantic state of the current active page, filtering out DOM noise. Note: If you see dropdowns/menus with expanded: false, you must hover them to reveal contents, then observe again.

Inputs: mode, budget.

browser_save_cookiesB

Save page cookies to a file for session persistence.

Inputs: path.

browser_screenshotA

Take a screenshot of the current page viewport and return it as a base64 encoded PNG string (useful for visual validation).

Inputs: fullPage.

browser_use_pageA

Switch the active page context to a specific tab by its index (from browser_list_pages).

Inputs: index (required).

browser_verifyB

Run safety action verification on a semantic node to confirm if it supports click/fill/hover and is interactable. Optional: pass 'state' if querying offline; otherwise defaults to last observed state.

Inputs: action (required), nodeId (required), state.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct browser automation task: navigation, state observation, interaction, JS execution, etc. There is no overlap; even similar tools like browser_verify and browser_find_targets serve different purposes.

    Naming Consistency5/5

    All tools follow a consistent 'browser_verb_noun' pattern, making it predictable which action applies to which resource. No mixed conventions or vague verbs.

    Tool Count5/5

    12 tools cover the essential browser automation capabilities without being excessive. The count is appropriate for the domain, providing a focused set that avoids bloat.

    Completeness4/5

    The tool surface covers core workflows (navigation, interaction, state extraction, screenshots, cookies) but lacks explicit tab creation or closure tools, which are minor gaps for a complete browsing session manager.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Semantic browser automation MCP server that lets AI agents control a browser using natural language, handling navigation, form filling, data extraction, and more without CSS selectors.
      758 npm
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Turns Chrome into a local MCP server, giving AI agents 51 browser tools to inspect DOM, automate clicks, run JavaScript, audit security and accessibility, mock APIs, extract data, record demos, and more from any MCP client.
      92
      113 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      A real Chromium browser for AI agents, driven over MCP: compact page outlines with stable refs, diff-only replies after each action, real mouse and keyboard input, the agent's own signed-in accounts, and human approval for payments. Windows 11.
      2
      -