@mcp-fe/mcp-worker 0.0.16 → 0.1.0

package/LICENSE

@@ -188,7 +188,7 @@
       same page as the copyright notice for easier identification within
       third-party archives.
 
-   Copyright 2026 [name of copyright owner]
+   Copyright 2026 Michal Kopecky
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,479 +1,314 @@
 # @mcp-fe/mcp-worker
 
-The core package of the MCP-FE (Model Context Protocol - Frontend Edge) ecosystem. This library provides a browser-based MCP server implementation using Web Workers, enabling AI agents to query real-time frontend application state and user interaction data.
+Browser-based MCP server running in Web Workers. Connect AI agents directly to your frontend application state.
 
-## Overview
+## What is MCP-FE Worker?
 
-`@mcp-fe/mcp-worker` turns your browser into an active, queryable MCP node by running MCP server endpoints in a Web Worker. It bridges the gap between AI agents and the live state of your frontend application, making runtime data accessible through standard MCP tools.
+`@mcp-fe/mcp-worker` turns your browser into a queryable MCP server. It allows AI agents (like Claude) to:
 
-### Key Features
+- 🔍 Query user interactions in real-time
+- 📊 Access application state directly
+- 🎯 Register custom tools dynamically
+- 💾 Store and retrieve events from IndexedDB
 
-- **Browser-based MCP Server**: Full MCP server implementation running in Web Workers
-- **Dual Worker Support**: Uses SharedWorker (preferred) with ServiceWorker fallback
-- **IndexedDB Storage**: Persistent storage for user events and application state
-- **WebSocket Transport**: Real-time connection to MCP proxy servers
-- **Zero Backend Dependencies**: Runs entirely in the browser
-- **Authentication Support**: Built-in token-based authentication
-- **Connection Management**: Automatic reconnection and status monitoring
+The MCP server runs in a Web Worker in your browser, requiring an MCP proxy server to bridge communication with AI agents.
 
-## Architecture
-
-The package implements a **Worker-as-MCP-Edge-Server** pattern:
-
-```
-Frontend App ←→ WorkerClient ←→ Web Worker (MCP Server) ←→ WebSocket ←→ MCP Proxy ←→ AI Agent
-```
+## Key Concepts
 
-1. **Frontend App**: Uses `workerClient` to send events and queries
-2. **WorkerClient**: Manages worker lifecycle and provides clean API
-3. **Web Worker**: Implements MCP server endpoints, stores data in IndexedDB
-4. **WebSocket**: Maintains persistent connection to MCP proxy server
-5. **MCP Proxy**: Bridges browser worker with external AI agents
-6. **AI Agent**: Queries frontend state using standard MCP tools
+### MCP Server in Browser
 
-## Installation
+This library runs an **MCP server in your browser** using Web Workers, exposing frontend application context to AI agents. This enables AI agents to query live browser state (DOM, localStorage, React state, etc.) through the standard MCP protocol.
 
-```bash
-npm install @mcp-fe/mcp-worker
-# or
-pnpm add @mcp-fe/mcp-worker
-# or
-yarn add @mcp-fe/mcp-worker
-```
+The key advantage is **making frontend context accessible** to AI agents without custom backend code for each use case.
 
-## Quick Start
+### Dual Worker Strategy
 
-### 1. Copy Worker Files to Public Directory
+The library uses **SharedWorker** (preferred) or **ServiceWorker** (fallback):
 
-The package exports pre-built worker scripts that must be accessible from your web server:
+- **SharedWorker**: Single instance shared across tabs, persistent connection
+- **ServiceWorker**: Universal browser support, automatic fallback
 
-```bash
-# Copy worker files to your public directory
-cp node_modules/@mcp-fe/mcp-worker/mcp-shared-worker.js public/
-cp node_modules/@mcp-fe/mcp-worker/mcp-service-worker.js public/
-```
+### Dynamic Tool Registration
 
-For build tools like Vite, Webpack, or Nx, you can configure them to copy these files automatically:
+Register custom MCP tools at runtime with **handlers running in the main thread**:
 
