MCP Tools Reference: mapstools.googleapis.com

Riferimento per gli strumenti MCP:

Questo documento descrive gli endpoint API REST esterni utilizzati per richiamare gli strumenti del protocollo di contesto del modello (MCP) remoto di Google. Questa API funge da proxy sicuro tra un client HTTP esterno (come curl o un servizio web) e il server MCP interno.

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

Strumento: 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 i dettagli di un luogo specifico: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 preferenza 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), facoltativamente seguito da un trattino basso e da un codice paese di due lettere (ISO 3166-1 alpha-2), ad esempio 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.

Instructions for Tool Call:

  • Informazioni sulla posizione (CRITICHE): la ricerca deve contenere informazioni sulla posizione sufficienti. Se la posizione è ambigua (ad es. solo "pizzerie"), devi specificarla in text_query (ad es. "pizzerie a New York") o utilizza 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 esplicitamente o se dedurre una posizione dal contesto noto di un utente è appropriato e necessario per ottenere risultati migliori.

Gli esempi riportati di seguito mostrano come utilizzare curl per richiamare lo strumento MCP search_places.

Curl Request 
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": search_places,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Strumento: lookup_weather

Fornisce le condizioni attuali, le previsioni orarie e giornaliere per qualsiasi località. Utilizza questo strumento per tutte le domande relative al meteo.

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.

Requisiti di input (CRITICI):

  • Condizioni attuali:richiede solo una località (ad es. città o indirizzo). Non specificare una data o un'ora.

  • Previsioni orarie:richiedono una località e un'ora (0-23). Utilizza questa frase se l'utente chiede informazioni sul meteo a un'ora specifica o utilizzando termini come "nelle prossime ore" o "più tardi oggi".

  • Previsioni giornaliere:richiedono una località e una data completa.

Gestione delle date (CRITICO): le date e le ore fornite dall'utente DEVONO essere indicate nel fuso orario locale della località richiesta. Le date DEVONO essere suddivise in parametri interi separati: anno, mese e giorno. Il formato richiesto per questi parametri è: {"year": , "month": , "day": }

Gli esempi riportati di seguito mostrano come utilizzare curl per richiamare lo strumento MCP lookup_weather.

Curl Request 
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": lookup_weather,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Strumento: compute_routes

Calcola un itinerario di viaggio tra un'origine e una destinazione specificate. Modalità di viaggio supportate:AUTO (predefinita), A PIEDI.

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

  • address: (stringa, ad es. "Torre Eiffel, Parigi"). Nota: più granulare o specifico è l'indirizzo di input, 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"}

Gli esempi riportati di seguito mostrano come utilizzare curl per richiamare lo strumento MCP compute_routes.

Curl Request 
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": compute_routes,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'