|
@@ -0,0 +1,317 @@
|
|
|
|
|
+# 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 <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
|
|
|
|
|
+
|
|
|
|
|
+```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
|