chrome-devtools-mcp-for-extension 0.17.0 → 0.18.1

package/README.md

@@ -4,64 +4,54 @@
 
 **AI-powered Chrome extension development with automated testing, debugging, and Web Store submission**
 
-System extensions auto-load, development extensions easy to configure.
-
-**Built for:** Claude Code, Cursor, VS Code Copilot, Cline, and other MCP-compatible AI tools
+Built for: Claude Code, Cursor, VS Code Copilot, Cline, and other MCP-compatible AI tools
 
 ---
 
-## 🎯 Why This Tool?
-
-### The Problem
-- **Puppeteer/Playwright**: Disable extensions by default, require complex configuration
-- **Traditional Testing**: Hours of setup, maintaining separate test profiles
-- **Extension Development**: Can't test in real user environments
+## 📦 For Users: Quick Start
 
-### The Solution
-- ✅ **System extensions auto-load**: Your installed Chrome extensions work automatically
-- ✅ **Easy dev extension setup**: Simple `--loadExtensionsDir` configuration for development
-- ✅ **Real environment**: Tests with your actual extensions and settings
-- ✅ **Independent instance**: Runs alongside your regular Chrome without conflicts
+### Installation
 
----
+**Option 1: Direct execution (recommended)**
+```bash
+npx chrome-devtools-mcp-for-extension@latest
+```
 
-## 🚀 Quick Start
+**Option 2: Global installation**
+```bash
+npm install -g chrome-devtools-mcp-for-extension
+chrome-devtools-mcp-for-extension
+```
 
-### 1. Add Configuration
+### MCP Configuration
 
-Add the following to `~/.claude.json`:
+Add to your MCP client configuration file:
 
+**For Claude Code** (`~/.claude.json`):
 ```json
 {
   "mcpServers": {
     "chrome-devtools-extension": {
-      "type": "stdio",
       "command": "npx",
-      "args": ["chrome-devtools-mcp-for-extension@latest"],
-      "env": {}
+      "args": ["chrome-devtools-mcp-for-extension@latest"]
     }
   }
 }
 ```
 
-> **Note**: For other MCP clients (Cursor, VS Code Copilot, Cline), add to your client's global 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
 
-### 2. Restart Your AI Client
+### Test It
 
-### 3. Test It
+1. Restart your AI client
+2. Ask: `"List all my Chrome extensions"`
+3. ✅ You should see your installed Chrome extensions
 
-Ask your AI:
-```
-"List all my Chrome extensions"
-```
+### Load Development Extensions (Optional)
 
-✅ You should see your installed Chrome extensions
-
----
-
-## 🔧 Load Development Extensions (Optional)
-
-To test your own extensions under development, add `--loadExtensionsDir`:
+To test your own extensions under development:
 
 ```json
 {
@@ -77,581 +67,327 @@ To test your own extensions under development, add `--loadExtensionsDir`:
 }
 ```
 
-**Directory structure example:**
+**Directory structure:**
 ```
 /path/to/your/extensions/
-├── my-extension-1/
+├── extension-1/
 │   └── manifest.json
-├── my-extension-2/
+├── extension-2/
 │   └── manifest.json
 ```
 
-**More options**: See [MCP Configuration Guide](docs/mcp-configuration-guide.md)
-
 ---
 
-## ✨ Core Capabilities
+## 👨‍💻 For Developers: Contributing
 
-- 🧩 **Extension Development**: Load, debug, and reload Chrome extensions during development
-- 🏪 **Automated Web Store Submission**: Complete publishing workflow with form filling and screenshots
-- 🔧 **Browser Testing**: Test extensions across real websites with full Chrome functionality
-- 🐛 **Advanced Debugging**: Service worker inspection, console monitoring, error detection
-- 📸 **Screenshot Generation**: Auto-create store listing images in all required formats
+### Local Development Setup
 
