# Brocogni > semantic browser observation for AI agents via MCP, 100% local, zero telemetry - **Type:** MCP server - **Install:** `agentstack add mcp-hrshx3o5o6-brocogni` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [hrshx3o5o6](https://agentstack.voostack.com/s/hrshx3o5o6) - **Installs:** 0 - **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [hrshx3o5o6](https://github.com/hrshx3o5o6) - **Source:** https://github.com/hrshx3o5o6/brocogni - **Website:** https://www.npmjs.com/package/browser-cognition-mcp ## Install ```sh agentstack add mcp-hrshx3o5o6-brocogni ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Brocogni Making Playwright make sense to AI agents. --- 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](https://raw.githubusercontent.com/hrshx3o5o6/brocogni/main/assets/demo.mp4) --- ## Before / After **Before -- fragile selectors that break on every deploy:** ```ts 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:** ```ts 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. --- ## 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 ```bash npx playwright install chromium npx browser-cognition-mcp ``` Then connect your agent: **Claude Code** ```bash 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** ```bash 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 ```bash 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](./CONTRIBUTING.md). Security issues? [SECURITY.md](./SECURITY.md). --- ## License [MIT](./LICENSE). Go build something. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [hrshx3o5o6](https://github.com/hrshx3o5o6) - **Source:** [hrshx3o5o6/brocogni](https://github.com/hrshx3o5o6/brocogni) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/browser-cognition-mcp Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-hrshx3o5o6-brocogni - Seller: https://agentstack.voostack.com/s/hrshx3o5o6 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.