@mcp-fe/mcp-worker 0.1.7 → 0.1.8

package/README.md

@@ -67,6 +67,31 @@ Frontend App ←→ WorkerClient ←→ Web Worker ←→ WebSocket ←→ MCP P
 5. **MCP Proxy** - Bridges browser with AI agents
 6. **AI Agent** - Queries your app via MCP protocol
 
+### Project Structure
+
+The library is organized into three main directories:
+
+```
+libs/mcp-worker/src/
+├── client/              # Client-side code (application runtime)
+│   ├── worker-client.ts # Main WorkerClient class
+│   └── index.ts         # Client API exports
+├── worker/              # Worker-side code (background processing)
+│   ├── mcp-controller.ts    # MCP server controller
+│   ├── mcp-server.ts        # MCP server setup
+│   ├── tab-manager.ts       # Multi-tab coordination
+│   ├── tool-registry.ts     # Dynamic tool management
+│   └── built-in-tools.ts    # Default MCP tools
+└── shared/              # Shared code (both contexts)
+    ├── types.ts         # TypeScript type definitions
+    ├── logger.ts        # Logging utilities
+    └── database.ts      # IndexedDB operations
+```
+
+**Entry points:**
+- `mcp-shared-worker.ts` - SharedWorker implementation (preferred)
+- `mcp-service-worker.ts` - ServiceWorker fallback
+
 ## Quick Start
 
 ### Installation
