MCP Reference: mapstools.googleapis.com

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 collegano 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.

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

Endpoint server

Un endpoint di servizio MCP è l'indirizzo di rete e l'interfaccia di comunicazione (in genere 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 MCP di Google possono essere globali o regionali.

Il server MCP mapstools.googleapis.com ha il seguente endpoint MCP:

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

Strumenti MCP

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

Il server MCP mapstools.googleapis.com ha i 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 - OBBLIGATORIA): 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 sul 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 parametro 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 la priorità al punto centrale: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omettendo radius_meters).

  3. language_code (stringa - FACOLTATIVA): 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 lingua non viene fornito, i risultati saranno in inglese.

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

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

Istruzioni per la chiamata dello strumento:

  • Informazioni sulla località (CRITICHE): la ricerca deve contenere informazioni sufficienti sulla località. 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. Se necessario per la disambiguazione, includi il nome della città, dello stato/provincia e della regione/del paese.

  • Fornisci sempre la text_query più specifica e ricca di contesto possibile.

  • Utilizza location_bias solo se le coordinate vengono fornite esplicitamente o se è appropriato e necessario dedurre una località dal contesto noto di un utente per ottenere risultati migliori.
lookup_weather

Recupera dati meteo completi, incluse le condizioni attuali, le previsioni orarie e giornaliere.

Dati specifici disponibili: temperatura (attuale, percepita, massima/minima, 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.

Località e regole per la località (CRITICHE):

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 della località 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/longitudine esatte.
    • Esempio: "lat_lng": { "latitude": 34.0522, "longitude": -118.2437 } // Los Angeles

  2. ID luogo (place_id)

    • Un identificatore di stringa non ambiguo (ID luogo di Google Maps).
    • Il place_id può essere recuperato dallo strumento search_places.
    • Esempio: "place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0" // Eiffel Tower

  3. Stringa di 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 stradale: 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").

Modalità di utilizzo:

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

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

  3. Previsione giornaliera: fornisci location e date. Non specificare hour. Utilizza per le richieste generali del giorno (ad es. "meteo per domani", "meteo di venerdì", "meteo del 25/12"). Se la data di oggi non è nel contesto, devi chiarirla con l'utente. La previsione giornaliera oltre i 10 giorni, incluso oggi, non è supportata. Il meteo storico non è supportato.

Vincoli dei parametri:

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

Calcola un percorso di viaggio tra un'origine e una destinazione specificate. Modalità di viaggio supportate: DRIVE (impostazione predefinita), WALK.

Requisiti di input (CRITICI): richiede sia origine che destinazione. Ciascuna deve essere fornita utilizzando uno dei seguenti metodi, nidificati nel rispettivo campo:

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

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

  • 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"}

Ottenere le specifiche degli strumenti MCP

Per ottenere le specifiche degli strumenti 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.

Richiesta 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
}'