MCP Tools Reference: mapstools.googleapis.com

Narzędzie: resolve_names

Rozwiązuje listę zapytań o konkretne lokalizacje (nazwy punktów orientacyjnych lub dokładne adresy) na kanoniczne identyfikatory miejsc w Mapach Google.

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

  1. queries (tablica obiektów – WYMAGANE): lista zapytań o lokalizację do rozwiązania. Możesz określić maksymalnie 20 zapytań.

    • Każdy obiekt zapytania musi zawierać:
      • text (ciąg znaków – WYMAGANY): zapytanie tekstowe reprezentujące konkretną nazwę miejsca lub adres do rozwiązania.
        • Przykłady: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'

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

    • Format: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (ciąg znaków – OPCJONALNIE): kod regionu CLDR w Unicode (dwuliterowy kod kraju, np. US, CA) użytkownika, który ma wpłynąć na wyniki.

Instrukcje dotyczące wywołania narzędzia:

  • Szczegółowość (KRYTYCZNA): zapytania muszą zawierać konkretną nazwę miejsca lub adres. Ogólne wyszukiwania, takie jak 'restaurants', lub nazwy sieci, takie jak 'Starbucks', nie są obsługiwane.
  • NIE wywołuj tego narzędzia, jeśli narzędzia podrzędne, których chcesz użyć, akceptują już bezpośrednio ciągi znaków z adresem lub nazwą miejsca.

Zapisz w Mapach Google:

  • Odpowiedź zawiera pole save_to_maps_url: pojedynczy link do Map Google zawierający wszystkie miejsca, które udało się rozpoznać.
  • Gdy użytkownik chce zapisać, udostępnić lub otworzyć rozwiązane miejsca jako listę w Mapach Google, wyświetl mu ten link. NIE twórz tego linku samodzielnie.

Obsługa błędów (KRYTYCZNA):

  • Jest to narzędzie do przetwarzania wsadowego. Żądanie może zwrócić „mieszane wyniki” (np. niektóre zapytania zostaną rozwiązane, a inne nie).
  • Lista wyjściowa results jest gwarantowana do mapowania 1:1 z indeksami wejściowymi queries. Nieudane zapytanie spowoduje, że w odpowiednim indeksie na liście results pojawi się pusta wiadomość Result (bez ustawionego parametru entity).
  • MUSISZ sprawdzić pole failed_requests map w odpowiedzi, aby określić, który indeks zapytania nie działa. Klucz failed_requests reprezentuje indeks nieudanego zapytania w żądaniu (liczony od zera). Nie zakładaj, że całe wywołanie wsadowe nie powiodło się z powodu częściowej awarii.

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

Żądanie Curl 
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": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schemat wejściowy

Wiadomość żądania dla ResolveNames.

ResolveNamesRequest

Zapis JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Pola
queries[]

object (LocationQuery)

Wymagane. Lista zapytań o lokalizację do rozwiązania. Możesz określić maksymalnie 20 zapytań.
locationBias

object (LocationBias)

Opcjonalnie: Opcjonalny region, który ma wpływać na wyniki rozpoznawania. Jeśli jest określony, wyniki rozpoznawania będą bardziej ukierunkowane na podmioty znajdujące się bliżej tego regionu. Użycie symbolu location_bias lub region_code często daje lepsze wyniki, ponieważ zawęża przestrzeń wyszukiwania.

Jeśli określono zarówno location_bias, jak i region_code, pierwszeństwo ma location_bias.region_code
regionCode

string

Opcjonalnie: Opcjonalny kod regionu, który ma wpływać na wyniki rozpoznawania. Jeśli zostanie określony, wyniki rozpoznawania będą bardziej ukierunkowane na podmioty znajdujące się w określonym regionie lub w jego pobliżu. Powinien to być kod regionu CLDR. Na przykład „US” lub „CA”. Użycie symbolu location_bias lub region_code często daje lepsze wyniki, ponieważ zawęża przestrzeń wyszukiwania.

