@mcp-fe/mcp-worker 0.0.17 → 0.1.0

package/docs/api.md

@@ -0,0 +1,418 @@
+# API Reference
+
+Complete API documentation for `@mcp-fe/mcp-worker`.
+
+## WorkerClient
+
+The main singleton instance for communicating with the MCP worker.
+
+```typescript
+import { workerClient } from '@mcp-fe/mcp-worker';
+```
+
+### Initialization
+
+#### `workerClient.init(options?)`
+
+Initializes the worker client with optional configuration.
+
+**Parameters:**
+- `options?: WorkerClientInitOptions | ServiceWorkerRegistration`
+
+**WorkerClientInitOptions:**
+```typescript
+interface WorkerClientInitOptions {
+  sharedWorkerUrl?: string;    // Default: '/mcp-shared-worker.js'
+  serviceWorkerUrl?: string;   // Default: '/mcp-service-worker.js'  
+  backendWsUrl?: string;       // Default: 'ws://localhost:3001'
+}
+```
+
+**Returns:** `Promise<void>`
+
+**Examples:**
+```typescript
+// Basic initialization with defaults
+await workerClient.init();
+
+// Custom configuration
+await workerClient.init({
+  backendWsUrl: 'wss://my-mcp-proxy.com/ws',
+  sharedWorkerUrl: '/workers/mcp-shared-worker.js'
+});
+
+// Use existing ServiceWorker registration
+const registration = await navigator.serviceWorker.register('/mcp-service-worker.js');
+await workerClient.init(registration);
+```
+
+### Event Storage
+
+#### `workerClient.post(type, payload?)`
+
+Send a fire-and-forget message to the worker.
+
+**Parameters:**
+- `type: string` - Message type
+- `payload?: Record<string, unknown>` - Message payload
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```typescript
+// Store a user event
+await workerClient.post('STORE_EVENT', {
+  event: {
+    type: 'click',
+    element: 'button',
+    elementText: 'Submit Form',
+    path: '/checkout',
+    timestamp: Date.now()
+  }
+});
+```
+
+#### `workerClient.request(type, payload?, timeoutMs?)`
+
+Send a request expecting a response via MessageChannel.
+
+**Parameters:**
+- `type: string` - Request type  
+- `payload?: Record<string, unknown>` - Request payload
+- `timeoutMs?: number` - Timeout in milliseconds (default: 5000)
+
+**Returns:** `Promise<T>` - Response data
+
+**Example:**
+```typescript
+// Get stored events
+const response = await workerClient.request('GET_EVENTS', {
+  type: 'click',
+  limit: 10
+});
+
+console.log('Recent clicks:', response.events);
+```
+
+### Authentication
+
+#### `workerClient.setAuthToken(token)`
+
+Set authentication token for the current session.
+
+**Parameters:**
+- `token: string` - Authentication token (e.g., JWT)
+
+**Example:**
+```typescript
+// Set token after user login
+workerClient.setAuthToken('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...');
+
+// Clear token on logout  
+workerClient.setAuthToken('');
+```
+
+### Connection Status
+
+#### `workerClient.getConnectionStatus()`
+
+Get current connection status to the MCP proxy server.
+
+**Returns:** `Promise<boolean>` - Connection status
+
+**Example:**
+```typescript
+const isConnected = await workerClient.getConnectionStatus();
+console.log('MCP connection:', isConnected ? 'Connected' : 'Disconnected');
+```
+
+#### `workerClient.onConnectionStatus(callback)`
+
+Subscribe to connection status changes.
+
+**Parameters:**
+- `callback: (connected: boolean) => void` - Status change callback
+
+**Example:**
+```typescript
+const handleConnectionChange = (connected: boolean) => {
+  console.log('Connection status:', connected ? 'Connected' : 'Disconnected');
+};
+
+workerClient.onConnectionStatus(handleConnectionChange);
+```
+
+#### `workerClient.offConnectionStatus(callback)`
+
+Unsubscribe from connection status changes.
+
+**Parameters:**
+- `callback: (connected: boolean) => void` - Previously registered callback
+
+**Example:**
+```typescript
+workerClient.offConnectionStatus(handleConnectionChange);
+```
+
+### Dynamic Tool Registration
+
+#### `workerClient.registerTool(name, description, inputSchema, handler)`
+
+Register a custom MCP tool dynamically.
+
+**Parameters:**
+- `name: string` - Tool name (use snake_case)
+- `description: string` - Tool description (AI uses this)
+- `inputSchema: Record<string, unknown>` - JSON Schema for input validation
+- `handler: (args: unknown) => Promise<ToolResult>` - Async handler function
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```typescript
+await workerClient.registerTool(
+  'get_user_data',
+  'Get current user information',
+  { type: 'object', properties: {} },
+  async () => {
+    const user = getCurrentUser();
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(user)
+      }]
+    };
+  }
+);
+```
+
+See [Dynamic Tool Registration Guide](./guide.md) for complete documentation.
+
+#### `workerClient.unregisterTool(name)`
+
+Unregister a previously registered tool.
+
+**Parameters:**
+- `name: string` - Tool name to unregister
+
+**Returns:** `Promise<boolean>` - True if tool was found and removed
+
+**Example:**
+```typescript
+const success = await workerClient.unregisterTool('get_user_data');
+```
+
+#### `workerClient.onToolChange(name, callback)`
+
+Subscribe to tool registration changes (for reactive updates).
+
+**Parameters:**
+- `name: string` - Tool name to watch
+- `callback: (info: ToolInfo | null) => void` - Change callback
+
+**Returns:** `() => void` - Unsubscribe function
+
+**Example:**
+```typescript
+const unsubscribe = workerClient.onToolChange('my_tool', (info) => {
+  console.log('Tool info:', info);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+#### `workerClient.getToolInfo(name)`
+
+Get information about a registered tool.
+
+**Parameters:**
+- `name: string` - Tool name
+
+**Returns:** `ToolInfo | null`
+
+```typescript
+interface ToolInfo {
+  refCount: number;
+  isRegistered: boolean;
+}
+```
+
+**Example:**
+```typescript
+const info = workerClient.getToolInfo('my_tool');
+if (info) {
+  console.log('RefCount:', info.refCount);
+  console.log('Registered:', info.isRegistered);
+}
+```
+
+#### `workerClient.isToolRegistered(name)`
+
+Check if a tool is registered.
+
+**Parameters:**
+- `name: string` - Tool name
+
+**Returns:** `boolean`
+
+**Example:**
+```typescript
+if (workerClient.isToolRegistered('my_tool')) {
+  console.log('Tool is registered');
+}
+```
+
+#### `workerClient.getRegisteredTools()`
+
+Get all registered tool names.
+
+**Returns:** `string[]`
+
+**Example:**
+```typescript
+const tools = workerClient.getRegisteredTools();
+console.log('Registered tools:', tools);
+```
+
+### Worker State
+
+#### `workerClient.initialized`
+
+Check if the worker is initialized.
+
+**Type:** `boolean` (getter)
+
+**Example:**
+```typescript
+if (workerClient.initialized) {
+  console.log('Worker is ready');
+}
+```
+
+#### `workerClient.waitForInit()`
+
+Wait for worker initialization to complete.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```typescript
+await workerClient.waitForInit();
+console.log('Worker is now initialized');
+```
+
+## Type Definitions
+
+### ToolResult
+
+```typescript
+interface ToolResult {
+  content: Array<{
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  }>;
+}
+```
+
+### ToolHandler
+
+```typescript
+type ToolHandler = (args: unknown) => Promise<ToolResult>;
+```
+
+### UserEvent
+
+```typescript
+interface UserEvent {
+  id: string;
+  type: 'navigation' | 'click' | 'input' | 'custom';
+  timestamp: number;
+  path?: string;
+  from?: string;          // navigation: previous route
+  to?: string;            // navigation: current route  
+  element?: string;       // interaction: element tag
+  elementId?: string;     // interaction: element ID
+  elementClass?: string;  // interaction: element classes
+  elementText?: string;   // interaction: element text content
+  metadata?: Record<string, unknown>;
+}
+```
+
+## Advanced Usage
+
+### Custom Event Storage
+
+```typescript
+// Store custom business events
+await workerClient.post('STORE_EVENT', {
+  event: {
+    type: 'custom',
+    timestamp: Date.now(),
+    metadata: {
+      eventName: 'purchase_completed',
+      orderId: '12345',
+      amount: 99.99,
+      currency: 'USD'
+    }
+  }
+});
+```
+
+### Querying Specific Events
+
+```typescript
+// Get navigation events from the last hour
+const response = await workerClient.request('GET_EVENTS', {
+  type: 'navigation',
+  startTime: Date.now() - (60 * 60 * 1000),
+  limit: 50
+});
+
+// Get clicks on specific elements
+const clicks = await workerClient.request('GET_EVENTS', {
+  type: 'click',
+  path: '/checkout',
+  limit: 20
+});
+```
+
+### Error Handling
+
+```typescript
+try {
+  await workerClient.init();
+} catch (error) {
+  if (error.message.includes('SharedWorker')) {
+    console.log('SharedWorker not supported, using ServiceWorker fallback');
+  } else {
+    console.error('Worker initialization failed:', error);
+  }
+}
+
+// Handle request timeouts
+try {
+  const data = await workerClient.request('GET_EVENTS', {}, 2000); // 2s timeout
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out');
+  }
+}
+```
+
+## MCP Tools Exposed
+
+The worker exposes these MCP tools to AI agents:
+
+- `get_user_events` - Query stored user interaction events
+- `get_connection_status` - Check WebSocket connection status
+- `get_session_info` - Get current session information
+- Custom tools registered via `registerTool()`
+
+## See Also
+
+- [Guide](./guide.md) - Dynamic tool registration guide
+- [Worker Implementation Details](./worker-details.md) - Technical details
+- [Architecture](./architecture.md) - How it works

package/docs/architecture.md

@@ -0,0 +1,195 @@
+# Proxy Architecture
+
+How dynamic tool registration works with handlers running in the main thread.
+
+## Overview
+
+The library uses a **proxy pattern** where:
+- ✅ Handlers run in **main thread** (browser context)
+- ✅ Worker acts as **proxy** between MCP and handlers
+- ✅ **No serialization** of function code
+- ✅ **Full access** to browser APIs, React, imports, etc.
+
+## Architecture
+
+```
+┌─────────────────────┐
+│   MCP Client        │
+│   (Claude, etc.)    │
+└──────────┬──────────┘
+           │ MCP Protocol
+           ▼
+┌─────────────────────┐
+│  Shared/Service     │
+│  Worker (MCP Server)│
+│                     │
+│  Tool Registry      │
+│  ├─ Proxy Handler   │ ← metadata + proxy
+│  └─ postMessage     │
+└──────────┬──────────┘
+           │ postMessage({ type: 'CALL_TOOL', args, callId })
+           ▼
+┌─────────────────────┐
+│  Main Thread        │
+│  (Browser Context)  │
+│                     │
+│  WorkerClient       │
+│  ├─ toolHandlers    │ ← actual handler functions
+│  └─ execute         │ ← with full API access
+└──────────┬──────────┘
+           │ postMessage({ type: 'TOOL_CALL_RESULT', result })
+           ▼
+┌─────────────────────┐
+│  Worker             │
+│  ├─ resolve Promise │
+│  └─ return to MCP   │
+└─────────────────────┘
+```
+
+## Benefits
+
+### No Serialization Issues
+- Handlers are normal functions in main thread
+- No `.toString()` → `new Function()` conversion
+- All closures and imports preserved
+
+### Full Browser API Access
+```typescript
+await client.registerTool('get_page_info', '...', {}, async () => {
+  // ✅ DOM access
+  const title = document.title;
+  
+  // ✅ localStorage
+  const theme = localStorage.getItem('theme');
+  
+  // ✅ React hooks/context (if handler in component)
+  const user = useUser();
+  
+  return { content: [{ type: 'text', text: JSON.stringify({ title, theme, user }) }] };
+});
+```
+
+### Use Any Imports
+```typescript
+import { z } from 'zod';
+import { myApi } from './api';
+
+await client.registerTool('validate', '...', schema, async (args: any) => {
+  // ✅ Use any imports!
+  const validated = z.object({ ... }).parse(args);
+  const result = await myApi.callSomething(validated);
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+});
+```
+
+### Easy Testing
+```typescript
+// Handler is a normal async function
+const myHandler = async (args: any) => {
+  // ... logic ...
+  return { content: [{ type: 'text', text: '...' }] };
+};
+
+// Test directly
+test('myHandler works', async () => {
+  const result = await myHandler({ test: 'data' });
+  expect(result.content[0].text).toContain('data');
+});
+
+// Then register
+await client.registerTool('my_tool', '...', schema, myHandler);
+```
+
+## Implementation
+
+### WorkerClient (Main Thread)
+
+Stores handlers locally and executes them when called:
+
+```typescript
+private toolHandlers = new Map<string, HandlerFunction>();
+
+public async registerTool(name, description, schema, handler) {
+  // Store handler in main thread
+  this.toolHandlers.set(name, handler);
+  
+  // Tell worker to create proxy
+  await this.request('REGISTER_TOOL', {
+    name, description, inputSchema: schema,
+    handlerType: 'proxy'  // ← important!
+  });
+}
+
+private async handleToolCall(toolName: string, args: unknown, callId: string) {
+  try {
+    const handler = this.toolHandlers.get(toolName);
+    const result = await handler(args); // ← runs in main thread!
+    
+    this.sendToolCallResult(callId, { success: true, result });
+  } catch (error) {
+    this.sendToolCallResult(callId, { success: false, error: error.message });
+  }
+}
+```
+
+### MCPController (Worker)
+
+Creates proxy handler and forwards calls:
+
+```typescript
+public async handleRegisterTool(toolData: Record<string, unknown>) {
+  const { name, description, inputSchema, handlerType } = toolData;
+  
+  if (handlerType === 'proxy') {
+    // Create proxy handler that forwards to main thread
+    mcpServer.registerTool(name, description, inputSchema, 
+      async (args: unknown) => {
+        // Forward to main thread
+        const callId = generateId();
+        this.broadcast({ type: 'CALL_TOOL', toolName: name, args, callId });
+        
+        // Wait for result
+        return await this.waitForToolCallResult(callId);
+      }
+    );
+  }
+}
+```
+
+## Message Flow
+
+1. **MCP Client** calls tool via MCP protocol
+2. **Worker** receives MCP tool call
+3. **Worker** sends `CALL_TOOL` message to main thread
+4. **Main Thread** executes handler function
+5. **Main Thread** sends `TOOL_CALL_RESULT` back
+6. **Worker** resolves promise and returns to MCP
+7. **MCP Client** receives result
+
+## Why This Works
+
+- **Worker**: Runs 24/7, maintains MCP connection
+- **Main Thread**: Has full browser API access
+- **Messages**: Bridge between the two contexts
+- **Handlers**: Execute where they have access to everything
+
+## Trade-offs
+
+### Advantages
+- ✅ Full browser API access
+- ✅ No serialization issues
+- ✅ Easy to implement
+- ✅ Easy to test
+- ✅ Works with any library
+
+### Considerations
+- Message passing overhead (minimal, ~1-2ms)
+- Handler must be async (already required by MCP)
+
+## Usage
+
+See [Guide](./guide.md) for complete usage guide and examples.
+
+See [examples/](../examples/) for runnable code examples.
+
+```