----
-
-## 📚 Common Workflows
-
-### Create & Test Extension
-```
-1. "Create a Chrome extension that blocks ads on YouTube"
-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 from the extension"
-4. "Reload the extension with latest changes"
-```
-
-### Publish to Web Store
-```
-1. "Generate screenshots for my extension"
-2. "Validate my manifest for Web Store compliance"
-3. "Submit my extension to Chrome Web Store"
-```
-
-### Performance Testing
-```
-1. "Start performance trace on current page"
-2. "Test the extension's impact on page load"
-3. "Show performance insights"
-```
-
----
-
-## 🔍 Check Installed Version
-
-To verify which version is being used by your AI client:
-
-```
-"What version of chrome-devtools-mcp-for-extension are you using?"
-```
-
-The AI will call the tool with `--version` flag to check.
-
-**Troubleshooting cache issues:**
-- If you're not getting the latest version with `@latest`:
-  - Clear npx cache: `npx clear-npx-cache` or `rm -rf ~/.npm/_npx`
-  - Or use specific version: `chrome-devtools-mcp-for-extension@0.8.1`
-  - Restart your AI client completely
-
-**Direct check (manual):**
+**1. Clone and install:**
 ```bash
-npx chrome-devtools-mcp-for-extension@latest --version
+git clone https://github.com/usedhonda/chrome-devtools-mcp.git
+cd chrome-devtools-mcp
+npm install
+npm run build
 ```
 
----
-
-## 🛠️ Extension Development Tools
-
-Quick reference for the 3 core extension tools:
-
-| Tool | Purpose | Example Command |
-|------|---------|-----------------|
-| `list_extensions` | View all extensions with status | "List all my Chrome extensions" |
-| `reload_extension` | Hot-reload during development | "Reload my-extension" |
-| `inspect_service_worker` | Debug background scripts | "Debug service worker for my-extension" |
-
-
----
-
-## 📊 How It Compares
-
-| Feature | This Tool | Puppeteer/Playwright | Original chrome-devtools-mcp |
-|---------|-----------|----------------------|------------------------------|
-| Extension Support | ✅ Always enabled | ❌ Disabled by default | ⚠️ Manual config required |
-| Setup Required | ❌ None | ✅ Complex config files | ✅ Multiple flags needed |
-| Real User Profile | ✅ Direct access | ❌ Temporary profiles | ⚠️ Optional |
-| Profile Copying | ❌ No copying needed | ⚠️ Manual setup | ⚠️ Manual setup |
-| Web Store Automation | ✅ Built-in | ❌ None | ❌ None |
-| Extension Debugging | ✅ Service worker + console | ⚠️ Limited | ❌ None |
-
----
-<details>
-<summary>📖 Detailed Tool Documentation</summary>
-
-### `list_extensions` - Extension Inventory
-**Purpose**: Comprehensive extension status monitoring
-**Technical**: Accesses `chrome://extensions/` via shadow DOM manipulation
-**Output**: Extension metadata, enabled/disabled status, version, error detection
-**Use Case**: "List all my Chrome extensions" → Shows development and installed extensions
-
-### `reload_extension` - Development Hot-Reload
-**Purpose**: Streamlined extension development workflow
-**Technical**: Finds extensions by name/partial match, triggers reload via Chrome extension API
-**Output**: Confirmation of reload success/failure with error details
-**Use Case**: "Reload my ad-blocker extension" → Instantly applies code changes
-
-### `inspect_service_worker` - Debug Integration
-**Purpose**: Deep debugging of extension background processes
-**Technical**: Opens DevTools for service workers, supports Manifest V2/V3 architectures
-**Output**: Direct DevTools access to extension console, network, sources
-**Use Case**: "Debug why my content script isn't working" → Opens debugging interface
-
-</details>
-
----
-
-<details>
-<summary>⚙️ Advanced Configuration</summary>
-
-## Auto-load Development Extension
-
-Add to `~/.claude.json`:
+**2. Configure MCP client to use local version:**
 
+Update `~/.claude.json`:
 ```json
 {
   "mcpServers": {
     "chrome-devtools-extension": {
-      "type": "stdio",
-      "command": "npx",
+      "command": "node",
       "args": [
-        "chrome-devtools-mcp-for-extension@latest",
-        "--loadExtension=/path/to/your/extension"
-      ],
-      "env": {}
+        "/absolute/path/to/chrome-devtools-mcp/scripts/cli.mjs",
+        "--loadExtensionsDir=/path/to/your/test/extensions"
+      ]
     }
   }
 }
 ```
 
-⚠️ **Note**: `--loadExtension` flag may be deprecated in Chrome 137+. Using system profile (default) is recommended.
-
-## Debug Mode
+**3. Restart your AI client**
 
