🌐 HTML Element Reader & Controller (Chrome Extension & MCP Server)

A powerful Chrome Extension & Model Context Protocol (MCP) server that empowers AI assistants (Claude, Antigravity, Gemini, GPT) to read, inspect, navigate, and control Google Chrome with human-like interactions and real-time DOM overlay visualization.

🌟 Key Features

• 🤖 17 Complete MCP Tools: Control Chrome browser tabs, mouse actions, keyboard events, form typing, full-page content reading, and semantic element searching over JSON-RPC.
• ⚡ Single-Turn Auto-Inspection (returnState): Action tools (click_element, type_text, navigate_browser, etc.) execute the action, automatically wait for page navigation/reloads, and return updated browser status + scanned elements in a single tool call.
• 🧠 LLM Context-Length Optimized: Pruned pixel rect clutter by default (~60% token savings), configurable scan limit, and category filters (interactive, forms, text, images, custom).
• 🏷️ On-Page Visual Badging: Displays floating numbered badges on interactive DOM elements with interactive tooltips and click animations.
• ⌨️ Synthesized Keyboard Controls (press_key): Dispatches natural keydown, keypress, and keyup events for key combos (Enter, Escape, Tab, Space, ArrowDown, Backspace, form submit).
• 🗂️ Multi-Tab Management: Query, open, switch, and close browser tabs across window focus shifts.
• 🛡️ Resilient CSS Selectors: Generates stable selectors prioritizing data-testid, aria-label, name, placeholder, id, and class combinations.

🛠️ MCP Tool Suite (17 Tools)

| Tool Name | Category | Description | | :--- | :---: | :--- | | get_browser_status | Core | Returns active tab title, URL, connection state & port. | | list_elements | DOM | Scans DOM with category filters (interactive, forms, text, images, custom), limit, & pruned context options. | | click_element | Action | Mouse click + single-turn auto-inspection (returnState) + page load sync. | | double_click_element | Action | Double-click mouse sequence with auto-inspection. | | right_click_element | Action | Right-click / context menu sequence with auto-inspection. | | type_text | Action | Type text into inputs, textareas, selects, and contenteditable elements. | | hover_element | Action | Dispatch hover/mouseenter/pointerover events. | | scroll_to_element | Action | Smoothly scrolls target element into viewport center. | | drag_element | Action | Simulates mouse drag with horizontal/vertical offsets (deltaX, deltaY). | | navigate_browser | Nav | Browser back, forward, reload, or goto with auto-inferred actions. | | press_key | Action | Synthesizes keyboard key presses (Enter, Escape, Tab, Space, ArrowDown, etc.). | | get_page_content | Content | Extracts structured full text/markdown of active page in 1 call. | | find_element | Search | Searches DOM elements containing specific text queries (e.g., "Sign In"). | | list_tabs | Tab | Lists all open Chrome browser tabs, titles, URLs, and active focus status. | | switch_tab | Tab | Switches extension and window focus to a target tab by tabId. | | new_tab | Tab | Opens a new Chrome tab at a specified URL. | | close_tab | Tab | Closes a specified Chrome tab by tabId. |

🚀 Getting Started

1. Install Chrome Extension

1. Open Google Chrome and go to chrome://extensions.
2. Enable Developer mode (top-right toggle).
3. Click Load unpacked and select the project directory: d:\DEV\Chrome_extention.
4. Pin the extension icon to your toolbar.

2. Run Local API Server

Start the REST API and WebSocket bridge server on port 8765:

node server.js 8765

2. Register MCP Server via npx (Recommended)

Add the server configuration to your MCP config file (e.g., mcp_config.json or Claude Desktop config):

{
  "mcpServers": {
    "chrome-element-controller": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-element-controller"
      ]
    }
  }
}

3. Alternative: Run via Local Node.js Path

{
  "mcpServers": {
    "chrome-element-controller": {
      "command": "node",
      "args": [
        "d:/DEV/Chrome_extention/cli.js"
      ]
    }
  }
}

🏗️ Project Architecture

Chrome_extention/
├── background.js              # Service worker & keep-alive alarm
├── content.js                 # Content script entry point & runtime listener
├── content.css                # Visual badge styling & target flash animations
├── manifest.json              # Extension Manifest V3 configuration
├── mcp-server.js              # Standalone Node.js MCP server entry point
├── server.js                  # Standalone Local REST API server entry point
└── src/
    ├── background/
    │   ├── tab-manager.js     # Multi-tab resolution, switching, and script injection
    │   └── websocket-client.js# Auto-reconnecting WebSocket client
    ├── content/
    │   ├── action-engine.js   # Human action synthesis (clicks, keys, drags, typing)
    │   ├── dom-scanner.js     # Fast DOM querying & content extraction
    │   ├── overlay-manager.js # Floating badge overlay & animation manager
    │   └── selector-builder.js# Resilient CSS selector generator
    ├── mcp/
    │   ├── index.js           # MCP server initialization
    │   ├── rpc-protocol.js    # JSON-RPC stdio protocol parser
    │   ├── tool-definitions.js# 17 MCP tool schemas & parameter specifications
    │   └── tool-handlers.js   # MCP tool execution handlers
    ├── popup/                 # Extension popup interface
    └── server/
        ├── index.js           # HTTP REST & WebSocket bridge server
        ├── rest-router.js     # REST API route handlers
        └── ws-codec.js        # WebSocket frame encoder/decoder

💡 Usage Examples

Navigate Browser & Auto-Inspect

{
  "name": "navigate_browser",
  "arguments": {
    "url": "https://example.com"
  }
}

Single-Turn Click & Auto-Inspect

{
  "name": "click_element",
  "arguments": {
    "index": 1,
    "returnState": true
  }
}

Synthesize Key Press (Enter)

{
  "name": "press_key",
  "arguments": {
    "index": 2,
    "key": "Enter"
  }
}

Search Elements by Text Query

{
  "name": "find_element",
  "arguments": {
    "query": "Sign In"
  }
}

Extract Full Page Structured Text

{
  "name": "get_page_content",
  "arguments": {
    "maxLength": 3000
  }
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.