@mcp-fe/mcp-worker 0.0.17 → 0.1.1

package/docs/initialization.md

@@ -0,0 +1,188 @@
+# Initialization Handling
+
+How the library handles tool registration before worker initialization is complete.
+
+## Problem
+
+Tool registration could fail if called before the worker was fully initialized, causing:
+- Registration failures
+- Lost registrations
+- Race conditions
+
+## Solution
+
+Two-level protection ensures registrations never fail:
+
+## Solution
+
+Two-level protection ensures registrations never fail:
+
+### 1. WorkerClient Level
+
+Queues registrations if worker isn't initialized yet:
+
+```typescript
+public async registerTool(...) {
+  if (!this.isInitialized) {
+    // Queue for later processing
+    return new Promise((resolve, reject) => {
+      this.pendingRegistrations.push({ name, ..., resolve, reject });
+    });
+  }
+  
+  // Already initialized - register immediately
+  return this.registerToolInternal(...);
+}
+```
+
+When init completes, all queued registrations are processed automatically.
+
+### 2. MCPController Level
+
+Queues registrations if MCP server isn't connected yet:
+
+```typescript
+public async handleRegisterTool(toolData) {
+  if (!this.isMCPServerReady) {
+    // Queue until WebSocket connects
+    return new Promise((resolve, reject) => {
+      this.pendingToolRegistrations.push({ toolData, resolve, reject });
+    });
+  }
+  
+  // Server ready - register immediately
+  return this.handleRegisterToolInternal(toolData);
+}
+```
+
+When WebSocket connects, queued registrations are processed.
+
+When WebSocket connects, queued registrations are processed.
+
+## Registration Flow
+
+```
+Tool Registration Called
+    ↓
+Worker Initialized?
+    ├─ NO → Queue registration → Wait for init → Process queue
+    └─ YES → Send to worker
+                ↓
+            MCP Server Ready?
+                ├─ NO → Queue in controller → Wait for connect → Process queue
+                └─ YES → Register tool immediately
+                            ↓
+                        ✅ Tool Active
+```
+
+## API
+
+### Check if Initialized
+
+```typescript
+// Check worker state
+if (workerClient.initialized) {
+  console.log('Worker ready');
+}
+```
+
+### Wait for Initialization
+
+```typescript
+// Wait for worker to be ready
+await workerClient.waitForInit();
+await workerClient.registerTool(...);
+```
+
+## Usage
+
+### Automatic (Recommended)
+
+Just call `registerTool()` - queueing is handled automatically:
+
+```typescript
+// Works even if worker isn't initialized yet!
+await workerClient.registerTool('my_tool', ...);
+```
+
+### React Hook
+
+Use `useMCPTool` - it handles everything:
+
+```typescript
+function MyComponent() {
+  useMCPTool({
+    name: 'my_tool',
+    // ... automatically waits for init
+  });
+}
+```
+
+## Scenarios
+
+### Early Registration
+
+```typescript
+// Component mounts before worker init
+function App() {
+  useMCPTool({ name: 'tool1', ... }); // ← Before init
+}
+
+// Flow:
+// 1. Tool registration queued
+// 2. Worker initializes in background
+// 3. Queue processed automatically
+// 4. Tool registered ✅
+```
+
+### Late Registration
+
+```typescript
+// Worker already initialized
+workerClient.init(); // ← Finishes
+
+// Later...
+useMCPTool({ name: 'tool2', ... }); // ← After init
+
+// Flow:
+// 1. Worker already ready
+// 2. Registers immediately ✅
+```
+
+### Multiple Parallel Registrations
+
+```typescript
+// Multiple components mount simultaneously
+<>
+  <ComponentA /> {/* useMCPTool('tool1') */}
+  <ComponentB /> {/* useMCPTool('tool2') */}
+  <ComponentC /> {/* useMCPTool('tool3') */}
+</>
+
+// Flow:
+// 1. All queue registrations
+// 2. Init completes
+// 3. All process together ✅
+```
+
+## Benefits
+
+- ✅ **No race conditions** - Always works regardless of timing
+- ✅ **Automatic queueing** - No manual coordination needed
+- ✅ **Transparent** - User doesn't need to know about init
+- ✅ **No lost registrations** - Everything gets processed
+
+## Implementation Notes
+
+For contributors:
+
+- **WorkerClient** queues at `registerTool()` level
+- **MCPController** queues at `handleRegisterTool()` level
+- Both use Promise-based queues for clean async handling
+- Queues are processed in order (FIFO)
+
+See source code for implementation details:
+- `libs/mcp-worker/src/lib/worker-client.ts`
+- `libs/mcp-worker/src/lib/mcp-controller.ts`
+
+

