使用说明

远程MCP网桥

A. 传输适配器（桥接器） 使客户端能够使用 本地MCP服务器/工具 （使用JSON-RPC 工作室)作为a 远程MCP服务器 通过网络 HTTP+SSE（或流式HTTP），通常由 Azure API管理（APIM） 对于企业 身份验证、治理、速率限制和可观察性.

概述

此网桥在两种传输协议之间进行转换：

远程MCP客户端 （HTTPS+SSE/流式HTTP）
→ APIM （OAuth/JWT+策略）
→ 桥（HTTP⇄ STDIO传输转换）
→ 本地MCP服务器 （标准JSON-RPC）

特性

✅ 双重运输支持：SSE（服务器发送事件）和流式HTTP
✅ 流程管理：自动生成、监督和重启本地MCP服务器
✅ 配置解析：支持具有可变分辨率的MCP配置JSON
✅ 背压处理：可配置的缓冲区限制和慢速客户端检测
✅ 健康检查：容器编排的就绪/活性端点
✅ 优雅地关闭：正确清理连接和流程
✅ Azure就绪：容器应用程序和APIM集成的二头肌模板

建筑

MCP Client (VS Code / Copilot / Foundry Agent)
            |
        HTTPS (SSE or Streamable HTTP)
            |
Azure API Management (APIM)
  - OAuth/JWT validation
  - quotas / rate limits
  - IP filtering
  - logging / analytics
            |
        HTTPS (SSE or Streamable HTTP)
            |
Bridge / Transport Adapter
  - HTTP POST ingress
  - SSE/stream egress
  - local process mgmt
            |
        STDIO (JSON-RPC)
            |
Local MCP Server (STDIO)

快速开始

先决条件

Node.js 18+和npm
Docker（用于容器化）
Azure CLI（用于部署）

地方发展

安装依赖项:
```
npm install
```
构建项目:
```
npm run build
```
配置MCP服务器: 编辑 specs/ado-mcp-configuration.json 或提供您自己的MCP配置文件。

设置环境变量 （可选）：

export PORT=3000
export MCP_CONFIG_PATH=specs/ado-mcp-configuration.json
export INPUT_ADO_ORG=your-org-name

跑桥:

npm start
# Or for development with auto-reload:
npm run dev

验证端点:

.\test_scripts\validate-bridge.ps1 -BaseUrl http://localhost:3000

配置

网桥从JSON文件读取MCP服务器配置（默认值： specs/ado-mcp-configuration.json).例子：

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name (e.g. 'contoso')"
    }
  ],
  "tools": [
    {
      "id": "ado",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}"]
    }
  ]
}

可变分辨率: ${input:variable_name} 可以通过以下方式解决：

环境变量： INPUT_VARIABLE_NAME 或 VARIABLE_NAME
配置文件中的默认值
显式重写（通过API或配置）

环境变量

变量	默认值	描述
`PORT`	`3000`	HTTP服务器端口
`MCP_CONFIG_PATH`	`specs/ado-mcp-configuration.json`	MCP配置文件的路径
`MAX_BUFFER_SIZE`	`1048576`	每个订阅者的最大缓冲区大小（字节）
`MAX_SUBSCRIBERS`	`100`	并发流订阅者的最大数量
`MAX_MESSAGE_SIZE`	`1048576`	最大JSON-RPC消息大小（字节）
`KEEPALIVE_INTERVAL`	`30000`	SSE保持活动间隔（ms）
`STREAM_TIMEOUT`	`300000`	流空闲超时（ms）
`RESTART_BACKOFF_BASE`	`1000`	进程重启退避基数（ms）
`RESTART_BACKOFF_MAX`	`60000`	进程重启回退最大值（ms）
`LAZY_START`	`true`	在第一次连接时启动MCP服务器进程

API终点

`GET /healthz`

容器就绪/活性探针的健康检查端点。

响应:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "process": {
    "running": true,
    "pid": 12345,
    "restartCount": 0
  },
  "subscribers": {
    "sse": 2,
    "streamableHttp": 1
  }
}

`GET /mcp/stream`

服务器发送事件（SSE）流端点，用于从本地MCP服务器接收JSON-RPC消息。

标头:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

事件：每条JSON-RPC消息都作为SSE发送 data: 活动。

`GET /mcp/streamable`

APIM首选传输的流式HTTP端点（SSE的替代方案）。

标头:

Content-Type: application/json
Transfer-Encoding: chunked

格式：以换行符分隔的JSON（NDJSON）。

`POST /mcp`

向本地MCP服务器发送JSON-RPC请求。

请求:

Content-Type: application/json
正文：JSON-RPC请求对象或批处理数组

响应: 202 Accepted （异步模式）

{
  "status": "accepted",
  "messageCount": 1
}

示例:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Docker部署

构建图像

docker build -t remote-mcp-bridge:latest .

运行容器

docker run -d \
  -p 3000:3000 \
  -e MCP_CONFIG_PATH=/app/specs/ado-mcp-configuration.json \
  -e INPUT_ADO_ORG=your-org-name \
  remote-mcp-bridge:latest