-Add to `~/.claude.json`:
+### Development Workflow
 
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["chrome-devtools-mcp-for-extension@latest"],
-      "env": {
-        "DEBUG": "mcp:*"
-      }
-    }
-  }
-}
-```
+**Standard workflow (manual rebuild):**
+```bash
+# 1. Edit TypeScript files
+vim src/tools/extensions.ts
 
-## Custom Chrome Channel
+# 2. Build
+npm run build
 
-Add to `~/.claude.json`:
+# 3. Restart AI client
+# Cmd+R in VS Code (or restart your MCP client)
 
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "chrome-devtools-mcp-for-extension@latest",
-        "--channel=canary"
-      ],
-      "env": {}
-    }
-  }
-}
+# 4. Test changes
+# Ask AI to use the modified tool
 ```
 
-Options: `stable` (default), `beta`, `dev`, `canary`
-
-## Isolated Profile Mode
-
-Add to `~/.claude.json`:
-
-```json
+**Hot-reload workflow (automatic rebuild):**
+```bash
+# 1. Update MCP configuration to use wrapper
+# Edit ~/.claude.json:
 {
   "mcpServers": {
     "chrome-devtools-extension": {
-      "type": "stdio",
-      "command": "npx",
+      "command": "node",
       "args": [
-        "chrome-devtools-mcp-for-extension@latest",
-        "--isolated"
+        "/absolute/path/to/chrome-devtools-mcp/scripts/mcp-wrapper.mjs"
       ],
-      "env": {}
+      "cwd": "/absolute/path/to/chrome-devtools-mcp",
+      "env": {
+        "MCP_ENV": "development"
+      }
     }
   }
 }
-```
 
-Forces temporary profile instead of system profile.
+# 2. Restart AI client ONCE (Cmd+R)
 
-</details>
+# 3. Edit TypeScript files
+vim src/tools/extensions.ts
 
----
-
-<details>
-<summary>🏗️ Technical Architecture & Implementation</summary>
-
-## What Makes This Different
-
-This fork significantly restructures the original Chrome DevTools MCP for extension-focused development:
-
-### System Profile Architecture (v0.6.0+)
-
-**Zero-Config Design:**
-```typescript
-// Automatically detects and uses system Chrome profile
-if (!isolated && !userDataDir) {
-  const systemProfile = detectSystemChromeProfile(channel) || detectAnySystemChromeProfile();
-
-  if (systemProfile) {
-    userDataDir = systemProfile.path;  // Direct access, no copying
-    usingSystemProfile = true;
-  }
-}
+# 4. Changes automatically rebuild and reload
+# No need to restart AI client!
+# Just test your changes immediately
 ```
 
-**Profile Paths:**
-- macOS: `~/Library/Application Support/Google/Chrome`
-- Windows: `%LOCALAPPDATA%\Google\Chrome\User Data`
-- Linux: `~/.config/google-chrome`
+**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)
 
-**Detection Priority:**
-1. Specified channel (via `--channel` flag)
-2. Fallback: stable → beta → dev → canary
-3. Last resort: Creates temporary isolated profile
+**See also:** [Hot-Reload Setup Guide](docs/hot-reload-setup-guide.md)
 
-### Extension Loading Architecture
+### Project Structure
 
-**Unconditional Extension Enablement (v0.6.1+):**
-```typescript
-// Always remove --disable-extensions flag
-ignoreDefaultArgs: ['--disable-extensions', '--enable-automation']
+```
+chrome-devtools-mcp/
+├── src/
+│   ├── tools/              # MCP tool definitions
+│   │   ├── extensions.ts   # Extension management (list, reload, debug)
+│   │   ├── chatgpt-web.ts  # ChatGPT automation
+│   │   └── ...
+│   ├── 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
 ```
 
-**Why this design:**
-- Puppeteer's default `--disable-extensions` conflicts with extension development
-- Previous versions used conditional logic (buggy, removed in v0.6.1)
-- Current approach: **Always enable all extensions** for predictable behavior
-
-### Chrome Security Challenges Solved
-
-#### Chrome 137+ Breaking Changes
-- **Problem**: Chrome 137+ disabled `--load-extension` in automation contexts
-- **Solution**: Added `--disable-features=DisableLoadExtensionCommandLineSwitch` bypass
-- **Impact**: Development extensions can still be loaded via CLI flags
-
-#### Automation Detection Bypass
-- **Problem**: Chrome blocks many operations when detecting automated control
-- **Solution**: `--disable-blink-features=AutomationControlled` for real-world testing
-- **Use Case**: Google login, OAuth flows, Web Store submission
-
-#### Profile Management Strategy
-- **Default**: Direct system profile access (no copying, instant sync)
-- **Fallback**: Temporary profile with bookmarks copy (when Chrome is already running)
-- **Override**: `--isolated` flag for completely separate profile
-
-### Architecture Diagram
+### Internal Architecture
 
+**For users (production):**
 ```
