MCP Reference: mapstools.googleapis.com

Este é um servidor MCP fornecido pela API Maps Grounding Lite. O servidor oferece ferramentas para que os desenvolvedores criem aplicativos de LLM na Plataforma Google Maps.

Um servidor do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) atua como um proxy entre um serviço externo que fornece contexto, dados ou recursos para um modelo de linguagem grande (LLM) ou um aplicativo de IA. Os servidores MCP conectam aplicativos de IA a sistemas externos, como bancos de dados e serviços da Web, traduzindo as respostas em um formato que o aplicativo de IA possa entender.

Configuração do servidor

É necessário ativar os servidores MCP e configurar a autenticação antes de usar. Para mais informações sobre como usar servidores MCP remotos do Google e do Google Cloud, consulte Visão geral dos servidores MCP do Google Cloud.

Endpoints do servidor

Um endpoint de serviço do MCP é o endereço de rede e a interface de comunicação (geralmente um URL) do servidor MCP que um aplicativo de IA (o host do cliente MCP) usa para estabelecer uma conexão segura e padronizada. É o ponto de contato para o LLM solicitar contexto, chamar uma ferramenta ou acessar um recurso. Os endpoints do MCP do Google podem ser globais ou regionais.

O servidor MCP da API Maps Grounding Lite tem o seguinte endpoint global:

  • https://mapstools.googleapis.com/mcp

Ferramentas do MCP

Uma ferramenta do MCP é uma função ou capacidade executável que um servidor MCP expõe a um LLM ou aplicativo de IA para realizar uma ação no mundo real.

Ferramentas

O servidor MCP mapstools.googleapis.com tem as seguintes ferramentas:

Ferramentas do MCP
search_places

Chame essa ferramenta quando a solicitação do usuário for encontrar lugares, empresas, endereços, locais, pontos de interesse ou qualquer outra pesquisa relacionada ao Google Maps.

Requisitos de entrada (CRÍTICO) :

  1. text_query (string – OBRIGATÓRIO) : a consulta de pesquisa principal. Ela precisa definir claramente o que o usuário está procurando.

    • Exemplos: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
    • Para detalhes específicos do lugar: inclua o atributo solicitado (por exemplo, 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  2. location_bias (objeto – OPCIONAL) : use esse parâmetro para priorizar os resultados perto de uma área geográfica específica.

    • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Uso:
      • Para direcionar a um raio de 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Para direcionar fortemente ao ponto central: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omitindo radius_meters).

  3. language_code (string – OPCIONAL) : o idioma em que o resumo dos resultados da pesquisa será mostrado.

    • Formato: um código de idioma de duas letras (ISO 639-1), opcionalmente seguido por um sublinhado e um código de país de duas letras (ISO 3166-1 alfa-2), por exemplo, en, ja, en_US, zh_CN, es_MX. Se o código de idioma não for fornecido, os resultados serão em inglês.

  4. region_code (string – OPCIONAL) : o código de região CLDR Unicode do usuário. Esse parâmetro é usado para mostrar os detalhes do lugar, como o nome específico da região, se disponível. O parâmetro pode afetar os resultados com base na lei aplicável.

    • Formato:um código de país de duas letras (ISO 3166-1 alfa-2), por exemplo, US, CA.

Instruções para a chamada de ferramenta :

  • Informações de localização (CRÍTICO): a pesquisa precisa conter informações de localização suficientes. Se o local for ambíguo (por exemplo, apenas "pizzarias"), é necessário especificá-lo na text_query (por exemplo, "pizzarias em Nova York") ou usar o parâmetro location_bias. Inclua o nome da cidade, estado/província e região/país, se necessário, para desambiguação.

  • Sempre forneça a text_query mais específica e contextual possível.

  • Use location_bias somente se as coordenadas forem fornecidas explicitamente ou se a inferência de um local do contexto conhecido de um usuário for apropriada e necessária para melhores resultados.

  • A saída fundamentada precisa ser atribuída à fonte usando as informações do campo attribution, quando disponíveis.
lookup_weather

Recupera dados meteorológicos abrangentes, incluindo condições atuais, previsões por hora e diárias.