-**Vite example:**
 ```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  // ... other config
-  publicDir: 'public',
-  build: {
-    rollupOptions: {
-      // Copy worker files during build
-      external: ['@mcp-fe/mcp-worker/mcp-*.js']
-    }
+await workerClient.registerTool(
+  'get_user_data',
+  'Get current user information',
+  { type: 'object', properties: {} },
+  async () => {
+    const user = getCurrentUser(); // Full browser access!
+    return {
+      content: [{ type: 'text', text: JSON.stringify(user) }]
+    };
   }
-});
+);
 ```
 
-### 2. Initialize in Your Application
-
-```typescript
-import { workerClient } from '@mcp-fe/mcp-worker';
+Handlers have full access to:
+- ✅ React context, hooks, state
+- ✅ DOM API, localStorage
+- ✅ All imports and dependencies
+- ✅ Closures and external variables
 
-// Initialize the worker client
-async function initMCP() {
-  try {
-    await workerClient.init({
-      sharedWorkerUrl: '/mcp-shared-worker.js',    // optional, default value
-      serviceWorkerUrl: '/mcp-service-worker.js',  // optional, default value  
-      backendWsUrl: 'ws://localhost:3001'          // your MCP proxy server
-    });
-    
-    console.log('MCP Worker initialized successfully');
-  } catch (error) {
-    console.error('Failed to initialize MCP Worker:', error);
-  }
-}
+## Architecture
 
-// Call during app startup
-initMCP();
 ```
-
-### 3. Set Authentication Token (Optional)
-
-```typescript
-// Set authentication token for user-specific data
-workerClient.setAuthToken('Bearer your-jwt-token-here');
-
-// Or queue the token before initialization
-workerClient.setAuthToken('Bearer token');
-await workerClient.init(/* options */);
+Frontend App ←→ WorkerClient ←→ Web Worker ←→ WebSocket ←→ MCP Proxy ←→ AI Agent
+                                    ↓
+                                IndexedDB
 ```
 
-## API Reference
+1. **Frontend App** - Your application
+2. **WorkerClient** - Simple API for worker communication
+3. **Web Worker** - MCP server running in background
+4. **WebSocket** - Real-time connection to proxy
+5. **MCP Proxy** - Bridges browser with AI agents
+6. **AI Agent** - Queries your app via MCP protocol
 
-### WorkerClient
+## Quick Start
 
-The main singleton instance for communicating with the MCP worker.
+### Installation
 
-#### `workerClient.init(options?)`
+```bash
+npm install @mcp-fe/mcp-worker
+# or
+pnpm add @mcp-fe/mcp-worker
+```
 
-Initializes the worker client with optional configuration.
+### 1. Setup Worker Files
 
-**Parameters:**
-- `options?: WorkerClientInitOptions | ServiceWorkerRegistration`
+Copy worker scripts to your public directory:
 
-**WorkerClientInitOptions:**
-```typescript
-interface WorkerClientInitOptions {
-  sharedWorkerUrl?: string;    // Default: '/mcp-shared-worker.js'
-  serviceWorkerUrl?: string;   // Default: '/mcp-service-worker.js'  
-  backendWsUrl?: string;       // Default: 'ws://localhost:3001'
-}
+```bash
+cp node_modules/@mcp-fe/mcp-worker/mcp-shared-worker.js public/
+cp node_modules/@mcp-fe/mcp-worker/mcp-service-worker.js public/
 ```
 
-**Examples:**
+### 2. Initialize
+
 ```typescript
-// Basic initialization with defaults
-await workerClient.init();
+import { workerClient } from '@mcp-fe/mcp-worker';
 
-// Custom configuration
 await workerClient.init({
-  backendWsUrl: 'wss://my-mcp-proxy.com/ws',
-  sharedWorkerUrl: '/workers/mcp-shared-worker.js'
+  backendWsUrl: 'ws://localhost:3001' // Your MCP proxy URL
 });
-
-// Use existing ServiceWorker registration
-const registration = await navigator.serviceWorker.register('/mcp-service-worker.js');
-await workerClient.init(registration);
 ```
 
-#### `workerClient.post(type, payload?)`
+### 3. Store Events
 
-Send a fire-and-forget message to the worker.
-
-**Parameters:**
-- `type: string` - Message type
-- `payload?: Record<string, unknown>` - Message payload
-
-**Example:**
 ```typescript
