@mcp-fe/mcp-worker 0.0.1

package/README.md

@@ -0,0 +1,11 @@
+# mcp-worker
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build mcp-worker` to build the library.
+
+## Running unit tests
+
+Run `nx test mcp-worker` to execute the unit tests via [Vitest](https://vitest.dev/).

package/eslint.config.mjs

@@ -0,0 +1,22 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}',
+            '{projectRoot}/vite.config.{js,ts,mjs,mts}',
+          ],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@mcp-fe/mcp-worker",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,9 @@
+{
+  "name": "mcp-worker",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/mcp-worker/src",
+  "projectType": "library",
+  "tags": [],
+  "// targets": "to see all targets run: nx show project mcp-worker --web",
+  "targets": {}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/worker-client';
+export { queryEvents, type UserEvent } from './lib/database';

package/src/lib/database.ts

@@ -0,0 +1,122 @@
+/**
+ * IndexedDB operations for storing and querying user events
+ */
+
+const DB_NAME = 'user-activity-db'
+const DB_VERSION = 1
+const STORE_NAME = 'user-events'
+
+export interface UserEvent {
+  id: string
+  type: 'navigation' | 'click' | 'input' | 'custom'
+  timestamp: number
+  path?: string
+  from?: string
+  to?: string
+  element?: string
+  elementId?: string
+  elementClass?: string
+  elementText?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface EventFilters {
+  type?: string
+  startTime?: number
+  endTime?: number
+  path?: string
+  limit?: number
+}
+
+// Initialize IndexedDB
+export async function initDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION)
+
+    request.onerror = () => reject(request.error)
+    request.onsuccess = () => resolve(request.result)
+
+    request.onupgradeneeded = (event) => {
+      const db = (event.target as IDBOpenDBRequest).result
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        const store = db.createObjectStore(STORE_NAME, { keyPath: 'id' })
+        store.createIndex('timestamp', 'timestamp', { unique: false })
+        store.createIndex('type', 'type', { unique: false })
+        store.createIndex('path', 'path', { unique: false })
+      }
+    }
+  })
+}
+
+// Store event in IndexedDB
+export async function storeEvent(event: Omit<UserEvent, 'id'>): Promise<void> {
+  const db = await initDB()
+  const transaction = db.transaction([STORE_NAME], 'readwrite')
+  const store = transaction.objectStore(STORE_NAME)
+
+  const eventWithId: UserEvent = {
+    ...event,
+    id: `${event.timestamp}-${Math.random().toString(36).substr(2, 9)}`,
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const request = store.add(eventWithId)
+    request.onsuccess = () => resolve()
+    request.onerror = () => reject(request.error)
+  })
+
+  // Clean up old events (keep last 1000 events)
+  const countRequest = store.count()
+  countRequest.onsuccess = () => {
+    if (countRequest.result > 1000) {
+      const index = store.index('timestamp')
+      const getAllRequest = index.getAll()
+      getAllRequest.onsuccess = () => {
+        const events = getAllRequest.result as UserEvent[]
+        events.sort((a, b) => a.timestamp - b.timestamp)
+        const toDelete = events.slice(0, events.length - 1000)
+        toDelete.forEach((event) => store.delete(event.id))
+      }
+    }
+  }
+}
+
+// Query events from IndexedDB
+export async function queryEvents(filters?: EventFilters): Promise<UserEvent[]> {
+  const db = await initDB()
+  const transaction = db.transaction([STORE_NAME], 'readonly')
+  const store = transaction.objectStore(STORE_NAME)
+  const index = store.index('timestamp')
+
+  return new Promise((resolve, reject) => {
+    const request = index.getAll()
+    request.onsuccess = () => {
+      let events = request.result as UserEvent[]
+
+      // Apply filters
+      if (filters?.type) {
+        events = events.filter((e) => e.type === filters.type)
+      }
+      if (filters?.startTime) {
+        events = events.filter((e) => e.timestamp >= filters.startTime!)
+      }
+      if (filters?.endTime) {
+        events = events.filter((e) => e.timestamp <= filters.endTime!)
+      }
+      if (filters?.path) {
+        events = events.filter((e) => e.path?.includes(filters.path!))
+      }
+
+      // Sort by timestamp descending (newest first)
+      events.sort((a, b) => b.timestamp - a.timestamp)
+
+      // Apply limit
+      if (filters?.limit) {
+        events = events.slice(0, filters.limit)
+      }
+
+      resolve(events)
+    }
+    request.onerror = () => reject(request.error)
+  })
+}

package/src/lib/mcp-controller.ts

@@ -0,0 +1,199 @@
+/* eslint-disable no-restricted-globals */
+/**
+ * MCP Controller
+ *
+ * Encapsulates the shared WebSocket / MCP server / storage logic used by
+ * both SharedWorker and ServiceWorker implementations.
+ */
+
+import { storeEvent, queryEvents, UserEvent } from './database';
+import { mcpServer } from './mcp-server';
+import { WebSocketTransport } from './websocket-transport';
+
+const MAX_RECONNECT_DELAY = 30000;
+const INITIAL_RECONNECT_DELAY = 1000;
+
+export type BroadcastFn = (message: unknown) => void;
+
+export class MCPController {
+  private socket: WebSocket | null = null;
+  private transport: WebSocketTransport | null = null;
+  private reconnectAttempts = 0;
+  private authToken: string | null = null;
+  private keepAliveInterval: ReturnType<typeof setInterval> | null = null;
+  private requireAuth: boolean;
+
+  constructor(private backendUrl: string, private broadcastFn: BroadcastFn, requireAuth = true) {
+    this.requireAuth = requireAuth;
+  }
+
+  private startKeepAlive(): void {
+    if (this.keepAliveInterval) {
+      clearInterval(this.keepAliveInterval);
+    }
+
+    this.keepAliveInterval = setInterval(() => {
+      if (this.socket?.readyState === WebSocket.OPEN) {
+        try {
+          this.socket.send(JSON.stringify({ type: 'ping' }));
+        } catch {
+          // ignore send errors
+        }
+      }
+    }, 20000);
+  }
+
+  private stopKeepAlive(): void {
+    if (this.keepAliveInterval) {
+      clearInterval(this.keepAliveInterval);
+      this.keepAliveInterval = null;
+    }
+  }
+
+  public async connectWebSocket(): Promise<void> {
+    // If we require auth and don't have a token yet, do not attempt connection
+    if (this.requireAuth && !this.authToken) {
+      console.log('[MCPController] Skipping WebSocket connect: auth token not set and requireAuth=true');
+      return;
+    }
+
+    if (this.socket?.readyState === WebSocket.OPEN || this.socket?.readyState === WebSocket.CONNECTING) {
+      return;
+    }
+
+    // Clean up existing transport and socket
+    if (this.transport) {
+      try {
+        await mcpServer.close();
+      } catch (error) {
+        console.error('[MCPController] Error closing MCP server:', error);
+      }
+      this.transport = null;
+    }
+
+    if (this.socket) {
+      this.socket.onopen = null;
+      this.socket.onclose = null;
+      this.socket.onerror = null;
+      if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING) {
+        this.socket.close();
+      }
+      this.socket = null;
+    }
+
+    return new Promise((resolve) => {
+      const url = this.authToken ? `${this.backendUrl}?token=${this.authToken}` : this.backendUrl;
+      this.socket = new WebSocket(url);
+
+      this.socket.onopen = async () => {
+        console.log('[MCPController] Connected to backend MCP server');
+        this.reconnectAttempts = 0;
+
+        try {
+          if (this.socket) {
+            this.transport = new WebSocketTransport(this.socket);
+            // start transport if available
+            if (typeof this.transport.start === 'function') {
+              try {
+                await this.transport.start();
+              } catch {
+                // some transport implementations may not require start
+                // ignore
+              }
+            }
+
+            await mcpServer.connect(this.transport);
+            console.log('[MCPController] MCP Server connected to WebSocket transport');
+
+            this.startKeepAlive();
+            this.broadcastFn({ type: 'CONNECTION_STATUS', connected: true });
+            resolve();
+          }
+        } catch (error) {
+          console.error('[MCPController] Error setting up MCP server:', error);
+          this.broadcastFn({ type: 'CONNECTION_STATUS', connected: false });
+          if (this.socket) {
+            this.socket.close();
+          }
+          resolve();
+        }
+      };
+
+      this.socket.onclose = async (event: CloseEvent) => {
+        console.log('[MCPController] Disconnected from backend MCP server', event?.code, event?.reason);
+        this.broadcastFn({ type: 'CONNECTION_STATUS', connected: false });
+
+        if (this.transport) {
+          try {
+            await mcpServer.close();
+          } catch (error) {
+            console.error('[MCPController] Error closing MCP server:', error);
+          }
+          this.transport = null;
+        }
+
+        this.socket = null;
+        this.stopKeepAlive();
+
+        if (event?.code !== 1000) {
+          const delay = Math.min(
+            INITIAL_RECONNECT_DELAY * Math.pow(2, this.reconnectAttempts),
+            MAX_RECONNECT_DELAY,
+          );
+          this.reconnectAttempts++;
+          console.log(`[MCPController] Retrying in ${delay}ms...`);
+          setTimeout(() => this.connectWebSocket(), delay);
+        }
+
+        resolve();
+      };
+
+      this.socket.onerror = (event) => {
+        console.error('[MCPController] WebSocket error:', event);
+        this.broadcastFn({ type: 'CONNECTION_STATUS', connected: false });
+      };
+    });
+  }
+
+  public setAuthToken(token: string | null): void {
+    const tokenChanged = this.authToken !== token;
+    this.authToken = token;
+
+    if (tokenChanged) {
+      console.log('[MCPController] Auth token changed, reconnecting WebSocket...');
+      if (this.socket && (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING)) {
+        // Close with normal closure to prevent auto-reconnect in some environments
+        this.socket.close(1000, 'Reconnecting with new auth token');
+      }
+
+      // small delay before reconnecting
+      setTimeout(() => {
+        this.connectWebSocket().catch((error) => console.error('[MCPController] Failed to reconnect with new token:', error));
+      }, 100);
+    }
+  }
+
+  public async handleStoreEvent(userEvent: UserEvent): Promise<void> {
+    await storeEvent(userEvent);
+  }
+
+  public async handleGetEvents(): Promise<ReturnType<typeof queryEvents>> {
+    return queryEvents({ limit: 50 });
+  }
+
+  public getConnectionStatus(): boolean {
+    return this.socket?.readyState === WebSocket.OPEN;
+  }
+
+  public dispose(): void {
+    this.stopKeepAlive();
+    if (this.socket) {
+      try {
+        this.socket.close(1000, 'Worker disposed');
+      } catch {
+        // ignore
+      }
+      this.socket = null;
+    }
+  }
+}

package/src/lib/mcp-server.ts

@@ -0,0 +1,209 @@
+/**
+ * MCP Server setup and request handlers
+ * Uses @modelcontextprotocol/sdk for type safety and validation
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+import { queryEvents } from './database'
+
+// Create MCP server instance for service worker
+export const mcpServer = new Server(
+  {
+    name: 'mcp-worker-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+)
+
+// Register tools list handler using SDK
+mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'get_user_events',
+        description: 'Get user activity events (navigation, clicks, etc.)',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              enum: ['navigation', 'click', 'input', 'custom'],
+              description: 'Filter by event type',
+            },
+            startTime: {
+              type: 'number',
+              description: 'Start timestamp (Unix timestamp in milliseconds)',
+            },
+            endTime: {
+              type: 'number',
+              description: 'End timestamp (Unix timestamp in milliseconds)',
+            },
+            path: {
+              type: 'string',
+              description: 'Filter by path/URL',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of events to return',
+              default: 100,
+            },
+          },
+        },
+      },
+      {
+        name: 'get_navigation_history',
+        description: 'Get user navigation history',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Maximum number of navigation events to return',
+              default: 50,
+            },
+          },
+        },
+      },
+      {
+        name: 'get_click_events',
+        description: 'Get user click events',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            element: {
+              type: 'string',
+              description: 'Filter by element selector or text',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of click events to return',
+              default: 100,
+            },
+          },
+        },
+      },
+    ],
+  };
+})
+
+// Register tool call handler using SDK
+mcpServer.setRequestHandler(
+  CallToolRequestSchema,
+  async (request: { params: { name: string; arguments?: unknown } }) => {
+    const { name, arguments: args } = request.params;
+
+    switch (name) {
+      case 'get_user_events': {
+        const schema = z.object({
+          type: z.enum(['navigation', 'click', 'input', 'custom']).optional(),
+          startTime: z.number().optional(),
+          endTime: z.number().optional(),
+          path: z.string().optional(),
+          limit: z.number().optional().default(100),
+        });
+
+        const validatedArgs = schema.parse(args || {});
+        const events = await queryEvents(validatedArgs);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ events }, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'get_navigation_history': {
+        const schema = z.object({
+          limit: z.number().optional().default(50),
+        });
+
+        const validatedArgs = schema.parse(args || {});
+        const events = await queryEvents({
+          type: 'navigation',
+          limit: validatedArgs.limit,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  navigationHistory: events.map((e) => ({
+                    from: e.from,
+                    to: e.to,
+                    path: e.path,
+                    timestamp: e.timestamp,
+                  })),
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      case 'get_click_events': {
+        const schema = z.object({
+          element: z.string().optional(),
+          limit: z.number().optional().default(100),
+        });
+
+        const validatedArgs = schema.parse(args || {});
+        const events = await queryEvents({
+          type: 'click',
+          limit: validatedArgs.limit,
+        });
+
+        let filteredEvents = events;
+        if (validatedArgs.element) {
+          const elementFilter = validatedArgs.element.toLowerCase();
+          filteredEvents = events.filter(
+            (e) =>
+              e.element?.toLowerCase().includes(elementFilter) ||
+              e.elementText?.toLowerCase().includes(elementFilter) ||
+              e.elementId?.toLowerCase().includes(elementFilter) ||
+              e.elementClass?.toLowerCase().includes(elementFilter),
+          );
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  clickEvents: filteredEvents.map((e) => ({
+                    element: e.element,
+                    elementId: e.elementId,
+                    elementClass: e.elementClass,
+                    elementText: e.elementText,
+                    path: e.path,
+                    timestamp: e.timestamp,
+                    metadata: e.metadata,
+                  })),
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  },
+);
+

package/src/lib/service-worker.ts

@@ -0,0 +1,87 @@
+/**
+ * Service Worker MCP Server
+ *
+ * This service worker acts as an MCP (Model Context Protocol) server,
+ * storing user events and exposing them via MCP protocol endpoints.
+ */
+
+declare const self: ServiceWorkerGlobalScope;
+
+import { UserEvent } from './database';
+import { MCPController } from './mcp-controller';
+
+const BACKEND_WS_URL = 'ws://localhost:3001';
+
+// Broadcast to all clients
+const controller = new MCPController(BACKEND_WS_URL, (message: unknown) => {
+  self.clients.matchAll().then((clients) => {
+    clients.forEach((client) => {
+      try {
+        client.postMessage(message);
+      } catch (e) {
+        // ignore
+        console.error('[ServiceWorker] Failed to post message to client:', e);
+      }
+    });
+  }).catch((err) => {
+    console.error('[ServiceWorker] Failed to match clients for broadcast:', err);
+  });
+});
+
+// Handle messages from the main thread
+self.addEventListener('message', async (event: ExtendableMessageEvent) => {
+  if (!event.data) return;
+
+  if (event.data.type === 'SET_AUTH_TOKEN') {
+    controller.setAuthToken(event.data.token);
+    return;
+  }
+
+  if (event.data.type === 'STORE_EVENT') {
+    event.waitUntil((async () => {
+      try {
+        const userEvent = event.data.event as UserEvent;
+        await controller.handleStoreEvent(userEvent);
+
+        if (event.ports && event.ports[0]) {
+          event.ports[0].postMessage({ success: true });
+        }
+      } catch (error) {
+        if (event.ports && event.ports[0]) {
+          event.ports[0].postMessage({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+        }
+      }
+    })());
+  } else if (event.data.type === 'GET_EVENTS') {
+    event.waitUntil((async () => {
+      try {
+        const events = await controller.handleGetEvents();
+        if (event.ports && event.ports[0]) {
+          event.ports[0].postMessage({ success: true, events });
+        }
+      } catch (error) {
+        if (event.ports && event.ports[0]) {
+          event.ports[0].postMessage({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+        }
+      }
+    })());
+  } else if (event.data.type === 'GET_CONNECTION_STATUS') {
+    if (event.ports && event.ports[0]) {
+      event.ports[0].postMessage({ success: true, connected: controller.getConnectionStatus() });
+    }
+  }
+});
+
+// Install and activate
+self.addEventListener('install', (event: ExtendableEvent) => {
+  event.waitUntil(self.skipWaiting());
+});
+
+self.addEventListener('activate', (event: ExtendableEvent) => {
+  // Do not automatically start the WebSocket connection here.
+  // If a client intends to use the service worker it will send messages
+  // (e.g. SET_AUTH_TOKEN) and the controller will connect on demand.
+  event.waitUntil(
+    Promise.resolve(self.clients.claim())
+  );
+});

package/src/lib/shared-worker.ts

@@ -0,0 +1,109 @@
+/* eslint-disable no-restricted-globals */
+/**
+ * SharedWorker MCP Server
+ *
+ * This SharedWorker acts as an MCP (Model Context Protocol) server,
+ * storing user events and exposing them via MCP protocol endpoints.
+ * Falls back to ServiceWorker if SharedWorker is not supported.
+ */
+
+declare const self: SharedWorkerGlobalScope;
+
+import { UserEvent } from './database';
+import { MCPController } from './mcp-controller';
+
+const BACKEND_WS_URL = 'ws://localhost:3001';
+
+// Track all connected ports
+const connectedPorts: MessagePort[] = [];
+
+// Create controller with a broadcast function that posts to all connected ports
+const controller = new MCPController(BACKEND_WS_URL, (message: unknown) => {
+  connectedPorts.forEach((port) => {
+    try {
+      port.postMessage(message);
+    } catch (error) {
+      const idx = connectedPorts.indexOf(port);
+      if (idx > -1) connectedPorts.splice(idx, 1);
+    }
+  });
+});
+
+// Handle new connections
+self.onconnect = (event: MessageEvent) => {
+  const port = event.ports[0];
+  connectedPorts.push(port);
+
+  // Send initial connection status
+  try {
+    port.postMessage({ type: 'CONNECTION_STATUS', connected: controller.getConnectionStatus() });
+  } catch (err) {
+    console.error('[SharedWorker] Failed to post initial status to port:', err);
+  }
+
+  port.onmessage = async (ev: MessageEvent) => {
+    if (!ev.data) return;
+    const messageData = ev.data;
+
+    if (messageData.type === 'SET_AUTH_TOKEN') {
+      const newToken = (messageData as any).token as string | null;
+      controller.setAuthToken(newToken);
+      return;
+    }
+
+    if (messageData.type === 'STORE_EVENT') {
+      try {
+        const userEvent = messageData.event as UserEvent;
+        await controller.handleStoreEvent(userEvent);
+        try {
+          port.postMessage({ success: true });
+        } catch (error) {
+          console.error('[SharedWorker] Failed to post success to port:', error);
+        }
+      } catch (error) {
+        try {
+          port.postMessage({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+        } catch (e) {
+          console.error('[SharedWorker] Failed to post failure to port:', e);
+        }
+      }
+
+      return;
+    }
+
+    if (messageData.type === 'GET_EVENTS') {
+      try {
+        const events = await controller.handleGetEvents();
+        try {
+          port.postMessage({ success: true, events });
+        } catch (error) {
+          console.error('[SharedWorker] Failed to post events to port:', error);
+        }
+      } catch (error) {
+        try {
+          port.postMessage({ success: false, error: error instanceof Error ? error.message : 'Unknown error' });
+        } catch (e) {
+          console.error('[SharedWorker] Failed to post failure to port:', e);
+        }
+      }
+      return;
+    }
+
+    if (messageData.type === 'GET_CONNECTION_STATUS') {
+      try {
+        port.postMessage({ success: true, connected: controller.getConnectionStatus() });
+      } catch (error) {
+        console.error('[SharedWorker] Failed to post connection status to port:', error);
+      }
+      return;
+    }
+  };
+
+  // Handle port disconnection
+  port.onmessageerror = () => {
+    const index = connectedPorts.indexOf(port);
+    if (index > -1) {
+      connectedPorts.splice(index, 1);
+    }
+  };
+};

package/src/lib/websocket-transport.ts

@@ -0,0 +1,43 @@
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Custom MCP Transport for WebSocket in Service Worker
+ */
+export class WebSocketTransport implements Transport {
+
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage) => void;
+
+  constructor(private ws: WebSocket) {}
+
+  async start(): Promise<void> {
+    this.ws.addEventListener('message', (event) => {
+      try {
+        const message = JSON.parse(event.data);
+        this.onmessage?.(message);
+      } catch (error) {
+        this.onerror?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    });
+
+    this.ws.addEventListener('close', () => {
+      this.onclose?.();
+    });
+
+    this.ws.addEventListener('error', (event) => {
+      this.onerror?.(new Error('WebSocket error'));
+    });
+  }
+
+  async send(message: JSONRPCMessage): Promise<void> {
+    this.ws.send(JSON.stringify(message));
+  }
+
+  async close(): Promise<void> {
+    this.ws.close();
+  }
+}

package/src/lib/worker-client.ts

@@ -0,0 +1,369 @@
+type WorkerType = 'shared' | 'service';
+
+export class WorkerClient {
+  private serviceWorkerRegistration: ServiceWorkerRegistration | null = null;
+  private sharedWorker: SharedWorker | null = null;
+  private sharedWorkerPort: MessagePort | null = null;
+  private workerType: WorkerType | null = null;
+  private pendingAuthToken: string | null = null;
+  // connection status subscribers
+  private connectionStatusCallbacks: Set<(connected: boolean) => void> = new Set();
+  private serviceWorkerMessageHandler: ((ev: MessageEvent) => void) | null = null;
+
+  // Mutex/promise to prevent concurrent init runs
+  private initPromise: Promise<void> | null = null;
+
+  // Initialize and choose worker implementation (prefer SharedWorker)
+  public async init(registration?: ServiceWorkerRegistration): Promise<void> {
+    // If an init is already in progress, wait for it and optionally retry if caller provided a registration
+    if (this.initPromise) {
+      return this.initPromise.then(async () => {
+        if (registration && this.workerType !== 'service') {
+          // retry once with provided registration after current init finished
+          await this.init(registration);
+        }
+      });
+    }
+
+    // Start initialization and store the promise as a mutex
+    this.initPromise = (async () => {
+      try {
+        // If an explicit ServiceWorker registration is provided, use it
+        if (registration) {
+          this.serviceWorkerRegistration = registration;
+          this.workerType = 'service';
+          console.log('[WorkerClient] Using ServiceWorker (explicit registration)');
+          // send pending token if exists
+          if (this.pendingAuthToken) {
+            this.sendAuthTokenToServiceWorker(this.pendingAuthToken);
+            this.pendingAuthToken = null;
+          }
+          return;
+        }
+
+        // Try SharedWorker first
+        if (typeof SharedWorker !== 'undefined') {
+          try {
+            this.sharedWorker = new SharedWorker('/shared-worker.js', { type: 'module' });
+            this.sharedWorkerPort = this.sharedWorker.port;
+            this.sharedWorkerPort.start();
+
+            if (this.pendingAuthToken && this.sharedWorkerPort) {
+              try {
+                this.sharedWorkerPort.postMessage({ type: 'SET_AUTH_TOKEN', token: this.pendingAuthToken });
+              } catch (err) {
+                console.warn('[WorkerClient] Immediate postMessage to SharedWorker failed (will retry after init):', err);
+              }
+            }
+
+            this.sharedWorker.onerror = (event: ErrorEvent) => {
+              console.error('[WorkerClient] SharedWorker error:', event.message || event.error || event);
+              if (this.workerType !== 'shared') {
+                this.initServiceWorkerFallback().catch((err) => {
+                  console.error('[WorkerClient] Failed to initialize ServiceWorker fallback:', err);
+                });
+              }
+            };
+
+            await new Promise<void>((resolve, reject) => {
+              let resolved = false;
+              const timeout = setTimeout(() => {
+                if (!resolved) {
+                  const p = this.sharedWorkerPort;
+                  if (p) p.onmessage = null;
+                  reject(new Error('SharedWorker initialization timeout'));
+                }
+              }, 2000);
+
+              const p = this.sharedWorkerPort;
+              if (!p) {
+                clearTimeout(timeout);
+                return reject(new Error('SharedWorker port not available'));
+              }
+
+              p.onmessage = (ev: MessageEvent) => {
+                try {
+                  const data = ev.data;
+                  if (data && data.type === 'CONNECTION_STATUS') {
+                    clearTimeout(timeout);
+                    resolved = true;
+                    this.workerType = 'shared';
+                    p.onmessage = null;
+                    resolve();
+                  }
+                } catch {
+                  // ignore parse/handler errors
+                }
+              };
+            });
+
+            const portAfterInit = this.sharedWorkerPort;
+            if (this.pendingAuthToken && portAfterInit) {
+              try {
+                portAfterInit.postMessage({ type: 'SET_AUTH_TOKEN', token: this.pendingAuthToken });
+                this.pendingAuthToken = null;
+              } catch (e) {
+                console.error('[WorkerClient] Failed to send pending auth token to SharedWorker:', e);
+              }
+            }
+
+            if (portAfterInit) {
+              portAfterInit.onmessage = (ev: MessageEvent) => {
+                try {
+                  const data = ev.data;
+                  if (data && data.type === 'CONNECTION_STATUS') {
+                    const connected = !!data.connected;
+                    this.connectionStatusCallbacks.forEach((cb) => {
+                      try { cb(connected); } catch (e) { /* ignore callback errors */ }
+                    });
+                  }
+                } catch {
+                  // ignore
+                }
+              };
+            }
+
+            console.log('[WorkerClient] Using SharedWorker');
+            return;
+          } catch (error) {
+            console.warn('[WorkerClient] SharedWorker not available, falling back to ServiceWorker:', error);
+          }
+        }
+
+        // If SharedWorker isn't supported or failed, use service worker
+        console.log("this should not be called");
+        await this.initServiceWorkerFallback();
+
+        // Send pending token if any
+        if (this.pendingAuthToken && this.workerType === 'service') {
+          this.sendAuthTokenToServiceWorker(this.pendingAuthToken);
+          this.pendingAuthToken = null;
+        }
+      } finally {
+        // Clear the mutex so future init calls can proceed
+        this.initPromise = null;
+      }
+    })();
+
+    return this.initPromise;
+  }
+
+  private async initServiceWorkerFallback(): Promise<void> {
+    console.log("initServiceWorkerFallback called");
+    if ('serviceWorker' in navigator) {
+      try {
+        const existingRegistration = await navigator.serviceWorker.getRegistration();
+        if (existingRegistration) {
+          this.serviceWorkerRegistration = existingRegistration;
+          this.workerType = 'service';
+          console.log('[WorkerClient] Using existing ServiceWorker registration');
+          return;
+        }
+
+        const reg = await navigator.serviceWorker.register('/sw.js');
+        this.serviceWorkerRegistration = reg;
+        this.workerType = 'service';
+        console.log('[WorkerClient] Using ServiceWorker (fallback)');
+        if (this.serviceWorkerMessageHandler) {
+          navigator.serviceWorker.removeEventListener('message', this.serviceWorkerMessageHandler);
+          this.serviceWorkerMessageHandler = null;
+        }
+        this.serviceWorkerMessageHandler = (ev: MessageEvent) => {
+          try {
+            const data = ev.data;
+            if (data && data.type === 'CONNECTION_STATUS') {
+              const connected = !!data.connected;
+              this.connectionStatusCallbacks.forEach((cb) => {
+                try { cb(connected); } catch (e) { /* ignore callback errors */ }
+              });
+            }
+          } catch {
+            // ignore
+          }
+        };
+        navigator.serviceWorker.addEventListener('message', this.serviceWorkerMessageHandler);
+      } catch (error) {
+        console.error('[WorkerClient] Failed to register ServiceWorker:', error);
+        throw error;
+      }
+    } else {
+      throw new Error('Neither SharedWorker nor ServiceWorker is supported');
+    }
+  }
+
+  // Low-level request that expects a reply via MessageChannel
+  public async request<T = any>(type: string, payload?: Record<string, unknown>, timeoutMs = 5000): Promise<T> {
+    // If using shared worker
+    if (this.workerType === 'shared' && this.sharedWorkerPort) {
+      return new Promise<T>((resolve, reject) => {
+        const mc = new MessageChannel();
+        const timer = setTimeout(() => {
+          mc.port1.onmessage = null;
+          reject(new Error('Request timeout'));
+        }, timeoutMs);
+
+        mc.port1.onmessage = (ev: MessageEvent) => {
+          clearTimeout(timer);
+          if (ev.data && ev.data.success) {
+            resolve(ev.data as T);
+          } else if (ev.data && ev.data.success === false) {
+            reject(new Error(ev.data.error || 'Worker error'));
+          } else {
+            resolve(ev.data as T);
+          }
+        };
+
+        try {
+          const port = this.sharedWorkerPort;
+          if (!port) {
+            clearTimeout(timer);
+            return reject(new Error('SharedWorker port not available'));
+          }
+          port.postMessage({ type, ...(payload || {}) }, [mc.port2]);
+        } catch (e) {
+          clearTimeout(timer);
+          reject(e instanceof Error ? e : new Error(String(e)));
+        }
+      });
+    }
+
+    // If using service worker
+    if (this.workerType === 'service' && this.serviceWorkerRegistration) {
+      // Ensure service worker active
+      const reg = this.serviceWorkerRegistration;
+      if (!reg) throw new Error('Service worker registration missing');
+      if (!reg.active) {
+        await navigator.serviceWorker.ready;
+        if (!reg.active) {
+          throw new Error('Service worker not active');
+        }
+      }
+
+      return new Promise<T>((resolve, reject) => {
+        const mc = new MessageChannel();
+        const timer = setTimeout(() => {
+          mc.port1.onmessage = null;
+          reject(new Error('Request timeout'));
+        }, timeoutMs);
+
+        mc.port1.onmessage = (ev: MessageEvent) => {
+          clearTimeout(timer);
+          if (ev.data && ev.data.success) {
+            resolve(ev.data as T);
+          } else if (ev.data && ev.data.success === false) {
+            reject(new Error(ev.data.error || 'Worker error'));
+          } else {
+            resolve(ev.data as T);
+          }
+        };
+
+        try {
+          const active = reg.active;
+          if (!active) {
+            clearTimeout(timer);
+            return reject(new Error('Service worker active instance not available'));
+          }
+          active.postMessage({ type, ...(payload || {}) }, [mc.port2]);
+        } catch (e) {
+          clearTimeout(timer);
+          reject(e instanceof Error ? e : new Error(String(e)));
+        }
+      });
+    }
+
+    // No worker available
+    throw new Error('No worker registered');
+  }
+
+  // Fire-and-forget postMessage (no response expected)
+  public async post(type: string, payload?: Record<string, unknown>): Promise<void> {
+    if (this.workerType === 'shared' && this.sharedWorkerPort) {
+      try {
+        this.sharedWorkerPort.postMessage({ type, ...(payload || {}) });
+      } catch (e) {
+        console.error('[WorkerClient] Failed to post to SharedWorker:', e);
+      }
+      return;
+    }
+
+    if (this.workerType === 'service' && this.serviceWorkerRegistration?.active) {
+      try {
+        this.serviceWorkerRegistration.active.postMessage({ type, ...(payload || {}) });
+      } catch (e) {
+        console.error('[WorkerClient] Failed to post to ServiceWorker (active):', e);
+      }
+      return;
+    }
+
+    if ('serviceWorker' in navigator && navigator.serviceWorker.controller) {
+      try {
+        navigator.serviceWorker.controller.postMessage({ type, ...(payload || {}) });
+      } catch (e) {
+        console.error('[WorkerClient] Failed to post to ServiceWorker.controller:', e);
+      }
+      return;
+    }
+
+    // If no worker yet, queue token if SET_AUTH_TOKEN
+    if (type === 'SET_AUTH_TOKEN' && payload) {
+      const token = (payload as any)['token'];
+      if (typeof token === 'string') this.pendingAuthToken = token;
+    }
+  }
+
+  private sendAuthTokenToServiceWorker(token: string): void {
+    if (this.serviceWorkerRegistration?.active) {
+      try {
+        this.serviceWorkerRegistration.active.postMessage({ type: 'SET_AUTH_TOKEN', token });
+      } catch (e) {
+        console.error('[WorkerClient] Failed to send auth token to ServiceWorker:', e);
+      }
+    } else if ('serviceWorker' in navigator && navigator.serviceWorker.controller) {
+      try {
+        navigator.serviceWorker.controller.postMessage({ type: 'SET_AUTH_TOKEN', token });
+      } catch (e) {
+        console.error('[WorkerClient] Failed to send auth token to ServiceWorker.controller:', e);
+      }
+    } else {
+      // keep as pending
+      this.pendingAuthToken = token;
+    }
+  }
+
+  // Subscription API for consumers to listen for connection status updates
+  public onConnectionStatus(cb: (connected: boolean) => void): void {
+    this.connectionStatusCallbacks.add(cb);
+  }
+
+  public offConnectionStatus(cb: (connected: boolean) => void): void {
+    this.connectionStatusCallbacks.delete(cb);
+  }
+
+  public async getConnectionStatus(): Promise<boolean> {
+    try {
+      const res = await this.request('GET_CONNECTION_STATUS', undefined, 2000);
+      if (res && typeof res === 'object' && 'connected' in (res as any)) return !!(res as any).connected;
+      return !!(res as any).connected;
+    } catch {
+      return false;
+    }
+  }
+
+  public setAuthToken(token: string): void {
+    this.pendingAuthToken = token;
+    // Try to send immediately if possible
+    if (this.workerType === 'shared' && this.sharedWorkerPort) {
+      try {
+        this.sharedWorkerPort.postMessage({ type: 'SET_AUTH_TOKEN', token });
+        this.pendingAuthToken = null;
+      } catch (e) {
+        console.error('[WorkerClient] Failed to set auth token on SharedWorker:', e);
+      }
+    } else if (this.workerType === 'service') {
+      this.sendAuthTokenToServiceWorker(token);
+      this.pendingAuthToken = null;
+    } else {
+      // queued and will be sent when init finishes
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "importHelpers": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "lib": ["esnext", "dom", "webworker"]
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,24 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,28 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ]
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ]
+}

package/vite.config.mts

@@ -0,0 +1,59 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import * as path from 'path';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
+
+export default defineConfig(() => ({
+  root: import.meta.dirname,
+  cacheDir: '../../node_modules/.vite/libs/mcp-worker',
+  plugins: [
+    nxViteTsPaths(),
+    nxCopyAssetsPlugin(['*.md']),
+    dts({
+      entryRoot: 'src',
+      tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json'),
+      pathsToAliases: false,
+    }),
+  ],
+  // Uncomment this if you are using workers.
+  // worker: {
+  //   plugins: () => [ nxViteTsPaths() ],
+  // },
+  // Configuration for building your library.
+  // See: https://vite.dev/guide/build.html#library-mode
+  build: {
+    outDir: '../../dist/libs/mcp-worker',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
+    lib: {
+      // Could also be a dictionary or array of multiple entry points.
+      entry: 'src/index.ts',
+      name: 'mcp-worker',
+      fileName: 'index',
+      // Change this to the formats you want to support.
+      // Don't forget to update your package.json as well.
+      formats: ['es' as const],
+    },
+    rollupOptions: {
+      // External packages that should not be bundled into your library.
+      external: [],
+    },
+  },
+  test: {
+    name: 'mcp-worker',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: '../../coverage/libs/mcp-worker',
+      provider: 'v8' as const,
+    },
+  },
+}));