MCP Gateway

🚀 MCP Gateway

MCP Gateway 是一款服務器聚合工具，它能將多個模型上下文協議（MCP）服務器整合為一個單一的網關。通過統一的搜索、描述和調用接口，該網關可將所有連接服務器的工具暴露出來，不過目前僅暴露 5 個工具。

🚀 快速開始

MCP Gateway 作為服務器聚合工具，解決了在連接多個 MCP 服務器時出現的上下文限制問題。它通過提供工具搜索功能，避免了一次性列出所有工具模式的問題，同時減少了初始使用的令牌數。以下是使用該工具的基本步驟：

1. 安裝：根據不同的使用場景（如Claude Code、OpenCode等），按照相應的配置添加 MCP Gateway。
2. 配置：通過 JSON 文件配置 MCP Gateway，指定連接的上游服務器信息。
3. 使用工具：使用 gateway.search、gateway.describe、gateway.invoke 等工具進行搜索、描述和調用操作。

✨ 主要特性

解決上下文限制問題

當將客戶端（如 Claude Code、Opencode 等）連接到多個 MCP 服務器時，每個服務器都會列出其所有工具。若有 10 個以上的 MCP 服務器，且每個服務器暴露 10 - 50 個工具，系統提示中的工具描述很容易超過 500 條。這會導致兩個問題：

1. 上下文溢出：許多大語言模型（LLM）在對話開始前就會達到其上下文限制。
2. 認知過載：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 文件中讀取配置。默認情況下，它會按以下順序查找配置文件：

1. 作為第一個命令行參數提供的路徑。
2. MCP_GATEWAY_CONFIG 環境變量。
3. ~/.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

端點：

示例：

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。