Puerta de enlace MCP

Licencia

Este proyecto está licenciado bajo la Licencia Pública General GNU v3.0 - consulte el archivo LICENCIA para más detalles.

Descripción general del proyecto

MCP Gateway es una aplicación desarrollada con Python. Actúa como una puerta de enlace central que conecta y agrega capacidades de múltiples servidores MCP backend (ya sea que se comuniquen mediante los protocolos Stdio o SSE). Finalmente, expone estas capacidades agregadas a los clientes MCP ascendentes a través de un punto final SSE unificado ( /sse ).

Ventajas principales:

Configuración de cliente simplificada: los clientes MCP solo necesitan conectarse a la única dirección de MCP Gateway para acceder a las funcionalidades de todos los servicios backend, lo que elimina la necesidad de configurar cada servidor backend individualmente.
Agregación y orquestación de capacidades: agrega herramientas MCP con diversas capacidades de varias fuentes, lo que proporciona una base para crear agentes más potentes y personalizados enfocados en dominios de tareas específicos.

Estructura del archivo del proyecto

.
├── config.json                     # Core configuration file: Defines the backend MCP servers to connect to and manage.
├── main.py                         # Program entry point: Parses command-line arguments, sets up logging, and starts the web server.
├── bridge_app.py                   # Starlette application core: Handles forwarding of MCP requests and SSE connection management.
├── client_manager.py               # Client manager: Responsible for establishing and maintaining connection sessions with backend MCP servers.
├── capability_registry.py          # Capability registry: Dynamically discovers, registers, and manages capabilities provided by all backend MCP servers.
├── config_loader.py                # Configuration loader: Responsible for loading and strictly validating the format and content of the `config.json` file.
├── errors.py                       # Custom exceptions: Defines project-specific error types, such as configuration errors and backend server errors.
├── rich_handler.py                 # Rich logging handler: Provides beautified, structured console log output.
├── servers/                        # Contains built-in/example backend MCP server scripts.
│   ├── bash_server.py              # <-- Built-in Bash command execution tool (Linux/macOS/WSL)
│   ├── cmd_server.py               # <-- Built-in Windows CMD command execution tool (Windows Only)
│   ├── powershell_server.py        # <-- Built-in Windows PowerShell command execution tool (Windows Only)
│   └── wmi_server.py               # <-- Built-in Windows WMI query tool (Windows Only)
└── logs/                           # Log directory: Stores runtime log files (created automatically).

Servidores MCP integrados

Este proyecto viene con cuatro herramientas de servidor MCP de backend que se pueden usar directamente y habilitar en config.json sin configuración adicional:

Herramienta de ejecución de comandos Bash ( bash_server.py ) : ejecuta comandos Bash en entornos Linux, macOS o WSL.
Herramienta de ejecución de comandos CMD de Windows ( cmd_server.py ) : ejecuta comandos CMD en entornos Windows.
Herramienta de ejecución de comandos de Windows PowerShell ( powershell_server.py ) : ejecuta comandos de PowerShell en entornos Windows.
Herramienta de consulta WMI de Windows ( wmi_server.py ) : ejecuta consultas WMI en entornos Windows.

