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/...") et que vous devez extraire les ID de lieu canoniques sous-jacents.
  • Vous pouvez spécifier jusqu'à 20 URL à résoudre dans une même requête par lot.

Exigences d'entrée (CRITIQUES) :

  • urls (tableau de chaînes, OBLIGATOIRE) : liste des URL Google Maps à résoudre. Chaque URL doit être une URL Google Maps valide et ne correspondre qu'à un seul lieu.

Enregistrer dans Google Maps

  • La réponse inclut un champ save_to_maps_url : un seul lien Google Maps contenant tous les lieux résolus avec succès.
  • 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 exceptions (CRITIQUE) :

  • Il s'agit d'un outil de traitement par lot. Une requête peut renvoyer des "résultats mitigés" (par exemple, certaines URL sont résolues, mais d'autres échouent).
  • La liste de sortie de entities est garantie de correspondre à 1:1 avec les indices urls d'entrée. L'échec de la résolution d'une URL entraîne un message Entity vide (aucun champ n'est défini) à 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'intégralité de l'appel par lot 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. Correspondance garantie 1:1 avec les indices urls de la requête. 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 le champ failed_requests pour connaître l'état de l'erreur.
failedRequests

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

Uniquement en sortie. Mappage communiquant les échecs partiels pour les URL Google Maps. La clé est l'index de la requête ayant échoué dans le champ urls. La valeur est l'état d'erreur détaillant la raison de l'échec de la résolution.

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 correctement 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 d'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 de début. N'écrivez pas de schéma sur ces références d'URI afin que les clients n'essaient pas de les contacter.

Le préfixe est arbitraire et les implémentations Protobuf sont censées simplement supprimer tout ce qui précède et inclut le dernier / pour identifier le type. type.googleapis.com/ est un préfixe par défaut courant requis par certaines anciennes implémentations. 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 d'URI légales avec la restriction supplémentaire (pour le format texte) que le contenu de la référence ne doit être composé que de caractères alphanumériques, de caractères d'échappement encodés en pourcentage et de caractères de l'ensemble suivant (sans inclure les accents graves externes) : /-.~_!$&()*+,;=. Bien que nous autorisions les encodages en pourcentage, les implémentations ne doivent pas les déséchapper 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 types à 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 problème de sécurité potentiel. 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 considèrent ces indications comme non fiables, mais elles peuvent être utilisées pour décider quand envoyer une invite de confirmation à un utilisateur.

En plus de la chaîne de titre, les indices booléens suivants sont définis 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", l'appel répété de l'outil 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 sur le Web serait en monde ouvert, tandis qu'un outil de mémoire ne le serait pas.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