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 构建。