MCP Context Forge – Detaillierte Projektbeschreibung

Projektübersicht

MCP Context Forge ist ein von IBM Open Source entwickeltes, funktionsreiches, FastAPI-gestütztes Modellkontextprotokoll (MCP)-Gateway, das Tools, Ressourcen, Prompts, Server und Peer-Gateways vereinheitlicht und zusammenführt, um jede REST-API als MCP-konformes Tool oder virtuellen Server zu verpacken. Das Projekt unterstützt die Bereitstellung aller Funktionen über HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE) und stdio-Übertragungsprotokolle und bietet eine umfangreiche interaktive Verwaltungs-UI, die als Container verpackt ist und jede von SQLAlchemy unterstützte Datenbank unterstützt.

Kernfunktionen

1. Protokoll-Gateway-Funktionen

• Echte Gateway-Architektur: Zentralisierte Registrierungsstelle für Tools, Ressourcen und Prompts unter Beibehaltung des offiziellen MCP 2025-03-26 Protokollstandards
• Multi-Server-Föderation: Vereinheitlichung mehrerer MCP-Server zu einem einzigen Endpunkt – automatische Erkennung von Peer-Knoten (mDNS oder explizite Konfiguration), Zustandsprüfungen und Zusammenführung ihrer Funktionen
• Virtualisierung von Diensten: Virtualisierung von Nicht-MCP-Diensten als "virtuelle Server", wobei jede REST-API oder jeder Funktionsendpunkt registriert und unter MCP-Semantik bereitgestellt werden kann

2. API-Adaptionsfunktionen

• REST-zu-MCP-Adapter: Anpassung beliebiger REST/HTTP-APIs an MCP-Tools, Unterstützung von JSON-Schema-Eingabevalidierung, Wiederholungs-/Ratenbegrenzungsrichtlinien und transparenten JSON-RPC-Aufrufen
• Protokollkonvertierung: Unterstützung der Konvertierung zwischen verschiedenen Übertragungsprotokollen (stdio, SSE, Streamable HTTP)

3. Bereitstellung und Verwaltung

• Vollständige Verwaltungs-UI: Bietet umfangreiche Übertragungsprotokolle, vorgefertigte Entwicklungserlebnis-Pipelines und produktionsreife Beobachtbarkeit
• Funktionen der Enterprise-Klasse: Umfasst vollständige Funktionen wie Authentifizierung und Autorisierung, Caching, Zustandsprüfungen, Metrikerfassung usw.

Systemarchitektur

Das Projekt verwendet eine modulare Architektur:

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 Authentifizierung │
│  Verwaltungsoberfläche │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 MCP Gateway Kern    │
    │     Protokollinitialisierung abgeschlossen │
    │        Föderationsmanager      │
    │   Übertragungsprotokolle HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           Service-Schicht       │
    │  🧰 Tool-Service  📁 Ressourcen-Service      │
    │  📝 Prompt-Service  🧩 Server-Service    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          Persistenz-Schicht      │
    │    💾 Datenbank SQLAlchemy       │
    │    ⚡ Cache Redis/Memory       │
    └───────────────────────────────┘

Technische Eigenschaften

Unterstützte Protokolle und Übertragungen

• Vollständige MCP 2025-03-26 Unterstützung: initialize, ping, notify, completion, sampling (SSE) sowie JSON-RPC-Fallback
• Mehrere Übertragungsprotokolle: HTTP/JSON-RPC, WebSocket (ping/pong), SSE (unidirektional + Rückkanal), stdio
• Protokollkonvertierung: Unterstützung der nahtlosen Konvertierung zwischen verschiedenen Übertragungsprotokollen

Föderation und Erkennung

• Automatische Erkennung: Unterstützung von mDNS oder explizit konfigurierter Peer-Gateway-Erkennung
• Zustandsprüfungen: Regelmäßige Zustandsprüfungen zur Unterstützung des Failover
• Transparente Zusammenführung: Transparente Zusammenführung von Remote-Registrierungen in einem einheitlichen Verzeichnis

Ressourcenverwaltung

