WebMCP

Chaque page d'unmap.dev enregistre un petit ensemble d'outils auprès du contexte de modèle du navigateur (WebMCP). Un agent qui travaille dans l'onglet (une extension de navigateur, ou un assistant qui pilote la page qu'une personne regarde) peut se servir du site plutôt que de le racler.

Cette page est la référence de ces quatre outils : leurs arguments, ce qu'ils renvoient et ce qu'ils refusent. Pour la vue d'ensemble de la façon dont unmap se présente aux agents, Agents couvre les documents de découverte et le point de terminaison A2A, et Serveur MCP couvre le point de terminaison MCP côté serveur, qui lui appelle l'API.

Ce que ces outils ne sont pas

La distinction compte plus ici qu'ailleurs dans cette documentation, parce que les deux surfaces se ressemblent et se comportent tout autrement.

Rien sur cette page ne touche à l'API unmap. Pas de clé, aucune requête vers api.unmap.dev, aucun appel facturé, aucune limite de débit. La recherche s'exécute sur un index statique déjà présent dans le navigateur ; les trois autres outils lisent des pages que le site sert de toute façon. Ils fonctionnent sans être connecté et ne coûtent rien.

Tout ce qui coûterait un appel (un géocodage, un trajet, un isochrone, une tuile) est délibérément absent. Cela vit sur le serveur MCP et l'API REST, qui exigent tous deux une clé. Un agent qui trouve list_unmap_map_styles ici et s'attend à géocoder avec a mal lu la surface.

search_unmap_docs

Recherche plein texte dans cette documentation, avec des sections classées par pertinence. C'est l'outil à saisir en premier quand la question est « comment faire X avec unmap ».

{
  "query": "isochrone",   // requis, non vide
  "limit": 5              // entier optionnel, 1 à 10, 5 par défaut
}

Renvoie du JSON : la requête telle qu'exécutée, et un tableau results de { url, title, section?, excerpt }. L'URL est absolue, donc transmissible à quelqu'un d'autre ou directement à read_unmap_page. section apparaît quand le résultat porte sur un titre d'une page plutôt que sur la page entière.

Les extraits arrivent en prose. L'index sous-jacent les renvoie en HTML, les mots trouvés entourés de <mark> ; le balisage est retiré et les entités décodées avant que le texte n'atteigne le modèle, parce qu'un modèle veut la phrase, pas les balises.

Un limit hors bornes est ramené dans l'intervalle plutôt que refusé : 0 comme 999 donnent une recherche qui fonctionne. Un query absent ou vide est une erreur.

read_unmap_page

N'importe quelle page d'unmap.dev en Markdown, à partir d'un chemin relatif à la racine. À utiliser pour lire toute la prose d'une page après qu'une recherche en a renvoyé un extrait.

{ "path": "/docs/start/quickstart" }   // requis

Renvoie le Markdown de la page sous forme de texte, les mêmes octets que le site fournit avec un en-tête Accept :

curl -H "Accept: text/markdown" https://unmap.dev/fr/docs/start/quickstart

Cet outil lit ; il ne déplace pas la personne. Si quelqu'un demande ce que dit une page, lisez-la et laissez-le où il est. navigate_unmap_site sert au cas où il veut aller voir la page lui-même.

Le chemin est restreint avant toute requête, et refusé plutôt que réparé. Une URL absolue sur l'origine d'unmap.dev est acceptée, parce que c'est ce que donne un résultat de recherche. Tout le reste est rejeté : une autre origine, une URL relative au protocole, une remontée de répertoire, et tout ce qui porte une extension de fichier, qui est une ressource sans Markdown à côté.

Cette vérification s'appuie sur un analyseur d'URL plutôt que sur l'inspection de chaînes, et la raison mérite d'être connue si vous écrivez quelque chose de semblable. L'analyseur WHATWG replie une barre oblique inversée en barre oblique et supprime purement et simplement tabulations et sauts de ligne : /\evil.com et un chemin contenant une tabulation se résolvent tous deux en //evil.com, un autre hôte, à partir d'une entrée qui se lit comme un chemin relatif à la racine. Les barres obliques inversées et les espaces intégrés sont donc refusés d'emblée, et l'origine analysée a le dernier mot.

