关键词

LLM工具管理AI上下文优化智能代理服务器开发工具集成API路由

项目简介

MCP Funnel是一个基于Model Context Protocol (MCP) 构建的代理服务器。它的核心功能是连接并管理多个独立的MCP服务器（例如GitHub、内存管理、文件系统操作等），然后将这些后端服务器提供的工具整合到一个单一的、经过优化的MCP接口中。这个统一的接口暴露给大型语言模型（LLM）客户端（如Claude Code CLI、Google Gemini），允许LLM访问这些工具。

MCP Funnel的主要价值在于其强大的工具管理能力。它允许用户进行精细化的工具过滤和命名空间管理，解决后端MCP服务器工具过多、名称冲突以及上下文令牌消耗过大的问题。通过仅暴露LLM客户端所需的必要工具，MCP Funnel能够显著优化LLM的上下文使用，降低成本，并提高交互效率。

主要功能点

  • 多服务器聚合: 能够同时连接任意数量的后端MCP服务器，并将它们的工具统一在一个接口下。
  • 工具命名空间: 自动为来自不同后端服务器的工具添加唯一前缀（例如，'github__create_issue'），有效避免工具名称冲突。
  • 灵活的工具过滤: 支持使用通配符模式（'*'）来精确控制哪些工具可以被LLM客户端看到。您可以选择隐藏不需要的特定工具，或仅暴露您希望LLM使用的工具子集。
  • 上下文优化: 通过对工具列表进行选择性过滤，显著减少传递给LLM的工具上下文（Readme中提到可减少40-60%），从而降低令牌消耗和提高LLM的推理效率。
  • 核心工具集: 提供一系列内置的MCP工具，用于增强LLM的交互能力，包括：
    • 'discover_tools_by_words': 允许LLM通过关键词搜索并发现可用的工具。
    • 'get_tool_schema': 帮助LLM获取特定工具的输入参数结构，以便正确调用。
    • 'bridge_tool_request': 允许LLM通过桥接方式动态执行任何已发现的工具。
    • 'load_toolset': 允许LLM一次性加载或启用预定义的一组相关工具。
  • 内置命令: 额外提供了一些开箱即用的开发命令，例如NPM包的查询和搜索功能，可以直接通过MCP接口使用。

安装步骤

  1. 克隆项目仓库: 打开您的终端或命令行工具，执行以下命令克隆MCP Funnel的GitHub仓库：

    git clone https://github.com/chris-schra/mcp-funnel.git
cd mcp-funnel

  2. 安装项目依赖: 进入项目目录后，使用npm或yarn安装所有必需的依赖项：

    yarn install
# 或者使用 npm install

  3. 创建配置文件: MCP Funnel需要一个配置文件来定义它应该连接哪些后端MCP服务器以及如何过滤工具。复制示例配置文件并进行修改：

    cp .mcp-funnel.example.json .mcp-funnel.json

    然后，您需要编辑 '.mcp-funnel.json' 文件，根据您的需求配置要代理的MCP服务器和工具过滤规则。

服务器配置

MCP Funnel的配置信息存储在一个JSON格式的文件中（通常是项目根目录下的'.mcp-funnel.json'）。这个文件定义了MCP Funnel作为代理服务器如何连接其他MCP服务器以及如何处理工具。

以下是一个'.mcp-funnel.json'配置示例及其关键参数的说明：

{
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "--env-file",
        ".env",
        "-i",
        "--rm",
        "ghcr.io/github/github-mcp-server"
      ]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  },
  "hideTools": [
    "github__list_workflow_runs",
    "github__get_workflow_run_logs",
    "memory__debug_*",
    "memory__dashboard_*",
    "github__get_team_members"
  ],
  "enableDynamicDiscovery": false,
  "hackyDiscovery": false,
  "toolsets": {
    "developer": [
      "github__create_issue",
      "github__list_issues",
      "memory__store_memory",
      "filesystem__read_file"
    ],
    "reviewer": ["github__*_pull_request*", "github__update_issue"]
  },
  "commands": {
    "enabled": true,
    "list": ["npm"]
  }
}