Si encuentra el siguiente error en un entorno Linux:
error: Distribution `pywin32==310 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform>
Desinstale el módulo wmi : uv remove wmi

Instalación y configuración

Este proyecto está escrito en Python. Se recomienda usar uv para la gestión del entorno y las dependencias.

Repositorio de clones
git clone https://github.com/trtyr/MCP-Gateway.git cd MCP-Gateway
Crear y activar un entorno virtual
# Create virtual environment uv venv # Activate virtual environment # Linux/macOS source .venv/bin/activate # Windows (Command Prompt/PowerShell) .venv\Scripts\activate
Instalar dependencias
# Install all required dependencies based on pyproject.toml uv sync

Después de completar estos pasos, el proyecto está listo para ejecutarse.

Inicio rápido

Obtener ayuda con el proyecto

Puede utilizar el argumento -h o --help para ver todas las opciones de inicio disponibles:

# Windows
uv run python .\main.py -h
# Linux/macOS
uv run python ./main.py -h

La salida será similar a esto:

usage: main.py [-h] [--host HOST] [--port PORT] [--log-level {debug,info,warning,error,critical}]

Start MCP_Bridge_Server v3.0.0

options:
  -h, --help            show this help message and exit
  --host HOST           Host address (default: 0.0.0.0)
  --port PORT           Port (default: 9000)
  --log-level {debug,info,warning,error,critical}
                        Set file logging level (default: info)

Iniciar el proyecto

Utilice uv run python main.py para iniciar el servidor. Puede especificar el host , port y log-level :

# Listen on all network interfaces on port 9000, set log level to debug
uv run python .\main.py --host 0.0.0.0 --port 9000 --log-level debug

Después de iniciar, verá una salida de consola mejorada y enriquecida similar a la imagen a continuación, que muestra el estado del servidor, la información de conexión y las herramientas cargadas:

Conexión de cliente MCP

Después de iniciar MCP Gateway, puede usar cualquier cliente compatible con MCP (como Cline, Cursor, Claude Desktop o un cliente personalizado) para conectarse al punto final SSE proporcionado por Gateway.

La dirección predeterminada es http://<Server_IP_Address>:9000/sse (si se utiliza el puerto predeterminado).

Ejemplo (usando ChatWise Connect):

Seleccione el tipo de conexión SSE .
Introduzca la URL SSE del portal (por ejemplo, http://127.0.0.1:9000/sse ).
Haga clic en Connect .

Después de una conexión exitosa, podrá ver todas las herramientas MCP de backend agregadas a través de Gateway en el cliente:

Registros

Los registros de tiempo de ejecución se guardan automáticamente en la carpeta logs del directorio raíz del proyecto. Los nombres de los archivos de registro incluyen marcas de tiempo y niveles de registro, lo que facilita el seguimiento de problemas.

logs/
├── log_20240801_103000_INFO.log
└── log_20240801_110000_DEBUG.log
...

Archivo de configuración ( `config.json` )

El archivo de configuración principal, config.json se encuentra en el directorio raíz del proyecto. Define los servidores backend de MCP a los que MCP Gateway debe conectarse y administrar.

Cada entrada representa un servidor backend. La clave es el nombre único que se le asigna (este nombre se usará como prefijo para sus funciones) y el valor es un objeto que contiene la configuración del servidor.

Se admiten dos tipos de conexiones de servidor backend:

stdio : se comunica con un proceso de servidor MCP iniciado localmente a través de entrada/salida estándar (stdin/stdout).
sse : se comunica con un servidor MCP remoto o que se ejecuta localmente a través del protocolo de eventos enviados por el servidor (SSE).

Configuración del tipo de Stdio

Adecuado para procesos de servidor MCP locales cuyo ciclo de vida debe ser administrado por el Gateway.

Campos de configuración:

type (obligatorio): debe ser "stdio" .
command (obligatorio): el comando ejecutable utilizado para iniciar el proceso del servidor (por ejemplo, python , uv , node o la ruta absoluta a un script/ejecutable).
args (obligatorio): una lista de argumentos (lista de cadenas) pasadas al command .
env (opcional): Un diccionario de variables de entorno (Dict[str, str]) que se configurará para el proceso hijo. Si se omite, el proceso hijo hereda el entorno de la puerta de enlace.

Ejemplo:

{
  "powershell": {
    "type": "stdio",
    "command": "python",
    "args": ["servers/powershell_server.py"]
  },
  "my_custom_tool": {
    "type": "stdio",
    "command": "/path/to/my/custom_mcp_server",
    "args": ["--port", "ignored_for_stdio", "--some-flag"],
    "env": {
      "API_KEY": "your_secret_key"
    }
  }
}

Cómo funciona: Al iniciarse MCP Gateway, utiliza el command y args especificados (junto con env opcional) para iniciar un proceso secundario. Gateway se comunica con el servidor MCP backend mediante la entrada y salida estándar de este proceso secundario. Al cerrarse, Gateway intenta finalizar estos procesos secundarios.

Configuración del tipo SSE

Adecuado para conectarse a servidores MCP que ya están en ejecución (locales o remotos) o casos en los que el Gateway necesita iniciar un proceso de servidor SSE local antes de conectarse.

Campos de configuración:

type (obligatorio): Debe ser "sse" .
url (obligatorio): la URL del punto final SSE del servidor MCP backend (dirección HTTP/HTTPS completa).
command (opcional): si se especifica, el Gateway ejecutará este comando al inicio para iniciar el servidor SSE local.
args (opcional, solo cuando se especifica command ): una lista de argumentos pasados al command .
env (opcional, solo cuando se especifica command ): variables de entorno para configurar para el proceso secundario iniciado localmente.

Ejemplo 1: Conexión a un servidor SSE remoto que ya está en ejecución

{
  "remote_search_service": {
    "type": "sse",
    "url": "https://mcp.example.com/search/sse"
  }
}

Ejemplo 2: Gateway inicia un servidor SSE local y se conecta

{
  "local_sse_server": {
    "type": "sse",
    "url": "http://127.0.0.1:8080/sse",
    "command": "uv",
    "args": ["run", "python", "servers/my_local_sse_app.py", "--port", "8080"],
    "env": { "MODE": "production" }
  }
}

Cómo funciona:

Sólo se proporciona url : la puerta de enlace intenta conectarse directamente a la url especificada.
url , command , args proporcionados : La puerta de enlace primero usa command y args para iniciar un proceso local (esperando que este proceso escuche en la dirección y el puerto correspondientes a url ). Luego espera un breve periodo ( LOCAL_SSE_STARTUP_DELAY definido en client_manager.py ) antes de intentar conectarse a la url . Cuando la puerta de enlace se apaga, intenta finalizar este proceso local.

Ejemplos de adición de configuración

A continuación se muestran ejemplos de cómo agregar servidores MCP de terceros a config.json .

Ejemplo de Stdio: Dramaturgo MCP

Supongamos que desea integrar el servidor MCP de Playwright ( @playwright/mcp ).

Método de inicio : Playwright MCP se inicia normalmente con npx @playwright/mcp@latest . Este es un paquete Node.js que se ejecuta mediante npx .
Configurar config.json :
{ // ... other server configurations ... "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] } // ... other server configurations ... }
Aquí, command es npx y args contiene el nombre y la versión del paquete Playwright MCP.
Reiniciar puerta de enlace : guarde config.json y reinicie MCP Gateway.

Después de iniciar, debería ver herramientas llamadas playwright/... (por ejemplo, playwright/browse ) en los registros de la consola y en su cliente.

Ejemplo de SSE: ENScan_GO (Inicio local)

Supongamos que desea integrar ENScan_GO, un programa Go que puede iniciarse con ./enscan --mcp y proporciona un servicio SSE en http://localhost:8080 .

Obtener el archivo ejecutable : descargue el ejecutable ENScan_GO (por ejemplo, enscan-v1.2.1-windows-amd64.exe ) y colóquelo en una ubicación accesible (por ejemplo, el directorio servers/ o en la RUTA de su sistema).
Configurar config.json :
{ // ... other server configurations ... "enscan": { "type": "sse", "url": "http://127.0.0.1:8080/sse", // Address ENScan_GO listens on // Note: Ensure path separators are correct on Windows, or use an absolute path "command": "servers/enscan-v1.2.1-windows-amd64.exe", // Path to the executable "args": ["--mcp"] // Startup arguments } // ... other server configurations ... }
Aquí, especificamos type como sse , proporcionamos la url que escucha y usamos command y args para indicarle al Gateway cómo iniciar este servidor SSE local.
Reiniciar puerta de enlace : guarde config.json y reinicie MCP Gateway.

La puerta de enlace iniciará primero el proceso ENScan_GO y luego se conectará a http://127.0.0.1:8080/sse . Tras el inicio, debería ver la herramienta enscan/...

MCP-Gateway

Integrations