# mcp-porter-server

**Repository Path**: ncnynl/mcp-porter-server

## Basic Information

- **Project Name**: mcp-porter-server
- **Description**: mcp-porter-server,基于mcp-endpoint-server的http/sse代理中介，提供给openclaw-mcp-adapter使用

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-19
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Porter Server

一个通用的MCP（Model Context Protocol）代理服务器，实现WebSocket到SSE（Server-Sent Events）的双向通信桥接。

## 项目简介

MCP Porter Server 是一个中间件代理，用于连接支持MCP协议的客户端（如OpenClaw）与远程MCP服务器。它实现了真正的MCP over SSE双向通信，同时兼容`mcporter`和`openclaw-mcp-adapter`。

## 主要功能

- **双向通信桥接**：将WebSocket协议转换为SSE协议，实现客户端与MCP服务器的双向通信
- **通用MCP代理**：支持任意MCP工具调用，无需硬编码参数
- **工具发现**：自动发现远程MCP服务器提供的工具列表
- **实时通知**：支持服务器向客户端推送通知
- **Docker支持**：提供完整的Docker和Docker Compose部署方案

## 技术栈

- **Python 3.12+**
- **FastAPI**：高性能Web框架
- **WebSockets**：WebSocket客户端/服务器实现
- **Uvicorn**：ASGI服务器
- **Docker**：容器化部署

## 快速开始

### 1. 环境准备

确保已安装：
- Python 3.12+
- Docker 和 Docker Compose（可选）
- Git

### 2. 克隆项目

```bash
git clone https://gitee.com/ncnynl/mcp-porter-server.git
cd mcp-porter-server
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境变量

创建 `.env` 文件：

```bash
# 远程MCP服务器WebSocket地址
REMOTE_WS_URL=ws://127.0.0.1:8004/mcp_endpoint/call/?token=your_token_here

# 可选：代理服务器端口
PORT=8000
```

### 5. 运行服务器

#### 方式一：直接运行

```bash
python ws2sse_proxy.py
```

#### 方式二：使用Docker

```bash
# 构建镜像
docker build -t mcp-porter-server .

# 运行容器
docker run -p 8000:8000 --env-file .env mcp-porter-server
```

#### 方式三：使用Docker Compose

```bash
# 确保存在共享网络
docker network create mcp-shared-network

# 启动服务
docker-compose up -d
```

## 项目结构

```
mcp-porter-server/
├── ws2sse_proxy.py          # 主代理服务器代码
├── requirements.txt         # Python依赖包
├── Dockerfile              # Docker构建配置
├── docker-compose.yml      # Docker Compose配置
├── install.sh              # 安装脚本
├── nohup.sh                # 后台运行脚本
├── run_proxy.sh            # 代理运行脚本
├── run_test.sh             # 测试运行脚本
├── test_proxy.py           # 增强版代理测试脚本
├── test_notification.py    # 通知测试脚本
├── ws2sse_proxy.py.bk      # 备份文件
└── .gitignore             # Git忽略文件
```

## API接口

### 1. MCP JSON-RPC端点
- **POST** `/mcp` - 标准MCP JSON-RPC端点（推荐使用）
  - 支持所有MCP方法：`tools/list`, `tools/call`, `notifications/initialized`等

### 2. SSE端点
- **GET** `/sse` - SSE流式连接端点（仅用于工具发现）

### 3. WebSocket端点
- **WS** `/ws` - WebSocket端点（可选）

### 4. 健康检查
- **GET** `/health` - 健康检查端点

## 使用示例

### 1. 获取工具列表

```bash
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

### 2. 调用工具

```python
import requests
import json

url = "http://localhost:8000/mcp"
payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "tool_name",
        "arguments": {
            "param1": "value1",
            "param2": "value2"
        }
    }
}

response = requests.post(url, json=payload)
print(json.dumps(response.json(), indent=2))
```

### 3. 测试脚本

项目包含两个测试脚本：

```bash
# 测试代理功能
python test_proxy.py --url http://localhost:8000/call_tool

# 测试通知功能
python test_notification.py
```

## 配置说明

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `REMOTE_WS_URL` | `ws://127.0.0.1:8004/mcp_endpoint/call/?token=...` | 远程MCP服务器地址 |
| `PORT` | `8000` | 代理服务器端口 |
| `TZ` | `Asia/Shanghai` | 时区设置 |

### Docker配置

- **端口映射**: 8000:8000
- **网络**: 使用共享网络 `mcp-shared-network`
- **卷挂载**: 当前目录挂载到容器 `/app`
- **重启策略**: 总是重启

## 开发指南

### 1. 代码结构

- `ws2sse_proxy.py`：主代理逻辑
  - WebSocket客户端管理
  - SSE服务器实现
  - 请求/响应路由
  - 工具发现和调用

### 2. 添加新功能

1. 在FastAPI应用中添加新的路由
2. 实现对应的处理函数
3. 更新测试脚本
4. 更新文档

### 3. 调试

```bash
# 启用调试日志
export LOG_LEVEL=DEBUG
python ws2sse_proxy.py

# 或直接修改代码中的日志级别
logging.basicConfig(level=logging.DEBUG)
```

## 故障排除

### 常见问题

1. **连接失败**
   - 检查远程MCP服务器是否运行
   - 验证token是否正确
   - 检查网络连接

2. **工具调用失败**
   - 确认工具名称正确
   - 检查参数格式
   - 查看服务器日志

3. **SSE连接断开**
   - 检查客户端是否支持SSE
   - 查看网络稳定性
   - 检查代理服务器日志

### 日志查看

```bash
# Docker容器日志
docker logs mcp-porter

# 直接运行日志
tail -f proxy.log
```

## 性能优化

1. **连接池**：复用WebSocket连接
2. **缓存**：缓存工具列表和schema
3. **异步处理**：使用asyncio提高并发性能
4. **压缩**：启用响应压缩

## 安全考虑

1. **Token保护**：不要将token硬编码在代码中
2. **输入验证**：验证所有客户端输入
3. **速率限制**：防止滥用
4. **HTTPS**：生产环境使用HTTPS

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 推送分支
5. 创建Pull Request

## 许可证

本项目采用MIT许可证。详见LICENSE文件。

## 联系方式

- 项目地址：https://gitee.com/ncnynl/mcp-porter-server
- 问题反馈：请使用Git Issues

## 更新日志

### v1.0.0
- 初始版本发布
- 实现WebSocket到SSE双向通信
- 支持工具发现和调用
- 提供Docker部署方案

---

**注意**：本项目为MCP协议的中间件，需要配合MCP服务器使用。确保远程MCP服务器已正确配置并运行。
## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.