# 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](#vue-densemble) - [Architecture](#architecture) - [Installation](#installation) - [Configuration](#configuration) - [Utilisation](#utilisation) - [Outils disponibles](#outils-disponibles) - [Format des réponses](#format-des-réponses) - [Gestion des erreurs](#gestion-des-erreurs) ## 🎯 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 ```bash # Clone le repository git clone 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 ```bash python -m mcp_server.main ``` ### Exemple d'appel d'outil (via MCP) ```json { "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 :** ```json { "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 :** ```json { "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 :** ```json { "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é : ```json { "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 ```json { "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 : ```json { "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 : ```bash python -m pytest mcp_server/tests/ -v ``` ## 📝 Logging Les logs sont stockés selon la configuration `LOG_LEVEL` : ```python 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