better readme

README.md

@@ -7,36 +7,58 @@
     <br/>
 </div>
 
+## Installation
 
+1. **Install the Chrome Extension**
 
-## Comparison
+   Install the [Playwriter MCP Extension](https://github.com/remorses/playwriter) from the Chrome Web Store (or load it unpacked during development). Pin the extension to your Chrome toolbar for easy access.
 
-### BrowserMCP
+2. **Connect to a Tab**
 
-Playwriter has access to the full playwright API available, it can send any CDP command via the playwright methods. It only uses 1 tool `execute` to send playwright code snippets. This means that the LLM can reuse its knowledge about playwright and less context window is used to expose browser automations tools.
+   Click the Playwriter MCP extension icon on any tab you want to control. The icon will turn green when successfully connected.
 
-Playwriter is also more capable because it exposes the full playwright API instead of only a few tools.
+   **Icon states:**
+   - **Gray:** Not connected
+   - **Green:** Connected and ready
+   - **Orange badge (...):** Connecting
+   - **Red badge (!):** Error
 
-For comparison here are the tools supported by BrowserMCP:
+3. **Add MCP to Your Agent**
 
-Navigation:
+   Add the following configuration to your MCP client settings (e.g., Claude Desktop's `claude_desktop_config.json`):
 
-- `browsermcp_browser_navigate` - Navigate to a URL
-- `browsermcp_browser_go_back` - Go back to the previous page
-- `browsermcp_browser_go_forward` - Go forward to the next page
-  Page Inspection:
-- `browsermcp_browser_snapshot` - Capture accessibility snapshot of the current page (use this to get references to elements)
-- `browsermcp_browser_screenshot` - Take a screenshot of the current page
-- `browsermcp_browser_get_console_logs` - Get console logs from the browser
-  Interactions:
-- `browsermcp_browser_click` - Click on an element (requires element reference from snapshot)
-- `browsermcp_browser_hover` - Hover over an element
-- `browsermcp_browser_type` - Type text into an editable element (with optional submit)
-- `browsermcp_browser_select_option` - Select an option in a dropdown
-- `browsermcp_browser_press_key` - Press a key on the keyboard
-  Utilities:
-- `browsermcp_browser_wait` - Wait for a specified time in seconds
+   ```json
+   {
+     "mcpServers": {
+       "playwriter": {
+         "command": "npx",
+         "args": [
+           "playwriter@latest"
+         ]
+       }
+     }
+   }
+   ```
 
+   Restart your MCP client and you're ready to go! Your AI assistant can now control the browser through the extension.
+
+## Usage
+
+### Using the MCP
+
+**Important:** Before using the MCP, you must enable the extension on at least one tab:
+
+1. Pin the Playwriter extension to your Chrome toolbar (click the puzzle icon)
+2. Navigate to a tab you want to control
+3. Click the extension icon - it will turn green when connected
+
+Once enabled on one or more tabs, your AI assistant can:
+- Control all enabled tabs through the `execute` tool
+- Switch between tabs using playwright's context and page APIs
+- Create new tabs programmatically
+- Run any Playwright code against your browser tabs
+
+The MCP will automatically start a relay server and connect to your enabled browser tabs.
 
 ### Using with Playwright
 
@@ -61,3 +83,42 @@ await page.screenshot({ path: 'screenshot.png' })
 await browser.close()
 server.close()
 ```
+
+## Comparison
+
+### vs Playwright
+
+Playwriter uses a Chrome extension instead of launching a full new Chrome window. This approach has several benefits:
+
+- **Collaborate with your agent** - Work alongside the AI in the same browser, helping it when stuck on captchas or complex interactions
+- **Start on existing pages** - Launch the MCP on a page in your existing browser to replicate bugs exactly as they occur
+- **Reuse your extensions** - Keep using ad blockers, password managers, and other extensions you already have installed
+- **Bypass automation detection** - Disable CDP/automation temporarily by disconnecting the extension to bypass detection systems like Google login, then reconnect to continue automation. With Playwright's headless Chrome, automation is always detected and blocks your workflow
+- **Less resource usage** - No need to spawn a separate Chrome instance, saving memory and CPU
+- **Single browser workflow** - Everything happens in your main Chrome browser, no switching between windows
+
+### vs BrowserMCP
+
+Playwriter has access to the full playwright API available, it can send any CDP command via the playwright methods. It only uses 1 tool `execute` to send playwright code snippets. This means that the LLM can reuse its knowledge about playwright and less context window is used to expose browser automations tools.
+
+Playwriter is also more capable because it exposes the full playwright API instead of only a few tools.
+
+For comparison here are the tools supported by BrowserMCP:
+
+Navigation:
+
+- `browsermcp_browser_navigate` - Navigate to a URL
+- `browsermcp_browser_go_back` - Go back to the previous page
+- `browsermcp_browser_go_forward` - Go forward to the next page
+  Page Inspection:
+- `browsermcp_browser_snapshot` - Capture accessibility snapshot of the current page (use this to get references to elements)
+- `browsermcp_browser_screenshot` - Take a screenshot of the current page
+- `browsermcp_browser_get_console_logs` - Get console logs from the browser
+  Interactions:
+- `browsermcp_browser_click` - Click on an element (requires element reference from snapshot)
+- `browsermcp_browser_hover` - Hover over an element
+- `browsermcp_browser_type` - Type text into an editable element (with optional submit)
+- `browsermcp_browser_select_option` - Select an option in a dropdown
+- `browsermcp_browser_press_key` - Press a key on the keyboard
+  Utilities:
+- `browsermcp_browser_wait` - Wait for a specified time in seconds