内容
# MCP 桥接服务
动态将任何基于 stdio 的 MCP 服务器转换为 HTTP 端点。
## 概述
**MCP 桥接服务** 是一个管理服务，允许您使用 stdio 传输（命令 + 参数 + 环境变量）配置任何 MCP 服务器，并通过 **可流式 HTTP** 或 **SSE** 传输在任意端口上立即公开它。
```bash
# 1. 启动服务
python run.py
# 2. 注册一个 MCP 服务器（仅需包名！）
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{"stdio": "bing-cn-mcp"}'
# 3. 通过 HTTP 使用它
curl -s http://<public-ip>:<returned-port>/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
## 功能
- **自动命名解析** - 只需传递 `"bing-cn-mcp"`，它会自动运行 `npx -y <name>`
- **两种传输模式**：可流式 HTTP（默认，请求-响应）和 SSE（基于会话的流式传输）
- **动态端口**：指定端口或让操作系统分配一个随机端口（端口：0）
- **管理 API**：`POST /register`，`GET /servers`，`DELETE /servers/{id}`
- **网页仪表盘**：内置管理页面，位于 `http://localhost:8191/`，用于可视化代理管理
- **多个实例**：并行运行多个 MCP 服务器，每个服务器都在其自己的端口上
- **真实公共 IP**：端点自动显示机器的公共 IP
- **客户端友好**：支持 `/` 和 `/mcp` 路径，并带有 CORS 头
- **子进程隔离**：每个代理都在其自己的进程中运行；崩溃不会影响其他进程
- **自动清理**：当服务关闭时，所有代理进程都会被终止
## 要求
- Python 3.10+
- `pip install -r requirements.txt`（fastapi + uvicorn）
## 项目结构
```
mcp-slink/
├── pyproject.toml # 项目元数据
├── run.py # 入口点（python run.py）
├── requirements.txt # Python 依赖项
├── register.example.json # 示例配置
└── src/
└── mcp_bridge/
├── __init__.py # 包标记
├── __main__.py # python -m mcp_bridge 支持
├── config.py # StdioConfig，名称解析，IP 检测
├── server.py # MCP 子进程管理器，SSE 会话，JSON-RPC 帮助程序
├── proxy_app.py # 单个代理 FastAPI 应用
├── service_app.py # 管理 API + HTML 仪表盘
└── cli.py # CLI 入口点
```
## 用法
### 服务模式（默认）
启动管理 API：
```bash
python run.py
# 或使用自定义管理员端口
python run.py --admin-port 9000
# 或通过包
PYTHONPATH=src python -m mcp_bridge
```
然后打开 **网页仪表盘**，位于 [http://localhost:8191/](http://localhost:8191/)，以可视化方式查看和管理代理，或直接使用 API。
注册代理 - 三种方式：
```bash
# ① 仅服务器名称（自动解析为 npx -y <name>）
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{"stdio": "bing-cn-mcp"}'
# ② 完整命令配置
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{
"stdio": {
"command": "npx",
"args": ["-y", "bing-cn-mcp"]
}
}'
# ③ Claude Desktop mcpServers 格式
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{
"stdio": {
"mcpServers": {
"bing-search": {
"command": "npx",
"args": ["-y", "bing-cn-mcp"]
}
}
}
}'
```
响应：
```json
{
"id": "mcp-a1b2c3d4",
"port": 54321,
"transport": "STREAMABLEHTTP",
"status": "running",
"pid": 12345,
"endpoints": {
"http": "http://101.42.40.58:54321/mcp"
},
"created_at": "2026-06-17T07:38:31Z"
}
```
使用代理：
```bash
curl -s http://101.42.40.58:54321/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### 直接代理模式（独立）
在没有管理 API 的情况下运行单个代理：
```bash
python run.py --mode proxy --transport STREAMABLEHTTP --port 8765 config.json
# 或
PYTHONPATH=src python -m mcp_bridge --mode proxy --transport SSE --port 8765 config.json
```
配置文件的格式 - 请参阅 [register.example.json](register.example.json)。
### 服务器名称解析
当您将字符串作为 `stdio` 传递（例如 `"bing-cn-mcp"`）时，桥接：
1. 检查 `~/.config/claude/mcp_servers.json` 或 `./mcp_servers.json` 以获取映射
2. 默认为 `npx -y <name>`（假设 npm 包）
要定义自定义映射：
```json
{
"my-server": {
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": { "API_KEY": "xxx" }
},
"bing-cn-mcp": {
"command": "npx",
"args": ["-y", "bing-cn-mcp"]
}
}
```
另存为 `~/.config/claude/mcp_servers.json` 或设置 `MCP_SERVERS_CONFIG` 环境变量。
### 重写公共 IP
设置 `MCP_PUBLIC_HOST` 环境变量以重写自动检测：
```bash
MCP_PUBLIC_HOST=example.com python run.py
```
## API 参考
### `POST /register`
创建代理实例。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `stdio` | 字符串 \| 对象 | **必填** | 服务器名称（字符串）或 `{command, args?, env?}` |
| `transport` | 字符串 | `STREAMABLEHTTP` | `STREAMABLEHTTP` 或 `SSE` |
| `port` | 整数 | `0` | 端口号；`0` = 随机 |
### `GET /servers`
列出所有正在运行的代理实例。
### `GET /servers/{id}`
获取特定代理的详细信息。
### `DELETE /servers/{id}`
停止并删除代理实例。
## 传输协议
### 可流式 HTTP（默认）
单个 POST 端点位于 `/` 和 `/mcp`。每个请求都是独立的。
```
POST /mcp → JSON-RPC 请求 → （stdin → stdout） → JSON-RPC 响应
```
- 无需持久连接或会话状态
- 响应由 JSON-RPC `id` 字段匹配
### SSE（服务器发送事件）
基于会话的流式传输。
```
GET /sse → SSE 流（接收服务器消息）
POST /messages?sessionId=<id> → 向服务器发送请求
```
- 每个 SSE 连接都创建一个会话
- 服务器到客户端的消息通过 SSE 流
- 客户端到服务器的消息通过 POST 端点
## 架构
```
┌──────────────────────────────────────┐
│ MCP 桥接服务 │
│ （管理 API，：8191） │
│ │
│ POST /register ──→ 产生 ──────────┼──→ 代理进程 A (:54321)
│ GET /servers │ └── MCP 服务器（npx ...）
│ DELETE /servers/:id │
│ ┌──────────────────┤──→ 代理进程 B (:54322)
│ │ PYTHONPATH=src │ └── MCP 服务器（python ...）
│ │ python -m │
│ │ mcp_bridge │
│ │ --mode proxy │
│ └──────────────────┘
└──────────────────────────────────────┘
```
每个代理都是一个运行 `python -m mcp_bridge --mode proxy` 的子进程。
服务跟踪所有进程，并在关闭时清理它们。
## 许可证
MIT
