Présentation détaillée du projet MCP Context Forge

Aperçu du projet

MCP Context Forge est une passerelle de protocole de contexte de modèle (MCP) riche en fonctionnalités, pilotée par FastAPI et open source d'IBM. Elle unifie et fédère les outils, les ressources, les invites, les serveurs et les passerelles homologues, en encapsulant n'importe quelle API REST en tant qu'outil ou serveur virtuel conforme à la norme MCP. Le projet prend en charge la publication de toutes les fonctionnalités via les protocoles de transport HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE) et stdio, et fournit une interface utilisateur d'administration interactive riche, empaquetée sous forme de conteneur, prenant en charge toute base de données compatible SQLAlchemy.

Fonctionnalités principales

1. Fonctionnalités de la passerelle de protocole

• Véritable architecture de passerelle : Centre d'enregistrement centralisé pour les outils, les ressources et les invites, tout en respectant la norme de protocole MCP 2025-03-26 officielle.
• Fédération multi-serveurs : Unifie plusieurs serveurs MCP en un seul point de terminaison - découverte automatique des nœuds homologues (mDNS ou configuration explicite), vérification de l'état et fusion de leurs fonctionnalités.
• Services virtualisés : Virtualise les services non-MCP en "serveurs virtuels", permettant d'enregistrer n'importe quelle API REST ou point de terminaison de fonction et de les exposer sous la sémantique MCP.

2. Fonctionnalités d'adaptation d'API

• Adaptateur REST vers MCP : Adapte n'importe quelle API REST/HTTP en outil MCP, prenant en charge la validation des entrées JSON-Schema, les stratégies de nouvelle tentative/limitation de débit et les appels JSON-RPC transparents.
• Conversion de protocole : Prend en charge la conversion entre plusieurs protocoles de transport (stdio, SSE, HTTP flux).

3. Déploiement et gestion

• Interface utilisateur d'administration complète : Fournit des protocoles de transport riches, des pipelines d'expérience de développement pré-construits et une observabilité de niveau production.
• Fonctionnalités de niveau entreprise : Comprend l'authentification et l'autorisation, la mise en cache, les vérifications de l'état, la collecte de métriques et d'autres fonctionnalités complètes.

Architecture du système

Le projet adopte une architecture modulaire :

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 Authentification et autorisation      │
│  Interface d'administration        │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 Noyau de la passerelle MCP        │
    │     Initialisation du protocole Ping terminée      │
    │        Gestionnaire de fédération              │
    │   Protocoles de transport HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           Couche de service               │
    │  🧰 Service d'outils  📁 Service de ressources      │
    │  📝 Service d'invites  🧩 Service de serveurs    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          Couche de persistance              │
    │    💾 Base de données SQLAlchemy       │
    │    ⚡ Cache Redis/Memory       │
    └───────────────────────────────┘

Caractéristiques techniques

Protocoles et transports pris en charge

• Prise en charge complète de MCP 2025-03-26 : initialize, ping, notify, completion, sampling (SSE), et repli JSON-RPC.
• Protocoles de transport multiples : HTTP/JSON-RPC, WebSocket (ping/pong), SSE (unidirectionnel + canal de retour), stdio.
• Conversion de protocole : Prend en charge la conversion transparente entre différents protocoles de transport.

Fédération et découverte

• Découverte automatique : Prend en charge la découverte de passerelles homologues via mDNS ou configuration explicite.
• Vérification de l'état : Vérifications de l'état régulières, prenant en charge le basculement.
• Fusion transparente : Fusion transparente des registres distants dans un catalogue unifié.

Gestion des ressources

• URI modélisés : Prend en charge les URI de ressources paramétrés.
• Cache intelligent : Mécanisme de cache LRU+TTL, détection du type MIME.
• Abonnement en temps réel : Prend en charge l'abonnement en temps réel aux modifications de ressources via SSE.

Gestion des invites

• Modèles Jinja2 : Prise en charge d'un moteur de modèles puissant.
• Validation de schéma : Validation forcée de JSON-Schema.
• Prise en charge multimodale : Prend en charge les blocs de contenu multimodaux.
• Contrôle de version : Gestion des versions et fonctionnalités de restauration.

Gestion des outils

• Prise en charge de plusieurs types : MCP natif ou outils basés sur REST.
• Validation des entrées : Mécanisme de validation des entrées complet.
• Logique de nouvelle tentative : Nouvelle tentative intelligente et limitation de débit/contrôle de la concurrence.

Fonctionnalités de gestion et de surveillance

Interface d'administration Web

• Pile technologique : HTMX + Alpine.js + Tailwind CSS
• CRUD complet : Gestion complète des serveurs, des outils, des ressources, des invites, des passerelles, des répertoires racine et des métriques.
• Surveillance en temps réel : Surveillance de l'état en temps réel et visualisation des journaux.

Authentification et autorisation

• Plusieurs méthodes d'authentification : Authentification Basic, JWT Bearer, authentification d'en-tête personnalisée.
• Contrôle précis : Contrôle de l'injection de dépendances pour chaque point de terminaison.
• Chiffrement sécurisé : Stockage chiffré AES des en-têtes d'authentification des outils.

Persistance et migration

