Geocontext

Serveur MCP expérimental fournissant du contexte spatial pour les LLM sur la base des services de la Géoplateforme de l'IGN.

• Geocontext

  • Motivation

  • Mises en garde

  • Principes de conception

  • Utilisation

    • Utilisation de la version publiée

    • Autres exemples d'utilisation

  • Développement

    • Construction de la version locale

    • Utilisation de la version locale

      • Avec un client MCP compatible JSON

      • Avec Docker en local

    • Debug de la version locale

  • Paramétrage

    • Tests

  • Fonctionnalités (Tools)

    • Utiliser des services spatiaux

    • Recherche d'informations pour un lieu

    • Explorer les données vecteurs

      • Explorer les tables

      • Explorer la structure des tables

      • Explorer les données des tables

  • Voir également

  • Contribution

    • Problèmes et demandes d'évolutions

    • Proposer une nouvelle fonctionnalité

  • Crédits

  • Licence

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

• Exemple d'utilisation avec Claude Desktop

• Exemple d'utilisation avec MCPJam

Développement

Pré-requis :

• Node.js 24.5.0 ou supérieur recommandé (22.21.0 minimum 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 :

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.

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=1 au sous-processus MCP lancé en stdio

• 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_types et gpf_wfs_describe_type s'appuient sur un catalogue de schémas embarqué fourni par @ignfab/gpf-schema-store.

• Les outils gpf_wfs_get_features et gpf_wfs_get_feature_by_id interrogent 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 typename valide. La recherche est textuelle et configurable via GPF_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'appeler gpf_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é :

• select pour choisir les propriétés à renvoyer

• result_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 une FeatureCollection normalisé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é :

• select pour choisir les propriétés à renvoyer

• where pour filtrer les objets

• order_by pour trier les résultats

• spatial_operator et ses paramètres dédiés pour le spatial

• result_type="request" pour récupérer la requête compilée en POST, ainsi qu'une get_url dérivée quand elle reste raisonnablement portable en GET

Exemples :

• where=[{ property: "code_insee", operator: "eq", value: "25000" }]

• spatial_operator="bbox" avec bbox_west, bbox_south, bbox_east, bbox_north

• spatial_operator="dwithin_point" avec dwithin_lon, dwithin_lat, dwithin_distance_m

• spatial_operator="intersects_feature" avec intersects_feature_typename et intersects_feature_id issus d'une feature_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.

Licence

MIT