Tidak Ada Deskripsi

Khanh Nguyen 45460820e1 update fix auth error 3 bulan lalu
.cursor dd0524835b project create 4 bulan lalu
src 45460820e1 update fix auth error 3 bulan lalu
.cursorignore dd0524835b project create 4 bulan lalu
.env.example 33cfb8f159 update authentication 3 bulan lalu
.gitignore dd0524835b project create 4 bulan lalu
AGENT.md dd0524835b project create 4 bulan lalu
README.md dd0524835b project create 4 bulan lalu
main.py dd0524835b project create 4 bulan lalu
pyproject.toml dd0524835b project create 4 bulan lalu
uv.lock dd0524835b project create 4 bulan lalu

README.md

OilApp MCP Server

Serveur Model Context Protocol (MCP) 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 3.13 ou supérieur
  • 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

git clone <url-du-depot>
cd oilapp-mcp
uv sync

Configuration

Copiez le fichier d'exemple et renseignez vos identifiants :

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

uv run oilapp-mcp

Équivalent :

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 :

{
  "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 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 — architecture et découpage des modules
  • spec.md — spécifications fonctionnelles et points REST
  • 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 :

uv run mcp dev main.py