Un échec est attendu et l'annonce clairement : en next dev local, aucun Worker ne se trouve devant le site pour servir le Markdown, donc la requête revient en HTML et l'outil le signale au lieu de tendre à un modèle une page de balisage comme si c'était de la prose.

navigate_unmap_site

Ouvre une page d'unmap.dev dans l'onglet courant.

{ "path": "/fr/docs/apis/geocoding" }   // requis ; une énumération, pas du texte libre

L'argument path est une énumération JSON Schema de toutes les pages du site, et non une chaîne. Cela fait deux choses : cela documente le site auprès du modèle, qui voit où il a le droit d'aller sans deviner ; et cela rend une destination hors site ou inventée non représentable plutôt que simplement rejetée.

La liste est construite depuis le système de fichiers au moment du build : une nouvelle page de documentation y entre sans que personne ait à y penser, et une page qui n'existe pas ne peut jamais s'y trouver. En français, tout ce qui n'a pas de miroir français en est retiré, de sorte qu'un agent ne se voit jamais proposer un chemin /fr/… qui donnerait un 404.

list_unmap_map_styles

Ne prend aucun argument. Renvoie les douze styles de fond de carte, chacun en clair et en sombre, avec la valeur flavor qui le demande, plus le gabarit d'URL de style et un exemple concret, parce qu'une liste de noms seule ne suffit pas à pointer une carte vers l'un d'eux.

{
  "modes": ["light", "dark"],
  "styles": [{ "name": "base", "flavors": ["base-light", "base-dark"] }],
  "usage": {
    "styleUrl": "https://api.unmap.dev/styles/{style}.json?key={YOUR_KEY}&flavor={style}-{mode}",
    "example": "https://api.unmap.dev/styles/base.json?key=um_live_…&flavor=base-dark",
    "docs": "https://unmap.dev/fr/docs/apis/maps"
  }
}

Notez l'espace réservé {YOUR_KEY} : cet outil dit à un agent quelle forme a une URL de style, et l'agent a toujours besoin de sa propre clé pour en récupérer une. L'API de cartes en est la référence complète.

Comment se fait l'enregistrement

WebMCP est un brouillon, et l'API a occupé deux emplacements. L'aperçu anticipé de Chrome l'expose comme navigator.modelContext ; la spécification l'accroche désormais à Document. unmap regarde aux deux endroits, déduplique par identité et s'enregistre sur ce qu'il trouve.

Un navigateur qui n'a ni l'un ni l'autre est laissé entièrement tranquille. Rien n'est polyfillé et aucune variable globale n'est modifiée. L'enregistrement est toute l'intégration, et la page se comporte à l'identique sans lui.

L'enregistrement se fait aussi outil par outil, et non tout ou rien. Si une implémentation détient déjà l'un de ces noms, cet enregistrement-là est refusé et les trois autres aboutissent quand même : une surface d'outils qui apparaît à moitié est plus utile qu'une qui disparaît parce qu'une page a été rendue deux fois.

Erreurs

Un outil qui échoue renvoie son message dans un résultat ordinaire marqué comme erreur, plutôt que de lever une exception à travers la frontière. Un modèle peut lire un message renvoyé et tenter autre chose ; un rejet lui est bien moins lisible.

Ainsi read_unmap_page sur un mauvais chemin répond par une phrase qui nomme le chemin et indique à quoi ressemble un bon chemin, et navigate_unmap_site sur un chemin inconnu énumère les pages qui existent. Ni l'un ni l'autre n'est une exception.

Les outils s'enregistrent au chargement de la page ; la vérification la plus rapide est donc la console du navigateur, sur n'importe quelle page d'unmap.dev :

(navigator.modelContext ?? document.modelContext) !== undefined

Un true signifie que le navigateur dispose d'un contexte de modèle où enregistrer les outils. Ce qui y est enregistré n'est pas énumérable depuis le script de la page (le contexte de modèle est la vue de l'agent, pas celle de la page), donc la vérification observable consiste à voir si un agent connecté à l'onglet aperçoit les quatre noms.

Prochaines étapes

• Le serveur MCP pour les mêmes outils hors du navigateur, avec une clé.
• Agents pour la fiche A2A qui permet à un agent de découvrir l'API.
• La référence des API pour les points de terminaison derrière les outils.