mcp-worker

# MCP Web Worker Demo This demo showcases a Model Context Protocol (MCP) client implementation using a Shared Web Worker architecture. It demonstrates how to use MCP in a browser environment with a decoupled architecture using pure JavaScript with no build requirements. ## Implementation Components ### 1. **Worker Implementation (`worker.js`)** - Contains the implementation for an MCP client in a worker context - Demonstrates the worker-side message handling patterns for MCP - Implements a simplified MCP client without external dependencies ### 2. **Client Wrapper (`mcp-client.js`)** - Provides a simplified API for the main thread to communicate with the worker - Handles connection, initialization, and method calls - Decouples the communication protocol from the actual MCP implementation ### 3. **Mock Server (`server.js`)** - Demo server implementation for testing - Provides tools, resources, and prompts - Implements MCP request handlers ### 4. **Demo UI (`index.html`)** - Interactive interface to test all MCP features - Demonstrates client capabilities like tool calling, resource reading, and prompt retrieval - Shows connection state and server information ### 5. **Testing Tools** - Minimal Worker (`minimal-worker.js`) - A simplified shared worker for compatibility testing - Diagnostics - Connection status indicators and detailed logging ## Message Protocol The implementation uses a custom message protocol to communicate between the main thread and the worker context: 1. **Connection Messages** - `{ type: 'connection', connectionId, status }` - Worker to main thread - `{ type: 'init', clientInfo }` - Main thread to worker - `{ type: 'close', connectionId }` - Main thread to worker 2. **MCP Messages** - `{ type: 'mcp', messageType: 'transport', payload }` - For raw MCP protocol messages - `{ type: 'mcp', messageType: 'method', method, params, requestId }` - Method calls - `{ type: 'mcp', messageType: 'result', method, result, requestId }` - Method results - `{ type: 'mcp', messageType: 'error', error, requestId }` - Error responses - `{ type: 'mcp', messageType: 'status', status }` - Status updates ## Benefits of the Worker-Based Architecture 1. **Performance** - Offloads MCP processing to a background thread - Main UI thread remains responsive during complex operations 2. **Shared State** - Single worker instance serves multiple tabs/windows - Shared connection and state across browser contexts 3. **Decoupled Design** - MCP implementation details are isolated in the worker - Main thread only needs to know the messaging API - Easier to update or replace either component 4. **Security** - MCP code runs in a separate context - Resource isolation between UI and protocol handling ## How to Run the Demo 1. Make sure the SDK is built: ```bash # From the typescript-sdk root directory npm run build ``` 2. Start a web server: ```bash # From the typescript-sdk/webworker-demo directory ./start.sh ``` This script starts a simple HTTP server on port 3000. Alternatively, you can use: ```bash # From the typescript-sdk root directory npx http-server -p 3000 ``` 3. Open a web browser (Chrome or Edge recommended) and navigate to: ``` http://localhost:3000/webworker-demo/ ``` **IMPORTANT:** Make sure you're accessing the site via `http://localhost:3000` and not `file://` protocol. SharedWorkers have restrictions when loaded from the file system. 4. Click "Connect to MCP" button to establish the connection - The tools, resources, and prompts should load automatically - If there are any issues, check the browser's console for detailed logs 5. Use the tabs to explore different MCP features: - Tools: List and call available tools (try the "hello" tool with your name) - Resources: List and read resources (check out the readme file) - Prompts: List and retrieve prompts (try the greeting prompt) ## Implementation Notes - This demo uses a self-contained implementation with no external dependencies - All code runs directly in the browser with no build step required - All modern JavaScript features are used (ES modules, async/await, etc.) - The worker implements a client and connects to a mock server running in the same context ## Browser Compatibility Requirements This demo strictly requires a browser that supports: - **Shared Web Workers** - This is a hard requirement (Chrome, Edge, and Opera are known to work) - ES Modules - Async/await - Other ES6+ features If your browser doesn't support SharedWorker, you'll see an error message. Unlike many demos, this implementation doesn't provide a fallback to other technologies - it's designed to showcase the specific advantages of using SharedWorker for MCP clients. ### Browsers Known to Support SharedWorker: - Chrome - Edge (Chromium-based) - Opera - Android Chrome ### Browsers with Limited or No Support: - Firefox (disabled by default but can be enabled via about:config) - Safari (limited support) - iOS Safari (no support) ## Troubleshooting If you encounter issues running the demo: 1. **Failed to fetch worker script**: - **Make sure you're accessing the demo through a web server** at `http://localhost:3000/webworker-demo/` - **Do not** try to load the demo from the file system (`file://`) - Ensure the SDK is built with `npm run build` from the main directory - Check your browser console for specific error messages - The demo will try multiple worker script paths automatically to find one that works 2. **SharedWorker not supported**: - Use Chrome or Edge which have good SharedWorker support - The demo will display a clear error if your browser doesn't support SharedWorker - The demo purposely does not implement a fallback for non-supporting browsers 3. **Module import errors**: - The worker and server use regular imports without requiring external libraries - Make sure you're accessing via HTTP server, not directly from filesystem - Check the browser console for specific import path errors 4. **Console errors**: - Look for "SharedWorker" or "MCP" related errors in the browser console - The implementation includes extensive logging for debugging purposes - The worker diagnostics panel shows connection status and script path 5. **Blank page or no tools/resources showing**: - Check the browser console (F12 or Cmd+Option+I) for detailed error messages - Make sure your browser has JavaScript enabled - Try clearing your browser cache and refreshing the page 6. **Path resolution issues**: - The worker attempts to load from multiple paths: 1. `./minimal-worker.js` - relative path to minimal worker 2. `/webworker-demo/minimal-worker.js` - absolute path to minimal worker 3. `./worker.js` - relative path to full worker 4. `/webworker-demo/worker.js` - absolute path to full worker - The worker diagnostics panel will show which path successfully loaded