feature: support more transport of mcp server

2025-06-12 07:57:07 +08:00
parent ef39222b83
commit 0ff1abecfb
15 changed files with 2799 additions and 11 deletions
--- a/docs/mcp-http-sse-implementation-plan.md
+++ b/docs/mcp-http-sse-implementation-plan.md
@ -0,0 +1,291 @@
+# 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
+
+**优势**:
+- 保持代码统一性
+- 复用现有逻辑
+- 最小化改动
+
+**实现路径**:
+```javascript
+// 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 服务器实现
+
+```javascript
+// 基础架构
+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` - 接收客户端消息
+
+#### 配置选项
+
+```javascript
+// 命令行参数
+{
+  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 传输
+
+**任务**:
+1. 创建 `MCPStreamableHttpCommand.js`
+2. 实现 StreamableHttpServerTransport 集成
+3. 支持统一端点架构和可选 SSE 升级
+4. 集成现有 MCP 工具处理逻辑
+5. 添加命令行参数支持
+6. 编写单元测试
+
+**预期成果**:
+```bash
+# 启动 Streamable HTTP 服务器
+pnpm start mcp-server --transport http --port 3000
+```
+
+### 阶段 2: SSE 传输兼容支持
+
+**目标**: 实现 SSE 传输的向后兼容
+
+**任务**:
+1. 在同一命令中添加 SSE 传输支持
+2. 实现 SSE 双端点架构
+3. 添加传输类型切换逻辑
+4. 性能优化和错误处理
+5. 兼容性测试
+
+**预期成果**:
+```bash
+# 启动 SSE 服务器（兼容模式）
+pnpm start mcp-server --transport sse --port 3000
+```
+
+### 阶段 3: 生产化增强
+
+**目标**: 完善生产环境特性
+
+**任务**:
+1. CORS 跨域支持
+2. 认证机制集成
+3. 连接池和限流
+4. 监控和日志增强
+5. Docker 部署支持
+
+**预期成果**:
+- 生产就绪的 Streamable HTTP MCP 服务器
+- 完整的部署文档
+- 性能基准测试报告
+
+## 配置管理
+
+### 环境变量支持
+```bash
+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%
+- 零安全漏洞
+- 完整的文档覆盖
+
+## 参考资料
+
+- [MCP 官方文档 - Transports](https://modelcontextprotocol.io/docs/concepts/transports)
+- [MCP SDK 示例 - Streamable HTTP Server](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/simpleStreamableHttp.js)
+- [MCP SDK 示例 - SSE Server](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/simpleSseServer.js)
+- [Streamable HTTP 实现指南](https://blog.christianposta.com/ai/understanding-mcp-recent-change-around-http-sse/)
+- [MCP 协议变更说明](https://blog.christianposta.com/ai/understanding-mcp-recent-change-around-http-sse/)