• Prise en charge ORM : ORM SQLAlchemy asynchrone (SQLite, PostgreSQL, MySQL, etc.).
• Migration automatique : Migration automatique de la base de données Alembic.
• Pool de connexions : Configuration complète du pool de connexions de la base de données.

Système d'événements et observabilité

• Événements unifiés : Encapsulation d'événements unifiés pour la diffusion WS/SSE.
• Filtrage côté serveur : Filtrage des événements côté serveur et hooks de rappel.
• Journalisation structurée : Enregistrement des journaux JSON structurés.
• Vérification de l'état : Point de terminaison /health et décorateur de métriques de latence.
• Métriques complètes : Collecte de métriques pour chaque gestionnaire.

Expérience de développement

Outils de développement

• Cibles Makefile : Plus de 100 cibles de développement prédéfinies.
• Qualité du code : Hooks pre-commit (ruff, black, mypy, isort).
• Rechargement en temps réel : Le serveur de développement prend en charge le rechargement en temps réel.
• Couverture des tests : Plus de 400 cas de test.
• CI/CD : Badges CI complets et processus automatisés.

Options de déploiement

• Déploiement conteneurisé : Prise en charge de Docker/Podman.
• Cloud natif : Prise en charge du déploiement IBM Cloud Code Engine.
• Environnements multiples : Configuration des environnements de développement, de test et de production.
• SSL/TLS : Prise en charge HTTPS complète.

Options de configuration

Configuration de base

# Configuration de base de l'application
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # Préfixe de sous-chemin facultatif

Configuration de l'authentification

# Authentification Basic (interface d'administration et API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# Configuration JWT
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # Minutes

# Contrôle de l'authentification
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

Configuration de la fédération

# Fonctionnalité de fédération
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

Démarrage rapide

Exécution avec 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

Développement local

# Créer un environnement virtuel et installer les dépendances
make venv install serve

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

Générer un jeton d'authentification

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

Exemples d'utilisation de l'API

Initialisation du protocole

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

Enregistrer un outil

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

Créer un modèle d'invite

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

Déploiement sur IBM Cloud Code Engine

Le projet offre une prise en charge complète du déploiement IBM Cloud Code Engine :

Configuration de l'environnement

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

Commandes de déploiement

make ibmcloud-check-env      # Vérifier les variables d'environnement
make ibmcloud-cli-install    # Installer IBM Cloud CLI
make ibmcloud-login          # Se connecter à IBM Cloud
make ibmcloud-ce-login       # Sélectionner le projet Code Engine
make ibmcloud-tag            # Étiqueter l'image du conteneur
make ibmcloud-push           # Pousser vers IBM Container Registry
make ibmcloud-deploy         # Déployer sur Code Engine

Structure du projet

mcpgateway/
├── admin.py                    # Routes FastAPI et contrôleur de l'interface d'administration
├── cache/
│   └── resource_cache.py      # Cache LRU+TTL en mémoire des ressources
├── config.py                  # Chargeur de paramètres Pydantic
├── db.py                      # Modèles SQLAlchemy ORM et configuration de la base de données
├── federation/
│   ├── discovery.py           # Découverte des passerelles homologues
│   ├── forward.py             # Logique de transfert RPC
│   └── manager.py             # Coordination de la fédération et vérification de l'état
├── handlers/
│   └── sampling.py            # Gestionnaire des requêtes d'échantillonnage en flux MCP
├── services/
│   ├── completion_service.py  # Logique de complétion des paramètres d'invites et de ressources
│   ├── gateway_service.py     # Enregistrement et gestion des passerelles homologues
│   ├── prompt_service.py      # CRUD et rendu des modèles d'invites
│   ├── resource_service.py    # Enregistrement, récupération et abonnement aux ressources
│   ├── server_service.py      # Enregistrement des serveurs et surveillance de l'état
│   └── tool_service.py        # Enregistrement, appel et métriques des outils
├── transports/
│   ├── sse_transport.py       # Transport Server-Sent Events
│   ├── stdio_transport.py     # Transport stdio
│   └── websocket_transport.py # Transport WebSocket
└── utils/
    ├── create_jwt_token.py    # Outil de génération et de vérification JWT
    └── verify_credentials.py # Dépendance d'authentification FastAPI

Développement et contribution

Configuration de l'environnement de développement

# Installer les dépendances de développement
make install-dev

# Exécuter les vérifications de code
make lint

# Exécuter les tests
make test

# Exécuter les tests de couverture
make coverage

Outils de qualité du code

Le projet intègre plusieurs outils de qualité du code :

• Formatage : black, isort, autoflake
• Analyse statique : mypy, pylint, pyright, pyre
• Analyse de sécurité : bandit, pip-audit
• Analyse de complexité : radon, wily
• Vérification des dépendances : fawltydeps, pip-licenses

Conclusion

MCP Context Forge est une solution de passerelle de protocole de contexte de modèle complète et prête pour la production, particulièrement adaptée aux besoins d'intégration et de gestion des outils des applications LLM de niveau entreprise. Il implémente non seulement les fonctionnalités complètes du protocole MCP, mais fournit également de riches fonctionnalités d'extension, telles que la découverte de fédération, la conversion de protocole, les services de virtualisation, etc., ce qui en fait un composant d'infrastructure idéal pour la construction d'écosystèmes d'applications d'IA complexes.