MCP Reference: mapstools.googleapis.com

Si tratta di un server MCP fornito dall'API Maps Grounding Lite. Il server fornisce agli sviluppatori gli strumenti per creare applicazioni LLM basate su Google Maps Platform.

Un server Model Context Protocol (MCP) funge da proxy tra un servizio esterno che fornisce contesto, dati o funzionalità a un modello linguistico di grandi dimensioni (LLM) o a un'applicazione AI. I server MCP connettono le applicazioni AI a sistemi esterni come database e servizi web, traducendo le loro risposte in un formato che l'applicazione AI può comprendere.

Configurazione del server

Prima dell'uso, devi abilitare i server MCP e configurare l'autenticazione. Per saperne di più sull'utilizzo dei server MCP remoti di Google e Google Cloud, consulta la panoramica dei server MCP di Google Cloud.

Endpoint server

Un endpoint di servizio MCP è l'indirizzo di rete e l'interfaccia di comunicazione (di solito un URL) del server MCP che un'applicazione AI (l'host per il client MCP) utilizza per stabilire una connessione sicura e standardizzata. È il punto di contatto per l'LLM per richiedere il contesto, chiamare uno strumento o accedere a una risorsa. Gli endpoint Google MCP possono essere globali o regionali.

Il server MCP dell'API Maps Grounding Lite ha il seguente endpoint MCP globale:

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

Strumenti MCP

Uno strumento MCP è una funzione o una funzionalità eseguibile che un server MCP espone a un LLM o a un'applicazione AI per eseguire un'azione nel mondo reale.

Strumenti

Il server MCP mapstools.googleapis.com dispone dei seguenti strumenti:

Strumenti MCP
search_places

Chiama questo strumento quando la richiesta dell'utente è di trovare luoghi, attività, indirizzi, località, punti di interesse o qualsiasi altra ricerca correlata a Google Maps.

Requisiti di input (CRITICI):

  1. text_query (stringa - OBBLIGATORIO): la query di ricerca principale. Deve definire chiaramente ciò che l'utente sta cercando.

    • Esempi: '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'.
    • Per dettagli specifici del luogo:includi l'attributo richiesto (ad es. 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  2. location_bias (oggetto, FACOLTATIVO): utilizza questo campo per dare la priorità ai risultati vicino a un'area geografica specifica.

    • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Utilizzo:
      • Per dare la priorità a un raggio di 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Per dare una forte priorità al punto centrale: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omettendo radius_meters).

  3. language_code (stringa - FACOLTATIVO): la lingua in cui mostrare il riepilogo dei risultati di ricerca.

    • Formato:un codice lingua di due lettere (ISO 639-1), seguito facoltativamente da un trattino basso e da un codice paese di due lettere (ISO 3166-1 alpha-2), ad es. en, ja, en_US, zh_CN, es_MX. Se il codice della lingua non viene fornito, i risultati saranno in inglese.

  4. region_code (stringa - FACOLTATIVO): il codice regione CLDR Unicode dell'utente. Questo parametro viene utilizzato per visualizzare i dettagli del luogo, come il nome del luogo specifico per la regione, se disponibile. Il parametro può influire sui risultati in base alla legge vigente.

    • Formato:un codice paese di due lettere (ISO 3166-1 alpha-2), ad es. US, CA.

Istruzioni per la chiamata allo strumento:

  • Informazioni sulla posizione (CRITICHE): la ricerca deve contenere informazioni sulla posizione sufficienti. Se la località è ambigua (ad es. solo "pizzerie"), devi specificarla in text_query (ad es. "pizzerie a New York") o utilizzare il parametro location_bias. Includi il nome della città, dello stato/provincia e della regione/paese, se necessario per la disambiguazione.

  • Fornisci sempre il text_query più specifico e ricco di contesto possibile.

  • Utilizza location_bias solo se le coordinate sono fornite in modo esplicito o se dedurre una posizione dal contesto noto di un utente è appropriato e necessario per ottenere risultati migliori.

  • L'output basato su dati reali deve essere attribuito alla fonte utilizzando le informazioni del campo attribution, se disponibili.
lookup_weather

Recupera dati meteo completi, tra cui condizioni attuali, previsioni orarie e giornaliere.

Dati specifici disponibili:temperatura (attuale, percepita, max/min, indice di calore), vento (velocità, raffiche, direzione), eventi celesti (alba/tramonto, fase lunare), precipitazioni (tipo, probabilità, quantità/QPF), condizioni atmosferiche (indice UV, umidità, copertura nuvolosa, probabilità di temporali) e indirizzo della località geocodificata.