package/docs/worker-details.md

@@ -0,0 +1,435 @@
+# Worker Implementation Details
+
+Technical details about how the MCP Worker implementation works under the hood.
+
+## Worker Architecture
+
+### SharedWorker vs ServiceWorker
+
+The library uses a **dual worker strategy** with automatic fallback:
+
+#### SharedWorker (Preferred)
+
+**Advantages:**
+- Single instance shared across all browser windows/tabs on the same origin
+- Maintains persistent WebSocket connection even when tabs are closed
+- Better for multi-tab applications
+- Lower resource usage (one instance for all tabs)
+
+**Browser Support:**
+- ✅ Chrome/Chromium
+- ✅ Firefox
+- ✅ Safari (16.4+)
+- ✅ Edge (Chromium-based)
+
+**Requirements:**
+- HTTPS in production (localhost works without HTTPS)
+- Not available in private/incognito mode in some browsers
+- May be blocked by enterprise policies
+
+#### ServiceWorker (Fallback)
+
+**Advantages:**
+- Runs in background with browser-managed lifecycle
+- Works in incognito mode
+- Universal browser support
+- Handles offline scenarios
+
+**Considerations:**
+- Separate instance per browser context
+- May be terminated by browser when inactive
+- Requires additional setup for multi-tab coordination
+
+### Automatic Selection
+
+The `WorkerClient` automatically chooses the best available option:
+
+```typescript
+await workerClient.init(); // Tries SharedWorker first, falls back to ServiceWorker
+```
+
+**Selection logic:**
+1. Check if `SharedWorker` is available
+2. Try to initialize SharedWorker
+3. If fails, fall back to ServiceWorker
+4. If both fail, throw error
+
+You can see which worker is being used:
+
+```typescript
+// Check in browser console
+console.log('[WorkerClient] Using SharedWorker'); // or
+console.log('[WorkerClient] Using ServiceWorker (fallback)');
+```
+
+## Data Storage
+
+### IndexedDB Schema
+
+Events are stored in IndexedDB for persistence and efficient querying.
+
+**Database:** `mcp-fe-events`  
+**Object Store:** `events`
+
+**Schema:**
+```typescript
+interface UserEvent {
+  id: string;              // UUID
+  type: 'navigation' | 'click' | 'input' | 'custom';
+  timestamp: number;       // Unix timestamp in ms
+  
+  // Navigation events
+  path?: string;
+  from?: string;           // Previous route
+  to?: string;             // Current route
+  
+  // Interaction events
+  element?: string;        // Element tag name (e.g., 'button')
+  elementId?: string;      // Element ID attribute
+  elementClass?: string;   // Element class attribute
+  elementText?: string;    // Element text content
+  
+  // Custom data
+  metadata?: Record<string, unknown>;
+}
+```
+
+**Indexes:**
+- `by-type` - Query by event type
+- `by-timestamp` - Query by time range
+- `by-path` - Query by page path
+
+### Storage Limits
+
+- **Quota:** Browser-dependent (typically 10-50% of available disk space)
+- **Auto-cleanup:** Old events may be removed based on storage pressure
+- **Manual cleanup:** Not currently implemented (TODO)
+
+## WebSocket Connection
+
+### Connection Management
+
+The worker maintains a persistent WebSocket connection to the MCP proxy server.
+
+**Connection lifecycle:**
+1. Worker initializes
+2. WebSocket connects to `backendWsUrl`
+3. Connection maintained with heartbeat
+4. Auto-reconnect on disconnect
+5. Events queued during disconnection
+
+### Message Protocol
+
+**From Worker to Proxy:**
+```typescript
+{
+  type: 'mcp_request',
+  id: 'unique-request-id',
+  method: 'tools/call',
+  params: {
+    name: 'get_user_events',
+    arguments: { limit: 10 }
+  }
+}
+```
+
+**From Proxy to Worker:**
+```typescript
+{
+  type: 'mcp_response',
+  id: 'unique-request-id',
+  result: {
+    content: [{
+      type: 'text',
+      text: '...'
+    }]
+  }
+}
+```
+
+### Authentication
+
+Authentication token is sent on connection:
+
+```typescript
+{
+  type: 'auth',
+  token: 'Bearer jwt-token-here'
+}
+```
+
+Token can be updated at runtime:
+
+```typescript
+workerClient.setAuthToken('Bearer new-token');
+```
+
+## Message Passing
+
+### WorkerClient ↔ Worker Communication
+
+The WorkerClient uses MessageChannel for request/response pattern:
+
+**Request flow:**
+```
+1. WorkerClient creates MessageChannel
+2. Sends message with port2
+3. Worker receives message with port2
+4. Worker processes request
+5. Worker sends response via port2
+6. WorkerClient receives response on port1
+```
+
+**Benefits:**
+- Dedicated channel per request
+- No message mixing
+- Built-in timeout handling
+- Clean async/await pattern
+
+### SharedWorker Communication
+
+```typescript
+// In WorkerClient
+const port = sharedWorker.port;
+port.start();
+port.postMessage({ type: 'INIT', backendUrl: '...' });
+port.onmessage = (event) => {
+  // Handle messages
+};
+```
+
+### ServiceWorker Communication
+
+```typescript
+// In WorkerClient
+const registration = await navigator.serviceWorker.register('/sw.js');
+navigator.serviceWorker.controller.postMessage({ type: 'INIT' });
+navigator.serviceWorker.addEventListener('message', (event) => {
+  // Handle messages
+});
+```
+
+## Worker Lifecycle
+
+### SharedWorker Lifecycle
+
+```
+Browser Start
+    ↓
+First Page Load
+    ↓
+SharedWorker Created
+    ↓
+Stays Active (even if all tabs closed)
+    ↓
+Browser Close → Worker Terminated
+```
+
+**Important:**
+- Lives beyond page lifecycle
+- Shared across all tabs of same origin
+- Not terminated when all tabs close (in most browsers)
+
+### ServiceWorker Lifecycle
+
+```
+Page Load
+    ↓
+ServiceWorker Registered
+    ↓
+Installing → Installed → Activating → Activated
+    ↓
+Handles requests
+    ↓
+Goes idle after period of inactivity
+    ↓
+Woken up when needed
+```
+
+**Important:**
+- Browser controls lifecycle
+- May be terminated when idle
+- Automatically restarted when needed
+
+## Performance Considerations
+
+### Memory Usage
+
+**SharedWorker:**
+- ~2-5 MB baseline
+- + event storage in IndexedDB
+- + WebSocket connection overhead
+
+**ServiceWorker:**
+- Similar to SharedWorker
+- Additional service worker cache (if used)
+
+### CPU Usage
+
+- **Idle:** Minimal (WebSocket heartbeat only)
+- **Event storage:** <1ms per event
+- **Event query:** 1-10ms depending on query complexity
+
+### Network Usage
+
+- **WebSocket:** ~1 KB/minute (heartbeat)
+- **Events:** Varies by application usage
+- **Reconnection:** Automatic with exponential backoff
+
+## Browser Compatibility
+
+### Full Feature Support
+
+- ✅ Chrome/Chromium 80+
+- ✅ Firefox 78+
+- ✅ Safari 16.4+
+- ✅ Edge 80+ (Chromium-based)
+
+### Minimum Requirements
+
+- ES2020+ support
+- WebWorker API
+- IndexedDB API
+- WebSocket API
+- MessageChannel API
+
+### Feature Detection
+
+The library automatically detects and uses available features:
+
+```typescript
+// SharedWorker detection
+if (typeof SharedWorker !== 'undefined') {
+  // Use SharedWorker
+} else {
+  // Fall back to ServiceWorker
+}
+```
+
+## Security Considerations
+
+### Origin Isolation
+
+Workers are isolated by origin:
+- SharedWorker: Shared only within same origin
+- ServiceWorker: Scoped to registration path
+
+### Authentication
+
+- Token-based authentication via `setAuthToken()`
+- Token transmitted over WebSocket (use WSS in production)
+- Token stored in memory only (not persisted)
+
+### Data Privacy
+
+- Events stored in IndexedDB (per-origin storage)
+- No cross-origin data access
+- Events cleared when user clears browser data
+
+### Content Security Policy (CSP)
+
+Required CSP directives:
+
+```http
+Content-Security-Policy: 
+  worker-src 'self';
+  connect-src 'self' ws://localhost:3001 wss://your-proxy.com;
+```
+
+## Debugging
+
+### Enable Debug Logs
+
+The worker logs important events to console:
+
+```
+[WorkerClient] init() called
+[WorkerClient] Using SharedWorker
+[WorkerClient] Worker initialized
+[MCPController] WebSocket connected
+[MCPController] Registered tool: get_user_events
+```
+
+### Inspect Worker
+
+**Chrome DevTools:**
+1. Open DevTools
+2. Go to Application tab
+3. Select "Service Workers" or "Shared Workers"
+4. Find your worker
+5. Click "inspect" to open dedicated DevTools
+
+**Firefox:**
+1. Open about:debugging
+2. Click "This Firefox"
+3. Find your worker in "Shared Workers" or "Service Workers"
+4. Click "Inspect"
+
+### Monitor WebSocket
+
+1. Open Network tab in DevTools
+2. Filter by "WS" (WebSocket)
+3. Click on the WebSocket connection
+4. View Messages tab to see all messages
+
+### Query IndexedDB
+
+1. Open Application tab in DevTools
+2. Expand "IndexedDB"
+3. Find "mcp-fe-events" database
+4. Browse stored events
+
+## Troubleshooting
+
+### SharedWorker Not Available
+
+**Symptoms:** Falls back to ServiceWorker immediately
+
+**Causes:**
+- Browser doesn't support SharedWorker
+- Private/incognito mode
+- Enterprise policy blocking
+- HTTP instead of HTTPS (in production)
+
+**Solution:** Library automatically uses ServiceWorker fallback
+
+### WebSocket Connection Fails
+
+**Symptoms:** `getConnectionStatus()` returns `false`
+
+**Causes:**
+- Proxy server not running
+- Wrong WebSocket URL
+- CORS/network issues
+- Firewall blocking WebSocket
+
+**Solution:**
+```typescript
+// Check connection in DevTools Network tab
+// Verify proxy server is running:
+// curl http://localhost:3001/health
+```
+
+### Events Not Storing
+
+**Symptoms:** `GET_EVENTS` returns empty array
+
+**Causes:**
+- Worker not initialized
+- IndexedDB quota exceeded
+- Browser blocking IndexedDB
+
+**Solution:**
+```typescript
+// Check worker is initialized
+console.log(workerClient.initialized);
+
+// Check for quota errors in console
+// Check IndexedDB in DevTools Application tab
+```
+
+## See Also
+
+- [API Reference](./api.md) - Complete API documentation
+- [Architecture](./architecture.md) - High-level architecture
+- [Guide](./guide.md) - Dynamic tool registration