Gateway MCP Server

Um servidor gateway que roteia inteligentemente solicitações MCP para múltiplos servidores backend

GitHub
3
Experimente este MCPPatrocinado

Documentação

Gateway MCP Server

mcpware Logo

Tests Coverage Python License: MIT

Roteie solicitações MCP de forma inteligente para múltiplos servidores backend.

🎯 Principais Recursos

🚀 Contorne os Limites de Ferramentas

  • Desafio: Clientes MCP frequentemente têm limites de quantas ferramentas podem ser carregadas de uma vez
  • Solução: mcpware expõe apenas 2 ferramentas de roteamento enquanto fornece acesso a ferramentas backend ilimitadas
  • Resultado: Conecte-se ao GitHub (mais de 50 ferramentas), bancos de dados e muito mais através de um único gateway!

🔧 Benefícios Adicionais

  • Ponto de entrada único para múltiplos servidores MCP
  • Gerenciamento automático de processos para servidores backend
  • Isolamento e implantação baseados em Docker

Início Rápido

# Clone the repository
git clone https://github.com/delexw/mcpware.git
cd mcpware

# Build the Docker image
docker build -t mcpware . --no-cache

# Configure MCP client (see Installation section)

Em seguida, configure os Clientes MCP conforme mostrado na seção Instalação.

Como Funciona

O mcpware roda como um contêiner Docker que:

  1. Recebe solicitações de clientes MCP via stdio
  2. Roteia para o servidor MCP backend apropriado (também rodando em Docker)
  3. Retorna respostas ao cliente MCP

Importante: Servidores backend podem usar qualquer comando (docker, npx, node, python, etc.). Ao executar o mcpware em Docker, backends que usam comandos locais como npx ou node serão executados dentro do contêiner do mcpware.

Instalação

Pré-requisitos

  • Docker
  • Clientes MCP (Cursor, etc.)

Configuração com Cliente MCP

  1. Clone este repositório:

    git clone https://github.com/delexw/mcpware.git
cd mcpware

  2. Configure seus backends em config.json (veja a seção de Configuração abaixo)

  3. Configure suas variáveis de ambiente:

    1. Copie o arquivo de exemplo: cp env.example .env
    2. Edite .env com seus valores reais: 
      GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
BUILDKITE_API_TOKEN=your_buildkite_token_here
# Add other environment variables as needed

  4. Adicione à configuração do cliente MCP:

    Nota: Você pode configurar os segredos ou tokens diretamente no config.json do mcpware

    Configuração (Execução Direta com Docker):

    {
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "--env-file",
        "/path/to/mcpware/.env",
        "mcpware"
      ]
    }
  }
}

    Importante:

    • Substitua /path/to/mcpware pelo caminho absoluto do seu repositório clonado
    • A montagem do socket Docker (/var/run/docker.sock) é necessária para o mcpware iniciar backends baseados em Docker, caso contrário você não precisa dela

    Por que montar o socket Docker?

    • O mcpware precisa iniciar contêineres Docker para servidores MCP backend (como ghcr.io/github/github-mcp-server)
    • A montagem do socket Docker permite que o mcpware se comunique com o Docker
    • Sem essa montagem, o mcpware não pode iniciar servidores backend que rodam como contêineres Docker

Configuração do Socket Docker Específica por Plataforma

O gateway precisa de acesso ao socket Docker para iniciar contêineres backend. O caminho de montagem difere por plataforma:

Por que o acesso ao socket Docker é necessário? O mcpware atua como um gerenciador de processos que inicia servidores MCP backend. Quando um backend é configurado para rodar como um contêiner Docker (ex.: ghcr.io/github/github-mcp-server), o mcpware precisa:

  • Criar e iniciar contêineres Docker
  • Gerenciar seu ciclo de vida (parar/reiniciar)
  • Comunicar-se com eles via stdio

Sem acesso ao socket Docker, o mcpware não pode iniciar backends baseados em Docker e falhará com erros de permissão.

Verificação Rápida

Execute este script para verificar sua configuração Docker:

python scripts/check_docker_socket.py

Linux/macOS/WSL2

Nenhuma alteração necessária. A configuração padrão funciona:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Windows (Contêineres Nativos)

Atualize o caminho do socket Docker:

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v",
        "//./pipe/docker_engine://./pipe/docker_engine",
        "--env-file",
        "/path/to/mcpware/.env",
        "mcpware"
      ]
    }
  }
}

Observe o caminho diferente do socket Docker: //./pipe/docker_engine em vez de /var/run/docker.sock

Verifique Seu Tipo de Docker

Para verificar qual backend Docker você está usando no Windows:

docker version --format '{{.Server.Os}}'
  • linux = backend WSL2/Hyper-V (use a configuração padrão)
  • windows = contêineres Windows (use o arquivo de substituição)

