MCP Worker

🚀 MCP Web Worker Example Demonstration

This demonstration showcases a Model Context Protocol (MCP) client implemented using a shared web worker architecture. It demonstrates how to use MCP in a browser environment, adopting a decoupled architecture and using only pure JavaScript without any build requirements.

🚀 Quick Start

Prerequisites

1. Install Node.js (version >=14 is recommended).
2. Run npm install in the project root directory.
3. Build production files using npm run build.

Startup Steps

1. Start the development server: npm start.
2. Open your browser and visit http://localhost:8000/webworker-demo/.
3. Test different functional modules and observe console logs and UI feedback.

✨ Features

Browser Support

• Fully Supported: Chrome, Edge (Chromium-based), Opera, Android Chrome
• Partially Supported: Firefox (manual enable required), Safari
• Not Supported: iOS Safari

Core Features

• Decoupled Design: The client and worker run independently without affecting each other.
• Automatic Fallback: If shared workers are not available, it can fallback to other implementation methods.
• Modular: The code is divided by function for easy maintenance and expansion.

📦 Installation

This demonstration uses a decoupled architecture and only requires pure JavaScript, without any build requirements. Just follow the startup steps above to run the project.

💻 Usage Examples

Basic Usage

The demonstration provides an interactive UI (index.html) for testing all MCP functions. You can start the development server and access the UI in your browser to test different functions.

Advanced Usage

You can modify the code in worker.js, mcp-client.js, server.js, etc., to implement more complex MCP functions.

📚 Documentation

Implementation Components

1. Worker Implementation (worker.js)

• Contains code to implement the MCP client in the worker context.
• Demonstrates the message processing pattern on the worker side.
• 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)

• A test demonstration server implementation.
• Provides tools, resources, and tips.
• Implements the MCP request handler.

4. Demonstration UI (index.html)

• An interactive interface for testing all MCP functions.
• Displays loading status, connection status, and log information.
• Contains a worker diagnostic panel that shows the loaded script path and status.

5. Minimal Worker (minimal-worker.js)

• A minimized implementation version that only handles basic connections.
• Used to detect if the browser supports shared workers.
• If it fails, it will fallback to using mcp-client.js.

Message Protocol

The client and server communicate through messages in the following JSON format:

Client Messages

1. "/#/mcp/connect" { "targetUrl": string }
   • Connect to the specified MCP target URL.
2. "/#/mcp/request" { "requestId": string, "payload": any }
   • Send a message with a unique identifier and payload.

Server Messages

1. "/#/mcp/connected" { "connectionId": string }
   • Connection successful, returns the connection ID.
2. "/#/mcp/response" { "requestId": string, "payload": any, "error?": string }
   • Send a response with the original request ID and result.

🔧 Technical Details

Resource Loading Path

The worker script attempts to load from the following paths:

1. ./minimal-worker.js - Relative path to the minimal worker.
2. /webworker-demo/minimal-worker.js - Absolute path to the minimal worker.
3. ./worker.js - Relative path to the full worker.
4. /webworker-demo/worker.js - Absolute path to the full worker.

Worker Diagnostic Panel

Displays the following information:

• Loading Status: Success or failure.
• Connection Status: Connecting, Connected, Disconnected.
• Script Path: The path attempted to load and the result.
• Log Information: Error messages and debug logs.

📄 Troubleshooting

Problem 1: Unable to Obtain Worker Script

• Ensure that you access the demonstration page through a web server, not directly from the file system.
• Check the console for specific error information.
• The worker diagnostic panel will show the attempted paths and results.

Problem 2: Shared Workers Not Supported

• Test using Chrome or Edge browsers.
• The browser console will prompt clear error information.
• Currently, there is no fallback solution for browsers that do not support shared workers.

Problem 3: Module Import Failure

• Ensure that you access the demonstration page through a web server, not directly from the file system.
• Check the console for specific import path errors.
• The worker diagnostic panel will show the attempted paths and results.

Problem 4: Blank Page or No Tools/Resources Displayed

• Open the browser console (F12 or Cmd+Option+I) to view detailed error information.
• Ensure that JavaScript is enabled in your browser.
• Clear the cache and refresh the page.

Problem 5: Path Resolution Issue

• The worker attempts to load scripts from multiple paths, and the worker diagnostic panel will show the results.
• If all paths fail, check the network connection and file existence.