7.2 KiB
7.2 KiB
MCP Streamable HTTP 传输实现规划
概述
本文档规划在 PromptX 项目中实现 MCP (Model Context Protocol) Streamable HTTP 传输的技术方案，同时提供 SSE 向后兼容支持。
背景分析
当前状态
- PromptX 目前仅支持 stdio 传输方式 (
MCPServerCommand.js) - 使用
@modelcontextprotocol/sdk@1.12.1，已包含 SSE 传输支持 - 启动方式：
pnpm start mcp-server(默认 stdio)
需求驱动
- 需要支持基于 HTTP 的 MCP 服务器实例
- 为 Web 客户端和远程访问提供现代化支持
- 采用最新 MCP 协议标准，确保长期兼容性
- 提供更灵活的部署选项
技术方案
传输协议选择
Streamable HTTP 传输（主要方案）
- 状态: MCP 协议当前推荐的标准传输方式
- 特点:
- 统一 HTTP POST 端点
- 无状态连接，支持 SSE 可选升级
- 支持会话管理和连接恢复
- 优势:
- 现代化架构，更好的可扩展性
- 简化客户端实现
- 更好的负载均衡支持
- 符合 REST 架构原则
SSE 传输（兼容方案）
- 状态: 在协议版本 2024-11-05 中被标记为弃用
- 特点: 双端点架构（GET 建立 SSE 流，POST 接收消息）
- 适用: 向后兼容现有客户端，过渡期使用
实现架构
方案一：扩展现有 MCPServerCommand
优势:
- 保持代码统一性
- 复用现有逻辑
- 最小化改动
实现路径:
// MCPServerCommand.js 修改
async execute(options = {}) {
const { transport = 'stdio', port = 3000 } = options;
switch (transport) {
case 'stdio':
return this.startStdioServer();
case 'http':
return this.startStreamableHttpServer(port);
case 'sse':
return this.startSSEServer(port); // 兼容支持
default:
throw new Error(`Unsupported transport: ${transport}`);
}
}
方案二：创建专用 HTTP 服务器命令
优势:
- 职责分离，代码清晰
- 便于独立测试和维护
- 避免原有功能的副作用
实现路径:
src/lib/commands/
├── MCPServerCommand.js # stdio 传输
├── MCPStreamableHttpCommand.js # Streamable HTTP 传输（主要）
└── index.js # 命令导出
详细设计
Streamable HTTP 服务器实现
// 基础架构
class MCPStreamableHttpCommand {
constructor() {
this.name = 'promptx-mcp-streamable-http-server';
this.version = '1.0.0';
}
async execute(options = {}) {
const {
transport = 'http', // 'http' | 'sse'
port = 3000,
host = 'localhost'
} = options;
if (transport === 'http') {
return this.startStreamableHttpServer(port, host);
} else if (transport === 'sse') {
return this.startSSEServer(port, host); // 兼容支持
}
}
async startStreamableHttpServer(port, host) {
// 使用 StreamableHttpServerTransport
// 实现现代化统一端点架构
}
async startSSEServer(port, host) {
// 使用 Express + SSEServerTransport
// 向后兼容双端点架构
}
}
端点设计
Streamable HTTP 端点（主要）:
POST /mcp- 统一入口端点- 接收所有 JSON-RPC 消息
- 支持可选 SSE 流式响应
- 支持会话管理（sessionId）
- 无状态设计，便于负载均衡
SSE 传输端点（兼容）:
GET /mcp- 建立 SSE 连接POST /messages- 接收客户端消息
配置选项
// 命令行参数
{
transport: 'stdio' | 'http' | 'sse', // 'http' 为推荐默认值
port: number, // HTTP 端口 (默认: 3000)
host: string, // 绑定地址 (默认: localhost)
cors: boolean, // CORS 支持 (默认: false)
auth: boolean, // 认证开关 (默认: false)
streaming: boolean, // SSE 流式响应 (默认: true)
maxConnections: number // 最大连接数 (默认: 100)
}
实现计划
阶段 1: Streamable HTTP 传输支持（主要目标）
目标: 实现 MCP 推荐的 Streamable HTTP 传输
任务:
- 创建
MCPStreamableHttpCommand.js - 实现 StreamableHttpServerTransport 集成
- 支持统一端点架构和可选 SSE 升级
- 集成现有 MCP 工具处理逻辑
- 添加命令行参数支持
- 编写单元测试
预期成果:
# 启动 Streamable HTTP 服务器
pnpm start mcp-server --transport http --port 3000
阶段 2: SSE 传输兼容支持
目标: 实现 SSE 传输的向后兼容
任务:
- 在同一命令中添加 SSE 传输支持
- 实现 SSE 双端点架构
- 添加传输类型切换逻辑
- 性能优化和错误处理
- 兼容性测试
预期成果:
# 启动 SSE 服务器（兼容模式）
pnpm start mcp-server --transport sse --port 3000
阶段 3: 生产化增强
目标: 完善生产环境特性
任务:
- CORS 跨域支持
- 认证机制集成
- 连接池和限流
- 监控和日志增强
- Docker 部署支持
预期成果:
- 生产就绪的 Streamable HTTP MCP 服务器
- 完整的部署文档
- 性能基准测试报告
配置管理
环境变量支持
MCP_TRANSPORT=http # 传输类型（推荐默认值）
MCP_PORT=3000 # 服务端口
MCP_HOST=localhost # 绑定地址
MCP_CORS_ENABLED=false # CORS 开关
MCP_STREAMING=true # SSE 流式响应
MCP_MAX_CONNECTIONS=100 # 最大连接数
测试策略
单元测试
- 传输类型选择逻辑
- HTTP 端点处理
- 错误处理机制
- 参数验证
集成测试
- 完整 MCP 会话流程
- 多客户端并发连接
- 传输协议兼容性
- 工具调用端到端测试
部署考虑
开发环境
- 本地调试支持
- 热重载机制
- 详细日志输出
生产环境
- 进程管理 (PM2)
- 反向代理 (Nginx)
- HTTPS 支持
- 监控告警
兼容性
MCP 客户端兼容性
- Claude Desktop
- MCP Inspector
- 自定义 MCP 客户端
协议版本兼容性
- 支持当前协议版本
- 向后兼容弃用特性
- 平滑迁移路径
风险评估
技术风险
- SSE 传输弃用风险 → 优先实现 Streamable HTTP
- 并发性能瓶颈 → 连接池和限流机制
- 内存泄漏风险 → 完善资源清理
维护风险
- 代码复杂度增加 → 清晰的架构分层
- 测试覆盖率下降 → 完善的测试策略
成功指标
功能指标
- 支持 Streamable HTTP 传输启动
- 支持 SSE 兼容传输
- 多传输类型无缝切换
- 完整的工具调用功能
性能指标
- 支持 > 50 并发连接
- 消息延迟 < 100ms
- 内存使用 < 500MB
质量指标
- 测试覆盖率 > 80%
- 零安全漏洞
- 完整的文档覆盖