MCP Orchestrator

MCP Orchestrator

Um hub central que se conecta a vários servidores MCP downstream, agrega suas ferramentas e fornece acesso unificado com poderosos recursos de busca de ferramentas.

Construído em torno de carregamento adiado de ferramentas — pesquise em todos os seus servidores sem estourar a janela de contexto do Claude.

Recursos

• Registro de servidores baseado em configuração: Adicione servidores MCP downstream via arquivo de configuração JSON
• Namespacing de ferramentas: Formato automático server_name__tool_name
• Busca de ferramentas: Busca unificada BM25/regex com suporte a carregamento adiado
• Autenticação flexível: Cabeçalhos salvos estáticos ou encaminhamento de token
• Múltiplos transportes: stdio ou HTTP
• Cache de definições de ferramentas: Definições em cache, passagem de resultados brutos
• Backends de armazenamento: Em memória (desenvolvimento) ou Redis (produção)

Início Rápido

Instalação

pip install mcp-orchestrator

Executando o servidor MCP

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

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

Transporte HTTP:

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

Isso inicia o servidor em http://localhost:8080/mcp com CORS habilitado.

Configurando servidores

Adicione servidores MCP downstream em server_config.json:

{
  "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"]
    }
  ]
}

Buscando por ferramentas

O orquestrador fornece busca unificada de ferramentas (BM25 por padrão, regex opcional):

# 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
})

Arquitetura

┌─────────────────────────────────────────────────────┐
│                  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    │
   └─────────┘        └─────────┘        └─────────┘

Configuração

Variáveis de ambiente

Variável	Padrão	Descrição
STORAGE_BACKEND	memory	Backend de armazenamento (memory ou redis)
REDIS_URL	redis://localhost:6379/0	URL de conexão Redis
MCP_ORCHESTRATOR_TOOL_CACHE_TTL	300	TTL do cache de esquema de ferramentas em segundos
MCP_ORCHESTRATOR_DEFAULT_CONNECTION_MODE	stateless	Modo de conexão padrão
MCP_ORCHESTRATOR_CONNECTION_TIMEOUT	30.0	Tempo limite de conexão em segundos
MCP_ORCHESTRATOR_MAX_RETRIES	3	Número máximo de tentativas
ORCHESTRATOR_TRANSPORT	stdio	Transporte MCP (stdio ou http)
ORCHESTRATOR_PORT	8080	Porta para transporte HTTP
ORCHESTRATOR_HOST	0.0.0.0	Host para transporte HTTP
ORCHESTRATOR_LOG_LEVEL	INFO	Nível de log
SERVER_CONFIG_PATH	server_config.json	Caminho para o arquivo de configuração do servidor

Integração com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Ferramentas MCP

tool_search

Busque ferramentas usando classificação de relevância BM25 ou correspondência de padrões regex.

@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

Descubra ferramentas de um servidor downstream registrado.

@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

Chame uma ferramenta diretamente em um servidor MCP downstream.

@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
    """

Resultados da busca de ferramentas

As ferramentas de busca retornam resultados no formato esperado pelo sistema de busca de ferramentas do Claude:

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

Testes

Execute a suíte de testes:

uv run pytest

Execute com cobertura:

uv run pytest --cov=mcp_orchestrator

Estrutura do projeto

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)

Licença

MIT License

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.