mcp-demo-streamable-http-bridge

docker

介绍

mcp-demo-streamable-http-bridge

mcp-demo-streamable-http-bridge

Related MCP server: TianGong-AI-MCP

介绍

这是一个演示项目，用于展示如何将 stdio 协议转换为 streamable-http 协议的桥接服务器。项目包含两个版本：

• TypeScript 版本 (main.ts) - 增强版本，支持多服务器、配置文件、热重载等高级功能

软件架构

该桥接服务器使用 JavaScript/TypeScript 编写，基于 Node.js 平台，通过 HTTP 协议与客户端进行交互。

安装教程

1. 确保已安装 Node.js 和 npm。

2. 克隆仓库到本地。

3. 进入项目目录并运行 npm install 安装依赖。

4. 编译 TypeScript 版本（如果需要）：npx tsc main.ts

使用说明

版本选择

TypeScript 版本 (main.ts)

推荐使用，支持以下高级功能：

• 多 MCP 服务器同时运行

• 配置文件支持

• 命令行参数解析

• 热重载配置

• 更好的错误处理和日志

把 stdio 协议转为 streamable-http 协议

此桥接服务器可以接收来自 stdio 的输入，并将其转换为 HTTP 请求，以便在 HTTP 协议下进行通信。

TypeScript 版本使用说明

编译和运行

命令行参数

TypeScript 版本支持以下命令行参数：

使用示例

配置文件支持

TypeScript 版本支持 JSON 配置文件，默认为settings.json。配置文件示例：

配置文件参数说明

• pathPrefix: URL 路径前缀（默认："/mcp"）

• hotReload: 是否启用配置文件热重载（默认：false）

• apiKey: API 认证密钥（可选）

• port: 服务器监听端口（默认：3000）

• host: 服务器绑定主机（默认："localhost"）

• corsAllowOrigins: CORS 允许的源列表（默认：["*"]）

• mcpServers: MCP 服务器配置对象

mcpServers 配置

mcpServers对象支持配置多个 MCP 服务器，每个服务器包含：

• command: 启动命令

• args: 命令参数数组

热重载功能

启用热重载后，当配置文件发生变化时，服务器会自动重新加载配置并重启 MCP 服务器：

多服务器支持

TypeScript 版本支持同时运行多个 MCP 服务器，所有服务器的工具、提示和资源都会被桥接到 HTTP 接口：

举例,可以通过这些网址访问 mcp 服务器的 memory 和 time 工具:

🌐 Available MCP ws endpoints:

memory

http://localhost:3000/ws/memory

time

http://localhost:3000/ws/time

🌐 Available MCP HTTP endpoints:

memory

http://localhost:3000/mcp/memory

time

http://localhost:3000/mcp/time

🌐 Available MCP SSE endpoints:

SSE Endpoint:

http://localhost:3000/sse/memory

Message Endpoint:

http://localhost:3000/messages/memory

SSE Endpoint:

http://localhost:3000/sse/time

Message Endpoint:

http://localhost:3000/messages/time

环境变量支持

TypeScript 版本仍然支持原有的环境变量配置：

• BRIDGE_STREAMABLE_HTTP_PATH: 覆盖配置文件中的 pathPrefix

• BRIDGE_API_TOKEN: 覆盖配置文件中的 apiKey

• BRIDGE_API_PORT: 覆盖配置文件中的 port

• BRIDGE_API_PWD: 设置 stdio 进程的工作目录

优先级：命令行参数 > 环境变量 > 配置文件 > 默认值

JavaScript 版本使用说明（原始版本）

启动桥接服务器

环境变量配置

桥接服务器支持以下环境变量：

• BRIDGE_STREAMABLE_HTTP_PATH: Streamable HTTP 的路径（stdio→Streamable HTTP 模式，默认：/mcp)

  • Streamable HTTP 的路径（stdio→Streamable HTTP 模式，默认：/mcp)

  • 示例: export BRIDGE_STREAMABLE_HTTP_PATH="/mcp"

• BRIDGE_API_TOKEN: HTTP API Token 认证密钥（可选）

  • 用于启用 HTTP API 的 Token 认证功能

  • 示例: export BRIDGE_API_TOKEN="your-secret-token"

• BRIDGE_API_PORT: 服务器监听端口（可选）

  • 设置桥接服务器监听的 HTTP 端口

  • 默认值: 3000

  • 示例: export BRIDGE_API_PORT=8080

• BRIDGE_API_PWD: 工作目录路径（可选）

  • 设置 stdio 进程的工作目录

  • 默认值: 当前工作目录

  • 示例: export BRIDGE_API_PWD="/path/to/workdir"

HTTP API Token 认证（可选）

为了增加安全性，可以配置 HTTP API Token 认证。在服务器配置中设置 Token，并在客户端请求时提供相应的 Token。

Linux/Mac

在 Linux 或 Mac 系统上，可以直接使用上述命令启动服务器。