配置参数说明:

  • 'servers': （必需）一个JSON对象，定义了MCP Funnel将作为客户端连接的后端MCP服务器。
    • 键: 您为该服务器指定的名称（例如'"github"'、'"memory"'）。这个名称将用作该服务器工具的前缀，以避免命名冲突（例如'github__create_issue'）。
    • 值: 另一个JSON对象，包含启动该后端MCP服务器的详细信息：
      • 'command': （必需）一个字符串，表示用于启动后端MCP服务器的命令行命令（例如'"docker"'、'"npx"'）。
      • 'args': （可选）一个字符串数组，包含传递给'command'的命令行参数（例如'["run", "github-mcp-server"]'）。
      • 'env': （可选）一个JSON对象，包含在启动后端MCP服务器时要设置的环境变量（例如'{"GITHUB_TOKEN": "your-token-here"}'）。请注意，API密钥等敏感信息应通过环境变量或'.env'文件管理，切勿直接提交到版本控制中。
  • 'hideTools': （可选）一个字符串数组，包含要从LLM客户端隐藏的工具模式。支持通配符'*'。匹配此模式的工具将不会暴露给LLM。
    • 例如：'"github__list_workflow_runs"' 会隐藏GitHub服务器的特定工具。
    • 例如：'"memory__debug_*"' 会隐藏Memory服务器所有以'debug_'开头的工具。
    • 例如：'"_list"' 会隐藏所有服务器中名称包含'list'的工具。
  • 'exposeTools': （可选）一个字符串数组，仅暴露匹配这些模式的工具。如果此字段存在，则只有与这些模式匹配的工具会被暴露给LLM客户端，其他工具将被隐藏。
  • 'alwaysVisibleTools': （可选）一个字符串数组，定义即使在启用动态发现模式时也会始终暴露给LLM客户端的工具模式。这适用于您希望LLM总是能访问的关键工具。
  • 'enableDynamicDiscovery': （可选，默认为'false'）一个布尔值。如果设置为'true'，MCP Funnel将启动动态工具发现模式，初始时仅暴露最少的工具（通常是'discover_tools_by_words'、'get_tool_schema'和'bridge_tool_request'），其他工具需要LLM通过发现工具进行激活。
  • 'hackyDiscovery': （可选，默认为'false'）一个布尔值。如果设置为'true'，这是一个针对某些LLM客户端限制的超低上下文模式，仅暴露3个核心桥接工具，以最大程度减少初始上下文消耗。
  • 'toolsets': （可选）一个JSON对象，定义了预定义的工具集。LLM可以通过'load_toolset'核心工具一次性加载或启用一个工具集中的所有工具。
    • 键: 工具集的名称（例如'"developer"'、'"reviewer"'）。
    • 值: 一个字符串数组，包含属于该工具集的工具模式。
  • 'commands': （可选）一个JSON对象，用于配置MCP Funnel的内置命令。
    • 'enabled': （默认为'false'）一个布尔值，表示是否启用内置命令功能。
    • 'list': （可选）一个字符串数组，列出要启用的特定内置命令的名称。如果为空，则启用所有发现的内置命令。

基本使用方法

MCP Funnel启动后，它将作为一个标准的MCP服务器运行，通过Stdio（标准输入/输出）协议与LLM客户端进行通信。要使用MCP Funnel，您需要将MCP Funnel的启动命令配置到您的LLM客户端中。

以下是一些常见LLM客户端的配置示例：

1. 使用Claude Code CLI

在您的项目目录中创建或编辑 '.mcp.json' 配置文件，并添加MCP Funnel的服务器配置：

{
  "mcpServers": {
    "mcp-funnel": {
      "command": "npx",
      "args": ["-y", "mcp-funnel"]
      // 如果您的 .mcp-funnel.json 文件不在当前工作目录，
      // 您可以显式指定路径，例如：
      // "args": ["-y", "mcp-funnel", "/path/to/your/.mcp-funnel.json"]
    }
  }
}

2. 使用Google Gemini

在您的项目配置（例如 '.gemini/settings.json'）中添加：

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

3. 使用Codex CLI

在您的Codex CLI配置（例如 '~/.codex/config.toml'）中添加：

[mcp_servers.mcp-funnel]
command = "npx"
args = ["-y", "mcp-funnel"]

配置完成后，当您使用上述LLM客户端时，它们将自动连接到MCP Funnel。您就可以通过自然语言与MCP Funnel聚合和过滤后的工具进行交互了。

示例对话:

假设您已经配置了GitHub MCP服务器并通过MCP Funnel代理，您可以直接向LLM提问：

'"Load PRs for https://github.com/chris-schra/mcp-funnel"'

LLM会通过MCP Funnel找到并调用您GitHub服务器上的'list_pull_requests'工具来获取信息，并以结构化的方式返回给您。

本地开发

  • 运行开发服务器 (带热重载): 
    yarn dev
  • 构建项目: 
    yarn build
    构建完成后，您可以通过以下方式运行： 
    node dist/cli.js                     # 使用当前目录的 .mcp-funnel.json
node dist/cli.js /path/to/custom-config.json # 指定配置文件路径

信息

分类

AI与计算

访问项目