浏览代码

update readme

Khanh Nguyen 5 月之前
父节点
当前提交
6b0b82f324
共有 2 个文件被更改,包括 98 次插入 和 1 次删除
  1. 9 1
      .cursorignore
  2. 89 0
      README.md

+ 9 - 1
.cursorignore

@@ -5,5 +5,13 @@
 
 #src/
 
-README.md
+#tests/
+#README.md
 
+htmlcov/
+
+.coverage
+
+.pytest_cache/
+
+uv.lock

+ 89 - 0
README.md

@@ -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"
+      }
+    }
+  }
+}
+```