Cynogis
Projet conçu pour un bureau d'études environnement travaillant à La Réunion (EPSG:2975) et à Mayotte (EPSG:4471). Un serveur MCP générique relaie les appels d'un client IA vers un plugin QGIS via un pont TCP local authentifié par jeton. Chaque outil est déclaré avec un niveau de risque, des paramètres validés par JSON Schema et une description destinée à l'IA. Les modifications passent par le tampon d'édition de QGIS, les opérations destructives exigent une validation humaine, les sorties ne sont jamais écrasées et chaque appel est journalisé.
- Python
- PyQGIS
- QGIS 3 / 4
- Qt (PyQt5 / PyQt6)
- Model Context Protocol
- JSON Schema
- TCP / JSON-lines
- GeoPackage
- WMS / WFS
- pytest
- ruff
Contexte et objectif
Dans un bureau d'études environnement, le travail SIG est répétitif : vérifier un SCR, contrôler des géométries, croiser une emprise de projet avec des zonages réglementaires, calculer des surfaces d'habitats impactés, produire une carte ou un atlas. Ces opérations demandent de bien connaître QGIS et parfois d'écrire du PyQGIS.
L'objectif de Cynogis est de permettre à un chargé d'études de formuler sa demande en langage naturel et de laisser un assistant IA réaliser les opérations directement dans QGIS. L'IA doit rester dans un périmètre maîtrisé, et l'utilisateur doit garder le contrôle sur les données.
- Réduire le temps passé sur les tâches d'inspection, de contrôle et de production cartographique
- Ne jamais modifier ni supprimer de données sans validation humaine
- Rester entièrement local : aucune donnée métier ne quitte le poste
- Gérer nativement les spécificités de La Réunion (EPSG:2975) et de Mayotte (EPSG:4471)
Architecture
Le système repose sur deux processus. Le serveur MCP, exécuté dans un environnement Python externe, communique en stdio avec le client IA. Il est volontairement générique : il ne déclare aucun outil lui-même, mais relaie le catalogue fourni par le plugin et le met en cache pour rester utilisable lorsque QGIS est fermé.
Le plugin QGIS ouvre un serveur TCP limité à 127.0.0.1. Chaque message est une ligne JSON versionnée et accompagnée d'un jeton de session. Ce jeton et le port sont publiés dans un fichier local relu par le serveur MCP à chaque appel. Côté plugin, un dispatcher valide les paramètres, contrôle le niveau de permission, exécute l'outil sur le thread principal de Qt puis journalise le résultat.
- Client MCP (Claude, MCP Inspector)
- Serveur MCP → pont TCP local (127.0.0.1, JSON-lines et jeton de session)
- Plugin QGIS → décodage du protocole → dispatcher → outils PyQGIS
- Ajout d'un outil uniquement côté plugin, sans modifier le serveur
- Compatibilité avec QGIS 3.x (Qt5) et 4.x (Qt6) via une couche de compatibilité
Déclaration des outils
Chaque outil est une fonction Python décorée par @tool. Le décorateur déclare son niveau de risque et ses paramètres, tandis que la docstring sert de description pour l'IA. Au chargement, le registre vérifie la correspondance entre les paramètres déclarés et la signature de la fonction, puis génère le schéma JSON exposé au client MCP.
Ce mécanisme rend le catalogue autodescriptif. Un nouvel outil devient disponible pour l'IA dès que le plugin est rechargé, avec une validation des paramètres, une gestion des erreurs et une journalisation homogènes.
- Nom de la fonction = nom de l'outil exposé
- Paramètres déclarés et convertis automatiquement en JSON Schema
- Docstring obligatoire, utilisée comme description pour l'agent IA
- Codes d'erreur typés et retours structurés avec données, avertissements et fichiers produits
Sécurité et garde-fous
Donner des capacités à un modèle de langage ne pose pas de difficulté particulière ; le véritable enjeu est de les encadrer. Chaque outil appartient à l'un des quatre niveaux suivants : lecture, création, modification ou destruction. Les données existantes ne sont jamais écrasées sur le disque.
Pour les cas qu'aucun outil ne couvre, un outil d'exécution PyQGIS de dernier recours est disponible. Il est classé au niveau le plus élevé : l'IA doit décrire chaque étape en français compréhensible, puis l'utilisateur consulte ces étapes et le code avant d'accepter l'exécution.
- READ : lecture seule
- CREATE : création de données uniquement, sans modifier l'existant
- MODIFY : modification dans le tampon d'édition QGIS, entièrement annulable
- DESTROY : confirmation humaine obligatoire et analyse d'impact
- Enregistrement sur disque uniquement via une demande de validation explicite
- Journal des modifications en attente affiché avant validation
- Liste blanche d'algorithmes Processing autorisés
- Sorties jamais écrasées : GeoPackage horodaté dans le projet, avec suffixes _2, _3…
- Audit de chaque appel : outil, paramètres, résultat et fichiers créés
Fonctionnalités développées
Le plugin expose une centaine d'outils regroupés en une trentaine de modules métier. Ils couvrent aussi bien les opérations SIG génériques que des traitements propres aux études environnementales menées à La Réunion et à Mayotte.
- Projet et couches : inventaire, métadonnées, SCR, informations raster, audit de projet, organisation des couches
- Géotraitements : reprojection, correction de géométries, tampons, fusion, extraction, superposition, jointure spatiale
- Édition vectorielle : attributs, champs, déplacement, découpage, fusion et accrochage de géométries
- Qualité des données : contrôle des trous topologiques, résolution des chevauchements, diagnostic des shapefiles
- Analyse paysagère : nomenclature locale fermée, classification, indices FRAGSTATS et extraction des ravines
- Terrain : pentes, exposition, accumulation de flux, classes de pente et échantillonnage du MNT
- Biodiversité : rattachement à TAXREF et HABREF, statuts de protection, cartographie des enjeux pondérés et densité de points
- Études d'impact : croisement avec les zonages réglementaires, surfaces d'habitats impactés et comparaison de variantes d'emprise
- Terrain et relevés : plans d'échantillonnage, import de données GPX, CSV, KoboToolbox et QField
- Services web : catalogue WMS / WFS et chargement d'entités
- Statistiques : statistiques descriptives et zonales, coefficients d'urbanisme (CES, COS, CBS, ruissellement)
- Cartographie : styles simples, cartes thématiques, annulation de style, export d'images et atlas PDF
- Livrables : export de tables, notes de synthèse Markdown / HTML et sauvegarde du projet
Qualité et tests
Toute la logique métier testable est placée dans un module Python pur (core/), sans aucune dépendance à QGIS : classification, statistiques, indices paysagers, règles d'enjeux, nomenclatures, nommage des sorties, validation des paramètres et protocole du pont. Le code PyQGIS spécifique est isolé dans tools/.
Cette séparation permet d'exécuter 353 tests unitaires pytest en moins d'une seconde, en dehors de QGIS.
- 353 tests unitaires pytest exécutés en Python pur
- Analyse statique avec ruff
- Script de test du pont sans IA et validation via MCP Inspector
- Documentation technique destinée aux développeurs et aux agents IA
Résultats
Le MVP est fonctionnel. Un chargé d'études peut décrire son besoin en langage naturel et l'IA enchaîne les outils nécessaires. Par exemple, elle peut charger les zonages, les croiser avec l'emprise du projet, calculer les surfaces d'habitats impactés, appliquer un style et produire un atlas.
Chaque action laisse une trace lisible et aucune donnée n'est modifiée sans que l'utilisateur ait vu et validé les changements dans QGIS.
Ce que j'ai appris
Ce projet m'a appris à concevoir une interface sûre entre un modèle de langage et une application métier. La qualité des descriptions d'outils et des schémas de paramètres influence directement la pertinence des actions choisies par l'IA, autant que le code lui-même.
J'ai également appris à travailler avec les contraintes d'un Python embarqué : exécution sur le thread principal de Qt, rechargement à chaud du plugin et compatibilité entre deux versions majeures de QGIS et de Qt.
- Conception d'outils MCP : nommage, descriptions et schémas de paramètres
- Communication interprocessus : protocole JSON-lines sur TCP local et découverte par fichier
- Modèle de permissions graduées avec validation humaine
- Isolation de la logique métier pour la tester sans l'application hôte
- Compatibilité entre QGIS 3 et 4 via une couche adaptée
Limites et suites possibles
Les outils s'exécutent sur le thread principal de QGIS. Un traitement long bloque donc l'interface, et le client abandonne au bout de 120 secondes. Certains outils récents doivent encore être validés en conditions réelles.
- Exécuter les traitements longs en arrière-plan avec QgsTask
- Rendre persistants le journal d'exécution et l'historique d'audit
- Ajouter des tests d'intégration dans QGIS
- Gérer plusieurs utilisateurs et l'accès à distance
Une question sur ce projet ou une opportunité de stage ? N'hésitez pas à me contacter.
Me contacter