mcp-demo-streamable-http-bridge

Name: mcp-demo-streamable-http-bridge
Availability: InStock
Author: masx200

GitHub

GitHub Stars

User Rating

Not Rated

Favorites

Views

Forks

Issues

README

mcp-demo-streamable-http-bridge

介绍

mcp-demo-streamable-http-bridge

介绍

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

JavaScript 版本 (bridge-streamable.js) - 原始版本，支持单个 MCP 服务器
TypeScript 版本 (main.ts) -
增强版本，支持多服务器、配置文件、热重载等高级功能

软件架构

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

安装教程

确保已安装 Node.js 和 npm。
克隆仓库到本地。
进入项目目录并运行 npm install 安装依赖。
编译 TypeScript 版本（如果需要）：npx tsc main.ts

使用说明

版本选择

JavaScript 版本 (bridge-streamable.js)

适合简单场景，支持单个 MCP 服务器桥接。

TypeScript 版本 (main.ts)

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

多 MCP 服务器同时运行
配置文件支持
命令行参数解析
热重载配置
更好的错误处理和日志

把 stdio 协议转为 streamable-http 协议

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

TypeScript 版本使用说明

编译和运行

# 编译TypeScript文件
npx tsc main.ts

# 运行编译后的文件
node main.js

# 或者直接运行（需要ts-node）
npx ts-node main.ts

命令行参数

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

node main.js [选项]

选项：
  --hot-reload          启用配置文件热重载
  --version             显示版本信息
  --config <路径>       指定配置文件路径（默认：settings.json）
  --api-key <密钥>      设置API认证密钥
  --port <端口>         设置监听端口（默认：3000）
  --host <主机>         设置绑定主机（默认：localhost）
  --cors-allow-origins <域名>  设置CORS允许的源（可多次使用）
  --path-prefix <路径>  设置URL路径前缀（默认：/mcp）
  --sse-server-enabled  启用SSE服务器模式
  --sse-endpoint <路径>  SSE服务器端点路径（默认：/sse）
  --sse-message-endpoint <路径>  SSE服务器消息端点路径（默认：/messages）
  -h, --help            显示帮助信息

使用示例

# 基本启动
node main.js

# 启用热重载
node main.js --hot-reload

# 指定配置文件
node main.js --config my-config.json

# 设置端口和API密钥
node main.js --port 8080 --api-key my-secret-key

# 设置CORS允许的源
node main.js --cors-allow-origins http://localhost:3000 --cors-allow-origins http://localhost:8080

配置文件支持

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

{
  "pathPrefix": "/mcp",
  "hotReload": true,
  "apiKey": "your-secret-api-key",
  "port": 3000,
  "host": "0.0.0.0",
  "corsAllowOrigins": ["*"],
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.json"
      }
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}

配置文件参数说明

pathPrefix: URL 路径前缀（默认："/mcp"）
hotReload: 是否启用配置文件热重载（默认：false）
apiKey: API 认证密钥（可选）
port: 服务器监听端口（默认：3000）
host: 服务器绑定主机（默认："localhost"）
corsAllowOrigins: CORS 允许的源列表（默认：["*"]）
mcpServers: MCP 服务器配置对象

mcpServers 配置

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

command: 启动命令
args: 命令参数数组

热重载功能

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

# 启用热重载
node main.js --hot-reload

# 或在配置文件中设置
{
  "hotReload": true
}

多服务器支持

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

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.json"
      }
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}

举例,可以通过这些网址访问 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 版本使用说明（原始版本）

启动桥接服务器

运行以下命令启动桥接服务器：

node bridge-streamable.js

环境变量配置

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

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
请求来与桥接服务器进行交互。具体请求格式和示例请参考项目文档或代码中的注释。

使用说明

把 stdio 协议转为 streamable-http 协议

node bridge-streamable.js "cmd" "/c"  "npx" "-y"  "@gitee/mcp-gitee@latest" -token <GITEE_ACCESS_TOKEN>

桥接服务器使用说明

启动桥接服务器

node bridge-streamable.js node index-stdio.js

环境变量配置

可以通过设置以下环境变量来配置桥接服务器：

# Linux/Mac
export BRIDGE_API_TOKEN="your-secret-token"      # 可选：Token认证
export BRIDGE_API_PORT=8080                       # 可选：端口配置，默认3000
export BRIDGE_API_PWD="/path/to/workdir"          # 可选：工作目录
node bridge-streamable.js node index-stdio.js

# Windows
set BRIDGE_API_TOKEN=your-secret-token
set BRIDGE_API_PORT=8080
set BRIDGE_API_PWD=C:\\path\\to\\workdir
node bridge-streamable.js node index-stdio.js

HTTP API Token 认证（可选）

可以通过设置环境变量BRIDGE_API_TOKEN来启用 HTTP API Token 认证：

# Linux/Mac
export BRIDGE_API_TOKEN="your-secret-token"
node bridge-streamable.js node index-stdio.js

# Windows
set BRIDGE_API_TOKEN=your-secret-token
node bridge-streamable.js node index-stdio.js

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

使用示例（无认证）

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

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

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

1. 基础 streamable-http 配置