@@ -130,6 +155,7 @@ await workerClient.registerTool(
 
 - **[Quick Start Guide](./docs/guide.md)** - Complete guide to dynamic tool registration
 - **[API Reference](./docs/api.md)** - Full API documentation
+- **[Project Structure](./docs/project-structure.md)** - Codebase organization explained
 - **[Worker Details](./docs/worker-details.md)** - Implementation details
 - **[Architecture](./docs/architecture.md)** - How the proxy pattern works
 - **[Initialization](./docs/initialization.md)** - Init queue handling

package/docs/index.md

@@ -12,6 +12,7 @@ Complete guide to all documentation and examples in the MCP Worker library.
 | **Complete API reference** | [API Reference](./api.md) |
 | **Multi-tab applications** | [Multi-Tab Guide](./multi-tab.md) |
 | **Worker implementation** | [Worker Details](./worker-details.md) |
+| **Understand codebase structure** | [Project Structure](./project-structure.md) |
 | **Use with React** | [React Hooks Guide](../../react-event-tracker/REACT_MCP_TOOLS.md) |
 | **Understand architecture** | [Architecture](./architecture.md) |
 | **Handle initialization** | [Initialization](./initialization.md) |
@@ -29,16 +30,26 @@ libs/mcp-worker/
 │   ├── multi-tab.md                       ← Multi-tab support
 │   ├── worker-details.md                  ← Worker implementation
 │   ├── architecture.md                    ← Technical architecture
-│   └── initialization.md                  ← Init handling
+│   ├── initialization.md                  ← Init handling
+│   ├── project-structure.md               ← Codebase organization
+│   └── tab-manager.md                     ← Tab management
 │
 ├── examples/                              ← Code examples
 │   ├── README.md                          ← Examples guide
 │   ├── quick-start.ts                     ← Simple examples
-│   └── dynamic-tools.ts                   ← Advanced patterns
+│   ├── dynamic-tools.ts                   ← Advanced patterns
+│   └── structured-output.ts               ← Structured outputs
 │
 └── src/                                   ← Source code
-    └── lib/
-        └── worker-client.ts
+    ├── client/                            ← Application runtime
+    │   └── worker-client.ts
+    ├── worker/                            ← Worker implementation
+    │   ├── mcp-controller.ts
+    │   └── ...
+    └── shared/                            ← Shared utilities
+        ├── types.ts
+        ├── logger.ts
+        └── database.ts
 
 libs/react-event-tracker/
 ├── REACT_MCP_TOOLS.md                     ← React hooks docs

package/docs/initialization.md

@@ -182,7 +182,7 @@ For contributors:
 - 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`
+- `libs/mcp-worker/src/client/worker-client.ts`
+- `libs/mcp-worker/src/worker/mcp-controller.ts`
 
 

package/docs/project-structure.md

@@ -0,0 +1,172 @@
+# Project Structure
+
+This document explains the organization of the `@mcp-fe/mcp-worker` codebase.
+
+## Directory Layout
+
+```
+libs/mcp-worker/src/
+├── index.ts                    # Main entry point (re-exports from client/)
+├── mcp-shared-worker.ts        # SharedWorker entry point
+├── mcp-service-worker.ts       # ServiceWorker entry point
+├── client/                     # Client-side code (application runtime)
+│   ├── index.ts                # Client API exports
+│   └── worker-client.ts        # Main WorkerClient class
+├── worker/                     # Worker-side code (background processing)
+│   ├── index.ts                # Worker internal exports
+│   ├── mcp-controller.ts       # MCP server controller & lifecycle
+│   ├── mcp-server.ts           # MCP server setup & handlers
+│   ├── websocket-transport.ts  # WebSocket transport for MCP
+│   ├── tool-registry.ts        # Dynamic tool registration
+│   ├── tab-manager.ts          # Multi-tab coordination
+│   ├── built-in-tools.ts       # Default MCP tools
+│   └── tab-manager.spec.ts     # Tests for TabManager
+└── shared/                     # Shared code (both contexts)
+    ├── types.ts                # TypeScript type definitions
+    ├── logger.ts               # Logging utilities
+    └── database.ts             # IndexedDB operations
+```
+
+## Module Responsibilities
+
+### Client (`client/`)
+
+**Purpose:** Code that runs in the main browser thread (your application).
+
+**Key Files:**
+- `worker-client.ts` - Main API for communicating with workers
+  - Handles worker initialization (SharedWorker vs ServiceWorker)
+  - Manages tool registration and lifecycle
+  - Handles multi-tab coordination
+  - Provides request/response messaging
+
+**Used by:** Your application code
+
+**Example:**
+```typescript
+import { workerClient } from '@mcp-fe/mcp-worker';
+await workerClient.init();
+```
+
+### Worker (`worker/`)
+
+**Purpose:** Code that runs inside Web Workers (background processing).
+
+**Key Files:**
+- `mcp-controller.ts` - Main controller for MCP server lifecycle
+  - WebSocket connection management
+  - Tool call routing and execution
+  - Tab management coordination
+  - Event storage and querying
+
+- `mcp-server.ts` - MCP server setup using @modelcontextprotocol/sdk
+  - Request handlers (ListTools, CallTool)
+  - Server configuration and capabilities
+
+- `tool-registry.ts` - Dynamic tool management
+  - Tool definition storage
+  - Handler registration and lookup
+  - Tool lifecycle management
+
+- `tab-manager.ts` - Multi-tab coordination
+  - Tab registration and tracking
+  - Active tab management
+  - Smart tool routing across tabs
+
+- `built-in-tools.ts` - Default MCP tools
+  - Event querying tools
+  - Tab listing tools
+  - Navigation history tools
+
+**Used by:** Worker entry points (`mcp-shared-worker.ts`, `mcp-service-worker.ts`)
+
+### Shared (`shared/`)
+
+**Purpose:** Code used by both client and worker contexts.
+
+**Key Files:**
+- `types.ts` - TypeScript type definitions
+  - `UserEvent`, `ToolDefinition`, `ToolHandler`
+  - `TabInfo`, `EventFilters`, etc.
+  - Ensures type consistency across contexts
+
+- `logger.ts` - Logging utilities
+  - Environment-aware logging (dev vs production)
+  - Consistent logging interface
+  - Works in both main thread and workers
+
+- `database.ts` - IndexedDB operations
+  - Event storage and retrieval
+  - Query filtering and pagination
+  - Available in both contexts (IndexedDB works everywhere)
+
+**Used by:** Both client and worker code
+
+## Communication Flow
+
+```
+Application Code
+    ↓ (imports)
+client/worker-client.ts
+    ↓ (postMessage)
+mcp-shared-worker.ts or mcp-service-worker.ts
+    ↓ (uses)
+worker/mcp-controller.ts
+    ↓ (uses)
+worker/mcp-server.ts
+    ↓ (uses)
+worker/tool-registry.ts
+    ↓ (WebSocket)
+MCP Proxy Server
+```
+
+## Import Patterns
+
+### For Application Code
+
+```typescript
+// Import from the main package
+import { workerClient, type ToolDefinition } from '@mcp-fe/mcp-worker';
+```
+
+### Internal Worker Code
+
+```typescript
+// Worker modules import from shared/
+import { logger } from '../shared/logger';
+import type { UserEvent } from '../shared/types';
+
+// Worker modules import from other worker modules
+import { toolRegistry } from './tool-registry';
+import { TabManager } from './tab-manager';
+```
+
+### Internal Client Code
+
+```typescript
+// Client modules import from shared/
+import { logger } from '../shared/logger';
+import type { ToolDefinition } from '../shared/types';
+```
+
+## Why This Structure?
+
+### Clear Separation of Concerns
+- **Client code** only deals with communication and API
+- **Worker code** handles MCP protocol and business logic
+- **Shared code** provides common utilities and types
+
+### Better Tree-Shaking
+- Applications only import client code
+- Worker bundles only include worker code
+- No unnecessary code in either bundle
+
+### Maintainability
+- Easy to find where specific functionality lives
+- Clear boundaries between contexts
+- Prevents accidental mixing of client/worker code
+
+### Future-Proof
+- Ready for splitting into separate npm packages if needed
+- Can add more worker types (e.g., dedicated workers)
+- Easy to add more shared utilities

package/index.js

@@ -1,4 +1,4 @@
-// libs/mcp-worker/src/lib/logger.ts
+// libs/mcp-worker/src/shared/logger.ts
 var isProduction = typeof process !== "undefined" && true;
 var mcpDebug = typeof process !== "undefined" && process.env?.["MCP_DEBUG"];
 var debugEnabled = mcpDebug === "true" || !isProduction && mcpDebug !== "false";
@@ -26,7 +26,7 @@ var logger = {
   }
 };
 
-// libs/mcp-worker/src/lib/worker-client.ts
+// libs/mcp-worker/src/client/worker-client.ts
 var WorkerClient = class _WorkerClient {
   // Configurable worker script URLs (defaults kept for backward compatibility)
   sharedWorkerUrl = "/mcp-shared-worker.js";
@@ -1046,7 +1046,10 @@ var WorkerClient = class _WorkerClient {
   }
 };
 
-// libs/mcp-worker/src/lib/database.ts
+// libs/mcp-worker/src/client/index.ts
+var workerClient = new WorkerClient();
+
+// libs/mcp-worker/src/shared/database.ts
 var DB_NAME = "user-activity-db";
 var DB_VERSION = 1;
 var STORE_NAME = "user-events";
@@ -1066,6 +1069,33 @@ async function initDB() {
     };
   });
 }
+async function storeEvent(event) {
+  const db = await initDB();
+  const transaction = db.transaction([STORE_NAME], "readwrite");
+  const store = transaction.objectStore(STORE_NAME);
+  const eventWithId = {
+    ...event,
+    id: `${event.timestamp}-${Math.random().toString(36).substr(2, 9)}`
+  };
+  await new Promise((resolve, reject) => {
+    const request = store.add(eventWithId);
+    request.onsuccess = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+  const countRequest = store.count();
+  countRequest.onsuccess = () => {
+    if (countRequest.result > 1e3) {
+      const index = store.index("timestamp");
+      const getAllRequest = index.getAll();
+      getAllRequest.onsuccess = () => {
+        const events = getAllRequest.result;
+        events.sort((a, b) => a.timestamp - b.timestamp);
+        const toDelete = events.slice(0, events.length - 1e3);
+        toDelete.forEach((event2) => store.delete(event2.id));
+      };
+    }
+  };
+}
 async function queryEvents(filters) {
   const db = await initDB();
   const transaction = db.transaction([STORE_NAME], "readonly");
@@ -1096,256 +1126,10 @@ async function queryEvents(filters) {
     request.onerror = () => reject(request.error);
   });
 }
-
-// libs/mcp-worker/src/lib/tab-manager.ts
-var TabManager = class {
-  // Registry of all active tabs
-  tabRegistry = /* @__PURE__ */ new Map();
-  // Currently active/focused tab
-  activeTabId = null;
-  // Tool handlers per tab: Map<ToolName, Set<TabId>>
-  toolHandlersByTab = /* @__PURE__ */ new Map();
-  /**
-   * Register a new tab
-   */
-  registerTab(tabId, url, title) {
-    if (!tabId) {
-      logger.warn("[TabManager] Cannot register tab: missing tabId");
-      return;
-    }
-    this.tabRegistry.set(tabId, {
-      url: url || "",
-      title: title || "",
-      lastSeen: Date.now()
-    });
-    logger.log(`[TabManager] Registered tab: ${tabId} (${title})`);
-  }
-  /**
-   * Set the active/focused tab
-   */
-  setActiveTab(tabId) {
-    if (!tabId) {
-      logger.warn("[TabManager] Cannot set active tab: missing tabId");
-      return;
-    }
-    this.activeTabId = tabId;
-    logger.log(`[TabManager] Active tab changed: ${tabId}`);
-    const tab = this.tabRegistry.get(tabId);
-    if (tab) {
-      tab.lastSeen = Date.now();
-    }
-  }
-  /**
-   * Get the currently active tab ID
-   */
-  getActiveTabId() {
-    return this.activeTabId;
-  }
-  /**
-   * Get all registered tabs
-   */
-  getAllTabs() {
-    return Array.from(this.tabRegistry.entries()).map(([tabId, info]) => ({
-      tabId,
-      ...info
-    }));
-  }
-  /**
-   * Get tab info by ID
-   */
-  getTabInfo(tabId) {
-    return this.tabRegistry.get(tabId);
-  }
-  /**
-   * Check if tab exists
-   */
-  hasTab(tabId) {
-    return this.tabRegistry.has(tabId);
-  }
-  /**
-   * Remove a tab from registry
-   */
-  removeTab(tabId) {
-    const existed = this.tabRegistry.delete(tabId);
-    if (existed) {
-      logger.log(`[TabManager] Removed tab: ${tabId}`);
-      if (this.activeTabId === tabId) {
-        this.activeTabId = null;
-      }
-      this.cleanupTabTools(tabId);
-    }
-    return existed;
-  }
-  /**
-   * Register a tool for a specific tab
-   */
-  registerToolForTab(toolName, tabId) {
-    if (!this.toolHandlersByTab.has(toolName)) {
-      this.toolHandlersByTab.set(toolName, /* @__PURE__ */ new Set());
-    }
-    const tabHandlers = this.toolHandlersByTab.get(toolName);
-    const isNewTab = !tabHandlers.has(tabId);
-    tabHandlers.add(tabId);
-    if (isNewTab) {
-      logger.log(
-        `[TabManager] Tab ${tabId} registered tool '${toolName}' (${tabHandlers.size} tab(s) total)`
-      );
-    } else {
-      logger.log(
-        `[TabManager] Tab ${tabId} re-registered tool '${toolName}' (already tracked)`
-      );
-    }
-    return isNewTab;
-  }
-  /**
-   * Unregister a tool from a specific tab
-   */
-  unregisterToolFromTab(toolName, tabId) {
-    const tabHandlers = this.toolHandlersByTab.get(toolName);
-    if (!tabHandlers || !tabHandlers.has(tabId)) {
-      return { wasRemoved: false, remainingTabs: 0, wasActiveTab: false };
-    }
-    const wasActiveTab = tabId === this.activeTabId;
-    tabHandlers.delete(tabId);
-    const remainingTabs = tabHandlers.size;
-    logger.log(
-      `[TabManager] Removed tab ${tabId} from tool '${toolName}' (${remainingTabs} tab(s) remaining)`
-    );
-    if (remainingTabs === 0) {
-      this.toolHandlersByTab.delete(toolName);
-    }
-    return { wasRemoved: true, remainingTabs, wasActiveTab };
-  }
-  /**
-   * Get all tabs that have a specific tool
-   */
-  getTabsForTool(toolName) {
-    return this.toolHandlersByTab.get(toolName) || /* @__PURE__ */ new Set();
-  }
-  /**
-   * Check if a tab has a specific tool
-   */
-  tabHasTool(toolName, tabId) {
-    const tabHandlers = this.toolHandlersByTab.get(toolName);
-    return tabHandlers ? tabHandlers.has(tabId) : false;
-  }
-  /**
-   * Smart routing: determine which tab should handle a tool call
-   *
-   * Priority:
-   * 1. Explicit tabId parameter (if provided and valid)
-   * 2. Only one tab has tool -> use it (regardless of focus)
-   * 3. Active tab has tool -> use it
-   * 4. Active tab doesn't have tool -> use first available
-   * 5. No active tab -> use first available
-   */
-  routeToolCall(toolName, explicitTabId) {
-    const tabHandlers = this.toolHandlersByTab.get(toolName);
-    if (!tabHandlers || tabHandlers.size === 0) {
-      return null;
-    }
-    if (explicitTabId) {
-      if (tabHandlers.has(explicitTabId)) {
-        return {
-          targetTabId: explicitTabId,
-          reason: "explicit tabId parameter"
-        };
-      } else {
-        return null;
-      }
-    }
-    if (tabHandlers.size === 1) {
-      const targetTabId = tabHandlers.values().next().value;
-      return {
-        targetTabId,
-        reason: "only one tab has tool"
-      };
-    }
-    if (this.activeTabId && tabHandlers.has(this.activeTabId)) {
-      return {
-        targetTabId: this.activeTabId,
-        reason: "active tab has tool"
-      };
-    }
-    const firstTab = tabHandlers.values().next().value;
-    const reason = this.activeTabId ? "active tab lacks tool, using first available" : "no active tab, using first available";
-    return {
-      targetTabId: firstTab,
-      reason
-    };
-  }
-  /**
-   * Get routing statistics for debugging
-   */
-  getRoutingInfo(toolName) {
-    const tabHandlers = this.toolHandlersByTab.get(toolName);
-    const tabsWithTool = tabHandlers ? Array.from(tabHandlers) : [];
-    return {
-      toolExists: tabsWithTool.length > 0,
-      tabsWithTool,
-      activeTabHasTool: this.activeTabId ? this.tabHasTool(toolName, this.activeTabId) : false,
-      recommendedTab: this.routeToolCall(toolName)?.targetTabId || null
-    };
-  }
-  /**
-   * Clean up all tools for a specific tab
-   * @private
-   */
-  cleanupTabTools(tabId) {
-    const removedTools = [];
-    for (const [toolName, tabHandlers] of this.toolHandlersByTab.entries()) {
-      if (tabHandlers.has(tabId)) {
-        tabHandlers.delete(tabId);
-        removedTools.push(toolName);
-        if (tabHandlers.size === 0) {
-          this.toolHandlersByTab.delete(toolName);
-        }
-      }
-    }
-    if (removedTools.length > 0) {
-      logger.log(
-        `[TabManager] Cleaned up ${removedTools.length} tool(s) for tab ${tabId}: ${removedTools.join(", ")}`
-      );
-    }
-  }
-  /**
-   * Get statistics for monitoring
-   */
-  getStats() {
-    const toolsPerTab = {};
-    for (const [tabId] of this.tabRegistry) {
-      let toolCount = 0;
-      for (const tabHandlers of this.toolHandlersByTab.values()) {
-        if (tabHandlers.has(tabId)) {
-          toolCount++;
-        }
-      }
-      toolsPerTab[tabId] = toolCount;
-    }
-    return {
-      totalTabs: this.tabRegistry.size,
-      activeTabId: this.activeTabId,
-      totalTools: this.toolHandlersByTab.size,
-      toolsPerTab
-    };
-  }
-  /**
-   * Clear all data (for testing)
-   */
-  clear() {
-    this.tabRegistry.clear();
-    this.activeTabId = null;
-    this.toolHandlersByTab.clear();
-    logger.log("[TabManager] Cleared all data");
-  }
-};
-
-// libs/mcp-worker/src/index.ts
-var workerClient = new WorkerClient();
 export {
-  TabManager,
   WorkerClient,
   logger,
   queryEvents,
+  storeEvent,
   workerClient
 };