Math MCP

🚀 WebSockets Model Context Protocol (MCP) Implementation

This reference implementation demonstrates how to leverage the WebSocket protocol to extend the Model Context Protocol (MCP) within the Cloudflare Workers environment. It enables real - time communication scenarios, such as high - frequency trading, real - time collaborative environments, and interactive agents requiring rapid responses.

🚀 Quick Start

This project showcases how to use WebSocket to expand the Model Context Protocol (MCP) in the Cloudflare Workers environment. It supports various real - time communication scenarios.

✨ Features

Request/Response Protocol

• Each WebSocket message contains the following fields:
  • type: Message type (request/response)
  • id: Unique request identifier
  • method: MCP method name
  • params: Request parameters
  • timestamp: Timestamp

Streaming Data Processing

• Supports fragmented transmission of large files.
• Implements a streaming result feedback mechanism.
• Ensures data integrity and order.

Heartbeat Detection

• Sends heartbeat packets periodically to maintain the connection.
• Monitors connection status changes.
• Handles reconnection logic in case of disconnection.

Advantages over Traditional HTTP Requests

1. Real - time Performance
   • Maintains long - term connections.
   • Reduces request latency.
2. Bandwidth Efficiency
   • Reduces the number of round - trips.
   • Improves data transmission efficiency.
3. Scalability
   • Supports large - scale concurrent connections.
   • Suitable for high - throughput scenarios.

📦 Installation

No installation steps are provided in the original README, so this section is skipped.

💻 Usage Examples

Basic Usage

import { MCPClient } from '@modelcontextprotocol/typescript-sdk';

// Create WebSocket transport layer
class WebSocketTransport implements MCPTransport {
  private ws: WebSocket;
  private pendingRequests: Map<string, { resolve: (result: any) => void, reject: (error: any) => void}>;

  constructor(serverUrl: string, agentId: string) {
    this.ws = new WebSocket(`${serverUrl}/agent/${agentId}/websocket`);
    this.pendingRequests = new Map();
    
    this.ws.addEventListener('message', this.handleMessage.bind(this));
  }
  
  async send(method: string, params: any): Promise<any> {
    return new Promise((resolve, reject) => {
      const requestId = crypto.randomUUID();
      
      this.pendingRequests.set(requestId, { resolve, reject });
      
      this.ws.send(JSON.stringify({
        type: 'mcp_request',
        request: { method, params },
        requestId
      }));
    });
  }
  
  private handleMessage(event: MessageEvent) {
    const message = JSON.parse(event.data);
    
    if (message.type === 'mcp_response' && message.requestId) {
      const pending = this.pendingRequests.get(message.requestId);
      if (pending) {
        pending.resolve(message.result);
        this.pendingRequests.delete(message.requestId);
      }
    }
  }
}

// Connect to MCP client using the transport
const transport = new WebSocketTransport('wss://example.com', 'agent-123');
const client = new MCPClient({ transport });

// Invoke MCP method as usual
const result = await client.invoke('add', { a: 5, b: 3 });

Advanced Usage

class WebSocketHandler {
  private ws: WebSocket;

  constructor(private readonly agentId: string) {}

  async handleRequest(request: Request): Promise<Response> {
    const response = new Response(null, {
      status: 101,
      webSocket: await this.upgradeToWebSocket(request)
    });
    
    return response;
  }

  private upgradeToWebSocket(request: Request): Promise<WebSocket> {
    // Implement WebSocket upgrade logic
    // Return a new WebSocket connection instance
  }
}

📚 Documentation

Project Structure

.
├── src/
│   ├── mcp-websocket.ts    # WebSocket transport layer implementation
│   └── mcp-client.ts      # MCP client extension
└── README.md              # Project documentation

Implementation Details

Core Components

1. WebSocket Connection Management
   • Utilizes the native WebSocket support of Cloudflare Workers.
   • Integrates into the existing MCP client architecture.
2. Bidirectional Communication Protocol
   • Request/response message format.
   • Streaming data processing mechanism.
   • Heartbeat detection and connection status monitoring.
3. State Management
   • Uses Durable Objects to maintain WebSocket connection states.
   • Associates session history with context.

Challenges and Solutions

Main Challenges

1. Complexity of State Management
   • Solution: Use Durable Objects to maintain session states.
2. Message Reliability
   • Solution: Implement an acknowledgment mechanism and retransmission strategy.
3. Error Handling
   • Solution: Define a unified error encoding and feedback mechanism.

🔧 Technical Details

This implementation focuses on using WebSocket in the Cloudflare Workers environment to expand the Model Context Protocol (MCP). It includes core components such as WebSocket connection management, bidirectional communication protocols, and state management. The key technologies used are the native WebSocket support of Cloudflare Workers and Durable Objects for state management.

📄 License

This project is licensed under the MIT License.
Copyright (c) 2023 Your Name.

Contact Information

• Project URL: WebSockets over MCP
• Author's Email: contact@your-domain.com
• Discussion Group: Join the MCP Developer Community