Jeśli określono zarówno location_bias, jak i region_code, pierwszeństwo ma location_bias.region_code

LocationQuery

Zapis JSON 
{
  "text": string
}
Pola
text

string

Wymagane. Zapytanie tekstowe, które ma zostać przekształcone w konkretny obiekt geoprzestrzenny w Mapach Google, np. miejsce lub adres. Im bardziej szczegółowe zapytanie, tym dokładniejsze rozwiązanie. Na przykład „San Francisco”, „Googleplex, Mountain View, CA”, „1600 Amphitheatre Parkway, Mountain View, CA” lub „Wieża Eiffla, Paryż”. Zapytania muszą zawierać konkretny adres lub nazwę miejsca. Ogólne lokalizacje, takie jak nazwa sieci (np. Starbucks) lub zapytanie „restauracje”, nie są obsługiwane.

LocationBias

Zapis JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Pola
Pole zbiorcze type. Typ odchylenia lokalizacji. type może mieć tylko jedną z tych wartości:
viewport

object (Viewport)

Widoczny obszar zdefiniowany przez ramkę ograniczającą.

Widoczny obszar

Zapis JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Pola
low

object (LatLng)

Wymagane. Najniższy punkt widocznego obszaru.
high

object (LatLng)

Wymagane. Najwyższy punkt widocznego obszaru.

LatLng

Zapis JSON 
{
  "latitude": number,
  "longitude": number
}
Pola
latitude

number

Szerokość geograficzna w stopniach. Musi mieścić się w zakresie od –90,0 do +90,0.
longitude

number

Długość geograficzna w stopniach. Musi mieścić się w zakresie od –180,0 do +180,0.

Schemat wyjściowy

Wiadomość z odpowiedzią dla ResolveNames.

ResolveNamesResponse

Zapis JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Pola
results[]

object (Result)

Tylko dane wyjściowe. Lista rozpoznanych podmiotów z zapytań o lokalizację. Gwarantowane mapowanie 1:1 z indeksami żądania queries. Pusty ciąg na pozycji i oznacza, że rozpoznawanie nie powiodło się w przypadku tego zapytania. Jeśli rozpoznanie się nie powiodło, sprawdź pole failed_requests, aby poznać stan błędu.
failedRequests

map (key: integer, value: object (Status))

Tylko dane wyjściowe. Mapa informująca o częściowych niepowodzeniach. Kluczem jest indeks nieudanego żądania w polu queries. Wartość to stan błędu, który zawiera szczegółowe informacje o tym, dlaczego rozpoznanie się nie powiodło.

Obiekt zawierający listę par "key": value. Przykład: { "name": "wrench", "mass": "1.3kg", "count": "3" }
saveToMapsUrl

string

Tylko dane wyjściowe. link do zapisania wszystkich prawidłowo rozwiązanych encji w Mapach Google;

Wynik

Zapis JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Pola
entity

object (Entity)

Tylko dane wyjściowe. Rozwiązana encja z zapytania o lokalizację.
confidence

enum (Confidence)

Tylko dane wyjściowe. Poziom ufności rozwiązania.

Jednostka

Zapis JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Pola
Pole zbiorcze entity. Rozwiązany typ elementu. entity może mieć tylko jedną z tych wartości:
place

string

Nazwa zasobu rozpoznanego miejsca.

FailedRequestsEntry

Zapis JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Pola
key

integer
value

object (Status)

Stan

Zapis JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Pola
code

integer

Kod stanu, który powinien być wartością wyliczeniową google.rpc.Code.
message

string

Komunikat o błędzie widoczny dla programisty, który powinien być w języku angielskim. Wszelkie komunikaty o błędach dla użytkowników powinny być zlokalizowane i wysyłane w polu google.rpc.Status.details lub zlokalizowane przez klienta.
details[]

object

Lista wiadomości zawierających szczegóły błędu. Na potrzeby interfejsów API dostępny jest wspólny zestaw typów wiadomości.