Dados específicos disponíveis:temperatura (atual, sensação térmica, máxima/mínima, índice de calor), vento (velocidade, rajadas, direção), eventos celestiais (nascer/pôr do sol, fase da lua), precipitação (tipo, probabilidade, quantidade/QPF), condições atmosféricas (índice UV, umidade, cobertura de nuvens, probabilidade de tempestade) e endereço de localização geocodificado.

Local e regras de localização (CRÍTICO) :

O local para o qual os dados meteorológicos são solicitados é especificado usando o campo location. Esse campo é uma estrutura "oneof", o que significa que você PRECISA fornecer um valor para APENAS UM dos três subcampos de local abaixo para garantir uma pesquisa precisa de dados meteorológicos.

  1. Coordenadas geográficas (lat_lng)

    • Use quando você receber coordenadas de latitude/longitude exatas.
    • Exemplo: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // Los Angeles

  2. ID de lugar (place_id)

    • Um identificador de string não ambíguo (ID de lugar do Google Maps).
    • O place_id pode ser buscado na ferramenta search_places.
    • Exemplo: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // Torre Eiffel

  3. String de endereço (address)

    • Uma string de formato livre que exige especificidade para geocodificação.
    • Cidade e região: sempre inclua a região/país (por exemplo, "Londres, Reino Unido", não "Londres").
    • Endereço da rua: forneça o endereço completo (por exemplo, "1600 Pennsylvania Ave NW, Washington, DC").
    • Códigos postais/CEP: PRECISAM ser acompanhados de um nome de país (por exemplo, "90210, EUA", NÃO "90210").
    • Exemplo: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

Modos de uso :

  • Clima atual:forneça apenas location. Não especifique date e hour.

  • Previsão de hora em hora:forneça location, date e hour (0 a 23). Use para horários específicos (por exemplo, "às 17h") ou termos como "próximas horas" ou "mais tarde hoje". Se o usuário especificar o minuto, arredonde para a hora mais próxima. A previsão de hora em hora além de 120 horas a partir de agora não é aceita. O clima histórico por hora é aceito até 24 horas no passado.

  • Previsão diária:forneça location e date. Não especifique hour. Use para solicitações gerais do dia (por exemplo, "clima para amanhã", "clima na sexta-feira", "clima em 25/12"). Se a data de hoje não estiver no contexto, esclareça com o usuário. A previsão diária além de 10 dias, incluindo hoje, não é aceita. O clima histórico está indisponível.

Restrições de parâmetros :

  • Fusos horários: todas as entradas de date e hour precisam ser relativas ao fuso horário local do local, não ao fuso horário do usuário.
  • Formato de data:as entradas precisam ser separadas em números inteiros {year, month, day}.
  • Unidades:o padrão é METRIC. Defina units_system como IMPERIAL para Fahrenheit/Milhas se o usuário implicar padrões dos EUA ou solicitar explicitamente.

  • A saída fundamentada precisa ser atribuída à fonte usando as informações do campo attribution, quando disponíveis.
compute_routes

Calcula um trajeto de viagem entre uma origem e um destino especificados. Modos de viagem aceitos:CARRO (padrão), A PÉ.

Requisitos de entrada (CRÍTICO) : exige origem e destino. Cada um precisa ser fornecido usando um dos métodos a seguir, aninhado no respectivo campo:

  • address : (string, por exemplo, "Torre Eiffel, Paris"). Observação: quanto mais granular ou específico for o endereço de entrada, melhores serão os resultados.

  • lat_lng: : (objeto, {"latitude": número, "longitude": número})

  • place_id: : (string, por exemplo, "ChIJOwE_Id1w5EAR4Q27FkL6T_0") Observação: esse ID pode ser obtido na ferramenta search_places. Qualquer combinação de tipos de entrada é permitida (por exemplo, origem por endereço, destino por lat_lng). Se a origem ou o destino estiver ausente, é necessário pedir esclarecimentos ao usuário antes de tentar chamar a ferramenta.

Exemplo de chamada de ferramenta : {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

  • A saída fundamentada precisa ser atribuída à fonte usando as informações do campo attribution, quando disponíveis.

Receber especificações da ferramenta MCP

Para receber as especificações da ferramenta MCP de todas as ferramentas em um servidor MCP, use o método tools/list. O exemplo a seguir demonstra como usar curl para listar todas as ferramentas e especificações disponíveis no momento no servidor MCP.

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/list",
    "jsonrpc": "2.0",
    "id": 1
}'