mcpproxy

# MCP SSE Proxy Server <p align="center"> <img src="assets/logo.png" alt="MCP SSE Proxy Server Logo" width="200"> </p> MCP SSE Proxy Server 是一个基于服务器推送事件（Server-Sent Events, SSE）的模型上下文协议（Model Context Protocol, MCP）代理服务器，能够使用标准的 MCP 协议远程执行 MCP 服务器。它支持共享和独立会话模式。 > 模型上下文协议（MCP）是一个开放协议，标准化了应用程序如何为大型语言模型（LLMs）提供上下文。可以将 MCP 想象成 AI 应用程序的 USB-C 端口。正如 USB-C 提供了一种标准化的方式将设备连接到各种外设和配件，MCP 提供了一种标准化的方式将 AI 模型连接到不同的数据源和工具。 > > 有关 MCP 的更多信息： > - [MCP 文档（英文）](https://modelcontextprotocol.io/introduction) > - [MCP 文档（中文）](https://docs.mcpservers.cn/introduction) > - [MCP 服务器画廊](https://mcpservers.cn/) - 发现和探索各种 MCP 服务器 [中文文档](README_zh.md) ## 它解决了什么问题？ 该项目允许您： - 使用标准的 MCP 协议远程启动和与任何 MCP 服务器交互 - 通过 SSE 维持稳定的长连接 - 支持多个客户端共享一个 MCP 会话或维持独立会话 - 通过请求参数动态配置服务器环境 - 通过 NPX 和 UVX 快速部署 STDIO 进程 ## 系统架构 <p align="center"> <img src="assets/architecture.png" alt="MCP SSE Proxy Server Architecture"> </p> ## 特性 - 支持服务器推送的 SSE 长连接 - 支持 JSON-RPC 2.0 消息格式 - 支持共享和独立会话模式 - 通过请求参数动态配置会话环境 - 自动连接保持（30 秒心跳） - 完整的错误处理和日志记录 - 内置支持 NPX 和 UVX STDIO 进程部署 ## 集成与定制 ### 自定义 Docker 镜像 MCP SSE Proxy Server 设计为高度可集成到各种自定义 Docker 镜像中。这种灵活性允许您为不同的用例创建专门的环境： - **浏览器自动化**：与 Chrome/Chromium 集成，用于基于浏览器的 MCP 服务器 - **数据库操作**：与特定数据库捆绑，用于数据操作的 MCP 服务器 - **开发工具**：与开发工具打包，用于代码相关的 MCP 服务器 - **AI/ML 工具**：包含 AI/ML 库，用于机器学习的 MCP 服务器 ### 高级路由 虽然默认配置通过环境变量加载 MCP 服务器命令，但您可以通过以下方式扩展功能： 1. **多个服务器集成**：通过配置文件配置多个 MCP 服务器 2. **动态路由**：向 SSE 连接添加路由字段，以将流量引导到不同的 MCP 服务器 3. **自定义路由器**：通过扩展此基础实现构建自己的 MCP 路由器项目 这种灵活性允许您： - 创建专门的 MCP 服务器集群 - 在多个服务器之间实现负载均衡 - 根据您的需求设计自定义路由逻辑 - 构建分层的 MCP 服务器架构 ## 配置 ### 环境变量 - `SHARED_SESSION`：控制会话模式 - `true`：共享会话模式（默认），所有客户端共享一个 MCP 会话 - `false`：独立会话模式，每个客户端创建一个单独的 MCP 会话 - `AUTH_KEY`：服务器访问密钥 - 如果设置，所有请求必须提供此密钥 - 通过 URL 参数 `auth_key` 传递 - `MCP_SERVER_CONFIG`：MCP 服务器配置 示例： ```bash # 使用 NPX 运行基于 Node.js 的 MCP 服务器 MCP_SERVER_CONFIG="npx -y @modelcontextprotocol/server-filesystem ." # 使用 UVX 运行基于 Python 的 MCP 服务器 MCP_SERVER_CONFIG="uvx mcp-server-fetch" ``` ### 动态配置 在独立会话模式（`SHARED_SESSION=false`）下，每个 SSE 连接启动一个新的 MCP 服务器进程。您可以通过 URL 参数动态配置每个会话的环境变量： ``` GET /sse?auth_key=xxx&[CUSTOM_ENV]=value ``` 这种机制在需要用户特定凭证的场景中特别有用。例如，在部署 GitHub MCP 服务器时，不同用户可以使用自己的个人访问令牌： 1. 在部署服务器时配置基础命令： ```bash export MCP_SERVER_CONFIG="npx -y @modelcontextprotocol/server-github" ``` 2. 用户在连接时通过 URL 提供他们的令牌： ``` GET /sse?auth_key=xxx&GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx ``` 这样，您只需部署一个 MCP 代理服务器来服务多个用户，每个用户使用自己的 GitHub 凭证。其他支持的环境变量配置： - 一般配置： - `NODE_ENV`：Node.js 环境（development/production） - `DEBUG`：调试日志级别 - 服务器特定配置： - GitHub MCP 服务器：`GITHUB_PERSONAL_ACCESS_TOKEN` - 文件系统 MCP 服务器：`ROOT_DIR` - 其他服务器特定环境变量 注意：URL 参数中的环境变量会覆盖服务器默认配置。 ## API 端点 ### SSE 连接 ``` GET /sse?auth_key=xxx ``` 成功建立连接后，服务器返回消息端点 URL： ``` event: endpoint data: /messages?session_id=<session_id> ``` ### 消息发送 ``` POST /messages?session_id=<session_id> Content-Type: application/json { "jsonrpc": "2.0", "method": "method_name", "params": {}, "id": 1 } ``` ## 支持的方法 - `initialize`：初始化会话 - `tools/list`：列出可用工具 - `tools/call`：调用工具 - `prompts/list`：列出可用提示 - `prompts/get`：获取提示 - `resources/list`：列出资源 - `resources/templates/list`：列出资源模板 - `resources/read`：读取资源 - `resources/subscribe`：订阅资源 - `resources/unsubscribe`：取消订阅资源 ## 运行服务器 ### 使用 Python ```bash # 设置环境变量 export AUTH_KEY=your_key export SHARED_SESSION=true # 或 false # 启动服务器 python main.py ``` 服务器默认在 `0.0.0.0:8000` 启动。 ### 使用 Docker 1. 拉取 Docker 镜像： ```bash docker pull codefriday123/mcpproxy:1.0 ``` 2. 运行容器： ```bash docker run -d \ -p 8000:8000 \ -e AUTH_KEY=your_key \ -e SHARED_SESSION=true \ -e MCP_SERVER_CONFIG="npx -y @modelcontextprotocol/server-filesystem ." \ codefriday123/mcpproxy:1.0 ``` 环境变量： - `AUTH_KEY`：服务器访问密钥（必需） - `SHARED_SESSION`：会话模式（默认：true） - `MCP_SERVER_CONFIG`：MCP 服务器配置命令 服务器将在 `http://localhost:8000` 可用。 ### 使用支付宝云运行 您还可以在 [支付宝云运行](https://cloud.alipay.com/) 上部署服务器（新人可免费使用容器资源）： <p align="center"> <img src="assets/deploy.png" alt="MCP SSE Proxy Server Deployment on Alibaba Cloud"> </p> 1. 在云运行中创建一个新服务 2. 使用以下设置配置服务： - 镜像：`codefriday123/mcpproxy:1.0` - 端口：`8000` - 环境变量： - `AUTH_KEY`：您的服务器访问密钥 - `SHARED_SESSION`：true/false - `MCP_SERVER_CONFIG`：您的 MCP 服务器配置 3. 部署服务 服务器将在提供的云运行端点可用。 ## 日志记录 服务器使用 Python 的日志模块记录详细日志，包括： - 环境变量信息 - 连接建立和关闭 - 消息处理 - 错误和异常 ## 错误处理 服务器使用标准的 JSON-RPC 2.0 错误响应格式： ```json { "jsonrpc": "2.0", "error": { "code": error_code, "message": "error message" }, "id": null } ``` 主要错误代码： - `-32700`：解析错误 - `-32600`：无效请求 - `-32601`：方法未找到 - `-32602`：无效参数 - `-32603`：内部错误 - `-32000`：服务器错误 ## 使用示例 ### Python 客户端 您可以使用官方的 MCP Python 客户端连接到已部署的 MCP 服务器： ```python import asyncio from typing import Optional from contextlib import AsyncExitStack from mcp import ClientSession, LoggingLevel from mcp.client.sse import sse_client class MCPClient: def __init__(self): self.session: Optional[ClientSession] = None self._streams_context = None self._session_context = None self.exit_stack = AsyncExitStack() async def connect_to_sse_server(self, server_url: str): """连接到运行 SSE 传输的 MCP 服务器""" try: print(f"连接到 {server_url}...") self._streams_context = sse_client(url=server_url) streams = await self._streams_context.__aenter__() self._session_context = ClientSession(*streams) self.session = await self._session_context.__aenter__() try: await asyncio.wait_for(self.session.initialize(), timeout=30.0) print("会话初始化成功") except asyncio.TimeoutError: print("会话初始化超时，但将继续") except Exception as e: print(f"连接错误：{e}") await self.cleanup() raise async def cleanup(self): """正确清理会话和流""" try: if hasattr(self, '_session_context') and self._session_context: await self._session_context.__aexit__(None, None, None) if hasattr(self, '_streams_context') and self._streams_context: await self._streams_context.__aexit__(None, None, None) except Exception as e: print(f"清理错误：{e}") async def main(): client = MCPClient() try: await client.connect_to_sse_server('http://your-server:8000/sse?auth_key=your_auth_key') response = await asyncio.wait_for(client.session.list_tools(), timeout=10.0) print(f"可用工具：{[tool.name for tool in response.tools]}") except Exception as e: print(f"错误：{e}") finally: await client.cleanup() if __name__ == "__main__": asyncio.run(main()) ### Cursor 集成 您还可以通过将服务器添加到 Cursor 的 MCP 配置中来集成 [Cursor](https://docs.cursor.com/context/model-context-protocol)： ```json { "mcpServers": { "server-name": { "url": "http://your-server:8000/sse?auth_key=your_auth_key", "env": { } } } } ``` 将此配置放置在以下位置之一： - 项目目录中的 `.cursor/mcp.json` 以进行项目特定访问 - 主目录中的 `~/.cursor/mcp.json` 以进行全局访问 ## 许可证 MIT 许可证 ## 贡献 欢迎贡献！随时提交 Pull Requests。 ## 路线图 ### 当前特性 - 基本的 MCP 服务器代理功能 - SSE 传输支持 - 共享和独立会话模式 - 动态环境配置 - 与 Cursor 和其他 MCP 客户端的集成 ### 未来计划 - **无状态架构** - 仅工具模式以实现无状态操作 - 无需会话管理的基于 HTTP 的工具执行 - 简化的部署和扩展 - 减少资源开销 - 提高可靠性和可维护性 - **代理沙箱** - 创建隔离环境以运行 MCP 代理 - 资源限制和监控 - 对不受信任代理的安全沙箱 - 代理执行的性能优化 - 可流式传输的 HTTP 支持 - 向后兼容可流式传输的 HTTP 协议 - 混合模式：SSE + HTTP 以增强灵活性 - 协议协商和回退机制 - 优化的流式性能 - **代理路由器** - 在多个 MCP 服务器之间进行智能路由 - 负载均衡和故障转移 - 请求/响应转换 - 协议版本兼容性处理 - 高级路由规则和策略 - **最佳实践** - 针对不同场景的部署指南 - 安全建议 - 性能优化技巧 - 监控和日志记录最佳实践 - 与各种 MCP 服务器的集成模式 敬请关注更新和新特性！