-Extension Development Flow:
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│ AI Assistant    │───▶│ MCP Server       │───▶│ Chrome Browser  │
-│ (Claude/Cursor) │    │ (Extension Tools)│    │ + Extensions    │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
-                              │                         │
-                              ▼                         ▼
-                       ┌──────────────────┐    ┌─────────────────┐
-                       │ Web Store        │    │ System Profile  │
-                       │ Automation       │    │ (Direct Access) │
-                       └──────────────────┘    └─────────────────┘
+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)
 ```
 
-### Web Store Automation Tools
-
-#### Submission Workflow (`submit_to_webstore`)
-1. **Manifest Validation**: Manifest V3 compliance, permission security analysis
-2. **Package Creation**: ZIP generation with optimized compression, development file exclusion
-3. **Store Listing**: Auto-generated descriptions based on manifest permissions
-4. **Browser Automation**: Login flow, form population, file upload, error detection
-
-#### Screenshot Generation (`generate_extension_screenshots`)
-- **Primary**: 1280x800 (Web Store requirement)
-- **Promotional Tiles**: Small (440x280), Large (920x680), Marquee (1400x560)
-- **Smart Capture**: Extension popup, options page, in-context usage
-
-### Manifest Validation System
-
-```typescript
-interface ManifestValidation {
-  required: string[];      // name, version, manifest_version
-  warnings: string[];      // description length, icon sizes
-  security: string[];      // dangerous permissions analysis
-  suggestions: string[];   // optimization recommendations
-}
+**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)
 ```
 
-**Validation Features:**
-- Manifest V3 compliance enforcement
-- Permission analysis with security implications
-- Icon size recommendations (16x16, 48x48, 128x128)
-- Service worker file verification
-- Host permission optimization suggestions
-
-### Added Dependencies
-- **archiver** (7.0.1): ZIP package creation for extension submission
-- **puppeteer-core** (24.22.3): Chrome automation with extension support
-- **@modelcontextprotocol/sdk** (1.18.1): MCP server implementation
+**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)
 
-### MCP Server Coexistence
-- **Server Name**: `chrome-devtools-extension` (vs original `chrome-devtools`)
-- **Package Name**: `chrome-devtools-mcp-for-extension`
-- **Purpose**: Allows both servers to run simultaneously for different use cases
+**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
 
-</details>
+### Testing
 
----
+```bash
+# Build
+npm run build
 
-<details>
-<summary>👨‍💻 Developer Reference</summary>
+# Type check
+npm run typecheck
 
-## Supported Extension Types
-- **Manifest V3**: Full support (recommended)
-- **Service Workers**: Background script debugging
-- **Content Scripts**: Page interaction testing
-- **Popup Extensions**: UI testing and screenshots
-- **Options Pages**: Settings interface validation
+# Run tests
+npm test
 
-## Browser Compatibility
-- **Chrome**: Primary target (latest stable)
-- **Chrome Canary**: Development testing
-- **Chromium**: Community builds
-- **Edge**: Chromium-based versions
+# Format code
+npm run format
+```
 
-## Technical Requirements
-- **Node.js**: 22.12.0+ (for latest Chrome DevTools Protocol)
-- **Chrome**: Any version with extension support
-- **Storage**: ~50MB for dependencies
-- **Network**: Required for Web Store automation
+### Publishing (Maintainers Only)
 
-## Extension Loading Capabilities
-- **Startup Loading**: Extensions loaded at Chrome startup via `--loadExtension`
-- **System Extensions**: Auto-loads all extensions from Chrome profile (default)
-- **Manual Reloading**: Update extensions via `reload_extension` MCP tool
-- **Multi-Extension**: Support for multiple extensions simultaneously
+```bash
+# 1. Update version in package.json
+npm version patch  # or minor, major
 
