MCP stdio to HTTP Streamable Proxy
一个独立的 HTTP 代理服务，将基于 stdio（JSON Lines）协议的 MCP server 转换为支持 HTTP streamable 协议的代理服务。
功能特性
- ✅ 支持 SSE (Server-Sent Events) 和流式 JSON 响应
- ✅ 进程池复用，提高并发性能
- ✅ 多连接支持
- ✅ 自动进程健康监控和恢复
- ✅ 完整的 JSON-RPC 2.0 协议支持
- ✅ 支持本地和云端部署
快速开始
安装依赖
pip install -e .配置环境变量
export MCP_SERVER_COMMAND="your-mcp-server-command"
export MCP_POOL_SIZE=5
export PORT=8000示例：使用 Context7 MCP Server
export MCP_SERVER_COMMAND="npx -y @upstash/context7-mcp"
export MCP_POOL_SIZE=2
export PORT=8000运行服务
python main.py服务将在 http://0.0.0.0:8000 启动。
配置项
必需配置
MCP_SERVER_COMMAND: stdio MCP server 的启动命令（必需）
可选配置
MCP_POOL_SIZE: 进程池大小（默认: 5）MCP_REQUEST_TIMEOUT: 请求超时时间，单位秒（默认: 30.0）MCP_SSE_ENABLED: 是否启用 SSE（默认: true）PORT: HTTP 服务端口（默认: 8000）HOST: HTTP 服务主机（默认: 0.0.0.0）LOG_LEVEL: 日志级别（默认: INFO）
API 文档
POST /mcp
标准 MCP 请求，返回完整的 JSON 响应。
请求示例：
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}'响应示例：
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [...]
}
}POST /mcp/stream
流式 MCP 请求，支持 SSE 或流式 JSON。
查询参数：
format: 响应格式，可选值sse或json（默认:json）
请求示例（流式 JSON）：
curl -X POST http://localhost:8000/mcp/stream?format=json \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {...}
}'请求示例（SSE）：
curl -X POST http://localhost:8000/mcp/stream?format=sse \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {...}
}'GET /health
健康检查端点，返回进程池状态。
响应示例：
{
"status": "healthy",
"pool": {
"pool_size": 5,
"available": 4,
"total": 5,
"in_use": 1,
"initialized": true
}
}架构设计
HTTP Client (SSE/Streamable HTTP)
↓
HTTP Proxy Server (FastAPI)
↓
Process Pool Manager
↓
stdio MCP Server Process (Subprocess)
↓
JSON-RPC over stdio (JSON Lines)进程池管理
服务维护一个 stdio MCP server 进程池，每个 HTTP 请求从池中获取一个进程进行处理。进程支持：
- 自动复用：请求完成后进程返回池中供后续请求使用
- 健康监控：自动检测进程崩溃并替换
- 动态扩容：当池为空时自动创建新进程
- 优雅关闭：服务关闭时正确终止所有进程
协议转换
stdio 协议
MCP stdio 协议使用 JSON Lines 格式，每行一个 JSON 对象：
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}HTTP 协议
HTTP 请求体包含 JSON-RPC 调用，响应可以是：
- 标准响应：完整的 JSON 对象
- SSE 响应：
text/event-stream格式，使用data:前缀 - 流式 JSON：
application/json格式，chunked transfer encoding
测试部署
Context7 MCP Server 示例
查看 DEPLOYMENT.md 了解完整的部署和测试指南。
快速测试：
# 1. 检查前置条件
python3 check_prerequisites.py
# 2. 设置环境变量
export MCP_SERVER_COMMAND="npx -y @upstash/context7-mcp"
export MCP_POOL_SIZE=2
export PORT=8000
# 3. 启动服务
python3.12 main.py
# 4. 测试（在另一个终端）
curl http://localhost:8000/healthCursor IDE 集成
查看 CURSOR_SETUP.md 了解如何在 Cursor IDE 中连接此代理服务。
快速设置：
# 运行自动配置脚本
./setup_cursor.sh
# 或手动配置，参考 CURSOR_SETUP.md文档
- 完整部署指南 - 详细的部署和测试步骤
- Context7 测试指南 - Context7 特定的测试说明
- Cursor IDE 连接指南 - 如何在 Cursor 中配置和使用代理服务
开发
项目结构
mcp-stdio-to-streamble-proxy/
├── src/
│ ├── __init__.py
│ ├── server.py # FastAPI 应用和路由
│ ├── process_pool.py # 进程池管理
│ ├── protocol.py # 协议转换
│ ├── streaming.py # 流式响应处理
│ ├── config.py # 配置管理
│ └── utils.py # 工具函数
├── tests/
│ └── test_*.py # 单元测试
├── pyproject.toml # 项目配置
├── README.md # 项目文档
└── main.py # 入口文件运行测试
pytest tests/许可证
MIT License