-// Store a user event
 await workerClient.post('STORE_EVENT', {
   event: {
     type: 'click',
     element: 'button',
-    elementText: 'Submit Form',
-    path: '/checkout',
+    elementText: 'Submit',
     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);
-```
-
-#### `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('');
-```
-
-#### `workerClient.getConnectionStatus()`
-
-Get current connection status to the MCP proxy server.
-
-**Returns:** `Promise<boolean>` - Connection status
+### 4. Register Custom Tools
 
-**Example:**
 ```typescript
-const isConnected = await workerClient.getConnectionStatus();
-console.log('MCP connection:', isConnected ? 'Connected' : 'Disconnected');
+await workerClient.registerTool(
+  'get_todos',
+  'Get all todos',
+  { type: 'object', properties: {} },
+  async () => ({
+    content: [{ type: 'text', text: JSON.stringify(todos) }]
+  })
+);
 ```
 
-#### Connection Status Events
+**That's it!** AI agents can now query your app via MCP protocol.
 
-Subscribe to connection status changes:
+## Documentation
 
-```typescript
-// Listen for connection changes
-const handleConnectionChange = (connected: boolean) => {
-  console.log('Connection status changed:', connected);
-};
-
-workerClient.onConnectionStatus(handleConnectionChange);
-
-// Stop listening
-workerClient.offConnectionStatus(handleConnectionChange);
-```
+### Core Documentation
 
-## Worker Implementation Details
+- **[Quick Start Guide](./docs/guide.md)** - Complete guide to dynamic tool registration
+- **[API Reference](./docs/api.md)** - Full API documentation
+- **[Worker Details](./docs/worker-details.md)** - Implementation details
+- **[Architecture](./docs/architecture.md)** - How the proxy pattern works
+- **[Initialization](./docs/initialization.md)** - Init queue handling
 
-### SharedWorker vs ServiceWorker
+### Examples
 
-**SharedWorker (Preferred):**
-- Single instance shared across all browser windows/tabs on the same origin
-- Maintains persistent WebSocket connection even when tabs are closed
-- Better for multi-tab applications
-- Supported in Chrome, Firefox, and Safari
+- **[Quick Start Examples](./examples/quick-start.ts)** - 4 simple examples
+- **[Advanced Examples](./examples/dynamic-tools.ts)** - Validation, async, error handling
+- **[Examples Guide](./examples/README.md)** - How to use examples
 
-**ServiceWorker (Fallback):**
-- Runs in background with browser-managed lifecycle
-- Automatic fallback when SharedWorker is unavailable
-- Handles offline scenarios and background sync
-- Universal browser support
+### React Integration
 
-The `WorkerClient` automatically chooses the best available option.
+- **[React Hooks Guide](../react-event-tracker/REACT_MCP_TOOLS.md)** - React integration
+- **[React Examples](../react-event-tracker/src/examples/ReactMCPToolsExamples.tsx)** - Component examples
 
-### Data Storage
+## Common Use Cases
 
-Events are stored in IndexedDB with the following schema:
+### Track User Interactions
 
 ```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>;
-}
+// Clicks, navigation, form inputs
+await workerClient.post('STORE_EVENT', {
+  event: { type: 'click', element: 'button', ... }
+});
 ```
 
-### 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
-
-## Advanced Usage
-
-### Custom Event Storage
+### Expose Application State
 
 ```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'
-    }
-  }
-});
+await workerClient.registerTool('get_cart', 'Get shopping cart', ..., 
+  async () => ({ content: [{ type: 'text', text: JSON.stringify(cart) }] })
+);
 ```
 
-### Querying Specific Events
+### Query Stored Events
 
 ```typescript
