MCP Funnel

🚀 MCP Funnel

MCP Funnel 是一款模型上下文協議（MCP）代理服務器，它能夠將多個 MCP 服務器聚合為單一接口，讓你可以通過 Claude Desktop 或 Claude Code CLI 同時使用來自多個源的工具。

🚀 快速開始

你可以按照以下步驟快速使用 MCP Funnel：

1. 確保滿足以下先決條件：
   • 安裝 Node.js 18+ 和 npm/yarn。
   • 安裝 tsx 以便直接運行 TypeScript。
   • 單獨安裝你想要代理的 MCP 服務器。
2. 進行配置，MCP Funnel 支持以下兩種配置方式：
   • 隱式配置（默認）：在當前工作目錄中查找 .mcp-funnel.json 文件。

     npx mcp-funnel  # 使用 ./.mcp-funnel.json
     

   • 顯式配置：指定自定義配置文件的路徑。

     npx mcp-funnel /path/to/config.json
     

   • 用戶基礎配置（自動合併）：如果存在 ~/.mcp-funnel/.mcp-funnel.json 文件，它將與項目配置合併，項目配置的值會覆蓋用戶基礎配置的值，數組會被替換（不會進行拼接）。
3. 開始使用，例如通過以下配置與 Claude Code CLI 集成：

   {
     "mcpServers": {
       "mcp-funnel": {
         "command": "npx",
         "args": ["-y", "mcp-funnel"]
       }
     }
   }
   

✨ 主要特性

• 多服務器聚合：可連接任意數量的 MCP 服務器。
• 工具命名空間：自動添加前綴，避免命名衝突（如 github__create_issue、memory__store_memory）。
• 靈活過濾：使用通配符模式顯示或隱藏工具。
• 精細控制：過濾服務器不允許禁用的單個工具。
• 上下文優化：通過選擇性過濾，將 MCP 工具的上下文使用量減少 40 - 60%。
• 自定義傳輸：支持基於標準輸入輸出（stdio）的 MCP 服務器（如 Docker、NPX、本地二進制文件）。
• 服務器日誌前綴：清晰標識哪個服務器在記錄什麼內容。
• 動態工具發現：一項實驗性特性，可通過按需加載工具來減少初始上下文使用量（目前存在一些限制）。
• 核心工具模式：超輕量級上下文模式，僅暴露選定的 MCP Funnel 內部工具，實現動態橋接，可將上下文使用量減少 95% 以上。

📦 安裝指南

先決條件

• Node.js 18+ 和 npm/yarn。
• tsx 用於直接運行 TypeScript。
• 單獨安裝你想要代理的 MCP 服務器。

安裝步驟

目前文檔未提供具體安裝命令，可根據上述先決條件進行準備。

💻 使用示例

基礎用法

以下是一個簡單的配置示例，展示如何將 MCP Funnel 與 Claude Code CLI 集成：

{
  "mcpServers": {
    "mcp-funnel": {
      "command": "npx",
      "args": ["-y", "mcp-funnel"]
    }
  }
}

高級用法

如果你想使用自定義配置文件路徑，可以這樣做：

{
  "mcpServers": {
    "mcp-funnel": {
      "command": "npx",
      "args": ["-y", "mcp-funnel", "/path/to/your/.mcp-funnel.json"]
    }
  }
}

📚 詳細文檔

配置選項

• servers：要連接的 MCP 服務器記錄（服務器名稱作為鍵）
  • 鍵：服務器名稱（用作工具前綴）
  • command：要執行的命令
  • args：命令參數（可選）
  • env：環境變量（可選）
• alwaysVisibleTools：始終暴露的工具模式，繞過發現模式（可選）
• exposeTools：要暴露的外部工具的包含模式（可選）
• hideTools：要隱藏的外部工具的排除模式（可選）
• exposeCoreTools：要暴露的內部 MCP Funnel 工具的包含模式（可選，默認為全部啟用）

alwaysVisibleTools 與 exposeTools 的區別

• 當你希望某個工具在啟動時可見時，單獨使用 exposeTools 即可，對於由服務器支持的工具，無需在 alwaysVisibleTools 中重複列出。
• 當你希望某個服務器工具繞過所有限制（暴露/隱藏、未來模式更改）時，使用 alwaysVisibleTools，它的優先級高於 hideTools，也無需在 exposeTools 中重複列出。
• 命令是特殊的：列出命令需要在 exposeTools 中使用 commands__… ；alwaysVisibleTools 不適用於開發命令列表。

過濾模式

過濾模式用於匹配帶前綴的工具名稱（serverName__toolName），並支持通配符（*）：

• 單個工具：
  • github__get_team_members - 隱藏 GitHub 服務器的特定工具
  • memory__check_database_health - 隱藏 Memory 服務器的特定工具
• 通配符模式：
  • memory__dashboard_* - 隱藏 Memory 服務器的所有儀表盤工具
  • github__debug_* - 隱藏 GitHub 服務器的所有調試工具
  • *__workflow_* - 隱藏任何服務器的所有與工作流相關的工具
  • memory__ingest_* - 隱藏 Memory 服務器的所有攝入工具
  • *__list_* - 隱藏任何服務器的所有列表工具

核心工具過濾

