Bez popisu

Damien Lugagne-Delpon 6b80eecfec feat: Ajout de la gestion des ressources MODX avec création, lecture et mise à jour před 9 měsíci
mcp_server 6b80eecfec feat: Ajout de la gestion des ressources MODX avec création, lecture et mise à jour před 9 měsíci
.gitignore 6b80eecfec feat: Ajout de la gestion des ressources MODX avec création, lecture et mise à jour před 9 měsíci
README.md 6b80eecfec feat: Ajout de la gestion des ressources MODX avec création, lecture et mise à jour před 9 měsíci
requirements.txt 6b80eecfec feat: Ajout de la gestion des ressources MODX avec création, lecture et mise à jour před 9 měsíci

README.md

LW-Copilot - Serveur MCP MODX

LW-Copilot est un serveur Model Context Protocol (MCP) permettant à un agent IA d'automatiser la gestion des ressources MODX. Il expose des outils pour créer, lire et modifier des ressources MODX de manière sécurisée et contextuelle.

📋 Table des matières

🎯 Vue d'ensemble

LW-Copilot V1 propose trois outils pour gérer les ressources MODX :

  1. create_resource - Créer une nouvelle ressource avec une template
  2. get_resource - Lire les données d'une ressource
  3. update_resource - Mettre à jour une ressource existante

Cas d'usage principaux

  • Avec template spécifiée : L'agent crée/modifie une ressource en utilisant une template précise
  • Sans template : L'agent cherche dans le contexte la template la plus appropriée
  • Modification précise : L'agent utilise get_resource pour lire puis mettre à jour une ressource

🏗️ Architecture

LW-Copilot/
├── mcp_server/
│   ├── main.py                    # Point d'entrée du serveur
│   ├── config/
│   │   ├── settings.py            # Configuration (URLs, auth, etc.)
│   │   └── logger.py              # Initialisation du logger
│   │
│   ├── core/
│   │   ├── errors.py              # Exceptions personnalisées
│   │   ├── permissions.py         # Vérification des permissions
│   │   ├── constants.py           # Énumérations (ModxType, actionType)
│   │   └── context/
│   │       ├── context_manager.py # Gestion du contexte
│   │       └── context_schema.py  # Schéma du contexte
│   │
│   ├── api/
│   │   └── modx_client.py         # Client HTTP pour MODX
│   │
│   ├── tools/
│   │   ├── tool_class.py          # Classe Tool de base
│   │   └── resource/
│   │       ├── create_resource.py # Outil create_resource
│   │       ├── get_resource.py    # Outil get_resource
│   │       └── update_resource.py # Outil update_resource
│   │
│   ├── mcp/
│   │   ├── tool_exposure.py       # Exposition des outils à MCP
│   │   ├── request_validator.py   # Validation des requêtes
│   │   └── response_formatter.py  # Formatage des réponses
│   │
│   └── tests/                     # Tests unitaires
│       ├── test_context.py
│       ├── test_permissions.py
│       └── test_tools_resource.py

💻 Installation

Prérequis

  • Python 3.8+
  • httpx pour les appels HTTP
  • Un serveur MODX avec endpoints REST configurés

Étapes

# Clone le repository
git clone <repo-url>
cd LW-Copilot

# Crée un virtual environment
python -m venv venv
source venv/bin/activate  # ou `venv\Scripts\activate` sur Windows

# Installe les dépendances
pip install -r requirements.txt

requirements.txt

httpx==0.24.0
python-dotenv==1.0.0

⚙️ Configuration

La configuration se fait via des variables d'environnement dans le fichier config/settings.py

📖 Utilisation

Démarrage du serveur

python -m mcp_server.main

Exemple d'appel d'outil (via MCP)

{
  "tool": "create_resource",
  "parameters": {
    "pagetitle": "Ma nouvelle page",
    "template": 1,
    "content": "Contenu de la page",
    "alias": "ma-nouvelle-page",
    "published": true,
    "tvs": {
      "subtitle": "Sous-titre"
    }
  }
}

🔧 Outils disponibles

1. create_resource

Crée une nouvelle ressource MODX.

Paramètres :

Paramètre Type Requis Description
pagetitle string ✅ Titre de la page
template integer ✅ ID de la template
content string ❌ Contenu principal
parent integer ❌ ID du parent (défaut: 0)
published boolean ❌ Publier la ressource
alias string ❌ Alias URL
tvs object ❌ Variables de template

Exemple :

{
  "tool": "create_resource",
  "parameters": {
    "pagetitle": "Documentation API",
    "template": 2,
    "content": "## Documentation\n\nCeci est la documentation...",
    "alias": "api-docs",
    "published": true
  }
}

2. get_resource

Récupère les données d'une ressource.

Paramètres :

Paramètre Type Requis Description
id integer ✅ ID de la ressource

Exemple :

{
  "tool": "get_resource",
  "parameters": {
    "id": 10
  }
}

3. update_resource

Met à jour une ressource existante.

Paramètres :

Paramètre Type Requis Description
id integer ✅ ID de la ressource
pagetitle string ❌ Nouveau titre
content string ❌ Nouveau contenu
published boolean ❌ Nouveau statut publication
alias string ❌ Nouvel alias
tvs object ❌ Nouvelles variables de template

Exemple :

{
  "tool": "update_resource",
  "parameters": {
    "id": 10,
    "pagetitle": "Documentation API (Mise à jour)",
    "content": "## Documentation mise à jour\n\n..."
  }
}

📤 Format des réponses

Toutes les réponses des outils suivent ce format standardisé :

{
  "success": true,
  "code": 200,
  "data": [
    {
      "id": 10,
      "pagetitle": "Ma page",
      "template": 1,
      "...": "..."
    }
  ],
  "message": "Resource created successfully"
}

Champs :

  • success (boolean) : Indique si l'opération a réussi
  • code (integer) : Code HTTP (200, 400, 401, 403, 404, 500)
  • data (array) : Données retournées (ressource, liste, etc.)
  • message (string) : Message descriptif

❌ Gestion des erreurs

Codes d'erreur

Code Erreur Description
400 Validation Error Paramètres invalides ou manquants
401 Authentication Error Authentification échouée
403 Permission Error Droits insuffisants
404 Not Found Ressource non trouvée
500 Internal Error Erreur serveur

Exemple de réponse d'erreur

{
  "success": false,
  "code": 403,
  "data": [],
  "message": "Access denied: update permission not granted for resource 10"
}

🔐 Gestion du contexte

Le contexte définit les ressources/templates accessibles par l'agent :

{
  "resource": {
    "10": { "read": true, "update": false },
    "11": { "read": true, "update": true }
  },
  "template": {
    "1": { "read": true },
    "2": { "read": true }
  }
}

L'agent ne peut que :

  • Lire les ressources avec permission "read": true
  • Modifier les ressources avec permission "update": true
  • Utiliser les templates avec permission "read": true

🧪 Tests

Exécute les tests unitaires :

python -m pytest mcp_server/tests/ -v

📝 Logging

Les logs sont stockés selon la configuration LOG_LEVEL :

import logging
logger = logging.getLogger(__name__)
logger.info("Message d'information")
logger.error("Message d'erreur")

🚀 Prochaines étapes (V2)

  • Support des outils template et chunk
  • Recherche intelligente de templates
  • Gestion des TVs spécialisés
  • Intégration de snippets MODX
  • Dashboard de monitoring

📄 Licence

© Intersel 2026

👥 Auteur

Damien Lugagne-Delpon - damien.lugagne-delpon@livinweb.fr