MCP Tools Reference: mapstools.googleapis.com

Narzędzie: search_places

Wywołaj to narzędzie, gdy użytkownik prosi o znalezienie miejsc, firm, adresów, lokalizacji, ciekawych miejsc lub o inne wyszukiwanie związane z Mapami Google.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

1. text_query (ciąg znaków – WYMAGANY): główne zapytanie. Musi on jasno określać, czego szuka użytkownik.

   • Przykłady: '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'.
   • Aby uzyskać informacje o miejscu: dodaj wymagany atrybut (np. 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

2. location_bias (obiekt – OPCJONALNY): użyj tego parametru, aby nadać priorytet wynikom w pobliżu określonego obszaru geograficznego.

   • Format: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Wykorzystanie:
     • Aby ustawić promień 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • Aby silnie przesunąć środek: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (pomijając radius_meters).

3. language_code (ciąg znaków – OPCJONALNY): język, w którym ma być wyświetlane podsumowanie wyników wyszukiwania.

   • Format: dwuliterowy kod języka (ISO 639-1), po którym opcjonalnie następuje podkreślenie i dwuliterowy kod kraju (ISO 3166-1 alfa-2), np. en, ja, en_US, zh_CN, es_MX. Jeśli nie podasz kodu języka, wyniki będą w języku angielskim.

4. region_code (ciąg znaków – OPCJONALNY): kod regionu CLDR Unicode użytkownika. Ten parametr służy do wyświetlania informacji o miejscu, takich jak nazwa miejsca w danym regionie, jeśli jest dostępna. Parametr może wpływać na wyniki zgodnie z obowiązującymi przepisami.

   • Format: dwuliterowy kod kraju (ISO 3166-1 alfa-2), np. US, CA.

5. page_size (liczba całkowita – OPCJONALNA): maksymalna liczba miejsc do zwrócenia, od 1 do 10. Domyślna wartość to 5. Ustaw wartość powyżej 5 tylko wtedy, gdy użytkownik chce porównać więcej niż 5 miejsc. Wartości od 6 do 10 wiążą się z wyższymi kosztami i większymi opóźnieniami.

6. include_extended_details (wartość logiczna – OPCJONALNA): ustaw to pole na true, gdy żądanie użytkownika wymaga szczegółowych statystyk jakościowych, dynamiki w czasie rzeczywistym lub specjalistycznych atrybutów encji. Domyślna wartość to false. Ustawienie wartości true wiąże się z wyższymi kosztami i dłuższym czasem oczekiwania.

Instrukcje dotyczące wywołania narzędzia:

• Informacje o lokalizacji (KRYTYCZNE): wyszukiwanie musi zawierać wystarczające informacje o lokalizacji. Jeśli lokalizacja jest niejednoznaczna (np. „pizzerie”), musisz określić ją w parametrze text_query (np. „pizzerie w Nowym Jorku”) lub użyć parametru location_bias. Jeśli jest to konieczne, podaj nazwę miasta, stanu/prowincji i regionu/kraju w celu uściślenia.

• Zawsze podawaj jak najbardziej szczegółowe i bogate w kontekst text_query.

• Używaj location_bias tylko wtedy, gdy współrzędne są wyraźnie podane lub gdy określenie lokalizacji na podstawie znanego kontekstu użytkownika jest odpowiednie i konieczne do uzyskania lepszych wyników.

• Odpowiedź oparta na źródłach musi być przypisana do źródła za pomocą informacji z pola attribution, jeśli są dostępne.

Poniższy przykładowy kod pokazuje, jak używać curl do wywoływania narzędzia MCP search_places.

Schemat wejściowy

{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "includeExtendedDetails": boolean,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}

{
  "circle": {
    object (Circle)
  }
}

{
  "center": {
    object (LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}

{
  "latitude": number,
  "longitude": number
}

Schemat wyjściowy

{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "contentToken": string
}

{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}

{
  "latitude": number,
  "longitude": number
}

{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}

{
  "title": string,
  "url": string
}

Adnotacje dotyczące narzędzi

Adnotacje narzędzi są wysyłane do klientów MCP, aby opisać podstawowe ryzyko związane z danym narzędziem. Większość klientów traktuje te wskazówki jako niezaufane, ale można ich użyć do określenia, kiedy wysłać użytkownikowi prośbę o potwierdzenie.

Oprócz ciągu tytułu zdefiniowane są te wskazówki logiczne:

• readOnlyHint: jeśli ma wartość „true”, narzędzie nie modyfikuje swojego środowiska. Wartość domyślna: false.
• destructiveHint: jeśli ma wartość „true”, narzędzie może wykonywać działania destrukcyjne. Jeśli ma wartość false, narzędzie może wykonywać tylko działania dodawania. Wartość domyślna: true.
• idempotentHint: jeśli ma wartość „true”, wielokrotne wywoływanie narzędzia z tymi samymi argumentami nie będzie miało dodatkowego wpływu na jego środowisko. Wartość domyślna: false.
• openWorldHint: jeśli ma wartość true, narzędzie może wchodzić w interakcje z „otwartym światem” podmiotów zewnętrznych. Jeśli ma wartość false, narzędzie może wchodzić w interakcje tylko z elementami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie jest narzędziem typu Otwarty świat, a narzędzie do zapamiętywania – nie.

Wskazówka dotycząca niszczenia: ❌ | Wskazówka dotycząca idempotencji: ❌ | Wskazówka dotycząca tylko do odczytu: ✅ | Wskazówka dotycząca otwartego świata: ❌