WebSockets MCP Math Demo

基本能力

产品定位

math-mcp 是一个基于 WebSockets 的 Model Context Protocol (MCP) 参考实现，旨在展示 MCP 协议在实时通信场景下的应用。

核心功能

• 完整的 MCP 客户端-服务器架构
• 通过 Durable Objects 实现持久化的有状态会话
• 基于 WebSockets 的双向实时通信
• 工具发现和调用
• 使用 Cloudflare Workers 进行部署

适用场景

• 实时数学运算服务
• 需要双向实时通信的应用
• 需要持久化会话状态的应用
• 基于 MCP 协议的开发参考

工具列表

• MathAgent: 维护持久化状态的 Durable Object，处理数学运算请求
• WebSocket 客户端/服务器: 实现双向实时通信

常见问题解答

• 连接管理: 通过心跳机制和自动重连处理 WebSocket 连接断开问题
• 状态管理: 使用 Durable Objects 维护连接状态
• 请求/响应配对: 通过消息 ID 跟踪和关联实现

使用教程

使用依赖

• Node.js (v18 或更高版本)
• Wrangler (Cloudflare Workers CLI)
• Cloudflare 账户

安装教程

1. 克隆仓库: bash git clone https://github.com/your-username/mcp-websockets-demo.git cd mcp-websockets-demo/math-mcp

2. 安装依赖: bash npm install

3. 部署服务器: bash cd server wrangler deploy

4. 部署客户端: bash cd ../client wrangler deploy

5. 记录部署后的 URL，用于访问应用

调试方式

Web 界面

1. 在浏览器中打开客户端 URL
2. 可以:
3. 连接到 MCP 服务器
4. 运行数学运算
5. 查看 WebSocket 消息日志

编程 API

// 创建代理
const agentResponse = await fetch('https://your-server.workers.dev/agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'MathAgent' })
});
const { agentId } = await agentResponse.json();

// 建立 WebSocket 连接
const ws = new WebSocket(`wss://your-server.workers.dev/agent/${agentId}/websocket`);

// 监听消息
ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
});

// 发送 MCP 请求
ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    type: 'mcp_request',
    request: {
      method: 'add',
      params: { a: 5, b: 3 }
    }
  }));
});

许可证

该项目遵循 Other 开源许可条款，请参阅 Other 了解完整条款。