Tutoriel : Installation d'un serveur MCP Codexia sur VPS

Ce guide détaille l'installation d'un serveur Model Context Protocol (MCP) sur un VPS Ubuntu pour permettre à une IA distante (ex: Claude Desktop) d'accéder aux ressources du projet Codexia de manière sécurisée.

1. Architecture cible

Serveur MCP : Application Node.js tournant sur le VPS.
Transport : SSE (Server-Sent Events) via HTTPS.
Ressources exposées : Documentation inputs/legacy/, accès aux logs, outils de diagnostic.
Sécurité : Authentification par clé API et tunnel TLS.

2. Pré-requis sur le VPS

Connectez-vous à votre VPS et assurez-vous que les outils de base sont présents :

# Mise à jour
sudo apt update && sudo apt upgrade -y

# Installation de Node.js (v18+)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Vérification
node -v
npm -v

3. Installation du serveur MCP Codexia

Nous allons utiliser un serveur MCP générique que nous configurerons pour Codexia.

Création du répertoire de travail

mkdir -p /opt/codexia/mcp-server
cd /opt/codexia/mcp-server

Initialisation du projet

npm init -y
npm install @modelcontextprotocol/sdk express cors

Création du serveur (`index.js`)

Créez un fichier index.js avec une configuration de base pour exposer le dossier inputs/legacy/ :

const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
const { SSEServerTransport } = require("@modelcontextprotocol/sdk/server/sse.js");
const express = require("express");

const server = new Server({
  name: "tlr-mcp",
  version: "1.0.0",
}, {
  capabilities: {
    resources: {},
    tools: {},
  },
});

// Logique pour exposer les ressources Codexia (ex: inputs/legacy/)
// ... configuration des resources ...

const app = express();
let transport;

app.get("/sse", async (req, res) => {
  transport = new SSEServerTransport("/message", res);
  await server.connect(transport);
});

app.post("/message", async (req, res) => {
  if (transport) {
    await transport.handleMessage(req, res);
  }
});

app.listen(3000, () => {
  console.log("Serveur MCP Codexia écoute sur le port 3000");
});

4. Exposition via Reverse Proxy (Apache)

Puisque votre VPS utilise Apache, nous allons configurer un VirtualHost pour servir de reverse proxy sécurisé (HTTPS).

Activation des modules nécessaires

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod ssl
sudo systemctl restart apache2

Configuration du VirtualHost

Créez un fichier /etc/apache2/sites-available/mcp-codexia.conf :

<VirtualHost *:443>
    ServerName mcp.codexia.fr

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/mcp.codexia.fr/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/mcp.codexia.fr/privkey.pem

    # Configuration du Proxy vers le serveur Node.js (port 3000)
    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/

    # Optimisations pour le flux SSE (Server-Sent Events)
    <Location "/sse">
        ProxyPass http://localhost:3000/sse
        SetEnv force-proxy-1.0 1
        SetEnv proxy-nokeepalive 1
        # Désactiver la mise en cache et le buffer pour le flux continu
        RequestHeader set Connection ""
    </Location>

    ErrorLog ${APACHE_LOG_DIR}/mcp-error.log
    CustomLog ${APACHE_LOG_DIR}/mcp-access.log combined
</VirtualHost>

Activation du site

sudo a2ensite mcp-codexia
sudo systemctl reload apache2

5. Gestion du processus avec PM2

Qu'est-ce que PM2 ?

PM2 est un gestionnaire de processus pour les applications Node.js. Sur un VPS, il remplit plusieurs rôles critiques :

Daemonisation : Il fait tourner votre application en arrière-plan (arrière-plan). Sans PM2, si vous fermez votre console SSH, le serveur MCP s'arrêterait.
Auto-redémarrage : Si votre application plante (crash), PM2 la relance instantanément.
Survie au Reboot : Il permet de relancer automatiquement le serveur MCP après un redémarrage du VPS.
Monitoring : Il offre une interface simple pour voir la consommation CPU/RAM et les logs en temps réel.

Installation et démarrage

sudo npm install -g pm2

# Démarrer le serveur
pm2 start index.js --name tlr-mcp

# Configurer le démarrage automatique au boot du VPS
pm2 startup
# (Suivre l'instruction affichée par la commande précédente)
pm2 save

Commandes utiles PM2

pm2 status : Liste les processus actifs.
pm2 logs tlr-mcp : Affiche les logs en direct (très utile pour débugger l'IA).
pm2 restart tlr-mcp : Redémarre le serveur après une modification du code.

6. Configuration du Client (Claude Desktop)

Sur votre machine locale, modifiez votre fichier claude_desktop_config.json pour ajouter le serveur distant :

{
  "mcpServers": {
    "codexia-vps": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client-sse",
        "https://mcp.codexia.fr/sse"
      ]
    }
  }
}

7. Sécurité et Monitoring

Pare-feu : Assurez-vous que le port 3000 n'est pas ouvert à l'extérieur (seul Nginx doit y accéder).
Fail2ban : Surveillez les logs Nginx pour bloquer les tentatives d'intrusion.
Logs : Consultez les logs du serveur MCP avec pm2 logs tlr-mcp.

8. Alternative : Serveur MCP avec Symfony 8 (PHP)

