@mcp-fe/mcp-worker 0.0.12 → 0.0.13

package/README.md

@@ -1,11 +1,62 @@
-# mcp-worker
+# @mcp-fe/mcp-worker
 
-This library was generated with [Nx](https://nx.dev).
+This library provides a client adapter and ready-to-use worker scripts for working with MCP (Model Context Protocol).
 
-## Building
+Exports
 
-Run `nx build mcp-worker` to build the library.
+- `index` — the main client module (exports the `workerClient` singleton and related types). Import this in your client application.
+- `mcp-service-worker.js` — Service Worker implementation intended to be registered via `navigator.serviceWorker.register(...)`.
+- `mcp-shared-worker.js` — SharedWorker implementation intended to be started via `new SharedWorker(...)`.
 
-## Running unit tests
+Note: Worker script files (service/shared) must be available on your application's public path so the browser can fetch them (for example `/mcp-service-worker.js` and `/mcp-shared-worker.js`).
 
-Run `nx test mcp-worker` to execute the unit tests via [Vitest](https://vitest.dev/).
+Quick start
+
+1) Make worker files available on your public path
+
+- Copy the worker files (`mcp-service-worker.js`, `mcp-shared-worker.js`) into the folder your webserver serves as public (for example `public/` or `dist/`).
+- Important: the URL used during registration must match the actual location of the files. The `WorkerClient` defaults to `/mcp-shared-worker.js` and `/mcp-service-worker.js`. 
+  If you place them elsewhere, pass the correct URLs to `init`.
+
+3) Import and initialize in your client app
+
+Example (TypeScript):
+
+```ts
+import { workerClient } from '@mcp-fe/mcp-worker';
+
+// Optionally provide custom worker URLs and backend WebSocket URL
+await workerClient.init({
+  sharedWorkerUrl: '/mcp-shared-worker.js',
+  serviceWorkerUrl: '/mcp-service-worker.js',
+  backendWsUrl: 'wss://your-backend.example/ws'
+});
+
+// Set an auth token (if you use authentication)
+workerClient.setAuthToken('Bearer ...');
+
+// Send an event to the worker (fire-and-forget)
+await workerClient.post('STORE_EVENT', { event: { /* ... */ } });
+
+// Request events (request/response)
+const res = await workerClient.request('GET_EVENTS');
+if (res && (res as any).events) {
+  console.log('Events:', (res as any).events);
+}
+```
+
+Alternatively, register the Service Worker yourself and pass the registration to `init`:
+
+```ts
+// register the service worker (e.g. in your app entry file)
+const registration = await navigator.serviceWorker.register('/mcp-service-worker.js');
+await workerClient.init(registration);
+```
+
+Notes & best practices
+
+- `WorkerClient` prefers `SharedWorker` (shared across windows/iframes on the same origin). If `SharedWorker` is not available, it will automatically fall back to `ServiceWorker`.
+- If you need different worker URLs, pass `sharedWorkerUrl` and `serviceWorkerUrl` to `workerClient.init(...)`.
+- Worker scripts must be served from the same origin as your app.
+- Calling `workerClient.setAuthToken(...)` before initialization is allowed: the client will queue the token and send it when a worker becomes available.
+- The default worker URLs are `/mcp-shared-worker.js` and `/mcp-service-worker.js`.

package/index.js

