<div align="center">
  <img src="assets/logo.svg" alt="A11yDriver Logo" width="128" height="128" />

  # A11yDriver Engine
  ### Zero-UI Chrome Extension & MCP Server Bridge for Autonomous AI Agents

  [![NPM Version](https://img.shields.io/npm/v/a11ydriver-mcp.svg?style=for-the-badge&color=6366F1)](https://www.npmjs.com/package/a11ydriver-mcp)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](CONTRIBUTING.md)

  <br />

  <img src="assets/store-banner-1280x800.svg" alt="A11yDriver Banner" width="100%" />

  <br />
  <br />

  <p align="center">
    <b>A11yDriver</b> empowers any AI Agent (Claude, Manus, OpenAI, Custom LLMs) to operate Chrome via DevTools CDP and Accessibility Trees with zero UI overhead.
  </p>

  <sub>Engineered with ❤️ by <b><a href="https://irnk.codes">Eliyanto Sarage</a></b> • <a href="mailto:officialelsa21@gmail.com">officialelsa21@gmail.com</a></sub>
</div>

---

<br />

## ⚡ Key Highlights & Architecture

- 🛡️ **Zero-UI Background Operator**: Operates 100% silently in Chrome service worker without popup or sidepanel overhead.
- 🌳 **Accessibility Tree Serializer (`a11y-engine.js`)**: Converts complex DOM + Shadow DOM trees into compressed semantic trees with `refId` tracking, saving up to 80% LLM tokens.
- 🧰 **21 Full CDP MCP Tools**: Complete browser control including Tab Group sessions, drag-and-drop, full-page screenshots, PDF export, hover triggering, and key pressing.
- 🔒 **Sensitive Data Redaction**: Automatic local masking of password fields, OTPs, and credit card credentials.
- ⏱️ **Manifest V3 Keep-Alive**: Heartbeat alarms prevent Service Worker sleep during extended AI agent sessions.

---

## 🚀 Quick Setup

### 1. Install Global MCP Server
```bash
npm install -g a11ydriver-mcp
```

### 2. Configure AI Agent (Claude Code / Claude Desktop / Custom Agent Host)
Add `a11ydriver-mcp` to your MCP configuration:
```json
{
  "mcpServers": {
    "a11ydriver": {
      "command": "a11ydriver-mcp"
    }
  }
}
```

### 3. Load Extension in Chrome
1. Open `chrome://extensions` in Google Chrome.
2. Turn on **Developer mode**.
3. Click **Load unpacked** and select the `extension/` directory.

### 4. Enable Agent Diagnostic Protocol (System Prompt)
Copy and paste the prompt in [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) into your AI Agent's system instructions. This ensures the AI Agent automatically detects whether MCP & Extension are connected and diagnoses any missing setup steps.

---

## 🛠️ Complete MCP Tool Protocol (21 Tools)

| Tool Category | MCP Tool Name | Description |
| :--- | :--- | :--- |
| **Tab & Group** | `browser_list_tabs` | List all open Chrome tabs with IDs & titles |
| | `browser_new_tab` | Open a new tab (optional `url`, `groupId`) |
| | `browser_create_agent_group` | Create an isolated tab group for AI agent session |
| | `browser_cleanup_agent_group` | Close all tabs inside an agent tab group after task finishes |
| | `browser_switch_tab` | Switch active focused tab by `tabId` |
| | `browser_close_tab` | Close specified tab by `tabId` |
| **Navigation** | `browser_navigate` | Navigate active tab to target `url` |
| | `browser_go_back` | Go back in browser history |
| | `browser_go_forward` | Go forward in browser history |
| | `browser_reload` | Reload current page |
| **Interactions** | `browser_click` | Click element by coordinates `(x, y)` or element `refId` |
| | `browser_hover` | Hover cursor over element or `(x, y)` coordinates |
| | `browser_drag_and_drop` | Perform drag & drop from `(fromX, fromY)` to `(toX, toY)` |
| | `browser_type` | Type text into element `refId` or active input |
| | `browser_press_key` | Press special keys (`Enter`, `Tab`, `Escape`, `Backspace`, `ArrowDown`, `ArrowUp`) |
| | `browser_scroll` | Scroll page vertically (`deltaY`) or horizontally (`deltaX`) |
| **DOM & Output** | `browser_get_a11y_tree` | Get semantic Accessibility Tree snapshot with `refId` |
| | `browser_evaluate_script` | Execute custom JS snippet on web context via CDP Runtime |
| | `browser_screenshot` | Capture tab screenshot (supports `fullPage: true`) |
| | `browser_print_to_pdf` | Print web page to PDF base64 document |
| | `browser_get_cookies` | Get session cookies for active domain |

---

<div align="center">
  <h2>👤 Author & License</h2>

  Developed by <b><a href="https://irnk.codes">Eliyanto Sarage</a></b> (<a href="mailto:officialelsa21@gmail.com">officialelsa21@gmail.com</a>)

  Released under the <b><a href="LICENSE">MIT License</a></b>.
</div>