MCP Tools Reference: mapstools.googleapis.com

Ferramenta: resolve_maps_urls

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

Quando chamar esta ferramenta (CRÍTICO):

  • Use esta 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 precisa extrair os IDs de lugar canônicos subjacentes.
  • É possível especificar até 20 URLs para resolver em uma única solicitação em lote.

Requisitos de entrada (CRÍTICOS):

  • urls (matriz de strings - OBRIGATÓRIO): a lista de URLs do Google Maps a serem resolvidos. Cada URL precisa ser um URL válido do Google Maps para um único lugar.

Salvar no Google Maps:

  • A resposta inclui um campo save_to_maps_url: um único link do Google Maps com todos os lugares resolvidos.
  • Quando o usuário quiser salvar, compartilhar ou abrir os lugares resolvidos como uma lista no Google Maps (por exemplo, coletar lugares compartilhados em uma conversa), apresente esse link para ele. NÃO crie esse link por conta própria.

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 com sucesso, enquanto outros falham).
  • A lista de saída de entities é garantida para mapear 1:1 com os índices de entrada urls. Uma resolução de URL com falha resultará 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 presuma que toda a chamada em lote falhou devido a uma falha parcial.

O exemplo de código abaixo mostra como usar curl para chamar 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 MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Mensagem de solicitação 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 um URL válido do Google Maps, por exemplo, https://maps.app.goo.gl/..., https://www.google.com/maps/place/... ou https://maps.google.com/.... No momento, só há suporte para URLs que apontam para um único lugar. É 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)
    },
    ...
  },
  "saveToMapsUrl": string
}
Campos
entities[]

object (Entity)

Apenas saída. A lista de entidades resolvidas dos URLs do Google Maps. É garantido que o mapeamento seja 1:1 com os índices 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 falhar, verifique o campo failed_requests para ver 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 de erro que detalha por que a resolução falhou.

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

string

Apenas saída. Um link para salvar todas as entidades resolvidas no Google Maps.

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 tipo enumerado 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 do tipo totalmente qualificado.

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

Essa string precisa conter pelo menos um caractere /, e o conteúdo após o último / 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 eles.

O prefixo é arbitrário, e as implementações do Protobuf precisam simplesmente remover tudo até o último /, inclusive, 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 os URIs que o contêm não devem responder a nenhuma solicitação.

Todas as strings de URL de tipo precisam ser referências de URI válidas 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 por porcentagem e caracteres no seguinte conjunto (não incluindo as aspas externas): /-.~_!$&()*+,;=. Embora permitamos codificações de porcentagem, as implementações não devem remover o escape delas para evitar confusão com os analisadores atuais. Por exemplo, type.googleapis.com%2FFoo deve 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 que entrar em 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 de Protobuf do tipo descrito por type_url.

Uma string codificada em base64.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um pedido de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

  • readOnlyHint: se for verdadeiro, a ferramenta não modifica o ambiente. (Padrão: falso).
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

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