chrome-devtools-mcp-for-extension 0.26.1 → 0.26.3

package/README.md

@@ -2,32 +2,24 @@
 
 [![npm chrome-devtools-mcp-for-extension package](https://img.shields.io/npm/v/chrome-devtools-mcp-for-extension.svg)](https://npmjs.org/package/chrome-devtools-mcp-for-extension)
 
-**AI-powered Chrome extension development with automated testing, debugging, and Web Store submission**
+> AI-powered Chrome extension development via MCP
 
 Built for: Claude Code, Cursor, VS Code Copilot, Cline, and other MCP-compatible AI tools
 
 ---
 
-## 📦 For Users: Quick Start
+## Quick Start (5 minutes)
 
-### Installation
-/
-**Option 1: Direct execution (recommended)**
-```bash
-npx chrome-devtools-mcp-for-extension@latest
-```
+### 1. Run the server
 
-**Option 2: Global installation**
 ```bash
-npm install -g chrome-devtools-mcp-for-extension
-chrome-devtools-mcp-for-extension
+npx chrome-devtools-mcp-for-extension@latest
 ```
 
-### MCP Configuration
-
-Add to your MCP client configuration file:
+### 2. Configure your MCP client
 
 **For Claude Code** (`~/.claude.json`):
+
 ```json
 {
   "mcpServers": {
@@ -39,19 +31,11 @@ Add to your MCP client configuration file:
 }
 ```
 
-**For other MCP clients** (Cursor, VS Code Copilot, Cline):
-- Refer to your client's MCP configuration documentation
-- Use the same `command` and `args` as above
+### 3. Verify it works
 
-### Test It
+Restart your AI client and ask: `"List all my Chrome extensions"`
 
-1. Restart your AI client
-2. Ask: `"List all my Chrome extensions"`
-3. ✅ You should see your installed Chrome extensions
-
-### Load Development Extensions (Optional)
-
-To test your own extensions under development:
+### Load development extensions (optional)
 
 ```json
 {
@@ -67,414 +51,202 @@ To test your own extensions under development:
 }
 ```
 
-**Directory structure:**
+---
+
+## What You Can Do
+
+- **Extension Development**: Load, debug, and hot-reload Chrome extensions
+- **Browser Automation**: Navigate, click, fill forms, take screenshots
+- **Performance Analysis**: Trace recording and insight extraction
+- **AI Research**: Automated ChatGPT/Gemini interactions
+- **Web Store Submission**: Automated screenshot generation and submission
+
+---
+
+## Tools Reference
+
+### Core Tools (18)
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `take_snapshot` | Get page structure with element UIDs | - |
+| `take_screenshot` | Capture page or element image | `fullPage`, `uid` |
+| `click` | Click element by UID | `uid`, `dblClick` |
+| `fill` | Fill input/textarea/select | `uid`, `value` |
+| `fill_form` | Fill multiple form elements | `elements[]` |
+| `hover` | Hover over element | `uid` |
+| `drag` | Drag element to another | `from_uid`, `to_uid` |
+| `upload_file` | Upload file through input | `uid`, `filePath` |
+| `navigate` | Go to URL, back, forward | `op`, `url` |
+| `pages` | List, select, close tabs | `op`, `pageIdx` |
+| `wait_for` | Wait for text to appear | `text`, `timeout` |
+| `handle_dialog` | Accept/dismiss dialogs | `action` |
+| `resize_page` | Change viewport size | `width`, `height` |
+| `emulate` | CPU/network throttling | `target`, `throttlingRate` |
+| `network` | List/get network requests | `op`, `url` |
+| `performance` | Start/stop/analyze traces | `op`, `insightName` |
+| `evaluate_script` | Run JavaScript in page | `function` |
+| `list_console_messages` | Get console output | - |
+
+### Optional Tools (2) - Web-LLM
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `ask_chatgpt_web` | Ask ChatGPT via browser | `question`, `createNewChat` |
+| `ask_gemini_web` | Ask Gemini via browser | `question`, `createNewChat` |
+
+**Full documentation:** [docs/reference/tools.md](docs/reference/tools.md)
+
+---
+
+## Plugin Architecture (v0.26.0)
+
+### Disable Web-LLM tools
+
+```json
+{
+  "env": {
+    "MCP_DISABLE_WEB_LLM": "true"
+  }
+}
+```
+
+### Load external plugins
+
+```json
+{
+  "env": {
+    "MCP_PLUGINS": "./my-plugin.js,@org/another-plugin"
+  }
+}
 ```
-/path/to/your/extensions/
-├── extension-1/
-│   └── manifest.json
-├── extension-2/
-│   └── manifest.json
+
+**Plugin interface:**
+
+```typescript
+export default {
+  id: 'my-plugin',
+  name: 'My Custom 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) { /* implementation */ },
+    });
+  },
+};
 ```
 
 ---
 
-## 👨‍💻 For Developers: Contributing
+## For Developers
 
-### Local Development Setup
+### Local development setup
 
-**1. Clone and install:**
 ```bash
 git clone https://github.com/usedhonda/chrome-devtools-mcp.git
 cd chrome-devtools-mcp
-npm install
-npm run build
+npm install && npm run build
 ```
 
-**2. Configure MCP client to use local version:**
+Configure `~/.claude.json` to use local version:
 
-Update `~/.claude.json`:
 ```json
 {
   "mcpServers": {
     "chrome-devtools-extension": {
       "command": "node",
-      "args": [
-        "/absolute/path/to/chrome-devtools-mcp/scripts/cli.mjs",
-        "--loadExtensionsDir=/path/to/your/test/extensions"
-      ]
+      "args": ["/absolute/path/to/chrome-devtools-mcp/scripts/cli.mjs"]
     }
   }
 }
 ```
 
-**3. Restart your AI client**
-
-### Development Workflow
-
-**Standard workflow (manual rebuild):**
-```bash
-# 1. Edit TypeScript files
-vim src/tools/extensions.ts
-
-# 2. Build
-npm run build
+### Hot-reload development
 
-# 3. Restart AI client
-# Cmd+R in VS Code (or restart your MCP client)
-
-# 4. Test changes
-# Ask AI to use the modified tool
-```
-
-**Hot-reload workflow (automatic rebuild):**
-```bash
-# 1. Update MCP configuration to use wrapper
-# Edit ~/.claude.json:
+```json
 {
   "mcpServers": {
     "chrome-devtools-extension": {
       "command": "node",
-      "args": [
-        "/absolute/path/to/chrome-devtools-mcp/scripts/mcp-wrapper.mjs"
-      ],
+      "args": ["/absolute/path/to/chrome-devtools-mcp/scripts/mcp-wrapper.mjs"],
       "cwd": "/absolute/path/to/chrome-devtools-mcp",
-      "env": {
-        "MCP_ENV": "development"
-      }
+      "env": { "MCP_ENV": "development" }
     }
   }
 }
-
-# 2. Restart AI client ONCE (Cmd+R)
-
-# 3. Edit TypeScript files
-vim src/tools/extensions.ts
-
-# 4. Changes automatically rebuild and reload
-# No need to restart AI client!
-# Just test your changes immediately
-```
-
-**Hot-reload benefits:**
-- ✅ Automatic TypeScript compilation (`tsc -w`)
-- ✅ Automatic server restart on file changes
-- ✅ No VSCode Reload Window needed
-- ✅ 2-5 second feedback loop (vs 20-30 seconds)
-
-**See also:** [Hot-Reload Setup Guide](docs/hot-reload-setup-guide.md)
-
-### Project Structure
-
-```
-chrome-devtools-mcp/
-├── src/
-│   ├── tools/              # MCP tool definitions
-│   │   ├── core-tools.ts   # Core tool exports (v0.26.0)
-│   │   ├── optional-tools.ts # Web-LLM tool exports (v0.26.0)
-│   │   ├── chatgpt-web.ts  # ChatGPT automation
-│   │   ├── gemini-web.ts   # Gemini automation
-│   │   └── ...
-│   ├── plugin-api.ts       # Plugin architecture (v0.26.0)
-│   ├── browser.ts          # Browser/profile management
-│   ├── main.ts             # MCP server entry point
-│   └── graceful.ts         # Graceful shutdown
-├── scripts/
-│   ├── cli.mjs                    # Production entry (users)
-│   ├── mcp-wrapper.mjs            # Development wrapper (hot-reload)
-│   └── browser-globals-mock.mjs   # Node.js browser globals
-├── build/                  # Compiled JavaScript (gitignored)
-└── docs/                   # Documentation
 ```
 
-### Internal Architecture
+**Benefits:** Auto-rebuild on file changes, 2-5 second feedback loop.
 
-**For users (production):**
-```
-npx chrome-devtools-mcp-for-extension@latest
-  ↓
-scripts/cli.mjs
-  ↓
-node --import browser-globals-mock.mjs build/src/main.js
-  ↓
-MCP Server (single process, simple)
-```
+**See also:** [docs/dev/hot-reload.md](docs/dev/hot-reload.md)
 
-**For developers (hot-reload):**
-```
-node scripts/mcp-wrapper.mjs (MCP_ENV=development)
-  ↓
-tsc -w (automatic compilation)
-  ↓
-chokidar (file watcher)
-  ↓
-Auto-restart build/src/main.js on changes
-  ↓
-MCP Server (development mode, 2-5s reload)
-```
-
-**Key files:**
-- `scripts/cli.mjs`: Simple wrapper for production (loads browser-globals-mock)
-- `scripts/mcp-wrapper.mjs`: Development wrapper (hot-reload with tsc -w)
-- `scripts/browser-globals-mock.mjs`: Polyfills for chrome-devtools-frontend in Node.js
-- `src/main.ts`: Main MCP server (includes fallback browser globals)
-
-**Why browser-globals-mock?**
-- chrome-devtools-frontend expects browser globals (`location`, `self`, `localStorage`)
-- Node.js doesn't have these globals
-- `--import` flag loads the mock BEFORE any chrome-devtools-frontend modules
-
-### Testing
+### Commands
 
 ```bash
-# Build
-npm run build
-
-# Type check
-npm run typecheck
-
-# Run tests
-npm test
-
-# Format code
-npm run format
+npm run build      # Build TypeScript
+npm run typecheck  # Type check
+npm test           # Run tests
+npm run format     # Format code
 ```
 
-### Publishing (Maintainers Only)
-
-```bash
-# 1. Update version in package.json
-npm version patch  # or minor, major
-
-# 2. Build
-npm run build
-
-# 3. Test locally
-npx .
+### Project structure
 
-# 4. Publish to npm
-npm publish
-
-# 5. Push to GitHub
-git push && git push --tags
 ```
-
----
-
-## ✨ Features
-
-- 🧩 **Extension Development**: Load, debug, and reload Chrome extensions
-- 🏪 **Web Store Automation**: Automated submission with screenshots
-- 🔧 **Browser Testing**: Test extensions in real user environments
-- 🐛 **Advanced Debugging**: Service worker inspection, console monitoring
-- 📸 **Screenshot Generation**: Auto-create store listing images
-- 🤖 **ChatGPT/Gemini Integration**: Automated AI interactions for research
-- 🔌 **Plugin Architecture** (v0.26.0): Extensible tool system with external plugins
-
----
-
-## 📚 Common Workflows
-
-### Create & Test Extension
-```
-1. "Create a Chrome extension that blocks ads"
-2. "List extensions to verify it loaded"
-3. "Test the extension on youtube.com"
-4. "Show any errors from the extension"
-```
-
-### Debug Extension Issues
-```
-1. "List extensions and show any errors"
-2. "Inspect service worker for my-ad-blocker"
-3. "Show console messages"
-4. "Reload the extension with latest changes"
-```
-
-### Publish to Web Store
-```
-1. "Generate screenshots for my extension"
-2. "Validate manifest for Web Store compliance"
-3. "Submit to Chrome Web Store"
+chrome-devtools-mcp/
+├── src/
+│   ├── tools/           # MCP tool definitions
+│   ├── plugin-api.ts    # Plugin architecture
+│   ├── browser.ts       # Browser management
+│   └── main.ts          # Entry point
+├── scripts/
+│   ├── cli.mjs          # Production entry
+│   └── mcp-wrapper.mjs  # Development wrapper
+└── docs/                # Documentation
 ```
 
 ---
 
-## 🛠️ Core Tools
+## Documentation
 
-| Tool | Purpose | Example |
-|------|---------|---------|
-| `open_extension_popup` | Select popup window | "Open my extension popup" |
-| `reload_iframe_extension` | Hot-reload via CDP | "Reload extension" |
-| `patch_iframe_popup` | Edit & reload | "Patch popup.html" |
-| `ask_chatgpt_web` | ChatGPT research | "Ask ChatGPT about..." |
-| `take_snapshot` | Page analysis | "Snapshot current page" |
-| `list_pages` | Browser tabs | "List open pages" |
-
-**Note:** Extension tools use CDP (Chrome DevTools Protocol) for reliable operation.
-Shadow DOM-based tools (`list_extensions`, `reload_extension`, etc.) were removed in v0.19.0
-due to Chrome security restrictions.
-
-**See also:** [Full Tool Documentation](docs/tools-reference.md)
+| Guide | Description |
+|-------|-------------|
+| [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 |
 
 ---
 
-## 🔍 Troubleshooting
-
-### Extension Not Loading
-
-```
-"Check extension popup for errors"
-```
-
-**Common fixes:**
-- Verify manifest.json is at root of extension directory
-- Check extension path in `--loadExtensionsDir`
-- Ensure manifest is valid Manifest V3
-
-### MCP Server Not Starting
+## Troubleshooting
 
-**Check version:**
-```bash
-npx chrome-devtools-mcp-for-extension@latest --version
-```
-
-**Clear npx cache:**
-```bash
-npx clear-npx-cache
-# or
-rm -rf ~/.npm/_npx
-```
-
-**Check MCP configuration:**
-```bash
-cat ~/.claude.json | jq '.mcpServers'
-```
-
-### Hot-Reload Not Working (Developers)
-
-**Verify development mode:**
-```bash
-ps aux | grep mcp-wrapper | grep MCP_ENV=development
-```
-
-**Check tsc -w is running:**
-```bash
-ps aux | grep 'tsc -w'
-```
+### Extension not loading
+- Verify `manifest.json` is at extension root
+- Use absolute paths in `--loadExtensionsDir`
 
-**Manually restart wrapper:**
+### MCP server issues
 ```bash
-pkill -f mcp-wrapper
-# Then restart AI client (Cmd+R)
+npx clear-npx-cache && npx chrome-devtools-mcp-for-extension@latest
 ```
 
----
-
-## 📖 Documentation
-
-- [MCP Configuration Guide](docs/mcp-configuration-guide.md)
-- [Hot-Reload Setup Guide](docs/hot-reload-setup-guide.md) (Developers)
-- [Tools Reference](docs/tools-reference.md)
-- [ChatGPT Integration](docs/chatgpt-integration.md)
-- [Web Store Automation](docs/webstore-automation.md)
-
----
-
-## 🔌 Plugin Architecture (v0.26.0)
-
-### Tool Categories
-
-**Core Tools (18)** - Stable, site-independent:
-- Input: click, hover, fill, drag, fill_form, upload_file
-- Navigation: pages, navigate, resize_page, handle_dialog
-- Debugging: list_console_messages, take_screenshot, evaluate_script, take_snapshot, wait_for
-- Analysis: emulate, network, performance
-
-**Optional Tools (2)** - Web-LLM, site-dependent (may break with UI changes):
-- `ask_chatgpt_web` - ChatGPT browser automation
-- `ask_gemini_web` - Gemini browser automation
-
-### Disable Web-LLM Tools
-
-If you don't need ChatGPT/Gemini integration:
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "command": "npx",
-      "args": ["chrome-devtools-mcp-for-extension@latest"],
-      "env": {
-        "MCP_DISABLE_WEB_LLM": "true"
-      }
-    }
-  }
-}
-```
-
-### External Plugins
-
-Load custom plugins at startup:
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "command": "npx",
-      "args": ["chrome-devtools-mcp-for-extension@latest"],
-      "env": {
-        "MCP_PLUGINS": "./my-plugin.js,@org/another-plugin"
-      }
-    }
-  }
-}
-```
-
-**Plugin Interface:**
-```typescript
-// my-plugin.js
-export default {
-  id: 'my-plugin',
-  name: 'My Custom Plugin',
-  version: '1.0.0',
-
-  async register(ctx) {
-    ctx.registry.register({
-      name: 'my_custom_tool',
-      description: 'Does something useful',
-      schema: { /* zod schema */ },
-      annotations: { category: 'automation' },
-      async handler(input, response, context) {
-        // Tool implementation
-      }
-    });
-    ctx.log('Plugin registered!');
-  },
-
-  async unload() {
-    // Cleanup if needed
-  }
-};
-```
+**More:** [docs/user/troubleshooting.md](docs/user/troubleshooting.md)
 
 ---
 
-## 🙏 Credits
+## Credits
 
-This project is a fork of [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) by Google LLC.
+Fork of [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) by Google LLC.
 
-**Major additions:**
-- Chrome extension development tools
-- Web Store automation
-- ChatGPT integration
-- Hot-reload development workflow
-- System profile management
+**Additions:** Extension development tools, Web Store automation, ChatGPT/Gemini integration, hot-reload workflow.
 
 ---
 
-## 📄 License
+## License
 
 Apache-2.0
 
-**Version**: 0.26.0
+**Version**: 0.26.1
 **Repository**: https://github.com/usedhonda/chrome-devtools-mcp

package/build/src/McpContext.js

@@ -93,7 +93,7 @@ export class McpContext {
     async #disposeSessions() {
         await Promise.allSettled([
             this.#browserSession?.detach(),
-            ...[...this.#pageSessions.values()].map(s => s.detach())
+            ...[...this.#pageSessions.values()].map(s => s.detach()),
         ]);
         this.#browserSession = undefined;
         this.#pageSessions.clear();
@@ -111,7 +111,9 @@ export class McpContext {
             this.logger('CDP: Browser-level session created');
             // 3. Enable Target discovery and auto-attach
             try {
-                await this.#browserSession.send('Target.setDiscoverTargets', { discover: true });
+                await this.#browserSession.send('Target.setDiscoverTargets', {
+                    discover: true,
+                });
                 this.logger('CDP: Target discovery enabled');
             }
             catch (err) {
@@ -121,7 +123,7 @@ export class McpContext {
                 await this.#browserSession.send('Target.setAutoAttach', {
                     autoAttach: true,
                     waitForDebuggerOnStart: false,
-                    flatten: true
+                    flatten: true,
                 });
                 this.logger('CDP: Auto-attach configured');
             }

package/build/src/browser-connection-manager.js

@@ -47,9 +47,8 @@ export class BrowserConnectionManager {
     /** Disconnected event handler (arrow function to preserve 'this') */
     onDisconnected = () => {
         this.log('Browser disconnected');
-        this.setState(ConnectionState.RECONNECTING);
-        // Trigger immediate reconnection (single-flight prevents duplicates)
-        void this.triggerReconnect('event:disconnected');
+        this.setState(ConnectionState.CLOSED);
+        // Auto-reconnection disabled: reconnect only when MCP operation requires it
     };
     constructor(options = {}) {
         this.options = { ...DEFAULT_OPTIONS, ...options };
@@ -111,8 +110,7 @@ export class BrowserConnectionManager {
             this.log(`Reconnection overall timeout (${overallTimeout}ms) exceeded`);
         }, overallTimeout);
         // Start reconnection sequence
-        this.reconnectSequenceInFlight = this._runReconnectionSequence(abortController.signal)
-            .finally(() => {
+        this.reconnectSequenceInFlight = this._runReconnectionSequence(abortController.signal).finally(() => {
             clearTimeout(timeoutId);
             this.reconnectSequenceInFlight = null;
         });
@@ -309,7 +307,7 @@ ${lastError?.message || 'Unknown error'}
      * Sleep for specified milliseconds
      */
     sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+        return new Promise(resolve => setTimeout(resolve, ms));
     }
     /**
      * Get current browser instance