README.md•3.82 kB
# MCP 通信服务器
一个支持页面与客户端数据通信的MCP (Model Context Protocol) 服务器实现。
## 🏗️ 架构设计
本项目采用分离式架构设计：
- **MCP 服务器** (`src/index.ts`) - 纯粹的MCP协议服务器，提供工具和资源
- **Web 服务器** (`src/web-server.ts`) - 独立的HTTP/WebSocket服务器，处理静态文件和实时通信
## 📦 安装依赖
```bash
npm install
```
## 🚀 启动服务
### 方式1：分别启动（推荐用于开发）
```bash
# 编译TypeScript代码
npm run build
# 启动Web服务器 (端口3001)
npm run start:web
# 启动MCP服务器 (在另一个终端)
npm run start
```
### 方式2：同时启动两个服务
```bash
npm run build
npm run start:both
```
### 方式3：只启动Web服务器
```bash
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. **实时通信**：支持双向实时数据交换
## 📝 消息格式
### 页面发送到服务器
```json
{
"type": "page_data",
"data": {
"page": "test",
"user_input": "Hello World",
"timestamp": "2024-01-01T00:00:00Z"
}
}
```
### 服务器发送到页面
```json
{
"type": "mcp_message",
"message": {
"command": "update_ui",
"data": "Some data from MCP client"
},
"timestamp": "2024-01-01T00:00:00Z"
}
```
## 🔧 开发
### 监听模式开发
```bash
# 在一个终端启动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连接数量，避免资源泄露