STARWARCLOUD STARWAR.AI
返回市场
模块化-mcp

模块化-mcp

作者：d-kimuson29 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

模块化MCP

License CI GitHub Release DeepWiki

<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->

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

概念

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

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

它是如何工作的？

1. 配置

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

这里是一个使用Context7和Playwright MCP服务器的例子：

{
+ "$schema": "https://raw.githubusercontent.com/d-kimuson/modular-mcp/refs/heads/main/config-schema.json",
  "mcpServers": {
    "context7": {
+     "description": "当您需要搜索库文档时使用。",
-     "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    },
    "playwright": {
+     "description": "当您需要控制或自动化网络浏览器时使用。",
-     "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    }
  }
}

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

注意：如果未指定，则type字段默认为"stdio"。对于stdio类型的服务器，您可以省略type字段以获得更简洁的配置。

环境变量插值

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

支持的语法：

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

注意：仅支持${VAR}语法。不支持$VAR（无大括号）语法，以避免与合法包含美元符号的值（如token$abc123）发生冲突。

插值支持的位置：

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

示例：

{
  "mcpServers": {
    "my-server": {
      "description": "具有环境变量的示例服务器",
      "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服务器",
      "type": "http",
      "url": "https://api.example.com",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

重要提示：

  • 在启动模块化MCP之前必须设置环境变量。
  • 如果引用的环境变量未定义，将记录警告并保留原始占位符（例如，${UNDEFINED_VAR}）。
  • 变量在加载时替换，因此配置文件仍然安全提交。

2. 注册模块化MCP

在您的MCP客户端配置（例如，Claude Code的.mcp.json）中注册模块化MCP：

{
  "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工具描述包括关于可用组的信息，如下所示：

模块化MCP将多个MCP服务器作为组织化的组进行管理，在需要时仅提供必要的组工具描述给LLM，而不是一次性将其淹没在所有工具描述中。

使用此工具检索特定组中的可用工具，然后使用call-modular-tool执行它们。

可用组：
- context7：当您需要搜索库文档时使用。
- playwright：当您需要控制或自动化网络浏览器时使用。

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

4. 按需工具加载

LLM现在可以根据组别加载和使用工具：

  1. 发现：LLM看到工具描述中的可用组（不需要工具调用）
  2. 探索：当LLM需要playwright工具时，它会调用get-modular-tools，参数为group="playwright"
  3. 执行：LLM使用call-modular-tool执行特定工具，如browser_navigate

例如，要自动化网络浏览器：

get-modular-tools(group="playwright")
→ 返回所有playwright工具模式

call-modular-tool(group="playwright", name="browser_navigate", args={"url": "https://example.com"})
→ 通过playwright MCP服务器执行导航

这种工作流程保持了最小的上下文使用，同时在需要时提供了对所有工具的访问。

优点

  • 减少上下文使用：仅在实际需要时加载工具信息。
  • 可扩展性：可以管理数十个MCP服务器而不使上下文过载。
  • 灵活性：轻松添加/删除工具组而不影响其他组。
  • 透明性：工具执行就像直接在上游服务器上调用一样。

从标准MCP配置迁移

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

使用迁移命令

运行迁移命令并带上现有的MCP配置文件：

npx -y @kimuson/modular-mcp migrate <mcp-config-file-path>

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

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

迁移命令将：

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

远程MCP服务器的OAuth认证

模块化MCP支持使用sse和http传输的远程MCP服务器的基于OAuth的认证。

使用内置OAuth支持（实验性）

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

{
  "mcpServers": {
    "linear-server": {
      "description": "当您想检查Linear票据等时使用。",
      "type": "sse",
      "url": "https://mcp.linear.app/sse"
    }
  }
}

首次连接时，您的浏览器将打开进行OAuth认证。令牌存储在本地的~/.modular-mcp/oauth-servers/中，并自动重用。

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

备用方案：通过stdio使用mcp-remote

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

{
  "mcpServers": {
    "linear-server": {
      "description": "当您想检查Linear票据等时使用。",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

这种方法将OAuth处理委托给mcp-remote客户端，如果实验性的OAuth支持对您的服务器不起作用，这是推荐的方法。