MCP 通信服务器

一个支持页面与客户端数据通信的MCP (Model Context Protocol) 服务器实现。

🏗️ 架构设计

本项目采用分离式架构设计：

• MCP 服务器 (src/index.ts) - 纯粹的MCP协议服务器，提供工具和资源
• Web 服务器 (src/web-server.ts) - 独立的HTTP/WebSocket服务器，处理静态文件和实时通信

📦 安装依赖

npm install

🚀 启动服务

方式1：分别启动（推荐用于开发）

# 编译TypeScript代码
npm run build

# 启动Web服务器 (端口3001)
npm run start:web

# 启动MCP服务器 (在另一个终端)
npm run start

方式2：同时启动两个服务

npm run build
npm run start:both

方式3：只启动Web服务器

npm run build
npm run start:web

🌐 访问地址

启动Web服务器后，可以通过以下URL访问：

• 主页: http://localhost:3001/
• 测试页面: http://localhost:3001/test-page.html
• 服务器状态: http://localhost:3001/api/status
• 连接列表: http://localhost:3001/api/connections

🛠️ MCP 工具

MCP服务器提供以下工具：

1. open_web_page

• 功能: 在浏览器中打开指定URL
• 参数: url (string) - 要打开的网页地址
• 示例:

  open_web_page("http://localhost:3001/test-page.html")
  

2. list_connections

• 功能: 列出所有活跃的WebSocket连接
• 参数: 无
• 返回: 当前所有连接ID列表

3. get_page_data

• 功能: 获取页面发送的数据
• 参数: connectionId (可选) - 指定连接ID，不提供则返回所有数据
• 返回: 页面数据的JSON格式

4. send_to_page

• 功能: 向指定页面发送消息
• 参数:
  • connectionId (string) - 目标连接ID
  • message (any) - 要发送的消息内容

🔄 通信流程

1. 建立连接：网页通过WebSocket连接到 ws://localhost:3001
2. 获取连接ID：服务器自动分配唯一连接ID
3. 发送数据：网页发送数据到服务器（如页面状态、用户输入等）
4. MCP交互：通过MCP工具获取数据或发送指令
5. 实时通信：支持双向实时数据交换

📝 消息格式

页面发送到服务器

{
  "type": "page_data",
  "data": {
    "page": "test",
    "user_input": "Hello World",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

服务器发送到页面

{
  "type": "mcp_message",
  "message": {
    "command": "update_ui",
    "data": "Some data from MCP client"
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

🔧 开发

监听模式开发

# 在一个终端启动TypeScript监听编译
npm run dev

# 在另一个终端启动Web服务器
npm run start:web

# MCP服务器需要手动重启来加载新代码
npm run start

添加新的MCP工具

在 src/index.ts 中使用 server.registerTool() 添加新工具。

扩展Web API

在 src/web-server.ts 中添加新的HTTP端点或WebSocket消息处理逻辑。

📁 项目结构

mcp/
├── src/
│   ├── index.ts          # MCP服务器
│   └── web-server.ts     # Web服务器
├── test-page.html        # 测试页面
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
└── README.md            # 说明文档

💡 使用场景

• 网页与AI助手的实时数据交换
• 浏览器插件与MCP客户端通信
• 在线工具与外部服务集成
• 实时协作应用开发

⚠️ 注意事项

1. 确保防火墙允许3001端口访问
2. 在生产环境中需要配置HTTPS和WSS
3. 考虑添加身份验证和授权机制
4. 监控WebSocket连接数量，避免资源泄露