• Templatisierte URIs: Unterstützung parametrisierter Ressourcen-URIs
• Intelligentes Caching: LRU+TTL-Caching-Mechanismus, MIME-Typ-Erkennung
• Echtzeit-Abonnement: Unterstützung von SSE-Echtzeit-Abonnements für Ressourcenänderungen

Prompt-Verwaltung

• Jinja2-Vorlagen: Leistungsstarke Vorlagen-Engine-Unterstützung
• Schema-Validierung: JSON-Schema-basierte Validierung
• Multimodale Unterstützung: Unterstützung multimodaler Inhaltsblöcke
• Versionskontrolle: Versionsverwaltung und Rollback-Funktionen

Tool-Verwaltung

• Unterstützung mehrerer Typen: Native MCP- oder REST-basierte Tools
• Eingabevalidierung: Vollständiger Eingabevalidierungsmechanismus
• Wiederholungslogik: Intelligente Wiederholungs- und Ratenbegrenzungs-/Concurrency-Kontrolle

Verwaltungs- und Überwachungsfunktionen

Web-Verwaltungsoberfläche

• Technologie-Stack: HTMX + Alpine.js + Tailwind CSS
• Vollständiges CRUD: Vollständige Verwaltung von Servern, Tools, Ressourcen, Prompts, Gateways, Stammverzeichnissen und Metriken
• Echtzeitüberwachung: Echtzeit-Statusüberwachung und Protokollanzeige

Authentifizierung und Autorisierung

• Mehrere Authentifizierungsmethoden: Basic-Authentifizierung, JWT Bearer, benutzerdefinierte Header-Authentifizierung
• Feingranulare Steuerung: Abhängigkeitsinjektionssteuerung für jeden Endpunkt
• Sichere Verschlüsselung: AES-verschlüsselte Speicherung von Tool-Authentifizierungsheadern

Persistenz und Migration

• ORM-Unterstützung: Asynchrones SQLAlchemy ORM (SQLite, PostgreSQL, MySQL usw.)
• Automatische Migration: Alembic automatische Datenbankmigration
• Verbindungspool: Vollständige Datenbankverbindungspoolkonfiguration

Ereignissystem und Beobachtbarkeit

• Einheitliche Ereignisse: Einheitliche Ereignisverpackung für WS/SSE-Fanout
• Serverseitige Filterung: Serverseitige Ereignisfilterung und Rückruf-Hooks
• Strukturierte Protokollierung: Strukturierte JSON-Protokollierung
• Zustandsprüfung: /health-Endpunkt und Latenzmetrik-Dekorator
• Vollständige Metriken: Metrikerfassung für jeden Handler

Entwicklungserlebnis

Entwicklungstools

• Makefile-Ziele: Über 100 vordefinierte Entwicklungsziele
• Codequalität: Pre-commit Hooks (ruff, black, mypy, isort)
• Live-Neuladen: Entwicklungsserver unterstützt Live-Neuladen
• Testabdeckung: 400+ Testfälle
• CI/CD: Vollständige CI-Badges und automatisierte Prozesse

Bereitstellungsoptionen

• Containerisierte Bereitstellung: Docker/Podman-Unterstützung
• Cloud-nativ: IBM Cloud Code Engine-Bereitstellungsunterstützung
• Mehrere Umgebungen: Entwicklungs-, Test-, Produktionsumgebungskonfiguration
• SSL/TLS: Vollständige HTTPS-Unterstützung

Konfigurationsoptionen

Basiskonfiguration

# Anwendungsgrundkonfiguration
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # Optionales Unterpfadpräfix

Authentifizierungskonfiguration

# Basic-Authentifizierung (Verwaltungsoberfläche und API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# JWT-Konfiguration
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # Minuten

# Authentifizierungskontrolle
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

Föderationskonfiguration

# Föderationsfunktionen
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

Schnellstart

Ausführen mit Docker

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-secret-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:latest

Lokale Entwicklung

# Virtuelle Umgebung erstellen und Abhängigkeiten installieren
make venv install serve

# Oder manuell installieren
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444

Authentifizierungstoken generieren

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)

API-Nutzungsbeispiele

Protokollinitialisierung

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "protocol_version":"2025-03-26",
    "capabilities":{},
    "client_info":{"name":"MyClient","version":"1.0.0"}
  }' \
  http://localhost:4444/protocol/initialize