创建 mcp-streamable-config.json：

{
  "mcpServers": {
    "streamable-gitee": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

2. 带认证的 streamable-http 配置

创建 mcp-streamable-auth.json：

{
  "mcpServers": {
    "streamable-secure": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

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

创建 mcp-bridge-streamable.json：

{
  "mcpServers": {
    "gitee-bridge": {
      "transport": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

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

创建 client-streamable-config.json：

{
  "mcp": {
    "servers": {
      "streamable-server": {
        "transport": {
          "type": "streamable-http",
          "url": "http://localhost:3000/mcp",
          "headers": {
            "User-Agent": "mcp-client/1.0"
          }
        }
      }
    }
  }
}

支持的传输协议

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

1. Stdio 传输协议

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

配置参数:

command: 启动命令（必需）
args: 命令参数数组（可选）
cwd: 工作目录（可选，默认为当前目录或 BRIDGE_API_PWD 环境变量）
env: 环境变量对象（可选）
type 或 transport: 设置为 "stdio"（可选）

配置示例:

{
  "mcpServers": {
    "memory-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "cwd": "/path/to/workdir",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.json"
      },
      "transport": "stdio"
    }
  }
}

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

SSE 客户端模式

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

配置参数:

sseUrl: SSE 服务端点 URL（必需，可通过 url 参数替代）
headers: 请求头对象（可选）
type 或 transport: 设置为 "sse"（可选）

配置示例:

{
  "mcpServers": {
    "sse-client": {
      "sseUrl": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
      },
      "transport": "sse"
    }
  }
}

SSE 服务器端模式

适用场景:

需要将 MCP 服务器作为 SSE 服务器运行
为客户端提供 SSE 连接端点
支持实时双向通信

配置参数:

sseServer.enabled: 启用 SSE 服务器模式
sseServer.endpoint: SSE 端点路径（默认：/sse）
sseServer.messageEndpoint: SSE 消息端点路径（默认：/messages）

示例配置:

{
  "sseServer": {
    "enabled": true,
    "endpoint": "/sse",
    "messageEndpoint": "/messages"
  },
  "mcpServers": {}
}

使用方式:

启动服务器：

npm run start -- --sse-server-enabled

访问 SSE 端点：

GET http://localhost:3000/sse/sse-server/

发送消息到 SSE 服务器：

POST http://localhost:3000/messages/sse-server/?sessionId=<session-id>

3. WebSocket 传输协议

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

配置参数:

wsUrl: WebSocket 服务端点 URL（必需，可通过 url 参数替代）
headers: 请求头对象（可选）
type 或 transport: 设置为 "ws"（可选）

配置示例:

{
  "mcpServers": {
    "websocket-server": {
      "wsUrl": "ws://localhost:8080/ws",
      "headers": {
        "Authorization": "Bearer your-token",
        "User-Agent": "mcp-client/1.0"
      },
      "transport": "ws"
    }
  }
}

4. HTTP/Streamable-HTTP 传输协议

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

配置参数:

httpUrl: HTTP 服务端点 URL（可通过 url 参数替代）
headers: 请求头对象（可选）
type 或 transport: 设置为 "http"（可选）

配置示例:

{
  "mcpServers": {
    "http-server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
      },
      "transport": "http"
    }
  }
}

传输协议选择逻辑

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

Stdio 协议: 当配置了 command 参数或 transport/type 为 "stdio" 时
SSE 客户端协议: 当配置了 sseUrl 或 url 且 transport/type 为 "sse"
时
WebSocket 协议: 当配置了 wsUrl 或 url 且 transport/type 为 "ws"
时
HTTP 协议: 当配置了 httpUrl 或 url 且 transport/type 为 "http" 时

混合配置示例

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

{
  "sseServer": {
    "enabled": true,
    "endpoint": "/sse",
    "messageEndpoint": "/messages"
  },
  "mcpServers": {
    "local-memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "transport": "stdio"
    },
    "remote-sse": {
      "sseUrl": "http://remote-server.com/sse",
      "headers": {
        "Authorization": "Bearer remote-token"
      },
      "transport": "sse"
    },

    "websocket-service": {
      "wsUrl": "ws://websocket-server.com/ws",
      "transport": "ws"
    },
    "http-api": {
      "url": "http://api-server.com/mcp",
      "transport": "http"
    }
  }
}

支持的 MCP 功能

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

1. MCP Tools 支持

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

2. MCP Prompts 支持

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

3. MCP Resources 支持

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

6. 性能优化建议

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

连接池管理: 使用 HTTP/1.1 keep-alive 减少连接开销
批处理请求: 合并多个相关请求
缓存策略: 对静态资源启用缓存
负载均衡: 在生产环境中使用反向代理

7. 安全最佳实践

Token 认证: 始终在生产环境中启用 BRIDGE_API_TOKEN
HTTPS: 使用反向代理添加 HTTPS 支持
CORS: 配置适当的 CORS 策略
速率限制: 实施 API 速率限制
输入验证: 验证所有输入参数

8. 集成示例

与 Cursor 集成

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

{
  "mcpServers": {
    "gitee": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Author Information