MCP Tools Reference: mapstools.googleapis.com

Ferramenta: resolve_maps_urls

Resolve uma lista de URLs do Google Maps em IDs canônicos de lugares do Google Maps.

Quando chamar essa ferramenta (CRÍTICO) :

  • Use essa ferramenta quando o usuário fornecer um ou mais links ou URLs de compartilhamento do Google Maps (por exemplo, "https://maps.app.goo.gl/...", "https://www.google.com/maps/place/..." ou "https://maps.google.com/...") e você precisar extrair os IDs canônicos de lugares.
  • É possível especificar até 20 URLs para resolver em uma única solicitação em lote.

Requisitos de entrada (CRÍTICO) :

  • urls (matriz de strings – OBRIGATÓRIO) : a lista de URLs do Google Maps a serem resolvidas. Cada URL precisa ser válida e de um único lugar do Google Maps.

Tratamento de erros (CRÍTICO) :

  • Essa é uma ferramenta de processamento em lote. Uma solicitação pode retornar "resultados mistos" (por exemplo, alguns URLs são resolvidos, enquanto outros falham).
  • A lista de saída de entities tem uma correspondência de 1:1 com os índices de urls de entrada. Uma resolução de URL com falha resulta em uma mensagem Entity vazia (nenhum campo é definido) no índice correspondente na lista entities.
  • Você PRECISA verificar o campo de mapa failed_requests na resposta para identificar qual índice de URL específico falhou. A chave de failed_requests representa o índice com base em 0 do URL com falha na solicitação. Não suponha que toda a chamada em lote falhou devido a uma falha parcial.

O exemplo a seguir demonstra como usar curl para invocar a ferramenta MCP resolve_maps_urls.

Solicitação 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 tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Solicita uma mensagem para ResolveMapsUrls.

ResolveMapsUrlsRequest

Representação JSON 
{
  "urls": [
    string
  ]
}
Campos
urls[]

string

Obrigatório. Os URLs do Google Maps a serem resolvidos. Cada URL precisa ser válida do Google Maps, por exemplo, https://maps.app.goo.gl/..., https://www.google.com/maps/place/..., ou https://maps.google.com/.... No momento, apenas URLs que apontam para um único lugar são aceitos. É possível especificar até 20 URLs.

Esquema de saída

Mensagem de resposta para ResolveMapsUrls.

ResolveMapsUrlsResponse

Representação JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Campos
entities[]

object (Entity)

Apenas saída. A lista de entidades resolvidas dos URLs do Google Maps. Tem uma correspondência de 1:1 com os índices de urls da solicitação. Uma mensagem vazia no índice i (em que nenhum entity está definido) indica que a resolução falhou para esse URL. Se a resolução falhou, verifique o campo failed_requests para conferir o status do erro.
failedRequests

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

Apenas saída. Um mapa que comunica falhas parciais para os URLs do Google Maps. A chave é o índice da solicitação com falha no campo urls. O valor é o status do erro que detalha por que a resolução falhou.

Um objeto com uma lista de "key": value pares. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Entidade

Representação 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ão entity. O tipo de entidade resolvido. entity pode ser apenas de um dos tipos a seguir:
place

string

O nome do recurso do lugar resolvido.

FailedRequestsEntry

Representação JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Campos
key

integer
value

object (Status)

Status

Representação JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

O código de status, que precisa ser um valor de enumeração de google.rpc.Code.
message

string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro para o usuário precisa ser localizada e enviada no campo google.rpc.Status.details, ou localizada pelo cliente.
details[]

object

Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Qualquer

Representação JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Identifica o tipo da mensagem Protobuf serializada com uma referência de URI que consiste em um prefixo que termina em uma barra e o nome de tipo totalmente qualificado.

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

Essa string precisa conter pelo menos um caractere /, e o conteúdo após a última / precisa ser o nome totalmente qualificado do tipo na forma canônica, sem um ponto inicial. Não escreva um esquema nessas referências de URI para que os clientes não tentem entrar em contato com elas.

O prefixo é arbitrário, e as implementações do Protobuf precisam remover tudo até a última / para identificar o tipo. type.googleapis.com/ é um prefixo padrão comum que algumas implementações legadas exigem. Esse prefixo não indica a origem do tipo, e não é esperado que URIs que o contenham respondam a nenhuma solicitação.

Todas as strings de URL de tipo precisam ser referências de URI legais com a restrição adicional (para o formato de texto) de que o conteúdo da referência precisa consistir apenas em caracteres alfanuméricos, escapes codificados em porcentagem e caracteres no conjunto a seguir (sem incluir as aspas externas): /-.~_!$&()*+,;=. Embora permitamos codificações de porcentagem, as implementações não devem fazer o escape delas para evitar confusão com analisadores existentes. Por exemplo, type.googleapis.com%2FFoo precisa ser rejeitado.

No design original de Any, a possibilidade de iniciar um serviço de resolução de tipo nesses URLs de tipo foi considerada, mas o Protobuf nunca implementou um e considera o contato com esses URLs problemático e um possível problema de segurança. Não tente entrar em contato com URLs de tipo.
value

string (bytes format)

Contém uma serialização Protobuf do tipo descrito por type_url.

Uma string codificada em base64.

Anotações da ferramenta

Dica destrutiva: ❌ | Dica idempotente: ❌ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