Geocontext
An experimental MCP server providing spatial context for LLM.
Ask AI about Geocontext
Powered by Claude · Grounded in docs
I know everything about Geocontext. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Geocontext
Serveur MCP expérimental fournissant du contexte spatial pour les LLM sur la base des services de la Géoplateforme de l'IGN.
📋 Table des matières
Motivation
Les LLM peuvent donner l'impression de disposer nativement de certaines capacités, mais ils dépendent, en pratique, des outils qui leur sont connectés. Par exemple, pour accéder à la date et à l'heure, un assistant doit être interfacé avec un serveur comme MCP time. De la même manière, pour lire une page web, il doit être relié à un outil tel que MCP fetch.
S'il est techniquement possible de brancher des API REST/GeoJSON telle APICARTO à un LLM, la conception de ces dernières n'est pas adaptée (5000 résultats par défaut, grosse géométrie dans les réponses, géométries complexes à fournir,...).
L'idée est ici d'expérimenter la conception d'un MCP rendant les données et les services de la Géoplateforme accessibles par un LLM.
Mises en garde
- Ce développement est un POC en incubation au sein d'IGNfab sur la base d'un premier prototype désormais archivé
- S'il s'avère utile de l'industrialiser, ce dépôt sera migré dans l'organisation IGN principale et l'outil sera renommé (ex :
IGNF/mcp-gpf-server) - Les issues sont régulièrement mises à jour et traitées
- Une roadmap est également régulièrement alimentée
- 🪄 Cet outil ne relève pas de la magie : ses capacités sont définies et documentées dans Fonctionnalités.
Principes de conception
- Ne pas répliquer les données de la Géoplateforme (objectif : concentrer les efforts sur l'amélioration des services existants plutôt que sur leur duplication)
- Prototyper les capacités manquantes pour l'usage des LLM avec la Géoplateforme (objectif : combler les briques techniques nécessaires à une intégration robuste). Le projet s'appuie notamment sur gpf-schema-store pour l'indexation et la description des schémas.
- Maîtriser la volumétrie des réponses (objectif : réduire le coût en jetons, limiter les hallucinations et permettre l'utilisation de modèles locaux). Cela se traduit en pratique par l'utilisation de références légères (
feature_ref) aux objets géométriques dans les réponses et outils du MCP.
Utilisation
Utilisation de la version publiée
Par exemple, avec "Cursor Settings / MCP / Add server" :
{
"mcpServers": {
"geocontext": {
"command": "npx",
"args": ["-y", "@ignfab/geocontext"]
}
}
}
Autres exemples d'utilisation
Développement
Pré-requis :
- Node.js
24.5.0ou supérieur recommandé (22.21.0minimum supporté) - npm compatible avec la version de Node utilisée
Le dépôt fournit .nvmrc et .node-version. Si vous utilisez nvm, vous pouvez donc faire :
nvm install
nvm use
Construction de la version locale
git clone https://github.com/ignfab/geocontext
cd geocontext
npm ci
npm run build
Utilisation de la version locale
Avec un client MCP compatible JSON
{
"mcpServers": {
"geocontext": {
"command": "node",
"args":["--use-env-proxy", "/chemin/absolu/vers/geocontext/dist/index.js"]
}
}
}
L'option --use-env-proxy est facultative : elle active la prise en charge des variables d'environnement de proxy par Node.js. Ajoutez-la uniquement si votre environnement réseau en a besoin. Voir aussi la section Configuration du proxy réseau.
Avec Docker en local
docker compose build
docker compose up -d
Ensuite :
{
"mcpServers": {
"geocontext": {
"url": "http://localhost:3000/mcp"
}
}
}
Debug de la version locale
Cette commande lance MCP Inspector, l’outil de développement de MCP pour tester et déboguer un serveur local.
npm run inspect:mcp
Pour les tests d'intégration et les tests E2E agent, voir la documentation dédiée.
Paramétrage
Pour une utilisation avancée :
| Nom | Description | Valeur par défaut |
|---|---|---|
TRANSPORT_TYPE | Transport permet de choisir entre "stdio" et "http" | "stdio" |
HTTP_HOST | Adresse d'écoute en mode HTTP. Utile avec Docker pour exposer le service via 0.0.0.0. | "127.0.0.1" |
HTTP_PORT | Port d'écoute du MCP | 3000 |
HTTP_MCP_ENDPOINT | Chemin d'exposition du MCP en HTTP | "/mcp" |
HTTP_CORS_ALLOWED_ORIGINS | Permet la configuration de allowedOrigins pour protection contre les attaques par DNS rebinding. Exemple : HTTP_CORS_ALLOWED_ORIGINS="http://localhost:3000,https://geollm.beta.ign.fr" | Aucun (warning) |
HTTP_TIMEOUT | Délai maximal, en secondes, pour les appels HTTP sortants vers les services amont IGN. Au-delà , la requête est interrompue et l'outil renvoie une erreur de timeout structurée. | 15 |
GPF_WFS_RATE_LIMIT | Nombre maximum de requêtes par seconde sur le WFS de la Géoplateforme | 30 |
GPF_WFS_MINISEARCH_OPTIONS | Chaîne JSON optionnelle pour ajuster les options MiniSearch utilisées par gpf_wfs_search_types (fields, combineWith, fuzzy, boost.namespace, boost.name, boost.title, boost.description, boost.properties, boost.enums, boost.identifierTokens). | options par défaut de @ignfab/gpf-schema-store |
LOG_FORMAT | Le format d'écriture des logs : "json" ou "simple". | "simple" |
LOG_LEVEL | Le niveau d'écriture des logs : "error", "info", ou "debug" | "debug" |
Exemple :
export GPF_WFS_MINISEARCH_OPTIONS='{"fields":["title","identifierTokens"],"combineWith":"OR","fuzzy":0.05,"boost":{"title":4,"name":5}}'
export HTTP_TIMEOUT=15
Si GPF_WFS_MINISEARCH_OPTIONS est absent ou vide, les options par défaut restent celles de @ignfab/gpf-schema-store, y compris le comportement par défaut OR de MiniSearch pour combineWith.
Configuration du proxy réseau
geocontext s'appuie sur la gestion native du proxy par Node.js.
- En exécution locale, le serveur démarre avec
node --use-env-proxy - Les tests d'intégration propagent
NODE_USE_ENV_PROXY=1au sous-processus MCP lancé enstdio - Les tests E2E démarrent les workers Vitest avec
--use-env-proxy
Il suffit donc de définir les variables d'environnement standard selon votre contexte :
export HTTP_PROXY=http://proxy.example:3128
export HTTPS_PROXY=http://proxy.example:3128
export NO_PROXY=localhost,127.0.0.1
Tests
Les commandes principales sont :
npm run typecheck
npm run typecheck:test
npm test
npm run test:integration
npm run test:e2e
npm run test:coverage
npm run verify
npm run verify:full
npm run verify:fast inclut le type-check de l'application et des fichiers de test avant le build et les tests unitaires.
Remarque :
- Les outils
gpf_wfs_search_typesetgpf_wfs_describe_types'appuient sur un catalogue de schémas embarqué fourni par@ignfab/gpf-schema-store. - Les outils
gpf_wfs_get_featuresetgpf_wfs_get_feature_by_idinterrogent toujours le service WFS de la Géoplateforme en direct. - Le catalogue embarqué améliore la description des featureTypes mais il peut être légèrement décalé par rapport à l'état courant du WFS.
Fonctionnalités (Tools)
👉 Une description avancée des tools équivalente au niveau de détail de la méthode tools/list est disponible ici.
On décrit ci-dessous succinctement les différents tools MCP proposés par geocontext.
Utiliser des services spatiaux
- geocode(text) s'appuie sur le service d’autocomplétion de la Géoplateforme pour convertir un nom de lieu en position (lon,lat).
Ex : Quelle est la position (lon,lat) de la mairie de Vincennes?
- altitude(lon,lat) s'appuie sur le service de calcul altimétrique de la Géoplateforme pour convertir une position en altitude.
Ex : Quelle est l'altitude de la mairie de Loray (25)?
Recherche d'informations pour un lieu
L'idée est ici de répondre à des questions précises en traitant côté serveur les appels aux services WFS de la Géoplateforme :
- adminexpress(lon,lat) permet de récupérer les informations administratives (commune, département, région,...) pour un lieu donné par sa position.
Ex : Quelles sont les informations administratives pour la mairie de Vincennes?
- cadastre(lon,lat) permet de récupérer les informations cadastrales (parcelle, feuille,...).
Ex : Quelles sont les informations du cadastre pour la mairie de Vincennes?
- urbanisme(lon,lat) permet de récupérer les informations d'urbanisme (PLU,POS,CC,PSMV)
Ex : Quel est le document PLU en vigueur pour le port de Marseille?
- assiette_sup(lon,lat) permet de récupérer les Servitudes d'Utilité Publique (SUP)
Ex: Quelles assiettes de SUP sont présentes autour de la mairie de Vincennes ?
Les tools WFS orientés "objet" (adminexpress, cadastre, urbanisme, assiette_sup) exposent un feature_ref { typename, feature_id } quand l'objet source est réutilisable tel quel dans un appel ultérieur à gpf_wfs_get_feature_by_id ou gpf_wfs_get_features (ex : spatial_operator="intersects_feature").
Explorer les données vecteurs
Explorer les tables
- gpf_wfs_search_types(keywords,max_results=10) pour rechercher un type WFS pertinent à partir de mots-clés et obtenir un
typenamevalide. La recherche est textuelle et configurable viaGPF_WFS_MINISEARCH_OPTIONS.
- Quels sont les millésimes ADMINEXPRESS disponibles sur la Géoplateforme?
- Quelle est la table de la BDTOPO correspondant aux bâtiments?
- Dans quelle table de la BDTOPO peut-on trouver les ponts?
Explorer la structure des tables
- gpf_wfs_describe_type(typename) pour récupérer le schéma détaillé d'un type WFS depuis le catalogue embarqué (
id,namespace,name,title,description,properties), en particulier avant d'appelergpf_wfs_get_features
- Quelles sont les informations disponibles pour les communes avec ADMINEXPRESS-COG.LATEST?
- Compare le modèle des communes entre ADMINEXPRESS-COG:2024 et ADMINEXPRESS-COG.LATEST
Explorer les données des tables
- gpf_wfs_get_feature_by_id(typename,feature_id,...) pour récupérer exactement un objet WFS identifié par son
feature_id.
Le tool accepte un contrat structuré :
selectpour choisir les propriétés à renvoyerresult_type="request"pour récupérer la requête compilée (POST+get_urléventuelle) pour utilisation par un autre tool (ex: affichage cartographique)result_type="results"pour renvoyer uneFeatureCollectionnormalisée contenant exactement un seul objet
Exemple :
typename="ADMINEXPRESS-COG.LATEST:commune", feature_id="commune.8952"
- gpf_wfs_get_features(typename,...) pour récupérer les données d'une table depuis le service WFS de la Géoplateforme sans écrire de CQL à la main.
Le tool accepte un contrat structuré :
selectpour choisir les propriétés à renvoyerwherepour filtrer les objetsorder_bypour trier les résultatsspatial_operatoret ses paramètres dédiés pour le spatialresult_type="request"pour récupérer la requête compilée enPOST, ainsi qu'uneget_urldérivée quand elle reste raisonnablement portable en GET
Exemples :
where=[{ property: "code_insee", operator: "eq", value: "25000" }]spatial_operator="bbox"avecbbox_west,bbox_south,bbox_east,bbox_northspatial_operator="dwithin_point"avecdwithin_lon,dwithin_lat,dwithin_distance_mspatial_operator="intersects_feature"avecintersects_feature_typenameetintersects_feature_idissus d'unefeature_ref
- Quelles sont les 5 communes les plus peuplées du Doubs (25)?
- Combien y a-t-il de bâtiments à moins de 5 km de la tour Eiffel?
Voir également
- https://github.com/datagouv/datagouv-mcp : MCP data.gouv.fr
- https://github.com/mapbox/mcp-server : MCP Mapbox
- https://git.tricoteuses.fr/logiciels/tricoteuses-api-parlement : MCP parlement français non officiel
- https://github.com/datagouv/datagouv-skill : Skills data.gouv.fr
Contribution
Problèmes et demandes d'évolutions
N'hésitez pas à créer une issue si vous rencontrez un problème! Merci de fournir :
- L'assistant (ex: Github Copilot) et le modèle utilisé (ex: Claude Sonnet 4.5)
- La demande que vous faites Ă l'assistant (ex : "Combien y a-t-il de pont franchissant la Seine?")
Proposer une nouvelle fonctionnalité
N'hésitez pas :
- Forker le dépôt
- Créer un nouveau tool
- Tester de votre côté
- Faire une pull-request
Crédits
- mcp-framework fournit le cadre de développement du MCP
- @ignfab/gpf-schema-store pour le catalogue de schémas embarqué utilisé par les outils d'exploration WFS.
- MiniSearch pour la recherche par mot clé utilisée dans
@ignfab/gpf-schema-store. - jsts pour les traitements géométriques (ex : tri des réponses par distance au point recherché).
- turfjs/distance pour les calculs de distance avec la formule de Haversine.
