MELODI MCP Server (melodi_mcp_server)

Serveur indépendant implémentant le protocole standardisé Model Context Protocol (MCP) pour MELODI ERP.
Cette application agit comme une passerelle d'adaptation sécurisée et dynamique entre les clients MCP (assistants IA, Claude Desktop, Cursor, agents autonomes) et l'API interne du module melodi_mcp de l'ERP.

📑 Sommaire

1. Architecture & Principes d'Isolation

2. Spécification du Contrat Interne MELODI (v1)

3. Prérequis & Installation

4. Configuration

5. Démarrage & Transports (STDIO, HTTP & Docker)

6. Console d'Administration Web (/admin)

7. Cycle de Vie & Synchronisation Dynamique

8. Sécurité & Confidentialité

9. Connexion avec un Client MCP (ex: Claude Desktop)

10. Tests Automatisés

11. Limites Connues & Perspectives

Related MCP server: contextboundary-gw

1. Architecture & Principes d'Isolation

melodi_mcp_server est entièrement découplé du code applicatif interne de MELODI :

• Aucun import des modules métier de MELODI ERP.

• Aucun accès direct à la base de données ERP.

• Rôle d'adaptateur pur : découverte de catalogue, conversion de schémas vers le format MCP, validation locale et dispatch des requêtes sécurisées avec injection d'identifiant de corrélation (X-Correlation-ID).

┌───────────────────────────────────────┐
│     Client MCP (Claude, Agent IA)     │
└───────────────────┬───────────────────┘
                    │  STDIO ou HTTP/SSE (JSON-RPC)
┌───────────────────▼───────────────────┐
│           melodi_mcp_server           │
│  - mcp_server.py (SDK MCP 2.x)        │
│  - tool_registry.py (Catalogue dyn.)  │
│  - tool_dispatcher.py (Validation)    │
│  - admin/ (Console Web autonome)      │
└───────────────────┬───────────────────┘
                    │  HTTP/REST sécurisé (Bearer / Correlation ID)
┌───────────────────▼───────────────────┐
│          MELODI ERP (melodi_mcp)      │
│  - /api/melodi_mcp/internal/health    │
│  - /api/melodi_mcp/internal/manifest  │
│  - /api/melodi_mcp/internal/tools     │
│  - /api/melodi_mcp/internal/tools/... │
└───────────────────────────────────────┘

2. Spécification du Contrat Interne MELODI (v1)

Le serveur communique avec l'instance MELODI ERP via une API REST sécurisée. Le préfixe d'accès (MELODI_API_PREFIX) est configurable (par défaut /api/melodi_mcp/internal, mais peut être configuré par exemple sur /internal/mcp ou /api/v1/mcp).

En-têtes obligatoires & contextuels

• Authorization: Bearer <MELODI_API_KEY> (ou X-Melodi-Service-Token: <TOKEN>)

• X-Correlation-ID: <UUID> : Identifiant de traçabilité unique généré par appel.

• X-Melodi-User-ID: <USER_ID> (facultatif) : Identité de l'utilisateur délégué si authentifié.

Routes requises côté MELODI

3. Prérequis & Installation

Prérequis

• Python 3.10 ou supérieur (testé et validé sous Python 3.12).

• pip ou un gestionnaire d'environnement virtuel standard.

Installation

# 1. Naviguer dans le dossier du projet
cd melodi_mcp_server

# 2. Créer l'environnement virtuel
python3 -m venv venv
source venv/bin/activate

# 3. Installer le paquet en mode éditable avec ses dépendances
pip install --upgrade pip
pip install -e ".[dev]"

4. Configuration

Copiez le fichier .env.example vers .env et adaptez les variables :

cp .env.example .env

5. Démarrage & Transports (STDIO & HTTP)

Mode 1 : STDIO (Usage local avec Claude Desktop / CLI)

En mode stdio, le flux JSON-RPC transite exclusivement sur l'entrée/sortie standard (stdin/stdout). Tous les logs de diagnostic sont strictement redirigés vers stderr pour ne jamais corrompre le protocole.

# Démarrage direct via la commande de script
melodi-mcp-server --transport stdio

# Ou via le binaire Python :
./venv/bin/python -m melodi_mcp_server.main --transport stdio

