MCP Tools Reference: mapstools.googleapis.com

Ferramenta: resolve_maps_urls

Resolve uma lista de URLs do Google Maps em IDs de lugares canônicos 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ê precisa extrair os IDs canônicos de lugar subjacentes.
  • É 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 resolvidos. Cada URL precisa ser um URL válido de um único lugar do Google Maps.

Salvar no Google Maps:

  • A resposta inclui um campo save_to_maps_url: um único link do 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, coletando lugares compartilhados em uma conversa), apresente esse link ao usuário. 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 êxito, enquanto outros falham).
  • A lista de saída de entities tem garantia de mapeamento 1:1 com os índices de entrada urls. Uma resolução de URL com falha vai 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 zero do URL com falha na solicitação. Não presuma que toda a chamada em lote falhou por causa de uma falha parcial.

O exemplo de código a seguir 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, 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)
    },
    ...
  },
  "saveToMapsUrl": string
}
Campos
entities[]

object (Entity)

Apenas saída. A lista de entidades resolvidas dos URLs do Google Maps. Garantia de mapeamento 1:1 com os índices de solicitação urls. 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 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 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 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 com 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 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 elas.

O prefixo é arbitrário, e as implementações do Protobuf devem remover tudo até o último /, inclusive, para identificar o tipo. type.googleapis.com/ é um prefixo padrão comum exigido por algumas implementações legadas. Esse prefixo não indica a origem do tipo, e não é esperado que os URIs que o contêm respondam a solicitações.

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 deve consistir apenas em caracteres alfanuméricos, escapes codificados por porcentagem e caracteres no seguinte conjunto (sem incluir as crases externas): /-.~_!$&()*+,;=. Embora permitamos codificações de porcentagem, as implementações não devem remover o escape delas para evitar confusão com analisadores atuais. Por exemplo, type.googleapis.com%2FFoo deve ser rejeitado.

No design original de Any, foi considerada a possibilidade de iniciar um serviço de resolução de tipos nesses URLs de tipo, 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 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 da seguinte maneira:

  • readOnlyHint: se for "true", a ferramenta não vai modificar o ambiente. (Padrão: falso).
  • destructiveHint: se for "true", a ferramenta poderá realizar ações destrutivas. Se for "false", a ferramenta só poderá realizar ações de adição. Padrão: verdadeiro.
  • idempotentHint: se for "true", chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente dela. (Padrão: falso).
  • openWorldHint: se for "true", a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for "false", 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 mundo aberto: ❌