Modular MCP

模块化MCP

  ](https://github.com/d-kimuson/modular-mcp/releases) 

一种模型上下文协议（MCP）代理服务器，通过按需分组和加载工具模式，实现了跨多个MCP服务器对大型工具集合的高效管理。

概念

在处理来自多个服务器的众多工具时，传统的MCP设置可能会淹没LLM上下文。模块化MCP通过以下方式解决了这个问题：

• 上下文效率：组信息嵌入在工具描述中，因此LLM可以在不进行任何工具调用的情况下发现可用组
• 按需加载：仅在特定组需要时检索详细的工具架构
• 关注点分离：在工具发现和执行之间保持清晰的阶段
• 代理架构：充当管理多个上游MCP服务器的单个MCP端点

它是如何工作的？

1.配置

创建配置文件（例如。， modular-mcp.json)对于您要管理的上游MCP服务器。这使用了标准的MCP服务器配置格式，并增加了一个：a description 每个服务器的字段。

以下是一个使用Context7和Playwright MCP服务器的示例：

{
+ "$schema": "https://raw.githubusercontent.com/d-kimuson/modular-mcp/refs/heads/main/config-schema.json",
  "mcpServers": {
    "context7": {
+     "description": "Use when you need to search library documentation.",
-     "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    },
    "playwright": {
+     "description": "Use when you need to control or automate web browsers.",
-     "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    }
  }
}

这 description 字段是标准MCP配置的唯一扩展。它有助于LLM理解每个工具组的目的，而无需加载详细的工具模式。

备注：The type 字段默认为 "stdio" 如果没有指定。对于 stdio 类型服务器，可以省略 type 用于更清洁配置的字段。

环境变量插值

模块化MCP支持配置文件中的环境变量插值，使您能够避免将API密钥和令牌等敏感信息提交给版本控制。

支持的语法:

• ${VAR} -带括号的变量引用

备注：只有 ${VAR} 支持语法。这 $VAR 有意不支持语法（不带大括号），以避免与合法包含美元符号的值（例如，类似 token$abc123).

支持插值的地方:

• stdio 服务器： args 数组元素和 env 对象值
• http/sse 服务器： url 字符串和 headers 对象值

示例:

{
  "mcpServers": {
    "my-server": {
      "description": "Example server with environment variables",
      "command": "node",
      "args": ["${HOME}/.local/bin/server.js", "--config=${XDG_CONFIG_HOME}/app/config.json"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "LOG_DIR": "${HOME}/logs"
      }
    },
    "api-server": {
      "description": "HTTP server with authentication",
      "type": "http",
      "url": "https://api.example.com",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

重要说明:

• 启动模块化MCP之前，必须设置环境变量
• 如果未定义引用的环境变量。， ${UNDEFINED_VAR})将被保存
• 变量在加载时被替换，因此配置文件仍然可以安全提交

2.注册模块化MCP

在MCP客户端配置中注册模块化MCP（例如。， .mcp.json 克劳德代码）：

{
  "mcpServers": {
    "modular-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kimuson/modular-mcp", "modular-mcp.json"],
      "env": {}
    }
  }
}

3.两个工具注册

当模块化MCP启动时，它只向LLM注册两个工具：

• get-modular-tools：检索特定组的工具名称和架构
• call-modular-tool：执行特定组中的工具

这 get-modular-tools 工具描述包括有关可用组的信息，如下所示：

modular-mcp manages multiple MCP servers as organized groups, providing only the necessary group's tool descriptions to the LLM on demand instead of overwhelming it with all tool descriptions at once.

Use this tool to retrieve available tools in a specific group, then use call-modular-tool to execute them.

Available groups:
- context7: Use when you need to search library documentation.
- playwright: Use when you need to control or automate web browsers.

此描述作为系统提示的一部分传递给LLM，使其能够在不进行任何工具调用的情况下发现可用组。

4.按需加载工具

LLM现在可以按组加载和使用工具：

1. 发现：LLM在工具描述中看到可用组（不需要工具调用）
2. 探索当法学硕士需要剧作家工具时，它会调用 get-modular-tools 随着 group="playwright"
3. 执行：LLM使用 call-modular-tool 执行特定工具，如 browser_navigate

例如，要自动化web浏览器：

get-modular-tools(group="playwright")
→ Returns all playwright tool schemas

call-modular-tool(group="playwright", name="browser_navigate", args={"url": "https://example.com"})
→ Executes the navigation through the playwright MCP server

此工作流将上下文使用率降至最低，同时在需要时提供对所有工具的访问。

益处

• 减少上下文使用：仅在实际需要时加载工具信息
• 可扩展的：可以管理数十台MCP服务器，而不会占用大量上下文
• 灵活的：易于添加/删除工具组，而不会影响其他工具组
• 透明：工具的执行方式与直接在上游服务器上调用时完全相同

从标准MCP配置迁移

如果您已经有一个标准的MCP配置文件（例如。， .mcp.json)，您可以使用内置的迁移命令轻松地将其迁移到模块化MCP格式。

使用迁移命令

使用现有的MCP配置文件运行迁移命令：

npx -y @kimuson/modular-mcp migrate 

例如，如果你有一个 .mcp.json 文件：

npx -y @kimuson/modular-mcp migrate .mcp.json

迁移命令将：

1. 生成一个 modular-mcp.json 具有迁移配置的文件（默认为 modular-mcp.json 在当前目录中，或使用 -o 指定自定义路径）
2. 将原始文件的内容替换为引用生成的模块化MCP服务器配置 modular-mcp.json 文件

远程MCP服务器的OAuth身份验证

模块化MCP支持远程MCP服务器使用OAuth进行身份验证 sse 和 http 运输。

使用内置OAuth支持（实验）

模块化MCP包括一个实验性的OAuth客户端，该客户端实现了 MCP授权规范:

{
  "mcpServers": {
    "linear-server": {
      "description": "Use when you want to check Linear tickets, etc.",
      "type": "sse",
      "url": "https://mcp.linear.app/sse"
    }
  }
}

在第一次连接时，您的浏览器将打开进行OAuth身份验证。令牌存储在本地 ~/.modular-mcp/oauth-servers/ 并自动重复使用。

注： 此功能是实验性的。如果遇到问题，请使用下面的回退方法。

回退：通过stdio使用mcp远程

为了与所有OAuth服务器兼容，您可以使用 mcp-remote 通过 stdio 运输：

{
  "mcpServers": {
    "linear-server": {
      "description": "Use when you want to check Linear tickets, etc.",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

此方法将OAuth处理委托给 mcp-remote 客户端，如果实验性OAuth支持不适用于您的服务器，建议使用。