Mode 2 : HTTP / SSE & Console d'Administration

Idéal pour les déploiements locaux ou sur serveur dédié.

melodi-mcp-server --transport http --host 0.0.0.0 --port 8765

Endpoints exposés en mode HTTP :

• /sse ou /mcp : Endpoint de streaming MCP pour les clients distants.

• /health : Bilan de santé opérationnel (JSON).

• /admin : Console d'administration web responsive.

Mode 3 : Déploiement Conteneurisé avec Docker & Docker Compose

Un Dockerfile multi-stage (léger, sécurisé avec utilisateur non-root appuser et healthcheck intégré) ainsi qu'un fichier docker-compose.yml sont fournis pour un déploiement instantané.

1. Lancement avec Docker Compose :

# Démarrer le serveur en tâche de fond (port 8765)
docker compose up -d

# Consulter les journaux en direct
docker compose logs -f melodi-mcp-server

# Vérifier l'état de santé du conteneur
docker compose ps

# Arrêter les services
docker compose down

2. Utilisation de l'Agent interactif avec Docker :

Pour lancer l'agent CLI interactif directement au sein d'un conteneur relié au serveur :

docker compose run --rm agent

3. Construction et exécution manuelle avec Docker :

# Construire l'image
docker build -t melodi-mcp-server .

# Lancer le conteneur
docker run -d \
  --name melodi-mcp-server \
  -p 8765:8765 \
  -e MELODI_BASE_URL="http://host.docker.internal:8000" \
  -e MELODI_API_KEY="votre_cle_secrete_melodi" \
  melodi-mcp-server

6. Console d'Administration Web (/admin)

La console d'administration web intégrée est 100% autonome (HTML, CSS et JS embarqués sans aucune dépendance externe CDN, opérationnelle en réseau isolé ou air-gapped).

Accessible par défaut sur : http://localhost:8765/admin

Fonctionnalités disponibles

1. Statut & Métriques temps réel : Uptime, état de liaison avec MELODI ERP, latence mesurée en millisecondes, total des requêtes, taux de succès.

2. Explorateur d'Outils dynamique : Tableau interactif avec recherche temps réel, distinction lecture/écriture, timeout et inspecteur de schéma JSON Schema.

3. Synchronisation à chaud (Force Sync) : Bouton d'action pour rafraîchir immédiatement le catalogue depuis MELODI sans redémarrage.

4. Historique des appels récents : Journal d'activité avec durée d'exécution, statut et identifiants de corrélation (avec masquage des secrets).

5. Protection optionnelle : Verrouillage possible par clé d'API via ADMIN_API_KEY.

7. Cycle de Vie & Synchronisation Dynamique

• Démarrage tolérant aux pannes : Si MELODI ERP est temporairement indisponible au boot, le serveur démarre en état DEGRADED et tente une reconnexion périodique sans planter.

• Suivi des révisions (catalog_revision) : Le serveur compare la révision renvoyée par MELODI pour éviter tout parsing superflu si les définitions n'ont pas changé.

• Remplacement atomique : Lors d'une mise à jour de catalogue, le registre en mémoire est remplacé atomiquement sous verrou asynchrone (asyncio.Lock), garantissant qu'aucun client ne voie un catalogue partiel.

• Fermeture propre (Graceful Shutdown) : Libération immédiate des tâches de fond et fermeture du pool de connexions HTTP (MelodiAsyncClient.aclose()).

8. Sécurité & Confidentialité

• Authentification unifiée par jeton JWT (Authorization) : Grâce au middleware McpAuthMiddleware, la connexion des clients MCP distant s'effectue via un unique en-tête Authorization: Bearer <jwt>. Le jeton JWT est signé en HS256 avec la clé secrète jwt_secret (configurable dans le dashboard ou via MCP_JWT_SECRET) et contient à la fois la clé MCP infrastructure (mcp_api_key) et l'identifiant personnel utilisateur de l'ERP (user_id).

• Sanitisation des logs : Un filtre de journalisation (SecretMaskingFormatter) expurge automatiquement tout jeton Bearer, mot de passe ou clé d'API des journaux.

• Validation stricte des schémas : Les arguments envoyés par les clients sont validés localement via jsonschema.Draft7Validator avant toute transmission à l'ERP.