-⚠️ **Note**: Runtime extension installation not supported. Extensions must be loaded at startup.
+# 2. Build
+npm run build
 
-## Security & Privacy Considerations
-- **System Profile Access**: Uses system Chrome profile by default (includes cookies, sessions, history, bookmarks)
-- **Profile Isolation**: Use `--isolated` flag for temporary profile without personal data
-- **Extension Sandboxing**: Extension permissions are sandboxed per Chrome security model
-- **Web Store Auth**: Uses standard Google OAuth flow (no credentials stored)
+# 3. Test locally
+npx .
 
-⚠️ **Warning**: When using system profile, the MCP server has access to all data in your Chrome profile. Use `--isolated` mode for testing sensitive operations.
+# 4. Publish to npm
+npm publish
 
-</details>
+# 5. Push to GitHub
+git push && git push --tags
+```
 
 ---
 
-<details>
-<summary>❓ Troubleshooting</summary>
+## ✨ Features
 
-## Extension Not Loading
+- 🧩 **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 Integration**: Automated ChatGPT interactions for research
 
-**Check manifest.json:**
-```
-"List extensions and show any errors"
-```
-
-**Verify extension is in correct directory:**
-- Manifest must be at root: `/your-extension/manifest.json`
-- Not: `/your-extension/dist/manifest.json`
+---
 
-**Solution:**
+## 📚 Common Workflows
 
-Update `~/.claude.json`:
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "chrome-devtools-mcp-for-extension@latest",
-        "--loadExtension=/correct/path"
-      ],
-      "env": {}
-    }
-  }
-}
+### 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"
 ```
 
-## Service Worker Not Inspecting
-
-**Extension may not be active:**
+### Debug Extension Issues
 ```
-"List extensions"  // Check if enabled
-"Reload my-extension"  // Restart extension
+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"
 ```
 
-**DevTools window not appearing:**
-- Service worker only runs when needed
-- Trigger extension action first (click popup, run content script)
-
-## Web Store Submission Fails
-
-**Manifest V3 compliance:**
+### Publish to Web Store
 ```
-"Validate my manifest for Web Store compliance"
+1. "Generate screenshots for my extension"
+2. "Validate manifest for Web Store compliance"
+3. "Submit to Chrome Web Store"
 ```
 
-**Common issues:**
-- Missing required icons (16x16, 48x48, 128x128)
-- Invalid permissions (host_permissions format)
-- Service worker not specified
-
-## Extensions Disabled After Chrome Update
-
-**Chrome 137+ breaking change:**
-- `--load-extension` may be restricted in newer Chrome versions
-- **Solution**: Use system profile (default) instead of `--loadExtension` flag
+---
 
-## System Extensions Loading (v0.7.1+)
+## 🛠️ Core Tools
 
-**How does the MCP server handle Chrome extensions?**
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `list_extensions` | View all extensions | "List my extensions" |
+| `reload_extension` | Hot-reload | "Reload my-extension" |
+| `inspect_service_worker` | Debug background | "Debug service worker" |
+| `ask_chatgpt_web` | ChatGPT research | "Ask ChatGPT about..." |
+| `take_snapshot` | Page analysis | "Snapshot current page" |
+| `list_pages` | Browser tabs | "List open pages" |
 
-The MCP server uses an **isolated profile with `--load-extension`** to provide system extensions while maintaining independence:
+**See also:** [Full Tool Documentation](docs/tools-reference.md)
 
-### Default Behavior
-- ✅ **Independent Chrome Instance**: Runs separately from your main Chrome browser
-- ✅ **System Extensions Loaded**: Your installed Chrome extensions are automatically loaded via `--load-extension`
-- ✅ **Concurrent Usage**: Works alongside your regular Chrome browser without conflicts
-- 🔒 **Isolated Login State**: First launch requires Google login (for security)
-- 🔒 **Isolated Profile**: Uses `~/.cache/chrome-devtools-mcp/chrome-profile/`
+---
 
