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:

   # From the typescript-sdk root directory

   npm run build

   

2. Start a web server:

   # From the typescript-sdk/webworker-demo directory

   ./start.sh

   

This script starts a simple HTTP server on port 3000. Alternatively, you can use:

   # 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