chrometools-mcp 2.5.0 → 3.1.2

package/README.md

@@ -8,16 +8,18 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
 - [Usage](#usage)
 - [AI Optimization Features](#ai-optimization-features) ⭐ **NEW**
 - [Scenario Recorder](#scenario-recorder) ⭐ **NEW** - Visual UI-based recording with smart optimization
-- [Available Tools](#available-tools) - **44+ Tools Total**
-  - [AI-Powered Tools](#ai-powered-tools) ⭐ **NEW** - smartFindElement, analyzePage, getAllInteractiveElements, findElementsByText
+- [Available Tools](#available-tools) - **46+ Tools Total**
+  - [AI-Powered Tools](#ai-powered-tools) ⭐ **NEW** - smartFindElement, analyzePage, getElementByApomId, getAllInteractiveElements, findElementsByText
   - [Core Tools](#1-core-tools) - ping, openBrowser
-  - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo, selectOption, dragScroll, scrollHorizontal
+  - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo, selectOption, selectFromGroup, drag, scrollHorizontal
   - [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
-  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
+  - [Tab Management Tools](#5-tab-management-tools) ⭐ **NEW** - listTabs, switchTab
+  - [Recorder Tools](#7-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
+- [Multi-Instance Support](#multi-instance-support) ⭐ **NEW** - Run multiple MCP servers simultaneously
 - [WSL Setup Guide](#wsl-setup-guide) → [Full WSL Guide](WSL_SETUP.md)
 - [Development](#development)
 - [Features](#features)
@@ -185,24 +187,81 @@ Get current page state and structure. Returns complete map of forms (with values
 - **Parameters**:
   - `refresh` (optional): Force refresh cache to get CURRENT state after changes (default: false)
   - `includeAll` (optional): Include ALL page elements, not just interactive ones (default: false). Useful for layout work - find any element, get its selector, then use `getComputedCss` or `setStyles` on it.
+  - `useLegacyFormat` (optional): Return legacy format instead of APOM (default: false - **APOM is now the default**) 🔄 **BREAKING CHANGE**
+  - `registerElements` (optional): Auto-register elements for ID-based usage (default: true) ⭐ **APOM**
+  - `groupBy` (optional): 'type' or 'flat' - how to group elements (default: 'type') ⭐ **APOM**
 - **Why better than screenshot**:
   - Shows actual data (form values, validation errors) not just visual
   - Uses 2-5k tokens vs screenshot 15-25k tokens
-  - Returns structured data with selectors
+  - Returns structured data with **unique element IDs** for easy interaction
+  - **Detects UI frameworks** (MUI, Ant Design, Chakra, Bootstrap, Vuetify, Semantic UI) ⭐
+  - **Extracts dropdown options** from both native `<select>` and custom UI components ⭐
 - **Returns**:
-  - By default: Complete map of forms (with current values), inputs, buttons, links, navigation with selectors
-  - With `includeAll: true`: Also includes `allElements` array with ALL visible page elements (divs, spans, headings, etc.) - each with selector, tag, text, classes, id
+  - **APOM format** (default): Tree-structured Page Object Model with unique IDs ⭐ **NOW DEFAULT**
+    - `tree` - Hierarchical tree of page elements (optimized: ~82% smaller than flat format)
+      - Each node: `{ tag, id?, type?, sel, ch?, bounds?, meta? }`
+      - Interactive elements have `bounds` and full metadata
+      - Parent containers have minimal info (position only)
+    - `groups` - Radio/checkbox groups with options (name, value, label, checked state)
+    - `meta` - Page metadata (url, title, timestamp, element counts)
+    - Elements automatically registered - use IDs with `click({ id: "..." })`, `type({ id: "..." })`, etc.
+    - **Token-optimized**: Minified JSON, simplified parents, no redundant data
+    - Example: `analyzePage()` returns APOM, then use `click({ id: "button_45" })` or `type({ id: "input_20", text: "..." })`
+  - **Use `getElementByApomId({ id: "input_20" })`** to get full details for any element
+  - **Legacy format** (`useLegacyFormat: true`): Classic format for backward compatibility
+    - Complete map of forms (with current values), inputs, buttons, links, navigation with selectors
+    - **Each element includes `uiFramework` info** (name, version, component type) ⭐
+    - **Select elements include `options` array** with value, text, index, selected, disabled, group ⭐
+    - With `includeAll: true`: Also includes `allElements` array with ALL visible page elements (divs, spans, headings, etc.) - each with selector, tag, text, classes, id
 - **Example workflow**:
   1. `openBrowser({ url: "..." })`
-  2. `analyzePage()` ← Initial analysis
-  3. `click({ selector: "submit-btn" })`
-  4. **`analyzePage({ refresh: true })`** ← See what changed after click!
+  2. `analyzePage()` ← Initial analysis, returns elements with IDs
+  3. `type({ id: "input_20", text: "user@example.com" })` ← Use APOM ID
+  4. `click({ id: "button_45" })` ← Use APOM ID
+  5. **`analyzePage({ refresh: true })`** ← See what changed after click!
 - **Layout work example**:
   1. `analyzePage({ includeAll: true })` ← Get all elements
   2. Find element you want to style (e.g., `div.header`)
   3. `getComputedCss({ selector: "div.header" })` ← Get current styles
   4. `setStyles({ selector: "div.header", styles: [...] })` ← Apply new styles
 
+#### getElementByApomId ⭐ **NEW**
+Get detailed information about a specific element by its APOM ID from `analyzePage`. Use this to inspect elements without re-analyzing the entire page.
+- **Parameters**:
+  - `id` (required): APOM element ID (e.g., `"input_20"`, `"button_45"`)
+- **Use case**: Get full details for a specific element (bounds, attributes, computed styles)
+- **Returns**: Element details including:
+  - `id`: Element APOM ID
+  - `selector`: CSS selector
+  - `tag`: HTML tag name
+  - `type`: Input type (for inputs)
+  - `text`: Visible text content
+  - `bounds`: `{ x, y, width, height }` position and size
+  - `attributes`: All HTML attributes
+  - `computedStyles`: Key CSS properties (display, visibility, color, background, etc.)
+  - `isVisible`: Whether element is visible
+  - `isEnabled`: Whether element is enabled (not disabled)
+- **Example**:
+  ```javascript
+  // Get details for specific input field
+  getElementByApomId({ id: "input_20" })
+
+  // Returns:
+  {
+    "success": true,
+    "id": "input_20",
+    "selector": "input[name='email']",
+    "tag": "input",
+    "type": "email",
+    "text": "",
+    "bounds": { "x": 100, "y": 200, "width": 300, "height": 40 },
+    "attributes": { "name": "email", "placeholder": "Enter email" },
+    "computedStyles": { "display": "block", "visibility": "visible" },
+    "isVisible": true,
+    "isEnabled": true
+  }
+  ```
+
 #### getAllInteractiveElements
 Get all clickable/fillable elements with their selectors.
 - **Parameters**:
@@ -234,25 +293,45 @@ Opens browser and navigates to URL. Browser stays open for further interactions.
 ### 2. Interaction Tools
 
 #### click
-Click an element with optional result screenshot.
+Click an element with optional result screenshot. **PREFERRED**: Use APOM ID from `analyzePage` for reliable targeting.
 - **Parameters**:
-  - `selector` (required): CSS selector
+  - `id` (optional): APOM element ID from analyzePage (e.g., `"button_45"`, `"link_7"`). **Preferred over selector.**
+  - `selector` (optional): CSS selector. Use when APOM ID is not available.
+  - ⚠️ Either `id` OR `selector` required (mutually exclusive)
   - `waitAfter` (optional): Wait time in ms (default: 1500)
   - `screenshot` (optional): Capture screenshot (default: false for performance) ⚡
   - `timeout` (optional): Max operation time in ms (default: 30000)
 - **Use case**: Buttons, links, form submissions
 - **Returns**: Confirmation text + optional screenshot
 - **Performance**: 2-10x faster without screenshot
+- **Example**:
+  ```javascript
+  // PREFERRED: Using APOM ID
+  click({ id: "button_45" })
+
+  // Alternative: Using CSS selector
+  click({ selector: "button[type='submit']" })
+  ```
 
 #### type
-Type text into input fields with optional clearing and typing delay.
+Type text into input fields with optional clearing and typing delay. **PREFERRED**: Use APOM ID from `analyzePage` for reliable targeting.
 - **Parameters**:
-  - `selector` (required): CSS selector
+  - `id` (optional): APOM element ID from analyzePage (e.g., `"input_20"`). **Preferred over selector.**
+  - `selector` (optional): CSS selector. Use when APOM ID is not available.
+  - ⚠️ Either `id` OR `selector` required (mutually exclusive)
   - `text` (required): Text to type
   - `delay` (optional): Delay between keystrokes in ms
   - `clearFirst` (optional): Clear field first (default: true)
 - **Use case**: Filling forms, search boxes, text inputs
 - **Returns**: Confirmation text
+- **Example**:
+  ```javascript
+  // PREFERRED: Using APOM ID
+  type({ id: "input_20", text: "user@example.com" })
+
+  // Alternative: Using CSS selector
+  type({ selector: "input[name='email']", text: "user@example.com" })
+  ```
 
 #### scrollTo
 Scroll page to bring element into view.
@@ -263,9 +342,11 @@ Scroll page to bring element into view.
 - **Returns**: Final scroll position
 
 #### selectOption
-Select option in dropdown (HTML select elements). Automatically detected by analyzePage with all available options.
+Select option in dropdown (HTML select elements). **PREFERRED**: Use APOM ID from `analyzePage` for reliable targeting.
 - **Parameters**:
-  - `selector` (required): CSS selector for select element
+  - `id` (optional): APOM element ID from analyzePage (e.g., `"select_5"`). **Preferred over selector.**
+  - `selector` (optional): CSS selector. Use when APOM ID is not available.
+  - ⚠️ Either `id` OR `selector` required (mutually exclusive)
   - `value` (optional): Option value attribute (priority 1)
   - `text` (optional): Option text content (priority 2)
   - `index` (optional): Option index, 0-based (priority 3)
@@ -273,6 +354,46 @@ Select option in dropdown (HTML select elements). Automatically detected by anal
 - **Returns**: Selected option details (value, text, index)
 - **Selection priority**: If multiple parameters specified, tries value → text → index
 - **AI Integration**: Use `analyzePage` to see all available options with their values, text, and indices
+- **Example**:
+  ```javascript
+  // PREFERRED: Using APOM ID
+  selectOption({ id: "select_5", value: "US" })
+
+  // Alternative: Using CSS selector
+  selectOption({ selector: "select[name='country']", text: "United States" })
+  ```
+
+#### selectFromGroup ⭐ **NEW**
+Select option(s) from radio or checkbox group by name attribute. Works at abstract group level instead of individual clicks.
+- **Parameters**:
+  - `name` (required): Name attribute of the radio/checkbox group (e.g., 'size', 'toppings')
+  - `value` (optional): Single value to select (for radio or single checkbox)
+  - `values` (optional): Array of values to select (for checkbox group)
+  - `text` (optional): Label text to match (alternative to value)
+  - `texts` (optional): Array of label texts to match (for checkbox group)
+  - `by` (optional): Match by 'value', 'text', or 'auto' (default: 'auto')
+  - `mode` (optional): For checkboxes - 'set' (replace all), 'add', 'remove', 'toggle' (default: 'set')
+- **Use case**: Radio buttons, checkbox groups, form options
+- **Returns**: Result with changes made and current selection state
+- **AI Integration**: Use `analyzePage` to see available groups in `groups` section with all options and labels
+- **Examples**:
+  ```javascript
+  // Radio group - select single option
+  selectFromGroup({ name: "size", value: "large" })
+  selectFromGroup({ name: "size", text: "Extra Large" })
+
+  // Checkbox group - set specific values (uncheck others)
+  selectFromGroup({ name: "toppings", values: ["cheese", "bacon"] })
+
+  // Checkbox group - add to existing selection
+  selectFromGroup({ name: "toppings", values: ["mushrooms"], mode: "add" })
+
+  // Checkbox group - remove specific values
+  selectFromGroup({ name: "toppings", values: ["onions"], mode: "remove" })
+
+  // Checkbox group - toggle values
+  selectFromGroup({ name: "toppings", texts: ["Extra Cheese"], mode: "toggle" })
+  ```
 
 #### drag
 Drag element by mouse (click-hold-move-release). Simulates real mouse drag, not scrollbar scrolling.
@@ -419,10 +540,21 @@ Filter requests by URL pattern with full details.
 3. `filterNetworkRequests({ urlPattern: "api/..." })` - get all matching requests with details
 
 #### hover
-Simulate mouse hover over element.
-- **Parameters**: `selector` (required)
+Simulate mouse hover over element. **PREFERRED**: Use APOM ID from `analyzePage` for reliable targeting.
+- **Parameters**:
+  - `id` (optional): APOM element ID from analyzePage (e.g., `"button_10"`). **Preferred over selector.**
+  - `selector` (optional): CSS selector. Use when APOM ID is not available.
+  - ⚠️ Either `id` OR `selector` required (mutually exclusive)
 - **Use case**: Testing hover effects, tooltips, dropdown menus
 - **Returns**: Confirmation text
+- **Example**:
+  ```javascript
+  // PREFERRED: Using APOM ID
+  hover({ id: "button_10" })
+
+  // Alternative: Using CSS selector
+  hover({ selector: ".dropdown-trigger" })
+  ```
 
 #### setStyles
 Apply inline CSS styles to element for live editing.
@@ -455,7 +587,49 @@ Navigate to different URL while keeping browser instance.
 - **Use case**: Moving between pages in workflow
 - **Returns**: New page title
 
-### 5. Figma Tools ⭐ ENHANCED
+### 5. Tab Management Tools ⭐ NEW
+
+Tools for managing multiple browser tabs. New tabs opened via `window.open()`, `target="_blank"`, or user actions are automatically detected and tracked.
+
+#### listTabs
+List all open browser tabs with their URLs, titles, and active status.
+- **Parameters**: None
+- **Returns**:
+  - `tabs`: Array of `{ index, url, title, isActive }`
+  - `totalCount`: Number of open tabs
+  - `newTabsDetected` (optional): Array of tabs opened since last check
+- **Use case**: See all open tabs, check for newly opened tabs
+
+```javascript
+// Example response
+{
+  "tabs": [
+    { "index": 0, "url": "https://example.com", "title": "Example", "isActive": false },
+    { "index": 1, "url": "https://google.com", "title": "Google", "isActive": true }
+  ],
+  "totalCount": 2,
+  "newTabsDetected": [
+    { "timestamp": "2026-01-25T...", "url": "https://google.com", "openerUrl": "https://example.com" }
+  ]
+}
+```
+
+#### switchTab
+Switch to a different browser tab by index or URL pattern.
+- **Parameters**:
+  - `tab` (required): Tab index (number, 0-based) or URL pattern (string, partial match)
+- **Use case**: Switch between tabs for multi-tab workflows
+- **Returns**: `{ success, switchedTo: { url, title } }`
+
+```javascript
+// Switch by index
+switchTab({ tab: 0 })
+
+// Switch by URL pattern
+switchTab({ tab: "google.com" })
+```
+
+### 6. Figma Tools ⭐ ENHANCED
 
 Design-to-code validation, file browsing, design system extraction, and comparison tools with automatic 3 MB compression.
 
@@ -601,7 +775,7 @@ Extract detailed design specifications from Figma including text content, colors
   - **Dimensions**: Width, height, x, y coordinates
   - **Children**: Recursive tree with text extraction from all child elements
 
-### 6. Recorder Tools ⭐ NEW
+### 7. Recorder Tools ⭐ NEW
 
 **URL-Based Storage (v2.1+)**: Scenarios are automatically organized by website domain in `~/.config/chrometools-mcp/projects/{domain}/scenarios/`.
 
@@ -970,18 +1144,29 @@ Generate Page Object Model (POM) class from current page structure. Analyzes pag
 // 1. Open page
 openBrowser({ url: "https://example.com/form" })
 
-// 2. Fill form
-type({ selector: "input[name='email']", text: "user@example.com" })
-type({ selector: "input[name='password']", text: "secret123" })
+// 2. Analyze page to get element IDs
+analyzePage()
+// Returns: { tree: {...}, groups: {...}, meta: {...} }
+// Elements: input_20 (email), input_21 (password), button_45 (submit)
 
-// 3. Submit
-click({ selector: "button[type='submit']" })
+// 3. Fill form using APOM IDs (preferred)
+type({ id: "input_20", text: "user@example.com" })
+type({ id: "input_21", text: "secret123" })
+
+// 4. Submit using APOM ID
+click({ id: "button_45" })
 
-// 4. Verify
-getElement({ selector: ".success-message" })
+// 5. Verify
+analyzePage({ refresh: true })  // See updated state
 screenshot({ selector: ".dashboard", padding: 20 })
 ```
 
+**Alternative: Using CSS selectors (still supported)**
+```javascript
+type({ selector: "input[name='email']", text: "user@example.com" })
+click({ selector: "button[type='submit']" })
+```
+
 ---
 
 ## Tool Usage Tips
@@ -1250,17 +1435,29 @@ npx @modelcontextprotocol/inspector node index.js
 
 ## Features
 
-- **27+ Powerful Tools**: Complete toolkit for browser automation
+- **44+ Powerful Tools**: Complete toolkit for browser automation
   - Core: ping, openBrowser
-  - Interaction: click, type, scrollTo
-  - Inspection: getElement, getComputedCss, getBoxModel, screenshot
-  - Advanced: executeScript, getConsoleLogs, getNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
-  - AI-Powered: smartFindElement, analyzePage, getAllInteractiveElements, findElementsByText
-  - Recorder: enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario
-  - Figma: getFigmaFrame, compareFigmaToElement, getFigmaSpecs
+  - Interaction: click, type, scrollTo, selectOption, selectFromGroup, drag, scrollHorizontal
+  - Inspection: getElement, getComputedCss, getBoxModel, screenshot, saveScreenshot
+  - Advanced: executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo, waitForElement
+  - AI-Powered: smartFindElement, analyzePage, getElementByApomId, getAllInteractiveElements, findElementsByText ⭐ **NEW**
+  - Recorder: enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
+  - Figma: getFigmaFrame, compareFigmaToElement, getFigmaSpecs, parseFigmaUrl, listFigmaPages, searchFigmaFrames, getFigmaComponents, getFigmaStyles, getFigmaColorPalette, convertFigmaToCode
+- **UI Framework Detection**: Automatic detection of MUI, Ant Design, Chakra UI, Bootstrap, Vuetify, Semantic UI ⭐ **NEW**
+- **Smart Dropdown Handling**: Extracts options from both native `<select>` and custom UI framework components ⭐ **NEW**
+- **APOM (Agent Page Object Model)**: Automatic element ID assignment for reliable interaction ⭐ **NEW**
+  - `analyzePage()` returns elements with unique IDs (e.g., `input_20`, `button_45`)
+  - Use `id` parameter in click/type/hover/selectOption for stable targeting
+  - Use `getElementByApomId()` to get detailed element info
 - **Console Log Capture**: Automatic JavaScript console monitoring
 - **Network Request Monitoring**: Track all HTTP/API requests (XHR, Fetch, etc.)
 - **Persistent Browser Sessions**: Browser tabs remain open between requests
+- **Multi-Instance Support**: Run multiple MCP servers simultaneously with automatic discovery ⭐ **NEW**
+  - Dynamic port allocation (9223-9227)
+  - Chrome Extension port scanning every 20s
+  - Broadcast pattern for parallel AI clients
+  - Graceful handling of ungraceful shutdowns
+- **Auto-Sync Active Tab**: MCP server automatically syncs to user's currently active tab ⭐ **NEW**
 - **Visual Browser (GUI Mode)**: See automation in real-time
 - **Cross-platform**: Works on Windows/WSL, Linux, macOS
 - **Simple Installation**: One command with npx
@@ -1268,9 +1465,180 @@ npx @modelcontextprotocol/inspector node index.js
 - **AI-Friendly**: Detailed descriptions optimized for AI agents
 - **Responsive Testing**: Built-in viewport control for mobile/tablet/desktop
 
+## Multi-Instance Support
+
+⭐ **NEW**: Run up to 8 MCP servers simultaneously, connecting/disconnecting at any time without coordination.
+
+### Overview
+
+ChromeTools MCP uses a **Bridge Architecture** for reliable multi-instance support:
+
+- **Multiple AI clients** (0-8) can connect/disconnect at any time
+- **No scanning delays** — instant connection to persistent Bridge Service
+- **Resilient** — Bridge survives MCP process crashes, maintains state
+- **Chrome lifecycle** — Bridge starts/stops with Chrome Extension
+
+### How It Works
+
+```
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│ Claude Desktop  │  │ Telegram Bot    │  │ Custom Script   │
+│   MCP Client    │  │   MCP Client    │  │   MCP Client    │
+└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
+         │                    │                    │
+         │    WebSocket       │    WebSocket       │    WebSocket
+         │    (client)        │    (client)        │    (client)
+         │                    │                    │
+         └────────────────────┼────────────────────┘
+                              │
+                              ↓
+              ┌───────────────────────────────┐
+              │      Bridge Service (:9223)   │
+              │   (Native Messaging Host)     │
+              │                               │
+              │  • Stores tabs state          │
+              │  • Stores recordings          │
+              │  • Broadcasts events          │
+              │  • Accepts 0-8 clients        │
+              └───────────────┬───────────────┘
+                              │
+                              │ Native Messaging (stdio)
+                              │
+              ┌───────────────┴───────────────┐
+              │      Chrome Extension         │
+              │   (Event Producer)            │
+              │                               │
+              │  • Tracks all tabs            │
+              │  • Records user actions       │
+              │  • Sends events to Bridge     │
+              └───────────────┬───────────────┘
+                              │
+                              ↓
+              ┌───────────────────────────────┐
+              │        Chrome Browser         │
+              └───────────────────────────────┘
+```
+
+### Installation
+
+**One-time setup** (installs Native Messaging Bridge):
+
+```bash
+npx chrometools-mcp --install-bridge
+```
+
+This:
+1. Creates Bridge Service files in `~/.chrometools/`
+2. Registers Native Messaging Host in system (Windows Registry / Chrome config)
+3. Bridge will auto-start when Chrome Extension loads
+
+**Verify installation:**
+```bash
+npx chrometools-mcp --check-bridge
+```
+
+### Architecture
+
+**1. Bridge Service (Persistent Intermediary)**
+- Launched by Chrome via Native Messaging when Extension starts
+- Runs WebSocket server on port 9223
+- Stores state: tabs, recordings, recorder state
+- Lives as long as Chrome is running
+- Accepts 0-8 simultaneous MCP clients
+
+**2. Chrome Extension (Event Producer)**
+- Tracks all browser tabs (created, updated, closed, activated)
+- Records user actions (clicks, typing, navigation)
+- Sends ALL events to Bridge via Native Messaging
+- Doesn't care about MCP clients — just produces events
+
+**3. MCP Server (Event Consumer)**
+- Connects to Bridge as WebSocket client
+- Receives full state immediately on connect
+- Gets real-time event updates
+- Can disconnect/reconnect at any time without losing state
+
+### Use Cases
+
+**Ephemeral AI Sessions**
+```bash
+# User sends message to Telegram bot
+# → Claude Code starts, connects to Bridge
+# → Gets current tabs state instantly
+# → Performs automation
+# → Claude Code exits, disconnects
+# → Bridge keeps running, state preserved
+
+# Next message: same flow, instant state access
+```
+
+**Parallel Workflows**
+```bash
+# Claude Desktop: form automation
+# Telegram Bot: monitoring & debugging
+# Custom script: data extraction
+
+# All connected to same Bridge
+# All see same browser state
+# All can control Chrome
+```
+
+### Configuration
+
+No configuration needed after installation. Just use:
+
+```bash
+npx chrometools-mcp
+```
+
+MCP automatically connects to Bridge on startup.
+
+### CLI Options
+
+```bash
+npx chrometools-mcp --install-bridge    # Install Native Messaging Bridge
+npx chrometools-mcp --uninstall-bridge  # Uninstall Bridge
+npx chrometools-mcp --check-bridge      # Check if Bridge is installed
+npx chrometools-mcp --help              # Show help
+```
+
+### Technical Details
+
+| Component | Technology | Port |
+|-----------|------------|------|
+| Bridge Service | Node.js + WebSocket Server | 9223 |
+| Extension ↔ Bridge | Native Messaging (stdio) | — |
+| MCP ↔ Bridge | WebSocket (client) | 9223 |
+
+**Max Clients:** 8 simultaneous MCP connections
+
+**State on Connect:** Full state (tabs, recordings, recorder state) sent immediately
+
+**Extension ID:** `dmehkibmncgphijnigkahhlekgajhpbl` (stable, generated from key)
+
+### Troubleshooting
+
+**Bridge not connecting:**
+```bash
+# Check if Bridge is installed
+npx chrometools-mcp --check-bridge
+
+# Reinstall if needed
+npx chrometools-mcp --install-bridge
+
+# Reload extension in chrome://extensions
+```
+
+**Extension shows "Disconnected":**
+- Bridge only runs when Chrome Extension is active
+- Close and reopen Chrome
+- Check Extension Service Worker console for errors
+
 ## Architecture
 
-- Uses Puppeteer for Chrome automation
-- MCP Server SDK for protocol implementation
-- Zod for schema validation
-- Stdio transport for communication
+- **Puppeteer** for Chrome automation
+- **MCP Server SDK** for protocol implementation
+- **Native Messaging Bridge** for persistent Extension ↔ MCP communication
+- **WebSocket** for multi-client support (Bridge as server, MCP as clients)
+- **Zod** for schema validation
+- **Stdio transport** for MCP communication