Azure部署

先决条件

Azure订阅
Azure CLI已安装并登录
Docker（用于构建容器镜像）
Azure容器注册表（ACR）或容器映像注册表

部署到Azure容器应用程序

选项1:PowerShell脚本

.\scripts\deploy.ps1 `
  -ResourceGroupName "rg-mcp-bridge" `
  -Location "eastus" `
  -AppName "remote-mcp-bridge" `
  -RegistryName "your-acr-name" `
  -ContainerImage "your-acr-name.azurecr.io/remote-mcp-bridge:latest"

选项2:Bash脚本

./scripts/deploy.sh \
  -g rg-mcp-bridge \
  -l eastus \
  -n remote-mcp-bridge \
  -r your-acr-name \
  -i your-acr-name.azurecr.io/remote-mcp-bridge:latest

选项3：手动二头肌展开

az deployment group create \
  --resource-group rg-mcp-bridge \
  --template-file infra/main.bicep \
  --parameters @infra/parameters.json \
  --parameters containerImage=your-acr-name.azurecr.io/remote-mcp-bridge:latest

配置API管理

部署网桥后，配置APIM将其作为远程MCP服务器公开：

引导到 Azure门户 → API管理 → 您的APIM实例
首选 应用程序编程接口 → MCP服务器
点击 “+创建MCP服务器” → “暴露现有的MCP服务器”
提供：
- 名字: remote-mcp-bridge
- 基本URL: https://your-container-app-url.azurecontainerapps.io
- 运输: StreamableHttp （或 SSE)
- 描述: Remote MCP Bridge exposing local STDIO MCP servers
配置策略：
- 入站：JWT验证、速率限制、IP过滤
- 出站：传递（避免转换JSON-RPC有效载荷）

看 infra/apim.bicep 用于配置结构（注意：APIM MCP服务器配置通常通过Portal或REST API完成）。

测试

单元测试

npm test

集成测试

npm test -- --testPathPattern=integration

验证脚本

.\test_scripts\validate-bridge.ps1 -BaseUrl http://localhost:3000

发展

项目结构

.
├── src/                    # TypeScript source code
│   ├── __tests__/         # Test files
│   ├── utils/             # Utility functions
│   ├── config.ts           # Configuration parser
│   ├── process-manager.ts  # STDIO process management
│   ├── sse-handler.ts      # SSE endpoint handler
│   ├── streamable-http-handler.ts  # Streamable HTTP handler
│   ├── message-router.ts   # Message fan-out router
│   ├── health.ts           # Health check handler
│   ├── server.ts           # Express HTTP server
│   └── index.ts            # Application entry point
├── infra/                  # Azure infrastructure templates
│   ├── main.bicep          # Container Apps deployment
│   ├── apim.bicep          # APIM configuration
│   └── parameters.json     # Deployment parameters
├── scripts/                # Deployment scripts
│   ├── deploy.ps1          # PowerShell deployment
│   └── deploy.sh           # Bash deployment
├── test_scripts/           # Validation scripts
├── specs/                  # Specifications and examples
├── Dockerfile              # Container image definition
└── package.json            # Node.js dependencies

建筑

npm run build

掉毛

npm run lint

故障排除

进程未启动

检查MCP配置文件路径： MCP_CONFIG_PATH
验证是否设置了所有必需的环境变量（尤其是 ${input:...} 变量）
检查日志中的进程生成错误

SSE流未连接

验证网桥是否可访问（检查防火墙/网络规则）
确保代理/网关支持长期连接
检查 KEEPALIVE_INTERVAL 设置（可能需要调整代理超时）

内存使用率高

减少 MAX_BUFFER_SIZE 和 MAX_SUBSCRIBERS
检查慢速客户端（它们可能正在缓冲消息）
监控进程重启计数（高计数表示不稳定）

APIM集成问题

确保APIM策略不会转换JSON-RPC有效负载
验证传输类型是否与网桥端点匹配（SSE与Streamable HTTP）
检查APIM日志以获取请求/响应详细信息

贡献

分叉存储库
创建要素分支
进行更改
添加测试
提交拉取请求

许可证

麻省理工学院

使用说明

远程MCP网桥

概述

特性

建筑

快速开始

先决条件

地方发展

配置

环境变量

API终点

GET /healthz

GET /mcp/stream

GET /mcp/streamable

POST /mcp

Docker部署

构建图像

运行容器

Azure部署

先决条件

部署到Azure容器应用程序

选项1:PowerShell脚本

选项2:Bash脚本

选项3：手动二头肌展开

配置API管理

测试

单元测试

集成测试

验证脚本

发展

项目结构

建筑

掉毛

故障排除

进程未启动

SSE流未连接

内存使用率高

APIM集成问题

贡献

许可证

参考文献

相关 MCP

JSON-RPC服务

CLI工具MCP服务器

以太坊RPC MPC服务器

WinDbg调试服务器

PHP MCP服务器SDK

CSV文件管理服务器

`GET /healthz`

`GET /mcp/stream`

`GET /mcp/streamable`

`POST /mcp`