MCP Tools Reference: mapstools.googleapis.com

Herramienta: resolve_maps_urls

Resuelve una lista de URLs de Google Maps en IDs de lugar canónicos de Google Maps.

Cuándo llamar a esta herramienta (CRÍTICO):

  • Usa esta herramienta cuando el usuario proporcione una o más URLs o vínculos para compartir de Google Maps (p.ej., "https://maps.app.goo.gl/...", 'https://www.google.com/maps/place/...' o 'https://maps.google.com/...') y necesitas extraer los IDs de lugar canónicos subyacentes.
  • Puedes especificar hasta 20 URLs para resolver en una sola solicitud por lotes.

Requisitos de entrada (CRUCIALES):

  • urls (array de cadenas, OBLIGATORIO): Es la lista de URLs de Google Maps que se deben resolver. Cada URL debe ser una URL válida de Google Maps que dirija a un solo lugar.

Cómo guardar en Google Maps:

  • La respuesta incluye un campo save_to_maps_url, que es un solo vínculo de Google Maps que contiene todos los lugares resueltos correctamente.
  • Cuando el usuario quiera guardar, compartir o abrir los lugares resueltos como una lista en Google Maps (p.ej., recopilar lugares compartidos en una conversación), preséntale este vínculo. NO construyas este vínculo por tu cuenta.

Manejo de errores (CRÍTICO):

  • Esta es una herramienta de procesamiento por lotes. Una solicitud puede devolver "resultados mixtos" (p.ej., algunas URLs se resuelven correctamente, mientras que otras fallan).
  • Se garantiza que la lista de salida de entities se asigne 1:1 con los índices de urls de entrada. Si falla la resolución de la URL, se generará un mensaje Entity vacío (no se establecen campos) en el índice correspondiente de la lista entities.
  • DEBES verificar el campo de mapa failed_requests en la respuesta para identificar qué índice de URL específico falló. La clave de failed_requests representa el índice basado en 0 de la URL con errores en la solicitud. No asumas que toda la llamada por lotes falló debido a un error parcial.

En la siguiente muestra de código, se indica cómo usar curl para llamar a la herramienta de MCP resolve_maps_urls.

Solicitud de 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
}'

Esquema de entrada

Mensaje de solicitud para ResolveMapsUrls.

ResolveMapsUrlsRequest

Representación JSON 
{
  "urls": [
    string
  ]
}
Campos
urls[]

string

Obligatorio. Son las URLs de Google Maps que se resolverán. Cada URL debe ser una URL válida de Google Maps, por ejemplo, https://maps.app.goo.gl/..., https://www.google.com/maps/place/... o https://maps.google.com/.... Actualmente, solo se admiten las URLs que dirigen a un solo lugar. Puedes especificar hasta 20 URLs.

Esquema de salida

Es el mensaje de respuesta para ResolveMapsUrls.

ResolveMapsUrlsResponse

Representación JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Campos
entities[]

object (Entity)

Solo salida. Es la lista de entidades resueltas de las URLs de Google Maps. Se garantiza que se asignarán en una relación de 1:1 con los índices urls de la solicitud. Un mensaje vacío en el índice i (en el que no se establece ningún entity) indica que la resolución falló para esa URL. Si la resolución falló, verifica el campo failed_requests para ver el estado del error.
failedRequests

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

Solo salida. Es un mapa que comunica las fallas parciales de las URLs de Google Maps. La clave es el índice de la solicitud con errores en el campo urls. El valor es el estado de error que detalla por qué falló la resolución.

Un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Solo salida. Un vínculo para guardar todas las entidades resueltas correctamente en Google Maps

Entidad

Representación JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Campos
Campo de unión entity. Es el tipo de entidad resuelto. entity puede ser solo uno de los parámetros siguientes:
place

string

Es el nombre del recurso del lugar resuelto.

FailedRequestsEntry

Representación JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Campos
key

integer
value

object (Status)

Estado

Representación JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

El código de estado, que debe ser un valor enum de google.rpc.Code.
message

string

Un mensaje de error dirigido al desarrollador, que debe estar en inglés. Cualquier mensaje de error dirigido al usuario debe localizarse y enviarse al campo google.rpc.Status.details; o el cliente debe localizarlo.
details[]

object

Una lista de mensajes que contienen los detalles del error. Hay un conjunto común de tipos de mensajes para que usen las API.

Un objeto que contiene campos de un tipo arbitrario. Un campo adicional "@type" contiene una URI que identifica el tipo. Ejemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Cualquiera

Representación JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Identifica el tipo de mensaje de Protobuf serializado con una referencia de URI que consta de un prefijo que termina en una barra diagonal y el nombre de tipo completamente calificado.

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

Esta cadena debe contener al menos un carácter /, y el contenido después del último / debe ser el nombre completamente calificado del tipo en formato canónico, sin un punto inicial. No escribas un esquema en estas referencias de URI para que los clientes no intenten comunicarse con ellos.

El prefijo es arbitrario y se espera que las implementaciones de Protobuf simplemente quiten todo hasta el último /, incluido este, para identificar el tipo. type.googleapis.com/ es un prefijo predeterminado común que requieren algunas implementaciones heredadas. Este prefijo no indica el origen del tipo, y no se espera que los URI que lo contienen respondan a ninguna solicitud.

Todas las cadenas de URL de tipo deben ser referencias de URI legales con la restricción adicional (para el formato de texto) de que el contenido de la referencia debe constar solo de caracteres alfanuméricos, escapes codificados con porcentaje y caracteres del siguiente conjunto (sin incluir las comillas simples exteriores): /-.~_!$&()*+,;=. A pesar de que permitimos las codificaciones porcentuales, las implementaciones no deben quitarles el escape para evitar confusiones con los analizadores existentes. Por ejemplo, se debería rechazar type.googleapis.com%2FFoo.

En el diseño original de Any, se consideró la posibilidad de lanzar un servicio de resolución de tipos en estas URLs de tipo, pero Protobuf nunca implementó uno y considera que comunicarse con estas URLs es problemático y un posible problema de seguridad. No intentes comunicarte con las URLs de tipo.
value

string (bytes format)

Contiene una serialización de Protobuf del tipo que se describe en type_url.

String codificada en base64.

Anotaciones de herramientas

Las anotaciones de herramientas se envían a los clientes de MCP para describir el riesgo básico de una herramienta determinada. La mayoría de los clientes tratan estas sugerencias como no confiables, pero se pueden usar para decidir cuándo se puede enviar un mensaje de confirmación a un usuario.

Junto con la cadena de título, las siguientes sugerencias booleanas se definen de la siguiente manera:

  • readOnlyHint: Si es verdadero, la herramienta no modifica su entorno. Valor predeterminado: false.
  • destructiveHint: Si es verdadero, la herramienta puede realizar acciones destructivas. Si es falso, la herramienta solo puede realizar acciones aditivas. Valor predeterminado: true.
  • idempotentHint: Si es verdadero, llamar a la herramienta de forma repetida con los mismos argumentos no tendrá ningún efecto adicional en su entorno. Valor predeterminado: false.
  • openWorldHint: Si es verdadero, la herramienta puede interactuar con un "mundo abierto" de entidades externas. Si es falso, la herramienta solo puede interactuar con entidades internas. Por ejemplo, una herramienta de búsqueda web sería de mundo abierto, mientras que una herramienta de memoria no lo sería.

Sugerencia destructiva: ❌ | Sugerencia idempotente: ❌ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