chrome-ai-bridge 1.0.20 → 2.0.3

package/README.md

@@ -3,9 +3,9 @@
 [![npm](https://img.shields.io/npm/v/chrome-ai-bridge.svg)](https://npmjs.org/package/chrome-ai-bridge)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
-> Bridge between AI and Chrome Browser
+> Bridge between AI coding assistants and ChatGPT/Gemini via Chrome Extension
 
-MCP server enabling AI assistants to control Chrome, consult other AIs, and develop extensions.
+MCP server that enables AI assistants to consult ChatGPT and Gemini through a Chrome extension.
 
 **Compatible with:** Claude Code, Cursor, VS Code Copilot, Cline, and other MCP clients
 
@@ -13,23 +13,30 @@ MCP server enabling AI assistants to control Chrome, consult other AIs, and deve
 
 ## What is this?
 
-chrome-ai-bridge is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants:
+chrome-ai-bridge is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants the ability to:
 
-- **Eyes**: See what's on web pages (screenshots, DOM snapshots)
-- **Hands**: Interact with pages (click, type, navigate)
-- **Voice**: Consult other AIs (ChatGPT, Gemini) via browser
+- **Consult other AIs**: Ask ChatGPT and Gemini questions via browser
+- **Get multiple perspectives**: Query both AIs in parallel for second opinions
+- **Debug connections**: Inspect page state via CDP snapshots
 
-Think of it as the bridge that connects your AI coding assistant to the browser world.
+> **v2.0.0 Breaking Change**: This version uses a Chrome extension for browser communication instead of Puppeteer. Previous CLI options (`--headless`, `--loadExtensionsDir`, etc.) are no longer supported.
 
 ---
 
 ## Quick Start
 
-### 1. Run the server
+### 1. Install the Chrome Extension
 
-```bash
-npx chrome-ai-bridge@latest
-```
+1. Download the latest release from [Releases](https://github.com/anthropics/anthropic-quickstarts/releases)
+2. Or build from source:
+   ```bash
+   git clone https://github.com/anthropics/anthropic-quickstarts.git
+   cd anthropic-quickstarts/mcp-devtools
+   npm install && npm run build
+   ```
+3. Open `chrome://extensions/` in Chrome
+4. Enable "Developer mode"
+5. Click "Load unpacked" and select `build/extension/`
 
 ### 2. Configure your MCP client
 
@@ -46,13 +53,19 @@ npx chrome-ai-bridge@latest
 }
 ```
 
-### 3. Verify it works
+### 3. Connect the Extension
+
+1. Open ChatGPT (https://chatgpt.com) or Gemini (https://gemini.google.com) in Chrome
+2. Log in to both services
+3. The extension will automatically connect when the MCP server starts
+
+### 4. Verify it works
 
-Restart your AI client and try: `"Take a screenshot of google.com"`
+Restart your AI client and try: `"Ask ChatGPT how to implement OAuth in Node.js"`
 
 ---
 
-## Key Features
+## Features
 
 ### Multi-AI Consultation
 
@@ -61,70 +74,52 @@ Ask ChatGPT or Gemini questions directly from your AI assistant:
 ```
 "Ask ChatGPT how to implement OAuth in Node.js"
 "Ask Gemini to review this architecture decision"
+"Ask both AIs for their opinions on this approach"
 ```
 
 | Feature | Description |
 |---------|-------------|
+| **Parallel queries** | Ask both AIs simultaneously with `ask_chatgpt_gemini_web` |
 | **Session persistence** | Conversations continue across tool calls |
-| **Auto-logging** | All Q&A saved to `docs/ask/chatgpt/` and `docs/ask/gemini/` |
-| **12 languages** | Login detection works in EN, JA, FR, DE, ES, IT, KO, ZH, PT, RU, AR |
+| **Auto-logging** | All Q&A saved to `.local/chrome-ai-bridge/history.jsonl` |
 
-### Browser Automation
+### Debugging Tools
 
-Full browser control with 20+ tools:
+Inspect the connection state and page content:
 
-| Category | Tools |
-|----------|-------|
-| **Snapshot** | `take_snapshot`, `take_screenshot` |
-| **Input** | `click`, `fill`, `fill_form`, `hover`, `drag`, `upload_file` |
-| **Navigation** | `navigate`, `pages`, `wait_for`, `handle_dialog` |
-| **Inspection** | `network`, `list_console_messages`, `evaluate_script` |
-| **Performance** | `performance` (start/stop/analyze traces) |
-| **Emulation** | `emulate` (CPU/network throttling), `resize_page` |
+| Tool | Description |
+|------|-------------|
+| `take_cdp_snapshot` | Get page state (URL, title, input/button status) |
+| `get_page_dom` | Query DOM elements with CSS selectors |
 
-### Chrome Extension Development
+---
 
-Build and debug Chrome extensions with AI assistance:
+## Tools Reference
 
-```json
-{
-  "args": ["chrome-ai-bridge@latest", "--loadExtensionsDir=/path/to/extensions"]
-}
-```
+### Available Tools (5)
 
 | Tool | Description |
 |------|-------------|
-| `extension_popup` | Open/close extension popups |
-| `iframe_popup` | Inspect, patch, reload iframe-embedded popups |
-| `bookmarks` | Quick access to chrome://extensions, Web Store dashboard |
+| `ask_chatgpt_web` | Ask ChatGPT via browser |
+| `ask_gemini_web` | Ask Gemini via browser |
+| `ask_chatgpt_gemini_web` | Ask both AIs in parallel (recommended) |
+| `take_cdp_snapshot` | Debug: Get CDP page state |
+| `get_page_dom` | Debug: Query DOM elements |
 
-### Plugin Architecture
+### Recommended Usage
 
-Extend with custom tools:
+For general queries, use `ask_chatgpt_gemini_web` to get multiple perspectives:
 
-```json
-{
-  "env": {
-    "MCP_PLUGINS": "./my-plugin.js,@org/another-plugin"
-  }
-}
 ```
+User: "Ask AI about React best practices"
+→ Claude uses ask_chatgpt_gemini_web (queries both in parallel)
+```
+
+Only use individual tools when explicitly requested:
 
-```typescript
-// my-plugin.js
-export default {
-  id: 'my-plugin',
-  name: 'My Plugin',
-  version: '1.0.0',
-  async register(ctx) {
-    ctx.registry.register({
-      name: 'my_tool',
-      description: 'Does something useful',
-      schema: { /* zod schema */ },
-      async handler(input, response, context) { /* ... */ },
-    });
-  },
-};
+```
+User: "Ask ChatGPT specifically about this"
+→ Claude uses ask_chatgpt_web
 ```
 
 ---
@@ -136,52 +131,6 @@ export default {
 | Variable | Description |
 |----------|-------------|
 | `MCP_DISABLE_WEB_LLM` | Set `true` to disable ChatGPT/Gemini tools |
-| `MCP_PLUGINS` | Comma-separated list of plugin paths |
-| `MCP_ENV` | Set `development` for hot-reload mode |
-
-### CLI Options
-
-| Option | Description |
-|--------|-------------|
-| `--loadExtensionsDir` | Load Chrome extensions from directory |
-| `--headless` | Run in headless mode |
-| `--channel` | Chrome channel (stable/canary) |
-
----
-
-## Tools Reference
-
-### Core Tools (18)
-
-| Tool | Description |
-|------|-------------|
-| `take_snapshot` | Get page structure with element UIDs |
-| `take_screenshot` | Capture page or element image |
-| `click` | Click element by UID |
-| `fill` | Fill input/textarea/select |
-| `fill_form` | Fill multiple form elements |
-| `hover` | Hover over element |
-| `drag` | Drag element to another |
-| `upload_file` | Upload file through input |
-| `navigate` | Go to URL, back, forward |
-| `pages` | List, select, close tabs |
-| `wait_for` | Wait for text to appear |
-| `handle_dialog` | Accept/dismiss dialogs |
-| `resize_page` | Change viewport size |
-| `emulate` | CPU/network throttling |
-| `network` | List/get network requests |
-| `performance` | Start/stop/analyze traces |
-| `evaluate_script` | Run JavaScript in page |
-| `list_console_messages` | Get console output |
-
-### Web-LLM Tools (2)
-
-| Tool | Description |
-|------|-------------|
-| `ask_chatgpt_web` | Ask ChatGPT via browser |
-| `ask_gemini_web` | Ask Gemini via browser |
-
-**Full documentation:** [docs/reference/tools.md](docs/reference/tools.md)
 
 ---
 
@@ -190,8 +139,8 @@ export default {
 ### Local Development
 
 ```bash
-git clone https://github.com/usedhonda/chrome-ai-bridge.git
-cd chrome-ai-bridge
+git clone https://github.com/anthropics/anthropic-quickstarts.git
+cd anthropic-quickstarts/mcp-devtools
 npm install && npm run build
 ```
 
@@ -208,23 +157,6 @@ Configure `~/.claude.json`:
 }
 ```
 
-### Hot-Reload Development
-
-```json
-{
-  "mcpServers": {
-    "chrome-ai-bridge": {
-      "command": "node",
-      "args": ["/path/to/chrome-ai-bridge/scripts/mcp-wrapper.mjs"],
-      "cwd": "/path/to/chrome-ai-bridge",
-      "env": { "MCP_ENV": "development" }
-    }
-  }
-}
-```
-
-Auto-rebuild on file changes with 2-5 second feedback loop.
-
 ### Commands
 
 ```bash
@@ -239,55 +171,95 @@ npm run format     # Format code
 ```
 chrome-ai-bridge/
 ├── src/
-│   ├── tools/           # MCP tool definitions
-│   ├── plugin-api.ts    # Plugin architecture
-│   ├── browser.ts       # Browser management
-│   └── main.ts          # Entry point
+│   ├── fast-cdp/        # CDP client and AI chat logic
+│   ├── extension/       # Chrome extension source
+│   ├── main.ts          # MCP server entry point
+│   └── index.ts         # Main exports
 ├── scripts/
-│   ├── cli.mjs          # Production entry
-│   └── mcp-wrapper.mjs  # Development wrapper
+│   └── cli.mjs          # CLI entry point
 └── docs/                # Documentation
 ```
 
+### Testing
+
+```bash
+# Test ChatGPT connection
+npm run test:chatgpt -- "TypeScript generics explanation"
+
+# Test Gemini connection
+npm run test:gemini -- "Python async file reading"
+
+# Test both
+npm run test:both
+
+# CDP snapshot for debugging
+npm run cdp:chatgpt
+npm run cdp:gemini
+```
+
 ---
 
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
+| [Technical Spec](docs/SPEC.md) | Detailed architecture and implementation |
 | [Setup Guide](docs/user/setup.md) | Detailed MCP configuration |
-| [Workflows](docs/user/workflows.md) | Common usage patterns |
 | [Troubleshooting](docs/user/troubleshooting.md) | Problem solving |
-| [Tools Reference](docs/reference/tools.md) | Full tool documentation |
-| [Hot-Reload Setup](docs/dev/hot-reload.md) | Developer workflow |
+| [Extension Bridge Design](docs/internal/design/extension-bridge.md) | Extension architecture |
 
 ---
 
 ## Troubleshooting
 
+### Extension not connecting
+
+1. Check that the extension is installed and enabled in `chrome://extensions/`
+2. Verify ChatGPT/Gemini tabs are open and logged in
+3. Check the extension popup for connection status
+
 ### MCP server not responding
 
 ```bash
 npx clear-npx-cache && npx chrome-ai-bridge@latest
 ```
 
-### Extension not loading
+### ChatGPT/Gemini not responding
 
-- Verify `manifest.json` exists at extension root
-- Use absolute paths in `--loadExtensionsDir`
+- Ensure you're logged in to both services
+- Try refreshing the ChatGPT/Gemini tab
+- Check for rate limiting or service issues
+
+**More:** [docs/user/troubleshooting.md](docs/user/troubleshooting.md)
 
-### ChatGPT/Gemini login issues
+---
 
-- Check browser window for login prompts
-- Login detection supports 12 languages
+## Architecture (v2.0.0)
 
-**More:** [docs/user/troubleshooting.md](docs/user/troubleshooting.md)
+```
+┌─────────────────┐         MCP         ┌──────────────────┐
+│  Claude Code    │ ◀──────────────────▶│   MCP Server     │
+│  (MCP Client)   │                     │  (Node.js)       │
+└─────────────────┘                     └────────┬─────────┘
+                                                 │
+                                                 ▼
+                                      ┌──────────────────┐
+                                      │ Chrome Extension │
+                                      │ (CDP via WebSocket)│
+                                      └────────┬─────────┘
+                                               │
+                               ┌───────────────┴───────────────┐
+                               ▼                               ▼
+                    ┌─────────────────┐             ┌─────────────────┐
+                    │  ChatGPT Tab    │             │  Gemini Tab     │
+                    └─────────────────┘             └─────────────────┘
+```
 
 ---
 
 ## Credits
 
-Built on [Chrome DevTools MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-devtools) by Google LLC, with extensions for multi-AI consultation and Chrome extension development.
+Originally forked from [Chrome DevTools MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-devtools) by Google LLC. This fork focuses on multi-AI consultation capabilities via Chrome extension.
 
 ---
 

package/build/src/McpResponse.js

@@ -1,60 +1,26 @@
-import { getDevelopmentExtensionPaths } from './browser.js';
-import { formatConsoleEvent } from './formatters/consoleFormatter.js';
-import { formatExtensionsPage } from './formatters/extensionsPageFormatter.js';
-import { getFormattedHeaderValue, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
-import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
-import { paginate } from './utils/pagination.js';
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
 export class McpResponse {
-    #includePages = false;
-    #includeSnapshot = false;
-    #attachedNetworkRequestUrl;
-    #includeConsoleData = false;
     #textResponseLines = [];
-    #formattedConsoleData;
     #images = [];
-    #networkRequestsOptions;
-    setIncludePages(value) {
-        this.#includePages = value;
+    // Stub methods for interface compatibility (not supported in extension mode)
+    setIncludePages(_value) {
+        // Not supported in extension-only mode
     }
-    setIncludeSnapshot(value) {
-        this.#includeSnapshot = value;
+    setIncludeSnapshot(_value) {
+        // Not supported in extension-only mode
     }
-    setIncludeNetworkRequests(value, options) {
-        if (!value) {
-            this.#networkRequestsOptions = undefined;
-            return;
-        }
-        this.#networkRequestsOptions = {
-            include: value,
-            pagination: options?.pageSize || options?.pageIdx
-                ? {
-                    pageSize: options.pageSize,
-                    pageIdx: options.pageIdx,
-                }
-                : undefined,
-            resourceTypes: options?.resourceTypes,
-        };
-    }
-    setIncludeConsoleData(value) {
-        this.#includeConsoleData = value;
-    }
-    attachNetworkRequest(url) {
-        this.#attachedNetworkRequestUrl = url;
-    }
-    get includePages() {
-        return this.#includePages;
-    }
-    get includeNetworkRequests() {
-        return this.#networkRequestsOptions?.include ?? false;
-    }
-    get includeConsoleData() {
-        return this.#includeConsoleData;
+    setIncludeNetworkRequests(_value, _options) {
+        // Not supported in extension-only mode
     }
-    get attachedNetworkRequestUrl() {
-        return this.#attachedNetworkRequestUrl;
+    setIncludeConsoleData(_value) {
+        // Not supported in extension-only mode
     }
-    get networkRequestsPageIdx() {
-        return this.#networkRequestsOptions?.pagination?.pageIdx;
+    attachNetworkRequest(_url) {
+        // Not supported in extension-only mode
     }
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
@@ -68,121 +34,14 @@ export class McpResponse {
     get images() {
         return this.#images;
     }
-    get includeSnapshot() {
-        return this.#includeSnapshot;
+    async handle(toolName, _context) {
+        return this.format(toolName);
     }
-    async handle(toolName, context) {
-        if (this.#includePages) {
-            await context.createPagesSnapshot();
-        }
-        if (this.#includeSnapshot) {
-            await context.createTextSnapshot();
-        }
-        let formattedConsoleMessages;
-        if (this.#includeConsoleData) {
-            const consoleMessages = context.getConsoleData();
-            if (consoleMessages) {
-                formattedConsoleMessages = await Promise.all(consoleMessages.map(message => formatConsoleEvent(message)));
-                this.#formattedConsoleData = formattedConsoleMessages;
-            }
-        }
-        return this.format(toolName, context);
-    }
-    format(toolName, context) {
+    format(toolName) {
         const response = [`# ${toolName} response`];
         for (const line of this.#textResponseLines) {
             response.push(line);
         }
-        const networkConditions = context.getNetworkConditions();
-        if (networkConditions) {
-            response.push(`## Network emulation`);
-            response.push(`Emulating: ${networkConditions}`);
-            response.push(`Navigation timeout set to ${context.getNavigationTimeout()} ms`);
-        }
-        const cpuThrottlingRate = context.getCpuThrottlingRate();
-        if (cpuThrottlingRate > 1) {
-            response.push(`## CPU emulation`);
-            response.push(`Emulating: ${cpuThrottlingRate}x slowdown`);
-        }
-        const dialog = context.getDialog();
-        if (dialog) {
-            response.push(`# Open dialog
-${dialog.type()}: ${dialog.message()} (default value: ${dialog.message()}).
-Call browser_handle_dialog to handle it before continuing.`);
-        }
-        if (this.#includePages) {
-            const parts = [`## Pages`];
-            let idx = 0;
-            for (const page of context.getPages()) {
-                parts.push(`${idx}: ${page.url()}${idx === context.getSelectedPageIdx() ? ' [selected]' : ''}`);
-                idx++;
-            }
-            response.push(...parts);
-        }
-        if (this.#includeSnapshot) {
-            const snapshot = context.getTextSnapshot();
-            if (snapshot) {
-                const pageUrl = context.getSelectedPage().url();
-                const isExtensionsPage = pageUrl.startsWith('chrome://extensions');
-                let formattedSnapshot;
-                if (isExtensionsPage) {
-                    // Use structured extensions page formatter
-                    const developmentPaths = getDevelopmentExtensionPaths();
-                    formattedSnapshot = formatExtensionsPage(snapshot.root, developmentPaths);
-                    response.push(formattedSnapshot);
-                }
-                else {
-                    // Use standard accessibility tree formatter
-                    formattedSnapshot = formatA11ySnapshot(snapshot.root);
-                    response.push('## Page content');
-                    response.push(formattedSnapshot);
-                }
-            }
-        }
-        response.push(...this.#getIncludeNetworkRequestsData(context));
-        if (this.#networkRequestsOptions?.include) {
-            let requests = context.getNetworkRequests();
-            // Apply resource type filtering if specified
-            if (this.#networkRequestsOptions.resourceTypes?.length) {
-                const normalizedTypes = new Set(this.#networkRequestsOptions.resourceTypes);
-                requests = requests.filter(request => {
-                    const type = request.resourceType();
-                    return normalizedTypes.has(type);
-                });
-            }
-            response.push('## Network requests');
-            if (requests.length) {
-                const paginationResult = paginate(requests, this.#networkRequestsOptions.pagination);
-                if (paginationResult.invalidPage) {
-                    response.push('Invalid page number provided. Showing first page.');
-                }
-                const { startIndex, endIndex, currentPage, totalPages } = paginationResult;
-                response.push(`Showing ${startIndex + 1}-${endIndex} of ${requests.length} (Page ${currentPage + 1} of ${totalPages}).`);
-                if (this.#networkRequestsOptions.pagination) {
-                    if (paginationResult.hasNextPage) {
-                        response.push(`Next page: ${currentPage + 1}`);
-                    }
-                    if (paginationResult.hasPreviousPage) {
-                        response.push(`Previous page: ${currentPage - 1}`);
-                    }
-                }
-                for (const request of paginationResult.items) {
-                    response.push(getShortDescriptionForRequest(request));
-                }
-            }
-            else {
-                response.push('No requests found.');
-            }
-        }
-        if (this.#includeConsoleData && this.#formattedConsoleData) {
-            response.push('## Console messages');
-            if (this.#formattedConsoleData.length) {
-                response.push(...this.#formattedConsoleData);
-            }
-            else {
-                response.push('<no console messages found>');
-            }
-        }
         const text = {
             type: 'text',
             text: response.join('\n'),
@@ -195,42 +54,6 @@ Call browser_handle_dialog to handle it before continuing.`);
         });
         return [text, ...images];
     }
-    #getIncludeNetworkRequestsData(context) {
-        const response = [];
-        const url = this.#attachedNetworkRequestUrl;
-        if (!url) {
-            return response;
-        }
-        const httpRequest = context.getNetworkRequestByUrl(url);
-        response.push(`## Request ${httpRequest.url()}`);
-        response.push(`Status:  ${getStatusFromRequest(httpRequest)}`);
-        response.push(`### Request Headers`);
-        for (const line of getFormattedHeaderValue(httpRequest.headers())) {
-            response.push(line);
-        }
-        const httpResponse = httpRequest.response();
-        if (httpResponse) {
-            response.push(`### Response Headers`);
-            for (const line of getFormattedHeaderValue(httpResponse.headers())) {
-                response.push(line);
-            }
-        }
-        const httpFailure = httpRequest.failure();
-        if (httpFailure) {
-            response.push(`### Request failed with`);
-            response.push(httpFailure.errorText);
-        }
-        const redirectChain = httpRequest.redirectChain();
-        if (redirectChain.length) {
-            response.push(`### Redirect chain`);
-            let indent = 0;
-            for (const request of redirectChain.reverse()) {
-                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request)}`);
-                indent++;
-            }
-        }
-        return response;
-    }
     resetResponseLineForTesting() {
         this.#textResponseLines = [];
     }