|
|
@@ -0,0 +1,89 @@
|
|
|
+# LW MCP Server
|
|
|
+
|
|
|
+Serveur MCP pour exposer des outils et ressources de pilotage MODX/LWE via API REST.
|
|
|
+
|
|
|
+## Architecture du projet
|
|
|
+
|
|
|
+### Rôles des modules
|
|
|
+
|
|
|
+| Couche | Dossier / fichier | Rôle |
|
|
|
+|--------|-------------------|------|
|
|
|
+| Point d'entrée | `src/main.py` | Valide la config, instancie `ClientRest`, lance `FastMCP` en transport stdio |
|
|
|
+| Configuration | `src/config/initialization.py` | Charge `.env`, valide `BASE_URL`, `LWE_TOKEN`, `PHPSESSID` |
|
|
|
+| Protocole MCP | `src/server_mcp/server.py` | Assemble le serveur et enregistre outils et ressources |
|
|
|
+| Outils (écriture) | `src/server_mcp/tools.py` | Opérations mutantes : CRUD ressources, chunks, snippets, templates, etc. |
|
|
|
+| Ressources (lecture) | `src/server_mcp/resources.py` | Opérations en lecture seule, réponses filtrées pour limiter le contexte envoyé à l'agent |
|
|
|
+| Transport HTTP | `src/services/client_rest.py` | Client synchrone `httpx` vers l'API distante |
|
|
|
+
|
|
|
+### Arborescence
|
|
|
+
|
|
|
+```
|
|
|
+mcp-server/
|
|
|
+├── src/
|
|
|
+│ ├── main.py # Entrée : get_settings() → build_server() → run(stdio)
|
|
|
+│ ├── config/
|
|
|
+│ │ └── initialization.py # Settings + validation au démarrage
|
|
|
+│ ├── server_mcp/
|
|
|
+│ │ ├── server.py # build_server(ClientRest)
|
|
|
+│ │ ├── tools.py # @server.tool — mutations LWE
|
|
|
+│ │ └── resources.py # @server.resource — lectures LWE
|
|
|
+│ └── services/
|
|
|
+│ └── client_rest.py # GET / POST / PUT / DELETE vers BASE_URL
|
|
|
+├── tests/ # pytest + couverture (unitaires + intégration optionnelle)
|
|
|
+├── .env.example
|
|
|
+└── pyproject.toml # uv, dépendances (mcp, httpx, python-dotenv)
|
|
|
+```
|
|
|
+
|
|
|
+### Séparation outils / ressources
|
|
|
+
|
|
|
+- **Ressources MCP** : exposent des données en lecture (liste ou détail de ressources MODX, etc.) avec un filtrage par liste blanche de champs.
|
|
|
+- **Outils MCP** : exposent des actions (création, mise à jour, suppression) avec des annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) pour guider l'agent.
|
|
|
+
|
|
|
+Les deux couches partagent le même `ClientRest` injecté à l'assemblage du serveur, ce qui centralise l'authentification et les appels HTTP.
|
|
|
+
|
|
|
+## Prerequis
|
|
|
+
|
|
|
+- Python 3.13+
|
|
|
+- `uv`
|
|
|
+- Un fichier `.env` avec:
|
|
|
+ - `BASE_URL`
|
|
|
+ - `LWE_TOKEN`
|
|
|
+ - `PHPSESSID`
|
|
|
+
|
|
|
+## Installation
|
|
|
+
|
|
|
+```bash
|
|
|
+uv sync
|
|
|
+cp .env.example .env
|
|
|
+```
|
|
|
+Remplir le fichier `.env` avec les variables d'environnements approriés
|
|
|
+
|
|
|
+## Execution
|
|
|
+
|
|
|
+```bash
|
|
|
+uv run python -m src.main
|
|
|
+```
|
|
|
+
|
|
|
+Le serveur fonctionne en transport stdio pour etre consomme par Cursor.
|
|
|
+
|
|
|
+## Intégration en Cursor
|
|
|
+
|
|
|
+Dans fichier `mcp.json` de Cursor,
|
|
|
+
|
|
|
+``` json
|
|
|
+{
|
|
|
+ "mcpServers": {
|
|
|
+ "modx": {
|
|
|
+ "command": "uv run",
|
|
|
+ "args": [
|
|
|
+ "--project", "path/to/project/root",
|
|
|
+ "python", "-m",
|
|
|
+ "src.main"
|
|
|
+ ],
|
|
|
+ "env": {
|
|
|
+ "PYTHONPATH": "path/to/project/root"
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|