Configuração

Crie um config.json com seus servidores backend:

{
  "backends": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      },
      "description": "GitHub MCP Server",
      "timeout": 60
    },
    "database": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "bytebase/dbhub", "--transport", "stdio"],
      "description": "Database MCP Server"
    }
  }
}

Notas de Configuração:

  • Comandos backend podem ser qualquer executável (docker, npx, node, python, etc.)
  • Ao usar comandos docker, certifique-se de que o socket Docker esteja montado (veja as instruções de instalação)

Veja config.example.json para mais exemplos de backend (bancos de dados, APIs, etc.).

Uso

O gateway expõe duas ferramentas principais:

use_tool

Roteia uma chamada de ferramenta para um servidor backend específico.

Parâmetros:

  • backend_server: Nome do servidor backend
  • server_tool: Nome da ferramenta a ser chamada
  • tool_arguments: Argumentos a serem passados para a ferramenta

Exemplo:

{
  "backend_server": "github",
  "server_tool": "create_issue",
  "tool_arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "title": "New issue",
    "body": "Issue description"
  }
}

discover_backend_tools

Descobre backends disponíveis e suas ferramentas.

Parâmetros:

  • backend_name: (Opcional) Backend específico para consultar

Usando o mcpware Junto com Outros Servidores MCP

O mcpware é projetado para funcionar junto com outros servidores MCP na configuração do seu cliente MCP. Você pode:

  1. Usar o mcpware como gateway para múltiplos servidores backend
  2. Manter alguns servidores MCP separados para acesso direto
  3. Combinar e personalizar com base nas suas necessidades

Exemplo de configuração mista:

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "--env-file", "/path/to/mcpware/.env",
        "mcpware"
      ]
    },
    "redis-direct": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "REDIS_HOST=localhost", "mcp/redis"]
    }
  }
}

Isso permite que você:

  • Acesse múltiplos servidores através do mcpware quando precisar de roteamento
  • Conecte-se diretamente a servidores específicos quando precisar de acesso dedicado
  • Organize seus servidores MCP com base no seu fluxo de trabalho

Desenvolvimento

Pré-requisitos

Certifique-se de ter Python 3.10+ instalado:

python --version  # Should show Python 3.10 or higher

Configuração de Desenvolvimento

  1. Clone o repositório:

    git clone https://github.com/delexw/mcpware.git
cd mcpware

  2. Crie um ambiente virtual (recomendado):

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Instale as dependências de desenvolvimento:

    pip install -r requirements.txt

Dependências de Desenvolvimento

O projeto usa dependências mínimas. Toda a funcionalidade principal é implementada usando a biblioteca padrão do Python.

Dependências de teste (incluídas no requirements.txt):

  • pytest - Framework de testes
  • pytest-asyncio - Suporte a testes assíncronos
  • pytest-cov - Relatório de cobertura de código

Ferramentas de desenvolvimento opcionais (instale separadamente se necessário):

# Code formatting
pip install black isort

# Linting
pip install flake8 pylint mypy

# Development convenience
pip install pytest-watch  # Auto-run tests on file changes

Executando Localmente

# Run the gateway server
python gateway_server.py --config config.json

# Run with debug logging
python gateway_server.py --config config.json --log-level DEBUG

Estilo de Código

Formate seu código antes de commitar:

# Format with black (if installed)
black src/ tests/ gateway_server.py

# Sort imports (if installed)
isort src/ tests/ gateway_server.py

# Run linting (if installed)
flake8 src/ tests/ gateway_server.py --max-line-length=120

Executando Testes

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov=gateway_server --cov-report=html

# Run specific test file
pytest tests/test_config.py

# Run tests in watch mode (requires pytest-watch)
pytest-watch

Docker

Compile e execute com Docker:

# Build the image
docker build -t mcpware .

# Run interactively (for testing)
docker run -it --rm \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

# Run with specific config file
docker run -it --rm \
  -v /path/to/your/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

Variáveis de Ambiente

O gateway suporta substituição de variáveis de ambiente nas configurações de backend. Defina-as no seu arquivo .env:

# Example .env file
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# Add other tokens as needed

Variáveis de ambiente referenciadas em config.json usando a sintaxe ${VAR_NAME} serão substituídas automaticamente.

Testes

O projeto inclui testes unitários e de integração abrangentes.

Executando Testes

  1. Instale as dependências de teste:

    pip install -r requirements.txt

  2. Execute todos os testes:

    pytest

  3. Execute testes com cobertura:

    pytest --cov=src --cov=gateway_server --cov-report=html

  4. Execute módulos de teste específicos:

    pytest tests/test_config.py
pytest tests/test_backend.py
pytest tests/test_protocol.py

  5. Execute testes em modo de observação:

    pytest-watch

Licença

MIT