Obiekt zawierający pola dowolnego typu. Dodatkowe pole "@type" zawiera identyfikator URI określający typ. Przykład: { "id": 1234, "@type": "types.example.com/standard/id" }

Dowolna

Zapis JSON 
{
  "typeUrl": string,
  "value": string
}
Pola
typeUrl

string

Określa typ serializowanego komunikatu Protobuf za pomocą odwołania URI składającego się z prefiksu kończącego się ukośnikiem i pełnej nazwy typu.

Przykład: type.googleapis.com/google.protobuf.StringValue

Ten ciąg znaków musi zawierać co najmniej 1 znak /, a treść po ostatnim znaku / musi być w pełni kwalifikowaną nazwą typu w formie kanonicznej, bez kropki na początku. Nie wpisuj schematu w tych odwołaniach do URI, aby klienci nie próbowali się z nimi kontaktować.

Prefiks jest dowolny, a implementacje Protobuf powinny po prostu usuwać wszystko aż do ostatniego znaku / włącznie, aby zidentyfikować typ. type.googleapis.com/ to typowy domyślny prefiks, który jest wymagany w przypadku niektórych starszych implementacji. Ten prefiks nie wskazuje pochodzenia typu, a identyfikatory URI, które go zawierają, nie powinny odpowiadać na żadne żądania.

Wszystkie ciągi URL typu muszą być prawidłowe odwołania URI z dodatkowym ograniczeniem (w przypadku formatu tekstowego), że zawartość odwołania musi składać się tylko ze znaków alfanumerycznych, znaków ucieczki zakodowanych w procentach i znaków z tego zestawu (bez zewnętrznych apostrofów): /-.~_!$&()*+,;=. Mimo że zezwalamy na kodowanie procentowe, implementacje nie powinny go dekodować, aby uniknąć nieporozumień z istniejącymi analizatorami. Na przykład adres type.googleapis.com%2FFoo powinien zostać odrzucony.

W pierwotnym projekcie Any rozważano możliwość uruchomienia usługi rozpoznawania typów pod tymi adresami URL, ale Protobuf nigdy jej nie wdrożył i uważa kontaktowanie się z tymi adresami URL za problematyczne i potencjalnie niebezpieczne. Nie próbuj kontaktować się z adresami URL typu kontakt.
value

string (bytes format)

Zawiera serializację Protobuf typu opisanego przez type_url.

Ciąg znaków zakodowany w formacie Base64.

Poziom ufności

Poziom ufności rozwiązania.

Wartości w polu enum
CONFIDENCE_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
MEDIUM Średnia pewność oznacza, że rozwiązanie jest prawdopodobnie prawidłowe, ale mogą istnieć inne możliwości.
HIGH Wysoki poziom ufności oznacza, że rozdzielczość jest prawidłowa i odnosi się do konkretnego obiektu geoprzestrzennego (np. konkretnego miejsca).

Adnotacje do narzędzi

Adnotacje narzędzia są wysyłane do klientów MCP w celu opisania podstawowego ryzyka związanego z danym narzędziem. Większość klientów traktuje te wskazówki jako niezaufane, ale można ich używać do określania, kiedy użytkownikowi może zostać wysłany monit o potwierdzenie.

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

  • readOnlyHint: jeśli wartość jest prawdziwa, narzędzie nie modyfikuje środowiska. Wartość domyślna: fałsz.
  • destructiveHint: jeśli ma wartość Prawda, narzędzie może wykonywać działania destrukcyjne. Jeśli wartość to „false”, narzędzie może wykonywać tylko działania dodające. 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: fałsz.
  • openWorldHint: jeśli wartość to „true”, narzędzie może wchodzić w interakcje z „otwartym światem” podmiotów zewnętrznych. Jeśli wartość jest fałszywa, narzędzie może wchodzić w interakcje tylko z podmiotami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie byłoby narzędziem typu otwarty świat, a narzędzie do zapamiętywania nie.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