Tool registrieren

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"clock_tool",
    "url":"http://localhost:9000/rpc",
    "description":"Returns current time",
    "input_schema":{
      "type":"object",
      "properties":{"timezone":{"type":"string"}},
      "required":[]
    }
  }' \
  http://localhost:4444/tools

Prompt-Vorlage erstellen

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"greet",
    "template":"Hello, {{ user }}!",
    "argument_schema":{
      "type":"object",
      "properties":{"user":{"type":"string"}},
      "required":["user"]
    }
  }' \
  http://localhost:4444/prompts

Bereitstellung in IBM Cloud Code Engine

Das Projekt bietet vollständige IBM Cloud Code Engine-Bereitstellungsunterstützung:

Umgebungskonfiguration

IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_API_KEY=your_api_key_here

Bereitstellungsbefehle

make ibmcloud-check-env      # Umgebungsvariablen prüfen
make ibmcloud-cli-install    # IBM Cloud CLI installieren
make ibmcloud-login          # In IBM Cloud anmelden
make ibmcloud-ce-login       # Code Engine-Projekt auswählen
make ibmcloud-tag            # Container-Image taggen
make ibmcloud-push           # In IBM Container Registry pushen
make ibmcloud-deploy         # In Code Engine bereitstellen

Projektstruktur

mcpgateway/
├── admin.py                    # FastAPI-Routen und Verwaltungs-UI-Controller
├── cache/
│   └── resource_cache.py      # Speicher-LRU+TTL-Cache für Ressourcen
├── config.py                  # Pydantic-Einstellungslader
├── db.py                      # SQLAlchemy ORM-Modelle und Datenbankeinstellungen
├── federation/
│   ├── discovery.py           # Peer-Gateway-Erkennung
│   ├── forward.py             # RPC-Weiterleitungslogik
│   └── manager.py             # Föderationskoordination und Zustandsprüfung
├── handlers/
│   └── sampling.py            # MCP-Streaming-Sampling-Request-Handler
├── services/
│   ├── completion_service.py  # Prompt- und Ressourcenparameter-Vervollständigungslogik
│   ├── gateway_service.py     # Peer-Gateway-Registrierung und -Verwaltung
│   ├── prompt_service.py      # Prompt-Vorlagen CRUD und Rendering
│   ├── resource_service.py    # Ressourcenregistrierung, -Abruf, -Abonnement
│   ├── server_service.py      # Serverregistrierung und -Zustandsüberwachung
│   └── tool_service.py        # Tool-Registrierung, -Aufruf, -Metriken
├── transports/
│   ├── sse_transport.py       # Server-Sent Events-Übertragung
│   ├── stdio_transport.py     # stdio-Übertragung
│   └── websocket_transport.py # WebSocket-Übertragung
└── utils/
    ├── create_jwt_token.py    # JWT-Generierungs- und -Prüfungstool
    └── verify_credentials.py # FastAPI-Authentifizierungsabhängigkeit

Entwicklung und Beitrag

Entwicklungsumgebung einrichten

# Entwicklungsabhängigkeiten installieren
make install-dev

# Code-Prüfung ausführen
make lint

# Tests ausführen
make test

# Abdeckungstests ausführen
make coverage

Codequalitätswerkzeuge

Das Projekt integriert verschiedene Codequalitätswerkzeuge:

• Formatierung: black, isort, autoflake
• Statische Analyse: mypy, pylint, pyright, pyre
• Sicherheitsprüfung: bandit, pip-audit
• Komplexitätsanalyse: radon, wily
• Abhängigkeitsprüfung: fawltydeps, pip-licenses

Zusammenfassung

MCP Context Forge ist eine funktionsreiche, produktionsreife Modellkontextprotokoll-Gateway-Lösung, die sich besonders für die Tool-Integration und -Verwaltung von LLM-Anwendungen der Enterprise-Klasse eignet. Es implementiert nicht nur die vollständigen Funktionen des MCP-Protokolls, sondern bietet auch umfangreiche Erweiterungsfunktionen wie Föderationserkennung, Protokollkonvertierung, Virtualisierungsdienste usw. und ist somit eine ideale Infrastrukturkomponente für den Aufbau komplexer KI-Anwendungsökosysteme.