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/app/chrome-extension/USER_ID_GUIDE.md
+++ b/app/chrome-extension/USER_ID_GUIDE.md
@@ -0,0 +1,178 @@
+# Chrome Extension User ID Guide
+
+## Overview
+
+The Chrome extension automatically generates and manages unique user IDs when connecting to the remote server. This guide explains how to access and use these user IDs.
+
+## How User IDs Work
+
+### 1. **Automatic Generation**
+- Each Chrome extension instance generates a unique user ID in the format: `user_{timestamp}_{random}`
+- Example: `user_1704067200000_abc123def456`
+- User IDs are persistent across browser sessions (stored in chrome.storage.local)
+
+### 2. **User ID Display in Popup**
+When connected to the remote server, the popup will show:
+- **User ID section** with the current user ID
+- **Truncated display** for long IDs (shows first 8 and last 8 characters)
+- **Copy button** (📋) to copy the full user ID to clipboard
+- **Tooltip** showing the full user ID on hover
+
+## Getting User ID Programmatically
+
+### 1. **From Popup/Content Scripts**
+```javascript
+// Send message to background script to get user ID
+const response = await chrome.runtime.sendMessage({ type: 'getCurrentUserId' });
+if (response && response.success) {
+  const userId = response.userId;
+  console.log('Current User ID:', userId);
+} else {
+  console.log('No user ID available or not connected');
+}
+```
+
+### 2. **From Background Script**
+```javascript
+import { getRemoteServerClient } from './background/index';
+
+// Get the remote server client instance
+const client = getRemoteServerClient();
+if (client) {
+  const userId = await client.getCurrentUserId();
+  console.log('Current User ID:', userId);
+}
+```
+
+### 3. **Direct Storage Access**
+```javascript
+// Get user ID directly from chrome storage
+const result = await chrome.storage.local.get(['chrome_extension_user_id']);
+const userId = result.chrome_extension_user_id;
+console.log('Stored User ID:', userId);
+```
+
+## User ID Lifecycle
+
+### 1. **Generation**
+- User ID is generated on first connection to remote server
+- Stored in `chrome.storage.local` with key `chrome_extension_user_id`
+- Persists across browser restarts and extension reloads
+
+### 2. **Usage**
+- Sent to remote server during connection handshake
+- Used for session management and routing
+- Enables multi-user support with session isolation
+
+### 3. **Display**
+- Shown in popup when connected to remote server
+- Updates automatically when connection status changes
+- Cleared from display when disconnected
+
+## Remote Server Integration
+
+### 1. **Connection Info**
+When connecting, the extension sends:
+```javascript
+{
+  type: 'connection_info',
+  userId: 'user_1704067200000_abc123def456',
+  userAgent: navigator.userAgent,
+  timestamp: Date.now(),
+  extensionId: chrome.runtime.id
+}
+```
+
+### 2. **Server-Side Access**
+The remote server receives and uses the user ID for:
+- Session management
+- LiveKit room assignment (`mcp-chrome-user-{userId}`)
+- Command routing
+- User isolation
+
+## Troubleshooting
+
+### 1. **User ID Not Showing**
+- Ensure you're connected to the remote server
+- Check browser console for connection errors
+- Verify remote server is running and accessible
+
+### 2. **User ID Changes**
+- User IDs should persist across sessions
+- If changing frequently, check chrome.storage permissions
+- Clear extension data to force new user ID generation
+
+### 3. **Copy Function Not Working**
+- Ensure clipboard permissions are granted
+- Check for HTTPS context requirements
+- Fallback: manually select and copy from tooltip
+
+## API Reference
+
+### Background Script Messages
+
+#### `getCurrentUserId`
+```javascript
+// Request
+{ type: 'getCurrentUserId' }
+
+// Response
+{ 
+  success: true, 
+  userId: 'user_1704067200000_abc123def456' 
+}
+// or
+{ 
+  success: false, 
+  error: 'Remote server client not initialized' 
+}
+```
+
+### Storage Keys
+
+#### `chrome_extension_user_id`
+- **Type**: String
+- **Format**: `user_{timestamp}_{random}`
+- **Persistence**: Permanent (until extension data cleared)
+- **Access**: chrome.storage.local
+
+## Best Practices
+
+1. **Always check connection status** before requesting user ID
+2. **Handle null/undefined user IDs** gracefully
+3. **Use the background script API** for reliable access
+4. **Don't hardcode user IDs** - they should be dynamic
+5. **Respect user privacy** - user IDs are anonymous but unique
+
+## Example Implementation
+
+```javascript
+// Complete example of getting and using user ID
+async function handleUserIdExample() {
+  try {
+    // Get current user ID
+    const response = await chrome.runtime.sendMessage({ 
+      type: 'getCurrentUserId' 
+    });
+    
+    if (response && response.success && response.userId) {
+      console.log('✅ User ID:', response.userId);
+      
+      // Use the user ID for your application logic
+      await processUserSpecificData(response.userId);
+      
+    } else {
+      console.log('❌ No user ID available');
+      console.log('Make sure you are connected to the remote server');
+    }
+    
+  } catch (error) {
+    console.error('Failed to get user ID:', error);
+  }
+}
+
+async function processUserSpecificData(userId) {
+  // Your application logic here
+  console.log(`Processing data for user: ${userId}`);
+}
+```