• Garde-fous sur les outils sensibles : Les outils marqués requires_confirmation: true exigent explicitement l'argument _confirmed: true pour s'exécuter.

• Aucune exécution de code arbitraire : Seuls les outils déclarés et autorisés par MELODI sont acceptés. L'ERP conserve l'autorité absolue sur les permissions finales.

9. Connexion avec un Client MCP (VS Code, Copilot, Claude Desktop, Cursor)

Option A : Connexion HTTP (VS Code / Copilot Agent / Cursor)

Dans votre fichier .mcp.json ou la configuration de votre client :

{
  "mcpServers": {
    "melodi": {
      "type": "http",
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN_JWT_GENERE_DANS_MELODI_ERP>"
      }
    }
  }
}

{
  "mcp_api_key": "votre_cle_mcp_si_definie",
  "user_id": "votre_identifiant_utilisateur_melodi"
}

Option B : Connexion STDIO locale (Claude Desktop / VS Code)

Pour connecter Claude Desktop à melodi_mcp_server en mode processus local :

Sous Linux / macOS :

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "melodi_erp": {
      "command": "/home/gomsugaetant/Documents/byt3lab/projets/melodi_mcp_server/venv/bin/melodi-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "MELODI_BASE_URL": "http://localhost:8000",
        "MELODI_API_PREFIX": "/api/melodi_mcp/internal",
        "MELODI_API_KEY": "votre_cle_secrete_melodi"
      }
    }
  }
}

Option C : Connexion Automatique OAuth 2.0 (ChatGPT Custom GPTs / Actions, Claude & Clients IA)

Pour connecter des clients IA distants supportant OAuth 2.0 :

• Découverte automatique (RFC 8414) : http://localhost:8765/.well-known/oauth-authorization-server (et /.well-known/openid-configuration)

• URL d'Autorisation : http://localhost:8765/oauth/authorize

• URL de Jeton (Token URL) : http://localhost:8765/oauth/token

• Enregistrement dynamique (RFC 7591) : http://localhost:8765/oauth/register

Lors de la première connexion, le client IA redirige l'utilisateur vers la mire d'autorisation web. L'utilisateur y colle simplement son jeton JWT généré dans MELODI ERP. Le serveur MCP valide la signature, vérifie que le jeton n'est pas révoqué, et fournit le jeton d'accès au client IA pour exécuter les outils en son nom. "MELODI_BASE_URL": "http://localhost:8000", "MELODI_API_PREFIX": "/api/melodi_mcp/internal", "MELODI_API_KEY": "votre_cle_secrete_melodi" } } } }

---

## 10. Tests Automatisés

La suite de tests automatisés utilise `pytest`, `pytest-asyncio` et `respx` pour simuler l'ensemble des scénarios sans nécessiter de serveur MELODI réel.

```bash
# Exécution de l'intégralité des tests unitaires et d'intégration
./venv/bin/pytest -v tests/

Couverture des 24 exigences formelles :

• Tests 1 à 2b : Chargement config, validation des rejets, préfixes d'API personnalisables.

• Tests 3 à 6 : Client HTTP asynchrone, authentification, timeouts, manifest et catalogue.

• Tests 7 à 11 & 18 : Registre dynamique, conversion Tool, collisions de noms, suppression d'outils obsolètes, suivi de révision.

• Tests 12 à 17 & 22 : Exécution lecture/écriture, confirmation requise, timeouts, erreurs métier et revalidation ERP.

• Tests 19 & 21 : Non-divulgation de secrets dans les logs, fermeture gracieuse.

• Test 20 : Cycle de vie du serveur et transport.

• Tests 23 & 24 : Dashboard d'administration (rendu HTML, APIs JSON de statut, synchronisation forcée).

11. Limites Connues & Perspectives

• Module ERP en cours d'implémentation : Le serveur est prêt et aligné sur le contrat v1. Dès que le module melodi_mcp sera déployé dans l'ERP, aucune modification de code ne sera requise côté serveur.

• Persistance locale des métriques : Les métriques de la console d'administration sont conservées en mémoire vive (anneau circulaire des 50 derniers appels). Une extension SQLite pourra être ajoutée si un archivage d'audit persistant sur disque est nécessaire.