AI导哈

MCP协议转换代理

一个灵活的代理服务器，可在不同的MCP（模型上下文协议）传输类型之间进行转换，支持流式HTTP和SSE模式，适用于需要协议适配的场景。

  • by charliek
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 charliek/mcp-sse-proxy

使用说明

MCP SSE代理

一种灵活的代理服务器，可以在不同的MCP（模型上下文协议）传输类型之间进行转换：

  • SSE转换为流式HTTP（默认）
  • SSE到SSE

特性

  • 支持两种代理模式：流式HTTP和SSE到SSE
  • 具有可配置级别和颜色的全面日志记录
  • 并发连接的会话管理
  • 对连接维护的心跳支持
  • 错误处理和优雅关机

先决条件

  • Node.js 18+
  • npm
  • 正在运行的MCP服务器（可流式传输HTTP或基于SSE）

安装

npm install

用法

默认模式（SSE到流式HTTP）

# Development
npm run dev

# Production
npm run build
npm start

SSE转SSE模式

# Development
npm run dev:sse

# Production
npm run build
npm run start:sse

命令行选项

# General usage
node dist/proxy.js [options]

Options:
  --mode          Proxy mode: streamable (HTTP) or sse (SSE-to-SSE)
                  [choices: "streamable", "sse"] [default: "streamable"]
  --port          Port to listen on [number] [default: 3000]
  --endpoint      Upstream endpoint URL [string]
                  Default: http://localhost:8080/mcp (streamable)
                          http://localhost:3001/sse (sse)
  --sse-endpoint  SSE endpoint path [string] [default: "/sse"]
  --help          Show help [boolean]

Examples:
  # SSE to HTTP proxy on custom port
  node dist/proxy.js --mode streamable --port 3500 --endpoint http://localhost:9000/mcp

  # SSE to SSE proxy
  node dist/proxy.js --mode sse --endpoint http://another-server.com/sse

配置

日志记录配置

代理使用灵活的日志记录系统，可以通过以下方式配置 logging.config.json 或环境变量。

默认logging.config.json：

{
  "levels": {
    "CONNECTION": { "enabled": true, "color": "green", "showPayload": true },
    "REQUEST": { "enabled": true, "color": "cyan", "showPayload": true },
    "FORWARD": { "enabled": true, "color": "yellow", "showPayload": true },
    "RESPONSE": { "enabled": true, "color": "magenta", "showPayload": true },
    "SSE": { "enabled": true, "color": "blue", "showPayload": false },
    "ERROR": { "enabled": true, "color": "red", "showPayload": true },
    "DEBUG": { "enabled": false, "color": "gray", "showPayload": true },
    "SYSTEM": { "enabled": true, "color": "white", "showPayload": false }
  },
  "showTimestamps": true,
  "showPayloads": false
}

环境变量

  • LOG_LEVELS：启用日志级别的逗号分隔列表（例如。， CONNECTION,REQUEST,ERROR)
  • LOG_COLORS：逗号分隔的级别列表：颜色对（例如。， CONNECTION:blue,ERROR:red)
  • LOG_SHOW_PAYLOADS：全局有效载荷显示设置(true 或 false)
  • LOG_PAYLOADS：每级有效载荷设置（例如。， REQUEST:true,RESPONSE:false)
  • LOG_SHOW_TIMESTAMPS：是否显示时间戳(true 或 false)

环境变量使用示例

# Show payloads only for REQUEST and FORWARD categories
LOG_PAYLOADS=REQUEST:true,FORWARD:true,RESPONSE:false npm run dev

# Enable all logs with payloads for debugging
LOG_LEVELS=CONNECTION,REQUEST,FORWARD,RESPONSE,SSE,DEBUG LOG_SHOW_PAYLOADS=true npm run dev

# Custom configuration with selective payloads
LOG_PAYLOADS=REQUEST:true,ERROR:true LOG_LEVELS=CONNECTION,REQUEST,ERROR,SYSTEM npm run dev

建筑

流模式（SSE→ HTTP)

  1. SSE客户端连接到 /sse 端点
  2. 服务器创建会话并发送 endpoint 带路径的事件
  3. 客户端将JSON-RPC消息POST到 /messages/{sessionId}
  4. 代理将请求转发到可流式传输的HTTP MCP服务器
  5. 流式响应通过SSE连接发回

SSE 模式 （SSE → SSE）

  1. SSE客户端连接到 /sse 端点
  2. 服务器创建会话和上游SSE连接
  3. 消息在客户端和上游之间双向中继
  4. 为双方管理连接生命周期
[SSE Client] <--SSE--> [This Proxy] <--HTTP Stream or SSE--> [MCP Server]

代理处理：

  • SSE连接管理
  • 会话跟踪
  • 请求/响应转发
  • 错误处理
  • 连接心跳

API终点

  • GET /sse -SSE连接端点
  • POST /messages/:sessionId -消息转发端点
  • GET /health -健康检查端点（返回状态、模式和连接计数）

连接客户

启动代理后，您可以将MCP SSE客户端连接到它：

  1. SSE端点将在以下位置可用： http://localhost:3000/sse
  2. 当客户端连接时，他们将收到 endpoint 带有发送消息的URL的事件
  3. 然后，客户端应将JSON-RPC消息POST到提供的端点

Claude.ai示例

  1. 启动MCP服务器（可流式传输HTTP或SSE）
  2. 以适当的模式启动此代理服务器
  3. 在Claude.ai中，转到集成
  4. 添加SSE端点URL: http://localhost:3000/sse

错误处理

代理处理各种错误情况：

  • 与上游服务器的连接失败
  • JSON-RPC消息无效
  • 流错误
  • 客户端断开连接
  • 会话未找到错误

所有错误都会记录到控制台，并将相应的错误响应发送回客户端。

发展

# Install dependencies
npm install

# Run in development mode (default: streamable)
npm run dev

# Run in SSE mode
npm run dev:sse

# Build TypeScript
npm run build

# Run built version
npm start

故障排除

  • 检查控制台日志以获取详细的连接和消息信息
  • 验证您的MCP服务器是否正在运行且可访问
  • 如果在不同的机器上运行，请确保正确的防火墙/网络访问
  • 检查SSE客户端是否正在发送有效的JSON-RPC请求
  • 使用健康终结点检查状态和连接计数

许可证

国际协调委员会

相关 MCP