# Better AI Browser Utilities (BABU)

Token-efficient MCP control for the Chrome session you already use—tabs, cookies,
logins, and all. BABU connects any MCP-compatible coding agent to a local Chrome
extension instead of launching a separate automation profile.

## Why BABU

- **Four compact MCP schemas by default** instead of twenty repetitive browser tools.
- **Progressive disclosure:** `browser_read` returns bounded text and compact controls;
  `browser_help` reveals command details only when requested.
- **Fast actions:** `browser_do` dispatches navigation, clicks, typing, keys, scrolling,
  waits, screenshots, JavaScript, and loopback file uploads.
- **Real browser state:** uses your existing Chrome tabs and authenticated sessions.
- **Portable:** install directly from GitHub with `uvx`; every documented client uses
  standard MCP stdio.
- **Local-first:** the only network listener binds to `127.0.0.1`; the extension
  WebSocket requires a generated pairing token.

The published MCP v2 schemas measure **567 tokens** in compact mode versus **2,219**
for the legacy twenty-tool surface: **74.45% less schema context per model turn**
(`o200k_base`, canonical JSON, excluding client framing).

## Architecture

```text
MCP client
   |  stdio (client-owned subprocess)
   v
BABU Python bridge
   |  authenticated WebSocket ws://127.0.0.1:8765
   v
BABU Chrome extension (MV3) -> your real Chrome tabs
```

## Install

Prerequisites: [uv](https://docs.astral.sh/uv/getting-started/installation/) and
Chrome 116 or newer.

```bash
uvx --from git+https://github.com/ItMeDiaTech/better-ai-browser-utilities@v0.1.0 babu setup
```

The command exports the bundled extension to `~/.babu/extension`, creates
`~/.babu/token`, and prints the token once for pairing.

In Chrome:

1. Open `chrome://extensions`.
2. Enable **Developer mode**.
3. Select **Load unpacked** and choose the printed extension directory.
4. Open the BABU extension, paste the pairing token, and select **Save**.

Stable Chrome no longer accepts automated `--load-extension` installation, so the
one-time manual load is required.

## Add BABU to an MCP client

Use this stdio launch definition:

```json
{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/ItMeDiaTech/better-ai-browser-utilities@v0.1.0",
    "babu",
    "mcp"
  ]
}
```

Exact commands and config files for Hermes, Codex, Claude Code, Cursor, VS Code,
Zed, ZCode, Gemini CLI, OpenCode, Cline, Windsurf, Pi, and Agent Prime are in
[docs/CLIENTS.md](docs/CLIENTS.md).

Only one BABU process can own WebSocket port 8765 at a time. Close another
BABU-enabled harness before starting a new one.

## MCP tools

| Tool | Purpose |
|---|---|
| `browser_health` | Connection, active-tab context, and optional full tab inventory |
| `browser_read` | Bounded page text and/or compact actionable element indices |
| `browser_do` | Validated dispatcher for browser actions |
| `browser_help` | On-demand command and parameter catalog |

`browser_do` commands:

```text
list_tabs, get_active_tab, open_tab, close_tab, activate_tab, navigate,
get_state, snapshot, click, hover, type, select, press, scroll, extract_text, screenshot,
eval, upload_files, wait_for, back, forward, reload
```

Recommended flow:

1. Call `browser_read` with a relevant `query`.
2. Pass the returned element index to `browser_do` with `click` or `type`.
3. Re-read after navigation or major DOM changes because indices are document-local.
4. Use `browser_help` only when a command's parameters are unclear.

Screenshots are saved to the system temporary directory by default; base64 image
bytes are omitted from model context unless `include_data_url=true` is explicit.

## CLI utilities

```bash
babu setup [--force]            # export/update extension and create token
babu token                      # print the current pairing token
babu mcp                        # stdio MCP server, compact profile
babu relay list_tabs            # direct browser command without an MCP client
babu relay navigate '{"url":"https://example.com"}'
```

`babu relay` is useful for minimal harnesses that prefer CLI tools over MCP.

## Tool profiles

- `compact` (default): the four tools above.
- `legacy`: twenty direct browser tools for clients that prefer one schema per action.
- `all`: both surfaces.

Select a profile with `--tool-profile compact|legacy|all` or
`BABU_TOOL_PROFILE`.

## Security

BABU controls the logged-in browser profile, so treat it as a powerful local tool.

- The WebSocket listener binds only to `127.0.0.1`; MCP travels over stdio.
- Chrome-extension origins and client roles are validated.
- The extension-to-bridge channel uses a 256-bit token stored at `~/.babu/token`.
- The extension popup can disable all control immediately.
- Password, OTP, and payment fields are redacted from routine reads.
- `browser_eval` executes JavaScript in the page's main world by design.
- File upload accepts only bounded direct loopback HTTP(S) URLs with no credentials.

Review every MCP tool invocation and use each client's approval controls.

## Limitations

- Chrome internal pages, the Web Store, PDF viewer, unloaded tabs, and controls inside
  iframes or shadow roots cannot be driven.
- Strict page CSP can block `browser_eval`; DOM read/click/type tools still work.
- `browser_press` supports Enter, Tab, and synthetic Escape; use `browser_type` for text.
- The unpacked extension must be reloaded from `chrome://extensions` after an update.
- The server is single-client and single-browser-extension by design.

## Update

```bash
uvx --from git+https://github.com/ItMeDiaTech/better-ai-browser-utilities@v0.1.0 babu setup --force
```

Reload BABU on `chrome://extensions`, then restart the MCP client. Change the Git tag
in your client config when adopting a newer release.

## License

MIT

<!-- mcp-name: io.github.ItMeDiaTech/better-ai-browser-utilities -->