MCP Tools Reference: mapstools.googleapis.com

Outil : resolve_maps_urls

Résout une liste d'URL Google Maps en ID de lieu Google Maps canoniques.

Quand appeler cet outil (CRITIQUE) :

  • Utilisez cet outil lorsque l'utilisateur fournit un ou plusieurs liens ou URL de partage Google Maps (par exemple, "https://maps.app.goo.gl/...", 'https://www.google.com/maps/place/...' ou 'https://maps.google.com/...'), vous devez extraire les ID de lieux canoniques sous-jacents.
  • Vous pouvez spécifier jusqu'à 20 URL à résoudre dans une même requête par lot.

Exigences concernant les entrées (CRITIQUES) :

  • urls (tableau de chaînes – OBLIGATOIRE) : liste des URL Google Maps à résoudre. Chaque URL doit être une URL Google Maps valide pour un seul lieu.

Enregistrer dans Google Maps :

  • La réponse inclut un champ save_to_maps_url, qui est un lien Google Maps unique contenant tous les lieux résolus.
  • Lorsque l'utilisateur souhaite enregistrer, partager ou ouvrir les lieux résolus sous forme de liste dans Google Maps (par exemple, pour collecter les lieux partagés dans une conversation), présentez-lui ce lien. NE créez PAS ce lien vous-même.

Gestion des erreurs (CRITIQUE) :

  • Il s'agit d'un outil de traitement par lot. Une requête peut renvoyer des "résultats mixtes" (par exemple, certaines URL sont résolues, tandis que d'autres échouent).
  • La liste de sortie de entities est garantie d'être mappée 1:1 avec les index d'entrée urls. Si la résolution d'une URL échoue, un message Entity vide (aucun champ n'est défini) s'affiche à l'index correspondant dans la liste entities.
  • Vous DEVEZ vérifier le champ de mappage failed_requests dans la réponse pour identifier l'index d'URL spécifique qui a échoué. La clé de failed_requests représente l'index de base 0 de l'URL ayant échoué dans la requête. Ne partez pas du principe que l'appel par lot entier a échoué en raison d'un échec partiel.

L'exemple de code suivant montre comment utiliser curl pour appeler l'outil MCP resolve_maps_urls.

Requête Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schéma d'entrée

Message de requête pour ResolveMapsUrls.

ResolveMapsUrlsRequest

Représentation JSON 
{
  "urls": [
    string
  ]
}
Champs
urls[]

string

Obligatoire. URL Google Maps à résoudre. Chaque URL doit être une URL Google Maps valide, par exemple https://maps.app.goo.gl/..., https://www.google.com/maps/place/... ou https://maps.google.com/.... Actuellement, seules les URL pointant vers un seul lieu sont acceptées. Vous pouvez spécifier jusqu'à 20 URL.

Schéma de sortie

Message de réponse pour ResolveMapsUrls.

ResolveMapsUrlsResponse

Représentation JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Champs
entities[]

object (Entity)

Uniquement en sortie. Liste des entités résolues à partir des URL Google Maps. La correspondance avec les index de la requête urls est garantie. Un message vide à l'index i (où aucun entity n'est défini) indique que la résolution a échoué pour cette URL. Si la résolution a échoué, veuillez vérifier l'état de l'erreur dans le champ failed_requests.
failedRequests

map (key: integer, value: object (Status))

Uniquement en sortie. Carte indiquant les échecs partiels pour les URL Google Maps. La clé correspond à l'index de la requête ayant échoué dans le champ urls. La valeur correspond à l'état d'erreur expliquant pourquoi la résolution a échoué.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Uniquement en sortie. Un lien permettant d'enregistrer toutes les entités résolues dans Google Maps.

Entité

Représentation JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Champs
Champ d'union entity. Type d'entité résolu. entity ne peut être qu'un des éléments suivants :
place

string

Nom de ressource du lieu résolu.

FailedRequestsEntry

Représentation JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Champs
key

integer
value

object (Status)

État

Représentation JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Champs
code

integer

Code d'état, qui doit être une valeur d'énumération de google.rpc.Code.
message

string

Message d'erreur destiné au développeur, qui doit être en anglais. Tout message d'erreur destiné aux utilisateurs doit être localisé et envoyé dans le champ google.rpc.Status.details, ou localisé par le client.
details[]

object

Liste de messages comportant les détails de l'erreur. Il existe un ensemble commun de types de message utilisable par les API.

Objet contenant des champs d'un type arbitraire. Un champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

Tous

Représentation JSON 
{
  "typeUrl": string,
  "value": string
}
Champs
typeUrl

string

Identifie le type du message Protobuf sérialisé avec une référence URI composée d'un préfixe se terminant par une barre oblique et du nom de type complet.

Exemple : type.googleapis.com/google.protobuf.StringValue

Cette chaîne doit contenir au moins un caractère /, et le contenu après le dernier / doit être le nom complet du type sous forme canonique, sans point au début. N'écrivez pas de schéma sur ces références d'URI afin que les clients ne tentent pas de les contacter.

Le préfixe est arbitraire et les implémentations Protobuf sont censées supprimer tout ce qui précède le dernier / (inclus) pour identifier le type. type.googleapis.com/ est un préfixe par défaut courant que certaines anciennes implémentations requièrent. Ce préfixe n'indique pas l'origine du type, et les URI qui le contiennent ne sont pas censés répondre aux requêtes.

Toutes les chaînes d'URL de type doivent être des références URI valides, avec la restriction supplémentaire (pour le format texte) que le contenu de la référence ne doit comporter que des caractères alphanumériques, des séquences d'échappement encodées en pourcentage et des caractères de l'ensemble suivant (sans les accents graves extérieurs) : /-.~_!$&()*+,;=. Bien que nous autorisions les encodages en pourcentage, les implémentations ne doivent pas les décoder pour éviter toute confusion avec les analyseurs existants. Par exemple, type.googleapis.com%2FFoo doit être rejeté.

Dans la conception d'origine de Any, la possibilité de lancer un service de résolution de type à ces URL de type a été envisagée, mais Protobuf n'en a jamais implémenté et considère que contacter ces URL est problématique et constitue un risque potentiel pour la sécurité. N'essayez pas de contacter les URL de type.
value

string (bytes format)

Contient une sérialisation Protobuf du type décrit par type_url.

Chaîne encodée en base64.

Annotations d'outils

Les annotations d'outil sont envoyées aux clients MCP pour décrire le risque de base d'un outil donné. La plupart des clients traitent ces indices comme non fiables, mais ils peuvent être utilisés pour déterminer quand un message de confirmation peut être envoyé à un utilisateur.

En plus de la chaîne de titre, les indications booléennes suivantes sont définies comme suit :

  • readOnlyHint : si la valeur est "true", l'outil ne modifie pas son environnement. Valeur par défaut : "false".
  • destructiveHint : si la valeur est "true", l'outil peut effectuer des actions destructrices. Si la valeur est "false", l'outil ne peut effectuer que des actions d'ajout. Valeur par défaut : "true".
  • idempotentHint : si la valeur est "true", appeler l'outil à plusieurs reprises avec les mêmes arguments n'aura aucun effet supplémentaire sur son environnement. Valeur par défaut : "false".
  • openWorldHint : si la valeur est "true", l'outil peut interagir avec un "monde ouvert" d'entités externes. Si la valeur est "false", l'outil ne peut interagir qu'avec des entités internes. Par exemple, un outil de recherche Web serait en monde ouvert, tandis qu'un outil de mémoire ne le serait pas.

Indication destructive : ❌ | Indication idempotente : ❌ | Indication en lecture seule : ✅ | Indication Open World : ❌