Si votre écosystème repose sur Symfony 8 (PHP 8.4+), vous pouvez implémenter un serveur MCP natif sans Node.js. Cette approche permet à l'IA d'interagir directement avec vos services Symfony (Doctrine, Twig, Services de diagnostic).

Architecture Symfony MCP

Contrôleur : McpController gère les requêtes JSON-RPC 2.0.
Services : Vos outils MCP sont des services Symfony taggués.
Sécurité : Firewall Symfony avec X-API-KEY.

Installation et Configuration

Création du projet (si nécessaire) :

composer create-project symfony/skeleton mcp-server "8.0.*"
cd mcp-server
composer require symfony/http-foundation symfony/routing symfony/serializer symfony/security-bundle

Implémentation du Contrôleur (src/Controller/McpController.php) : Ce contrôleur reçoit les requêtes de l'IA (Claude/ChatGPT) et les route vers vos outils.

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class McpController extends AbstractController
{
    #[Route('/api/mcp', name: 'app_mcp_endpoint', methods: ['POST'])]
    public function handle(Request $request): JsonResponse
    {
        $payload = json_decode($request->getContent(), true);

        // Logique simplifiée de routage MCP (JSON-RPC)
        $method = $payload['method'] ?? '';

        $response = match($method) {
            'resources/list' => ['result' => ['resources' => [['uri' => 'file://inputs/legacy/readme', 'name' => 'README Legacy']]]],
            'tools/list' => ['result' => ['tools' => [['name' => 'analyze_doc', 'description' => 'Analyse la qualité de la doc']]]],
            default => ['error' => ['code' => -32601, 'message' => 'Method not found']]
        };

        return $this->json(array_merge(['jsonrpc' => '2.0', 'id' => $payload['id'] ?? null], $response));
    }
}

Exposition via Apache : Le VirtualHost est identique à une application Symfony standard, pointant vers public/index.php.

Avantages de Symfony 8 pour MCP

Accès natif au code : L'IA peut appeler des méthodes PHP complexes (ex: EpubCheck ou validateurs d'accessibilité).
Stabilité : Utilisation de PHP-FPM et du cache d'OPcache pour des performances optimales.
Typage fort : Exploitation des énumérations PHP 8.1+ et du typage strict pour définir les schémas d'outils (JSON Schema).

Ajout d'un outil (Tool) PHP personnalisé

Pour étendre votre serveur MCP Symfony, vous devez créer des classes d'outils qui seront automatiquement détectées.

Définition de l'Interface (src/Mcp/McpToolInterface.php) :

namespace App\Mcp;

interface McpToolInterface
{
    public function getName(): string;
    public function getDescription(): string;
    public function getParameters(): array; // JSON Schema
    public function execute(array $arguments): array;
}

Création d'un outil concret (src/Mcp/Tools/DocQualityTool.php) :

namespace App\Mcp\Tools;

use App\Mcp\McpToolInterface;

class DocQualityTool implements McpToolInterface
{
    public function getName(): string { return 'check_doc_quality'; }

    public function getDescription(): string { 
        return 'Vérifie la qualité Markdown d\'un fichier de documentation.'; 
    }

    public function getParameters(): array {
        return [
            'type' => 'object',
            'properties' => [
                'path' => ['type' => 'string', 'description' => 'Chemin relatif du fichier .md']
            ],
            'required' => ['path']
        ];
    }

    public function execute(array $arguments): array {
        $path = $arguments['path'];
        // Logique de vérification (ex: présence de titres, longueur...)
        return ['status' => 'success', 'score' => 85, 'suggestions' => ['Ajouter un titre H1']];
    }
}

Enregistrement et Injection (Autoconfiguration) : Dans config/services.yaml, activez l'autoconfiguration pour votre interface :

services:
    _instanceof:
        App\Mcp\McpToolInterface:
            tags: ['codexia.mcp_tool']

Mise à jour du Contrôleur : Le contrôleur peut désormais lister et exécuter les outils en utilisant le ServiceLocator de Symfony.

9. Exemples concrets pour valoriser votre documentation

L'utilisation d'un serveur MCP permet de transformer votre documentation statique en un système interactif "intelligent".

Exemple 1 : Assistant de conformité RGAA (Accessibilité)

L'outil : check_accessibility_compliance

Action : L'IA lit un fichier Markdown de la documentation.
Traitement : Elle appelle le service Symfony qui scanne les structures de titres (#, ##) et vérifie la présence de textes alternatifs sur les images.
Résultat : L'IA vous indique en temps réel : "Attention, le document guides/ia.md ne respecte pas le niveau AA sur la hiérarchie des titres (saut du H2 au H4)."

Exemple 2 : Indexation sémantique et Navigation

L'outil : find_related_docs

Action : Vous posez une question sur le déploiement SSL.
Traitement : Le serveur MCP parcourt le dossier inputs/legacy/ (via PHP Finder) et identifie les fichiers pertinents (guides/ssl-tls.md et guides/hsts.md).
Résultat : L'IA synthétise une réponse en citant précisément les paragraphes de la documentation officielle, assurant une source de vérité unique.

Exemple 3 : Génération de Résumés Exécutifs

L'outil : summarize_roadmap

Action : L'IA accède aux fichiers du dossier pilotage/.
Traitement : Elle extrait les points clés de la roadmap.md et les compare aux derniers CHANGELOG.md.
Résultat : Elle génère un rapport de progression pour les décideurs, valorisant ainsi le travail de documentation méthodologique.