Remote MCP Adapter

远程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（用于部署）

地方发展

1. 安装依赖项:

   npm install

1. 构建项目:

   npm run build

1. 配置MCP服务器:

编辑 specs/ado-mcp-configuration.json 或提供您自己的MCP配置文件。

1. 设置环境变量 （可选）：

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

1. 跑桥:

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

1. 验证端点:

   .\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或配置）

环境变量

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

1. 引导到 Azure门户 → API管理 → 您的APIM实例
2. 首选 应用程序编程接口 → MCP服务器
3. 点击 “+创建MCP服务器” → “暴露现有的MCP服务器”
4. 提供：

- 名字: remote-mcp-bridge - 基本URL: https://your-container-app-url.azurecontainerapps.io - 运输: StreamableHttp （或 SSE) - 描述: Remote MCP Bridge exposing local STDIO MCP servers

1. 配置策略：

- 入站：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日志以获取请求/响应详细信息

贡献

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

许可证

麻省理工学院

参考文献

• 远程MCP网桥规范
• 在Azure API管理中公开现有MCP服务器
• JSON-RPC 2.0规范
• 服务器发送事件（SSE）