@mcp-fe/mcp-worker 0.2.0 → 0.2.2

package/docs/project-structure.md

@@ -1,172 +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
+# 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/docs/tab-manager.md

@@ -1,150 +1,150 @@
-# TabManager
-
-Manages browser tabs and tool registration routing.
-
-## API
-
-### Tab Management
-
-```typescript
-// Register tab
-tabManager.registerTab(tabId, url, title);
-
-// Set active tab
-tabManager.setActiveTab(tabId);
-
-// Get active tab
-const activeId = tabManager.getActiveTabId(); // → string | null
-
-// Get all tabs
-const tabs = tabManager.getAllTabs(); // → TabInfo[]
-
-// Remove tab
-tabManager.removeTab(tabId); // → boolean
-```
-
-### Tool Registration
-
-```typescript
-// Register tool for tab
-const isNew = tabManager.registerToolForTab(toolName, tabId);
-
-// Unregister tool from tab
-const result = tabManager.unregisterToolFromTab(toolName, tabId);
-// → { wasRemoved, remainingTabs, wasActiveTab }
-
-// Get tabs with tool
-const tabs = tabManager.getTabsForTool(toolName); // → Set<string>
-
-// Check if tab has tool
-const has = tabManager.tabHasTool(toolName, tabId); // → boolean
-```
-
-### Smart Routing
-
-```typescript
-const route = tabManager.routeToolCall(toolName, explicitTabId?);
-// → { targetTabId: string, reason: string } | null
-```
-
-**Priority:**
-1. Explicit `tabId` (if valid)
-2. Only one tab has tool → use it
-3. Active tab has tool → use it
-4. Use first available
-
-### Diagnostics
-
-```typescript
-// Debug routing
-const info = tabManager.getRoutingInfo(toolName);
-
-// Get stats
-const stats = tabManager.getStats();
-
-// Clear all (testing)
-tabManager.clear();
-```
-
-## Usage
-
-```typescript
-import { TabManager } from '@mcp-fe/mcp-worker';
-
-const tabs = new TabManager();
-
-// Register tabs
-tabs.registerTab('tab-1', '/dashboard', 'Dashboard');
-tabs.registerTab('tab-2', '/settings', 'Settings');
-
-// Register tools
-tabs.registerToolForTab('get_data', 'tab-1');
-tabs.registerToolForTab('get_data', 'tab-2');
-
-// Set active
-tabs.setActiveTab('tab-1');
-
-// Route
-const route = tabs.routeToolCall('get_data');
-// → { targetTabId: 'tab-1', reason: 'active tab has tool' }
-
-// Route to specific tab
-const route2 = tabs.routeToolCall('get_data', 'tab-2');
-// → { targetTabId: 'tab-2', reason: 'explicit tabId parameter' }
-```
-
-## Integration
-
-MCPController uses TabManager internally:
-
-```typescript
-class MCPController {
-  private tabManager = new TabManager();
-
-  handleRegisterTab(data) {
-    this.tabManager.registerTab(data.tabId, data.url, data.title);
-  }
-
-  async handleRegisterToolInternal(toolData) {
-    const isNew = this.tabManager.registerToolForTab(toolData.name, toolData.tabId);
-    
-    if (!isNew) return;
-    
-    // Create handler with routing
-    const handler = async (args) => {
-      const route = this.tabManager.routeToolCall(toolData.name, args.tabId);
-      if (!route) throw new Error('Tool not available');
-      
-      return this.sendToolCall(route.targetTabId, args);
-    };
-    
-    toolRegistry.register({ name: toolData.name }, handler);
-  }
-}
-```
-
-## Why Separate Class?
-
-- **Separation of Concerns**: Tab logic separate from MCP protocol
-- **Testable**: Easy to unit test without MCP dependencies
-- **Reusable**: Can be used in other contexts
-- **Type Safe**: Strong typing throughout
-
-```typescript
-// Example test
-test('routes to only available tab', () => {
-  const tabs = new TabManager();
-  tabs.registerTab('tab-1', '/page', 'Page');
-  tabs.registerTab('tab-2', '/page', 'Page');
-  tabs.registerToolForTab('tool', 'tab-1');
-  tabs.setActiveTab('tab-2'); // Active tab doesn't have tool
-  
-  const route = tabs.routeToolCall('tool');
-  expect(route.targetTabId).toBe('tab-1');
-});
-```
-
-## See Also
-
-- [Multi-Tab Guide](./multi-tab.md) - Complete multi-tab docs
-- [Architecture](./architecture.md) - System architecture
+# TabManager
+
+Manages browser tabs and tool registration routing.
+
+## API
+
+### Tab Management
+
+```typescript
+// Register tab
+tabManager.registerTab(tabId, url, title);
+
+// Set active tab
+tabManager.setActiveTab(tabId);
+
+// Get active tab
+const activeId = tabManager.getActiveTabId(); // → string | null
+
+// Get all tabs
+const tabs = tabManager.getAllTabs(); // → TabInfo[]
+
+// Remove tab
+tabManager.removeTab(tabId); // → boolean
+```
+
+### Tool Registration
+
+```typescript
+// Register tool for tab
+const isNew = tabManager.registerToolForTab(toolName, tabId);
+
+// Unregister tool from tab
+const result = tabManager.unregisterToolFromTab(toolName, tabId);
+// → { wasRemoved, remainingTabs, wasActiveTab }
+
+// Get tabs with tool
+const tabs = tabManager.getTabsForTool(toolName); // → Set<string>
+
+// Check if tab has tool
+const has = tabManager.tabHasTool(toolName, tabId); // → boolean
+```
+
+### Smart Routing
+
+```typescript
+const route = tabManager.routeToolCall(toolName, explicitTabId?);
+// → { targetTabId: string, reason: string } | null
+```
+
+**Priority:**
+1. Explicit `tabId` (if valid)
+2. Only one tab has tool → use it
+3. Active tab has tool → use it
+4. Use first available
+
+### Diagnostics
+
+```typescript
+// Debug routing
+const info = tabManager.getRoutingInfo(toolName);
+
+// Get stats
+const stats = tabManager.getStats();
+
+// Clear all (testing)
+tabManager.clear();
+```
+
+## Usage
+
+```typescript
+import { TabManager } from '@mcp-fe/mcp-worker';
+
+const tabs = new TabManager();
+
+// Register tabs
+tabs.registerTab('tab-1', '/dashboard', 'Dashboard');
+tabs.registerTab('tab-2', '/settings', 'Settings');
+
+// Register tools
+tabs.registerToolForTab('get_data', 'tab-1');
+tabs.registerToolForTab('get_data', 'tab-2');
+
+// Set active
+tabs.setActiveTab('tab-1');
+
+// Route
+const route = tabs.routeToolCall('get_data');
+// → { targetTabId: 'tab-1', reason: 'active tab has tool' }
+
+// Route to specific tab
+const route2 = tabs.routeToolCall('get_data', 'tab-2');
+// → { targetTabId: 'tab-2', reason: 'explicit tabId parameter' }
+```
+
+## Integration
+
+MCPController uses TabManager internally:
+
+```typescript
+class MCPController {
+  private tabManager = new TabManager();
+
+  handleRegisterTab(data) {
+    this.tabManager.registerTab(data.tabId, data.url, data.title);
+  }
+
+  async handleRegisterToolInternal(toolData) {
+    const isNew = this.tabManager.registerToolForTab(toolData.name, toolData.tabId);
+    
+    if (!isNew) return;
+    
+    // Create handler with routing
+    const handler = async (args) => {
+      const route = this.tabManager.routeToolCall(toolData.name, args.tabId);
+      if (!route) throw new Error('Tool not available');
+      
+      return this.sendToolCall(route.targetTabId, args);
+    };
+    
+    toolRegistry.register({ name: toolData.name }, handler);
+  }
+}
+```
+
+## Why Separate Class?
+
+- **Separation of Concerns**: Tab logic separate from MCP protocol
+- **Testable**: Easy to unit test without MCP dependencies
+- **Reusable**: Can be used in other contexts
+- **Type Safe**: Strong typing throughout
+
+```typescript
+// Example test
+test('routes to only available tab', () => {
+  const tabs = new TabManager();
+  tabs.registerTab('tab-1', '/page', 'Page');
+  tabs.registerTab('tab-2', '/page', 'Page');
+  tabs.registerToolForTab('tool', 'tab-1');
+  tabs.setActiveTab('tab-2'); // Active tab doesn't have tool
+  
+  const route = tabs.routeToolCall('tool');
+  expect(route.targetTabId).toBe('tab-1');
+});
+```
+
+## See Also
+
+- [Multi-Tab Guide](./multi-tab.md) - Complete multi-tab docs
+- [Architecture](./architecture.md) - System architecture