金大哥 - mcp-gateway MCP 详情

article

README

🚀 MCP Gateway

MCP Gateway 是一款服务器聚合工具，它能将多个模型上下文协议（MCP）服务器整合为一个单一的网关。通过统一的搜索、描述和调用接口，该网关可将所有连接服务器的工具暴露出来，不过目前仅暴露 5 个工具。

🚀 快速开始

MCP Gateway 作为服务器聚合工具，解决了在连接多个 MCP 服务器时出现的上下文限制问题。它通过提供工具搜索功能，避免了一次性列出所有工具模式的问题，同时减少了初始使用的令牌数。以下是使用该工具的基本步骤：

安装：根据不同的使用场景（如Claude Code、OpenCode等），按照相应的配置添加 MCP Gateway。
配置：通过 JSON 文件配置 MCP Gateway，指定连接的上游服务器信息。
使用工具：使用 gateway.search、gateway.describe、gateway.invoke 等工具进行搜索、描述和调用操作。

✨ 主要特性

解决上下文限制问题

当将客户端（如 Claude Code、Opencode 等）连接到多个 MCP 服务器时，每个服务器都会列出其所有工具。若有 10 个以上的 MCP 服务器，且每个服务器暴露 10 - 50 个工具，系统提示中的工具描述很容易超过 500 条。这会导致两个问题：

上下文溢出：许多大语言模型（LLM）在对话开始前就会达到其上下文限制。
认知过载：LLM 难以从数百个选项中选择合适的工具。

提供工具搜索功能

MCP Gateway 通过提供 工具搜索 功能解决了上述问题，而不是一次性列出所有工具模式。

减少初始令牌使用

使用 MCP Gateway 可使初始使用的令牌数减少约 40%。

📦 安装指南

Claude Code

在你的 Claude MCP 配置中添加以下内容：

{
  "mcpServers": {
    "gateway": {
      "command": "bunx",
      "args": ["@eznix/mcp-gateway@latest"]
    }
  }
}

OpenCode

在你的 OpenCode MCP 配置中添加以下内容：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-gateway": {
      "type": "local",
      "command": ["bunx", "@eznix/mcp-gateway@latest"]
    }
  }
}

你可以将 ~/.config/opencode/AGENTS.md 文件与此模板合并。现在，你可以简单地枚举可用的 MCP。

💻 使用示例

基础用法

`gateway.search`

搜索所有连接服务器中的工具。

{
  query: "kubernetes pods",
  limit: 10,  // 可选，最大值为 50
  filters: {
    server: "kubernetes"  // 可选，按服务器名称过滤
  }
}

返回匹配的工具及其相关性得分。名称匹配的工具会获得更高的分数。

`gateway.describe`

获取特定工具的详细信息。

{
  id: "kubernetes::pods_list"  // 格式：serverKey::toolName
}

返回完整的工具模式，包括输入模式。

`gateway.invoke`

同步执行工具并立即获取结果。

{
  id: "kubernetes::pods_list",
  args: { namespace: "default" },
  timeoutMs: 30000  // 可选，默认 30 秒
}

`gateway.invoke_async`

启动异步工具执行。返回一个作业 ID 用于轮询。

{
  id: "some-server::long-running-tool",
  args: { ... },
  priority: 10,  // 可选，值越高优先级越高
  timeoutMs: 60000
}

`gateway.invoke_status`

检查异步作业的状态。

{
  jobId: "job_123456789_abc123"
}

📚 详细文档

配置

MCP Gateway 从 JSON 文件中读取配置。默认情况下，它会按以下顺序查找配置文件：

作为第一个命令行参数提供的路径。
MCP_GATEWAY_CONFIG 环境变量。
~/.config/mcp-gateway/config.json。

配置格式

