# mcp-demo-streamable-http-bridge

## docker

```bash
docker pull docker.cnb.cool/masx200/docker_mirror/mcp-streamable-http-bridge:latest
```

#### 介绍

mcp-demo-streamable-http-bridge

# mcp-demo-streamable-http-bridge

## 介绍

这是一个演示项目，用于展示如何将 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 版本使用说明

#### 编译和运行

```bash
# 编译TypeScript文件
npx tsc main.ts

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

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

#### 命令行参数

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

```bash
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            显示帮助信息
```

#### 使用示例

```bash
# 基本启动
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`。配置文件示例：

```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 服务器：

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

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

#### 多服务器支持

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

```json
{
  "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 版本使用说明（原始版本）

#### 启动桥接服务器

#### 环境变量配置

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

- **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`：

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

#### 2. 带认证的 streamable-http 配置

创建 `mcp-streamable-auth.json`：

```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 配置

创建 `settings.json`：

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

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

创建 `client-streamable-config.json`：

```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"`（可选）

**配置示例**:

```json
{
  "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"`（可选）

**配置示例**:

```json
{
  "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`）

**示例配置**:

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

**使用方式**:

1. 启动服务器：

```bash
npm run start -- --sse-server-enabled
```

2. 访问 SSE 端点：

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

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

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

### 3. WebSocket 传输协议

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

**配置参数**:

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

**配置示例**:

```json
{
  "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"`（可选）

**配置示例**:

```json
{
  "mcpServers": {
    "http-server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
      },
      "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"` 时

### 混合配置示例

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

```json
{
  "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. 性能优化建议

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

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 服务器：

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