Gateway MCP Server

Un servidor gateway que enruta inteligentemente solicitudes MCP a múltiples servidores backend.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Gateway MCP Server

mcpware Logo

Tests Coverage Python License: MIT

Enruta solicitudes MCP de forma inteligente hacia múltiples servidores backend.

🎯 Características Principales

🚀 Supera los Límites de Herramientas

  • Desafío: Los clientes MCP a menudo tienen límites sobre cuántas herramientas pueden cargar a la vez
  • Solución: mcpware expone solo 2 herramientas de enrutamiento mientras proporciona acceso a herramientas backend ilimitadas
  • Resultado: ¡Conéctate a GitHub (más de 50 herramientas), bases de datos y más a través de una única puerta de enlace!

🔧 Beneficios Adicionales

  • Punto de entrada único para múltiples servidores MCP
  • Gestión automática de procesos para servidores backend
  • Aislamiento y despliegue basado en Docker

Inicio 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)

Luego configura los clientes MCP como se muestra en la sección Instalación.

Cómo Funciona

mcpware se ejecuta como un contenedor Docker que:

  1. Recibe solicitudes de clientes MCP a través de stdio
  2. Las enruta al servidor MCP backend apropiado (también ejecutándose en Docker)
  3. Devuelve las respuestas al cliente MCP

Importante: Los servidores backend pueden usar cualquier comando (docker, npx, node, python, etc.). Cuando se ejecuta mcpware en Docker, los backends que usan comandos locales como npx o node se ejecutarán dentro del contenedor de mcpware.

Instalación

Requisitos Previos

  • Docker
  • Clientes MCP (Cursor, etc.)

Configuración con el Cliente MCP

  1. Clona este repositorio:

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

  2. Configura tus backends en config.json (consulta la sección de Configuración a continuación)

  3. Configura tus variables de entorno:

    1. Copia el archivo de ejemplo: cp env.example .env
    2. Edita .env con tus valores reales: 
      GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
BUILDKITE_API_TOKEN=your_buildkite_token_here
# Add other environment variables as needed

  4. Añade a la configuración del cliente MCP:

    Nota: Puedes configurar los secretos o tokens directamente en mcpware config.json

    Configuración (Ejecución Directa con 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:

    • Reemplaza /path/to/mcpware con la ruta absoluta a tu repositorio clonado
    • El montaje del socket de Docker (/var/run/docker.sock) es necesario para que mcpware lance backends basados en Docker; de lo contrario, no lo necesitas

    ¿Por qué montar el socket de Docker?

    • mcpware necesita lanzar contenedores Docker para servidores MCP backend (como ghcr.io/github/github-mcp-server)
    • El montaje del socket de Docker permite que mcpware se comunique con Docker
    • Sin este montaje, mcpware no puede iniciar servidores backend que se ejecutan como contenedores Docker

Configuración del Socket de Docker Específica por Plataforma

La puerta de enlace necesita acceso al socket de Docker para lanzar contenedores backend. La ruta de montaje varía según la plataforma:

¿Por qué se requiere acceso al socket de Docker? mcpware actúa como un gestor de procesos que lanza servidores MCP backend. Cuando un backend está configurado para ejecutarse como un contenedor Docker (por ejemplo, ghcr.io/github/github-mcp-server), mcpware necesita:

  • Crear e iniciar contenedores Docker
  • Gestionar su ciclo de vida (detener/reiniciar)
  • Comunicarse con ellos a través de stdio

Sin acceso al socket de Docker, mcpware no puede lanzar backends basados en Docker y fallará con errores de permisos.

Verificación Rápida

Ejecuta este script para verificar tu configuración de Docker:

python scripts/check_docker_socket.py

Linux/macOS/WSL2

No se necesitan cambios. La configuración predeterminada funciona:

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

Windows (Contenedores Nativos)

Actualiza la ruta del socket de 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"
      ]
    }
  }
}

Observa la diferente ruta del socket de Docker: //./pipe/docker_engine en lugar de /var/run/docker.sock

Verifica tu Tipo de Docker

Para verificar qué backend de Docker estás usando en Windows:

docker version --format '{{.Server.Os}}'
  • linux = backend WSL2/Hyper-V (usa la configuración predeterminada)
  • windows = contenedores Windows (usa el archivo de anulación)

Configuración

Crea un config.json con tus 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 Configuración:

  • Los comandos backend pueden ser cualquier ejecutable (docker, npx, node, python, etc.)
  • Cuando uses comandos docker, asegúrate de que el socket de Docker esté montado (consulta las instrucciones de instalación)

Consulta config.example.json para más ejemplos de backends (bases de datos, APIs, etc.).

Uso

La puerta de enlace expone dos herramientas principales:

use_tool

Enruta una llamada de herramienta a un servidor backend específico.

Parámetros:

  • backend_server: Nombre del servidor backend
  • server_tool: Nombre de la herramienta a llamar
  • tool_arguments: Argumentos a pasar a la herramienta

Ejemplo:

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

discover_backend_tools

Descubre los backends disponibles y sus herramientas.

Parámetros:

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

Usar mcpware Junto a Otros Servidores MCP

mcpware está diseñado para funcionar junto a otros servidores MCP en tu configuración de cliente MCP. Puedes:

  1. Usar mcpware como puerta de enlace para múltiples servidores backend
  2. Mantener algunos servidores MCP separados para acceso directo
  3. Combinar y personalizar según tus necesidades

Ejemplo de configuración mixta:

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

Esto te permite:

  • Acceder a múltiples servidores a través de mcpware cuando necesitas enrutamiento
  • Conectarte directamente a servidores específicos cuando necesitas acceso dedicado
  • Organizar tus servidores MCP según tu flujo de trabajo

Desarrollo

Requisitos Previos

Asegúrate de tener Python 3.10+ instalado:

python --version  # Should show Python 3.10 or higher

Configuración de Desarrollo

  1. Clona el repositorio:

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

  2. Crea un entorno virtual (recomendado):

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

  3. Instala las dependencias de desarrollo:

    pip install -r requirements.txt

Dependencias de Desarrollo

El proyecto utiliza dependencias mínimas. Toda la funcionalidad principal está implementada usando la biblioteca estándar de Python.

Dependencias de prueba (incluidas en requirements.txt):

  • pytest - Marco de pruebas
  • pytest-asyncio - Soporte de pruebas asíncronas
  • pytest-cov - Informes de cobertura de código

Herramientas de desarrollo opcionales (instala por separado si es necesario):

# Code formatting
pip install black isort

# Linting
pip install flake8 pylint mypy

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

Ejecución Local

# 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

Formatea tu código antes de confirmar:

# 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

Ejecución de Pruebas

# 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

Compila y ejecuta con 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

Variables de Entorno

La puerta de enlace admite la sustitución de variables de entorno en las configuraciones de backend. Configúralas en tu archivo .env:

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

Las variables de entorno referenciadas en config.json usando la sintaxis ${VAR_NAME} se sustituirán automáticamente.

Pruebas

El proyecto incluye pruebas unitarias y de integración exhaustivas.

Ejecución de Pruebas

  1. Instala las dependencias de prueba:

    pip install -r requirements.txt

  2. Ejecuta todas las pruebas:

    pytest

  3. Ejecuta las pruebas con cobertura:

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

  4. Ejecuta módulos de prueba específicos:

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

  5. Ejecuta las pruebas en modo de observación:

    pytest-watch

Licencia

MIT