-// Get navigation events from the last hour
-const response = await workerClient.request('GET_EVENTS', {
+const events = 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
+### Monitor Connection Status
 
 ```typescript
-try {
-  await workerClient.init();
-} catch (error) {
-  if (error.message.includes('SharedWorker')) {
-    console.log('SharedWorker not supported, falling back to ServiceWorker');
-  } 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, worker may be busy');
-  }
-}
-```
-
-## Integration with Higher-Level Libraries
-
-This package is designed to be used with higher-level integration libraries:
-
-- **[@mcp-fe/event-tracker](../event-tracker/README.md)**: Framework-agnostic event tracking
-- **[@mcp-fe/react-event-tracker](../react-event-tracker/README.md)**: React-specific hooks and components
-
-**Example with event-tracker:**
-```typescript
-import { initEventTracker, trackEvent } from '@mcp-fe/event-tracker';
-
-// Initialize (uses @mcp-fe/mcp-worker internally)
-await initEventTracker({
-  backendWsUrl: 'ws://localhost:3001'
-});
-
-// Track events (stored via mcp-worker)
-await trackEvent({
-  type: 'click',
-  element: 'button',
-  elementText: 'Save Changes'
+const connected = await workerClient.getConnectionStatus();
+workerClient.onConnectionStatus((connected) => {
+  console.log('MCP connection:', connected);
 });
 ```
 
-## Setting Up MCP Proxy Server
-
-The worker connects to an MCP proxy server that bridges browser workers with AI agents. You need a Node.js MCP proxy running to use this package effectively.
+## MCP Proxy Server
 
-### Using the Official Docker Image
+The worker connects to an MCP proxy server that bridges browser with AI agents.
 
-The easiest way to run the MCP proxy server is using the official Docker image:
+### Using Docker (Recommended)
 
 ```bash
-# Pull and run the MCP proxy server
 docker pull ghcr.io/mcp-fe/mcp-fe/mcp-server:main
 docker run -p 3001:3001 ghcr.io/mcp-fe/mcp-fe/mcp-server:main
 ```
 
-The server will be available at `ws://localhost:3001` for your frontend applications.
+Server available at `ws://localhost:3001`
 
+### Development
 
-**With Environment Variables:**
 ```bash
-docker run -p 3001:3001 \
-  -e NODE_ENV=production \
-  -e PORT=3001 \
-  ghcr.io/mcp-fe/mcp-fe/mcp-server:main
+git clone https://github.com/mcp-fe/mcp-fe.git
+cd mcp-fe
+pnpm install
+nx serve mcp-server
 ```
 
-### Development Setup
+See [mcp-server docs](../../apps/mcp-server/README.md) for complete setup.
 
-For development, you can run the proxy server from source:
+## Features
 
-```bash
-# Clone the MCP-FE repository
-git clone https://github.com/mcp-fe/mcp-fe.git
-cd mcp-fe
+### Dynamic Tool Registration
 
-# Install dependencies
-pnpm install
+Register custom MCP tools at runtime:
 
-# Start the MCP proxy server
-nx serve mcp-server
+```typescript
+await workerClient.registerTool(
+  'get_user_data',
+  'Get current user information',
+  { type: 'object', properties: {} },
+  async () => {
+    const user = getCurrentUser(); // Full browser access!
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(user)
+      }]
+    };
+  }
+);
+```
+
+**Learn more:**
+- [Guide](./docs/guide.md) - Complete step-by-step guide
+- [Quick Start Examples](./examples/quick-start.ts) - Ready-to-use examples
+- [Advanced Examples](./examples/dynamic-tools.ts) - Validation, async, error handling
+- [React Integration](../react-event-tracker/REACT_MCP_TOOLS.md) - React hooks
+
+### Event Storage
+
+Store and query user interactions:
+
+```typescript
+// Store event
+await workerClient.post('STORE_EVENT', {
+  event: { type: 'click', element: 'button', ... }
+});
+
+// Query events
+const events = await workerClient.request('GET_EVENTS', {
+  type: 'click',
+  limit: 10
+});
 ```
 
-The proxy server handles:
-- WebSocket connections from browser workers
-- MCP protocol message routing
-- Tool call forwarding between AI agents and frontend applications
-- Connection management and error handling
+### Connection Management
 
-See the [mcp-server documentation](../../apps/mcp-server/README.md) and main [MCP-FE documentation](../../README.md) for complete proxy server setup and configuration options.
+Monitor MCP proxy connection:
+
+```typescript
+const connected = await workerClient.getConnectionStatus();
+workerClient.onConnectionStatus((connected) => {
+  console.log('Status:', connected);
+});
+```
 
 ## Browser Compatibility
 
-- **Chrome/Chromium**: Full support (SharedWorker + ServiceWorker)
-- **Firefox**: Full support (SharedWorker + ServiceWorker) 
-- **Safari**: SharedWorker support, ServiceWorker fallback
-- **Edge**: Full support (Chromium-based)
+- ✅ **Chrome/Chromium 80+** - Full support
+- ✅ **Firefox 78+** - Full support
+- ✅ **Safari 16.4+** - Full support
+- ✅ **Edge 80+** - Full support (Chromium-based)
 
-**Minimum Requirements:**
-- ES2020+ support
-- WebWorker support
-- IndexedDB support
-- WebSocket support (for MCP proxy connection)
+**Requirements:** ES2020+, WebWorker, IndexedDB, WebSocket
 
-## Troubleshooting
+See [Worker Details](./docs/worker-details.md) for more information.
 
-### Worker Files Not Found (404)
+## Troubleshooting
 
-**Problem**: `Failed to load worker script` errors
+### Worker files not found (404)
 
-**Solution**: 
-1. Ensure worker files are copied to your public directory
-2. Verify the URLs match your server configuration
-3. Check browser Network tab for 404 errors
+Ensure worker files are in your public directory and paths match:
 
 ```typescript
