barebrowse 0.1.0 → 0.2.1

package/cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * cli.js -- barebrowse CLI entry point.
+ *
+ * Usage:
+ *   npx barebrowse mcp            Start the MCP server (JSON-RPC over stdio)
+ *   npx barebrowse install        Auto-configure MCP in Claude Desktop / Cursor / Claude Code
+ *   npx barebrowse browse <url>   One-shot browse, print snapshot to stdout
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+const cmd = process.argv[2];
+
+if (cmd === 'mcp') {
+  await import('./mcp-server.js');
+
+} else if (cmd === 'install') {
+  install();
+
+} else if (cmd === 'browse' && process.argv[3]) {
+  const { browse } = await import('./src/index.js');
+  const url = process.argv[3];
+  const mode = process.argv[4] || 'headless';
+  try {
+    const snapshot = await browse(url, { mode });
+    process.stdout.write(snapshot + '\n');
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+} else {
+  process.stdout.write(`barebrowse -- CDP-direct browsing for autonomous agents
+
+Usage:
+  barebrowse mcp                Start MCP server (JSON-RPC over stdio)
+  barebrowse install            Auto-configure MCP for Claude Desktop / Cursor / Claude Code
+  barebrowse browse <url>       One-shot browse, print ARIA snapshot
+
+As a library:
+  import { browse, connect } from 'barebrowse';
+
+As bareagent tools:
+  import { createBrowseTools } from 'barebrowse/bareagent';
+
+More: see README.md or barebrowse.context.md
+`);
+}
+
+// --- MCP auto-installer ---
+
+function install() {
+  const mcpEntry = {
+    command: 'npx',
+    args: ['barebrowse', 'mcp'],
+  };
+
+  const targets = detectTargets();
+
+  if (targets.length === 0) {
+    console.log('No MCP clients detected. You can manually add this to your MCP config:\n');
+    console.log(JSON.stringify({ mcpServers: { barebrowse: mcpEntry } }, null, 2));
+    console.log('\nSupported clients: Claude Desktop, Cursor, Claude Code');
+    return;
+  }
+
+  let installed = 0;
+
+  for (const target of targets) {
+    try {
+      const config = readJsonOrEmpty(target.path);
+      if (!config.mcpServers) config.mcpServers = {};
+
+      if (config.mcpServers.barebrowse) {
+        console.log(`  ${target.name}: already configured`);
+        installed++;
+        continue;
+      }
+
+      config.mcpServers.barebrowse = mcpEntry;
+
+      // Ensure parent dir exists
+      const dir = join(target.path, '..');
+      mkdirSync(dir, { recursive: true });
+
+      writeFileSync(target.path, JSON.stringify(config, null, 2) + '\n');
+      console.log(`  ${target.name}: installed -> ${target.path}`);
+      installed++;
+    } catch (err) {
+      console.log(`  ${target.name}: failed (${err.message})`);
+    }
+  }
+
+  if (installed > 0) {
+    console.log(`\nDone. Restart your MCP client to pick up the new server.`);
+    console.log('Tools available: browse, goto, snapshot, click, type, press, scroll');
+  }
+}
+
+function detectTargets() {
+  const home = homedir();
+  const os = platform();
+  const targets = [];
+
+  // Claude Desktop
+  let claudeDesktop;
+  if (os === 'darwin') {
+    claudeDesktop = join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  } else if (os === 'linux') {
+    claudeDesktop = join(home, '.config', 'Claude', 'claude_desktop_config.json');
+  } else if (os === 'win32') {
+    claudeDesktop = join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+  }
+  if (claudeDesktop) {
+    // Check if Claude Desktop dir exists (even if config doesn't yet)
+    const dir = join(claudeDesktop, '..');
+    if (existsSync(dir)) {
+      targets.push({ name: 'Claude Desktop', path: claudeDesktop });
+    }
+  }
+
+  // Cursor
+  let cursorDir;
+  if (os === 'darwin') {
+    cursorDir = join(home, '.cursor');
+  } else if (os === 'linux') {
+    cursorDir = join(home, '.cursor');
+  } else if (os === 'win32') {
+    cursorDir = join(home, '.cursor');
+  }
+  if (cursorDir && existsSync(cursorDir)) {
+    targets.push({ name: 'Cursor', path: join(cursorDir, 'mcp.json') });
+  }
+
+  // Claude Code (project-level .mcp.json in cwd)
+  const cwd = process.cwd();
+  const claudeCodePath = join(cwd, '.mcp.json');
+  // Only suggest if we're in a project directory (has package.json or .git)
+  if (existsSync(join(cwd, 'package.json')) || existsSync(join(cwd, '.git'))) {
+    targets.push({ name: 'Claude Code (this project)', path: claudeCodePath });
+  }
+
+  return targets;
+}
+
+function readJsonOrEmpty(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}

package/docs/blueprint.md

@@ -0,0 +1,361 @@
+# barebrowse -- Blueprint
+
+Vanilla JS library. CDP-direct. URL in, pruned ARIA snapshot out.
+No Playwright, no bundled browser, no build step.
+
+---
+
+## What It Does
+
+Gives autonomous agents authenticated access to the web through the user's own Chromium browser.
+
+```js
+import { browse, connect } from 'barebrowse';
+
+// One-shot: read a page
+const snapshot = await browse('https://any-page.com');
+
+// Session: navigate, interact, observe
+const page = await connect();
+await page.goto('https://any-page.com');
+console.log(await page.snapshot());
+await page.click('8');      // ref from snapshot
+await page.type('3', 'hello');
+await page.scroll(500);
+await page.close();
+```
+
+---
+
+## Capabilities
+
+Every action returns a **pruned ARIA snapshot** -- the agent's view of the page after each move. The snapshot is a YAML-like tree with `[ref=N]` markers on interactive elements. The agent reads the snapshot, picks a ref, acts, then reads the next snapshot. This is the observe-think-act loop.
+
+### Actions
+
+| Action | Method | What It Does | Status |
+|--------|--------|-------------|--------|
+| Navigate | `page.goto(url)` | Load a URL, wait for page load, dismiss consent | Done |
+| Snapshot | `page.snapshot()` | Pruned ARIA tree (47-95% token reduction) | Done |
+| Click | `page.click(ref)` | Scroll into view, mouse press+release at element center | Done |
+| Type | `page.type(ref, text)` | Focus element, insert text (fast batch mode) | Done |
+| Type (clear) | `page.type(ref, text, { clear: true })` | Select-all + delete, then type (replaces pre-filled content) | Done |
+| Type (key events) | `page.type(ref, text, { keyEvents: true })` | Char-by-char keyDown/keyUp (triggers JS handlers) | Done |
+| Press | `page.press(key)` | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home/End, PageUp/Down, Space | Done |
+| Scroll | `page.scroll(deltaY)` | Mouse wheel event (positive=down, negative=up) | Done |
+| Hover | `page.hover(ref)` | Move mouse to element center (triggers hover styles/tooltips) | Done |
+| Select | `page.select(ref, value)` | Set `<select>` value or click custom dropdown option | Done |
+| Screenshot | `page.screenshot(opts)` | `Page.captureScreenshot`, returns base64 string | Done |
+| Wait for nav | `page.waitForNavigation()` | Promise.race of loadEventFired + frameNavigated (SPA-aware) | Done |
+| Wait for idle | `page.waitForNetworkIdle(opts)` | Resolve when no pending requests for N ms (default 500) | Done |
+| Inject cookies | `page.injectCookies(url, opts)` | Extract cookies from Firefox/Chromium, inject via CDP | Done |
+| Raw CDP | `page.cdp.send(method, params)` | Escape hatch for any CDP command | Done |
+| Close | `page.close()` | Close page target, disconnect CDP, kill browser (if headless) | Done |
+
+### Obstacle course -- what barebrowse handles automatically
+
+| Obstacle | How It's Handled | Mode |
+|----------|-----------------|------|
+| **Cookie consent walls** (GDPR) | ARIA tree scan, jsClick accept button. 7 languages: EN, NL, DE, FR, ES, IT, PT | Both |
+| **Consent in dialog role** | Detect `dialog`/`alertdialog` with consent hints, click accept inside | Both |
+| **Consent outside dialog** (BBC SourcePoint) | Fallback global button scan when dialog has no accept button | Both |
+| **Consent behind iframe overlay** | JS `.click()` via `DOM.resolveNode` bypasses z-index/overlay issues | Both |
+| **Permission prompts** (location, notifications, camera, mic) | Launch flags + CDP `Browser.setPermission` auto-deny | Both |
+| **Media autoplay blocked** | `--autoplay-policy=no-user-gesture-required` | Both |
+| **Login walls** | Firefox cookie extraction, CDP injection (user's real sessions) | Both |
+| **Pre-filled form inputs** | `type({ clear: true })` selects all + deletes before typing | Both |
+| **Off-screen elements** | `DOM.scrollIntoViewIfNeeded` before every click | Both |
+| **Form submission** | `press('Enter')` with proper `text: '\r'` triggers onsubmit | Both |
+| **Tab between fields** | `press('Tab')` with `text: '\t'` moves focus | Both |
+| **SPA navigation** (YouTube, GitHub) | `waitForNavigation()` uses frameNavigated + loadEventFired race | Both |
+| **Bot detection** (Google, Reddit) | Stealth patches (headless) + headed mode with real cookies | Both |
+| **`navigator.webdriver`** | Stealth patches: webdriver, plugins, languages, chrome object | Headless |
+| **Profile locking** | Unique temp dir per headless instance (`/tmp/barebrowse-<pid>-<ts>`) | Headless |
+| **ARIA noise** | 9-step pruning: wrapper collapse, noise removal, landmark promotion | Both |
+
+### Not yet handled
+
+| Obstacle | What's Needed | Difficulty |
+|----------|--------------|------------|
+| File upload | `Input.setFiles` via CDP | Low |
+| Drag and drop | `Input.dispatchDragEvent` sequence | Medium |
+| Infinite scroll | Scroll + wait for new content strategy | Medium |
+| CAPTCHAs | Cannot solve -- headed mode lets user solve manually | N/A |
+| Cross-origin iframes | Frame tree traversal via CDP | Medium |
+| Canvas/WebGL | Opaque to ARIA -- needs screenshot + vision model | Hard |
+
+### Tested sites (16+ sites, 8 countries, all consent dismissed)
+
+| Site | Consent | Cookies | Interactions | Notes |
+|------|---------|---------|-------------|-------|
+| google.com | NL dialog dismissed | Firefox injection | Search (combobox + Enter) | Bot-blocks headless |
+| youtube.com | Bypassed via cookies | Firefox injection | Search + video playback | Full e2e demo, SPA nav |
+| bbc.com | SourcePoint dismissed | -- | -- | Button outside dialog |
+| wikipedia.org | -- | -- | Link click + navigation | Clean, no consent |
+| github.com | -- | -- | SPA navigation | Needs settle time |
+| duckduckgo.com | -- | -- | Search + results | Headless-friendly |
+| news.ycombinator.com | -- | -- | Story link click | Clean, simple DOM |
+| amazon.de | Banner dismissed | -- | -- | |
+| theguardian.com | CMP dismissed | -- | -- | |
+| spiegel.de | CMP dismissed | -- | -- | German |
+| lemonde.fr | CMP dismissed | -- | -- | French |
+| elpais.com | CMP dismissed | -- | -- | Spanish |
+| corriere.it | CMP dismissed | -- | -- | Italian |
+| nos.nl | CMP dismissed | -- | -- | Dutch |
+| bild.de | CMP dismissed | -- | -- | German |
+| nu.nl | CMP dismissed | -- | -- | Dutch |
+| booking.com | Banner dismissed | -- | -- | |
+| nytimes.com | -- | -- | -- | No consent wall |
+| stackoverflow.com | Footer link only | -- | -- | Not blocking |
+| cnn.com | -- | -- | -- | No consent wall |
+| reddit.com | -- | -- | Fallback to old.reddit | Bot-blocks headless |
+
+---
+
+## Architecture
+
+### Full pipeline: browse(url) or connect() -> goto(url)
+
+```
+1. LAUNCH            chromium.js finds installed browser
+                     Headless: spawn fresh Chromium with permission flags
+                     Headed: connect to running browser on CDP port
+                     Hybrid: try headless, detect challenge page, fallback to headed
+
+2. CDP CONNECTION    cdp.js opens WebSocket to browser
+                     Creates page target, attaches flattened session
+                     Enables Page, Network, DOM domains
+
+3. STEALTH           stealth.js (headless only)
+                     Page.addScriptToEvaluateOnNewDocument before any page scripts
+                     Patches: navigator.webdriver, plugins, languages, chrome object
+
+4. PERMISSIONS       Browser.setPermission denies all prompts
+                     geo, notifications, camera, mic, midi, sensors, idle
+
+5. AUTH              auth.js extracts cookies from user's browser
+                     Firefox: SQLite cookies.sqlite (plaintext)
+                     Chromium: SQLite Cookies + AES decrypt via keyring
+                     Injects via Network.setCookie before navigation
+
+6. NAVIGATE          Page.navigate(url), wait for Page.loadEventFired
+                     500ms settle for dynamic content
+
+7. CONSENT           consent.js scans ARIA tree post-load
+                     Finds dialog/alertdialog with consent hints
+                     Falls back to global button scan (BBC SourcePoint pattern)
+                     jsClick via DOM.resolveNode (bypasses iframe overlays)
+
+8. SNAPSHOT          Accessibility.getFullAXTree -> nested tree (aria.js)
+                     prune.js: 9-step pipeline (47-95% token reduction)
+                     Output: YAML-like text with [ref=N] markers
+
+9. INTERACT          interact.js dispatches real CDP Input events
+                     click: scrollIntoView -> getBoxModel -> mousePressed/Released
+                     type: DOM.focus -> insertText or keyDown/keyUp per char
+                     press: special keys (Enter, Tab, Escape, arrows, etc.)
+                     scroll: mouseWheel events
+                     hover: mouseMoved at element center
+                     select: set <select> value or click custom dropdown option
+
+10. OBSERVE AGAIN    Back to step 8. Refs are ephemeral -- fresh snapshot needed.
+```
+
+### Module table
+
+Eleven modules, 2,396 lines, zero required dependencies.
+
+| Module | Lines | Purpose |
+|---|---|---|
+| `src/index.js` | 434 | Public API: `browse()`, `connect()`, screenshot, network idle, hybrid |
+| `src/cdp.js` | 148 | WebSocket CDP client, flattened sessions |
+| `src/chromium.js` | 148 | Find/launch Chromium browsers, permission-suppressing flags |
+| `src/aria.js` | 69 | Format ARIA tree as YAML-like text |
+| `src/auth.js` | 279 | Cookie extraction (Chromium AES + keyring, Firefox), CDP injection |
+| `src/prune.js` | 472 | ARIA pruning pipeline (9-step, ported from mcprune) |
+| `src/interact.js` | 208 | Click, type, press, scroll, hover, select |
+| `src/consent.js` | 210 | Auto-dismiss cookie consent dialogs, 7 languages |
+| `src/stealth.js` | 51 | Navigator patches for headless anti-detection |
+| `src/bareagent.js` | 161 | Tool adapter for bareagent Loop |
+| `mcp-server.js` | 216 | MCP server (JSON-RPC 2.0 over stdio) |
+
+---
+
+## What's Built
+
+### Headless mode -- done
+Spawn a fresh Chromium, navigate, snapshot, close. Default mode.
+- Cookie extraction from user's Firefox or Chromium profile
+- Cookie injection via `Network.setCookie` before navigation
+- ARIA tree extraction via `Accessibility.getFullAXTree`
+- 9-step pruning: landmarks, noise removal, wrapper collapsing, context filtering
+- 47-95% token reduction depending on page complexity
+- Permission prompts auto-suppressed (notifications, geolocation, camera, mic)
+- Stealth patches: `navigator.webdriver`, plugins, languages, chrome object
+
+### Headed mode -- done
+Connect to an already-running browser on a CDP debug port.
+- Same ARIA + prune pipeline
+- Manual cookie injection via `page.injectCookies(url, { browser })` (e.g. inject Firefox cookies into headed Chromium)
+- Permission prompts suppressed via CDP `Browser.setPermission`
+- User must launch browser with `--remote-debugging-port=9222`
+
+### Hybrid mode -- done
+Try headless first. If bot-blocked (Cloudflare, etc.), fall back to headed automatically.
+- Detection: heuristic on ARIA tree for challenge phrases ("Just a moment", "Checking your browser")
+- Fallback: kill headless, connect to user's running browser on port 9222, re-navigate
+- One flag: `mode: 'hybrid'`
+
+### Interactions -- done, real-world tested
+On `connect()` sessions: `click(ref)`, `type(ref, text, opts)`, `press(key)`, `scroll(deltaY)`, `hover(ref)`, `select(ref, value)`, `screenshot()`, `waitForNavigation()`, `waitForNetworkIdle()`, `injectCookies(url, opts)`.
+- Refs come from ARIA snapshot (`[ref=N]` markers)
+- Click: `DOM.scrollIntoViewIfNeeded` -> `DOM.getBoxModel` -> center -> `Input.dispatchMouseEvent`
+- Type: `DOM.focus` + `Input.insertText` (fast) or `Input.dispatchKeyEvent` (triggers handlers)
+- Type with `{ clear: true }`: select-all (Ctrl+A) + delete before typing
+- Press: special keys (Enter, Tab, Escape, Backspace, arrows) with proper key/code/keyCode
+- Scroll: `Input.dispatchMouseEvent` mouseWheel
+- Hover: `DOM.scrollIntoViewIfNeeded` -> `Input.dispatchMouseEvent` mouseMoved
+- Select: native `<select>` (set value + change event) or custom dropdown (click + find option)
+- Screenshot: `Page.captureScreenshot` -> base64 string (png/jpeg/webp)
+- WaitForNavigation: `Promise.race` of `Page.loadEventFired` + `Page.frameNavigated` (SPA-aware)
+- WaitForNetworkIdle: track pending requests, resolve when 0 for N ms
+
+**Real-world tested against:** Google, Wikipedia, GitHub (SPA), Hacker News, DuckDuckGo, YouTube (search + video playback), example.com
+
+### Cookie consent auto-dismiss -- done
+Automatically detects and dismisses GDPR/cookie consent dialogs after page load.
+- Scans ARIA tree for `dialog`/`alertdialog` with consent-related content
+- Falls back to global button scan for sites that don't use dialog roles (e.g. BBC SourcePoint)
+- Uses JS `.click()` via `DOM.resolveNode` + `Runtime.callFunctionOn` to bypass iframe overlays
+- Multi-language: EN, NL, DE, FR, ES, IT, PT button text patterns
+- Opt-out via `{ consent: false }`
+- Works in both headless and headed modes
+
+**Tested against 16+ sites across 8 countries, 0 consent dialogs remaining.**
+
+### Permission suppression -- done
+Chrome permission prompts (location, notifications, camera, mic, etc.) are suppressed automatically.
+- Headless: launch flags (`--disable-notifications`, `--autoplay-policy=no-user-gesture-required`, `--use-fake-device-for-media-stream`, `--use-fake-ui-for-media-stream`, `--disable-features=MediaRouter`)
+- Both modes: CDP `Browser.setPermission` denies geolocation, notifications, midi, audioCapture, videoCapture, sensors, idleDetection, etc.
+- No user prompt ever appears -- agents browse without interruption
+
+### Cross-browser cookie injection -- done
+Firefox cookies (user's default browser) extracted from SQLite -> injected into headless or headed Chromium via CDP `Network.setCookie`. No need to use Chromium as daily browser.
+- `browse()`: auto-injects cookies before navigation (opt-out with `{ cookies: false }`)
+- `connect()`: manual injection via `page.injectCookies(url, { browser: 'firefox' })`
+- Proven: YouTube login session transferred from Firefox -> headed Chromium -> video playback
+
+### Stealth patches -- done
+Anti-detection for headless mode via `Page.addScriptToEvaluateOnNewDocument` (runs before page scripts).
+- `navigator.webdriver` -> undefined
+- `navigator.plugins` -> fake 3 plugins
+- `navigator.languages` -> `['en-US', 'en']`
+- `window.chrome` -> fake object
+- `Permissions.prototype.query` -> notifications return 'prompt'
+- Applied automatically in headless mode
+
+### Tests -- 47+ passing
+- 16 unit tests (pruning logic)
+- 7 unit tests (cookie extraction -- 2 skip when Chromium profile locked)
+- 5 unit tests (CDP client + browser launch)
+- 11 integration tests (end-to-end browse pipeline)
+- 15 integration tests (real-world interactions: data: URL fixture + live sites)
+
+---
+
+## Integrations
+
+### bareagent -- tool adapter
+
+`createBrowseTools(opts)` returns bareagent-compatible tools for the Loop:
+
+```js
+import { Loop } from 'bare-agent';
+import { Anthropic } from 'bare-agent/providers';
+import { createBrowseTools } from 'barebrowse/src/bareagent.js';
+
+const { tools, close } = createBrowseTools();
+const loop = new Loop({ provider: new Anthropic({ apiKey }) });
+const result = await loop.run(messages, tools);
+await close();
+```
+
+9 tools: browse, goto, snapshot, click, type, press, scroll, select, screenshot.
+Action tools auto-return snapshot (300ms settle delay). The LLM always sees the result.
+
+### MCP server
+
+Raw JSON-RPC 2.0 over stdio. Zero SDK dependencies. `npm install barebrowse` then:
+
+```json
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
+```
+
+7 tools: browse (one-shot), goto, snapshot, click, type, press, scroll.
+Action tools return `'ok'` -- agent calls `snapshot` explicitly (MCP tool calls are cheap to chain).
+Session tools share a singleton page, lazy-created on first use.
+
+---
+
+## Ecosystem
+
+```
+bareagent  = the brain  (orchestration, LLM loop, memory, retries)
+barebrowse = the eyes + hands  (browse, read, interact with the web)
+```
+
+**barebrowse is a library.** bareagent imports it as a capability. barebrowse doesn't know about bareagent. bareagent doesn't know about CDP. Clean boundary. Each ships and tests independently.
+
+---
+
+## Constraints
+
+- **Chromium-only.** CDP protocol. Covers Chrome, Chromium, Edge, Brave, Vivaldi, Arc, Opera (~80% desktop share). Firefox later via WebDriver BiDi.
+- **Linux first.** Tested on Fedora/KDE. macOS/Windows cookie extraction paths exist in auth.js but untested.
+- **Node >= 22.** Built-in WebSocket, built-in SQLite.
+- **Not a server.** Library that agents import. Wrap as MCP (included) or HTTP if needed.
+- **Not cross-platform tested.** Local development only, not published to npm.
+
+---
+
+## File Map
+
+```
+barebrowse/
+├── src/
+│   ├── index.js       # Public API: browse(), connect(), screenshot, network idle, hybrid
+│   ├── cdp.js         # WebSocket CDP client
+│   ├── chromium.js    # Find/launch Chromium, permission flags
+│   ├── aria.js        # ARIA tree formatting
+│   ├── auth.js        # Cookie extraction + injection
+│   ├── prune.js       # ARIA pruning (9-step pipeline)
+│   ├── interact.js    # Click, type, press, scroll, hover, select
+│   ├── consent.js     # Auto-dismiss cookie consent dialogs
+│   ├── stealth.js     # Navigator patches for headless anti-detection
+│   └── bareagent.js   # Tool adapter for bareagent Loop
+├── test/
+│   ├── unit/          # prune, auth, cdp tests
+│   └── integration/   # browse + interact tests (real sites)
+├── examples/
+│   ├── headed-demo.js # Interactive demo: Wikipedia → DuckDuckGo
+│   └── yt-demo.js     # YouTube demo: Firefox cookies → search → play video
+├── docs/
+│   ├── prd.md         # Decisions + rationale (reference)
+│   ├── poc-plan.md    # Original POC phases + DoD
+│   ├── blueprint.md   # This file
+│   └── testing.md     # Test guide: pyramid, all 54 tests, CI strategy
+├── mcp-server.js      # MCP server (JSON-RPC 2.0 over stdio)
+├── cli.js             # CLI entry: `npx barebrowse mcp` or `npx barebrowse browse <url>`
+├── .mcp.json          # MCP server config for Claude Desktop / Cursor
+├── barebrowse.context.md  # LLM-consumable integration guide
+├── package.json
+├── README.md
+└── CLAUDE.md
+```