Major refactor: Multi-user Chrome MCP extension with remote server architecture

2025-08-21 20:09:57 +05:00
parent d97cad1736
commit 5d869f6a7c
125 changed files with 16249 additions and 11906 deletions
--- a/examples/background-page-navigation.md
+++ b/examples/background-page-navigation.md
@@ -0,0 +1,170 @@
+# Background Page Navigation Examples
+
+This document demonstrates how to use the new `backgroundPage` parameter to open URLs in background pages using minimized windows.
+
+## Overview
+
+The `backgroundPage` parameter allows you to open URLs without interrupting the user's current workflow. When set to `true`, it creates a minimized window that runs in the background instead of opening a new tab or focused window.
+
+## Usage Examples
+
+### 1. Basic Background Page Navigation
+
+```json
+{
+  "name": "chrome_navigate",
+  "arguments": {
+    "url": "https://example.com",
+    "backgroundPage": true
+  }
+}
+```
+
+This will:
+
+1. Create a new window with the specified URL
+2. Immediately minimize the window to keep it in the background
+3. Return window and tab information for reference
+
+### 2. Natural Language Background Navigation
+
+```json
+{
+  "name": "chrome_navigate_natural",
+  "arguments": {
+    "query": "open google",
+    "backgroundPage": true
+  }
+}
+```
+
+This will:
+
+1. Process the natural language query ("open google" → "https://www.google.com")
+2. Create a minimized window with the processed URL
+3. Keep the window running in the background
+
+### 3. Background Page with Custom Dimensions
+
+```json
+{
+  "name": "chrome_navigate",
+  "arguments": {
+    "url": "https://example.com",
+    "backgroundPage": true,
+    "width": 1920,
+    "height": 1080
+  }
+}
+```
+
+The window will be created with the specified dimensions before being minimized.
+
+### 4. Parameter Precedence
+
+When both `newWindow` and `backgroundPage` are specified:
+
+```json
+{
+  "name": "chrome_navigate",
+  "arguments": {
+    "url": "https://example.com",
+    "newWindow": true,
+    "backgroundPage": true
+  }
+}
+```
+
+The `backgroundPage` parameter takes precedence, and the URL will be opened in a minimized window.
+
+## Use Cases
+
+### 1. Background Data Loading
+
+Open data-heavy pages in the background while continuing to work:
+
+```json
+{
+  "name": "chrome_navigate",
+  "arguments": {
+    "url": "https://dashboard.example.com/reports",
+    "backgroundPage": true
+  }
+}
+```
+
+### 2. Preloading Content
+
+Preload content that will be needed later:
+
+```json
+{
+  "name": "chrome_navigate_natural",
+  "arguments": {
+    "query": "youtube trending",
+    "backgroundPage": true
+  }
+}
+```
+
+### 3. Background Monitoring
+
+Open monitoring or status pages in the background:
+
+```json
+{
+  "name": "chrome_navigate",
+  "arguments": {
+    "url": "https://status.example.com",
+    "backgroundPage": true
+  }
+}
+```
+
+## Response Format
+
+When using `backgroundPage: true`, the response will include:
+
+```json
+{
+  "success": true,
+  "message": "Opened URL in background page (minimized window)",
+  "windowId": 123,
+  "tabs": [
+    {
+      "tabId": 456,
+      "url": "https://example.com"
+    }
+  ]
+}
+```
+
+## Implementation Details
+
+The background page functionality:
+
+1. Creates a new window using `chrome.windows.create()` with full dimensions
+2. Sets `focused: false` to avoid stealing focus
+3. Sets `state: 'normal'` to ensure proper initial window state
+4. Waits 1 second for page load and proper dimension establishment
+5. Calls `chrome.windows.update()` with `state: 'minimized'` to move to background
+6. Returns window and tab information for future reference
+
+This approach ensures web automation tools can properly interact with the page even when minimized, as the window maintains its proper dimensions and DOM accessibility.
+
+## Comparison with Regular Navigation
+
+| Parameter                               | Behavior                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------- |
+| `backgroundPage: false` (default)       | Opens in new tab or focused window                                        |
+| `backgroundPage: true`                  | Opens full-size window, then minimizes (automation-compatible background) |
+| `newWindow: true`                       | Opens in new focused window                                               |
+| `newWindow: true, backgroundPage: true` | Opens full-size window, then minimizes (backgroundPage wins)              |
+
+## Browser Compatibility
+
+This feature requires:
+
+- Chrome extension with `windows` permission
+- Chrome browser (Chromium-based browsers)
+- The `chrome.windows.WindowState.MINIMIZED` API support