通用MCP服务器代理
一个灵活的、生产就绪的代理服务器,它将任何基于stdio的MCP(模型上下文协议)服务器包装在一起,提供承载令牌身份验证和SSE流支持。
概述
该脚手架为部署MCP服务器提供了一个强大的基础设施,包括:
- 承载令牌身份验证 用于安全访问
- SSE流媒体 用于实时MCP协议通信
- 健康监测 优雅的启动操作
- 结构化日志记录 用于调试和监控
- 生产就绪 错误处理和优雅关机
快速开始
1.安装依赖项
要求:
- Node.js:22.x LTS或更高版本
- npm:10.x或更高(包含在Node 22中)```bash
npm install
### 2.设置所需的环境变量
**必修的:**
- `MCP_COMMAND` -启动MCP服务器的命令
**可选(用于生产):**
- `BEARER_TOKEN` -API访问的身份验证令牌
- `DEBUG_LOGGING` -启用详细日志记录(`true` 或 `1`)
- `PORT` -外部端口(默认:8080)
### 3.配置您的MCP服务器
设置 `MCP_COMMAND` 启动MCP服务器的命令的环境变量:```bash
# GitHub MCP Server
export MCP_COMMAND="npx -y @modelcontextprotocol/server-github"
# Linear MCP Server
export MCP_COMMAND="npx -y @linear-mcp/server"
# Custom MCP Server
export MCP_COMMAND="node /path/to/your/mcp-server.js"
4.添加工具特定的环境变量
传递MCP服务器所需的任何凭据:```bash
export GITHUB_TOKEN="ghp_..."
export LINEAR_API_KEY="lin_api_..."
export OPENAI_API_KEY="sk-..."
### 5.启动代理```bash
node server.js
代理将在端口8080上启动,并通过超级网关生成您的MCP服务器。
建筑```
Client → Generic MCP Proxy (8080) → Supergateway (8000) → MCP Server (stdio)
### 组件详细信息
- **通用MCP代理**:具有承载身份验证、请求路由和SSE流的HTTP服务器
- **超级网关**:将HTTP/SSE桥接到stdio以进行MCP协议通信
- **MCP服务器**:您的特定MCP工具服务器(任何基于stdio的实现)
## 配置
|环境变量|必需|目的|示例|
|---------------------|----------|---------|---------|
| `MCP_COMMAND` | ✅ 是|启动MCP服务器的命令| `npx -y @modelcontextprotocol/server-github` |
| `BEARER_TOKEN` | ⚠️ 生产| API认证| `$(openssl rand -base64 32)` |
| `DEBUG_LOGGING` | ❌ 否|启用详细日志记录| `true` 或 `1` |
| `PORT` | ❌ 否|外部端口| `8080` |
|特定于工具的变量|变化| MCP服务器的凭据| `GITHUB_TOKEN`, `OPENAI_API_KEY` |
## API终点
### `GET /sse`
MCP协议通信的SSE端点(生产中需要承载令牌)
### `POST /sse`
MCP请求的HTTP端点(生产中需要承载令牌)
### `GET /health`
健康检查端点-返回网关状态
## 认证
### 发展模式
在以下情况下,身份验证是可选的:
- `NODE_ENV` 不是 `"production"`
- `FLY_APP_NAME` 未设置
### 生产模式
在以下情况下需要身份验证:
- `NODE_ENV` 是 `"production"`
- `FLY_APP_NAME` 已设置(Fly.io部署)
生成安全令牌:```bash
TOKEN=$(openssl rand -base64 32)
echo $TOKEN
设置令牌:```bash
export BEARER_TOKEN="$TOKEN"
## 部署示例
### Fly.io部署
1. **创建 `fly.toml`:**```toml
[build]
dockerfile = "Dockerfile"
[env]
PORT = "8080"
# VM resource allocation (Fly.io V2)
[[vm]]
size = "shared-cpu-1x"
memory = "512mb"
# HTTP service configuration (Fly.io V2)
[http_service]
internal_port = 8080
force_https = true
auto_stop_machines = "stop"
auto_start_machines = true
min_machines_running = 0
processes = ["web"]
# TCP/TLS service configuration
[[services]]
internal_port = 8080
protocol = "tcp"
processes = ['web'] # CRITICAL: Required for proper routing
[[services.ports]]
handlers = ["http"]
port = 80
[[services.ports]]
handlers = ["tls", "http"]
port = 443
[[services.tcp_checks]]
grace_period = "1s"
interval = "15s"
restart_limit = 0
timeout = "2s"
[[services.http_checks]]
grace_period = "10s"
interval = "30s"
method = "GET"
path = "/healthz"
protocol = "http"
restart_limit = 0
timeout = "5s"
tls_skip_verify = false
# Process configuration
[processes]
web = "node server.js"
看 fly.example.toml 以完成V2配置。
- 部署:```bash
flyctl deploy --remote-only
3. **设置秘密:**```bash
flyctl secrets set BEARER_TOKEN="$TOKEN"
flyctl secrets set MCP_COMMAND="npx -y @modelcontextprotocol/server-github"
flyctl secrets set GITHUB_TOKEN="ghp_..."
Docker部署
- 创建
Dockerfile:```dockerfile
FROM node:22-alpine3.23
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"
COPY . .
EXPOSE 8080
CMD ["node", "server.js"]
**主要特点:**
- ✅ 节点22 LTS基础映像
- ✅ 将npm二进制文件烘焙到PATH中以直接执行
- ✅ 现代npm命令(`--omit=dev` 而不是弃用的标志)
- ✅ 非root用户安全
- ✅ 健康检查包括
2. **构建并运行:**```bash
docker build -t mcp-proxy .
docker run -p 8080:8080 \
-e MCP_COMMAND="npx -y @modelcontextprotocol/server-github" \
-e BEARER_TOKEN="$TOKEN" \
-e GITHUB_TOKEN="ghp_..." \
mcp-proxy
MCP服务器兼容性
此代理适用于以下任何MCP服务器:
- 通过stdio进行通信
- 遵循MCP协议规范
- 可以通过命令行界面启动
经过测试的MCP服务器
@modelcontextprotocol/server-github@linear-mcp/server- 基于stdio的自定义MCP服务器
监控与调试
结构化日志记录
所有事件都以JSON格式记录,结构如下:```json
{
"timestamp": "2025-01-01T00:00:00.000Z",
"level": "info",
"category": "mcp-call",
"phase": "runtime",
"message": "MCP method: tools/call",
"data": { "requestId": "abc123", "method": "tools/call" }
}
### 调试模式
启用详细日志记录:```bash
export DEBUG_LOGGING=true
node server.js
健康监测
监控网关运行状况:```bash
curl http://localhost:8080/health
答复:```json
{
"status": "healthy",
"gatewayReady": true,
"gatewayExited": false,
"uptimeMs": 12345
}
故障排除
常见问题
“MCP_COMMAND环境变量是必需的”
- 设置
MCP_COMMANDMCP服务器启动命令的环境变量
“生产中需要BEARER_TOKEN”
- 为生产部署生成并设置安全的承载令牌
“网关启动超时”
- 检查您的MCP命令是否有效,服务器是否可以启动
- 验证您的MCP服务器是否设置了所有必需的环境变量
“服务不可用:MCP网关已退出”
- 检查日志中的启动错误
- 确保您的MCP服务器兼容且配置正确
调试步骤
- 手动验证MCP命令:```bash
eval $MCP_COMMAND --help
2. **检查环境变量:**```bash
env | grep -E "(MCP_COMMAND|BEARER_TOKEN)"
- 启用调试日志记录:```bash
export DEBUG_LOGGING=true
node server.js
4. **测试健康终点:**```bash
curl -v http://localhost:8080/health
安全注意事项
- 在生产中始终使用不记名代币 -该端点可以通过其他方式公开访问
- 定期旋转令牌 -在部署管道中实现令牌轮换
- 限制令牌范围 -使用具有最低所需权限的令牌
- 监控访问日志 -警惕未经授权的访问企图
- 在生产环境中使用HTTPS -在负载均衡器或反向代理端终止TLS
演出
- 冷启动处理 -代理在接受请求之前等待MCP服务器启动
- SSE流媒体 -长期连接得到妥善管理,没有超时
- 请求缓冲 -HTTP请求被缓冲;SSE响应被流式传输
- 资源限制 -网关进程有50MB的缓冲区限制,以防止内存问题
经验教训:npm二进制路径管理
问题
npm包将二进制文件安装到 node_modules/.bin/,默认情况下不在系统PATH中。这导致了以下问题 supergateway 无法直接访问,需要 npx 变通办法。
解决方案
在Docker构建时将npm二进制文件烘焙到PATH中:dockerfile
RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"
好处
- ✅ 更快的启动 -无npx处置开销
- ✅ 可预测的行为 -直接二进制执行
- ✅ 离线兼容性 -没有网络呼叫来检查更新
- ✅ 清理原木 -没有npx消息
- ✅ 生产就绪 -符合最佳实践
为何这很重要
在分叉此脚手架时,请确保您的Dockerfile包含PATH配置。没有它,你需要使用 npx 前缀或在运行时手动将二进制文件添加到PATH中,这会增加复杂性并降低性能。
许可证
MIT许可证-您可以自由地将此脚手架用于MCP服务器部署。
