MCP-Gateway

Englisch |简体中文

Lizenz

Dieses Projekt ist unter der GNU General Public License v3.0 lizenziert – weitere Einzelheiten finden Sie in der Datei LICENSE .

Related MCP server: Maya MCP

Projektübersicht

MCP Gateway ist eine mit Python erstellte Anwendung. Es fungiert als zentrales Gateway , das Verbindungen zu mehreren MCP-Backend-Servern herstellt und deren Funktionen aggregiert (unabhängig davon, ob diese über Stdio- oder SSE-Protokolle kommunizieren). Diese aggregierten Funktionen werden schließlich über einen einheitlichen SSE- Endpunkt ( /sse ) den Upstream-MCP-Clients zur Verfügung gestellt.

Hauptvorteile:

1. Vereinfachte Client-Konfiguration: MCP-Clients müssen sich nur mit der einzigen Adresse des MCP-Gateways verbinden, um auf die Funktionen aller Backend-Dienste zuzugreifen. Dadurch entfällt die Notwendigkeit, jeden Backend-Server einzeln zu konfigurieren.

2. Aggregation und Orchestrierung von Fähigkeiten: Aggregiert MCP-Tools mit unterschiedlichen Fähigkeiten aus verschiedenen Quellen und bietet so eine Grundlage für die Erstellung leistungsfähigerer, maßgeschneiderter Agenten, die sich auf bestimmte Aufgabenbereiche konzentrieren.

Projektdateistruktur

.
├── 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).

Integrierte MCP-Server

Dieses Projekt enthält vier Backend-MCP-Server-Tools, die direkt verwendet und ohne zusätzliche Konfiguration in config.json aktiviert werden können:

• Bash-Befehlsausführungstool ( bash_server.py ) : Führt Bash-Befehle in Linux-, macOS- oder WSL-Umgebungen aus.

• Windows CMD Command Execution Tool ( cmd_server.py ) : Führt CMD-Befehle in Windows-Umgebungen aus.

• Windows PowerShell Command Execution Tool ( powershell_server.py ) : Führt PowerShell-Befehle in Windows-Umgebungen aus.

• Windows WMI-Abfragetool ( wmi_server.py ) : Führt WMI-Abfragen in Windows-Umgebungen aus.

Wenn in einer Linux-Umgebung der folgende Fehler auftritt:

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>

Bitte deinstallieren Sie das wmi -Modul: uv remove wmi

Installation und Einrichtung

Dieses Projekt ist in Python geschrieben. Die Verwendung von uv für die Umgebungs- und Abhängigkeitsverwaltung wird empfohlen.

1. Repository klonen

   git clone https://github.com/trtyr/MCP-Gateway.git
   cd MCP-Gateway

2. Erstellen und Aktivieren einer virtuellen Umgebung

   # Create virtual environment
   uv venv
   
   # Activate virtual environment
   # Linux/macOS
   source .venv/bin/activate
   # Windows (Command Prompt/PowerShell)
   .venv\Scripts\activate

3. Abhängigkeiten installieren

   # Install all required dependencies based on pyproject.toml
   uv sync

Nach Abschluss dieser Schritte ist das Projekt betriebsbereit.

Schnellstart

Projekthilfe erhalten

Sie können das Argument -h oder --help verwenden, um alle verfügbaren Startoptionen anzuzeigen:

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

Die Ausgabe sieht ungefähr so aus:

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)

Starten Sie das Projekt

Verwenden Sie uv run python main.py um den Server zu starten. Sie können host , port und log-level angeben:

# 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

Nach dem Start sehen Sie eine aufwendig gestaltete Konsolenausgabe ähnlich der Abbildung unten, die den Serverstatus, Verbindungsinformationen und geladene Tools anzeigt:

MCP-Client-Verbindung

Nach dem Start von MCP Gateway können Sie jeden MCP-kompatiblen Client (z. B. Cline, Cursor, Claude Desktop oder einen benutzerdefinierten Client) verwenden, um eine Verbindung mit dem vom Gateway bereitgestellten SSE-Endpunkt herzustellen.

Die Standardadresse lautet http://<Server_IP_Address>:9000/sse (bei Verwendung des Standardports).

Beispiel (mit ChatWise Connect):

1. Wählen Sie SSE Verbindungstyp.