{
  "local-server": {
    "type": "local",
    "command": ["bun", "run", "/path/to/server.ts"]
  },
  "remote-server": {
    "type": "remote",
    "url": "https://mcp.example.com",
    "enabled": true
  },
  "websocket-server": {
    "type": "remote",
    "url": "wss://mcp.example.com/ws",
    "enabled": true
  }
}

每个条目指定以下信息：

type："local" 或 "remote"。
command（仅适用于本地）：用于启动上游服务器的命令和参数数组。
url（仅适用于远程）：远程 MCP 服务器的完整 URL。
transport（可选，仅适用于远程）：覆盖传输检测（"streamable_http" 或 "websocket"）。通常根据 URL 协议自动检测。
environment（仅适用于本地）：传递给启动进程的环境变量，支持 {env:VAR_NAME} 替换。
enabled：设置为 false 可跳过连接到该服务器。

支持替换的环境变量

本地 MCP 服务器支持使用 {env:VAR_NAME} 语法进行环境变量替换：

{
  "jupyter-lab": {
    "type": "local",
    "command": ["uvx", "jupyter-mcp-server@latest"],
    "environment": {
      "JUPYTER_URL": "http://localhost:{env:JUPYTER_PORT}/",
      "JUPYTER_TOKEN": "{env:JUPYTER_TOKEN}",
      "DEBUG": "true"
    }
  }
}

{env:VAR_NAME} 占位符会从当前进程环境中解析。如果环境变量未设置，则会替换为空字符串。

Docker

使用 HTTP 传输在 Docker 中运行 MCP Gateway：

# 构建镜像
docker build -t mcp-gateway .

# 挂载配置文件并运行
docker run -p 3000:3000 \
  -v ./examples/config.json:/home/gateway/.config/mcp-gateway/config.json:ro \
  mcp-gateway

端点： | 端点 | 描述 | |------|------| | GET / | 网关信息和端点 | | GET /health | 健康检查 | | /mcp | MCP 协议端点 |

示例：

curl http://localhost:3000/
# {"name":"MCP Gateway",...,"endpoints":{"mcp":"/mcp","health":"/health"}}

curl http://localhost:3000/health
# {"status":"ok"}

远程服务器配置

远程服务器会根据 URL 协议自动检测：

http:// 或 https:// → 可流式传输的 HTTP（推荐）
ws:// 或 wss:// → WebSocket

{
  "gh-grep": {
    "type": "remote",
    "url": "https://mcp.grep.app"
  },
  "custom-websocket": {
    "type": "remote",
    "url": "wss://my-server.com/mcp"
  }
}

工具 ID 格式

所有网关工具使用 serverKey::toolName 格式来标识工具：

kubernetes::pods_list
playwright::browser_navigate
github::create_issue

serverKey 是配置文件中的键名。

🔧 技术细节

组件

MCPGateway 类：主要协调器。
上游连接管理器：管理与 MCP 服务器的连接（本地使用 stdio，远程使用 HTTP/WebSocket）。
工具目录：内存中存储所有可用工具及其元数据的索引。
作业队列：处理异步工具调用，支持优先级排序和并发限制（默认最大并发数为 3）。
搜索引擎：使用 MiniSearch 并结合 BM25 评分和模糊匹配。

搜索算法

搜索使用 MiniSearch 并结合 BM25 排名：

BM25 评分：相关性算法。
字段加权：名称匹配（3 倍）、标题匹配（2 倍）、描述/服务器匹配（1 倍）。
模糊匹配：以 0.2 为阈值处理拼写错误（例如，"kubenetes" → 找到 "kubernetes"）。
前缀搜索：支持部分单词匹配（例如，"pod" 匹配 "pods_list"）。

贡献代码

git clone https://github.com/eznix86/mcp-gateway.git
cd mcp-gateway
bun install

# 本地运行（stdio 传输）
bun run index.ts

# 使用 Docker 运行（端口 3000 上的 HTTP 传输）
bun run docker:build && bun run docker:run

📄 许可证

本项目采用 MIT 许可证。详情请见 LICENSE。

mcp-gateway