Serveur MCP pour exposer des outils et ressources de pilotage MODX/LWE via API REST.

Khanh Nguyen 7b5055669b update tool and client rest to fix delete resource error преди 5 месеца
src 7b5055669b update tool and client rest to fix delete resource error преди 5 месеца
tests 6be50720a3 update test tools преди 5 месеца
.cursorignore 7b5055669b update tool and client rest to fix delete resource error преди 5 месеца
.env.example 237dd86418 initialize mcp server преди 5 месеца
.gitignore 237dd86418 initialize mcp server преди 5 месеца
README.md aef402b26d update readme add mcp.json example преди 5 месеца
pyproject.toml e1326ac4f4 add intergration test преди 5 месеца

README.md

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

uv sync
cp .env.example .env

Remplir le fichier .env avec les variables d'environnements approriés

Execution

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,

{
  "mcpServers": {
    "modx": {
      "command": "uv run",
      "args": [
        "--project", "path/to/project/root",
        "python", "-m", 
	      "src.main"
      ],
      "env": {
        "PYTHONPATH": "path/to/project/root"
      }
    }
  }
}

Un exemple de mcp.json

{
  "mcpServers": {
    "modx": {
      "command": "uv run",
      "args": [
        "--project", "/home/user/khanh/mcp-server",
        "python", "-m", 
	      "src.main"
      ],
      "env": {
        "PYTHONPATH": "/home/user/khanh/mcp-server"
      }
    }
  }
}