MCP Stdio To Streamble Proxy

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/health

Cursor 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