mcp-gateway

MCP Orchestrator

一个中央枢纽，可连接多个下游 MCP 服务，聚合其工具，并通过强大的工具搜索功能提供统一访问。

基于 延迟加载工具 构建——可搜索所有服务，而不会占满 Claude 的上下文窗口。

功能

• 基于配置的服务注册：通过 JSON 配置文件添加下游 MCP 服务
• 工具命名空间：自动采用 server_name__tool_name 格式
• 工具搜索：统一的 BM25/正则表达式搜索，支持延迟加载
• 灵活的身份验证：静态保存的标头或令牌转发
• 多种传输方式：stdio 或 HTTP
• 工具定义缓存：缓存定义，原始结果直通
• 存储后端：内存（开发环境）或 Redis（生产环境）

快速开始

安装

pip install mcp-orchestrator

运行 MCP 服务

# Run as stdio MCP server (for Claude Desktop, Cursor, etc.)
mcp-orchestrator

# Or run with Python directly
python -m mcp_orchestrator.main

HTTP 传输：

ORCHESTRATOR_TRANSPORT=http ORCHESTRATOR_PORT=8080 python -m mcp_orchestrator.main

这会在 http://localhost:8080/mcp 启动服务并启用 CORS。

配置服务

在 server_config.json 中添加下游 MCP 服务：

{
  "servers": [
    {
      "name": "my-server",
      "url": "http://localhost:8080/mcp",
      "transport": "http",
      "auth_type": "static",
      "auth_headers": {
        "Authorization": "Bearer my-token"
      }
    },
    {
      "name": "my-stdio-server",
      "url": "server.py",
      "transport": "stdio",
      "command": "uv",
      "args": ["run", "python", "server.py"]
    }
  ]
}

搜索工具

Orchestrator 提供统一的工具搜索（默认使用 BM25，可选正则表达式）：

# BM25 search (default - natural language)
results = await mcp_client.call_tool("tool_search", {
    "query": "get weather information",
    "max_results": 3
})

# Regex search (set use_regex=true)
results = await mcp_client.call_tool("tool_search", {
    "query": "weather|forecast",
    "use_regex": true,
    "max_results": 3
})

架构

┌─────────────────────────────────────────────────────┐
│                  MCP Orchestrator                    │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │              FastMCP Server                   │   │
│  │  ┌─────────────┐  ┌──────────────────┐   │   │
│  │  │ tool_search │  │ call_remote_tool  │   │   │
│  │  └─────────────┘  └──────────────────┘   │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐      │
│  │  Server  │  │   Tool   │  │   Storage    │      │
│  │ Registry │  │  Search  │  │(Memory/Redis)│      │
│  └──────────┘  └──────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────┘
                           │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   ┌─────────┐        ┌─────────┐        ┌─────────┐
   │ MCP Svr │        │ MCP Svr │        │ MCP Svr │
   │   #1    │        │   #2    │        │   #N    │
   └─────────┘        └─────────┘        └─────────┘

配置

环境变量

变量	默认值	说明
STORAGE_BACKEND	memory	存储后端（memory 或 redis）
REDIS_URL	redis://localhost:6379/0	Redis 连接 URL
MCP_ORCHESTRATOR_TOOL_CACHE_TTL	300	工具架构缓存 TTL，单位为秒
MCP_ORCHESTRATOR_DEFAULT_CONNECTION_MODE	stateless	默认连接模式
MCP_ORCHESTRATOR_CONNECTION_TIMEOUT	30.0	连接超时时间，单位为秒
MCP_ORCHESTRATOR_MAX_RETRIES	3	最大重试次数
ORCHESTRATOR_TRANSPORT	stdio	MCP 传输方式（stdio 或 http）
ORCHESTRATOR_PORT	8080	HTTP 传输端口
ORCHESTRATOR_HOST	0.0.0.0	HTTP 传输主机
ORCHESTRATOR_LOG_LEVEL	INFO	日志级别
SERVER_CONFIG_PATH	server_config.json	服务配置文件路径

Claude Desktop 集成

将以下内容添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "mcp-orchestrator": {
      "command": "mcp-orchestrator",
      "env": {
        "STORAGE_BACKEND": "memory",
        "ORCHESTRATOR_LOG_LEVEL": "INFO"
      }
    }
  }
}

MCP 工具

tool_search

使用 BM25 相关性排序或正则表达式模式匹配搜索工具。

@mcp.tool()
async def tool_search(
    query: str,
    max_results: int = 3,
    use_regex: bool = False,
) -> dict:
    """Search for tools using BM25 or regex.

    By default uses BM25 natural language search. Set use_regex=True
    to search using Python regex patterns instead.
    """

discover_tools

从已注册的下游服务中发现工具。

@mcp.tool()
async def discover_tools(
    server_name: str,
) -> dict:
    """Discover tools from a registered server and index them for search.

    Returns the list of discovered tools with their schemas.
    """

call_remote_tool

直接在下游 MCP 服务上调用工具。

@mcp.tool()
async def call_remote_tool(
    tool_name: str,
    arguments: Optional[dict] = None,
    auth_header: Optional[str] = None,
) -> Any:
    """Call a tool on a downstream server.

    Args:
        tool_name: Namespaced tool name (server_name__tool_name)
        arguments: Tool arguments
        auth_header: Optional auth header to override server's configured auth
    """

工具搜索结果

搜索工具会按 Claude 工具搜索系统所需的格式返回结果：

{
  "success": true,
  "tool_references": [
    {
      "type": "tool_reference",
      "tool_name": "server_name__tool_name"
    }
  ],
  "total_matches": 5,
  "query": "weather"
}

测试

运行测试套件：

uv run pytest

运行并生成覆盖率报告：

uv run pytest --cov=mcp_orchestrator

项目结构

mcp-orchestrator/
├── src/mcp_orchestrator/
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── models.py            # Pydantic models
│   ├── mcp_server.py        # FastMCP server
│   ├── config_loader.py     # Config file loader
│   ├── server/
│   │   └── registry.py      # Server registry
│   ├── tools/
│   │   ├── router.py       # Tool router
│   │   └── search.py       # Tool search service
│   └── storage/
│       ├── base.py          # Storage interface
│       ├── memory.py        # In-memory backend
│       └── redis.py         # Redis backend
├── tests/
│   ├── test_registry.py
│   ├── test_search.py
│   ├── test_storage.py
│   ├── test_models.py
│   └── test_integration.py
├── server_config.json       # Pre-configured downstream servers
├── pyproject.toml
├── README.md
└── .env                    # Environment variables (not committed)

许可证

MIT 许可证

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。