@@ -1,5 +1,10 @@
 // libs/mcp-worker/src/lib/worker-client.ts
 var WorkerClient = class {
+  // Configurable worker script URLs (defaults kept for backward compatibility)
+  sharedWorkerUrl = "/mcp-shared-worker.js";
+  serviceWorkerUrl = "/mcp-service-worker.js";
+  // Backend websocket URL to pass into the worker(s)
+  backendWsUrl = "ws://localhost:3001";
   serviceWorkerRegistration = null;
   sharedWorker = null;
   sharedWorkerPort = null;
@@ -7,143 +12,113 @@ var WorkerClient = class {
   pendingAuthToken = null;
   // connection status subscribers
   connectionStatusCallbacks = /* @__PURE__ */ new Set();
-  serviceWorkerMessageHandler = null;
   // Mutex/promise to prevent concurrent init runs
   initPromise = null;
   // Initialize and choose worker implementation (prefer SharedWorker)
-  async init(registration) {
+  // Accept either a ServiceWorkerRegistration OR WorkerInitOptions to configure URLs
+  async init(registrationOrOptions) {
+    let explicitRegistration;
+    const maybeReg = registrationOrOptions;
+    if (maybeReg && typeof maybeReg.scope === "string") {
+      explicitRegistration = registrationOrOptions;
+    } else if (registrationOrOptions) {
+      const opts = registrationOrOptions;
+      if (opts.sharedWorkerUrl)
+        this.sharedWorkerUrl = opts.sharedWorkerUrl;
+      if (opts.serviceWorkerUrl)
+        this.serviceWorkerUrl = opts.serviceWorkerUrl;
+      if (opts.backendWsUrl)
+        this.backendWsUrl = opts.backendWsUrl;
+    }
     if (this.initPromise) {
       return this.initPromise.then(async () => {
-        if (registration && this.workerType !== "service") {
-          await this.init(registration);
+        if (explicitRegistration && this.workerType !== "service") {
+          await this.init(explicitRegistration);
         }
       });
     }
     this.initPromise = (async () => {
       try {
-        if (registration) {
-          this.serviceWorkerRegistration = registration;
+        if (explicitRegistration) {
+          this.serviceWorkerRegistration = explicitRegistration;
           this.workerType = "service";
-          console.log("[WorkerClient] Using ServiceWorker (explicit registration)");
-          if (this.pendingAuthToken) {
-            this.sendAuthTokenToServiceWorker(this.pendingAuthToken);
-            this.pendingAuthToken = null;
-          }
-          return;
-        }
-        if (typeof SharedWorker !== "undefined") {
+          console.log(
+            "[WorkerClient] Using ServiceWorker (explicit registration)"
+          );
           try {
-            this.sharedWorker = new SharedWorker("/mcp-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) => {
-              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((resolve, reject) => {
-              let resolved = false;
-              const timeout = setTimeout(() => {
-                if (!resolved) {
-                  const p2 = this.sharedWorkerPort;
-                  if (p2)
-                    p2.onmessage = null;
-                  reject(new Error("SharedWorker initialization timeout"));
-                }
-              }, 2e3);
-              const p = this.sharedWorkerPort;
-              if (!p) {
-                clearTimeout(timeout);
-                return reject(new Error("SharedWorker port not available"));
-              }
-              p.onmessage = (ev) => {
-                try {
-                  const data = ev.data;
-                  if (data && data.type === "CONNECTION_STATUS") {
-                    clearTimeout(timeout);
-                    resolved = true;
-                    this.workerType = "shared";
-                    p.onmessage = null;
-                    resolve();
-                  }
-                } catch {
-                }
-              };
-            });
-            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) => {
-                try {
-                  const data = ev.data;
-                  if (data && data.type === "CONNECTION_STATUS") {
-                    const connected = !!data.connected;
-                    this.connectionStatusCallbacks.forEach((cb) => {
-                      try {
-                        cb(connected);
-                      } catch (e) {
-                      }
-                    });
-                  }
-                } catch {
-                }
-              };
+            const initMsg = { type: "INIT", backendUrl: this.backendWsUrl };
+            if (this.pendingAuthToken)
+              initMsg["token"] = this.pendingAuthToken;
+            if (this.serviceWorkerRegistration.active) {
+              this.serviceWorkerRegistration.active.postMessage(initMsg);
+            } else if ("serviceWorker" in navigator && navigator.serviceWorker.controller) {
+              navigator.serviceWorker.controller.postMessage(initMsg);
             }
-            console.log("[WorkerClient] Using SharedWorker");
-            return;
-          } catch (error) {
-            console.warn("[WorkerClient] SharedWorker not available, falling back to ServiceWorker:", error);
+          } catch {
           }
+          return;
         }
-        console.log("this should not be called");
+        const sharedOk = await this.initSharedWorker();
+        if (sharedOk)
+          return;
         await this.initServiceWorkerFallback();
-        if (this.pendingAuthToken && this.workerType === "service") {
-          this.sendAuthTokenToServiceWorker(this.pendingAuthToken);
-          this.pendingAuthToken = null;
-        }
       } finally {
         this.initPromise = null;
       }
     })();
     return this.initPromise;
   }
-  async initServiceWorkerFallback() {
-    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;
+  async initSharedWorker() {
+    if (typeof SharedWorker === "undefined") {
+      return false;
+    }
+    try {
+      this.sharedWorker = new SharedWorker(this.sharedWorkerUrl, {
+        type: "module"
+      });
+      this.sharedWorkerPort = this.sharedWorker.port;
+      this.sharedWorkerPort.start();
+      await new Promise((resolve, reject) => {
+        let resolved = false;
+        const timeout = setTimeout(() => {
+          if (!resolved) {
+            const p2 = this.sharedWorkerPort;
+            if (p2)
+              p2.onmessage = null;
+            reject(new Error("SharedWorker initialization timeout"));
+          }
+        }, 2e3);
+        const p = this.sharedWorkerPort;
+        if (!p) {
+          clearTimeout(timeout);
+          return reject(new Error("SharedWorker port not available"));
         }
-        const reg = await navigator.serviceWorker.register("/mcp-service-worker.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;
+        p.onmessage = (ev) => {
+          try {
+            const data = ev.data;
+            if (data && data.type === "CONNECTION_STATUS") {
+              clearTimeout(timeout);
+              resolved = true;
+              this.workerType = "shared";
+              p.onmessage = null;
+              resolve();
+            }
+          } catch {
+          }
+        };
+      });
+      const portAfterInit = this.sharedWorkerPort;
+      if (portAfterInit) {
+        try {
+          const initMsg = { type: "INIT", backendUrl: this.backendWsUrl };
+          if (this.pendingAuthToken)
+            initMsg["token"] = this.pendingAuthToken;
+          portAfterInit.postMessage(initMsg);
+          this.pendingAuthToken = null;
+        } catch (e) {
+          console.warn("[WorkerClient] Failed to send INIT to SharedWorker port:", e);
         }
-        this.serviceWorkerMessageHandler = (ev) => {
+        portAfterInit.onmessage = (ev) => {
           try {
             const data = ev.data;
             if (data && data.type === "CONNECTION_STATUS") {
@@ -151,16 +126,58 @@ var WorkerClient = class {
               this.connectionStatusCallbacks.forEach((cb) => {
                 try {
                   cb(connected);
-                } catch (e) {
+                } catch {
                 }
               });
             }
           } catch {
           }
         };
-        navigator.serviceWorker.addEventListener("message", this.serviceWorkerMessageHandler);
+      }
+      console.log("[WorkerClient] Using SharedWorker");
+      return true;
+    } catch (error) {
+      console.warn(
+        "[WorkerClient] SharedWorker not available, falling back to ServiceWorker:",
+        error
+      );
+      return false;
+    }
+  }
+  async initServiceWorkerFallback() {
+    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;
+        }
+        this.serviceWorkerRegistration = await navigator.serviceWorker.register(
+          this.serviceWorkerUrl
+        );
+        this.workerType = "service";
+        console.log("[WorkerClient] Using MCP ServiceWorker (fallback)");
+        try {
+          const initMsg = { type: "INIT", backendUrl: this.backendWsUrl };
+          if (this.pendingAuthToken)
+            initMsg["token"] = this.pendingAuthToken;
+          if (this.serviceWorkerRegistration.active) {
+            this.serviceWorkerRegistration.active.postMessage(initMsg);
+          } else if ("serviceWorker" in navigator && navigator.serviceWorker.controller) {
+            navigator.serviceWorker.controller.postMessage(initMsg);
+          }
+          this.pendingAuthToken = null;
+        } catch {
+        }
       } catch (error) {
-        console.error("[WorkerClient] Failed to register ServiceWorker:", error);
+        console.error(
+          "[WorkerClient] Failed to register ServiceWorker:",
+          error
+        );
         throw error;
       }
     } else {
@@ -229,7 +246,9 @@ var WorkerClient = class {
           const active = reg.active;
           if (!active) {
             clearTimeout(timer);
-            return reject(new Error("Service worker active instance not available"));
+            return reject(
+              new Error("Service worker active instance not available")
+            );
           }
           active.postMessage({ type, ...payload || {} }, [mc.port2]);
         } catch (e) {
@@ -252,17 +271,29 @@ var WorkerClient = class {
     }
     if (this.workerType === "service" && this.serviceWorkerRegistration?.active) {
       try {
-        this.serviceWorkerRegistration.active.postMessage({ type, ...payload || {} });
+        this.serviceWorkerRegistration.active.postMessage({
+          type,
+          ...payload || {}
+        });
       } catch (e) {
-        console.error("[WorkerClient] Failed to post to ServiceWorker (active):", 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 || {} });
+        navigator.serviceWorker.controller.postMessage({
+          type,
+          ...payload || {}
+        });
       } catch (e) {
-        console.error("[WorkerClient] Failed to post to ServiceWorker.controller:", e);
+        console.error(
+          "[WorkerClient] Failed to post to ServiceWorker.controller:",
+          e
+        );
       }
       return;
     }
@@ -275,15 +306,27 @@ var WorkerClient = class {
   sendAuthTokenToServiceWorker(token) {
     if (this.serviceWorkerRegistration?.active) {
       try {
-        this.serviceWorkerRegistration.active.postMessage({ type: "SET_AUTH_TOKEN", token });
+        this.serviceWorkerRegistration.active.postMessage({
+          type: "SET_AUTH_TOKEN",
+          token
+        });
       } catch (e) {
-        console.error("[WorkerClient] Failed to send auth token to ServiceWorker:", 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 });
+        navigator.serviceWorker.controller.postMessage({
+          type: "SET_AUTH_TOKEN",
+          token
+        });
       } catch (e) {
-        console.error("[WorkerClient] Failed to send auth token to ServiceWorker.controller:", e);
+        console.error(
+          "[WorkerClient] Failed to send auth token to ServiceWorker.controller:",
+          e
+        );
       }
     } else {
       this.pendingAuthToken = token;
@@ -298,10 +341,14 @@ var WorkerClient = class {
   }
   async getConnectionStatus() {
     try {
-      const res = await this.request("GET_CONNECTION_STATUS", void 0, 2e3);
+      const res = await this.request(
+        "GET_CONNECTION_STATUS",
+        void 0,
+        2e3
+      );
       if (res && typeof res === "object" && "connected" in res)
         return !!res.connected;
-      return !!res.connected;
+      return !!res?.connected;
     } catch {
       return false;
     }
@@ -313,7 +360,10 @@ var WorkerClient = class {
         this.sharedWorkerPort.postMessage({ type: "SET_AUTH_TOKEN", token });
         this.pendingAuthToken = null;
       } catch (e) {
-        console.error("[WorkerClient] Failed to set auth token on SharedWorker:", e);
+        console.error(
+          "[WorkerClient] Failed to set auth token on SharedWorker:",
+          e
+        );
       }
     } else if (this.workerType === "service") {
       this.sendAuthTokenToServiceWorker(token);
@@ -373,7 +423,10 @@ async function queryEvents(filters) {
     request.onerror = () => reject(request.error);
   });
 }
+
+// libs/mcp-worker/src/index.ts
+var workerClient = new WorkerClient();
 export {
-  WorkerClient,
-  queryEvents
+  queryEvents,
+  workerClient
 };

package/mcp-service-worker.js

@@ -27831,9 +27831,9 @@ var WebSocketTransport = class {
 // libs/mcp-worker/src/lib/mcp-controller.ts
 var MAX_RECONNECT_DELAY = 3e4;
 var INITIAL_RECONNECT_DELAY = 1e3;
-var MCPController = class {
-  constructor(backendUrl, broadcastFn, requireAuth = true) {
-    this.backendUrl = backendUrl;
+var MCPController = class _MCPController {
+  constructor(backendUrl2, broadcastFn, requireAuth = true) {
+    this.backendUrl = backendUrl2;
     this.broadcastFn = broadcastFn;
     this.requireAuth = requireAuth;
   }
@@ -27979,61 +27979,133 @@ var MCPController = class {
       this.socket = null;
     }
   }
+  /**
+   * Factory helper to create an MCPController instance. Use this instead of
+   * replicating controller creation logic in callers.
+   */
+  static create(backendUrl2, broadcastFn, requireAuth = true) {
+    return new _MCPController(backendUrl2, broadcastFn, requireAuth);
+  }
 };
 
 // libs/mcp-worker/src/mcp-service-worker.ts
-var BACKEND_WS_URL = "ws://localhost:3001";
-var controller = new MCPController(BACKEND_WS_URL, (message) => {
-  self.clients.matchAll().then((clients) => {
-    clients.forEach((client) => {
-      try {
-        client.postMessage(message);
-      } catch (e) {
-        console.error("[ServiceWorker] Failed to post message to client:", e);
-      }
+var controller = null;
+var backendUrl = null;
+var pendingToken = null;
+var getController = () => {
+  if (!controller)
+    throw new Error("Worker not initialized (no backendUrl)");
+  return controller;
+};
+var setBackendUrl = (url2) => {
+  backendUrl = url2;
+  controller = null;
+  controller = MCPController.create(url2, (message) => {
+    self.clients.matchAll().then((clients) => {
+      clients.forEach((client) => {
+        try {
+          client.postMessage(message);
+        } catch (e) {
+          console.error("[ServiceWorker] Failed to post message to client:", e);
+        }
+      });
+    }).catch((err) => {
+      console.error("[ServiceWorker] Failed to match clients for broadcast:", err);
     });
-  }).catch((err) => {
-    console.error("[ServiceWorker] Failed to match clients for broadcast:", err);
   });
-});
+  return controller;
+};
 self.addEventListener("message", async (event) => {
   if (!event.data)
     return;
-  if (event.data.type === "SET_AUTH_TOKEN") {
-    controller.setAuthToken(event.data.token);
+  const msg = event.data;
+  if (msg["type"] === "INIT") {
+    const url2 = msg["backendUrl"];
+    if (!url2) {
+      console.error("[ServiceWorker] INIT missing backendUrl");
+      return;
+    }
+    try {
+      setBackendUrl(url2);
+      const token = msg["token"];
+      if (token) {
+        getController().setAuthToken(token);
+      } else if (pendingToken) {
+        getController().setAuthToken(pendingToken);
+        pendingToken = null;
+      }
+    } catch (e) {
+      console.error("[ServiceWorker] Failed to apply INIT:", e);
+    }
+    return;
+  }
+  if (msg["type"] === "SET_AUTH_TOKEN") {
+    const token = msg["token"];
+    if (!token)
+      return;
+    try {
+      if (controller) {
+        getController().setAuthToken(token);
+      } else {
+        pendingToken = token;
+      }
+    } catch (e) {
+      console.error("[ServiceWorker] Failed to set auth token:", e);
+    }
     return;
   }
-  if (event.data.type === "STORE_EVENT") {
+  if (msg["type"] === "STORE_EVENT") {
     event.waitUntil((async () => {
       try {
+        if (!backendUrl || !controller) {
+          if (event.ports && event.ports[0]) {
+            event.ports[0].postMessage({ success: false, error: "Worker not initialized" });
+          }
+          return;
+        }
         const userEvent = event.data.event;
-        await controller.handleStoreEvent(userEvent);
+        await getController().handleStoreEvent(userEvent);
         if (event.ports && event.ports[0]) {
           event.ports[0].postMessage({ success: true });
         }
       } catch (error48) {
         if (event.ports && event.ports[0]) {
-          event.ports[0].postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Unknown error" });
+          event.ports[0].postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Worker not initialized" });
         }
       }
     })());
-  } else if (event.data.type === "GET_EVENTS") {
+    return;
+  }
+  if (msg["type"] === "GET_EVENTS") {
     event.waitUntil((async () => {
       try {
-        const events = await controller.handleGetEvents();
+        if (!backendUrl || !controller) {
+          if (event.ports && event.ports[0]) {
+            event.ports[0].postMessage({ success: false, error: "Worker not initialized" });
+          }
+          return;
+        }
+        const events = await getController().handleGetEvents();
         if (event.ports && event.ports[0]) {
           event.ports[0].postMessage({ success: true, events });
         }
       } catch (error48) {
         if (event.ports && event.ports[0]) {
-          event.ports[0].postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Unknown error" });
+          event.ports[0].postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Worker not initialized" });
         }
       }
     })());
-  } else if (event.data.type === "GET_CONNECTION_STATUS") {
+    return;
+  }
+  if (msg["type"] === "GET_CONNECTION_STATUS") {
     if (event.ports && event.ports[0]) {
-      event.ports[0].postMessage({ success: true, connected: controller.getConnectionStatus() });
+      if (!backendUrl || !controller) {
+        event.ports[0].postMessage({ success: false, error: "Worker not initialized" });
+      } else {
+        event.ports[0].postMessage({ success: true, connected: getController().getConnectionStatus() });
+      }
     }
+    return;
   }
 });
 self.addEventListener("install", (event) => {

package/mcp-shared-worker.js

@@ -27831,9 +27831,9 @@ var WebSocketTransport = class {
 // libs/mcp-worker/src/lib/mcp-controller.ts
 var MAX_RECONNECT_DELAY = 3e4;
 var INITIAL_RECONNECT_DELAY = 1e3;
-var MCPController = class {
-  constructor(backendUrl, broadcastFn, requireAuth = true) {
-    this.backendUrl = backendUrl;
+var MCPController = class _MCPController {
+  constructor(backendUrl2, broadcastFn, requireAuth = true) {
+    this.backendUrl = backendUrl2;
     this.broadcastFn = broadcastFn;
     this.requireAuth = requireAuth;
   }
@@ -27979,27 +27979,48 @@ var MCPController = class {
       this.socket = null;
     }
   }
+  /**
+   * Factory helper to create an MCPController instance. Use this instead of
+   * replicating controller creation logic in callers.
+   */
+  static create(backendUrl2, broadcastFn, requireAuth = true) {
+    return new _MCPController(backendUrl2, broadcastFn, requireAuth);
+  }
 };
 
 // libs/mcp-worker/src/mcp-shared-worker.ts
-var BACKEND_WS_URL = "ws://localhost:3001";
 var connectedPorts = [];
-var controller = new MCPController(BACKEND_WS_URL, (message) => {
-  connectedPorts.forEach((port) => {
-    try {
-      port.postMessage(message);
-    } catch (error48) {
-      const idx = connectedPorts.indexOf(port);
-      if (idx > -1)
-        connectedPorts.splice(idx, 1);
-    }
+var controller = null;
+var backendUrl = null;
+var pendingToken = null;
+var getController = () => {
+  if (!controller)
+    throw new Error("Worker not initialized (no backendUrl)");
+  return controller;
+};
+var setBackendUrl = (url2) => {
+  backendUrl = url2;
+  controller = null;
+  controller = MCPController.create(url2, (message) => {
+    connectedPorts.forEach((port) => {
+      try {
+        port.postMessage(message);
+      } catch (error48) {
+        const idx = connectedPorts.indexOf(port);
+        if (idx > -1)
+          connectedPorts.splice(idx, 1);
+        console.debug("[SharedWorker] Failed to broadcast to a port (removed):", error48);
+      }
+    });
   });
-});
+  return controller;
+};
 self.onconnect = (event) => {
   const port = event.ports[0];
   connectedPorts.push(port);
   try {
-    port.postMessage({ type: "CONNECTION_STATUS", connected: controller.getConnectionStatus() });
+    const connected = controller ? getController().getConnectionStatus() : false;
+    port.postMessage({ type: "CONNECTION_STATUS", connected });
   } catch (err) {
     console.error("[SharedWorker] Failed to post initial status to port:", err);
   }
@@ -28007,23 +28028,93 @@ self.onconnect = (event) => {
     if (!ev.data)
       return;
     const messageData = ev.data;
+    if (messageData.type === "INIT") {
+      const url2 = messageData["backendUrl"];
+      if (!url2) {
+        try {
+          port.postMessage({ success: false, error: "INIT missing backendUrl" });
+        } catch (e) {
+          console.debug("[SharedWorker] Failed to reply to INIT with missing backendUrl:", e);
+        }
+        return;
+      }
+      try {
+        setBackendUrl(url2);
+        const token = messageData["token"];
+        if (token) {
+          getController().setAuthToken(token);
+        } else if (pendingToken) {
+          getController().setAuthToken(pendingToken);
+          pendingToken = null;
+        }
+        try {
+          port.postMessage({ success: true });
+        } catch (e) {
+          console.debug("[SharedWorker] Failed to post INIT success to port:", e);
+        }
+      } catch (e) {
+        try {
+          port.postMessage({ success: false, error: String(e) });
+        } catch (er) {
+          console.debug("[SharedWorker] Failed to post INIT failure to port:", er);
+        }
+      }
+      return;
+    }
     if (messageData.type === "SET_AUTH_TOKEN") {
-      const newToken = messageData.token;
-      controller.setAuthToken(newToken);
+      const newToken = messageData["token"];
+      if (!newToken)
+        return;
+      if (controller) {
+        try {
+          getController().setAuthToken(newToken);
+        } catch (e) {
+          console.error("[SharedWorker] Failed to set auth token:", e);
+        }
+      } else {
+        pendingToken = newToken;
+      }
+      return;
+    }
+    if (messageData.type === "SET_BACKEND_URL") {
+      const url2 = messageData["url"];
+      if (!url2)
+        return;
+      try {
+        setBackendUrl(url2);
+        if (pendingToken) {
+          try {
+            getController().setAuthToken(pendingToken);
+            pendingToken = null;
+          } catch (e) {
+            console.error("[SharedWorker] Failed to set pending auth token after SET_BACKEND_URL:", e);
+          }
+        }
+      } catch (e) {
+        console.error("[SharedWorker] Failed to set backend URL:", e);
+      }
       return;
     }
     if (messageData.type === "STORE_EVENT") {
       try {
+        if (!backendUrl || !controller) {
+          try {
+            port.postMessage({ success: false, error: "Worker not initialized" });
+          } catch (e) {
+            console.debug("[SharedWorker] Failed to post uninitialized error for STORE_EVENT:", e);
+          }
+          return;
+        }
         const userEvent = messageData.event;
-        await controller.handleStoreEvent(userEvent);
+        await getController().handleStoreEvent(userEvent);
         try {
           port.postMessage({ success: true });
-        } catch (error48) {
-          console.error("[SharedWorker] Failed to post success to port:", error48);
+        } catch (e) {
+          console.debug("[SharedWorker] Failed to post STORE_EVENT success to port:", e);
         }
       } catch (error48) {
         try {
-          port.postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Unknown error" });
+          port.postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Worker not initialized" });
         } catch (e) {
           console.error("[SharedWorker] Failed to post failure to port:", e);
         }
@@ -28032,7 +28123,15 @@ self.onconnect = (event) => {
     }
     if (messageData.type === "GET_EVENTS") {
       try {
-        const events = await controller.handleGetEvents();
+        if (!backendUrl || !controller) {
+          try {
+            port.postMessage({ success: false, error: "Worker not initialized" });
+          } catch (e) {
+            console.debug("[SharedWorker] Failed to post uninitialized error for GET_EVENTS:", e);
+          }
+          return;
+        }
+        const events = await getController().handleGetEvents();
         try {
           port.postMessage({ success: true, events });
         } catch (error48) {
@@ -28040,7 +28139,7 @@ self.onconnect = (event) => {
         }
       } catch (error48) {
         try {
-          port.postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Unknown error" });
+          port.postMessage({ success: false, error: error48 instanceof Error ? error48.message : "Worker not initialized" });
         } catch (e) {
           console.error("[SharedWorker] Failed to post failure to port:", e);
         }
@@ -28049,9 +28148,22 @@ self.onconnect = (event) => {
     }
     if (messageData.type === "GET_CONNECTION_STATUS") {
       try {
-        port.postMessage({ success: true, connected: controller.getConnectionStatus() });
+        if (!backendUrl || !controller) {
+          try {
+            port.postMessage({ success: false, error: "Worker not initialized" });
+          } catch (e) {
+            console.debug("[SharedWorker] Failed to post uninitialized error for GET_CONNECTION_STATUS:", e);
+          }
+          return;
+        }
+        port.postMessage({ success: true, connected: getController().getConnectionStatus() });
       } catch (error48) {
-        console.error("[SharedWorker] Failed to post connection status to port:", error48);
+        console.debug("[SharedWorker] GET_CONNECTION_STATUS failed:", error48);
+        try {
+          port.postMessage({ success: false, error: "Worker not initialized" });
+        } catch (e) {
+          console.debug("[SharedWorker] Failed to post GET_CONNECTION_STATUS failure:", e);
+        }
       }
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-fe/mcp-worker",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "private": false,
   "type": "module",
   "main": "./index.js",

package/src/index.d.ts

@@ -1,3 +1,5 @@
-export * from './lib/worker-client';
+import { WorkerClient } from './lib/worker-client';
+export { type WorkerClientInitOptions } from './lib/worker-client';
 export { queryEvents, type UserEvent } from './lib/database';
+export declare const workerClient: WorkerClient;
 //# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../libs/mcp-worker/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../libs/mcp-worker/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAO,qBAAqB,CAAC;AAElD,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG7D,eAAO,MAAM,YAAY,cAAqB,CAAC"}

package/src/lib/mcp-controller.d.ts

@@ -24,5 +24,10 @@ export declare class MCPController {
     handleGetEvents(): Promise<ReturnType<typeof queryEvents>>;
     getConnectionStatus(): boolean;
     dispose(): void;
+    /**
+     * Factory helper to create an MCPController instance. Use this instead of
+     * replicating controller creation logic in callers.
+     */
+    static create(backendUrl: string, broadcastFn: BroadcastFn, requireAuth?: boolean): MCPController;
 }
 //# sourceMappingURL=mcp-controller.d.ts.map

package/src/lib/mcp-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-controller.d.ts","sourceRoot":"","sources":["../../../../../libs/mcp-worker/src/lib/mcp-controller.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAc,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOhE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAErD,qBAAa,aAAa;IAQZ,OAAO,CAAC,UAAU;IAAU,OAAO,CAAC,WAAW;IAP3D,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,iBAAiB,CAA+C;IACxE,OAAO,CAAC,WAAW,CAAU;gBAET,UAAU,EAAE,MAAM,EAAU,WAAW,EAAE,WAAW,EAAE,WAAW,UAAO;IAI5F,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,aAAa;IAOR,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAyGvC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAkBlC,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IAIhE,mBAAmB,IAAI,OAAO;IAI9B,OAAO,IAAI,IAAI;CAWvB"}
+{"version":3,"file":"mcp-controller.d.ts","sourceRoot":"","sources":["../../../../../libs/mcp-worker/src/lib/mcp-controller.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAc,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOhE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAErD,qBAAa,aAAa;IAQZ,OAAO,CAAC,UAAU;IAAU,OAAO,CAAC,WAAW;IAP3D,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,iBAAiB,CAA+C;IACxE,OAAO,CAAC,WAAW,CAAU;gBAET,UAAU,EAAE,MAAM,EAAU,WAAW,EAAE,WAAW,EAAE,WAAW,UAAO;IAI5F,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,aAAa;IAOR,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAyGvC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAkBlC,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IAIhE,mBAAmB,IAAI,OAAO;IAI9B,OAAO,IAAI,IAAI;IAYtB;;;OAGG;WACW,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,UAAO,GAAG,aAAa;CAGtG"}

package/src/lib/worker-client.d.ts

@@ -1,15 +1,64 @@
+/**
+ * WorkerClient — adapter for communicating with a worker process.
+ *
+ * Responsibilities
+ * - Chooses the transport: prefers a SharedWorker and falls back to a ServiceWorker.
+ * - Provides a request/response API (MessageChannel) and a fire-and-forget post API.
+ * - Tracks connection status and exposes a subscription API for CONNECTION_STATUS updates.
+ * - Buffers an auth token (SET_AUTH_TOKEN) when no worker is available and sends it when a
+ *   worker becomes active.
+ *
+ * Public API
+ * - async init(registration?: ServiceWorkerRegistration): Promise<void>
+ *   Initializes the client. If a ServiceWorkerRegistration is provided, it will be used directly.
+ *
+ * - async request<T = any>(type: string, payload?: Record<string, unknown>, timeoutMs = 5000): Promise<T>
+ *   Sends a request expecting a reply via MessageChannel. Rejects on timeout, missing worker,
+ *   or a worker-reported error.
+ *
+ * - async post(type: string, payload?: Record<string, unknown>): Promise<void>
+ *   Fire-and-forget message. If type === 'SET_AUTH_TOKEN' and no worker is available, the token
+ *   is queued and sent after initialization.
+ *
+ * - getConnectionStatus(): Promise<boolean>
+ *   Attempts to obtain the current connection status (uses GET_CONNECTION_STATUS request with a
+ *   short timeout) and returns a boolean.
+ *
+ * - onConnectionStatus(cb: (connected: boolean) => void): void
+ * - offConnectionStatus(cb: (connected: boolean) => void): void
+ *   Subscribe/unsubscribe to connection status updates.
+ *
+ * Error model and edge cases
+ * - init may throw if neither SharedWorker nor ServiceWorker is supported or registration fails.
+ * - request may reject due to timeout, no worker registered, missing active ServiceWorker, or a
+ *   worker-reported error payload.
+ * - post does not throw for transient postMessage failures; SET_AUTH_TOKEN is queued instead.
+ * - Concurrent init calls are serialized via an internal mutex (initPromise).
+ *
+ */
+export type WorkerClientInitOptions = {
+    /** URL to the SharedWorker script (optional) */
+    sharedWorkerUrl?: string;
+    /** URL to the ServiceWorker script (optional) */
+    serviceWorkerUrl?: string;
+    /** Backend WebSocket URL to configure inside the worker (optional) */
+    backendWsUrl?: string;
+};
 export declare class WorkerClient {
+    private sharedWorkerUrl;
+    private serviceWorkerUrl;
+    private backendWsUrl;
     private serviceWorkerRegistration;
     private sharedWorker;
     private sharedWorkerPort;
     private workerType;
     private pendingAuthToken;
     private connectionStatusCallbacks;
-    private serviceWorkerMessageHandler;
     private initPromise;
-    init(registration?: ServiceWorkerRegistration): Promise<void>;
+    init(registrationOrOptions?: ServiceWorkerRegistration | WorkerClientInitOptions): Promise<void>;
+    private initSharedWorker;
     private initServiceWorkerFallback;
-    request<T = any>(type: string, payload?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    request<T = unknown>(type: string, payload?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
     post(type: string, payload?: Record<string, unknown>): Promise<void>;
     private sendAuthTokenToServiceWorker;
     onConnectionStatus(cb: (connected: boolean) => void): void;

package/src/lib/worker-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-client.d.ts","sourceRoot":"","sources":["../../../../../libs/mcp-worker/src/lib/worker-client.ts"],"names":[],"mappings":"AAEA,qBAAa,YAAY;IACvB,OAAO,CAAC,yBAAyB,CAA0C;IAC3E,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,OAAO,CAAC,yBAAyB,CAAgD;IACjF,OAAO,CAAC,2BAA2B,CAA6C;IAGhF,OAAO,CAAC,WAAW,CAA8B;IAGpC,IAAI,CAAC,YAAY,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;YAsI5D,yBAAyB;IA4C1B,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAoF/F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCjF,OAAO,CAAC,4BAA4B;IAoB7B,kBAAkB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAI1D,mBAAmB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAIrD,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAU7C,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAiBzC"}
+{"version":3,"file":"worker-client.d.ts","sourceRoot":"","sources":["../../../../../libs/mcp-worker/src/lib/worker-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAMH,MAAM,MAAM,uBAAuB,GAAG;IACpC,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qBAAa,YAAY;IAEvB,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,gBAAgB,CAA4B;IAEpD,OAAO,CAAC,YAAY,CAAwC;IAE5D,OAAO,CAAC,yBAAyB,CAA0C;IAC3E,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,OAAO,CAAC,yBAAyB,CACrB;IAGZ,OAAO,CAAC,WAAW,CAA8B;IAIpC,IAAI,CACf,qBAAqB,CAAC,EAAE,yBAAyB,GAAG,uBAAuB,GAC1E,OAAO,CAAC,IAAI,CAAC;YAkEF,gBAAgB;YAwFhB,yBAAyB;IA8C1B,OAAO,CAAC,CAAC,GAAG,OAAO,EAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,SAAS,SAAO,GACf,OAAO,CAAC,CAAC,CAAC;IAsFA,IAAI,CACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC;IAkDhB,OAAO,CAAC,4BAA4B;IAmC7B,kBAAkB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAI1D,mBAAmB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAIrD,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;IAe7C,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAoBzC"}

package/src/mcp-shared-worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-shared-worker.d.ts","sourceRoot":"","sources":["../../../../libs/mcp-worker/src/mcp-shared-worker.ts"],"names":[],"mappings":"AACA;;;;;;GAMG"}
+{"version":3,"file":"mcp-shared-worker.d.ts","sourceRoot":"","sources":["../../../../libs/mcp-worker/src/mcp-shared-worker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}