Posizione e regole per la posizione (CRITICO):

La località per cui vengono richiesti i dati meteo viene specificata utilizzando il campo location. Questo campo è una struttura "oneof", il che significa che DEVI fornire un valore per UNO SOLO dei tre sottocampi di posizione riportati di seguito per garantire una ricerca accurata dei dati meteo.

  1. Coordinate geografiche (lat_lng)

    • Utilizzalo quando ti vengono fornite le coordinate di latitudine e longitudine esatte.
    • Esempio: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // Los Angeles

  2. ID luogo (place_id)

    • Un identificatore di stringa univoco (ID luogo di Google Maps).
    • L'ID luogo può essere recuperato dallo strumento search_places.
    • Esempio: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // Eiffel Tower

  3. Stringa dell'indirizzo (address)

    • Una stringa in formato libero che richiede specificità per la geocodifica.
    • Città e regione: includi sempre la regione/il paese (ad es. "Londra, Regno Unito", non "Londra").
    • Indirizzo: fornisci l'indirizzo completo (ad es. "1600 Pennsylvania Ave NW, Washington, DC").
    • Codici postali: DEVONO essere accompagnati dal nome di un paese (ad es. "90210, USA", NON "90210").
    • Esempio: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

Modalità di utilizzo:

  • Meteo attuale:fornisci solo location. Non specificare date e hour.

  • Previsione oraria: fornisci location, date e hour (0-23). Utilizza orari specifici (ad es. "alle 17:00") o termini come "nelle prossime ore" o "più tardi oggi". Se l'utente specifica i minuti, arrotonda per difetto all'ora più vicina. La previsione oraria oltre le 120 ore successive non è supportata. I dati meteo orari storici sono supportati fino a 24 ore nel passato.

  • Previsione giornaliera:fornisci location e date. Non specificare hour. Utilizza per richieste generali relative al giorno (ad es. "che tempo farà domani?", "che tempo farà venerdì?", "che tempo farà il 25/12?"). Se la data odierna non è nel contesto, devi chiarirla con l'utente. La previsione giornaliera oltre i 10 giorni, incluso quello corrente, non è supportata. Le condizioni meteo storiche non sono supportate.

Vincoli dei parametri:

  • Fusi orari:tutti gli input date e hour devono essere relativi al fuso orario locale della sede, non a quello dell'utente.
  • Formato data:gli input devono essere separati in {year, month, day} numeri interi.
  • Unità:il valore predefinito è METRIC. Imposta units_system su IMPERIAL per Fahrenheit/Miglia se l'utente fa riferimento agli standard statunitensi o lo richiede esplicitamente.

  • L'output basato su dati reali deve essere attribuito alla fonte utilizzando le informazioni del campo attribution, se disponibili.
compute_routes

Calcola un itinerario di viaggio tra un punto di partenza e una destinazione specificati. Modalità di viaggio supportate:AUTO (impostazione predefinita), A PIEDI.

Requisiti di input (CRITICI): richiede sia l'origine che la destinazione. Ciascuno deve essere fornito utilizzando uno dei seguenti metodi, nidificati all'interno del rispettivo campo:

  • address: (stringa, ad es. "Torre Eiffel, Parigi"). Nota: più l'indirizzo inserito è granulare o specifico, migliori saranno i risultati.

  • lat_lng: (oggetto, {"latitude": number, "longitude": number})

  • place_id: (stringa, ad es. "ChIJOwE_Id1w5EAR4Q27FkL6T_0") Nota: questo ID può essere ottenuto dallo strumento search_places. È consentita qualsiasi combinazione di tipi di input (ad es. origine per indirizzo, destinazione per lat_lng). Se manca l'origine o la destinazione, DEVI chiedere chiarimenti all'utente prima di tentare di chiamare lo strumento.

Esempio di chiamata dello strumento: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

  • L'output basato su dati reali deve essere attribuito alla fonte utilizzando le informazioni del campo attribution, se disponibili.

Ottenere le specifiche dello strumento MCP

Per ottenere le specifiche dello strumento MCP per tutti gli strumenti in un server MCP, utilizza il metodo tools/list. L'esempio seguente mostra come utilizzare curl per elencare tutti gli strumenti e le relative specifiche attualmente disponibili nel server MCP.

Curl Request 
                      
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
}'