MCP Funnel 包含用於發現和橋接的內部工具，你可以使用 exposeCoreTools 控制暴露哪些核心工具：

"exposeCoreTools": ["discover_*", "load_toolset"]  // 僅暴露發現工具和工具集加載工具

可用的核心工具包括：

• discover_tools_by_words - 通過關鍵字搜索工具
• get_tool_schema - 獲取工具的輸入模式
• bridge_tool_request - 動態執行工具
• load_toolset - 加載預定義的工具模式

如果未指定 exposeCoreTools，默認啟用所有核心工具。

工具可見性控制

MCP Funnel 提供了一個三層可見性系統來管理哪些工具被暴露：

• 始終可見的工具（alwaysVisibleTools）：匹配這些模式的工具從啟動時就始終可見，即使使用動態發現模式（空允許列表）也是如此，適用於你始終需要使用的關鍵工具。
• 可發現的工具（exposeTools）：當使用空允許列表（exposeTools: []）時，這些工具最初是隱藏的，但可以通過 load_toolset 動態發現和啟用；當列入 exposeTools 允許列表時，它們從啟動時就可見。
• 隱藏的工具（hideTools）：匹配這些模式的工具永遠不會被暴露，無論其他設置如何。

動態發現

如果你想從最小化的工具集開始，並按需啟用工具，可以這樣配置：

{
  "exposeTools": [],
  "alwaysVisibleTools": [],
  "exposeCoreTools": [
    "discover_*",
    "get_tool_schema",
    "load_toolset",
    "bridge_tool_request"
  ]
}

運行時流程如下：

1. 搜索：使用 discover_tools_by_words 並提供關鍵字（如 "context7"）。
2. 啟用：使用 load_toolset 並指定明確的工具名稱或模式（如 ["context7__resolve_library_id", "context7__get-library-docs"]）。
3. 調用：正常使用已啟用的工具。

核心工具模式（超低上下文）

核心工具模式允許你僅暴露 MCP Funnel 的內部工具以進行動態發現。當你將 exposeCoreTools 設置為最小集合時，MCP Funnel 可以只暴露最少 3 個工具，而不是 100 多個：

1. discover_tools_by_words：通過關鍵字搜索工具。
2. get_tool_schema：獲取任何工具的輸入模式。
3. bridge_tool_request：動態執行任何工具。

動態工具發現（實驗性）

MCP Funnel 包含一個 discover_tools_by_words 工具，允許通過關鍵字搜索工具。然而，目前該功能的實用性有限：

• Claude Code CLI 不支持動態工具更新：一旦會話開始，工具列表就固定了。這意味著：
  • discover_tools_by_words 可以找到匹配的工具。
  • 它可以在 MCP Funnel 的內部狀態中“啟用”這些工具。
  • 但在你重啟會話之前，Claude 不會看到新啟用的工具。

安全考慮

• 切勿提交 API 密鑰：使用環境變量或 .env 文件（在 .gitignore 中忽略）。
• 文件系統訪問：謹慎設置文件系統服務器的路徑。
• Docker 權限：如果使用容器化服務器，確保有正確的 Docker 套接字訪問權限。
• 網絡隔離：對於敏感操作，考慮在隔離環境中運行。

路線圖

• [x] 實現連接重試邏輯，以實現彈性服務器管理。
• [ ] 實現健康監測和狀態報告。
• [x] 實現服務器故障時的優雅降級。
• [ ] 實現可配置級別的結構化日誌記錄。
• [ ] 實現指標和性能監測。
• [ ] 支持 WebSocket 傳輸。
• [ ] 實現完整的動態工具發現（取決於 Claude Code CLI 的支持）。

測試

運行測試套件：

yarn test           # 運行所有測試
yarn test:e2e       # 運行端到端測試
yarn validate       # 運行代碼質量檢查（ lint、類型檢查、格式化）

該項目包含全面的端到端測試，模擬了與模擬 MCP 服務器的 Claude SDK 對話。

貢獻

歡迎貢獻代碼！目前需要改進的關鍵領域包括：

1. 錯誤處理：使 MCP Funnel 能夠更好地應對服務器故障。
2. 測試：為除 Claude Code 之外的其他客戶端添加全面的測試覆蓋。
3. 日誌記錄：實現結構化日誌記錄。

🔧 技術細節

架構

┌────────────────────────┐
│ CLI (e.g. Claude Code) │
└──────┬─────────────────┘
       │ MCP Protocol via stdio
┌──────▼──────┐
│  MCP Funnel │ ← Filtering and dynamic discovery happens here
└──────┬──────┘
       │
   ┌───┴──────┬─────────┬─────────┐
   │          │         │         │
┌──▼────┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│GitHub │ │Memory │ │FS     │ │ ...   │ ← Each exposes all tools
└───────┘ └───────┘ └───────┘ └───────┘

MCP Funnel 的工作流程如下：

1. 作為客戶端連接到多個 MCP 服務器。
2. 從每個服務器接收所有工具。
3. 應用你的過濾規則。
4. 僅向客戶端暴露經過過濾的工具。
5. 將工具調用路由到適當的後端服務器。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱倉庫根目錄下的 LICENSE 文件。

🙏 致謝

本項目基於 Anthropic 的 Model Context Protocol SDK 構建。