使用说明

MCP统一网关

一个统一的网关服务器，将MCP（模型上下文协议）请求路由到多个后端MCP服务器。内置于荣誉并可部署到 Cloudflare员工.

特性

多服务器路由：自动将工具调用路由到相应的MCP服务器
多种运输方式：支持stdio、HTTP和SSE（服务器发送事件）后端
代码模式验证：内置代码模式的验证和执行
时间戳跟踪：所有请求和响应的自动时间戳
边缘就绪：在Cloudflare Workers或支持Hono的任何边缘运行时上运行

建筑

网关充当反向代理：

接收来自客户的MCP请求（如Claude Code）
根据工具名称模式确定哪个后端服务器应处理请求
将请求路由到相应的后端服务器（stdio进程、HTTP端点或SSE流）
将响应返回给客户端

┌─────────────┐          ┌──────────────────┐          ┌─────────────────┐
│ MCP Client  │  HTTP    │  Unified Gateway │  stdio   │  Serena MCP     │
│ (Claude)    │─────────▶│  (Hono Server)   │─────────▶│  Server         │
└─────────────┘          │                  │          └─────────────────┘
                         │                  │  HTTP    ┌─────────────────┐
                         │                  │─────────▶│  Figma MCP      │
                         │                  │          │  Server         │
                         │                  │          └─────────────────┘
                         │                  │  HTTP    ┌─────────────────┐
                         │                  │─────────▶│  Context7 MCP   │
                         └──────────────────┘          │  Server         │
                                                        └─────────────────┘

快速开始

1.安装依赖项

npm install

2.启动网关

npm start
# Server runs on http://localhost:3000

3.测试网关

# Check status
curl http://localhost:3000/gateway/status

# Health check
curl http://localhost:3000/health

网关端点

主要终点

端点	方法	描述
`/`	获取	欢迎信息和API文档
`/mcp`	POST	带自动路由的主MCP端点
`/gateway/:server`	POST	路由到特定服务器
`/gateway/status`	GET	查看所有已配置的服务器
`/health`	GET	健康检查

`/mcp` 端点（推荐）

这 /mcp 端点根据工具名称模式自动将请求路由到适当的后端服务器。

MCP请求示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mcp__serena__find_symbol",
    "arguments": {
      "name_path_pattern": "MyClass"
    }
  }
}

网关将自动检测到 mcp__serena__* 工具应该被路由到Serena服务器。

与MCP客户端集成

Claude代码集成

将网关添加到您的Claude代码配置中：

macOS/Linux：

# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# Or: ~/.config/Claude/claude_desktop_config.json (Linux)

窗户：

# Edit: %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "unified-gateway": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http"
    }
  }
}

保存后，重新启动Claude Code。网关将自动将工具调用路由到相应的后端服务器。

其他MCP客户端

任何支持Streamable HTTP传输的MCP客户端都可以连接到网关：

// Example using MCP SDK
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport({
  url: 'http://localhost:3000/mcp'
});

添加新的MCP服务器

要添加新的后端MCP服务器，请编辑 servers 对象在 src/index.ts:

示例1:HTTP服务器

const servers: Record<string, ServerConfig> = {
  // ... existing servers ...

  'my-custom-server': {
    type: 'http',
    url: 'https://my-server.example.com/mcp',
    tools: ['custom_*'], // Match all tools starting with "custom_"
    apiKey: 'optional-api-key' // Optional authentication
  }
};

示例2：Stdio服务器

const servers: Record<string, ServerConfig> = {
  // ... existing servers ...

  'python-tools': {
    type: 'stdio',
    command: 'python',
    args: ['-m', 'my_mcp_server'],
    tools: ['python_analyze', 'python_format']
  }
};

示例3:SSE服务器

const servers: Record<string, ServerConfig> = {
  // ... existing servers ...

  'streaming-server': {
    type: 'sse',
    url: 'https://streaming.example.com/mcp',
    tools: ['stream_*']
  }
};