-// Custom paths if needed
 await workerClient.init({
-  sharedWorkerUrl: '/assets/workers/mcp-shared-worker.js',
-  serviceWorkerUrl: '/assets/workers/mcp-service-worker.js'
+  sharedWorkerUrl: '/path/to/mcp-shared-worker.js',
+  serviceWorkerUrl: '/path/to/mcp-service-worker.js'
 });
 ```
 
-### Connection Issues
-
-**Problem**: `getConnectionStatus()` returns `false`
-
-**Solution**:
-1. Verify MCP proxy server is running on the specified URL
-2. Check WebSocket connection in browser Developer Tools
-3. Verify CORS settings if proxy is on different origin
+### Connection issues
 
-### SharedWorker Not Working
+1. Verify MCP proxy server is running
+2. Check WebSocket connection in DevTools Network tab
+3. Verify CORS settings if on different origin
 
-**Problem**: Falls back to ServiceWorker unexpectedly
+### SharedWorker not available
 
-**Solution**:
-1. SharedWorker requires HTTPS in production
-2. Some browsers disable SharedWorker in private/incognito mode
-3. Enterprise browser policies may block SharedWorker
+SharedWorker requires HTTPS in production and may be blocked in incognito mode. The library automatically falls back to ServiceWorker.
 
+**For more help:** See [Worker Details](./docs/worker-details.md#troubleshooting)
 
 ## Related Packages
 
-- **[Main MCP-FE Project](../../README.md)**: Complete documentation and examples
-- **[@mcp-fe/event-tracker](../event-tracker/README.md)**: Framework-agnostic event tracking API
-- **[@mcp-fe/react-event-tracker](../react-event-tracker/README.md)**: React integration hooks
+- [Main MCP-FE Project](../../README.md) - Complete documentation
+- [@mcp-fe/event-tracker](../event-tracker/README.md) - Framework-agnostic event tracking
+- [@mcp-fe/react-event-tracker](../react-event-tracker/README.md) - React integration hooks
 
 ## License
 
-Licensed under the Apache License, Version 2.0. See the [LICENSE](../../LICENSE) file for details.
+Licensed under the Apache License, Version 2.0. See [LICENSE](../../LICENSE) for details.
 
 ---
 
-**Note**: This package is the foundational layer of the MCP-FE ecosystem. For most applications, consider using the higher-level integration packages like `@mcp-fe/react-event-tracker` which provide a more convenient API.
+**For most applications, consider using [@mcp-fe/react-event-tracker](../react-event-tracker/README.md) for a more convenient React-focused API.**