-### What Works
-- ✅ **Extensions**: All system Chrome extensions are dynamically loaded
-- ✅ **Bookmarks**: Accessible via MCP tools (`list_bookmarks`, `navigate_bookmark`)
-- ✅ **Login State**: Preserved in isolated profile after first login
+## 🔍 Troubleshooting
 
-### What Doesn't Work
-- ❌ **Bookmarks in Browser UI**: Not displayed in browser bookmarks bar (use MCP tools instead)
-- ❌ **Shared Login State**: System Chrome login state is not shared (first login required)
+### Extension Not Loading
 
-### Profile Location
 ```
-~/.cache/chrome-devtools-mcp/chrome-profile/
-└── Default/
-    ├── Cookies        (isolated)
-    ├── Login Data     (isolated)
-    └── ...            (all files isolated)
+"List extensions and show any errors"
 ```
 
-### First Launch
-- **Extensions**: Automatically loaded from system Chrome via `--load-extension`
-- **Google Login required**: You'll need to log in once (login state is isolated for security)
-- **Subsequent launches**: Login state is preserved in the isolated profile
+**Common fixes:**
+- Verify manifest.json is at root of extension directory
+- Check extension path in `--loadExtensionsDir`
+- Ensure manifest is valid Manifest V3
 
-### Isolated Mode (No Extensions)
-To run without any extensions:
+### MCP Server Not Starting
+
+**Check version:**
 ```bash
-npx chrome-devtools-mcp-for-extension@latest --isolated
+npx chrome-devtools-mcp-for-extension@latest --version
 ```
 
-</details>
-
----
-
-# 日本語 / Japanese
-
-**Chrome拡張機能開発用のAI支援MCPサーバー**
-
-システム拡張機能を自動ロード、開発用拡張機能も簡単設定
-
-## クイックスタート
-
-### 1. 設定を追加
-
-`~/.claude.json` に以下を追加:
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["chrome-devtools-mcp-for-extension@latest"],
-      "env": {}
-    }
-  }
-}
+**Clear npx cache:**
+```bash
+npx clear-npx-cache
+# or
+rm -rf ~/.npm/_npx
 ```
 
-### 2. AIクライアントを再起動
+**Check MCP configuration:**
+```bash
+cat ~/.claude.json | jq '.mcpServers'
+```
 
-### 3. 動作確認
+### Hot-Reload Not Working (Developers)
 
-AIに質問:
+**Verify development mode:**
+```bash
+ps aux | grep mcp-wrapper | grep MCP_ENV=development
 ```
-「Chrome拡張機能を一覧表示して」
+
+**Check tsc -w is running:**
+```bash
+ps aux | grep 'tsc -w'
 ```
 
-✅ インストール済みの拡張機能が表示されます
+**Manually restart wrapper:**
+```bash
+pkill -f mcp-wrapper
+# Then restart AI client (Cmd+R)
+```
 
 ---
 
-## 開発用拡張機能のロード（--loadExtensionsDirあり）
+## 📖 Documentation
 
-開発中の拡張機能をテストする場合:
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools-extension": {
-      "command": "npx",
-      "args": [
-        "chrome-devtools-mcp-for-extension@latest",
-        "--loadExtensionsDir=/path/to/your/extensions"
-      ]
-    }
-  }
-}
-```
+- [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)
 
 ---
 
-## 主な機能
+## 🙏 Credits
 
-- 🧩 **拡張機能の開発・デバッグ・リロード**: ライブ開発環境
-- 🏪 **Chrome Web Store への自動申請**: スクリーンショット生成付き
-- 🔧 **実環境でのブラウザテスト**: 既存の拡張機能と共存
-- 🐛 **高度なデバッグ**: サービスワーカー検査、コンソール監視
+This project is a 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
 
-```
-「広告ブロック拡張機能を作成して」
-「拡張機能のエラーを確認して」
-「サービスワーカーをデバッグして」
-「Web Storeに申請して」
-```
+---
 
-その他の詳細は英語セクションを参照してください。
+## 📄 License
 
----
+Apache-2.0
 
-**Version**: 0.6.2
+**Version**: 0.18.0
 **Repository**: https://github.com/usedhonda/chrome-devtools-mcp
-**License**: Apache-2.0
-**Original**: Chrome DevTools MCP by Google LLC