Windows

在 Windows 系统上，确保已安装 Node.js，并使用命令提示符运行启动命令。

使用示例（无认证）

启动服务器后，可以通过发送 HTTP 请求来与桥接服务器进行交互。具体请求格式和示例请参考项目文档或代码中的注释。

使用说明

桥接服务器使用说明

启用认证后，所有 HTTP 请求都需要在 Authorization 头中提供 Bearer Token：

使用示例（无认证）

启动后，可以通过 HTTP 请求访问 MCP 服务：

Streamable-HTTP 协议 MCP 服务器配置示例

以下是使用 streamable-http 协议的 MCP 服务器配置文件示例：

1. 基础 streamable-http 配置

创建 mcp-streamable-config.json：

2. 带认证的 streamable-http 配置

创建 mcp-streamable-auth.json：

3. 使用桥接服务器的 streamable-http 配置

创建 settings.json：

5. 客户端连接 streamable-http 配置示例

创建 client-streamable-config.json：

支持的传输协议

TypeScript 版本的桥接服务器通过 selectTransport 函数支持多种传输协议，可以根据不同的配置自动选择合适的传输方式。以下是支持的传输协议及其配置方法：

1. Stdio 传输协议

适用场景: 本地进程间通信，通过标准输入输出进行数据交换。

配置参数:

• command: 启动命令（必需）

• args: 命令参数数组（可选）

• cwd: 工作目录（可选，默认为当前目录或 BRIDGE_API_PWD 环境变量）

• env: 环境变量对象（可选）

• type 或 transport: 设置为 "stdio"（可选）

配置示例:

2. SSE (Server-Sent Events) 传输协议

SSE 客户端模式

适用场景: 服务器向客户端推送实时数据，支持单向通信。

配置参数:

• sseUrl: SSE 服务端点 URL（必需，可通过 url 参数替代）

• headers: 请求头对象（可选）

• type 或 transport: 设置为 "sse"（可选）

配置示例:

SSE 服务器端模式

适用场景:

• 需要将 MCP 服务器作为 SSE 服务器运行

• 为客户端提供 SSE 连接端点

• 支持实时双向通信

配置参数:

• sseServer.enabled: 启用 SSE 服务器模式

• sseServer.endpoint: SSE 端点路径（默认：/sse）

• sseServer.messageEndpoint: SSE 消息端点路径（默认：/messages）

示例配置:

使用方式:

1. 启动服务器：

2. 访问 SSE 端点：

3. 发送消息到 SSE 服务器：

3. WebSocket 传输协议

适用场景: 需要双向实时通信的场景，支持全双工通信。

配置参数:

• wsUrl: WebSocket 服务端点 URL（必需，可通过 url 参数替代）

• headers: 请求头对象（可选）

• type 或 transport: 设置为 "ws"（可选）

配置示例:

4. HTTP/Streamable-HTTP 传输协议

适用场景: 基于 HTTP 的请求-响应模式，支持 RESTful 风格的 API 调用。

配置参数:

• httpUrl: HTTP 服务端点 URL（可通过 url 参数替代）

• headers: 请求头对象（可选）

• type 或 transport: 设置为 "http"（可选）

配置示例:

传输协议选择逻辑

selectTransport 函数按照以下优先级自动选择传输协议：

1. Stdio 协议: 当配置了 command 参数或 transport/type 为 "stdio" 时

2. SSE 客户端协议: 当配置了 sseUrl 或 url 且 transport/type 为 "sse" 时

3. WebSocket 协议: 当配置了 wsUrl 或 url 且 transport/type 为 "ws" 时

4. HTTP 协议: 当配置了 httpUrl 或 url 且 transport/type 为 "http" 时

混合配置示例

支持同时配置多种传输协议的服务器：

支持的 MCP 功能

桥接服务器完整支持 MCP 协议的所有核心功能，包括 Tools、Prompts 和 Resources 的转发和交互。

1. MCP Tools 支持

桥接服务器可以透明地转发所有 MCP Tools 调用，支持以下功能：

2. MCP Prompts 支持

支持 MCP Prompts 的完整生命周期管理：

3. MCP Resources 支持

完整支持 MCP Resources 的读取和管理：

6. 性能优化建议

为了获得最佳性能，建议：

1. 连接池管理: 使用 HTTP/1.1 keep-alive 减少连接开销

2. 批处理请求: 合并多个相关请求

3. 缓存策略: 对静态资源启用缓存

4. 负载均衡: 在生产环境中使用反向代理

7. 安全最佳实践

1. Token 认证: 始终在生产环境中启用 BRIDGE_API_TOKEN

2. HTTPS: 使用反向代理添加 HTTPS 支持

3. CORS: 配置适当的 CORS 策略

4. 速率限制: 实施 API 速率限制

5. 输入验证: 验证所有输入参数

8. 集成示例

与 Cursor 集成

在 Cursor 设置中添加 MCP 服务器：