2. Geben Sie die SSE-URL des Gateways ein (z. B. http://127.0.0.1:9000/sse ).

3. Klicken Sie auf Connect .

Nach einer erfolgreichen Verbindung können Sie alle über das Gateway aggregierten Backend-MCP-Tools im Client sehen:

Protokolle

Laufzeitprotokolle werden automatisch im Ordner logs im Stammverzeichnis des Projekts gespeichert. Die Protokolldateinamen enthalten Zeitstempel und Protokollebenen, sodass Probleme leicht nachverfolgt werden können.

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

Konfigurationsdatei ( config.json )

Die Kernkonfigurationsdatei config.json befindet sich im Stammverzeichnis des Projekts. Sie definiert die Backend-MCP-Server, mit denen sich MCP Gateway verbinden und die es verwalten muss.

Jeder Eintrag stellt einen Backend-Server dar. Der Schlüssel ist der eindeutige Name, den Sie diesem Backend-Server zuweisen (dieser Name wird als Präfix für seine Funktionen verwendet), und der Wert ist ein Objekt, das die Konfiguration des Servers enthält.

Es werden zwei Arten von Backend-Serververbindungen unterstützt:

• stdio : Kommuniziert mit einem lokal gestarteten MCP-Serverprozess über die Standardeingabe/-ausgabe (stdin/stdout).

• sse : Kommuniziert mit einem Remote- oder lokal ausgeführten MCP-Server über das Server-Sent Events (SSE)-Protokoll.

Stdio-Typkonfiguration

Geeignet für lokale MCP-Serverprozesse, deren Lebenszyklus vom Gateway verwaltet werden muss.

Konfigurationsfelder:

• type (erforderlich): Muss "stdio" sein.

• command (erforderlich): Der ausführbare Befehl, der zum Starten des Serverprozesses verwendet wird (z. B. python , uv , node oder der absolute Pfad zu einem Skript/einer ausführbaren Datei).

• args (erforderlich): Eine Liste von Argumenten (Liste von Zeichenfolgen), die an den command übergeben werden.

• env (optional): Ein Wörterbuch mit Umgebungsvariablen (Dict[str, str]), die für den Kindprozess festgelegt werden sollen. Wird diese Variable weggelassen, übernimmt der Kindprozess die Umgebung des Gateways.

Beispiel:

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

Funktionsweise: Beim Start des MCP Gateways werden die angegebenen command und args (sowie optional env ) verwendet, um einen untergeordneten Prozess zu starten. Das Gateway kommuniziert über die Standardeingabe und -ausgabe dieses untergeordneten Prozesses mit dem MCP-Backend-Server. Beim Herunterfahren versucht das Gateway, diese untergeordneten Prozesse zu beenden.

SSE-Typkonfiguration

Geeignet für die Verbindung mit bereits laufenden MCP-Servern (lokal oder remote) oder für Fälle, in denen das Gateway vor der Verbindung einen lokalen SSE-Serverprozess starten muss.

Konfigurationsfelder:

• type (erforderlich): Muss "sse" sein.

• url (erforderlich): Die SSE-Endpunkt-URL des Backend-MCP-Servers (vollständige HTTP/HTTPS-Adresse).

• command (optional): Wenn angegeben, führt das Gateway diesen Befehl beim Start aus, um den lokalen SSE-Server zu starten.

• args (optional, nur wenn command angegeben ist): Eine Liste der an den command übergebenen Argumente.

• env (optional, nur wenn command angegeben ist): Umgebungsvariablen, die für den lokal gestarteten untergeordneten Prozess festgelegt werden sollen.

Beispiel 1: Verbindung zu einem bereits laufenden Remote-SSE-Server herstellen

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

Beispiel 2: Gateway startet einen lokalen SSE-Server und verbindet

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

So funktioniert es:

• Nur angegebene url : Das Gateway versucht direkt, eine Verbindung mit der angegebenen url herzustellen.

• url , command und angegebene args : Das Gateway startet zunächst mit command und args einen lokalen Prozess (erwartet, dass dieser Prozess die Adresse und den Port der url überwacht). Anschließend wartet es kurz ( LOCAL_SSE_STARTUP_DELAY , definiert in client_manager.py ), bevor es versucht, eine Verbindung zur url herzustellen. Beim Herunterfahren des Gateways versucht es, diesen lokalen Prozess zu beenden.

Beispiele für zusätzliche Konfigurationen

Hier sind Beispiele zum Hinzufügen von MCP-Servern von Drittanbietern zu config.json .

Stdio-Beispiel: Playwright MCP

Angenommen, Sie möchten den MCP-Server von Playwright ( @playwright/mcp ) integrieren.

1. Startmethode verstehen : Playwright MCP wird normalerweise mit npx @playwright/mcp@latest gestartet. Dies ist ein Node.js-Paket, das über npx ausgeführt wird.

2. Konfigurieren Sie config.json :

   {
     // ... other server configurations ...
     "playwright": {
       "type": "stdio",
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
     }
     // ... other server configurations ...
   }

   Hier lautet command``npx und args enthält den Namen und die Version des Playwright MCP-Pakets.

3. Gateway neu starten : Speichern Sie config.json und starten Sie MCP Gateway neu.

Nach dem Start sollten Sie in den Konsolenprotokollen und auf Ihrem Client Tools mit dem Namen playwright/... (z. B. playwright/browse ) sehen.

SSE-Beispiel: ENScan_GO (Lokaler Start)

Angenommen, Sie möchten ENScan_GO integrieren, ein Go-Programm, das mit ./enscan --mcp gestartet werden kann und einen SSE-Dienst unter http://localhost:8080 bereitstellt.

1. Ausführbare Datei abrufen : Laden Sie die ausführbare Datei ENScan_GO herunter (z. B. enscan-v1.2.1-windows-amd64.exe ) und platzieren Sie sie an einem zugänglichen Ort (z. B. im Verzeichnis servers/ oder in Ihrem Systempfad).

2. Konfigurieren Sie 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 ...
   }

   Hier geben wir type als sse an, stellen die url bereit, auf der er lauscht, und verwenden command und args , um dem Gateway mitzuteilen, wie dieser lokale SSE-Server gestartet werden soll.

3. Gateway neu starten : Speichern Sie config.json und starten Sie MCP Gateway neu.

Das Gateway startet zunächst den ENScan_GO-Prozess und stellt dann eine Verbindung zu http://127.0.0.1:8080/sse her. Nach dem Start sollten Tools mit dem Namen enscan/... angezeigt werden.