工具匹配模式

这 tools array支持两种模式：

精确匹配: 'ping' 仅匹配名为“ping”的工具
统配符匹配: 'mcp__serena__*' 匹配以“mcp_sena_”开头的所有工具

预配置服务器

网关附带了几个预配置的服务器：

服务器	类型	工具	描述
`serena`	站立	`mcp__serena__*`	代码分析和重构工具
`figma-remote`	http	`figma_*`	Figma设计工具
`cloudflare-docs`	http	`mcp__cloudflare-docs__*`	Cloudflare文档
`context7`	http	`mcp__context7__*`	图书馆文献查询
`my-mcp`	http	`ping`, `start-notification-stream`	本地服务器示例

查看所有已配置的服务器：

curl http://localhost:3000/gateway/status

代码模式验证

网关包括对常见模式的内置验证：

参数必须是对象：确保工具参数结构正确
相对路径强制：Serena工具需要相对路径，而不是绝对路径
所需参数：验证特定工具所需的参数
时间戳元数据：自动添加验证时间戳

发展

本地开发

npm run dev
# Server runs on http://localhost:3000 with hot reload

使用MCP示例客户端进行测试

在一个终端中：

npm start

在另一个终端中：

node node_modules/@modelcontextprotocol/sdk/dist/esm/examples/client/simpleStreamableHttp.js

示例客户端中的命令：

> connect http://localhost:3000/mcp
> list-tools
> call-tool ping

部署

部署到Cloudflare Workers

npm run deploy

部署后，更新您的MCP客户端配置以使用Cloudflare Workers URL：

{
  "mcpServers": {
    "unified-gateway": {
      "url": "https://your-worker.workers.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

Cloudflare Workers的配置

这 wrangler.jsonc 文件包括：

入口点: src/index.ts
兼容性: nodejs_compat Node.js流API的标志
捆绑优化：别名未使用的依赖项以减小捆绑包大小

监控与调试

所有请求都会记录时间戳：

[2025-01-15T10:30:45.123Z] [Gateway] Request received
[2025-01-15T10:30:45.125Z] Matched tool 'mcp__serena__find_symbol' to server 'serena'
[2025-01-15T10:30:45.126Z] [stdio] Spawning uvx --from git+https://github.com/oraios/serena...
[2025-01-15T10:30:45.789Z] [stdio] Process completed with code 0
[2025-01-15T10:30:45.790Z] [Gateway] Request completed

检查日志：

本地：终端中的控制台输出
Cloudflare员工：在Cloudflare仪表板的Workers&Pages下查看→ 您的员工→ Logs

故障排除

找不到服务器

错误: No server found for tool 'my_tool'

解决方案：将工具模式添加到服务器的 tools 数组in src/index.ts:

'my-server': {
  type: 'http',
  url: 'http://localhost:3000/mcp',
  tools: ['my_tool', 'other_tool']
}

验证失败

错误: Code pattern validation failed: Serena tools require relative paths

解决方案：使用相对路径而不是绝对路径：

// ❌ Wrong
{ relative_path: '/Users/name/project/file.ts' }

// ✅ Correct
{ relative_path: 'src/file.ts' }

Stdio服务器超时

错误: Request timeout

解决方案:

检查stdio命令是否正确且可执行
确保服务器在30秒内响应
检查stderr日志中的错误

API 参考

服务器配置界面

interface ServerConfig {
  type: 'stdio' | 'http' | 'sse';
  command?: string;      // For stdio: command to execute
  args?: string[];       // For stdio: command arguments
  url?: string;          // For http/sse: endpoint URL
  apiKey?: string;       // Optional: API key for authentication
  tools?: string[];      // Tool name patterns to match
}

许可证

麻省理工学院

贡献

欢迎投稿！请确保您的更改：

遵循现有代码样式
包括适当的错误处理
添加调试日志
更新文档