brocogni
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.
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) + buttonThe 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-mcpThen connect your agent:
Claude Code
claude mcp add brocogni -- npx -y browser-cognition-mcpCursor
Settings -> Features -> MCP -> Add New
Name: brocogni | Type: stdio | Command: npx -y browser-cognition-mcpClaude Desktop
npx browser-cognition-mcp installOpenCode
Zero setup -- reads opencode.json automatically.
MCP Tools
Tool | What it does |
| Open a URL |
| Compile page into semantic node map |
| Search by role, name, or purpose |
| Get primary + fallback selectors |
| Click, fill, or hover |
| Preflight: visible, enabled, compatible |
| Diff two page states |
| Capture viewport as PNG |
| Run JS in page context |
| Persist session cookies |
| Page URL, title, iframe count |
Also exposes a write-robust-playwright-script prompt that teaches agents how to use these tools effectively.
Tests
npm testDeterministic, 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 toolsbrowser_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_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
Scored across 12 tools
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.
All tools follow a consistent 'browser_verb_noun' pattern, making it predictable which action applies to which resource. No mixed conventions or vague verbs.
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.
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
Related MCP Connectors
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenancethe open automation engine for AI agents. Control live browsers and desktop apps locally with instant execution171 npm3AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceSemantic 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 npm1MIT
- AlicenseBqualityBmaintenanceTurns 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.92113 npmMIT
- FlicenseNot gradedqualityAmaintenanceA 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-