# OilApp MCP Server Serveur [Model Context Protocol (MCP)](https://modelcontextprotocol.io) en Python pour **OilApp**, l'application de suivi des anomalies documentaires (OIL aéronautique) hébergée sur Livinweb Engine. Il agit comme passerelle entre un assistant IA (Cursor en V0) et l'API REST OilApp : l'agent dialogue en langage naturel, le serveur MCP traduit les intentions en requêtes HTTP authentifiées. ## Fonctionnalités - **Créer** un finding (anomalie documentaire) - **Rechercher** des findings existants dans un projet ou un item - **Consulter** des statistiques agrégées sur les findings - **Lire** le contexte métier (projets, items, finding unitaire) via des ressources MCP ## Prérequis - [Python](https://www.python.org/) 3.13 ou supérieur - [uv](https://docs.astral.sh/uv/) (gestionnaire de paquets et d'environnement) - Un accès réseau vers l'API REST OilApp - Un cookie de session PHP valide (`PHPSESSID`) pour un utilisateur autorisé ## Installation ```bash git clone cd oilapp-mcp uv sync ``` ## Configuration Copiez le fichier d'exemple et renseignez vos identifiants : ```bash cp .env.example .env ``` | Variable | Obligatoire | Description | |----------|-------------|-------------| | `BASE_URL` | Oui | URL racine de l'API REST OilApp (ex. `https://api.site.local`) | | `PHPSESSID` | Oui | Cookie de session PHP de l'utilisateur connecté | | `AUTHORIZATION` | Non | Jeton d'authentification complémentaire, si requis par l'API | Le fichier `.env` est exclu du contrôle de version (`.gitignore`) et de l'indexation Cursor (`.cursorignore`). Ne commitez jamais de secrets. Sans `.env` valide, le serveur refuse de démarrer et indique les variables manquantes. ## Démarrage ```bash uv run oilapp-mcp ``` Équivalent : ```bash uv run python main.py ``` Le serveur communique en **stdio** (JSON-RPC 2.0), comme attendu par les clients MCP. ## Utilisation avec Cursor Le dépôt inclut une configuration MCP dans `.cursor/mcp.json` : ```json { "mcpServers": { "oilapp": { "command": "uv", "args": ["run", "oilapp-mcp"] } } } ``` Après configuration et redémarrage de Cursor, le serveur **oilapp** apparaît dans les outils MCP. Vous pouvez alors demander en langage naturel, par exemple : - « Liste les projets auxquels j'ai accès » - « Montre les findings du projet 10255 » - « Crée une anomalie sur l'item 298 » - « Donne-moi les statistiques des findings du projet 10255 » Consultez [AGENT.md](AGENT.md) pour les règles de comportement de l'agent et les particularités de l'API. ## Outils MCP (Tools) | Outil | Description | Méthode REST | |-------|-------------|--------------| | `create_finding` | Crée un finding | `POST /rest/oilapp-findings/finding/` | | `get_findings` | Recherche des findings | `GET /rest/oilapp-findings/findings` | | `get_finding_stats` | Statistiques des findings | `GET /rest/oilapp-stats/findingstats` | Les paramètres de chaque outil sont documentés via des champs Pydantic `Field(description=...)` et exposés au client MCP dans le schéma JSON. ## Ressources MCP (Resources) | URI | Description | Point REST | |-----|-------------|------------| | `oilapp://finding/{id}` | Détail d'un finding | `GET /rest/oilapp-findings/finding` | | `oilapp://projects` | Projets accessibles | `GET /rest/oilapp-projects/projects` | | `oilapp://items/{id}` | Items d'un projet | `GET /rest/oilapp-items/items` | ## Structure du projet ``` oilapp-mcp/ ├── main.py # Point d'entrée ├── pyproject.toml # Dépendances et script oilapp-mcp ├── .env.example # Modèle de configuration ├── AGENT.md # Règles de l'agent IA ├── concept.md # Conception technique ├── spec.md # Spécification détaillée └── src/ ├── config/ │ └── initialization.py # Chargement .env, validation, démarrage ├── services/ │ └── client_rest.py # Client HTTP httpx (singleton) └── mcp/ ├── engine.py # Instance FastMCP ├── tools.py # Outils MCP └── resources.py # Ressources MCP ``` ## Sécurité - L'authentification repose sur le cookie `PHPSESSID` (et éventuellement `Authorization`). - Les droits d'accès sont contrôlés côté serveur LWE selon le rôle utilisateur. - Ne transmettez pas de données personnelles aux modèles d'IA externes. - Les jetons d'authentification ne doivent pas apparaître dans les journaux. ## Documentation - [concept.md](concept.md) — architecture et découpage des modules - [spec.md](spec.md) — spécifications fonctionnelles et points REST - [AGENT.md](AGENT.md) — consignes pour l'agent Cursor (outils autorisés, pièges API) ## Développement Dépendances principales : - `mcp[cli]` — SDK Python MCP (FastMCP) - `httpx` — client HTTP synchrone - `python-dotenv` — chargement des variables d'environnement Pour inspecter le serveur en mode développement MCP : ```bash uv run mcp dev main.py ```